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