xen/tools/libxl/idl.txt

libxl IDL
---------

Each type in the libxl interface is represented by an object of type
idl.Type (or a subclass thereof). Every local variable defined by the
.idl file must be an instance of idl.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 while Type.rawname is always set to the 'base' name
of the type.

The idl.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.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: idl.PASS_BY_VALUE)

 Defines the manner in which a type should be passed to C
 functions. Valid values for this fields are:
   idl.PASS_BY_VALUE
   idl.PASS_BY_REFERENCE

Type.dispose_fn: (default: typename + "_dispose" 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_dispose_fn: (default: True)

 Indicates if the above named Type.dispose_fn should be
 autogenerated.

Type.init_val: (default: None)

 C expression for the value to initialise instances of this type to.

 If present takes precendence over init_fn (see below).

Type.init_fn: (default: typename + "_init" if dir in [IN, BOTH] and
                        type != None)

 The name of the C function which will initialist Type.

Type.autogenerate_init_fn: (default: True if dir in [IN, BOTH])

 Indicates if the above named Type.init_fn should be
 autogenerated.

Type.json_fn: (default: typename + "_gen_json" or None if type == None)

 The name of the C function which will generate a YAJL data structure
 representing this type.

Type.autogenerate_json: (default: True)

 Indicates if the above named Type.json_fn should be autogenerated.

Other simple type-Classes
-------------------------

idl.Builtin

 Instances of this class represent types which are predefined within
 the system.

idl.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

Complex type-Classes
--------------------

idl.Enumeration

  A class representing an enumeration (named integer values).

  The values are available in the list Enumeration.values. Each
  element in the list is of type idl.EnumerationValue.

  Each EnumerationValue has the following properties:

    EnumerationValue.enum       Reference to containing Enumeration
    EnumerationValue.name       The C name of this value, including
                                    the namespace and typename of the
                                    containing Enumeration (e.g.
                                    "LIBXL_FOOENUM_VALUE")
    EnumerationValue.rawname    The C name of this value, excluding
                                    the namespace but including the
                                    typename of the containing
                                    Enumeration (e.g. "FOOENUM_VALUE")
    EnumerationValue.valuename  The name of this value, excluding the
                                    name of the containing Enumeration
                                    and any namespace (e.g. "VALUE")
    EnumerationValue.value      The integer value associated with this name.

idl.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 idl.Field representing a member of the
 aggregate.

 Each field has the following properties:

  Field.type     The type of the member (a idl.Type).
  Field.name     The name of the member (can be None for anonymous
                 fields).
  Field.const    Boolean, true if the member is const.
  Field.init_val The initialisation value for this field. Takes
                 precendence over both Field.type.init_val and
                 Field.type.init_fn.

idl.Struct

 A subclass of idl.Aggregate representing the C struct type.

 Struct.kind == "struct"

idl.Union

 A subclass of idl.Aggregate representing the C union type.

 Union.kind == "union"

idl.KeyedUnion

 A subclass of idl.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. An idl.KeyedUnion must
 always be a member of a containing idl.Aggregate type.

 The KeyedUnion.keyvar contains an idl.Field, this is the member of
 the containing type which determines the valid member of the
 union. The idl.Field.type of the keyvar must be an Enumeration type.

idl.Array

  A class representing an array of similar elements. An idl.Array must
  always be an idl.Field of a containing idl.Aggregate.

  idl.Array.elem_type contains an idl.Type which is the type of each
  element of the array.

  idl.Array.len_var contains an idl.Field which is added to the parent
  idl.Aggregate and will contain the length of the array. The field
  MUST be named num_ARRAYNAME.

Standard Types
--------------

Several standard types a predefined. They are

void                    (void pointer type)
bool
size_t
integer                 24 bit signed integer.

uint{8,16,32,64}        uint{8,16,32,64}_t

domid                   Domain ID

string                  NULL terminated string