MONITOR(8)

NAME
monitor, edparams - load and start Minix, modify boot parameters

SYNOPSIS
edparams device [command ...]

DESCRIPTION
This text describes the boot monitor, a boot time interactive program designed not only to load and start Minix, its most important task, but to also provide an easy to use interface to configure Minix and to boot other operating systems.

The monitor is controlled with an environment that is modeled after the Bourne shell. This environment is filled at startup with default values that depend on the machine the monitor is running on and the environment settings saved into the boot parameters sector (the second sector on a device). When the environment is loaded, the monitor executes the function named main, which by default starts a simple menu.

The environment can be manipulated at boot time from the monitor prompt, but may also be edited using edparams on a given device. Edparams simulates the monitor as much as it can, echoing commands it can't execute between brackets. It may be used in Makefiles or scripts too by giving it commands as arguments.

COMMANDS
The monitor is best described by the commands you can type to the '>' prompt. This is known as the monitor mode. You can enter this mode by hitting the Escape key. A list of commands is shown if you type something illegal, like 'help'. These are the commands:

name = [device] value
    Set environment variable.
    Changes the value of name to value. Adding the word device (or any word starting with a 'd') marks name as being subject to device translation. (See the section on devices.) These (name, value) pairs are passed to the kernel who usually ignores them, unless they are one of these special variables: rootdev
        This is the device used as your root device. It is by default set to ram, which means that the device specified by ramimagedev will be loaded into the RAM disk and used as root. If you change this variable, then a physical device will be used as root, and the RAM disk will be uninitialized and have the size specified by ramsize.
    ramimagedev
        Describes the device to use to initialize the RAM disk if rootdev is set to ram. It's by default set to bootdev, a special name for the device the monitor booted from.
    ramsize
        The size of the RAM disk when it is not used as the root device, by default 0.
    keyboard
        This is by default set to standard, but may be changed to olivetti, us or dutch. The keyboard choice is translated to a number (if not a number already) and passed to the kernel assigned to the reserved scancode variable.
    processor
        Set by default to 86, 186, 286, 386 or 486, depending on the hardware you have. You can set it to a smaller value to test your kernel in a more limited environment.
    memsize
        Kilobytes of conventional memory.
    emssize
        Kilobytes of extended memory.
    chrome
        Either color or mono.
    video
        Describes capabilities of the VDU: mda, cga, ega, or vga.
    Two variables are only used by the monitor, even though they are passed to the kernel too: image
        The name of the file containing the kernel image, by default minix. If it refers to a directory however, the newest file inside that directory is chosen to be the kernel image. The names inside that directory are best set to the Minix version you are using, which looks good when the monitor prints the copyright message. To add feature to feature, if you add something like 'r29' to the version number, it will nicely tell you that you are running your 29-th revision of the original Minix. To sum up the rules used for pretty printing image names: A '/' or '_' is changed to a space. The first letter is changed from lowercase to uppercase. An 'r' if followed by a digit changes to ' revision '. If no digits have been printed, '1.6' is added as the default version.
    label
        If set then only processes marked with this label or without a label are loaded from the image. Use it to select a kernel process with a proper winchester driver for instance.
    Installboot -boot will create functions to select images and labels. These functions will set label and image and echo what you selected. The two numbers separated by a colon used as an image name tell the starting sector and sector count of the image on disk.
name() { ... }
    Define function.
    Functions may be used to bundle a set of commands, so that you can easily boot Minix with a different set of parameters then normal. E.g.
        ram() { rootdev=ram; boot }
    will allow you to run Minix with the root device on RAM for a change, if you normally use a real device as root. The only pre-set function is main with default value menu, which is the default command executed by the monitor. You can use newlines after the ')' token, the monitor will then use a '+' prompt and ask for the rest.
name(key) { ... }
    Define kernel selecting function.
    The menu command uses functions like these to add menu entries to select a different kernel from a boot disk. Installboot -boot produces these functions when the images are labeled. The label AT would give:
        AT(a) {label=AT;image=42:626;echo AT kernel selected;menu}
    With the menu option:
        a    Select AT kernel
    Typing a will then execute the AT function above.
name(key,text) { ... }
    User defined menu option.
    This variant may be used to make any menu entry you like:
        dos(d,Boot MS-DOS) { boot hd1 }
    Text may be anything, even matching parentheses.
name
    Call function.
    If name is a user defined function then its value is expanded and executed in place of name. Try a recursive one like 'rec() {rec;xx}' one day. You can see the monitor run out of space with nice messages about using chmem(1) to increase it's heap.
boot [device]
    Boot Minix or another O.S.
    Without an argument, boot will load and execute the Minix image named by the image variable. With an argument, boot loads the boot sector of device into memory and jumps to it, starting another operating system. You would normally use partitions on the first hard disk for this command (hd[1-4]), using hd0 may also work (choosing the active partition). Devices on the second hard disk (hd[5-9]) can only be booted if the bootstrap writer did not hardwire the disk number to disk 0. The name of device is used, not its Minix device number, making it independent from the Minix device name to device number mapping.
    Some operating systems can only be booted from the active partition, if you use a '*', e.g. boot *hd3, then partition 3 is first made active. You'll then need to use installboot -master with a fix key to forcefully boot the Minix partition at startup.
delay [msec]
    Delay (500 msec default).
    The first time my program worked on the hard disk I was a bit disappointed, 10 days of work went by in less then a second. Later I was pleased with that, because speed was one of the objectives. But if you need some time (to hit Escape, or stare at the numbers) you can use delay to make the monitor pause for a specified amount of time. To specify a delay just before Minix is started, you can set the variable delay to a number of milliseconds. Example:
        main() {delay 250; delay=500; boot}
    Look at this carefully, 'delay 250' means: "wait 1/4 sec now!", while 'delay=500' means: "wait 1/2 sec after loading Minix". If you use the word swap instead of a number, then the monitor will wait until you have inserted a root diskette and typed RETURN.
echo word ...
    Print these words.
    Used to tell you that you just selected image X.
ls [directory]
    List contents of directory.
    Shows the names of the files in a directory. It's only use is to list the names of the available kernels in the minix directory.
menu
    Menu driven startup.
    This command allows you to execute functions defined with a key. If no menu functions have been defined then menu will use this one hidden built-in function:
        *(=,Start Minix) { boot }
    Kernel selecting functions only add new options to this set, but if you define a two argument function yourself then the above one is no longer shown, allowing you to customize the menu completely. Your first function definition should therefore be one that starts Minix.
save
    Save environment.
    This will save all the environment variables and functions with nondefault values to the parameter sector (the second sector on the boot device), so they are automatically set the next time you boot the monitor.
set
    Show environment.
    Like the shell command of the same name, set will show you the current values of the environment variables and functions. Default values are shown between parentheses to distinguish them from values that were explicitly set.
trap msec command
    Schedule command.
    Schedules a command to be executed after msec milliseconds. Only the monitor mode cannot be interrupted, a scheduled trap is killed when the prompt is printed. Example:
        main() {trap 10000 boot; menu}
    This gives you 10 seconds to choose a menu option before Minix is booted.
unset name ...
    Unset environment variables.
    Removes the named variables and functions from the environment, and sets special variables back to their default values. This is also the only way to remove the "device name translation" property from a variable.

DEVICES
The Minix kernel can't do anything with device names, so they have to be translated to device numbers before they are passed to the kernel. This number is found under the st_rdev field (see stat(2)) of the file on the boot file system. The monitor will look for the device file with the working directory set to '/dev'. If it can't find the device name then it will translate names like 'ram', 'fd1', 'hd0', 'hd6', and 'hd2a' to what it itself thinks the numbers should be.

The special name bootdev is translated to the name of the device booted from, like 'fd0', or 'hd3', and then searched for in /dev.

EXTENSIONS
A few extensions have been made to this program for kernel hackers. They may be triggered by setting bits in the (normally 0) word used for the kernel DS value in kernel/mpx.x. The flag bits are:

0x0001 Call kernel in 386 mode.
    The monitor will make the switch to 386 protected mode before it calls the kernel. This requires changes to the early startup phase of the kernel. The advantages are that variables used at startup need not be within the first 64K, no need for a 8086 cross compiler to compile the few files that need to be in 16 bit mode, nor a loader that can combine 8086 and 80386 code.
0x0002 Do not make space for bss.
    The 386 virtual memory kernel can claim the bss pages for each process other than itself, the monitor need not do that. This allows for a much larger bss area then the monitor can make in that puny 640Kb. The size of the bss area in clicks is added to the two word table of process sizes in the kernel data segment to make it a three word table.
0x0004 Use the stack size set by chmem(1).
    This flag tells the monitor that it needs to make space for a stack as set by the chmem(1) command, because the processes are not using fixed sized arrays for the stack. If the 0x0002 bit is set, then the size of the stack in clicks is simply provided in a fourth word in the kernel data segment.
0x0008 Obsolete.
    This flag used to ask for the size of the symbol table, but the monitor no longer supports the misfeature of loading symbol tables into memory.
0x0010 No need to patch anything.
    The monitor places an array of the 32 byte a.out headers of the processes at address 0x00600. Setting this flag means that the kernel is using them instead of the sizes array, so the monitor need not patch anything.
Do not think that all of this means that this package is geared towards 386 Minix. All these extensions are just a few simple extra features. (Having first used Minix on an XT with just two 360kb floppy drives makes one not forget the low end.)

SEE ALSO
chmem(1), stat(2), installboot(8).

DIAGNOSTICS
Many self-explanatory messages about files not being found, bad images, disk read errors, lack of memory, etc.

ACKNOWLEDGMENTS
Guy Helmer, for the floppy sensing code that somehow disappeared into the boot block.

Earl Chew, for the inspiration his shoelace package provided, unless he wants to file a 'look and feel' suit against me, then I will say I modeled it after the SunOS ROM boot monitor, which is also true.

BUGS
The delay command will hang forever on the original IBM PC (not the XT!). Not that it matters, as everything takes forever on that box.

Reading the first sector to boot a floppy (e.g. boot fd1), is done using whatever floppy parameters boot currently has available. This will probably always work.

The two forms of delay are a crock.

The word emssize comes from EMS, that has to do with expanded memory, not extended memory. I didn't know the difference.

AUTHOR
Kees J. Bot (kjb@cs.vu.nl)