osfmk/mach/mig.h

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