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 Class {
 119                 guid: "C30D0A85-EA8B-11D9-B985-000A95BB581A";
 120                 query_interface(Interface iface, bool supported out);
 121                 instantiate(Object instance out);
 122         };
 123
 124         interface Interface {
 125                 guid: "C36EBE18-EA8B-11D9-896D-000A95BB581A";
 126         };
 127
 128         interface Method {
 129                 guid: "C3D1BA69-EA8B-11D9-9439-000A95BB581A";
 130         };
 131
 132         interface Struct {
 133                 guid: "C4384909-EA8B-11D9-B856-000A95BB581A";
 134         };
 135
 136         interface Filter {
 137                 guid: "C4A89048-EA8B-11D9-BB2C-000A95BB581A";
 138
 139                 // Returns the object from which the filter was created.
 140                 // This will only succeed if the calling process already
 141                 // has a reference to the real object.  If the filter
 142                 // points to another filter, it will return the transitive
 143                 // real object if possible, or else the filter closest to
 144                 // the real object for which the process already has a
 145                 // reference.  If neither the real object nor a closer
 146                 // filter can be returned, this filter itself is returned.
 147                 // This should not be used for comparing filter references,
 148                 // as separately created filters for the same object will
 149                 // have different IDs and pointers, even if they contain
 150                 // the same subset of interfaces.
 151
 152                 get_real_obj(Object obj out);
 153
 154                 // Returns a local ID of the real object, regardless of whether
 155                 // the calling process has a reference to it, or whether there
 156                 // are other intervening filters.  The ID cannot be used to
 157                 // invoke methods, but it can be used to compare the identities
 158                 // of the objects behind different filter objects.  If a real
 159                 // reference to the object is later obtained, it will have
 160                 // the same local ID.
 161
 162                 get_real_obj_id(ID id out);
 163         };
 164
 165         interface ObjectManager {
 166                 guid: "C28596AB-EA8B-11D9-8DEB-000A95BB581A";
 167
 168                 new_object(ID cla, ID obj out);
 169                 delete_object(ID obj) async;
 170
 171                 new_interface(ID cd, ID cla out);
 172                 delete_interface(ID cla, bool call_del) async;
 173
 174                 open_object(ID obj, uint handle out);
 175                 close_object(uint handle) async;
 176
 177                 // Create a filter object that implements only some of the
 178                 // interfaces implemented by "obj".  This is useful to create a
 179                 // more limited reference to pass to less trusted processes.  If
 180                 // "exclude" is true, then all interfaces but those specified will
 181                 // be included.  Otherwise, only those interfaces specified will be
 182                 // included.  A filter with no interfaces may be created to act as
 183                 // a (mostly) opaque handle.
 184                 //
 185                 // A holder of a filter reference can convert it into the real
 186                 // object if it already has (or later obtains) a reference to to
 187                 // the real object.  It can also compare the identities of
 188                 // separately created filters pointing at the same object
 189                 // regardless of what it has a real reference to.  Thus, filters
 190                 // should be used only to limit access granted by passing a
 191                 // reference to another process; it should not be used to hide the
 192                 // identity of the real object.
 193
 194                 create_filter(Object obj, bool exclude, Interface[] ifaces,
 195                               Filter filter out);
 196         };
 197
 198         // This is a generic Factory interface; specific factories may
 199         // (but do not need to) implement a more specific interface that
 200         // guarantees that the generated object will comply with some
 201         // particular interface.
 202
 203         interface Factory {
 204                 guid: "9C084DD0-5D69-11DA-BD5A-000A95BB581A";
 205                 create(Object obj out);
 206         };
 207 }