[Xen-API] libxl stable API (Re: [Xen-devel] 4.2 TODO update)

[Ian Campbell <Ian.Campbell@xxxxxxxxxx>]

On Mon, 2012-03-12 at 12:11 +0000, Ian Campbell wrote:
> [...] 
> tools, blockers:
>       * libxl stable API -- we would like 4.2 to define a stable API
>         which downstream's can start to rely on not changing. Aspects of
>         this are:

So now would be a good time for potential users of libxl in 4.2 onwards
to do a quick sanity check of the interfaces such that any omissions can
be added to the 4.2 list.

Now is also a good time to decide on the policy and mechanisms which we
will use to make life easy for our downstreams (some of whom I have
CC'd).

The goal and default assumption should obviously be that a downstream
which builds against libxl from 4.2 will continue to build (and work!)
against future versions of libxl without source modification.

In order to help us achieve this we can define some interfaces /
mechanisms now which will make everyone's lives easier in the future. I
propose that downstreams who want to be exposed to a particular API
should be required to #define LIBXL_API_VERSION before including
libxl.h. This will allow libxl.h to introduce the necessary compat/shim
layer. e.g. if they want the 4.2.0 interface they must:
        #define LIBXL_API_VERSION 0x040200

Assuming that 4.3.0 eventually releases with an identical API then users
would be expected to continue to use 0x040200 (i.e. we wouldn't
explicitly duplicate up the #ifdef's for compatible releases) but if in
4.4.0 changes are required then users could either continue to use
0x040200 (and expect libxl.h to provide suitable impedance matching to
make that work) or switch to 0x040400 and make the necessary source
level changes. Lack of LIBXL_API_VERSION would be taken to mean "the
latest". Specifying an unknown LIBXL_API_VERSION would result in #error
(e.g. in the above example 0x040300 and 0x123456 would both be an
error).

We should try especially hard to avoid changing the API during a stable
series, i.e. it should be unusual for the last byte to be non-zero.

If there is broad agreement with this scheme I will write up a patch to
add it to some documentation / header somewhere.

Do we need to define a horizon for how far we are willing to support
this level of compatibility? A new major release seems like the obvious
watershed -- i.e. at Xen 5.0.0 we may decide to drop support for
LIBXL_API_VERSION 0x04xxxx and earlier (although we don't have to).

Much as I hate to admit it I expect there will eventually/inevitably be
changes which cannot be papered over with this scheme. In order to make
it possible for downstreams to support the use of a single code base
across such changes I suggest that we always add a #define
LIBXL_HAVE_foo_interface for any such change.

The assumption should be that the barrier for backporting to a stable
branch will be very high for any change of this type.

Lastly we also to decide what we want to do about ABI (as opposed to
API) compatibility. Obviously if we change the ABI then we should change
the SONAME, but is this something we want to commit to avoiding? i.e.
should it be possible to build a downstream against libxl.so.2.0 (the
current libxl soname) from 4.2 and expect that dropping in libxl.so.2.0
from 4.3 will Just Work against the new hypervisor interfaces? Or do we
expect that 4.3 will provide libxl.so.2.1 and that the same downstream
source can be built twice? (e.g. with the correct one selected via some
plugin mechanism). Obviously avoiding ABI changes is a lot harder and
I'm not sure if that is something we are able to commit to at this stage
(and I'm not sure how good we would be at it even if we did try and make
that commitment).

>               * add libxl_defbool and generally try and arrange that
>                 memset(foo,0,...) requests the defaults (Ian Campbell,
>                 DONE)
>               * Safe fork vs. fd handling hooks. This is an API
>                 addition, so maybe not required fro stable API, bit need
>                 to have for 4.2? (Ian J, patches posted)

Ian.


_______________________________________________
xen-api mailing list
xen-api@xxxxxxxxxxxxx
http://lists.xen.org/cgi-bin/mailman/listinfo/xen-api