Re: [Xen-API] [PATCH] libxl: Document API and ABI compatibility guarantees

[Zhigang Wang <zhigang.x.wang@xxxxxxxxxx>]

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@xxxxxxxxxx>
> # Date 1332169579 0
> # Node ID f588c69fd12f17e81d3289653ae1e3b20cd41c11
> # Parent  e10c4b937e8fa9159070584113e9378ca175f728
> libxl: Document API and ABI compatibility guarantees.
>
> Signed-off-by: Ian Campbell <ian.campbell@xxxxxxxxxx>
>
> 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 */


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