view tools/libxl/idl.txt @ 22848:6341fe0f4e5a

Added tag 4.1.0-rc2 for changeset 9dca60d88c63
author Keir Fraser <>
date Tue Jan 25 14:06:55 2011 +0000 (2011-01-25)
parents 251694a87f1d
line source
1 libxltypes IDL
2 --------------
4 Each type in the libxl interface is represented by an object of type
5 libxltypes.Type (or a subclass thereof). Every local variable defined
6 by the .idl file must be an instance of libxltypes.Type (e.g. you may
7 not define Python functions or any other construct other than defining
8 variables)
10 The name of the type must be passed as the first argument to the
11 constructor when defining a new type. The name given should not
12 contain the initial namespace element (e.g. "libxl_"). See below for
13 how to specify a namespace.
15 The Type.typename contains the C name of the type _including_ the
16 namespace element while Type.rawname is always set to the 'base' name
17 of the type.
19 The libxltypes.Type base class has several other properties which
20 apply to all types. The properties are set by passing a named
21 parameter to the constructor.
23 Type.comment:
25 A free text comment which describes the type.
27 Type.namespace: (default: "libxl_")
29 The namespace in which the type resides. Usually this is "libxl_" but
30 system defined and builtin types may differ.
32 If the typename is not None then the namespace is prepended to the
33 type.
35 Type.passby: (default: libxltypes.PASS_BY_VALUE)
37 Defines the manner in which a type should be passed to C
38 functions. Valid values for this fields are:
39 libxltypes.PASS_BY_VALUE
40 libxltypes.PASS_BY_REFERENCE
42 Type.destructor_fn: (default: typename + "_destroy" or None if type == None)
44 The name of the C function which will free all dynamically allocated
45 memory contained within this type (but not the type itself).
47 Type.autogenerate_destructor: (default: True)
49 Indicates if the above named Type.destructor_fn should be
50 autogenerated.
52 Other simple type-Classes
53 -------------------------
55 libxltype.Builtin
57 Instances of this class represent types which are predefined within
58 the system.
60 libxltype.UInt
62 Instances of this class represent the standard uint<N>_t types.
64 The <N> for a given instance must be passed to the constructor and is
65 then available in UInt.width
67 libxltype.BitField
69 Instances of this class represent bitfield type classes.
71 The base type and desired width for a given instance must be passed
72 to the contructor. The base type becomes the type of the instance and
73 width is contained in BitField.width
75 libxltype.Reference
77 Instances of this type represent a reference to another type
79 The referant type must be passed to the constructor and is then
80 available in Reference.ref_type
82 Complex type-Classes
83 --------------------
85 libxltype.Aggregate
87 Base class for type-Classes which contain a number of other types
88 (e.g. structs and unions).
90 The contained types are available in the list Aggregate.fields. Each
91 element in the list is of type libxltype.Field representing a member
92 of the aggregate.
94 Each field has the following properties:
96 Field.type The type of the member (a libxltypes.Type).
97 The name of the member (can be None for anonymous
98 fields).
99 Field.const Boolean, true if the member is const.
100 Field.comment A free text comment which describes the member.
102 libxltype.Struct
104 A subclass of libxltype.Aggregate representing the C struct type.
106 Struct.kind == "struct"
108 libxltype.Union
110 A subclass of libxltype.Aggregate representing the C union type.
112 Union.kind == "union"
114 libxltype.KeyedUnion
116 A subclass of libxltype.Aggregate which represents the C union type
117 where the currently valid member of the union can be determined based
118 upon another member in the containing type.
120 The KeyedUnion.keyvar_name must contain the name of the member of the
121 containing type which determines the valid member of the union
123 The fields in a KeyedUnion have an extra Field.keyvar_expr
124 property. This must be a string containing a single "%s" format
125 specifier such that when "%s" is substited by an instance of
126 KeyedUnion.keyvar_name it becomes a C expression which evaluates to
127 True IFF this field currently contains valid data.
129 Standard Types
130 --------------
132 Several standard types a predefined. They are
134 void (void pointer type)
135 bool
136 size_t
137 integer (C int type)
138 unsigned_integer (C unsigned int type)
139 unsigned (C unsigned int type)
140 unsigned_long (C unsigned long type)
142 uint{8,16,32,64} uint{8,16,32,64}_t
144 domid Domain ID
146 string NULL terminated string
148 inaddr_ip struct in_addr