osfmk/mach/mig.h

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