idl/objmgr.idl

   1 /* The Object Manager
   2  *
   3  * This is the kernel interface through which objects, interfaces, and
   4  * interfaces are opened, created and destroyed.  The instantiated objmgr
   5  * object is always id 1.
   6  */
   7
   8 interface Object {
   9         guid: "C227980E-EA8B-11D9-84F1-000A95BB581A";
  10 };
  11
  12 struct VStruct virtual {
  13         guid: "E2E3AF5F-2858-11DA-9FBB-00112431A05E";
  14 };
  15
  16 namespace Objects {
  17         // FIXME: make this a built-in ID type that fixes things
  18         // up when moving between systems.  It can be native word
  19         // sized, rather than always long.
  20
  21         typedef ulong ID;
  22
  23         struct TypeDesc {
  24                 enum BasicType {
  25                         Bool, Short, Int, Long,
  26                         UShort, UInt, ULong,
  27                         FShort, FLong, Octet, Enum,
  28                         Bitfield, Interface, Struct
  29                 } type;
  30
  31                 ID id;            // ID of interface, struct, bitfield, or enum (or 0).
  32                 ulong length;     // Type length: bits in bitfield, bytes in
  33                                   //              struct, max value of enum, or 0.
  34
  35                 struct Array {
  36                         // Inclusive lower and upper bounds of the array.  If the
  37                         // array has no upper bound, upper should be -1.  If the
  38                         // array has no lower bound, lower should be 0.  If this is
  39                         // not an array, both should be 0.
  40
  41                         long lower, upper;
  42                 } array;
  43         };
  44
  45         struct ParamDesc {
  46                 TypeDesc type;
  47
  48                 enum Dir {
  49                         In, Out, InOut
  50                 } dir;
  51
  52                 bitfield Attr:32 {
  53                         copy:1,   /* If input argument references memory, a
  54                                      copy will be made (possibly via copy-on-write)
  55                                      before the method receives control.
  56                                      If the parameter is inout, the changes (if any)
  57                                      will be copied to the original memory area (or
  58                                      the copy-on-write mapping will occur on return
  59                                      from the method).  This is an implementation
  60                                      attribute and is incompatible with shared. */
  61
  62                         shared:1, /* If input argument references memory, the
  63                                      method may continue to access the memory
  64                                      until it explicitly releases it.  The memory
  65                                      region must remain valid until then, and all
  66                                      changes to the memory area will be shared by
  67                                      both the caller and the callee.  This is an
  68                                      interface attribute and is incompatible with
  69                                      copy.  The argument should be page aligned
  70                                      and its size must be a multiple of the page
  71                                      size; otherwise, the caller will have
  72                                      access to data outside the region passed. */
  73                 } attr;
  74         };
  75
  76         struct MethodDesc {
  77                 char[] name;
  78                 ulong entry;      /* Address of method entry point */
  79                 ParamDesc[] params;
  80
  81                 bitfield Flags:32 {
  82                         async:1,       /* Method is invoked indirectly via message passing,
  83                                           and the caller does not wait for completion.  No
  84                                           out parameters may be used in such a method. */
  85
  86                         ordered:1,     /* Method requires strong ordering; all ordered methods
  87                                           from the same thread will be delivered in order, and
  88                                           the next such method will not be delivered until
  89                                           the recipient of the previous invocation message
  90                                           acknowledges it.  This flag is only valid on async
  91                                           methods, as synchronous methods are inherently
  92                                           ordered.
  93
  94                                           An alternative is to invoke methods through
  95                                           a serialization object, which allows finer
  96                                           control over the level of serialization.
  97                                           This flag may go away in favor of always
  98                                           using explicit serialization objects when
  99                                           needed. */
 100                 } flags;
 101         };
 102
 103         struct ClassDesc {
 104                 ulong[] super;          /* superinterface(es) */
 105                 MethodDesc[] methods;
 106                 ulong instantiate, subinterface, remove;        /* access tokens */
 107         };
 108
 109         struct DatumDesc {
 110                 char[] name;
 111                 TypeDesc type;
 112         };
 113
 114         struct StructDesc {
 115                 DatumDesc[] data;
 116         };
 117
 118         interface IDSpace {
 119                 guid: "06489629-9C25-4C14-9A5B-6C59639C87D6";
 120
 121                 new_object(Mem.AddrSpace aspace, ulong entry, ID obj out);
 122
 123                 // Release "num" references on the object.  If exactly "num"
 124                 // references remain, the object handle is closed and "gone" is
 125                 // true.  If more references remain, the handle is not closed and
 126                 // "gone" is false.  If fewer references than "num" are present
 127                 // when called, no references are released, and RefCountException
 128                 // is thrown.
 129                 //
 130                 // A handle's refcount is incremented whenever a reference is
 131                 // received via IPC.  Objects created with new_object start with
 132                 // a refcount of 1.
 133
 134                 release(ID obj, int num, bool gone out);
 135         };
 136
 137         // This is a generic Factory interface; specific factories may
 138         // (but do not need to) implement a more specific interface that
 139         // guarantees that the generated object will comply with some
 140         // particular interface.
 141
 142         interface Factory {
 143                 guid: "9C084DD0-5D69-11DA-BD5A-000A95BB581A";
 144                 create(Object obj out);
 145         };
 146 }