home *** CD-ROM | disk | FTP | other *** search
/ H4CK3R 4 / hacker04 / 04_HACK04.ISO / darwin / darwinx86.iso / usr / include / mach / port.h < prev    next >
Encoding:
C/C++ Source or Header  |  2001-09-30  |  9.7 KB  |  269 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.  * Mach Operating System
  27.  * Copyright (c) 1991,1990,1989,1988,1987 Carnegie Mellon University
  28.  * All Rights Reserved.
  29.  * 
  30.  * Permission to use, copy, modify and distribute this software and its
  31.  * documentation is hereby granted, provided that both the copyright
  32.  * notice and this permission notice appear in all copies of the
  33.  * software, derivative works or modified versions, and any portions
  34.  * thereof, and that both notices appear in supporting documentation.
  35.  * 
  36.  * CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS"
  37.  * CONDITION.  CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR
  38.  * ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE.
  39.  * 
  40.  * Carnegie Mellon requests users of this software to return to
  41.  * 
  42.  *  Software Distribution Coordinator  or  Software.Distribution@CS.CMU.EDU
  43.  *  School of Computer Science
  44.  *  Carnegie Mellon University
  45.  *  Pittsburgh PA 15213-3890
  46.  * 
  47.  * any improvements or extensions that they make and grant Carnegie Mellon
  48.  * the rights to redistribute these changes.
  49.  */
  50. /*
  51.  */
  52. /*
  53.  *    File:    mach/port.h
  54.  *
  55.  *    Definition of a port
  56.  *
  57.  *    [The basic port_t type should probably be machine-dependent,
  58.  *    as it must be represented by a 32-bit integer.]
  59.  */
  60.  
  61. #ifndef    _MACH_PORT_H_
  62. #define _MACH_PORT_H_
  63.  
  64. #include <mach/boolean.h>
  65. #include <mach/machine/vm_types.h>
  66.  
  67. /*
  68.  * A port_name_t is a 32 bit value which represents a name of a
  69.  * port right within some ipc space.  This is a constant definition
  70.  * everywhere.
  71.  *
  72.  * The type port_t represents a reference added or deleted to a
  73.  * port right.
  74.  *
  75.  *     At user space, this is represented by returning the name of
  76.  *    the right(s) that got altered within the user's ipc space.
  77.  *    So a port_t is the same type as a port_name_t there.
  78.  *
  79.  *    Since there is no right space for the kernel proper (all rights
  80.  *    are naked rights) these rights are represented by passing a
  81.  *    pointer to the specific ipc_object_t subclass (typically
  82.  *    ipc_port_t) that got altered/is to be altered.
  83.  */
  84. typedef natural_t port_name_t;
  85. typedef port_name_t *port_name_array_t;
  86.  
  87.  
  88. typedef port_name_t port_t;
  89.  
  90.  
  91. /*
  92.  *  PORT_NULL is a legal value that can be carried in messages.
  93.  *  It indicates the absence of any port or port rights.  (A port
  94.  *  argument keeps the message from being "simple", even if the
  95.  *  value is PORT_NULL.)  The value PORT_DEAD is also a legal
  96.  *  value that can be carried in messages.  It indicates
  97.  *  that a port right was present, but it died.
  98.  */
  99. #define PORT_NULL        ((port_t) 0)
  100. #define PORT_DEAD        ((port_t) ~0)
  101. #define    PORT_VALID(name)                \
  102.         (((port_t)(name) != PORT_NULL) &&    \
  103.                  ((port_t)(name) != PORT_DEAD))
  104.  
  105. /*
  106.  *  Mach 3.0 renamed everything to have mach_ in front of it.
  107.  *  Do that mapping here, so we have the types and macros in
  108.  *  both formats.
  109.  */
  110. typedef port_t            mach_port_t;
  111. typedef port_t            *mach_port_array_t;
  112. typedef port_name_t        mach_port_name_t;
  113. typedef mach_port_name_t    *mach_port_name_array_t;
  114.  
  115. #define MACH_PORT_NULL        0  /* intentional loose typing */
  116. #define MACH_PORT_DEAD        ((mach_port_name_t) ~0)
  117. #define MACH_PORT_VALID(name)                \
  118.         (((name) != MACH_PORT_NULL) &&         \
  119.          ((name) != MACH_PORT_DEAD))
  120.  
  121. /*
  122.  *  mach_port_name_t must be an unsigned type.  Port values
  123.  *  have two parts, a generation number and an index.
  124.  *  These macros encapsulate all knowledge of how
  125.  *  a mach_port_name_t is laid out.  They are made visible 
  126.  *  to user tasks so that packages to map from a mach_port_name_t
  127.  *  to associated user data can discount the generation
  128.  *  nuber (if desired) in doing the mapping.
  129.  *
  130.  *  Within the kernel, ipc/ipc_entry.c implicitly assumes
  131.  *  when it uses the splay tree functions that the generation
  132.  *  number is in the low bits, so that names are ordered first
  133.  *  by index and then by generation.  If the size of generation
  134.  *  numbers changes, be sure to update IE_BITS_GEN_MASK and
  135.  *  friends in ipc/ipc_entry.h.
  136.  */
  137. #ifndef NO_PORT_GEN
  138. #define    MACH_PORT_INDEX(name)        ((name) >> 8)
  139. #define    MACH_PORT_GEN(name)        (((name) & 0xff) << 24)
  140. #define    MACH_PORT_MAKE(index, gen)    \
  141.         (((index) << 8) | (gen) >> 24)
  142. #else
  143. #define    MACH_PORT_INDEX(name)        (name)
  144. #define    MACH_PORT_GEN(name)        (0)
  145. #define    MACH_PORT_MAKE(index, gen)    (index)
  146. #endif    /* !NO_PORT_GEN */
  147.  
  148. /*
  149.  *  These are the different rights a task may have.
  150.  *  The MACH_PORT_RIGHT_* definitions are used as arguments
  151.  *  to mach_port_allocate, mach_port_get_refs, etc, to specify
  152.  *  a particular right to act upon.  The mach_port_names and
  153.  *  mach_port_type calls return bitmasks using the MACH_PORT_TYPE_*
  154.  *  definitions.  This is because a single name may denote
  155.  *  multiple rights.
  156.  */
  157.  
  158. typedef natural_t mach_port_right_t;
  159.  
  160. #define MACH_PORT_RIGHT_SEND        ((mach_port_right_t) 0)
  161. #define MACH_PORT_RIGHT_RECEIVE        ((mach_port_right_t) 1)
  162. #define MACH_PORT_RIGHT_SEND_ONCE    ((mach_port_right_t) 2)
  163. #define MACH_PORT_RIGHT_PORT_SET    ((mach_port_right_t) 3)
  164. #define MACH_PORT_RIGHT_DEAD_NAME    ((mach_port_right_t) 4)
  165. #define MACH_PORT_RIGHT_NUMBER        ((mach_port_right_t) 5)
  166.  
  167. typedef natural_t mach_port_type_t;
  168. typedef mach_port_type_t *mach_port_type_array_t;
  169.  
  170. #define MACH_PORT_TYPE(right)                        \
  171.         ((mach_port_type_t)(((mach_port_type_t) 1)          \
  172.         << ((right) + ((mach_port_right_t) 16))))    
  173. #define MACH_PORT_TYPE_NONE        ((mach_port_type_t) 0L)
  174. #define MACH_PORT_TYPE_SEND        MACH_PORT_TYPE(MACH_PORT_RIGHT_SEND)
  175. #define MACH_PORT_TYPE_RECEIVE        MACH_PORT_TYPE(MACH_PORT_RIGHT_RECEIVE)
  176. #define MACH_PORT_TYPE_SEND_ONCE    MACH_PORT_TYPE(MACH_PORT_RIGHT_SEND_ONCE)
  177. #define MACH_PORT_TYPE_PORT_SET        MACH_PORT_TYPE(MACH_PORT_RIGHT_PORT_SET)
  178. #define MACH_PORT_TYPE_DEAD_NAME    MACH_PORT_TYPE(MACH_PORT_RIGHT_DEAD_NAME)
  179.  
  180. /* Convenient combinations. */
  181.  
  182. #define MACH_PORT_TYPE_SEND_RECEIVE                    \
  183.         (MACH_PORT_TYPE_SEND|MACH_PORT_TYPE_RECEIVE)
  184. #define    MACH_PORT_TYPE_SEND_RIGHTS                    \
  185.         (MACH_PORT_TYPE_SEND|MACH_PORT_TYPE_SEND_ONCE)
  186. #define    MACH_PORT_TYPE_PORT_RIGHTS                    \
  187.         (MACH_PORT_TYPE_SEND_RIGHTS|MACH_PORT_TYPE_RECEIVE)
  188. #define    MACH_PORT_TYPE_PORT_OR_DEAD                    \
  189.         (MACH_PORT_TYPE_PORT_RIGHTS|MACH_PORT_TYPE_DEAD_NAME)
  190. #define MACH_PORT_TYPE_ALL_RIGHTS                    \
  191.         (MACH_PORT_TYPE_PORT_OR_DEAD|MACH_PORT_TYPE_PORT_SET)
  192.  
  193. /* Dummy type bits that mach_port_type/mach_port_names can return. */
  194.  
  195. #define MACH_PORT_TYPE_DNREQUEST    0x80000000
  196.  
  197. /* User-references for capabilities. */
  198.  
  199. typedef natural_t mach_port_urefs_t;
  200. typedef integer_t mach_port_delta_t;            /* change in urefs */
  201.  
  202. /* Attributes of ports.  (See mach_port_get_receive_status.) */
  203.  
  204. typedef natural_t mach_port_seqno_t;        /* sequence number */
  205. typedef natural_t mach_port_mscount_t;        /* make-send count */
  206. typedef natural_t mach_port_msgcount_t;        /* number of msgs */
  207. typedef natural_t mach_port_rights_t;        /* number of rights */
  208.  
  209. /*
  210.  *    A port may have NMS detection enabled, in which case
  211.  *    it tracks outstanding send rights.  Otherwise, there
  212.  *    is no information available about outstanding srights.
  213.  *    The return values are deliberately chosen to match
  214.  *    the old boolean (0=FALSE=no srights, 1=TRUE=srights,
  215.  *    2=xxx=no information available).
  216.  */
  217. #define    MACH_PORT_SRIGHTS_NONE        0        /* NMS:  no srights */
  218. #define    MACH_PORT_SRIGHTS_PRESENT    1        /* NMS:  srights */
  219. #define    MACH_PORT_SRIGHTS_NO_INFO    2        /* no NMS */
  220. typedef unsigned int mach_port_srights_t;    /* status of send rights */
  221.  
  222. typedef struct mach_port_status {
  223.     mach_port_name_t    mps_pset;    /* containing port set */
  224.     mach_port_seqno_t    mps_seqno;    /* sequence number */
  225.     mach_port_mscount_t    mps_mscount;    /* make-send count */
  226.     mach_port_msgcount_t    mps_qlimit;    /* queue limit */
  227.     mach_port_msgcount_t    mps_msgcount;    /* number in the queue */
  228.     mach_port_rights_t    mps_sorights;    /* how many send-once rights */
  229.     boolean_t        mps_srights;    /* do send rights exist? */
  230.     boolean_t        mps_pdrequest;    /* port-deleted requested? */
  231.     boolean_t        mps_nsrequest;    /* no-senders requested? */
  232.     unsigned int        mps_flags;    /* port flags */
  233. } mach_port_status_t;
  234.  
  235. #define MACH_PORT_QLIMIT_DEFAULT    ((mach_port_msgcount_t) 5)
  236. #define MACH_PORT_QLIMIT_MAX        ((mach_port_msgcount_t) 16)
  237.  
  238. typedef struct mach_port_limits {
  239.     mach_port_msgcount_t    mpl_qlimit;    /* number of msgs */
  240. } mach_port_limits_t;
  241.  
  242. typedef integer_t *mach_port_info_t;        /* varying array of natural_t */
  243.  
  244. /* Flavors for mach_port_get/set_attributes() */
  245. typedef int    mach_port_flavor_t;
  246. #define MACH_PORT_LIMITS_INFO        1    /* uses mach_port_status_t */
  247. #define MACH_PORT_RECEIVE_STATUS    2    /* uses mach_port_limits_t */
  248. #define MACH_PORT_DNREQUESTS_SIZE    3    /* info is int */
  249.  
  250. #define MACH_PORT_LIMITS_INFO_COUNT \
  251.     (sizeof(mach_port_limits_t)/sizeof(natural_t))
  252. #define MACH_PORT_RECEIVE_STATUS_COUNT \
  253.     (sizeof(mach_port_status_t)/sizeof(natural_t))
  254. #define MACH_PORT_DNREQUESTS_SIZE_COUNT 1
  255.  
  256. /*
  257.  * Structure used to pass information about port allocation requests.
  258.  * Must be padded to 64-bits total length.
  259.  */
  260.  
  261. typedef struct mach_port_qos {
  262.     boolean_t        name:1;        /* name given */
  263.     boolean_t        prealloc:1;    /* prealloced message */
  264.     boolean_t        pad1:30;
  265.     natural_t        len;
  266. } mach_port_qos_t;
  267.  
  268. #endif    /* _MACH_PORT_H_ */
  269.