mirror of
https://github.com/xen-project/xen.git
synced 2026-10-29 10:40:03 +01:00
Juergen Gross
41aea82de2
Carve out all libxenlight related sources and move them to tools/libs/light in order to use the generic library build environment. The closely related sources for libxl-save-helper and the libxl test environment are being moved, too. Signed-off-by: Juergen Gross <jgross@suse.com> Acked-by: Wei Liu <wl@xen.org>
215 lines
6.8 KiB
Plaintext
215 lines
6.8 KiB
Plaintext
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.copy_fn: (default: typename + "_copy" or None if type == None)
|
|
|
|
The name of the C function which will deep copy all fields within
|
|
this type.
|
|
|
|
Type.autogenerate_copy_fn: (default: True)
|
|
|
|
Indicates if the above named Type.copy_fn should be
|
|
autogenerated.
|
|
|
|
Type.autogenerate_copy_fn
|
|
|
|
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_gen_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.json_parse_fn: (default: typename + "_parse_json" or None if type == None)
|
|
|
|
The name of the C function which will parse a libxl JSON structure
|
|
representing this type to C type.
|
|
|
|
Type.autogenerate_json: (default: True)
|
|
|
|
Indicates if the above named Type.json_*_fn should be autogenerated.
|
|
|
|
Type.check_default_fn:
|
|
|
|
If it's set then calling this function shall return true if this type
|
|
has been set to default value (internal libxl implementation).
|
|
|
|
If this is not set, that means we can check the type against init_val
|
|
(if it has one) or zero to determine whether the value is default
|
|
value.
|
|
|
|
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).
|
|
This class has one property besides the ones defined for the Type
|
|
class:
|
|
|
|
Enumeration.value_namespace: (default: namespace)
|
|
|
|
The namespace in which the values of the Enumeration (see below) reside.
|
|
This prefix is prepended to the name of the value.
|
|
|
|
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
|