

MONITOR(8)                Minix Programmer's Manual                 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


                                                                             1



MONITOR(8)                Minix Programmer's Manual                 MONITOR(8)


               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.


                                                                             2



MONITOR(8)                Minix Programmer's Manual                 MONITOR(8)


          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()


                                                                             3



MONITOR(8)                Minix Programmer's Manual                 MONITOR(8)


          {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


                                                                             4



MONITOR(8)                Minix Programmer's Manual                 MONITOR(8)


          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.





                                                                             5



MONITOR(8)                Minix Programmer's Manual                 MONITOR(8)


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







                                                                             6



MONITOR(8)                Minix Programmer's Manual                 MONITOR(8)


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)




























                                                                             7

