osfmk/mach/mig.h

   1 /*
   2  * Copyright (c) 2000 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 <mach/port.h>
  34 #include <mach/message.h>
  35 #include <mach/kern_return.h>
  36
  37 /*
  38  * Definition for MIG-generated server stub routines.  These routines
  39  * unpack the request message, call the server procedure, and pack the
  40  * reply message.
  41  */
  42 typedef void    (*mig_stub_routine_t) (mach_msg_header_t *InHeadP,
  43                                        mach_msg_header_t *OutHeadP);
  44
  45 typedef mig_stub_routine_t mig_routine_t;
  46
  47 /*
  48  * Definition for MIG-generated server routine.  This routine takes a
  49  * message, and returns the appropriate stub function for handling that
  50  * message.
  51  */
  52 typedef mig_routine_t (*mig_server_routine_t) (mach_msg_header_t *InHeadP);
  53
  54 /*
  55  * Generic definition for implementation routines.  These routines do
  56  * the real work associated with this request.  This generic type is
  57  * used for keeping the pointers in the subsystem array.
  58  */
  59 typedef kern_return_t   (*mig_impl_routine_t)(void);
  60
  61 typedef struct mig_routine_descriptor {
  62         mig_stub_routine_t       stub_routine;  /* Unmarshalling function   */
  63         mach_msg_size_t          max_reply_msg; /* Max size for this reply  */
  64 } mig_routine_descriptor;
  65 typedef mig_routine_descriptor  *mig_routine_descriptor_t;
  66
  67 typedef struct mig_subsystem {
  68         mig_server_routine_t     server;        /* server routine           */
  69         mach_msg_id_t            start;         /* Min routine number       */
  70         mach_msg_id_t            end;           /* Max routine number + 1   */
  71         mach_msg_size_t          max_reply;     /* Max reply message size   */
  72         mach_msg_size_t          max_request;   /* Max request msg size     */
  73         mig_routine_descriptor   routine[1];    /* Routine descriptor array */
  74 } *mig_subsystem_t;
  75
  76 #ifdef  KERNEL_PRIVATE
  77 /*
  78  * MIG object runtime definitions
  79  *
  80  * Conforming MIG subsystems may enable this support to get
  81  * significant assistance from the base mig_object_t implementation.
  82  *
  83  * Support includes:
  84  *      - Transparency from port manipulation.
  85  *      - Dymanic port allocation on first "remoting" of an object.
  86  *      - Reference conversions from object to port and vice versa.
  87  *      - Automatic port deallocation on no-more-senders.
  88  *      - Support for multiple server implementations in a single space.
  89  *      - Messaging bypass for local servers.
  90  *      - Automatic hookup to base dispatch mechanism.
  91  *      - General notification support
  92  * Coming soon:
  93  *      - User-level support
  94  */
  95 typedef unsigned int                            mig_notify_type_t;
  96
  97 typedef struct MIGIID {
  98         unsigned long                           data1;
  99         unsigned short                          data2;
 100         unsigned short                          data3;
 101         unsigned char                           data4[8];
 102 } MIGIID;
 103
 104 typedef struct IMIGObjectVtbl                   IMIGObjectVtbl;
 105 typedef struct IMIGNotifyObjectVtbl             IMIGNotifyObjectVtbl;
 106
 107 typedef struct IMIGObject {
 108         IMIGObjectVtbl                          *pVtbl;
 109 } IMIGObject;
 110
 111 typedef struct IMIGNotifyObject {
 112         IMIGNotifyObjectVtbl                    *pVtbl;
 113 } IMIGNotifyObject;
 114
 115 struct IMIGObjectVtbl {
 116         kern_return_t (*QueryInterface)(
 117                         IMIGObject              *object,
 118                         const MIGIID            *iid,
 119                         void                    **ppv);
 120
 121         unsigned long (*AddRef)(
 122                         IMIGObject              *object);
 123
 124         unsigned long (*Release)(
 125                         IMIGObject              *object);
 126
 127         unsigned long (*GetServer)(
 128                         IMIGObject              *object,
 129                         mig_server_routine_t    *server);
 130
 131         boolean_t (*RaiseNotification)(
 132                         IMIGObject              *object,
 133                         mig_notify_type_t       notify_type);
 134
 135         boolean_t (*RequestNotification)(
 136                         IMIGObject              *object,
 137                         IMIGNotifyObject        *notify,
 138                         mig_notify_type_t       notify_type);
 139 };
 140
 141 /*
 142  * IMIGNotifyObject
 143  *
 144  * A variant of the IMIGObject interface that is a sink for
 145  * MIG notifications.
 146  *
 147  * A reference is held on both the subject MIGObject and the target
 148  * MIGNotifyObject. Because of this, care must be exercised to avoid
 149  * reference cycles.  Once a notification is raised, the object
 150  * reference is returned and the request must be re-requested (if
 151  * desired).
 152  *
 153  * One interesting note:  because this interface is itself a MIG
 154  * object, one may request notification about state changes in
 155  * the MIGNotifyObject itself.
 156  */
 157 struct IMIGNotifyObjectVtbl {
 158         kern_return_t (*QueryInterface)(
 159                         IMIGNotifyObject        *notify,
 160                         const MIGIID            *iid,
 161                         void                    **ppv);
 162
 163         unsigned long (*AddRef)(
 164                         IMIGNotifyObject        *notify);
 165
 166         unsigned long (*Release)(
 167                         IMIGNotifyObject        *notify);
 168
 169         unsigned long (*GetServer)(
 170                         IMIGNotifyObject        *notify,
 171                         mig_server_routine_t    *server);
 172
 173         boolean_t (*RaiseNotification)(
 174                         IMIGNotifyObject        *notify,
 175                         mig_notify_type_t       notify_type);
 176
 177         boolean_t (*RequestNotification)(
 178                         IMIGNotifyObject        *notify,
 179                         IMIGNotifyObject        *notify_notify,
 180                         mig_notify_type_t       notify_type);
 181
 182         void (*HandleNotification)(
 183                         IMIGNotifyObject        *notify,
 184                         IMIGObject              *object,
 185                         mig_notify_type_t       notify_type);
 186 };
 187
 188 #endif /* KERNEL_PRIVATE */
 189
 190 #endif /* _MACH_MIG_H_ */