home *** CD-ROM | disk | FTP | other *** search
/ H4CK3R 4 / hacker04 / 04_HACK04.ISO / darwin / darwinx86.iso / usr / include / mach / rpc.h < prev    next >
Encoding:
C/C++ Source or Header  |  2001-09-30  |  14.4 KB  |  425 lines
  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 RPC Subsystem Interfaces
  28.  */
  29.  
  30. #ifndef    _MACH_RPC_H_
  31. #define _MACH_RPC_H_
  32.  
  33. #include <mach/boolean.h>
  34. #include <mach/kern_return.h>
  35. #include <mach/port.h>
  36. #include <mach/vm_types.h>
  37.  
  38. #include <mach/mig.h>
  39. #include <mach/mig_errors.h>
  40. #include <mach/machine/rpc.h>
  41. #include <mach/thread_status.h>
  42.  
  43. #ifdef    MACH_KERNEL_PRIVATE
  44. #include <ipc/ipc_object.h>
  45. #endif    /* MACH_KERNEL_PRIVATE */
  46.  
  47. /*
  48.  * The various bits of the type field of the routine_arg_descriptor
  49.  */
  50.  
  51. /* The basic types */
  52.  
  53. #define TYPE_SHIFT                      0
  54. #define MACH_RPC_PORT            (1 << TYPE_SHIFT)
  55. #define MACH_RPC_ARRAY                  (1 << (TYPE_SHIFT + 1))
  56. #define MACH_RPC_VARIABLE               (1 << (TYPE_SHIFT + 2))
  57. #define LAST_TYPE_BIT                   (TYPE_SHIFT+3)
  58.  
  59. /* XXX Port arrays need not be variable arrays, as assumed below. Fixme. */
  60. #define MACH_RPC_ARRAY_FIX        (MACH_RPC_ARRAY)
  61. #define MACH_RPC_ARRAY_FIXED        (MACH_RPC_ARRAY)
  62. #define MACH_RPC_ARRAY_VAR        (MACH_RPC_ARRAY | MACH_RPC_VARIABLE)
  63. #define MACH_RPC_ARRAY_VARIABLE        (MACH_RPC_ARRAY | MACH_RPC_VARIABLE)
  64. #define MACH_RPC_PORT_ARRAY        (MACH_RPC_PORT  | MACH_RPC_ARRAY_VAR)
  65.  
  66. /* Argument direction bits */
  67.  
  68. #define DIRECT_SHIFT                LAST_TYPE_BIT
  69. #define DIRECTION_SHIFT                 LAST_TYPE_BIT
  70. #define MACH_RPC_IN            (1 << DIRECTION_SHIFT)
  71. #define MACH_RPC_OUT            (1 << (DIRECTION_SHIFT + 1))
  72. #define LAST_DIRECT_BIT             (DIRECTION_SHIFT + 2)
  73. #define LAST_DIRECTION_BIT              (DIRECTION_SHIFT + 2)
  74.  
  75. #define MACH_RPC_INOUT            (MACH_RPC_IN | MACH_RPC_OUT)
  76.  
  77. /* Persist and pointer bit */
  78.  
  79. #define POINTER_SHIFT                   LAST_DIRECTION_BIT
  80. #define MACH_RPC_POINTER                (1 << POINTER_SHIFT)
  81. #define LAST_POINTER_BIT                (POINTER_SHIFT + 1)
  82.  
  83. /* Port disposition bits */
  84.  
  85. #define NAME_SHIFT                        LAST_POINTER_BIT
  86. #define MACH_RPC_RECEIVE                (1 << NAME_SHIFT)
  87. #define MACH_RPC_SEND                   (2 << NAME_SHIFT)
  88. #define MACH_RPC_SEND_ONCE              (3 << NAME_SHIFT)
  89. #define LAST_NAME_BIT            (NAME_SHIFT + 2)
  90.  
  91. #define ACTION_SHIFT            LAST_NAME_BIT
  92. #define MACH_RPC_MOVE                   (1 << ACTION_SHIFT)
  93. #define MACH_RPC_COPY                   (2 << ACTION_SHIFT)
  94. #define MACH_RPC_MAKE                   (3 << ACTION_SHIFT)
  95. #define LAST_ACTION_BIT                 (ACTION_SHIFT + 2)
  96.  
  97. #define MACH_RPC_MOVE_RECEIVE        (MACH_RPC_MOVE | MACH_RPC_RECEIVE)
  98. #define MACH_RPC_MOVE_SEND        (MACH_RPC_MOVE | MACH_RPC_SEND)
  99. #define MACH_RPC_COPY_SEND        (MACH_RPC_COPY | MACH_RPC_SEND)
  100. #define MACH_RPC_MAKE_SEND        (MACH_RPC_MAKE | MACH_RPC_SEND)
  101. #define MACH_RPC_MOVE_SEND_ONCE        (MACH_RPC_MOVE | MACH_RPC_SEND_ONCE)
  102. #define MACH_RPC_MAKE_SEND_ONCE        (MACH_RPC_MAKE | MACH_RPC_SEND_ONCE)
  103.  
  104. /* Hint for virtual vs. physical copy */ 
  105.  
  106. #define OPTION_SHIFT                    LAST_ACTION_BIT
  107. #define MACH_RPC_PHYSICAL_COPY        (1 << OPTION_SHIFT)
  108. #define MACH_RPC_VIRTUAL_COPY        (1 << (OPTION_SHIFT + 1))
  109. #define LAST_OPTION_BIT                 (OPTION_SHIFT + 2)
  110.  
  111. /* Deallocate? */
  112.  
  113. #define DEALLOCATE_SHIFT                LAST_OPTION_BIT
  114. #define MACH_RPC_DEALLOCATE        (1 << DEALLOCATE_SHIFT)
  115. #define LAST_DEALLOCATE_BIT             (DEALLOCATE_SHIFT + 1)
  116.  
  117. /* Argument is already on the stack */
  118.  
  119. #define ONSTACK_SHIFT                   LAST_DEALLOCATE_BIT
  120. #define MACH_RPC_ONSTACK        (1 << ONSTACK_SHIFT)
  121. #define LAST_ONSTACK_BIT                (ONSTACK_SHIFT + 1)
  122.  
  123. /* Is variable array bounded? Derived from type and arg.size */
  124.  
  125. #define BOUND_SHIFT            LAST_ONSTACK_BIT
  126. #define MACH_RPC_BOUND            (1 << BOUND_SHIFT)
  127. #define MACH_RPC_UNBOUND        (0)
  128. #define BOUND                MACH_RPC_BOUND
  129. #define UNBND                MACH_RPC_UNBOUND
  130. #define LAST_BOUND_BIT            (BOUND_SHIFT + 1)
  131.  
  132. /*
  133.  * Basic mach rpc types.
  134.  */
  135. typedef unsigned int    routine_arg_type;
  136. typedef unsigned int    routine_arg_offset;
  137. typedef unsigned int    routine_arg_size;
  138.  
  139. /*
  140.  * Definitions for a signature's argument and routine descriptor's.
  141.  */
  142. struct routine_arg_descriptor {
  143.     routine_arg_type    type;       /* Port, Array, etc. */
  144.         routine_arg_size        size;      /* element size in bytes */
  145.         routine_arg_size        count;     /* number of elements */
  146.     routine_arg_offset    offset;       /* Offset in list of routine args */
  147. };
  148. typedef struct routine_arg_descriptor *routine_arg_descriptor_t;
  149.  
  150. struct routine_descriptor {
  151.     mig_impl_routine_t    impl_routine;    /* Server work func pointer   */
  152.     mig_stub_routine_t    stub_routine;    /* Unmarshalling func pointer */
  153.     unsigned int        argc;        /* Number of argument words   */
  154.     unsigned int        descr_count;    /* Number of complex argument */
  155.                             /* descriptors                */
  156.     struct routine_arg_descriptor *
  157.                 arg_descr;    /* Pointer to beginning of    */
  158.                         /* the arg_descr array        */
  159.     unsigned int        max_reply_msg;    /* Max size for reply msg     */
  160. };
  161. typedef struct routine_descriptor *routine_descriptor_t;
  162.  
  163. #define DESCR_SIZE(x) ((x)->descr_count * sizeof(struct routine_arg_descriptor))
  164.  
  165. struct rpc_signature {
  166.     struct routine_descriptor rd;
  167.     struct routine_arg_descriptor rad[1];
  168. };
  169.  
  170. #ifdef    MACH_KERNEL_PRIVATE
  171.  
  172. typedef struct rpc_signature *rpc_signature_t;
  173.  
  174. #endif
  175.  
  176. #define RPC_SIGBUF_SIZE 8
  177. /*
  178.  *    A subsystem describes a set of server routines that can be invoked by
  179.  *    mach_rpc() on the ports that are registered with the subsystem.  For
  180.  *    each routine, the routine number is given, along with the
  181.  *    address of the implementation function in the server and a
  182.  *    description of the arguments of the routine (it's "signature").
  183.  *
  184.  *    This structure definition is only a template for what is really a
  185.  *    variable-length structure (generated by MIG for each subsystem).
  186.  *    The actual structures do not always have one entry in the routine
  187.  *    array, and also have a varying number of entries in the arg_descr
  188.  *    array.  Each routine has an array of zero or more arg descriptors
  189.  *    one for each complex arg.  These arrays are all catenated together
  190.  *    to form the arg_descr field of the subsystem struct.  The
  191.  *    arg_descr field of each routine entry points to a unique sub-sequence
  192.  *    within this catenated array.  The goal is to keep everything
  193.  *    contiguous.
  194.  */
  195. struct rpc_subsystem {
  196.     struct subsystem *subsystem;    /* Reserved for system use */
  197.  
  198.     mach_msg_id_t    start;        /* Min routine number */
  199.     mach_msg_id_t    end;        /* Max routine number + 1 */
  200.     unsigned int    maxsize;    /* Max mach_msg size */
  201.     vm_address_t    base_addr;    /* Address of this struct in user */
  202.  
  203.     struct routine_descriptor    /* Array of routine descriptors */
  204.             routine[1       /* Actually, (start-end+1) */
  205.                  ];
  206.  
  207.     struct routine_arg_descriptor
  208.             arg_descriptor[1   /* Actually, the sum of the descr_ */
  209.                     ]; /* count fields for all routines   */
  210. };
  211. typedef struct rpc_subsystem  *rpc_subsystem_t;
  212.  
  213. #define RPC_SUBSYSTEM_NULL    ((rpc_subsystem_t) 0)
  214.  
  215. /* 
  216.  *     New RPC declarations
  217.  *
  218.  *    First pass at definitions and types for the new rpc service.
  219.  *    This is subject to revision.
  220.  */
  221.  
  222. /*
  223.  *    RPC macros
  224.  */
  225.  
  226. #define RPC_MASK(shift,last)                                            \
  227.         ( ((1 << ((last)-(shift)))-1) << (shift) )
  228.  
  229. #define RPC_FIELD(field,shift,last)                                     \
  230.         ( (field) & (((1 << ((last)-(shift)))-1) << (shift)) )
  231.  
  232. #define RPC_BOUND(dsc)                                                  \
  233.         (((RPC_FIELD((dsc).type,TYPE_SHIFT+1,TYPE_SHIFT+3) ==           \
  234.            MACH_RPC_ARRAY_VARIABLE) && (dsc).count != 0) ? MACH_RPC_BOUND : 0)
  235.  
  236. #define ROUNDUP2(x,n)    ((((unsigned)(x)) + (n) - 1) & ~((n)-1))
  237. #define ROUNDWORD(x)    ROUNDUP2(x,sizeof(int))
  238.  
  239. /*
  240.  *      RPC errors
  241.  *
  242.  *      Display and process errors of different severity, from just for
  243.  *      information only to fatal (panic). Error code colors indicate how
  244.  *      difficult it is for the subsystem to handle the error correctly.
  245.  *      The implication is that, for example, early versions of the code may
  246.  *      not be handling code red errors properly. The code should use this
  247.  *      facility instead of regular printf's.
  248.  */
  249.  
  250. #define    MACH_RPC_DEBUG    1
  251.  
  252. #define ERR_INFO        1               /* purely informational */
  253. #define ERR_GREEN       2               /* easily handled error */
  254. #define ERR_YELLOW      3               /* medium difficult error */
  255. #define ERR_RED         4               /* difficult to handle error */
  256. #define ERR_FATAL       5               /* unrecoverable error, panic */
  257.  
  258. #if MACH_RPC_DEBUG > 1
  259. #define rpc_error(E,S)                                                  \
  260.         printf("RPC error ");                                           \
  261.         rpc_error_show_severity(S);                                     \
  262.         printf("in file \"%s\", line %d: ", __FILE__, __LINE__);        \
  263.         printf E ;                                                      \
  264.         printf("\n");                                                   \
  265.         rpc_error_severity(S)
  266. #else
  267. #define rpc_error(E,S)                                                  \
  268.     if ((S) == ERR_FATAL || (S) == ERR_RED) {            \
  269.         printf("RPC error ");                                           \
  270.         rpc_error_show_severity(S);                                     \
  271.         printf("in file \"%s\", line %d: ", __FILE__, __LINE__);        \
  272.         printf E ;                                                      \
  273.         printf("\n");                                                   \
  274.         rpc_error_severity(S);                        \
  275.     }
  276. #endif    /* MACH_RPC_DEBUG */
  277.  
  278. /*
  279.  *      RPC buffer size and break points
  280.  *
  281.  *      These values define the rpc buffer size on the kernel stack,
  282.  *      and break point values for switching to virtual copy (cow).
  283.  *      This should be in a machine dependent include file. All sizes
  284.  *      are in word (sizeof(int)) units.
  285.  */
  286.  
  287. #define RPC_KBUF_SIZE   16              /* kernel stack buffer size (ints) */
  288. #define RPC_COW_SIZE    1024            /* size where COW is a win (ints) */
  289. #define RPC_DESC_COUNT  4               /* default descriptor count */
  290.  
  291.  
  292. /*
  293.  *      RPC copy state
  294.  *
  295.  *      Record the rpc copy state for arrays, so we can unwind our state
  296.  *      during error processing. There is one entry per complex (signatured)
  297.  *      argument. The first entry is marked COPY_TYPE_ALLOC_KRN if this record
  298.  *      itself was kalloc'd because the number of complex arg descriptors
  299.  *      exceeded the default value (RPC_DESC_COUNT). This is not a conflict
  300.  *      since the first argument is always the destination port, never an array.
  301.  */
  302.  
  303. #define COPY_TYPE_NO_COPY               0       /* nothing special */
  304. #define COPY_TYPE_ON_KSTACK             1       /* array is on kernel stack */
  305. #define COPY_TYPE_ON_SSTACK             2       /* array is on server stack */
  306. #define COPY_TYPE_VIRTUAL_IN            3       /* vm_map_copyin part of cow */
  307. #define COPY_TYPE_VIRTUAL_OUT_SVR       4       /* map cpyout svr part of cow */
  308. #define COPY_TYPE_VIRTUAL_OUT_CLN       5       /* map cpyout cln part of cow */
  309. #define COPY_TYPE_ALLOC_KRN             6       /* kernel kalloc'd for array */
  310. #define COPY_TYPE_ALLOC_SVR             7       /* vm_alloc'd in server space */
  311. #define COPY_TYPE_ALLOC_CLN             8       /* vm_alloc'd in client space */
  312. #define COPY_TYPE_PORT                  9       /* plain port translated */
  313. #define COPY_TYPE_PORT_ARRAY            10      /* port array translated */
  314.  
  315.  
  316. /*
  317.  *     RPC types
  318.  */
  319. typedef int             rpc_id_t;
  320. typedef int             rpc_return_t;
  321. typedef unsigned int        rpc_size_t;
  322. typedef unsigned int        rpc_offset_t;
  323.  
  324. struct rpc_copy_state {
  325.         unsigned                copy_type;      /* what kind of copy */
  326.         vm_offset_t             alloc_addr;     /* address to free */
  327. };
  328. typedef struct rpc_copy_state *rpc_copy_state_t;
  329. typedef struct rpc_copy_state  rpc_copy_state_data_t;
  330.  
  331. typedef boolean_t (*copyfunc_t)(const char *, char *, vm_size_t);
  332.  
  333.  
  334. /*
  335.  *    RPC function declarations
  336.  */
  337.  
  338. #ifdef    CALLOUT_RPC_MODEL
  339.  
  340. extern
  341. void            rpc_bootstrap( void );
  342.  
  343. extern
  344. void            rpc_remote_bootstrap( void );
  345.  
  346. extern 
  347. rpc_return_t    mach_rpc_trap(
  348.                 mach_port_name_t    dest_port,
  349.                 rpc_id_t        routine_num,
  350.                 rpc_signature_t    signature_ptr,
  351.                 rpc_size_t     signature_size );
  352.                                         
  353. extern 
  354. rpc_return_t    mach_rpc_return_trap( void );
  355.  
  356. extern 
  357. rpc_return_t    mach_rpc_return_error( void );
  358.  
  359. void            mach_rpc_return_wrapper( void );
  360.  
  361. void                rpc_upcall( 
  362.                 vm_offset_t        stack,
  363.                 vm_offset_t        new_stack, 
  364.                 vm_offset_t        server_func, 
  365.                 int             return_code );
  366.  
  367. void                rpc_error_severity( int severity );
  368. void                rpc_error_show_severity( int severity );
  369. unsigned int        name_rpc_to_ipc( unsigned int action );
  370.  
  371. void            clean_port_array(
  372.                 ipc_object_t *        array,
  373.                 unsigned        count,
  374.                 unsigned        cooked,
  375.                 unsigned        direct );
  376.  
  377. void                unwind_rpc_state( 
  378.                 routine_descriptor_t    routine, 
  379.                 rpc_copy_state_t    state, 
  380.                 int *             arg_buf );
  381.  
  382. kern_return_t        unwind_invoke_state( 
  383.                 thread_act_t        thr_act );
  384.  
  385. kern_return_t       rpc_invke_args_in( 
  386.                 routine_descriptor_t    routine, 
  387.                 rpc_copy_state_t    state,
  388.                 int *            arg_buf,
  389.                 copyfunc_t        infunc );
  390.  
  391. kern_return_t       rpc_invke_args_out( 
  392.                 routine_descriptor_t    routine, 
  393.                 rpc_copy_state_t    state,
  394.                 int *            arg_buf, 
  395.                 int **             new_sp,
  396.                 copyfunc_t        outfunc );
  397.  
  398. kern_return_t       rpc_reply_args_in( 
  399.                 routine_descriptor_t    routine, 
  400.                 rpc_copy_state_t    state,
  401.                 int *            svr_buf,
  402.                 copyfunc_t        infunc );
  403.  
  404. kern_return_t       rpc_reply_args_out( 
  405.                 routine_descriptor_t    routine, 
  406.                 rpc_copy_state_t    state,
  407.                 int *            svr_buf, 
  408.                 int *             cln_buf,
  409.                 copyfunc_t        outfunc );
  410.  
  411. #endif  /* CALLOUT_RPC_MODEL */
  412.  
  413. /*
  414.  * libmach helper functions:
  415.  */
  416. extern rpc_subsystem_t    mach_subsystem_join(
  417.                 rpc_subsystem_t,
  418.                 rpc_subsystem_t,
  419.                 unsigned int *,
  420.                 void *(* )(int));
  421.  
  422. #endif    /* _MACH_RPC_H_ */
  423.  
  424.  
  425.