This document describes the programs used to generate an initial bootable EROS environment. It provides a brief description of the cross environment and system generation tools.

1. Overview

Creating a bootable system image entails the following steps:

1. Creating, using a set of cross compilation tools, an EROS kernel image and boot sector(s) for the target architecture.
2. Creating, using a set of cross compilation tools, the domains required during the initial system load (ISL).
3. Producing from these domains a single eros image file describing the relationships between the domains and all of the keys they hold. (mkimage).
4. Formatting a volume to include a boot sector, a kernel image and suitably prepared EROS divisions, including performing any necessary bad sector detection and remapping (mkvol).
5. Mapping the master eros image file onto the nodes and pages that are actually available on a given volume (sysgen).

mkimage provides the necessary mechanisms to convert UNIX a.out files into EROS segments, set the values of domain and node registers, and generally wire up a family of collaborating domains.

mkvol creates an initial volume image, including bootstrap loader, an optional kernel image, and user-specified object ranges. The object ranges created by mkvol are initially empty.

The sysgen utility populates a volume created by mkvol with nodes and pages by loading one or more EROS image files into the volume. The EROS image files contain relocatable node and page keys; the sysgen utility assigns final locations to these nodes and pages. This is about to change - the ErosImage files will no longer hold relocatable page and node keys. All system initialization nodes/pages will be numbered from oid 0.

This document describes the EROS volume structure and boot process, and the use of the mkimage, mkvol, and sysgen tools.

EROS Volume Structure

An EROS volume is a logical disk. On an EROS-formatted floppy, the volume spans the entire disk. On hard disks things are a bit more complicated. Typically, the system firmware is designed to allow multiple independent operating systems to be loaded onto a single disk. The disk is divided into non-overlapping regions, typically called partitions, and each operating system acts for the most part as if its partition was a single disk. EROS is no different; it views its partition as a single volume, and largely ignores the rest of the disk.

Every EROS volume has up to 64 non-overlapping areas. To avoid collision with firmware terminology, we use the term division. Divisions come in several types:

Unused	Empty. Placeholder for unallocated space.
Boot	Contains the system-dependent boot code.
DivTbl	A table describing the division layout.
Kernel	The kernel's code.
Spare	Division containing spare sectors.
Log	A swap area.
Object	Holds EROS Pages and Nodes.

Every volume has exactly one boot division at sector 0. Every volume has at most one kernel division.

Every disk technology that we know about reserves sector 0 of a partition as the "boot sector." The EROS boot sector is defined by the VolHdr structure. It contains the following, among other things:

• A unique system identifier (iplSysId). All the volumes in a single EROS system will have the same system identifier. If the computer has volumes for more than one independent EROS system, the iplSysId distinguishes them. Only volumes matching the iplSysId of the booted volume will be mounted.
• The location of the primary (and optional secondary) division tables.

The division table describes, for each division, the type, the starting sector, and the ending sector. If the division is an Object or Log division, the division table also contains the starting OID or SwapLoc of the division.

2. Mkimage: Constructing EROS Images

An EROS image file consists of sequentially numbered nodes and pages, and is constructed using the mkimage utility. mkimage provides the facilities to turn UNIX a.out files into domains, and to establish the initial contents of nodes and pages.

A mkimage file consists of node and pages, each having object identifiers starting at 0. Node and page object identifiers are in independent name spaces, so there is no confusion of numbering.

Every EROS image file has at least one node, whose contents are used by the space bank. The first key of this node is a number key giving the object identifier of the highest allocated (equivalently: first available) node. The second key similarly gives the object identifier of the highest allocated page. A node key to this node is the first key in the image directory, and is inserted under the name volsize. A key to this node can be handed to the the prime space bank, and is used to avoid reallocating the space that has gone to nodes and pages in the boot image.

2.1. The Image Specification Language

This section needs to be rewritten.

mkimage produces an eros image file based on the instructions provided in a description file. Statements in the description file either import an existing eros image into the current image, declare new objects or modify existing objects.

3. Mkvol: Building an EROS Volume

3.1 Formatting and Spare Sectors

How much of this is still true?

Volume formatting is performed by the mkvol utility. The mkvol program formats a raw volume for use as an EROS volume. It takes as input a volume map file that describes how the disk should be formatted and the name of the volume file (on UNIX, the raw file corresponding to the EROS parition), and an optional disk descriptor type. Currently valid descriptor types are fd144 and fd. Descriptor types are used to describe the desired layout of the target volume when not writing directly to the raw device.

In order for a volume to be usable, the kernel, boot, and divtbl divisions must be error free. (We know how to remove this restriction for the kernel division, but have not done the necessary work in the boot loader to support sector remapping).

Some disk subsystems (SCSI, some IDE) provide automatic sector remapping. On these subsystems, no spare division is required, and the EROS kernel relies on the underlying hardware to provide remapping services. On disk subsystems that require OS-implemented remapping, the spare division will be used, if present, as a pool of spare sectors. The spare division is always optional. If it is not present, no remapping will be performed. The system generation process, for example, does not place a spare division on the ISL floppies, because we assume that the distribution media will be free of errors.

If a spare division is present, the bad sector remapping information is kept in the same disk page as the division table, and directly follows the division table entries. This allows a disk to have up to 384 bad sectors. Beyond that number, we think it's probably time to replace the disk.

As an EROS volume is formatted, a list of bad sectors is accumulated by the formatting program. Bad sectors that are found in Object or Log divisions are added to the BadMap. Bad sectors that are found in other types of divisions cause formatting to fail. Usually these failures can be worked around by rearranging the volume map to avoid the bad sectors.

3.2 The mkvol Volume Map

The mkvol utility performs formatting according to a volume map. The volume map is essentially a human-readable version of the division table to be created. It describes the start and end of each division, and for some divisions it provides the file that should be used to initialize that division (for example: the file containing the code for the boot sector).

The volmap file syntax is described in the mkvol reference.

3. Sysgen: Mapping Eros Images Onto Volumes

Once an EROS system image has been constructed and a volume has been formatted, mapping one onto the other is fairly straightforward. Pages from the EROS image are copied to the actual volume starting with the first page division, and nodes are copied starting with the first node division.

As a matter of practical simplicity, the sysgen utility assumes that only zero pages will need to be relocated. When the time comes to actually write such pages to the volume, final OID's are assigned to these pages and the necessary keys are relocated. All other objects are assumed to end up at the OID's assigned in the eros image volume, which precludes the need for any relocation.

A more sophisticated design would enable range placement, but I haven't the energy to build it at this time.

4. The Boot Process

This may want to move to another document

When the machine is powered up or reset, the firmware determines which volume (disk or partition) will be booted. Though the details are machine specific, the firmware typically proceeds by loading a small machine-dependent boot sector from sector 0 of the boot volume. Usually, the boot sector must first load a larger bootstrap routine, which in turn examines the volume map and loads the kernel itself. At this point, the EROS kernel proceeds with it's own startup procedure.

At a high level, the EROS kernel startup proceeds as follows:

1. Perform the minimum required hardware initialization.
2. Determine the unique system identifier (iplSysId) of the booted volume.
3. Locate and mount all divisions on all volumes whose iplSysId matches the iplSysId of the booted volume.
4. Locate the run list and begin executing the running processes. The run list is obtained from the most recent valid checkpoint image in the swap area.

Note that if unauthorized users are able to physically access the boot media, the system is not secure.

Finding the Unique System Identifier

The bootstrap routine passes the iplSysId, along with some other information, to the kernel in a structure called SysInfo.

Mounting the Divisions

Having determined the unique system identifier, the kernel now loads the master partition table of every disk, and searches for EROS volumes. For every EROS volume that it finds with a matching iplSysId, , it loads the division table. For every Object and Log division, the division is mounted and the pages and nodes in that division are made available to the object loading subsystem.

Finding the Run List

Once all of the divisions are known, the kernel must locate the list of processes to run from the swap area. The processes named in the run list are swapped in and scheduled.

Once these processes have been started, the system is running normally, and bootstrap processing terminates.