[Mesa-dev] [RFC] mapi: a generic dispatcher to be used by OpenVG (and OpenGL)

[Zack Rusin]

On Saturday 01 May 2010 15:27:45 Chia-I Wu wrote:
> Hi all,
> 
> I've been working on and off for a while on a dispatcher builder called
>  mapi (multiple-api, in contrary to gl-api).  The code is available at
> 
>   http://cgit.freedesktop.org/~olv/mesa/log/?h=mapi
> 
> The motivation is to build a dispatcher for OpenVG.  I will give an
>  overview for mapi in this mail, and see if it could be merged and how.
> 
> To create a dispatcher for an API with mapi, one needs to create a text
>  file that describes the function names, parameters, and return values of
>  the API. The text file is parsed by mapi_abi.py, a script provided by
>  mapi, to generate a header file.  A libglapi.a-like dispatcher can then be
>  created by compiling mapi with the generated header file.
> 
> Unlike libglapi.a, which must be used with a set of accompanying headers
>  such as glapidispatch.h and glapioffsets.h, the mapi derived dispatcher
>  has a simpler interface.  It consists of functions to create and fill an
>  opaque dispatch table, and to make a dispatch table current.  But that is
>  all for now.
> 
> Internally, mapi consists of
> 
>  - current dispatch/context management
>  - execmem allocation
>  - thread support
>  - public entry points (C or ASM)
>  - dynamic entry point generation
> 
> The first three are directly copied from glapi, slightly modified so that
>  they do not depend on core mesa headers.  The handling of C entry points
>  is just like how it is done in glapi.  The handling of ASM and dynamic
>  entry points points is different though.  In mapi, adding support for
>  arch-specific entry points is straightforward.  For example,
> 
>  
>  http://cgit.freedesktop.org/~olv/mesa/commit/?h=mapi&id=c2eb929ad643adba9d
> b01e02b06e489100f8c769
> 
> allows mapi to generate ASM and dynamic entry points on x86-64 with TLS. 
>  It is simple, and all changes live in a file of its own.  This example
>  uses inline assembly.  It is not a requirement.  But the build rule needs
>  to be adjusted if a .S file is to be used.
> 
> There are 8 commits in the branch.  The current state is
> 
>  - mapi works as discussed above
>  - other than generic C entry points, it can generate x86 and x86-64
>  assembly entry points
>  - there is an OpenVG dispatcher created with mapi
>  - glapi is modified to use the first three components of mapi (in fact,
>  they are copied from glapi)
>  - dispatchers now live under subdirectories of src/mapi/.
> 
> I'd like make glapi use all internal components of mapi.  Actually, there
>  is another branch that does that
> 
>   http://cgit.freedesktop.org/~olv/mesa/log/?h=mapi-replaces-glapi
> 
> As can been seen, not much is left in glapi.  The problem with the branch
>  is that mapi does not support as many architectures and toolchains as
>  glapi does with regard to ASM entry points.
> 
> My plan is to merge mapi branch first, likely after Kristian merges his
>  gles work.  It allows us to verify mapi and the new way to build glapi. 
>  Once mapi supports all interesting archs and toolchains (help needed!), we
>  can then merge mapi-replaces-glapi branch.
> 
> Any thought or comment?

It looks pretty good. 
Personally I'd prefer to see xml file with the same format we have in gl 
instead of a text file for entry points generation, but that's not a big issue. 

I'm just wondering what exactly are the advantages of using dispatch tables 
instead of straight forward api entries (as they are right now) for VG, could 
you elaborate on that?