home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.0 / NeXTSTEP3.0.iso / NextDeveloper / Headers / mach / message.h < prev    next >
Encoding:
C/C++ Source or Header  |  1992-07-30  |  10.7 KB  |  382 lines
  1. /* 
  2.  * Mach Operating System
  3.  * Copyright (c) 1989 Carnegie-Mellon University
  4.  * Copyright (c) 1988 Carnegie-Mellon University
  5.  * Copyright (c) 1987 Carnegie-Mellon University
  6.  * All rights reserved.  The CMU software License Agreement specifies
  7.  * the terms and conditions for use and redistribution.
  8.  */
  9. /*
  10.  * HISTORY
  11.  * $Log:    message.h,v $
  12.  * 20-Apr-90  Gregg Kellogg (gk) at NeXT
  13.  *    NeXT: Added in RCV_LARGE option from new IPC.
  14.  *
  15.  * 04-Mar-90  Gregg Kellogg (gk) at NeXT
  16.  *    Go ahead and define MSG_TYPE_PORT_RECEIVE if not MACH_IPC_XXXHACH
  17.  *    for NeXT.  It will work the same as MSG_TYPE_PORT_ALL.
  18.  *
  19.  * Revision 2.13  89/05/01  17:02:55  rpd
  20.  *     Named the unused bits in msg_header_t and msg_type_t.
  21.  *     [89/05/01  14:10:59  rpd]
  22.  * 
  23.  * Revision 2.12  89/04/08  23:57:26  rpd
  24.  *     Added MSG_TYPE_POLYMORPHIC.
  25.  *     [89/04/08  23:56:51  rpd]
  26.  * 
  27.  * Revision 2.11  89/03/15  15:05:28  gm0w
  28.  *     Removed define of EXPORT_BOOLEAN and include of mach/boolean.h
  29.  *     [89/03/14            mrt]
  30.  * 
  31.  * Revision 2.10  89/03/09  20:21:19  rpd
  32.  *     More cleanup.
  33.  * 
  34.  * Revision 2.9  89/03/05  16:48:39  rpd
  35.  *     Moved ownership rights under MACH_IPC_XXXHACK !2n KERNEL).
  36.  *     [89/02/16            rpd]
  37.  * 
  38.  * Revision 2.8  89/02/25  18:38:35  gm0w
  39.  *     Changes for cleanup.
  40.  * 
  41.  * Revision 2.7  89/02/07  00:52:38  mwyoung
  42.  * Relocated from sys/message.h
  43.  * 
  44.  * Revision 2.6  88/10/11  10:25:00  rpd
  45.  *     Made comments fit into 80 column windows.
  46.  *     Commented out SEND_MSG_SIZE_CHANGE and SEND_KERNEL.
  47.  *     [88/10/09  08:48:39  rpd]
  48.  * 
  49.  * Revision 2.5  88/09/25  22:16:18  rpd
  50.  *     Commented out MSG_TYPE_INVALID.
  51.  *     [88/09/24  18:10:21  rpd]
  52.  * 
  53.  * Revision 2.4  88/08/24  02:35:27  mwyoung
  54.  *     Adjusted include file references.
  55.  *     [88/08/17  02:17:13  mwyoung]
  56.  * 
  57.  * Revision 2.3  88/07/20  21:05:05  rpd
  58.  * Made MSG_TYPE_PORT_NAME a separate type.
  59.  * 
  60.  * 25-Feb-88  Michael Young (mwyoung) at Carnegie-Mellon University
  61.  *    Added SEND_SWITCH for KERNEL-only use; created SEND_USER and
  62.  *    RCV_USER declarations.
  63.  *
  64.  * 20-Nov-87  Michael Young (mwyoung) at Carnegie-Mellon University
  65.  *    Fixed declarations to use msg_timeout_t and msg_size_t everywhere.
  66.  *
  67.  * 12-Nov-87  Michael Young (mwyoung) at Carnegie-Mellon University
  68.  *    Added SEND_MSG_SIZE_CHANGE.
  69.  *
  70.  * 22-Oct-87  David Golub (dbg) at Carnegie-Mellon University
  71.  *    Fixed C++ declaration of msg_rpc.
  72.  *
  73.  * 20-Oct-87  Michael Young (mwyoung) at Carnegie-Mellon University
  74.  *    Add msg_size_t, msg_timeout_t declarations.
  75.  *
  76.  * 13-Oct-87  Mary R. Thompson
  77.  *    Changed timeout params in msg_send, msg_receive and msg_rpc to 
  78.  *    unsigned, since that is how mig declares them.
  79.  *
  80.  * 30-Aug-87  Michael Young (mwyoung) at Carnegie-Mellon University
  81.  *    Added C++ definitions, courtesy of David Detlefs.
  82.  *    Added MSG_TYPE_INTERNAL_MEMORY.
  83.  *
  84.  *  6-Aug-87  Mary Thompson (mrt) at Carnegie Mellon
  85.  *    Added MSG_TYPE_STRING_C to clarify what is intended by the type.
  86.  *
  87.  * 27-May-87  Avadis Tevanian (avie) at Carnegie-Mellon University
  88.  *    Changed msg_size and msg_simple to unsigned int, msg_long_{name,size}
  89.  *    to unsigned shorts.
  90.  *
  91.  * 27-Apr-87  Michael Young (mwyoung) at Carnegie-Mellon University
  92.  *    Added SEND_INTERRUPT option; fixed include file locations;
  93.  *    removed ancient history.
  94.  *
  95.  *    Mach IPC message and primitive function definitions.
  96.  *
  97.  */
  98.  
  99. #ifndef    _SYS_MESSAGE_H_
  100. #define _SYS_MESSAGE_H_
  101.  
  102. #include <mach/port.h>
  103.  
  104. /*
  105.  *    Message data structures.
  106.  *
  107.  *    Messages consist of two parts: a fixed-size header, immediately
  108.  *    followed by a variable-size!2ay of typed data items.
  109.  *
  110.  */
  111.  
  112. typedef    unsigned int    msg_size_t;
  113.  
  114. typedef    struct {
  115.         unsigned int    msg_unused : 24,
  116.                 msg_simple : 8;
  117.         msg_size_t    msg_size;
  118.         int        msg_type;
  119.         port_t        msg_local_port;
  120.         port_t        msg_remote_port;
  121.         int        msg_id;
  122. } msg_header_t;
  123.  
  124. #define MSG_SIZE_MAX    8192
  125.  
  126. /*
  127.  *    Known values for the msg_type field.
  128.  *    These are Accent holdovers, which should be purged when possible.
  129.  *
  130.  *    Only one bit in the msg_type field is used by the kernel.
  131.  *    Others are available to user applications.  See <msg_type.h>
  132.  *    for system application-assigned values.
  133.  */
  134.  
  135. #define MSG_TYPE_NORMAL        0
  136. #define MSG_TYPE_EMERGENCY    1
  137.  
  138. /*
  139.  *    Each data item is preceded by a description of that
  140.  *    item, including what type of data, how big it is, and
  141.  *    how many of them are present.
  142.  *
  143.  *    The actual data will either follow this type
  144.  *    descriptor ("inline") or will be specified by a pointer.
  145.  *
  146.  *    If the type name, size, or number is too large to be encoded
  147.  *    in this structure, the "longform" option may be selected,
  148.  *    and those fields must immediately follow in full integer fields.
  149.  *
  150.  *    For convenience, out-of-line data regions or port rights may
  151.  *    be deallocated when the message is sent by specifying the
  152.  *    "deallocate" field.  Beware: if the data item in question is both
  153.  *    out-of-line and contains port rights, then both will be deallocated.
  154.  */
  155.  
  156. typedef struct  {
  157.     unsigned int    msg_type_name : 8,        /* What kind of data */
  158.             msg_type_size : 8,        /* How many bits is each item */
  159.             msg_type_number : 12,        /* How many items are there */
  160.             msg_type_inline : 1,        /* If true, data follows; else a pointer */
  161.             msg_type_longform : 1,        /* Name, size, number follow: see above */
  162.             msg_type_deallocate : 1,    /* Deallocate port rights or memory */
  163.             msg_type_unused : 1;
  164. } msg_type_t;
  165.  
  166. typedef    struct    {
  167.     msg_type_t    msg_type_header;
  168.     unsigned short    msg_type_long_name;
  169.     unsigned short    msg_type_long_size;
  170.     unsigned int    msg_type_long_number;
  171. } msg_type_long_t;
  172.  
  173. /*
  174.  *    Known values for the msg_type_name field.
  175.  *
  176.  *    The only types known to the Mach kernel are
  177.  *    the port types, and those types used in the
  178.  *    kernel RPC interface.
  179.  */
  180.  
  181. #define MSG_TYPE_UNSTRUCTURED    0
  182. #define MSG_TYPE_BIT        0
  183. #define MSG_TYPE_BOOLEAN    0
  184. #define MSG_TYPE_INTEGER_16    1
  185. #define MSG_TYPE_INTEGER_32    2
  186. #define MSG_TYPE_PORT_ALL    5
  187. #define MSG_TYPE_PORT        6
  188. #define !2TYPE_CHAR        8
  189. #define MSG_TYPE_BYTE        9
  190. #define MSG_TYPE_INTEGER_8    9
  191. #define MSG_TYPE_REAL        10
  192. #define MSG_TYPE_STRING        12
  193. #define MSG_TYPE_STRING_C    12
  194. /*    MSG_TYPE_INVALID    13    unused */
  195.  
  196. #ifdef    KERNEL
  197. #define MSG_TYPE_INTERNAL_MEMORY 14
  198. #else    KERNEL
  199. #define MSG_TYPE_INTERNAL_MEMORY MSG_TYPE_INTEGER_8
  200. #endif    KERNEL
  201.  
  202. #define MSG_TYPE_PORT_NAME    15        /* A capability name */
  203. #define MSG_TYPE_LAST        16        /* Last assigned */
  204.  
  205. #define MSG_TYPE_POLYMORPHIC    ((unsigned int) -1)
  206.  
  207. /*
  208.  *    Is a given item a port type?
  209.  */
  210.  
  211. #define MSG_TYPE_PORT_ANY(x)    \
  212.     (((x) == MSG_TYPE_PORT) || ((x) == MSG_TYPE_PORT_ALL))
  213.  
  214. /*
  215.  *    Other basic types
  216.  */
  217.  
  218. typedef    unsigned int    msg_timeout_t;
  219.  
  220. /*
  221.  *    Options to IPC primitives.
  222.  *
  223.  *    These can be combined by or'ing; the combination RPC call
  224.  *    uses both SEND_ and RCV_ options at once.
  225.  */
  226.  
  227. typedef    int        msg_option_t;
  228.  
  229. #define MSG_OPTION_NONE    0x0000    /* Terminate only when message op works */
  230.  
  231. #define SEND_TIMEOUT    0x0001    /* Terminate on timeout elapsed */
  232. #define SEND_NOTIFY    0x0002    /* Terminate with reply message if need be */
  233.  
  234. #define SEND_INTERRUPT    0x0004    /* Terminate on software interrupt */
  235.  
  236. #ifdef    NeXT
  237. #define SEND_SWITCH    0x0020    /* Use handoff scheduling */
  238. #endif    NeXT
  239.  
  240. #ifdef    KERNEL
  241. #ifdef    NeXT
  242. #else    NeXT
  243. #define SEND_USER    (SEND_TIMEOUT|SEND_NOTIFY)
  244.                 /* Valid user options */
  245. #endif    NeXT
  246. #define SEND_ALWAYS    0x0008    /* Never block */
  247. /*    SEND_KERNEL    0x0010       Kernel is originator (not used) */
  248. #ifdef    NeXT
  249. #define    SEND_USER    (SEND_TIMEOUT|SEND_NOTIFY|SEND_SWITCH)
  250.                 /* Valid user options */
  251. #else    NeXT
  252. #define SEND_SWITCH    0x0020    /* Use handoff scheduling */
  253. #endif    NeXT
  254. #endif    KERNEL
  255.  
  256. #define RCV_TIMEOUT    0x0100    /* Terminate on timeout elapsed */
  257. #define RCV_NO_SENDERS    0x0200    /* Terminate if I'm the only sender left */
  258. #define RCV_INTERRUPT    0x0400    /* Terminate on software interrupt */
  259. #if    NeXT
  260. #define RCV_LARGE    0x1000
  261. #endif    NeXT
  262.  
  263. #ifdef    KERNEL
  264. #if    NeXT
  265. #define RCV_USER    (RCV_TIMEOUT|RCV_NO_SENDERS|RCV_INTERRUPT|RCV_LARGE)
  266. #else    NeXT
  267. #define RCV_USER    (RCV_TIMEOUT|RCV_NO_SENDERS|RCV_INTERRUPT)
  268. #endif    NeXT
  269. #endif    KERNEL
  270.  
  271. /*
  272.  *    Returns from IPC primitives.
  273.  *
  274.  *    Values are separate in order to allow RPC users to
  275.  *    distinguish which operation failed; for successful completion,
  276.  *    this doesn't matter.
  277.  */
  278.  
  279. typedef    int        msg_return_t;
  280.  
  281. #define SEND_SUCCESS        0
  282.  
  283. #define SEND_ERRORS_START    -100
  284. #ifdef    KERNEL
  285. #define SEND_IN_PROGRESS    -100
  286. #endif    KERNEL
  287. #define SEND_INVALID_MEMORY    -101    /* Message or OOL data invalid */
  288. #define SEND_INVALID_PORT    -102    /* Reference to inacessible port */
  289. #define SEND_TIMED_OUT        -103    /* Terminated due to timeout */
  290. #define SEND_WILL_NOTIFY    -105    /* Msg accepted provisionally */
  291. #define SEND_NOTIFY_IN_PROGRESS    -106    /* Already awaiting a notification */
  292. #define SEND_KERNEL_REFUSED    -107    /* Message to the kernel refused */
  293. #defin!2ND_INTERRUPTED    -108    /* Software interrupt during send */
  294. #define SEND_MSG_TOO_LARGE    -109    /* Message specified was too large */
  295. #define SEND_MSG_TOO_SMALL    -110    /* Data specified exceeds msg size */
  296. /*    SEND_MSG_SIZE_CHANGE    -111       Msg size changed during copy */
  297. #define SEND_ERRORS_END        -111
  298.  
  299. #define msg_return_send(x)    ((x) < SEND_ERRORS_START && (x) > SEND_ERRORS_END)
  300.  
  301. #define RCV_SUCCESS        0
  302.  
  303. #define RCV_ERRORS_START    -200
  304. #ifdef    KERNEL
  305. #define RCV_IN_PROGRESS        -200
  306. #endif    KERNEL
  307. #define RCV_INVALID_MEMORY    -201
  308. #define RCV_INVALID_PORT    -202
  309. #define RCV_TIMED_OUT        -203
  310. #define RCV_TOO_LARGE        -204    /* Msg structure too small for data */
  311. #define RCV_NOT_ENOUGH_MEMORY    -205    /* Can't find space for OOL data */
  312. #define RCV_ONLY_SENDER        -206    /* Receiver is only sender */
  313. #define RCV_INTERRUPTED        -207
  314. #define RCV_PORT_CHANGE        -208    /* Port was put in a set */
  315. #define RCV_ERRORS_END        -209
  316.  
  317. #define msg_return_rcv(x)    ((x) < RCV_ERRORS_START && (x) > RCV_ERRORS_END)
  318.  
  319. #define RPC_SUCCESS        0
  320.  
  321. /*
  322.  *    The IPC primitive functions themselves
  323.  */
  324.  
  325. msg_return_t    msg_send(
  326. #if    c_plusplus || __STDC__
  327.     msg_header_t    *header,
  328.     msg_option_t    option,
  329.     msg_timeout_t    timeout);
  330. #else    c_plusplus || __STDC__
  331. #if    LINTLIBRARY
  332.             header, option, timeout)
  333.     msg_header_t    *header;
  334.     msg_option_t    option;
  335.     msg_timeout_t    timeout;
  336.     { return(SEND_SUCCESS); }
  337. #else    LINTLIBRARY
  338.         );
  339. #endif    LINTLIBRARY
  340. #endif    c_plusplus || __STDC__
  341.  
  342. msg_return_t    msg_receive(
  343. #if    c_plusplus || __STDC__
  344.     msg_header_t    *header,
  345.     msg_option_t    option,
  346.     msg_timeout_t    timeout);
  347. #else    c_plusplus || __STDC__
  348. #if    LINTLIBRARY
  349.             header, option, timeout)
  350.     msg_header_t    *header;
  351.     msg_option_t    option;
  352.     msg_timeout_t    timeout;
  353.     { return(RCV_SUCCESS); }
  354. #else    LINTLIBRARY
  355.         );
  356. #endif    LINTLIBRARY
  357. #endif    c_plusplus || __STDC__
  358.  
  359. msg_return_t    msg_rpc(
  360. #if    c_plusplus || __STDC__
  361.     msg_header_t    *header,    /* in/out */
  362.     msg_option_t    option,
  363.     msg_size_t    rcv_size,
  364.     msg_timeout_t    send_timeout,
  365.     msg_timeout_t    rcv_timeout);
  366. #else    c_plusplus || __STDC__
  367. #if    LINTLIBRARY
  368.             header, option, rcv_size,
  369.             send_timeout, rcv_timeout)
  370.     msg_header_t    *header;    /* in/out */
  371.     msg_option_t    option;
  372.     msg_size_t    rcv_size;
  373.     msg_timeout_t    send_timeout;
  374.     msg_timeout_t    rcv_timeout;
  375.     { return(RPC_SUCCESS); }
  376. #else    LINTLIBRARY
  377.         );
  378. #endif    LINTLIBRARY
  379. #endif    c_plusplus || __STDC__
  380.  
  381. #endif    _SYS_MESSAGE_H_
  382.