Page Numbers: Yes First Page: 27 X: 527 Y: 10.5"
Margins: Binding: 13
Odd Heading:
Alto/Mesa Image Files
Even Heading: Not-on-first-page
Alto/Mesa Image Files
Alto/Mesa Image Files
October 1980
A Mesa image file contains the information necessary to start execution of a Mesa system. In addition to image files that contain all code and data, there are also image files, called check files, that contain only data. (Because check files know the addresses of other files on the disk they cannot be moved like other image files). This section defines the facilities provided to make them. See ImageDefs for further details.
Making Image Files
The standard system does not contain code to make an image file of itself and any user programs which have been loaded. Clients must either load the ImageMaker or include it as part of their configuration. Clients may make an image file by calling the procedure:
MakeImage: PROCEDURE [name: STRING, merge: BOOLEAN ← TRUE];
Makes an image file on file name and returns to the Alto Executive. When the image file is restarted, MakeImage returns to its caller.
MakeImage normally merges all the Bcds that have been loaded into one bcd and cleans up system data structures. This results in faster loading of additional Bcds into the new image. Those clients who do not want Bcds merged during a MakeImage because they call UnNewConfig should supply FALSE to the optional parameter merge. The following procedure is provided for compatibly:
MakeUnMergedImage: PROCEDURE [name: STRING] = INLINE
{MakeImage[name, FALSE]};
Signals that may be generated by MakeImage or MakeUnMergedImage are:
InvalidImage: SIGNAL;
An attempt has been made to make an image file on top of the currently executing image file.
NoRoomInImageMap: SIGNAL;
The map in the ImageHeader has filled up. This usually means that there are too many segments in memory at the time the image file is made.
ImmovableSegmentInXM: SIGNAL [seg: SegmentHandle];
MakeImage (or CheckPoint) has discovered a segment in the extended memory banks that cannot be swapped out. (See the section on restrictions, below, for more information).
Check Files
Check files differ from normal image files in that they do not contain all the code and data necessary to start the execution of the image file. Check files only contain the data of the Mesa system, and all code and other segments remain in their original files. As a result, check files are made and restarted very quickly. However, care must be taken not to destroy files that are pointed to by the check file. Check files are useful for making check points in the execution of a Mesa system. The procedures and signals that make check files are:
MakeCheckPoint: PROCEDURE [name: STRING] RETURNS [restart: BOOLEAN];
Makes a check file on file name. Returns to the caller when finished as if nothing happened with restart set FALSE. If the check file is being restarted, it returns to the caller with TRUE.
NoRoomInCheckMap: SIGNAL;
In MakeCheckPoint, the map in the ImageHeader has filled up. This usually means that there are too many segments in memory at the time the check file is made.
The ability to make check files is not included in the basic system. Clients should include the CheckPoint module in their configuration.
Running Image Files
Mesa programs may run another image file without returning to the Alto Executive. The procedures and signals that implement this are:
RunImage: PROCEDURE [file: SegmentDefs.FileSegmentHandle];
Runs the image file specified by file where file is a segment handle for the header of the image file. The current state of the present image file is lost, and the new image file is loaded and started.
Fine point: currently the header of an image file is page one (this may change in the future, and may not be constant). Communication between the two image files must be done via disk files (like Com.cm). See the Alto Operating System Reference Manual.
InvalidImage: SIGNAL;
In RunImage, file specifies an invalid image file.
NoRoomForLoader: SIGNAL;
In RunImage, there is no room for the bootstrap loader that loads and starts the image file.
Clients should include the configuration ImageRunner in their configuration.
Miscellaneous
The version stamp of the currently running image file may be obtained by calling the procedure:
ImageVersion: PROCEDURE RETURNS [BcdDefs.VersionStamp];
The time that the currently running image file was created may be obtained by calling the procedure:
ImageTime: PROCEDURE RETURNS [TimeDefs.PackedTime];
The same information can be obtained about the caller’s BCD from the procedures:
BcdVersion: PROCEDURE RETURNS [BcdDefs.VersionStamp];
BcdTime: PROCEDURE RETURNS [TimeDefs.PackedTime];
A client may stop execution of a Mesa system and return to the Alto Executive by calling:
StopMesa: PROCEDURE;
A client may terminate execution of a Mesa system as if shift-swat had been typed and return to the Alto Executive by calling:
AbortMesa: PROCEDURE;
Cleanup Procedures
Client programs sometimes need to be notified when certain events occur so they can perform various cleanup functions. Cleanup procedures provide a facility to notify client programs when image files are made or restarted, and when stopping the execution of Mesa programs. The types and data structures involved with Cleanup procedures are:
CleanupProcedure: TYPE = PROCEDURE [why: CleanupReason];
CleanupItem: TYPE = RECORD [
link: POINTER TO CleanupItem,
mask: CARDINAL,
proc: CleanupProcedure];
CleanupReason: TYPE = BcplOps.CleanupReason;
BcplOps.CleanupReason: TYPE = {
Finish, . . . Save, Restore, CheckPoint, Restart, Continue, . . .};
CleanupReasons are copied from BcplOps. Valid ones are:
Finish:StopMesa was called.
Save:MakeImage was called.
Restore:returning from MakeImage.
Checkpoint:Checkpoint was called.
Restart:returning from Checkpoint restarted by the Alto Executive.
Continue:returning from Checkpoint.
The following procedures is used to add or remove cleanup procedures. The list of CleanupItems is processed in the opposite order when returning from an image file than when making one.
AddCleanupProcedure: PROCEDURE [POINTER TO CleanupItem];
RemoveCleanupProcedure: PROCEDURE [POINTER TO CleanupItem];
Warning: these procedures may not be invoked from inside Cleanup procedures.
CleanupMask: ARRAY CleanupReason OF CARDINAL =
[1, 2, 4, 10B, 20B, 40B, 100B, 200B, 400B, 1000B];
When the Cleanup procedure mechanism is invoked, each item is examined. If the bit corresponding to the reason is set in item.mask, item.proc is called. Clients must set the mask field so that their procedure is invoked only for the reasons they expect. For example, if a client needs to be notified when a normal image file is being made or started, the mask is set to:
CleanupMask[Save] + CleanupMask[Restore].
Warning: if the item.mask is improperly set, item.proc may be invoked at sensitive times, probably resulting in erroneous behavior.
Restrictions
MakeImage
1. The name of the new image file may not be the same as the name of the image file running at the time MakeImage is called. An image file can be renamed any time it is not running.
2. The user program should not have handles on any files or disk streams. Any file segments allocated by a user program will be made a part of the new image file.
3. This list of restrictions may not be exhaustive. In general you should avoid doing anything other than loading modules and initializing data structures before making an image file.
4. MakeImage cannot preserve the contents of extended memory in the image file it constructs. If MakeImage is invoked when useXM is TRUE, it will swap out all unlocked file segments in extended memory. (It will also move any locked code segments to the MDS.) If any segments then remain in extended memory, MakeImage will refuse to build the image file. Analogous comments apply to CheckPoint.
MakeCheckPoint
1. The name of the new image file may be the same as the name of the image file running at the time MakeCheckPoint is called, only if the current image file is a check file. A check file should not be renamed.
2. The files that are pointed to by the check files should not be moved or altered. Care must be taken with open disk streams that the pages of the current position of the stream are not moved or destroyed.
3. This list of restrictions may not be exhaustive and care must be taken with all files that are open at the time the check file was make.
CleanupProcedures
1. CleanupProcedures are called with interrupts and timeouts turned off.
2. This list of restrictions may not be exhaustive and care must be taken when using CleanupProcedures.