02/26/88 generate_mst, gm Syntax as a command: gm path reel_id {-control_args} Function: generates a BCE/Multics system tape that can later be "bootloaded" by BCE as the first step in bringing up a Multics system. Arguments: path is the pathname of the header segment without the header suffix. reel_id is the reel identification number of the tape from which information is to be copied. The reel identification number, which is site dependent, can be up to 32 characters long. The reel_id can also include a density specification to indicate the density of the tape being written, as in "060341,den=1600". Control arguments: -directory, -dr provides a search rule segment in your working directory. The name of the search rule segment is path.search, where path is the entryname portion of the pathname given as the first argument to generate_mst. -file, -fl directs output to a file in the storage system rather than to a tape. The file name (which can specify a multisegment file) has the same name as the reel_id argument. -hold does not detach the tape when generation is completed. You can then perform a checker run on the same tape without remounting the reel. -notape does not generate a tape. You can use -notape to check the consistency of the header segment and produce an output listing without actually generating a tape. -sys_id STR, -sysid STR sets the system identifier to STR (which can be up to eight characters long). If you omit it, the first eight characters of the entryname portion of the pathname given as the first argument to generate_mst are used by default. -vers_id STR, -versid STR sets the version identifier to STR (which can be up to eight characters long). If you omit it, the first eight characters of the entryname portion of the pathname given as the first argument to generate_mst are used by default. Notes on the format of a system tape header: A system tape header is an ASCII file (in free format) consisting of keywords followed by optional control arguments. You can place comments anywhere in the header, except within a keyword name or control argument, and can separate them by "/*" and "*/". There are two levels of keywords, major and minor. The fabricate, first_name, name, object, and text keywords are initial keywords and indicate the start of a description of control arguments for a single segment to be placed on the system tape. The linkage keyword is only valid if found in a Segment Description List (SDL). The end keyword indicates the end of an SDL. The collection keyword, which cannot occur in an SDL, instructs the generator to write a collection mark on the system tape The fini keyword, which cannot occur within an SDL, instructs the generator to close out the tape by writing an EOF and dismounting it. The syntax of the header consists of some SDLs, occasionally separated by collection keywords and ending with a fini keyword. Keywords that do not have arguments are followed immediately by semicolons; those that have are followed immediately by a colon, which is followed by arguments, separated by commas. The arguments end with a semicolon. List of major keywords: add_segnames adds the segnames defined in an object segment to the list of names for that segment, as if they had appeared in the list following an "object" or a "name" statement. All names that appear as segname definitions in the object segment are added to the list of names for this segment. You can only use this keyword in the SDL for a bound object segment immediately after the keyword that begins the SDL. You can usually use it to replace the list of names associated with a bound segment. boot_program begins the definition of a segment that will be placed in the bootload portion of the system tape label. The bootload_program portion of the system tape label will be executed when the Initialize/Bootload sequence is executed via the IOM switch or OC command sequence. Only the text section of the program is placed on the tape, and it must be less than 1500 (octal) words long; if shorter, it is padded to 1500 words with NOP instructions. Put this keyword first in the header file. It is incompatible with the first_name keyword. collection writes a collection mark indicated by N on the tape containing the collection number that follows the collection keyword. Put this keyword between segments, not in a segment definition. data names begins a list of names associated with the segment. This keyword places the complete named segment on the tape, preceded by a preface area containing all the information specified in the SDL. The data keyword is used only for segments that are not Multics standard object segments, such as ASCII files. The data and linkage keywords are incompatible. default_rpv_data specifies the information that will be placed in the twenty-four character external variable, default_rpv_data, in this segment. This normally appears only for BCE/Multics system tapes and identifies the symbol bootload_info$default_rpv_data in bound_bootload_0. At system boot time this data can be used in place of the current operator query; "Enter RPV data: ". Example: default_rpv_data: rpv a40 800 501 9; default_time_zone is an optional key word that specifies a default time zone to use at system bootload time when the time zone specification in the system configuration is not available. If this argument is missing the current per-process default time zone will be used. This segment must contain two external names, default_time_zone and default_time_zone_delta. The first identifies the location of the four character variable used to hold the time zone abbreviation. The second identifies the location of the fixed bin (71) variable used to hold the micro-second offset (delta) of the selected time zone from Greenwich Mean Time (GMT). This normally appears only for BCE/Multics system tapes and identifies the symbols bootload_info$default_time_zone and bootload_info$default_time_zone_delta in bound_bootload_0. delete_name names removes extra names from the list of names for the current segment that were added with the add_segnames statement but that should not appear on the segment. Like add_segnames, you can usually use it to replace the list of names associated with a bound segment. It must appear after add_segnames in an SDL. end specifies the end of a segment definition. This keyword must conclude every use of an object, name, first_name, fabricate, or text keyword. fabricate names makes an all-zero segment and places it on the tape; names is a list of names associated with the segment. The attributes for the segment are derived from the SDL. The fabricate and linkage keywords are incompatible. fini specifies the end of a system tape header. Any keywords appearing in the header after the first fini keyword are ignored. first_name name indicates that the named segment associated with this SDL is the first segment on the tape and is specially processed; i.e., the first 32 decimal words of the segment are overwritten with tape header information when the tape is bootloaded. linkage places the linkage and definitions sections of an object segment on the tape, following the object segment itself (if you used the object keyword to define it) or the text section (if you used the name or text keywords). The linkage keyword must appear in an object definition between the object, text, or name keyword for the segment and the end keyword. Any minor keywords following a linkage keyword (e.g., wired) are applied to the linkage section rather than to the text section; you can use this to direct the linkage section into a different supervisor-combined linkage segment than would be used by default. You must supply the linkage keyword to include definitions on the tape and copy them into the supervisor definitions segment, even if the segment has no linkage section. This is often true for object segments created with create_data_segment. If an object segment is used by the supervisor, place its definitions sections on the tape by specifying the linkage keyword, even if the segment is started with the object statement, so that the definitions section is included along with the text section. name names places the named segment on tape preceded by a preface area for the segment containing all the information specified in the SDL. If the linkage keyword is found in the SDL, the generator splits apart the object segment named and places only the text on the tape. Then the linkage section by itself (preceded by a preface area for the linkage section) follows the text and definitions section (preceded by its preface) on the tape. Otherwise the entire object segment is placed on the tape. Use this keyword for nonobject segments. For a BCE/Multics system tape, the names specified in the header for a segment are the only ones by which you can reference the segment. Extra names on the segment itself are ignored. When adding a new program to an existing bound segment, update the system tape header, as well as the bindfile, before adding the name of the new program to the list of names for the bound segment. object names behaves exactly as the name keyword except that the entire object segment is placed on tape rather than just the text section. It is also followed by the (redundant) linkage and definition sections if you use the linkage keyword. text names places the text section alone on tape. Use this keyword if you want only the text part of an object segment. List of minor keywords: abs_seg is either yes or no. Indicates whether or not to suppress creation of a segment when current length/maximum length is not zero. access is the SDW access mode for the segment in the supervisor's address space. The list can contain any combination of read, write, execute, and privileged. acl is an ACL entry placed in the branch of the segment. Only segments placed in the hierarchy (via "path_name") can have ACL entries. The format of the acl arguments is " Person_id.Project_id.tag", where Person.Project.tag must include all three components. bit_count is a number specifying a bit count to be associated with the segment. cache is either yes or no. It indicates whether or not to override the default encacheability of the segment. If you don't give this keyword, the following defaults are used: if you specify the per_process keyword as yes, then cache is yes; if you specify the init_seg or temp_seg keywords as yes or specify write access under the access keyword, then cache is no; otherwise cache is yes. cur_length is a number specifying the number of words to be allocated to the segment (for unpaged segments and segments loaded in collection1). If this segment is a collection1 segment that is to be paged, cur_length is its length while unpaged. delete_at_shutdown is either yes or no. It indicates whether or not to return the pages of the segment to the appropriate free pool at shutdown time. init_seg is either yes or no. It indicates whether or not to delete the segment at the end of initialization. link_sect_wired is either yes or no. It indicates whether or not the linkage for the segment is to be combined in the supervisor's wired linkage section even though the segment itself might not be wired. max_length is a number specifying the number of pages to be allocated to this segment (for paged segments). The greater of max_length and cur_length (converted to pages) determines the size of the page table and the segment bound. paged is either yes or no. It indicates whether or not the segment is to be constructed as a paged segment. path_name specifies that the segment is to be placed in the hierarchy. The value of the argument is the pathname of the directory in which the segment is placed. This keyword is required for segments in collection3. If you choose this keyword, all names listed for the segment are added to the version in the hierarchy. If an object segment is to be placed in the hierarchy, define it with the object keyword, so that the whole segment appears rather than just the text section. per_process either yes or no. Indicates whether or not to suppress copying of the SDW for this segment at process-creation time. ringbrack is 1, 2, or 3 numbers, separated by commas, to be interpreted as the ring brackets to be placed in the branch for segments that are to go in the hierarchy. Default ring brackets are (0,0,0). Rules for assigning ring brackets are described in the set_ring_brackets command. sys_id specifies an external name in this segment identifying a location that is set to the eight-character system identifier (see -sys_id). This normally appears only for BCE/Multics system tapes and identifies the symbol active_all_rings_data$system_id. temp_seg either yes or no. Indicates whether or not to delete the segment at the end of the collection in which it was loaded. vers_id specifies an external name in this segment identifying a location that is set to the eight-character version identifier (see -vers_id). This normally appears only for BCE/Multics system tapes and identifies the symbol active_all_rings_data$version_id. wired either yes or no. Indicates whether or not the pages of the segment are to be wired. Notes on operations: The generate_mst command works by reading the header segments and performing one of the following. 1. If the word found is an initial keyword, the information about the specified segment (i.e., all information up to the next end keyword) is gathered together and written on the system tape followed by the data for the segment itself. 2. If the keyword is collection, a special mark is written on the tape indicating the end of the specified collection. 3. If the keyword is fini, the tape is closed out and dismounted. For segments that are placed on tape (i.e., segments specified with an initial keyword), the first argument to the initial keyword is the name used when searching for the actual segment to be placed on tape. All subsequent arguments are treated as secondary names, and although they are placed on the tape in the preface area for each segment they are not used by the generator. Notes on hardcore profiling: If hardcore programs are compiled with the -profile or -long_profile options, it is possible to profile the behavior of the supervisor (see the -hardcore control argument to the profile command). There are several common pitfalls encountered in hardcore profiling. The size of the supervisor linkage segments must be increased to contain the additional static data generated by the profiling code. You can determine the required sizes from the loading summary information following collection two in the output file from check_mst. The supervisor linkage segments are as_linkage ("Active Supervisor"), ai_linkage ("Active Initialization"), ws_linkage ("Wired Supervisor"), and wi_linkage ("Wired Initialization"). aThey are defined near the beginning of the standard header. Unless you remove the init_seg and temp_seg keywords from initialization programs and their linkage sections, it is not possible to profile supervisor initialization programs (because the profiling information would otherwise be discarded as the system finished initialization), but this is rarely a problem. If wired code is to be profiled and you select -long_profile, the hcs_ gate and its linkage section must be wired because they are referenced by the virtual CPU time and paging calculation operators; this is not necessary if you use only -profile. If profiling a procedure that is specified as wired in the header but whose linkage section is specified as unwired, change the linkage section to be wired. Interrupt side code can be meaningfully profiled only with -profile, not with -long_profile, because interrupt code is not run in any particular process, and therefore the virtual CPU time calculation (which is per process) returns random results. This may lead to overflow faults while running on the PRDS. Because -profile does not require these calculations, you can use it with interrupt code. Notes: The procedures that generate the system tape must first find the necessary segments to place on the system tape and put them there in a manner that can later be read by BCE and the initializing programs themselves. The system tape generating procedures find this information by scanning a header segment that contains names of programs and data bases to be placed on the tape along with other control information about the segments. There is a set of search rules specifying which directories are to be searched and the order of search when looking for the specified segments. These rules can be contained in a segment, or you can use default rules. If you use no search segment, only the directory >ldd>hardcore>execution is searched for the programs to be placed on the tape. The standard system tape header used to generate the BCE/Multics system tape is located in the segment >ldd>hardcore>info>hardcore.header. The standard headers contain many examples of valid header syntax. When you modify a header, first, if possible, locate an example of the modification elsewhere in the header since the semantics of the header are complicated. This command assumes the name of the header segment is path.header, where path is the first argument to the command. The output listing is placed in a segment path.list in your working directory. The search file must contain a list of directories to be searched, one directory name per line. A blank line signifies your working directory. ----------------------------------------------------------- Historical Background This edition of the Multics software materials and documentation is provided and donated to Massachusetts Institute of Technology by Group BULL including BULL HN Information Systems Inc. as a contribution to computer science knowledge. This donation is made also to give evidence of the common contributions of Massachusetts Institute of Technology, Bell Laboratories, General Electric, Honeywell Information Systems Inc., Honeywell BULL Inc., Groupe BULL and BULL HN Information Systems Inc. to the development of this operating system. Multics development was initiated by Massachusetts Institute of Technology Project MAC (1963-1970), renamed the MIT Laboratory for Computer Science and Artificial Intelligence in the mid 1970s, under the leadership of Professor Fernando Jose Corbato. Users consider that Multics provided the best software architecture for managing computer hardware properly and for executing programs. Many subsequent operating systems incorporated Multics principles. Multics was distributed in 1975 to 2000 by Group Bull in Europe , and in the U.S. by Bull HN Information Systems Inc., as successor in interest by change in name only to Honeywell Bull Inc. and Honeywell Information Systems Inc. . ----------------------------------------------------------- Permission to use, copy, modify, and distribute these programs and their documentation for any purpose and without fee is hereby granted,provided that the below copyright notice and historical background appear in all copies and that both the copyright notice and historical background and this permission notice appear in supporting documentation, and that the names of MIT, HIS, BULL or BULL HN not be used in advertising or publicity pertaining to distribution of the programs without specific prior written permission. Copyright 1972 by Massachusetts Institute of Technology and Honeywell Information Systems Inc. Copyright 2006 by BULL HN Information Systems Inc. Copyright 2006 by Bull SAS All Rights Reserved