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

[Chia-I Wu]

On Mon, May 3, 2010 at 12:24 AM, Zack Rusin <zackr at vmware.com> wrote:
> On Saturday 01 May 2010 15:27:45 Chia-I Wu wrote:
>> 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 could integrate that part when the way code/header generation is unified.
One thing I would also like to do is to make the files to be generated on the
fly instead of pre-generated.
> 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?
The dispatch table is installed only when there is a current context.  A minor
advantage is that vg_current_context() is guaranteed to never return NULL when
the real functions are called.

But more importantly, libEGL.so is used to bootstrap libOpenVG.so right now.
That is, libEGL.so creates pipe_screens and pipe_textures of a window for
libOpenVG.so.  This imposes a hard requirement that libEGL.so and libOpenVG.so
must be built from the same release as Gallium does not have a stable
interface.

Using a dispatcher allows one to create a dispatch-only libOpenVG.so.  st/egl
and st/vega can live together elsewhere to solve the ABI issue.  This is kind
of like the case with DRI drivers where each driver owns a copy of libmesa.a
instead of sharing it to avoid ABI incompatibility.

-- 
olv at LunarG.com