osfmk/mach/mig.h

   1 /*
   2  * Copyright (c) 2000-2005 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * The contents of this file constitute Original Code as defined in and
   7  * are subject to the Apple Public Source License Version 1.1 (the
   8  * "License").  You may not use this file except in compliance with the
   9  * License.  Please obtain a copy of the License at
  10  * http://www.apple.com/publicsource and read it before using this file.
  11  *
  12  * This Original Code and all software distributed under the License are
  13  * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  14  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  15  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  16  * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the
  17  * License for the specific language governing rights and limitations
  18  * under the License.
  19  *
  20  * @APPLE_LICENSE_HEADER_END@
  21  */
  22 /*
  23  * @OSF_COPYRIGHT@
  24  */
  25
  26 /*
  27  * Mach MIG Subsystem Interfaces
  28  */
  29
  30 #ifndef _MACH_MIG_H_
  31 #define _MACH_MIG_H_
  32
  33 #include <stdint.h>
  34 #include <mach/port.h>
  35 #include <mach/message.h>
  36 #include <mach/vm_types.h>
  37
  38 #include <sys/cdefs.h>
  39
  40 #if defined(MACH_KERNEL)
  41
  42 /* Turn MIG type checking on by default for kernel */
  43 #define __MigTypeCheck 1
  44 #define __MigKernelSpecificCode 1
  45 #define _MIG_KERNEL_SPECIFIC_CODE_ 1
  46
  47 /* Otherwise check legacy setting (temporary) */
  48 #elif defined(TypeCheck)
  49
  50 #define __MigTypeCheck TypeCheck
  51
  52 #endif /* defined(TypeCheck) */
  53
  54 /*
  55  * Pack MIG message structs.
  56  * This is an indicator of the need to view shared structs in a
  57  * binary-compatible format - and MIG message structs are no different.
  58  */
  59 #define __MigPackStructs 1
  60
  61 /*
  62  * Definition for MIG-generated server stub routines.  These routines
  63  * unpack the request message, call the server procedure, and pack the
  64  * reply message.
  65  */
  66 typedef void    (*mig_stub_routine_t) (mach_msg_header_t *InHeadP,
  67                                        mach_msg_header_t *OutHeadP);
  68
  69 typedef mig_stub_routine_t mig_routine_t;
  70
  71 /*
  72  * Definition for MIG-generated server routine.  This routine takes a
  73  * message, and returns the appropriate stub function for handling that
  74  * message.
  75  */
  76 typedef mig_routine_t (*mig_server_routine_t) (mach_msg_header_t *InHeadP);
  77
  78 /*
  79  * Generic definition for implementation routines.  These routines do
  80  * the real work associated with this request.  This generic type is
  81  * used for keeping the pointers in the subsystem array.
  82  */
  83 typedef kern_return_t   (*mig_impl_routine_t)(void);
  84
  85 typedef mach_msg_type_descriptor_t routine_arg_descriptor;
  86 typedef mach_msg_type_descriptor_t *routine_arg_descriptor_t;
  87 typedef mach_msg_type_descriptor_t *mig_routine_arg_descriptor_t;
  88
  89 #define MIG_ROUTINE_ARG_DESCRIPTOR_NULL ((mig_routine_arg_descriptor_t)0)
  90
  91 struct routine_descriptor {
  92         mig_impl_routine_t      impl_routine;   /* Server work func pointer   */
  93         mig_stub_routine_t      stub_routine;   /* Unmarshalling func pointer */
  94         unsigned int            argc;                   /* Number of argument words   */
  95         unsigned int            descr_count;    /* Number complex descriptors */
  96         routine_arg_descriptor_t
  97                                                 arg_descr;              /* pointer to descriptor array*/
  98         unsigned int            max_reply_msg;  /* Max size for reply msg     */
  99 };
 100 typedef struct routine_descriptor *routine_descriptor_t;
 101
 102 typedef struct routine_descriptor mig_routine_descriptor;
 103 typedef mig_routine_descriptor *mig_routine_descriptor_t;
 104
 105 #define MIG_ROUTINE_DESCRIPTOR_NULL ((mig_routine_descriptor_t)0)
 106
 107 typedef struct mig_subsystem {
 108         mig_server_routine_t server;            /* pointer to demux routine     */
 109         mach_msg_id_t            start;                 /* Min routine number       */
 110         mach_msg_id_t            end;                   /* Max routine number + 1   */
 111         mach_msg_size_t          maxsize;               /* Max reply message size   */
 112         vm_address_t             reserved;              /* reserved for MIG use     */
 113         mig_routine_descriptor
 114                                                  routine[1];    /* Routine descriptor array */
 115 } *mig_subsystem_t;
 116
 117 #define MIG_SUBSYSTEM_NULL              ((mig_subsystem_t)0)
 118
 119 typedef struct mig_symtab {
 120         char                            *ms_routine_name;
 121         int                                     ms_routine_number;
 122         void                            (*ms_routine)(void);    /* Since the functions in the
 123                                                                                                  * symbol table have unknown
 124                                                                                                  * signatures, this is the best
 125                                                                                                  * we can do...
 126                                                                                                  */
 127 } mig_symtab_t;
 128
 129 #ifdef  PRIVATE
 130
 131 /* MIG object runtime - not ready for public consumption */
 132
 133 #ifdef  KERNEL_PRIVATE
 134
 135 /*
 136  * MIG object runtime definitions
 137  *
 138  * Conforming MIG subsystems may enable this support to get
 139  * significant assistance from the base mig_object_t implementation.
 140  *
 141  * Support includes:
 142  *      - Transparency from port manipulation.
 143  *      - Dymanic port allocation on first "remoting" of an object.
 144  *      - Reference conversions from object to port and vice versa.
 145  *      - Automatic port deallocation on no-more-senders.
 146  *      - Support for multiple server implementations in a single space.
 147  *      - Messaging bypass for local servers.
 148  *      - Automatic hookup to base dispatch mechanism.
 149  *      - General notification support
 150  * Coming soon:
 151  *      - User-level support
 152  */
 153 typedef unsigned int                    mig_notify_type_t;
 154
 155 typedef struct MIGIID {
 156         unsigned long                           data1;
 157         unsigned short                          data2;
 158         unsigned short                          data3;
 159         unsigned char                           data4[8];
 160 } MIGIID;
 161
 162 typedef struct IMIGObjectVtbl                   IMIGObjectVtbl;
 163 typedef struct IMIGNotifyObjectVtbl             IMIGNotifyObjectVtbl;
 164
 165 typedef struct IMIGObject {
 166         const IMIGObjectVtbl                    *pVtbl;
 167 } IMIGObject;
 168
 169 typedef struct IMIGNotifyObject {
 170         const IMIGNotifyObjectVtbl              *pVtbl;
 171 } IMIGNotifyObject;
 172
 173 struct IMIGObjectVtbl {
 174         kern_return_t (*QueryInterface)(
 175                         IMIGObject              *object,
 176                         const MIGIID            *iid,
 177                         void                    **ppv);
 178
 179         unsigned long (*AddRef)(
 180                         IMIGObject              *object);
 181
 182         unsigned long (*Release)(
 183                         IMIGObject              *object);
 184
 185         unsigned long (*GetServer)(
 186                         IMIGObject              *object,
 187                         mig_server_routine_t    *server);
 188
 189         boolean_t (*RaiseNotification)(
 190                         IMIGObject              *object,
 191                         mig_notify_type_t       notify_type);
 192
 193         boolean_t (*RequestNotification)(
 194                         IMIGObject              *object,
 195                         IMIGNotifyObject        *notify,
 196                         mig_notify_type_t       notify_type);
 197 };
 198
 199 /*
 200  * IMIGNotifyObject
 201  *
 202  * A variant of the IMIGObject interface that is a sink for
 203  * MIG notifications.
 204  *
 205  * A reference is held on both the subject MIGObject and the target
 206  * MIGNotifyObject. Because of this, care must be exercised to avoid
 207  * reference cycles.  Once a notification is raised, the object
 208  * reference is returned and the request must be re-requested (if
 209  * desired).
 210  *
 211  * One interesting note:  because this interface is itself a MIG
 212  * object, one may request notification about state changes in
 213  * the MIGNotifyObject itself.
 214  */
 215 struct IMIGNotifyObjectVtbl {
 216         kern_return_t (*QueryInterface)(
 217                         IMIGNotifyObject        *notify,
 218                         const MIGIID            *iid,
 219                         void                    **ppv);
 220
 221         unsigned long (*AddRef)(
 222                         IMIGNotifyObject        *notify);
 223
 224         unsigned long (*Release)(
 225                         IMIGNotifyObject        *notify);
 226
 227         unsigned long (*GetServer)(
 228                         IMIGNotifyObject        *notify,
 229                         mig_server_routine_t    *server);
 230
 231         boolean_t (*RaiseNotification)(
 232                         IMIGNotifyObject        *notify,
 233                         mig_notify_type_t       notify_type);
 234
 235         boolean_t (*RequestNotification)(
 236                         IMIGNotifyObject        *notify,
 237                         IMIGNotifyObject        *notify_notify,
 238                         mig_notify_type_t       notify_type);
 239
 240         void (*HandleNotification)(
 241                         IMIGNotifyObject        *notify,
 242                         IMIGObject              *object,
 243                         mig_notify_type_t       notify_type);
 244 };
 245
 246 #endif  /* KERNEL_PRIVATE */
 247 #endif  /* PRIVATE */
 248
 249 __BEGIN_DECLS
 250
 251 /* Client side reply port allocate */
 252 extern mach_port_t mig_get_reply_port(void);
 253
 254 /* Client side reply port deallocate */
 255 extern void mig_dealloc_reply_port(mach_port_t reply_port);
 256
 257 /* Client side reply port "deallocation" */
 258 extern void mig_put_reply_port(mach_port_t reply_port);
 259
 260 /* Bounded string copy */
 261 extern int mig_strncpy(char     *dest, const char *src, int     len);
 262
 263 #ifdef KERNEL_PRIVATE
 264
 265 /* Allocate memory for out-of-stack mig structures */
 266 extern char *mig_user_allocate(vm_size_t size);
 267
 268 /* Deallocate memory used for out-of-stack mig structures */
 269 extern void mig_user_deallocate(char *data, vm_size_t size);
 270
 271 #else
 272
 273 /* Allocate memory for out-of-line mig structures */
 274 extern void mig_allocate(vm_address_t *, vm_size_t);
 275
 276 /* Deallocate memory used for out-of-line mig structures */
 277 extern void mig_deallocate(vm_address_t, vm_size_t);
 278
 279 #endif /* KERNEL_PRIVATE */
 280
 281 __END_DECLS
 282
 283 #endif  /* _MACH_MIG_H_ */