PREFACE:
pmon was obtained from the website, www.carmel.com/pmon

The file, README, came from this website.

Numerous changes were made to files and files were added during
the course of normal development.

Please see the file, include/defines.h, and change this file to
customize pmon if necessary.

This code is supplied under the restriction that it may NOT be used
for any purpose other then that covered under the support of the
statement of work for BRECIS associated developments.  All other use
is forbidden. 

    NOTE: The files in the html directory have not been fully updated
    to match this distribution.  Please use the PMON Reference Guide 
    provided instead of the html files since this is more accurate. 



INTRODUCTION:
This file contains a pointer to a pre-built pmon image,
instructions for building pmon, 
instructions for loading a pmon into the BRECIS MSP EVM board, 
instructions for loading a pmon startup script, and
miscellaneous guidelines for pmon.



PRE-BUILT pmon IMAGE:
A pre-built binary image of pmon which can be loaded to flash can
be found in /mnt/cdrom/pmon/pmon/bg/pmon.bin.  Please see the
instructions for loading pmon into the BRECIS MSP EVM board.



INSTRUCTIONS FOR BUILDING pmon:
    Invoke the ./bld script in the top directory to build pmon.

    IMPORTANT: Insure your ${PATH} variable includes the path
               to the mips tools.

    $PMON      in dot.sh points to the topmost pmon directory.

    After the build completes, the pmon/pmon/bg directory will contain
    the finished pmon binaries.  pmon is the elf image.
    pmon.bin is the binary image built using mips-objcopy.



INSTRUCTIONS FOR LOADING pmon INTO THE BRECIS MSP EVM BOARD:
There are two ways to load pmon into the EVM board:
1) using a flash burner, one can place the pmon.bin image into flash.

2) using pmon, one can load a binary file (this binary file could be
   anything, not just executable code) using the following commands:

   a) under pmon, set up the ethernet MAC address and IP address.
      Please reference the authorized ethernet MAC addresses which may
      be found on bar-coded labels on the BRECIS MSP EVM board.
      The following numbers are used as examples.
      PMON> set etheraddr 00:02:d8:00:00:50
      PMON> set ipaddr 172.18.40.55
      PMON> load -B

      pmon should print:
      Downloading from ethernet, ^C to abort

   b) from a host with a tftp client program please send the file
      as binary.  The following example is from Linux:
      tftp 172.18.40.55
      tftp> bin
      tftp> rex 1
      tftp> put pmon.bin 80040000
      Sent 194296 bytes in 0.9 seconds
      tftp> quit

   c) pmon should print:
      Downloading from ethernet, ^C to abort
      Loaded data from 80040000 to 8006f6f7, length 2f6f8 (194296 decimal)
      PMON> 

      NOTE: the load address, 80040000, and the length 2f6f8, CAN be 
            different in your particular case.  Please use your numbers
            in the copy -f -f command below.

   d) To copy pmon.bin to the Chip select 0, flash chip, please do:
      PMON> copy -f -f 80040000 bfc00000 2f6f8

      Since pmon is overwriting the currently, running pmon, the
      following will be printed:
      CAUTION: Overwriting flash from which pmon booted.
      Nothing will be printed during the flash update.
      Please wait 30 seconds for flash to be written.
      If successful, the new pmon will be automatically booted.

   After which, if all is successful, the new pmon will boot up.



INSTRUCTIONS FOR LOADING A pmon STARTUP SCRIPT: 
pmon allows one to define a bootup script of commands to run when pmon
boots.  pmon will automatically look for this script in flash starting
at address 0xbfc70000.  An example pmon script can be found in
/mnt/cdrom/pmon/examples/pmon-script.

pmon, during bootup, internally does the following pmon command:
exec -c bfc70000

Within a script, one can do any commands one can type in
manually.  A script can call another script; the call is a
subroutine call. When the called script finishes, pmon will
continue executing the original script.

To get a script into flash, use the steps outlined above in the
section titled: 
INSTRUCTIONS FOR LOADING pmon INTO THE BRECIS MSP EVM BOARD  

The script should be copied to the address expected by pmon (bfc70000).
Then, when pmon reboots, pmon will automatically execute this script.



USEFUL VARIABLES FOR LOADING 

Environment variables can be set and displayed using the set command.

* etheraddr - This variable specifies the hardware Ethernet address.

* ipaddr    - This variable specifies the Internet Protocol address.

* phyaddr   - This variable specifies the phy address in the format:
              hardware index:phy address
              where hardware index is the index to select the mdc/mdio
              registers and is
              0 for MACA (0xb860000), 
              1 for MACB (0xb8700000), 
              2 for MACC (0xb8900000)
              and phy address is 0 through 31 for the phy number
              used in the mdc register.

* heaptop   - This variable specifies the highest allowable address in
              the heap maintained by the monitor. The default value of 
              this variable is 0x80040000. Once set, the value of this 
              variable should never be lowered.

* hostport  - This variable selects whether ethernet0, ethernet1 or 
              ethernet2 is the host port. ethernet is a valid alias
              for ethernet0.



MISCELLANEOUS GUIDELINES FOR pmon:

The DEFAULT FLASH layout for pmon is as follows:
1) 0xbfc00000 = Beginning of CS0 Flash (where pmon executable is loaded)
2) 0xbfc70000 = Beginning of pmon script
3) 0xbfc80000 = Expected location where a kernel binary might reside
3) 0xbe000000 = Beginning of CS1 Flash

The DEFAULT RAM layout for pmon is as follows:
1) 0x80000200 = Beginning of pmon ram data
2) 0x80040000 = End of pmon ram data, Beginning of the kernel
3) (top of memory) - (length of pmon code) - 0x4000 = Beginning of
   pmon code in ram 

The following are guidelines for kernel placement:
1) The kernel should start at or above 0x80040000
2) pmon services are unavailable to a kernel that uses ram reserved
   for pmon. 
3) pmon avoids using the last 0x4000 of RAM because some kernels
   use this area.

PMON examples DIRECTORY:
There are a collection of examples which come with the pmon
source tree.  Not all of these examples have been tested.
Several use floating point which is not currently available. 
The following examples have been ported and tested:
    game.c
    ledflash.c


Other notes:
A manufacturing record in flash will be used to obtain certain information
include ethernet MAC addresses.  The address of this manufacturing record
is set by the value of FLASH_CONFIG_ADDRESS found in pmon/pmon.lk and is
0xbfc00020.  This information is passed as environment variables to the 
kernel image if those environment variables were not set in the pmon script.
The "-p" option has been added to the copy command telling the copy command
to preserve any manufacturing record found in flash.  The "-F" option has
been added to the copy command telling the copy command to overwrite any
manufacturing record found in flash without asking.  Information in the
manufacturing record is used as a default if not supplied elsewhere; i.e.,
information in the pmon-script overrides information in the manufacturing
info record.


