mach_init.tproj/bootstrap.defs

   1 /*
   2  * Copyright (c) 1999 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * "Portions Copyright (c) 1999 Apple Computer, Inc.  All Rights
   7  * Reserved.  This file contains Original Code and/or Modifications of
   8  * Original Code as defined in and that are subject to the Apple Public
   9  * Source License Version 1.0 (the 'License').  You may not use this file
  10  * except in compliance with the License.  Please obtain a copy of the
  11  * License at http://www.apple.com/publicsource and read it before using
  12  * this file.
  13  *
  14  * The Original Code and all software distributed under the License are
  15  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  16  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  17  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  18  * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the
  19  * License for the specific language governing rights and limitations
  20  * under the License."
  21  *
  22  * @APPLE_LICENSE_HEADER_END@
  23  */
  24 /*
  25  * bootstrap -- fundamental service initiator and port server
  26  * Mike DeMoney, NeXT, Inc.
  27  * Copyright, 1990.  All rights reserved.
  28  *
  29  * bootstrap.defs -- Mig interface definition
  30  */
  31
  32 subsystem bootstrap 400;
  33
  34 /*
  35  *      Interface:      Bootstrap server
  36  *
  37  *  The bootstrap server is the first user-mode task initiated by the Mach
  38  *  kernel at system boot time.  The bootstrap server provides two services,
  39  *  it initiates other system tasks, and manages a table of name-port bindings
  40  *  for fundamental system services  (e.g. the NetMsgServer, and the Unix
  41  *  emulation service).
  42  *
  43  *  The file /etc/bootstrap.conf is read by bootstrap to determine other system
  44  *  services to initiate at system boot time.  The format of this file is
  45  *  described later.
  46  *
  47  *  Name-port bindings can be established with the bootstrap server by either
  48  *  of two mechanisms:
  49  *
  50  *  1.  The binding can be indicated in the file /etc/bootstrap.conf.  In this
  51  *  case, bootstrap will immediately create a port and bind the indicated name
  52  *  with that port.  At a later time, a service may "checkin" for the name-port
  53  *  binding and will be returned receive rights for the bound port.  Lookup's
  54  *  on bindings created by this mechanism will return send rights to the port,
  55  *  even if no service has "checked-in".  In this case, requests sent to the
  56  *  bound port will be queued until a server has checked-in and can satisfy the
  57  *  request.
  58  *
  59  *  2.  Bindings can be established dynamically via a "register" request.  In
  60  *  this case, the register request provides bootstrap with a name and send
  61  *  rights for a port.  Bootstrap will provide send rights for the bound port
  62  *  to any requestor via the lookup request.
  63  *
  64  *  Bootstrap provides its service port to descendant tasks via the Mach
  65  *  "bootstrap" special task port.  All direct descendants of bootstrap receive
  66  *  a "privileged" bootstrap service port.  System services that initiate
  67  *  untrusted tasks should replace the Mach bootstrap task special port with
  68  *  a subset bootstrap port to prevent them from infecting the namespace.
  69  *
  70  *  The bootstrap server creates a "backup" port for each service that it
  71  *  creates.  This is used to detect when a checked out service is no longer
  72  *  being served.  The bootstrap server regains all rights to the port and
  73  *  it is marked available for check-out again.  This allows crashed servers to
  74  *  resume service to previous clients.  Lookup's on this named port will
  75  *  continue to be serviced by bootstrap while holding receive rights for the
  76  *  bound port.  A client may detect that the service is inactive via the.
  77  *  bootstrap status request.  If the service re-registers rather than
  78  *  "checking-in" the original bound port is destroyed.
  79  *
  80  *  The status of a named service may be obtained via the "status" request.
  81  *  A service is "active" if a name-port binding exists and receive rights
  82  *  to the bound port are held by a task other than bootstrap.
  83  *
  84  *  Bootstrap initiates server tasks and creates initial name-port bindings as
  85  *  directed by the configuration file /etc/bootstrap.conf.  This file has
  86  *  entries with the following formats:
  87  *
  88  *      services [ SERVICE_NAME ]+ ;
  89  *
  90  *              E.g:
  91  *              services OldService=1 SomeService;
  92  *
  93  *              Creates a port and binds the name "OldService" to it.
  94  *              For compatability, assigns the port via mach_ports_register to
  95  *              slot 1.  Also creates a port and binds the name "SomeService".
  96  *
  97  *      self [ SERVICE_NAME ]+ ;
  98  *
  99  *              E.g:
 100  *              self BootStrapService;
 101  *
 102  *              Provides a binding to bootstrap's own service port named
 103  *              "BootStrapService".
 104  *
 105  *      [restartable] server SERVER_FILE_AND_ARGS [ services ... ] ;
 106  *
 107  *              E.g:
 108  *              server "/usr/etc/sigserver -i" services UnixSignalService;
 109  *
 110  *              Initiates the server task "/usr/etc/sigserver" with
 111  *              command-line argument "-i", and also creates a name-port
 112  *              binding for the name UnixSignalService.  Checkin requests for
 113  *              UnixSignalService are only accepted via the bootstrap service
 114  *              port passed to/usr/etc/sigserver.  If the "restartable" option
 115  *              had been specified, bootstrap will reinitiate the server task
 116  *              if it receives notification that all of the server's service
 117  *              ports have been destroyed or deallocated.  The server command
 118  *              may be specified without surrounding quotes if it does not
 119  *              include blanks.
 120  *
 121  *      init SERVER_FILE_AND_ARGS [ services ... ] ;
 122  *
 123  *              E.g:
 124  *              init /etc/init services NetMsgService=0 PSWindowService=4;
 125  *
 126  *              Functions like "server" request above, except process is
 127  *              started as pid 1.  Illegal if bootstrap itself was not
 128  *              initiated as pid 1.
 129  *
 130  *      forward;
 131  *
 132  *              If present, bootstrap will forward unknown lookup requests to
 133  *              its bootstrap service port (if not PORT_NULL), and forward any
 134  *              reply to the original requester.
 135  *
 136  *      # Comment string up to end of line.
 137  *
 138  *              A line terminated comment starts with a sharp sign (#).
 139  *
 140  *  Lexical notes:  Strings are either enclosed in double quotes ("), or must
 141  *  start with a letter or underscore (_) and followed by a string of
 142  *  alphanumerics and underscores; backslash (\) escapes the following
 143  *  character.  Strings are limited to a (large) length.  Numbers must be
 144  *  decimal.  Blanks and newlines may be freely used outside of strings.
 145  */
 146
 147 #include <mach/std_types.defs>
 148 import <servers/bootstrap_defs.h>;
 149
 150 type name_t             = c_string[128];
 151 type name_array_t       = ^array [] of name_t;
 152 type bool_array_t       = ^array [] of boolean_t;
 153
 154 serverprefix x_;
 155
 156 /*  old service_checkin */
 157 skip;
 158 /*  old service_status */
 159 skip;
 160
 161 /*
 162  * kern_return_t
 163  * bootstrap_check_in(mach_port_t bootstrap_port,
 164  *                   name_t service_name,
 165  *                   port_all_t *service_port)
 166  *
 167  * Returns all rights to service_port of service named by service_name.
 168  *
 169  * Errors:      Returns appropriate kernel errors on rpc failure.
 170  *              Returns BOOTSTRAP_UNKNOWN_SERVICE, if service does not exist.
 171  *              Returns BOOTSTRAP_NOT_PRIVILEGED, if request directed to
 172  *                      bootstrap port without privilege.
 173  *              Returns BOOTSTRAP_SERVICE_ACTIVE, if service has already been
 174  *                      registered or checked-in.
 175  */
 176 routine bootstrap_check_in(
 177                         bootstrap_port  : mach_port_t;
 178                         service_name    : name_t;
 179                 out     service_port    : mach_port_move_receive_t);
 180
 181 /*
 182  * kern_return_t
 183  * bootstrap_register(mach_port_t bootstrap_port,
 184  *                    name_t service_name,
 185  *                    mach_port_t service_port)
 186  *
 187  * Registers send rights for the port service_port for the service named by
 188  * service_name.  Attempts to registering a service where an active binding
 189  * already exists are rejected.  On the otherhand, registering a service where
 190  * and inactive binding exists (i.e. bootstrap currently holds receive rights
 191  * for the service port) is allowed; in this case the previous service port
 192  * will be deallocated.  Restarting services wishing to resume service for
 193  * previous clients must first attempt to checkin to the service in order to
 194  * recover the previous service port.
 195  *
 196  * Errors:      Returns appropriate kernel errors on rpc failure.
 197  *              Returns BOOTSTRAP_NOT_PRIVILEGED, if request directed to
 198  *                      bootstrap port without privilege.
 199  *              Returns BOOTSTRAP_NAME_IN_USE, if service has already been
 200  *                      register or checked-in.
 201  */
 202 routine bootstrap_register(
 203                 bootstrap_port  : mach_port_t;
 204                 service_name    : name_t;
 205                 service_port    : mach_port_t);
 206
 207 /*
 208  * kern_return_t
 209  * bootstrap_look_up(mach_port_t bootstrap_port,
 210  *                  name_t service_name,
 211  *                  mach_port_t *service_port)
 212  *
 213  * Returns send rights for the service port of the service named by
 214  * service_name in service_port.  Service is not guaranteed to be active.
 215  *
 216  * Errors:      Returns appropriate kernel errors on rpc failure.
 217  *              Returns BOOTSTRAP_UNKNOWN_SERVICE, if service does not exist.
 218  */
 219 routine bootstrap_look_up(
 220                 bootstrap_port  : mach_port_t;
 221                 service_name    : name_t;
 222         out     service_port    : mach_port_t);
 223
 224 /*
 225  * kern_return_t
 226  * bootstrap_look_up_array(mach_port_t bootstrap_port,
 227  *                        name_array_t service_names,
 228  *                        int service_names_cnt,
 229  *                        port_array_t *service_port,
 230  *                        int *service_ports_cnt,
 231  *                        boolean_t *all_services_known)
 232  *
 233  * Returns port send rights in corresponding entries of the array service_ports
 234  * for all services named in the array service_names.  Service_ports_cnt is
 235  * returned and will always equal service_names_cnt (assuming service_names_cnt
 236  * is greater than or equal to zero).
 237  *
 238  * Errors:      Returns appropriate kernel errors on rpc failure.
 239  *              Returns BOOTSTRAP_NO_MEMORY, if server couldn't obtain memory
 240  *                      for response.
 241  *              Unknown service names have the corresponding service port set
 242  *                      to PORT_NULL.
 243  *              If all services are known, all_services_known is true on
 244  *                      return, if any service is unknown, it's false.
 245  */
 246 routine bootstrap_look_up_array(
 247                 bootstrap_port  : mach_port_t;
 248                 service_names   : name_array_t;
 249         out     service_ports   : mach_port_array_t;
 250         out     all_services_known: boolean_t);
 251
 252 /*  old bootstrap_get_unpriv_port */
 253 skip;
 254
 255 /*
 256  * kern_return_t
 257  * bootstrap_status(mach_port_t bootstrap_port,
 258  *                  name_t service_name,
 259  *                  boolean_t *service_active);
 260  *
 261  * Returns: service_active is true if service is available.
 262  *
 263  * Errors:      Returns appropriate kernel errors on rpc failure.
 264  *              Returns BOOTSTRAP_UNKNOWN_SERVICE, if service does not exist.
 265  */
 266 routine bootstrap_status(
 267                 bootstrap_port  :       mach_port_t;
 268                 service_name    :       name_t;
 269         out     service_active  :       boolean_t);
 270
 271 /*
 272  * kern_return_t
 273  * bootstrap_info(port_t bootstrap_port,
 274  *                name_array_t *service_names,
 275  *                int *service_names_cnt,
 276  *                name_array_t *server_names,
 277  *                int *server_names_cnt,
 278  *                bool_array_t *service_active,
 279  *                int *service_active_cnt);
 280  *
 281  * Errors:      Returns appropriate kernel errors on rpc failure.
 282  */
 283 routine bootstrap_info(
 284                 bootstrap_port  : mach_port_t;
 285         out     service_names   : name_array_t, dealloc;
 286         out server_names        : name_array_t, dealloc;
 287         out service_active      : bool_array_t, dealloc);
 288
 289 /*
 290  * kern_return_t
 291  * bootstrap_subset(mach_port_t bootstrap_port,
 292  *                  mach_port_t requestor_port,
 293  *                  mach_port_t *subset_port);
 294  *
 295  * Returns a new port to use as a bootstrap port.  This port behaves
 296  * exactly like the previous bootstrap_port, except that ports dynamically
 297  * registered via bootstrap_register() are available only to users of this
 298  * specific subset_port.  Lookups on the subset_port will return ports
 299  * registered with this port specifically, and ports registered with
 300  * ancestors of this subset_port.  Duplications of services already
 301  * registered with an ancestor port may be registered with the subset port
 302  * are allowed.  Services already advertised may then be effectively removed
 303  * by registering PORT_NULL for the service.
 304  * When it is detected that the requestor_port is destroied the subset
 305  * port and all services advertized by it are destroied as well.
 306  *
 307  * Errors:      Returns appropriate kernel errors on rpc failure.
 308  */
 309 routine bootstrap_subset(
 310                 bootstrap_port  : mach_port_t;
 311                 requestor_port  : mach_port_t;
 312         out     subset_port     : mach_port_t);
 313
 314 /*
 315  * kern_return_t
 316  * bootstrap_create_service(mach_port_t bootstrap_port,
 317  *                    name_t service_name,
 318  *                    mach_port_t *service_port)
 319  *
 320  * Creates a service named "service_name" and returns send rights to that
 321  * port in "service_port."  The port may later be checked in as if this
 322  * port were configured in the bootstrap configuration file.
 323  *
 324  * Errors:      Returns appropriate kernel errors on rpc failure.
 325  *              Returns BOOTSTRAP_SERVICE_ACTIVE, if service already exists.
 326  */
 327 routine bootstrap_create_service(
 328                 bootstrap_port  : mach_port_t;
 329                 service_name    : name_t;
 330         out     service_port    : mach_port_t);