1 02/26/88 generate_mst, gm
2
3 Syntax as a command: gm path reel_id -control_args
4
5
6 Function: generates a BCE/Multics system tape that can later be
7 "bootloaded" by BCE as the first step in bringing up a Multics system.
8
9
10 Arguments:
11 path
12 is the pathname of the header segment without the header suffix.
13 reel_id
14 is the reel identification number of the tape from which information
15 is to be copied. The reel identification number, which is site
16 dependent, can be up to 32 characters long. The reel_id can also
17 include a density specification to indicate the density of the tape
18 being written, as in "060341,den=1600".
19
20
21 Control arguments:
22 -directory, -dr
23 provides a search rule segment in your working directory. The name
24 of the search rule segment is path.search, where path is the
25 entryname portion of the pathname given as the first argument to
26 generate_mst.
27 -file, -f
28 directs output to a file in the storage system rather than to a
29 tape. The file name which can specify a multisegment file has the
30 same name as the reel_id argument.
31 -hold
32 does not detach the tape when generation is completed. You can then
33 perform a checker run on the same tape without remounting the reel.
34
35
36 -notape
37 does not generate a tape. You can use -notape to check the
38 consistency of the header segment and produce an output listing
39 without actually generating a tape.
40 -sys_id STR, -sysid STR
41 sets the system identifier to STR which can be up to eight
42 characters long. If you omit it, the first eight characters of the
43 entryname portion of the pathname given as the first argument to
44 generate_mst are used by default.
45 -vers_id STR, -versid STR
46 sets the version identifier to STR which can be up to eight
47 characters long. If you omit it, the first eight characters of the
48 entryname portion of the pathname given as the first argument to
49 generate_mst are used by default.
50
51
52 Notes on the format of a system tape header: A system tape header is
53 an ASCII file in free format consisting of keywords followed by
54 optional control arguments. You can place comments anywhere in the
55 header, except within a keyword name or control argument, and can
56 separate them by "/*" and "*/".
57
58 There are two levels of keywords, major and minor. The fabricate,
59 first_name, name, object, and text keywords are initial keywords and
60 indicate the start of a description of control arguments for a single
61 segment to be placed on the system tape. The linkage keyword is only
62 valid if found in a Segment Description List SDL. The end keyword
63 indicates the end of an SDL. The collection keyword, which cannot
64 occur in an SDL, instructs the generator to write a collection mark on
65 the system tape The fini keyword, which cannot occur within an SDL,
66 instructs the generator to close out the tape by writing an EOF and
67 dismounting it.
68
69
70 The syntax of the header consists of some SDLs, occasionally separated
71 by collection keywords and ending with a fini keyword.
72
73 Keywords that do not have arguments are followed immediately by
74 semicolons; those that have are followed immediately by a colon, which
75 is followed by arguments, separated by commas. The arguments end with
76 a semicolon.
77
78
79 List of major keywords:
80 add_segnames
81 adds the segnames defined in an object segment to the list of names
82 for that segment, as if they had appeared in the list following an
83 "object" or a "name" statement. All names that appear as segname
84 definitions in the object segment are added to the list of names for
85 this segment. You can only use this keyword in the SDL for a bound
86 object segment immediately after the keyword that begins the SDL.
87 You can usually use it to replace the list of names associated with
88 a bound segment.
89
90
91 boot_program
92 begins the definition of a segment that will be placed in the
93 bootload portion of the system tape label. The bootload_program
94 portion of the system tape label will be executed when the
95 Initialize/Bootload sequence is executed via the IOM switch or OC
96 command sequence. Only the text section of the program is placed
97 on the tape, and it must be less than 1500 octal words long; if
98 shorter, it is padded to 1500 words with NOP instructions. Put
99 this keyword first in the header file. It is incompatible with the
100 first_name keyword.
101 collection
102 writes a collection mark indicated by N on the tape containing the
103 collection number that follows the collection keyword. Put this
104 keyword between segments, not in a segment definition.
105
106
107 data names
108 begins a list of names associated with the segment. This keyword
109 places the complete named segment on the tape, preceded by a preface
110 area containing all the information specified in the SDL. The data
111 keyword is used only for segments that are not Multics standard
112 object segments, such as ASCII files. The data and linkage keywords
113 are incompatible.
114
115 default_rpv_data
116 specifies the information that will be placed in the twenty-four
117 character external variable, default_rpv_data, in this segment.
118 This normally appears only for BCE/Multics system tapes and
119 identifies the symbol bootload_info$default_rpv_data in
120 bound_bootload_0. At system boot time this data can be used in
121 place of the current operator query; "Enter RPV data: ". Example:
122
123 default_rpv_data: rpv a40 800 501 9;
124
125
126 default_time_zone
127 is an optional key word that specifies a default time zone to use
128 at system bootload time when the time zone specification in the
129 system configuration is not available. If this argument is missing
130 the current per-process default time zone will be used. This
131 segment must contain two external names, default_time_zone and
132 default_time_zone_delta. The first identifies the location of the
133 four character variable used to hold the time zone abbreviation.
134 The second identifies the location of the fixed bin 71 variable
135 used to hold the micro-second offset delta of the selected time
136 zone from Greenwich Mean Time GMT. This normally appears only
137 for BCE/Multics system tapes and identifies the symbols
138 bootload_info$default_time_zone and
139 bootload_info$default_time_zone_delta in bound_bootload_0.
140
141 delete_name names
142 removes extra names from the list of names for the current segment
143 that were added with the add_segnames statement but that should not
144 appear on the segment. Like add_segnames, you can usually use it to
145 replace the list of names associated with a bound segment. It must
146 appear after add_segnames in an SDL.
147
148
149 end
150 specifies the end of a segment definition. This keyword must
151 conclude every use of an object, name, first_name, fabricate, or
152 text keyword.
153 fabricate names
154 makes an all-zero segment and places it on the tape; names is a list
155 of names associated with the segment. The attributes for the
156 segment are derived from the SDL. The fabricate and linkage
157 keywords are incompatible.
158 fini
159 specifies the end of a system tape header. Any keywords appearing
160 in the header after the first fini keyword are ignored.
161
162
163 first_name name
164 indicates that the named segment associated with this SDL is the
165 first segment on the tape and is specially processed; i.e., the
166 first 32 decimal words of the segment are overwritten with tape
167 header information when the tape is bootloaded.
168
169
170 linkage
171 places the linkage and definitions sections of an object segment on
172 the tape, following the object segment itself if you used the
173 object keyword to define it or the text section if you used the
174 name or text keywords. The linkage keyword must appear in an
175 object definition between the object, text, or name keyword for the
176 segment and the end keyword. Any minor keywords following a linkage
177 keyword e.g. wired are applied to the linkage section rather than
178 to the text section; you can use this to direct the linkage section
179 into a different supervisor-combined linkage segment than would be
180 used by default. You must supply the linkage keyword to include
181 definitions on the tape and copy them into the supervisor
182 definitions segment, even if the segment has no linkage section.
183
184
185 This is often true for object segments created with
186 create_data_segment. If an object segment is used by the
187 supervisor, place its definitions sections on the tape by specifying
188 the linkage keyword, even if the segment is started with the object
189 statement, so that the definitions section is included along with
190 the text section.
191
192
193 name names
194 places the named segment on tape preceded by a preface area for the
195 segment containing all the information specified in the SDL. If the
196 linkage keyword is found in the SDL, the generator splits apart the
197 object segment named and places only the text on the tape. Then the
198 linkage section by itself preceded by a preface area for the
199 linkage section follows the text and definitions section preceded
200 by its preface on the tape. Otherwise the entire object segment is
201 placed on the tape. Use this keyword for nonobject segments. For a
202 BCE/Multics system tape, the names specified in the header for a
203 segment are the only ones by which you can reference the segment.
204 Extra names on the segment itself are ignored. When adding a new
205 program to an existing bound segment, update the system tape header,
206 as well as the bindfile, before adding the name of the new program
207 to the list of names for the bound segment.
208
209
210 object names
211 behaves exactly as the name keyword except that the entire object
212 segment is placed on tape rather than just the text section. It is
213 also followed by the redundant linkage and definition sections if
214 you use the linkage keyword.
215 text names
216 places the text section alone on tape. Use this keyword if you want
217 only the text part of an object segment.
218
219
220 List of minor keywords:
221 abs_seg
222 is either yes or no. Indicates whether or not to suppress creation
223 of a segment when current length/maximum length is not zero.
224 access
225 is the SDW access mode for the segment in the supervisor's address
226 space. The list can contain any combination of read, write,
227 execute, and privileged.
228 acl
229 is an ACL entry placed in the branch of the segment. Only segments
230 placed in the hierarchy via "path_name" can have ACL entries. The
231 format of the acl arguments is "<access> Person_id.Project_id.tag",
232 where Person.Project.tag must include all three components.
233
234
235 bit_count
236 is a number specifying a bit count to be associated with the
237 segment.
238 cache
239 is either yes or no. It indicates whether or not to override the
240 default encacheability of the segment. If you don't give this
241 keyword, the following defaults are used: if you specify the
242 per_process keyword as yes, then cache is yes; if you specify the
243 init_seg or temp_seg keywords as yes or specify write access under
244 the access keyword, then cache is no; otherwise cache is yes.
245 cur_length
246 is a number specifying the number of words to be allocated to the
247 segment for unpaged segments and segments loaded in collection1.
248 If this segment is a collection1 segment that is to be paged,
249 cur_length is its length while unpaged.
250
251
252 delete_at_shutdown
253 is either yes or no. It indicates whether or not to return the
254 pages of the segment to the appropriate free pool at shutdown time.
255 init_seg
256 is either yes or no. It indicates whether or not to delete the
257 segment at the end of initialization.
258 link_sect_wired
259 is either yes or no. It indicates whether or not the linkage for
260 the segment is to be combined in the supervisor's wired linkage
261 section even though the segment itself might not be wired.
262 max_length
263 is a number specifying the number of pages to be allocated to this
264 segment for paged segments. The greater of max_length and
265 cur_length converted to pages determines the size of the page
266 table and the segment bound.
267
268
269 paged
270 is either yes or no. It indicates whether or not the segment is to
271 be constructed as a paged segment.
272 path_name
273 specifies that the segment is to be placed in the hierarchy. The
274 value of the argument is the pathname of the directory in which the
275 segment is placed. This keyword is required for segments in
276 collection3. If you choose this keyword, all names listed for the
277 segment are added to the version in the hierarchy. If an object
278 segment is to be placed in the hierarchy, define it with the object
279 keyword, so that the whole segment appears rather than just the text
280 section.
281 per_process
282 either yes or no. Indicates whether or not to suppress copying of
283 the SDW for this segment at process-creation time.
284
285
286 ringbrack
287 is 1, 2, or 3 numbers, separated by commas, to be interpreted as the
288 ring brackets to be placed in the branch for segments that are to go
289 in the hierarchy. Default ring brackets are 000. Rules for
290 assigning ring brackets are described in the set_ring_brackets
291 command.
292 sys_id
293 specifies an external name in this segment identifying a location
294 that is set to the eight-character system identifier see -sys_id.
295 This normally appears only for BCE/Multics system tapes and
296 identifies the symbol active_all_rings_data$system_id.
297 temp_seg
298 either yes or no. Indicates whether or not to delete the segment at
299 the end of the collection in which it was loaded.
300
301
302 vers_id
303 specifies an external name in this segment identifying a location
304 that is set to the eight-character version identifier see
305 -vers_id. This normally appears only for BCE/Multics system tapes
306 and identifies the symbol active_all_rings_data$version_id.
307 wired
308 either yes or no. Indicates whether or not the pages of the segment
309 are to be wired.
310
311
312 Notes on operations: The generate_mst command works by reading the
313 header segments and performing one of the following.
314
315 1. If the word found is an initial keyword, the information about the
316 specified segment i.e. all information up to the next end keyword
317 is gathered together and written on the system tape followed by the
318 data for the segment itself.
319
320 2. If the keyword is collection, a special mark is written on the tape
321 indicating the end of the specified collection.
322
323 3. If the keyword is fini, the tape is closed out and dismounted.
324
325
326
327 For segments that are placed on tape i.e. segments specified with an
328 initial keyword, the first argument to the initial keyword is the name
329 used when searching for the actual segment to be placed on tape. All
330 subsequent arguments are treated as secondary names, and although they
331 are placed on the tape in the preface area for each segment they are
332 not used by the generator.
333
334
335 Notes on hardcore profiling: If hardcore programs are compiled with
336 the -profile or -long_profile options, it is possible to profile the
337 behavior of the supervisor see the -hardcore control argument to the
338 profile command.
339
340
341 There are several common pitfalls encountered in hardcore profiling.
342 The size of the supervisor linkage segments must be increased to
343 contain the additional static data generated by the profiling code.
344 You can determine the required sizes from the loading summary
345 information following collection two in the output file from check_mst.
346 The supervisor linkage segments are as_linkage "Active Supervisor",
347 ai_linkage "Active Initialization", ws_linkage "Wired Supervisor",
348 and wi_linkage "Wired Initialization". aThey are defined near the
349 beginning of the standard header. Unless you remove the init_seg and
350 temp_seg keywords from initialization programs and their linkage
351 sections, it is not possible to profile supervisor initialization
352 programs because the profiling information would otherwise be
353 discarded as the system finished initialization, but this is rarely a
354 problem.
355
356
357 If wired code is to be profiled and you select -long_profile, the hcs_
358 gate and its linkage section must be wired because they are referenced
359 by the virtual CPU time and paging calculation operators; this is not
360 necessary if you use only -profile. If profiling a procedure that is
361 specified as wired in the header but whose linkage section is specified
362 as unwired, change the linkage section to be wired.
363
364 Interrupt side code can be meaningfully profiled only with -profile,
365 not with -long_profile, because interrupt code is not run in any
366 particular process, and therefore the virtual CPU time calculation
367 which is per process returns random results. This may lead to
368 overflow faults while running on the PRDS. Because -profile does not
369 require these calculations, you can use it with interrupt code.
370
371
372 Notes: The procedures that generate the system tape must first find
373 the necessary segments to place on the system tape and put them there
374 in a manner that can later be read by BCE and the initializing
375 programs themselves. The system tape generating procedures find this
376 information by scanning a header segment that contains names of
377 programs and data bases to be placed on the tape along with other
378 control information about the segments.
379
380 There is a set of search rules specifying which directories are to be
381 searched and the order of search when looking for the specified
382 segments. These rules can be contained in a segment, or you can use
383 default rules. If you use no search segment, only the directory
384 >ldd>hardcore>execution is searched for the programs to be placed on
385 the tape.
386
387
388 The standard system tape header used to generate the BCE/Multics
389 system tape is located in the segment
390 >ldd>hardcore>info>hardcore.header. The standard headers contain many
391 examples of valid header syntax. When you modify a header, first, if
392 possible, locate an example of the modification elsewhere in the
393 header since the semantics of the header are complicated.
394
395 This command assumes the name of the header segment is path.header,
396 where path is the first argument to the command. The output listing is
397 placed in a segment path.list in your working directory.
398
399 The search file must contain a list of directories to be searched, one
400 directory name per line. A blank line signifies your working
401 directory.