]>
Commit | Line | Data |
---|---|---|
1815bff5 A |
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); |