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 if we have Power alignment of 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 #if __DARWIN_ALIGN_POWER
  60 #define __MigPackStructs 1
  61 #endif
  62
  63 /*
  64  * Definition for MIG-generated server stub routines.  These routines
  65  * unpack the request message, call the server procedure, and pack the
  66  * reply message.
  67  */
  68 typedef void    (*mig_stub_routine_t) (mach_msg_header_t *InHeadP,
  69                                        mach_msg_header_t *OutHeadP);
  70
  71 typedef mig_stub_routine_t mig_routine_t;
  72
  73 /*
  74  * Definition for MIG-generated server routine.  This routine takes a
  75  * message, and returns the appropriate stub function for handling that
  76  * message.
  77  */
  78 typedef mig_routine_t (*mig_server_routine_t) (mach_msg_header_t *InHeadP);
  79
  80 /*
  81  * Generic definition for implementation routines.  These routines do
  82  * the real work associated with this request.  This generic type is
  83  * used for keeping the pointers in the subsystem array.
  84  */
  85 typedef kern_return_t   (*mig_impl_routine_t)(void);
  86
  87 typedef mach_msg_type_descriptor_t routine_arg_descriptor;
  88 typedef mach_msg_type_descriptor_t *routine_arg_descriptor_t;
  89 typedef mach_msg_type_descriptor_t *mig_routine_arg_descriptor_t;
  90
  91 #define MIG_ROUTINE_ARG_DESCRIPTOR_NULL ((mig_routine_arg_descriptor_t)0)
  92
  93 struct routine_descriptor {
  94         mig_impl_routine_t      impl_routine;   /* Server work func pointer   */
  95         mig_stub_routine_t      stub_routine;   /* Unmarshalling func pointer */
  96         unsigned int            argc;                   /* Number of argument words   */
  97         unsigned int            descr_count;    /* Number complex descriptors */
  98         routine_arg_descriptor_t
  99                                                 arg_descr;              /* pointer to descriptor array*/
 100         unsigned int            max_reply_msg;  /* Max size for reply msg     */
 101 };
 102 typedef struct routine_descriptor *routine_descriptor_t;
 103
 104 typedef struct routine_descriptor mig_routine_descriptor;
 105 typedef mig_routine_descriptor *mig_routine_descriptor_t;
 106
 107 #define MIG_ROUTINE_DESCRIPTOR_NULL ((mig_routine_descriptor_t)0)
 108
 109 typedef struct mig_subsystem {
 110         mig_server_routine_t server;            /* pointer to demux routine     */
 111         mach_msg_id_t            start;                 /* Min routine number       */
 112         mach_msg_id_t            end;                   /* Max routine number + 1   */
 113         mach_msg_size_t          maxsize;               /* Max reply message size   */
 114         vm_address_t             reserved;              /* reserved for MIG use     */
 115         mig_routine_descriptor
 116                                                  routine[1];    /* Routine descriptor array */
 117 } *mig_subsystem_t;
 118
 119 #define MIG_SUBSYSTEM_NULL              ((mig_subsystem_t)0)
 120
 121 typedef struct mig_symtab {
 122         char                            *ms_routine_name;
 123         int                                     ms_routine_number;
 124         void                            (*ms_routine)(void);    /* Since the functions in the
 125                                                                                                  * symbol table have unknown
 126                                                                                                  * signatures, this is the best
 127                                                                                                  * we can do...
 128                                                                                                  */
 129 } mig_symtab_t;
 130
 131 #ifdef  PRIVATE
 132
 133 /* MIG object runtime - not ready for public consumption */
 134
 135 #ifdef  KERNEL_PRIVATE
 136
 137 /*
 138  * MIG object runtime definitions
 139  *
 140  * Conforming MIG subsystems may enable this support to get
 141  * significant assistance from the base mig_object_t implementation.
 142  *
 143  * Support includes:
 144  *      - Transparency from port manipulation.
 145  *      - Dymanic port allocation on first "remoting" of an object.
 146  *      - Reference conversions from object to port and vice versa.
 147  *      - Automatic port deallocation on no-more-senders.
 148  *      - Support for multiple server implementations in a single space.
 149  *      - Messaging bypass for local servers.
 150  *      - Automatic hookup to base dispatch mechanism.
 151  *      - General notification support
 152  * Coming soon:
 153  *      - User-level support
 154  */
 155 typedef unsigned int                    mig_notify_type_t;
 156
 157 typedef struct MIGIID {
 158         unsigned long                           data1;
 159         unsigned short                          data2;
 160         unsigned short                          data3;
 161         unsigned char                           data4[8];
 162 } MIGIID;
 163
 164 typedef struct IMIGObjectVtbl                   IMIGObjectVtbl;
 165 typedef struct IMIGNotifyObjectVtbl             IMIGNotifyObjectVtbl;
 166
 167 typedef struct IMIGObject {
 168         const IMIGObjectVtbl                    *pVtbl;
 169 } IMIGObject;
 170
 171 typedef struct IMIGNotifyObject {
 172         const IMIGNotifyObjectVtbl              *pVtbl;
 173 } IMIGNotifyObject;
 174
 175 struct IMIGObjectVtbl {
 176         kern_return_t (*QueryInterface)(
 177                         IMIGObject              *object,
 178                         const MIGIID            *iid,
 179                         void                    **ppv);
 180
 181         unsigned long (*AddRef)(
 182                         IMIGObject              *object);
 183
 184         unsigned long (*Release)(
 185                         IMIGObject              *object);
 186
 187         unsigned long (*GetServer)(
 188                         IMIGObject              *object,
 189                         mig_server_routine_t    *server);
 190
 191         boolean_t (*RaiseNotification)(
 192                         IMIGObject              *object,
 193                         mig_notify_type_t       notify_type);
 194
 195         boolean_t (*RequestNotification)(
 196                         IMIGObject              *object,
 197                         IMIGNotifyObject        *notify,
 198                         mig_notify_type_t       notify_type);
 199 };
 200
 201 /*
 202  * IMIGNotifyObject
 203  *
 204  * A variant of the IMIGObject interface that is a sink for
 205  * MIG notifications.
 206  *
 207  * A reference is held on both the subject MIGObject and the target
 208  * MIGNotifyObject. Because of this, care must be exercised to avoid
 209  * reference cycles.  Once a notification is raised, the object
 210  * reference is returned and the request must be re-requested (if
 211  * desired).
 212  *
 213  * One interesting note:  because this interface is itself a MIG
 214  * object, one may request notification about state changes in
 215  * the MIGNotifyObject itself.
 216  */
 217 struct IMIGNotifyObjectVtbl {
 218         kern_return_t (*QueryInterface)(
 219                         IMIGNotifyObject        *notify,
 220                         const MIGIID            *iid,
 221                         void                    **ppv);
 222
 223         unsigned long (*AddRef)(
 224                         IMIGNotifyObject        *notify);
 225
 226         unsigned long (*Release)(
 227                         IMIGNotifyObject        *notify);
 228
 229         unsigned long (*GetServer)(
 230                         IMIGNotifyObject        *notify,
 231                         mig_server_routine_t    *server);
 232
 233         boolean_t (*RaiseNotification)(
 234                         IMIGNotifyObject        *notify,
 235                         mig_notify_type_t       notify_type);
 236
 237         boolean_t (*RequestNotification)(
 238                         IMIGNotifyObject        *notify,
 239                         IMIGNotifyObject        *notify_notify,
 240                         mig_notify_type_t       notify_type);
 241
 242         void (*HandleNotification)(
 243                         IMIGNotifyObject        *notify,
 244                         IMIGObject              *object,
 245                         mig_notify_type_t       notify_type);
 246 };
 247
 248 #endif  /* KERNEL_PRIVATE */
 249 #endif  /* PRIVATE */
 250
 251 __BEGIN_DECLS
 252
 253 /* Client side reply port allocate */
 254 extern mach_port_t mig_get_reply_port(void);
 255
 256 /* Client side reply port deallocate */
 257 extern void mig_dealloc_reply_port(mach_port_t reply_port);
 258
 259 /* Client side reply port "deallocation" */
 260 extern void mig_put_reply_port(mach_port_t reply_port);
 261
 262 /* Bounded string copy */
 263 extern int mig_strncpy(char     *dest, const char *src, int     len);
 264
 265 #ifdef KERNEL_PRIVATE
 266
 267 /* Allocate memory for out-of-stack mig structures */
 268 extern char *mig_user_allocate(vm_size_t size);
 269
 270 /* Deallocate memory used for out-of-stack mig structures */
 271 extern void mig_user_deallocate(char *data, vm_size_t size);
 272
 273 #else
 274
 275 /* Allocate memory for out-of-line mig structures */
 276 extern void mig_allocate(vm_address_t *, vm_size_t);
 277
 278 /* Deallocate memory used for out-of-line mig structures */
 279 extern void mig_deallocate(vm_address_t, vm_size_t);
 280
 281 #endif /* KERNEL_PRIVATE */
 282
 283 __END_DECLS
 284
 285 #endif  /* _MACH_MIG_H_ */