NAME

     monitor, edparams - load and  start  MINIX  3,  modify  boot
     parameters


SYNOPSIS

     /boot
     edparams device [command ...]
     boot.com virdisk [command ...]


DESCRIPTION

     This text describes the Boot Monitor, a boot  time  interac-
     tive  program  designed  not only to load and start MINIX 3,
     its most important task, but to also provide an interface to
     configure MINIX 3 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 dev-
     ice).   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
     can also be used in Makefiles and scripts by giving it  com-
     mands as arguments.

     The DOS version of the monitor, usually named boot.com under
     DOS, boots MINIX 3 from a "DOS virtual disk".  Boot.com is a
     simple COM program that interprets a DOS  file  as  a  disk,
     loads a MINIX 3 kernel from the active partition in the same
     way as the BIOS based monitor,  and  executes  it  to  start
     MINIX 3.  All the monitor commands function in the same way,
     except for the boot command, it can only load MINIX 3.   The
     monitor  grabs  as much free memory as it can for MINIX 3 to
     work in, as the memory variable shows.  Further  details  on
     how to run MINIX 3 under DOS, Windows 95, or even Windows NT
     are written down in dosminix(8).


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.   These
     are the monitor commands:

     name = [device] value

          Set environment variable.
          Changes the value of name to value.  The optional  word
          device  marks  name as being subject to device transla-
          tion.  (See the  section  on  devices.)   These  (name,
          value)  pairs are passed to the kernel who uses them to
          configure  itself.   These  variables  are  passed   by
          default:

          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.  If the RAM disk is used
               for the root file system then the root file system
               is stretched out to ramsize if possible.

          processor
               Set by default to 86,  186,  286,  386,  486,  ...
               depending  on  the hardware you have.  You can set
               it to a smaller value to test  your  kernel  in  a
               more limited environment.

          bus
               The type of system bus,  either  xt,  at  or  mca.
               This  answers  basic  questions  like:  "How  many
               interrupt controllers and how to initialize?"  Or:
               "Does the keyboard have LEDs?"

          memory
               List of memory free for use by MINIX 3.  It  is  a
               comma  separated  list of base:size pairs denoting
               the byte offsets and sizes of free memory in hexa-
               decimal.   800:925E0,100000:F00000  is  a  typical
               example of about 585K  starting  at  2K,  and  15M
               starting at 1M.  (The first 2K are BIOS parameters
               and the 53K under the 640K boundary is the monitor
               itself.)   The  very last number you can play with
               if you know what you are doing.   Either  increase
               it  if the monitor has it wrong, or decrease it to
               test if MINIX 3 still runs with less  memory  then
               normal.

          video
               Describes capabilities of the VDU:  mda, cga,  ega
               or vga.

          chrome
               Either color or mono.

          c0
               By default at (AT compatibles), bios (XT or PS/2),
               or  dosfile  (running under DOS).  The c0 variable
               binds a driver to the first controller,  i.e.  the
               /dev/c0*  devices.  The monitor sets c0 to a suit-
               able default, so that most machines can find their
               disk.

          console
               If set to a hexadecimal value it makes the monitor
               set the BIOS video mode to this value when MINIX 3
               is started.  This allows the use  of  video  modes
               with  more  rows or colums than the standard 80x25
               mode.  You can use any  text  mode  in  the  00-FF
               range,  and  VESA  extended  modes  in the 100-FFF
               range.  Most text modes use a 9x16 font  with  400
               scanlines on screen, so you see 400/16 = 25 lines.
               The text mode can be modified  by  adding  special
               flags  to the console setting.  Add 2000 to switch
               to 480 scan lines, adding 20% more  lines  to  the
               screen.   Add 4000 to select a 9x14 font, so 28 or
               34 lines are shown.  Add 8000 instead to select an
               8x8 font showing 50 or 60 lines.  Each setting has
               drawbacks.  Using 480 scanlines implies  a  60  Hz
               refresh,  so the screen may flicker.  The 8x8 font
               looks squashed.  More letters  on  screen  require
               more  memory,  so  there  is less for virtual con-
               soles.  Interesting modes to try are 4003 (80x28),
               2003  (80x30),  6003  (80x34),  8003 (80x50), A003
               (80x60), 109 (132x25), 10A (132x43), 10B (132x50),
               10C  (132x60).   The 109 VESA mode is often avail-
               able, and can be modified like mode 3.  Use mode 7
               instead  of  3  for  monochrome.   Which modes and
               flags work can only be found  out  by  experiment.
               More  parameters  may  follow the mode number that
               are  of  interest  to  the  console  driver,   see
               boot(8).

          dosfile-d0
               Set by the DOS version of the monitor to the  name
               of the virtual disk, i.e.  the virdisk argument as
               shown above.  The "dosfile" driver will  use  this
               as the name of the file to use as a disk.

          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 then the newest file inside the  directory
               is  chosen  to  be  the  kernel  image.  The names
               inside /minix/ are best set to the MINIX 3 version
               you  are  using, which looks good when the monitor
               prints its name.  Rules 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 ".

          label
               If set then only processes marked with this  label
               or without a label are loaded from the image.

          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() command
          Define function.
          Functions may be used to bundle a set of  commands,  so
          that  you  can easily boot MINIX 3 with a different set
          of parameters then normal.  E.g.

               ram() { rootdev=ram; boot }

          will allow you to run MINIX 3 with the root  device  on
          RAM  for a change, if you normally use a real device as
          root.  There are three  predefined  functions,  leader,
          with  default  value  an  echo  command  that shows the
          monitor's startup  banner,  main,  with  default  value
          menu,  and  trailer,  with default value a command that
          clears the screen.  The monitor executes leader;main at
          startup  to  show  the  banner message and a menu.  The
          trailer function is executed just  before  MINIX  3  is
          started.  These three functions can be redefined as you
          please.

     name(key) command
          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) command
          User defined menu option.
          This variant may be used to make  any  menu  entry  you
          like:

               dos(d,Boot MS-DOS) boot d0p0

          Text may be anything, even parentheses if they match.

     name
          Call function.
          If name is a user defined function then  its  value  is
          expanded  and  executed in place of name.  Try a recur-
          sive 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 [-opts]
     boot device
          Boot MINIX 3 or another O.S.
          Without an argument, boot will  load  and  execute  the
          MINIX  3  image  named  by  the  image  variable.  With
          options the variable bootopts is  first  set  to  -opts
          before  MINIX  3  is  started,  and  unset  when  Minix
          returns.  With a device argument, boot loads  the  boot
          sector  of device into memory and jumps to it, starting
          another operating system.  You would normally use  par-
          titions  on  the  first  hard  disk  for  this  command
          (d0p[0-3]), using  d0  will  also  work  (choosing  the
          active  partition).   One  can also boot devices on the
          second hard disk (d1, d1p[0-3]) if the bootstrap writer
          did not hardwire the disk number to disk 0.
          Some Operating Systems can  only  be  booted  from  the
          active  partition,  if you use a '*', e.g.  boot *d0p2,
          then partition 2 is first  made  active.   You'll  then
          need to use

               installboot -m /dev/c0d0 /usr/mdec/jumpboot keys

          with keys chosen so that MINIX 3 is booted at  startup.
          (See installboot(8).)

     ctty n
          Copies output to and takes input  from  serial  line  n
          (0-3) at 9600 baud, 8 bits, no parity.  This allows you
          to control a MINIX 3 system remotely through an  RS-232
          connection.

     delay [msec]
          Delay (500 msec default).
          Fast booting speed was one of the objectives when  this
          program  was created, so a hard disk boot usually takes
          only a fraction of a second.  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  number  of
          milliseconds.

     echo word ...
          Print these words.
          Used to display  messages,  like  the  startup  banner.
          Echo  normally  prints the words with spaces in between
          and a newline at the end.  Echo understands special '\'
          escape sequences as follows:

               \    (At the end) Don't print a newline.
               \n   Print a newline.
               \v   Print the monitor's version numbers.
               \c   Clear the screen.
               \w   Wait until a RETURN is typed
               \\   Print a backslash.

     ls [directory]
          List contents of a directory.
          Useful when looking for kernel images.

     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 3.

          Menu entries are shown in the same order as  set  shows
          them.   If  you  don't  like the order then you have to
          unset the functions  and  retype  them  in  the  proper
          order.

          If you type a key then a scheduled trap is  killed  and
          the appropriate menu function is executed.  If you need
          more time to choose then hit the spacebar.  A  key  not
          on the menu also kills a trap, but does nothing more.

     save
          Save environment.
          This will save all the environment variables and  func-
          tions  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.
          Show 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 function
          Schedule function.
          Schedules a function to be  executed  after  msec  mil-
          liseconds.   Only  the  monitor  mode  cannot be inter-
          rupted, 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 3 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.

     exit
          Exit the monitor.
          Reboot the machine, exit to MINIX 3 or exit to  DOS  as
          appropriate.

     off
          Turn the PC off.
          If the PC supports power management then turn  it  off,
          otherwise print some error messages and do nothing.

     { command; ... }
          Bundle commands.
          Treat a number of commands as a single  command.   Used
          for function definitions when a function body must con-
          tain more than one command.


DEVICES

     The MINIX 3 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 dev-
     ice name then it will translate  names  like  'ram',  'fd1',
     'c0d1p0',  'c1d0p2s0',  and even the obsolete '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 'c0d0p1s0', and then
     searched for in /dev.  Bootdev can only be translated  to  a
     device  for  the  first controller, and only if the disks on
     that controller are numbered without  "gaps".   (The  master
     device  on  the  second IDE channel is always d2 on MINIX 3.
     The BIOS will call it disk 0,  1,  or  2  depending  on  the
     number of disks on the first IDE channel.)

     Controller numbers are meaningless to the  BIOS,  so  every-
     thing  is  assumed  to be attached to controller 0.  You can
     omit c0 for device names, and it is best to always  omit  c0
     for  the  boot  command, and to always use the full name for
     variables passed to MINIX 3.


EXTENSIONS

     A few extensions have been made to this program  for  kernel
     hackers.  They may be triggered by setting bits in the flags
     word in the kernel startup code (the mpx  file.)   The  flag
     bits are:

     0x0001    Call kernel in 386 mode.

     0x0002    Do not make space for the bss areas  of  processes
               other than the kernel.

     0x0004    Use the stack size set by chmem(1).

     0x0008    Load MM, FS, etc. into extended memory.

     0x0010    No need to patch process sizes into the kernel.

     0x0020    The kernel can return to the monitor  on  halt  or
               reboot.

     0x0040    Offer generic BIOS support instead of just INT  13
               (disk I/O).

     0x0080    Pass  memory  lists  for  free  and  used   memory
               (processes).

     0x0100    Kernel returns monitor code on  shutdown  in  boot
               parameters array.


SEE ALSO

     controller(4),    installboot(8),     usage(8),     boot(8),
     dosminix(8).


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.

     By redefining leader one can easily  hide  the  identity  of
     this program.


ACKNOWLEDGMENTS

     Earl Chew, for the inspiration  his  ShoeLace  package  pro-
     vided,  unless  he  wants  to  file  a  "look and feel" suit
     against me, then I will say I modeled it after the  Sun  ROM
     boot monitor, which is also true.


AUTHOR

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