libxl: autogenerate _libxl_types.h

The libxl interface types are represented by a simple python data
structure (which could be parsed from a bespoke language in the
future).

This will allow the autogeneration of functions to free the component
members of the libxl types. In the future it may also enable auto
generation of type marshalling code for language bindings.

The generated file should be identical to before with the exception of
the "DO NOT EDIT" header.

It was unfortunately necessary to add explcit an dependency on
_libxl_types.h (indirectly via libxl.h) to all C files since the
autogenerated dependencies are not available in time.

[PATCH 04 of 16 of
 libxl: autogenerate type definitions and destructor functions]

Signed-off-by: Ian Campbell <ian.campbell@citrix.com>
Signed-off-by: Ian Jackson <ian.jackson@eu.citrix.com>

1 files changed, 147 insertions, 0 deletions

diff --git a/tools/libxl/idl.txt b/tools/libxl/idl.txt
new file mode 100644
index 0000000000..9cb3f67ee7
--- /dev/null
+++ b/tools/libxl/idl.txt
@@ -0,0 +1,147 @@
+libxltypes IDL
+--------------
+
+Each type in the libxl interface is represented by an object of type
+libxltypes.Type (or a subclass thereof). Every local variable defined
+by the .idl file must be an instance of libxltypes.Type (e.g. you may
+not define Python functions or any other construct other than defining
+variables)
+
+The name of the type must be passed as the first argument to the
+constructor when defining a new type. The name given should not
+contain the initial namespace element (e.g. "libxl_"). See below for
+how to specify a namespace.
+
+The Type.typename contains the C name of the type _including_ the
+namespace element.
+
+The libxltypes.Type base class has several other properties which
+apply to all types. The properties are set by passing a named
+parameter to the constructor.
+
+Type.comment:
+
+  A free text comment which describes the type.
+
+Type.namespace: (default: "libxl_")
+
+ The namespace in which the type resides. Usually this is "libxl_" but
+ system defined and builtin types may differ.
+
+ If the typename is not None then the namespace is prepended to the
+ type.
+ 
+Type.passby: (default: libxltypes.PASS_BY_VALUE)
+
+ Defines the manner in which a type should be passed to C
+ functions. Valid values for this fields are:
+   libxltypes.PASS_BY_VALUE
+   libxltypes.PASS_BY_REFERENCE
+
+Type.destructor_fn: (default: typename + "_destroy" or None if type == None)
+
+ The name of the C function which will free all dynamically allocated
+ memory contained within this type (but not the type itself).
+
+Type.autogenerate_destructor: (default: True)
+
+ Indicates if the above named Type.destructor_fn should be
+ autogenerated.
+
+Other simple type-Classes
+-------------------------
+
+libxltype.Builtin
+
+ Instances of this class represent types which are predefined within
+ the system.
+
+libxltype.UInt
+
+ Instances of this class represent the standard uint<N>_t types.
+
+ The <N> for a given instance must be passed to the constructor and is
+ then available in UInt.width
+
+libxltype.BitField
+
+ Instances of this class represent bitfield type classes.
+
+ The base type and desired width for a given instance must be passed
+ to the contructor. The base type becomes the type of the instance and
+ width is contained in BitField.width
+
+libxltype.Reference
+
+ Instances of this type represent a reference to another type
+
+ The referant type must be passed to the constructor and is then
+ available in Reference.ref_type
+
+Complex type-Classes
+--------------------
+
+libxltype.Aggregate
+
+ Base class for type-Classes which contain a number of other types
+ (e.g. structs and unions).
+
+ The contained types are available in the list Aggregate.fields. Each
+ element in the list is of type libxltype.Field representing a member
+ of the aggregate.
+
+ Each field has the following properties:
+
+  Field.type	The type of the member (a libxltypes.Type).
+  Field.name    The name of the member (can be None for anonymous
+		fields).
+  Field.const	Boolean, true if the member is const.
+  Field.comment	A free text comment which describes the member.
+
+libxltype.Struct
+
+ A subclass of libxltype.Aggregate representing the C struct type.
+
+ Struct.kind == "struct"
+
+libxltype.Union
+
+ A subclass of libxltype.Aggregate representing the C union type.
+
+ Union.kind == "union"
+
+libxltype.KeyedUnion
+
+ A subclass of libxltype.Aggregate which represents the C union type
+ where the currently valid member of the union can be determined based
+ upon another member in the containing type.
+
+ The KeyedUnion.keyvar_name must contain the name of the member of the
+ containing type which determines the valid member of the union
+
+ The fields in a KeyedUnion have an extra Field.keyvar_expr
+ property. This must be a string containing a single "%s" format
+ specifier such that when "%s" is substited by an instance of
+ KeyedUnion.keyvar_name it becomes a C expression which evaluates to
+ True IFF this field currently contains valid data.
+
+Standard Types
+--------------
+
+Several standard types a predefined. They are
+
+void			(void pointer type)
+bool
+size_t
+integer			(C int type)
+unsigned_integer	(C unsigned int type) 
+unsigned		(C unsigned int type) 
+unsigned_long		(C unsigned long type)
+
+uint{8,16,32,64}	uint{8,16,32,64}_t
+
+domid			Domain ID
+
+string			NULL terminated string
+
+inaddr_ip		struct in_addr