osfmk/mach/mig.h

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