$Id: README.vgmflash,v 1.8 2005/05/13 22:11:39 till Exp $ Till Straumann , 3/2002 Using the VGM remote boot loader -------------------------------- The VGM remote boot loader is itself an RTEMS application intended to download other RTEMS applications. RATIONALE: - the VGM SMON firmware doesn't support BOOTP/DHCP, hence all VGM boards would need manual boot parameter configuration stored into NVRAM. - having a dedicated loader would require adding networking support etc. The remote loader is a RTEMS application which can be stored into VGM flash. When started, the loader tries to get the - VGM IP address (mandatory) - IP subnet mask (mandatory) - server address - gateway address - VGM hostname - log server address - boot file name either using the BOOTP protocol or from NVRAM (which option to use by default is also NVRAM configurable). It then tries to download the 'boot file' from the 'server' using either the 'nfs', 'rsh' or the 'tftp' protocol. Common Parameters - - - - - - - - - This section describes a set of parameters/conventions common to all boot methods: path: relative path to the boot file on the server. The path may end in a directory or be empty altogether. In this case, the default filename 'rtems.exe' is appended to the path. hostspec: defines the boot file server. May either be a DNS name (provided that the boot parameters specify a DNS server) or an IP address in standard 'dot-notation'. The hostspec may be missing thus instructing the bootloader to use the default server. The default server is either the BOOTP server ('d' key or BOOTP-enable flag set to 'P' or 'Y' and a key other than 'm' is pressed) or the server stored in NVRAM ('m' key or BOOTP-enable flag set to 'N' and a key other than 'd' is pressed) RSH download - - - - - - - A file name conforming to the syntax rsh-path = [ hostspec, ':' ], '~', user, [ '/', path ]; instructs loader to issue a rsh hostspec -l user cat path command for downloading the image. and are extracted from the BOOTP 'filename' answer. I.e., is relative to 's home directory. Examples: server:~rtems/rtems-4.6.0/bin/rtems.exe ~rtems (* uses file 'rtems.exe' in user 'rtems' home dir *) NFS download - - - - - - - A valid NFS path specifier must conform to the syntax nfs-path = [ server ], ':', remote-path, ':' [ [ '/' ], path ]; server = [ uid, '.', gid, '@' ], [ hostspec ]; uid = digit, { digit }; gid = digit, { digit }; hostspec = dns-name | dot-notation-ip-address; remote-path = '/', exported-path-to-mount; path = file-relative-to-mountpoint; Optionally, the user and group IDs to be used for authentication on the NFS server can be provided (defaults to 0.0). Examples: :/export/rtems:4.6.0/bin/rtems.exe 1024.1024@192.168.2.12:/export/rtems:4.6.0/bin 1111@1111:/export/rtems:4.6.0/bin/rtems-test.exe :/export/rtems: TFTP download - - - - - - - The syntax for a TFTP path specifier is tftp-path = [ '/TFTP/', serverid ], path; serverid = dot-notation-ip-address | 'BOOTP_HOST'; If the '/TFTP/', serverid prefix is missing, the default prefix "/TFTP/BOOTP_HOST" will be used. 'BOOTP_HOST' is substituted by the default server (see 'hostspec' definition above). Note that a DNS name can *not* be used. Note that simple relative lacking any '~' or ':' characters only matches the rule. The loader attempts to use TFTP in such cases. Manual ServerIP / Filename configuration - - - - - - - - - - - - - - - - - - - - - If no filename / server are supplied or if the download fails, the respective parameters may be entered manually at the console. They are interpreted exactly the same way as described above. Manual Configuration - - - - - - - - - - - The loader also supports using manually configured IP addresses etc. which it stores in NVRAM. A programmable flag (also a NVRAM configuration setting) determines whether to use the manual/NVRAM configuration or to obtain a configuration via BOOTP. The "Use BOOTP" flag supports three settings: 'N', 'Y' and 'P': 'N': do not use BOOTP; obtain all settings from NVRAM. 'Y': do not use NVRAM for settings other than the 'Use BOOTP flag' and the 'Autoboot delay' but use BOOTP. 'P': do BOOTP to get all networking parameters but use the 'filename' and 'commandline' stored in NVRAM. This is handy on development platforms. The NVRAM setting of the 'Use BOOTP' flag can be overridden at run-time by hitting the 'm', 'd', and 'p' keys which enforce the behavior described under 'N', 'Y' and 'P', respectively. (In some cases, booting may be refused because of missing NVRAM parameters. It is not possible, for example to override 'Y' with the 'm' key if there are IP configuration parameters missing in NVRAM.) NOTE: The loader maintains its own IP configuration in NVRAM (manual option) which is independent from the SMON 'config'. BURNING THE VGM FLASH --------------------- VGM boards have a restriction on using the onboard flash rom: Only a small range (512k) of physical address space is available for addressing flash devices (0xfff80000 - 0xffffffff) (NOTE: the boot device's [flash or eprom] first 512k may also be addressed at 0xfffe0000-0xfffe7fff)! This address space (i.e. the 0xfff80000-0xffffffff range) must be shared among different devices: - socketed flash/EPROM - boot flash - user flash Different boot loaders (e.g. for vxWorks and for RTEMS) can be programmed into different 512k flash banks. The SMON commands flashAdr() (map a flash range to 0xfff80000...) flashWrite() (write a memory block to flash and verify) flashEraseBlock() (selectively erase blocks) flashNumBlocks() (get # of blocks) flashBlockSize() (get block size) vxboot() are interesting in this context. The vxboot seems to look for a vxWorks bootrom in the first 512k bank. Hence, it makes sense to write the RTEMS loader to any other bank: SMon0> flashBlockSize 2 value = 0x20000 = 131072 We want to erase (and later write the RTEMS loader) to the second bank of the user flash (id 2), hence we start with erasing blocks 4..7 (using the blocksize info of 0x20000==128k and the fact that the window/bank size is 500k = 4 blocks) of the user flash: SMon0> flashWrEn 0 /* enable writing user flash */ SMon0> flashEraseBlock 4 2 /* erase 4th block of user flash */ SMon0> flashEraseBlock 5 2 /* erase 5th block of user flash */ SMon0> flashEraseBlock 6 2 /* ... */ SMon0> flashEraseBlock 7 2 Now, we download the binary image of the loader into RAM: SMon0> load "netboot.flashimg.bin" Received 376944 bytes in 6.0 seconds. loaded img at 10000 SMon0> get the image size (the 'load' command puts the target start- and ending addresses into r5 and r6, respectively): SMon0> r6-r5 value = 0x5C070 = 376944 write the flash... NOTE: DONT use flashCopy() because it erases the _entire_ flash device, not only the destination area! The 0x80000 'offset' parameter directs SMON to write the image to the second 512k bank of user flash (id 2) SMon0> flashWrite 0x80000 r5 r6-r5 2 (NOTE: the registers r5, r6 must not have been tampered with since completion of the 'load' command) ############################################################# NOTE: Programming the flash device has been made much easier by the 'reflash.st' script. 1) Edit the 'reflash.st' script to reflect the correct paths on the server. Optionally, a host IP string may be programmed (ho="xxx.xxx.xxx.xxx";). If this step is omitted, the host IP present in SMON's NVRAM configuration will be used. 2) LoadEB "/reflash.st" "reflash" 3) ExecEB "reflash" This burns the flash and loads all necessary scripts. Beware: 'reflash.st' is reloaded also. Better make sure the correct version (i.e., the one with your local mods) is found. ############################################################# STARTING THE RTEMS LOADER ------------------------- 1) Map flash bank to flash address window (this example uses the second bank as used by the programming example above) and set the PC (location counter) to the resulting address: SMon0> pc=flashAdr(0x80000,2) value = 0xFFF80000 = -524288 2) Clear r5 and r6. This instructs the loader to automatically calculate its own start address and length. Clear r3 and r4 also. (r3 and r4 hold the start and ending addresses of an optional command line string.) SMon0> r5=0; r6=0; r3=0; r4=0 value = 0 3) Make sure the network if's DMA is stopped (THIS IS IMPORTANT) SMon0> netStop 3) fire off SMon0> g 0xfff80000 NOTE: these instructions may be written to a script, e.g. called "rtems" which in turn may be called from the startup script (execEB "rtems") [use indirection to simply switch between different scripts]. See the "smonscript.st" file for details. SMON can also load a script remotely: SMon0> loadEB "smonscript.st" "rtems" Received 557 bytes in 0.0 seconds. New buffer "rtems" @ 0xFFE80410 In the actual startup script (called "startup") I only put one line, vectoring to the "rtems" script: execEB "rtems" this allows for easy switching boot scripts. Note that you might have to remove some of the comments in the example script because it exceeds the SMON script line limits.