December 6, 2002

    bbload is a boot loader for the BRECIS EVM board.  It is 
    normally the first thing executed when the MIPS powers up.

    bbload executes a script and, depending on commands in the script,
    will do one of the following:

    1) copy a kernel image to SDRAM and start the kernel image in SDRAM

    2) will jump to a location, almost always in flash, where
       a kernel image resides which can copy itself to SDRAM.

    To build:
        Insure the $PATH includes the MIPS open-tools provided by BRECIS.

        Do the following command:
        make

        Two binary files are generated:
        bbload      boot loader binary
                    This image should be loaded to the flash location
                    0xbfc00000.  The location 0xbfc00000 is the address
                    the MIPS chip boots from during power up.  The address
                    of the .romtext section found in mips/mips.lk MUST
                    start at this address.

        example-script  Example bbload script which is placed at the
                    flash location 0xbfc10000.  The example script
                    must start with the line:
                    #!/bin/bbload 
                    and should end with the line:
                    #!eof
                    Comments start with '#'.
                    bbload recognizes the following commands:
                    1)  set environment variable to a given value
                        set     name1   value1
                        These environment variables are passed to
                        the kernel image in the following format:
                        envp[0] = "name1=value1"
                        envp[1] = "name2=value2"
                        ...
                        envp[n] = NULL
                    2)  set arguments that are passed to the kernel
                        setargs progname a=xxx yyy c=zzz ...
                        These arguments are passed to the kernel image
                        in the following format:
                        argv[0] = "progname"
                        argv[1] = "a=xxx"
                        argv[2] = "yyy"
                        argv[3] = "c=zzz"
                        ...
                        argv[n] = NULL
                        argc is the count of elements in the argv array.

                    3)  set the program counter for the kernel to something
                        other than the default:
                        setpc address

                        example:
                            setpc bfc20000

                        NOTE: 
                        If no setpc command is in the bbload script,
                        bbload will copy the kernel image from the address,
                        eromtext, to the address, ftext, with length,
                        edata - ftext.  These symbols are found in 
                        mips/mips.lk.
                        
                        If a setpc command is in the bbload script,
                        bbload will not copy the kernel image.
                        bbload will assume the address is the address
                        of a kernel image that will copy itself.
                        The address can be any address and should
                        almost always be a flash address.

        bin         example kernel image
                    This image should be loaded to the flash location
                    determined by the value of eromtext found in
                    mips/mips.lk.  This location currently is set
                    to 0xbfc20000.

                    This kernel image will execute in the SDRAM location
                    determined by the values of ftext found in 
                    mips/mips.lk AND the address of the .text section
                    found in kernel/kernel.lk.  The SDRAM location
                    currently is set to 0x80001000.

                    CAUTION: If bbload is copying the kernel from flash
                    to SDRAM, the value of ftext found in mips/mips.lk
                    AND the address of the .text section found in
                    kernel/kernel.lk must be the same.  If setpc is
                    specified which means bbload is not copying the
                    kernel, the address of the .text section found
                    in the kernel does not have match ftext.

    To test:
                    Load bbload to the correct location in flash.
                    Load bin to the correct location in flash.

                    boot from flash.

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 mips/mips.lk and is
0xbfc00020.  This information is passed as environment variables to the 
kernel image if those environment variables were not set in the bbload script.


    
