Ian Campbell
2012-Mar-19 15:14 UTC
[PATCH] libxl: Document API and ABI compatibility guarantees
# HG changeset patch # User Ian Campbell <ian.campbell@citrix.com> # Date 1332169579 0 # Node ID f588c69fd12f17e81d3289653ae1e3b20cd41c11 # Parent e10c4b937e8fa9159070584113e9378ca175f728 libxl: Document API and ABI compatibility guarantees. Signed-off-by: Ian Campbell <ian.campbell@citrix.com> diff -r e10c4b937e8f -r f588c69fd12f tools/libxl/libxl.h --- a/tools/libxl/libxl.h Mon Mar 19 14:24:01 2012 +0000 +++ b/tools/libxl/libxl.h Mon Mar 19 15:06:19 2012 +0000 @@ -14,6 +14,77 @@ */ /* + * libxl API compatibility + * + * From Xen 4.2 onwards the API of libxl will be maintained in a + * stable manner. This means that it should be possible to write an + * application against the API provided by libxl in Xen 4.2 and expect + * that it will continue to compile against future versions of Xen + * without source modification. + * + * In order to make such compatibility possible it is required that + * application which want to be exposed to a particular API #define + * LIBXL_API_VERSION before including libxl.h or any other libxl + * header. The syntax of the LIBXL_API_VERSION is: + * 0xVVSSEE + * where ($(XEN_xxx) from xen/Makefile): + * VV is the Xen major release number, $(XEN_VERSION) + * SS is the Xen sub version number, $(XEN_SUBVERSION) + * EE is the Xen extra version digit, first numeric part of + * $(XEN_EXTRAVERSION) not including the leading "." + * For example the first stable API version, supported by Xen 4.2.0, + * is 0x040200. + * + * Lack of LIBXL_API_VERSION means "the latest" which will + * change. Specifying an unknown LIBXL_API_VERSION will result in a + * compile time error. + * + * Identical versions of the libxl API will represented by the version + * containing the earliest instance of that API. e.g. if 4.2.0 and + * 4.3.0 contain an identical libxl API then only LIBXL_API_VERSION + * 0x040200 will be valid. + * + * We will try especially hard to avoid changing the API during a + * stable series, i.e. it should be unusual for the last byte of + * LIBXL_API_VERSION to be non-zero. + * + * In the event that a change is required which cannot be made + * backwards compatible in this manner a #define of the form + * LIBXL_HAVE_<interface> will always be added in order to make it + * possible to write applciations which build against any version of + * libxl. Such changes are expected to be exceptional and used as a + * last resort. The barrier for backporting such a change to a stable + * branch will be very high. + * + * These guarantees apply only to stable releases of Xen. When an + * incompatible change is made in the unstable tree then + * LIBXL_API_VERSION will be bumped to the next expected stable + * release number on the first such change only. Applications which + * want to support building against Xen unstable are expected to track + * API changes in that tree until it is released as a stable release. + * + * API compatibility will be maintained for all versions of Xen using + * the same $(XEN_VERSION) (e.g. throughout a major release). + */ + +/* + * libxl ABI compatibility + * + * The only guarantee which libxl makes regarding ABI compatibility + * across releases is that the SONAME will always be bumped whenever + * the ABI is changed in an incompatible way. + * + * This applies within stable branches as well as + * development branches. It is possible that a new stable release of + * Xen may require a rebuild of applications using the + * library. However per the API compatibility gaurantees such a + * rebuild should not normally require any source level changes. + * + * As with the API compatiblity the SONAME will only be bumped for the + * first ABI incompatible change in a development branch. + */ + +/* * libxl memory management * * From the point of view of the application (ie, libxl''s caller), @@ -184,6 +255,13 @@ #include <libxl_uuid.h> #include <_libxl_list.h> +/* API compatibility. Only 0x040200 is supported at this time. */ +#ifdef LIBXL_API_VERSION +#if LIBXL_API_VERSION != 0x040200 +#error Unknown LIBXL_API_VERSION +#endif +#endif + typedef uint8_t libxl_mac[6]; #define LIBXL_MAC_FMT "%02hhx:%02hhx:%02hhx:%02hhx:%02hhx:%02hhx" #define LIBXL_MAC_FMTLEN ((2*6)+5) /* 6 hex bytes plus 5 colons */
Zhigang Wang
2012-Mar-19 18:20 UTC
Re: [PATCH] libxl: Document API and ABI compatibility guarantees
Any thought on Python/OCaml bindings for this? Thanks, Zhigang On 03/19/2012 11:14 AM, Ian Campbell wrote:> # HG changeset patch > # User Ian Campbell <ian.campbell@citrix.com> > # Date 1332169579 0 > # Node ID f588c69fd12f17e81d3289653ae1e3b20cd41c11 > # Parent e10c4b937e8fa9159070584113e9378ca175f728 > libxl: Document API and ABI compatibility guarantees. > > Signed-off-by: Ian Campbell <ian.campbell@citrix.com> > > diff -r e10c4b937e8f -r f588c69fd12f tools/libxl/libxl.h > --- a/tools/libxl/libxl.h Mon Mar 19 14:24:01 2012 +0000 > +++ b/tools/libxl/libxl.h Mon Mar 19 15:06:19 2012 +0000 > @@ -14,6 +14,77 @@ > */ > > /* > + * libxl API compatibility > + * > + * From Xen 4.2 onwards the API of libxl will be maintained in a > + * stable manner. This means that it should be possible to write an > + * application against the API provided by libxl in Xen 4.2 and expect > + * that it will continue to compile against future versions of Xen > + * without source modification. > + * > + * In order to make such compatibility possible it is required that > + * application which want to be exposed to a particular API #define > + * LIBXL_API_VERSION before including libxl.h or any other libxl > + * header. The syntax of the LIBXL_API_VERSION is: > + * 0xVVSSEE > + * where ($(XEN_xxx) from xen/Makefile): > + * VV is the Xen major release number, $(XEN_VERSION) > + * SS is the Xen sub version number, $(XEN_SUBVERSION) > + * EE is the Xen extra version digit, first numeric part of > + * $(XEN_EXTRAVERSION) not including the leading "." > + * For example the first stable API version, supported by Xen 4.2.0, > + * is 0x040200. > + * > + * Lack of LIBXL_API_VERSION means "the latest" which will > + * change. Specifying an unknown LIBXL_API_VERSION will result in a > + * compile time error. > + * > + * Identical versions of the libxl API will represented by the version > + * containing the earliest instance of that API. e.g. if 4.2.0 and > + * 4.3.0 contain an identical libxl API then only LIBXL_API_VERSION > + * 0x040200 will be valid. > + * > + * We will try especially hard to avoid changing the API during a > + * stable series, i.e. it should be unusual for the last byte of > + * LIBXL_API_VERSION to be non-zero. > + * > + * In the event that a change is required which cannot be made > + * backwards compatible in this manner a #define of the form > + * LIBXL_HAVE_<interface> will always be added in order to make it > + * possible to write applciations which build against any version of > + * libxl. Such changes are expected to be exceptional and used as a > + * last resort. The barrier for backporting such a change to a stable > + * branch will be very high. > + * > + * These guarantees apply only to stable releases of Xen. When an > + * incompatible change is made in the unstable tree then > + * LIBXL_API_VERSION will be bumped to the next expected stable > + * release number on the first such change only. Applications which > + * want to support building against Xen unstable are expected to track > + * API changes in that tree until it is released as a stable release. > + * > + * API compatibility will be maintained for all versions of Xen using > + * the same $(XEN_VERSION) (e.g. throughout a major release). > + */ > + > +/* > + * libxl ABI compatibility > + * > + * The only guarantee which libxl makes regarding ABI compatibility > + * across releases is that the SONAME will always be bumped whenever > + * the ABI is changed in an incompatible way. > + * > + * This applies within stable branches as well as > + * development branches. It is possible that a new stable release of > + * Xen may require a rebuild of applications using the > + * library. However per the API compatibility gaurantees such a > + * rebuild should not normally require any source level changes. > + * > + * As with the API compatiblity the SONAME will only be bumped for the > + * first ABI incompatible change in a development branch. > + */ > + > +/* > * libxl memory management > * > * From the point of view of the application (ie, libxl''s caller), > @@ -184,6 +255,13 @@ > #include <libxl_uuid.h> > #include <_libxl_list.h> > > +/* API compatibility. Only 0x040200 is supported at this time. */ > +#ifdef LIBXL_API_VERSION > +#if LIBXL_API_VERSION != 0x040200 > +#error Unknown LIBXL_API_VERSION > +#endif > +#endif > + > typedef uint8_t libxl_mac[6]; > #define LIBXL_MAC_FMT "%02hhx:%02hhx:%02hhx:%02hhx:%02hhx:%02hhx" > #define LIBXL_MAC_FMTLEN ((2*6)+5) /* 6 hex bytes plus 5 colons */
Ian Jackson
2012-Apr-03 14:32 UTC
Re: [PATCH] libxl: Document API and ABI compatibility guarantees
Ian Campbell writes ("[Xen-devel] [PATCH] libxl: Document API and ABI
compatibility guarantees"):> libxl: Document API and ABI compatibility guarantees.
>
> Signed-off-by: Ian Campbell <ian.campbell@citrix.com>
Committed-by: Ian Jackson <ian.jackson@eu.citrix.com>