The User Interface provides several methods for loading and executing a program on the machine. These methods load a file into memory from Ethernet, a hard disk, a floppy disk, or a serial port, and support the execution of Forth, FCode and binary executable programs.
Most of these methods require the file to have a Client program header; see IEEE 1275.1-1994 Standard for Boot (Initialization Configuration) Firmware for a description. This header is similar to the a.out header used by many UNIX systems. Sun's FCode tokenizer generates files with the Client program header.
OpenBoot commands for loading files from various sources are listed in Table 46.
Table 46 File Loading Commands and Extensions
------------------------------------------------------------------------------------------------------------------------
Command Stack Diagram Description ------------------------------------------------------------------------------------------------------------------------
boot [device-specifier] [arguments] ( -- ) Depending on the values of various configuration
variables and the optional arguments, determine the
file and device to be used. Reset the machine, load
the identified program from the identified device,
and execute the program.
byte-load ( addr xt -- ) Interpret FCode beginning at addr. If xt is 1 (the
usual case), use rb@ to read the FCode. Otherwise,
use the access routine whose execution token is xt.
dl ( -- ) Load a Forth source text file over a serial line until
Control-D is detected and then interpret. Using tip
as an example, type:
~C cat filename
Control-D
dlbin ( -- ) Load a binary file over a serial line. Using tip as an
example, type:
~C cat filename
dload filename ( addr -- ) Load the specified file over Ethernet at the given
address.
eval ( ... str len -- ???)Synonym for evaluate.
evaluate ( ... str len -- ???)Interpret Forth source text from the specified string.
go ( -- ) Begin executing a previously-loaded binary
program, or resume executing an interrupted
program.
init-program ( -- ) Prepare machine to execute a binary file.
load [device-specifier] [arguments] ( -- ) Depending on the values of various configuration
variables and the optional arguments, determine the
file and device to be used, and load the identified
program from the identified device.
load-base ( -- addr ) Address at which load places the data it reads from
a device.
?go ( -- ) Execute Forth, FCode or binary programs.
------------------------------------------------------------------------------------------------------------------------
Although boot is normally used to boot the operating system, it can be used to load and execute any client program. Although booting usually happens automatically, the user can also initiate booting from the User Interface.
The boot process is as follows:
boot has the following general format:
-------------------------------------------
boot [device-specifier] [arguments] -------------------------------------------
where device-specifier and arguments are optional. For a complete discussion of the use of the boot command, see "Booting for the Expert User" on page 15.
Forth programs loaded with dl must be ASCII files.
To load a file over the serial line, connect the test system's serial port A to a machine that is able to transfer a file on request (in other words, a server). Start a terminal emulator on the server, and use that terminal emulator to download the file using dl.
The following example assumes the use of the Solaris terminal emulator tip. (See Appendix A, "Setting Up a TIP Connection", for information on this procedure.)
-------------
ok dl -------------
~C
to obtain a command line with which to issue a Solaris command on the server.
Note - The C is case-sensitive and must be capitalized.
Note - tip will only recognize the ~ as a tip command if it is the first character on the command line. If tip fails to recognize the ~C, type Enter in the tip window and repeat ~C.
-------------------------------------
~C (local command) cat filename (Away two seconds) Control-D -------------------------------------
When tip displays a message of the form (Away n seconds), type:
Control-D
in the tip window to signal dl that the end of the file has been reached.
dl then automatically interprets the file, and the ok prompt reappears on the screen of the test system.
The syntax and behavior of load are similar to boot except that the program is only loaded and not executed. load also does not do a machine reset prior to loading as boot may.
The general form of the load command is:
-------------------------------------------
load [device-specifier] [arguments] -------------------------------------------
The parsing of the load command's parameters is affected by the same configuration variables as boot, and load's device-specifier and arguments are identified by the same process. (See "Booting for the Expert User" on page 15 for the details.)
Once the device-specifier and arguments are identified, loading proceeds as follows:
If the list contains more than one entry, an attempt is made to open each listed device, beginning with the first entry, and continuing until the next to last entry. If the system successfully opens a device, that device is closed and is used by load as the device-specifier. If none of these devices can be opened, the last device in the list is used by load as the device-specifier.
FCode or binary programs loaded with dlbin must be Client program header files. dlbin loads the files at the entry point indicated in the Client program header. Link binary files for 4000 (hex). Recent versions of the FCode Tokenizer create a Client program header file with entry point 4000.
To load a file over the serial line, connect the test system's serial port A to a machine that is able to transfer a file on request ( i.e. a server). Start a terminal emulator on the server, and use that terminal emulator to download the file using dlbin.
The following example assumes the use of the Solaris terminal emulator tip. (See Appendix A, "Setting Up a TIP Connection", for information on this procedure.)
----------------
ok dlbin ----------------
~C
to obtain a command line with which to issue a Solaris command on the server.
Note - The C is case-sensitive and must be capitalized.
Note - tip will only recognize the ~ as a tip command if it is the first character on the command line. If tip fails to recognize the ~C, type Enter in the tip window and repeat ~C.
-------------------------------------
~C (local command) cat filename (Away two seconds) -------------------------------------
When tip completes the download, it displays a message of the form (Away n seconds), and the ok prompt reappears on the screen of the test system.
To execute an FCode program, type:
------------------------
ok 4000 1 byte-load ------------------------
To execute the downloaded program, type:
----------
ok go ----------
dload loads files over Ethernet at a specified address, as shown below.
---------------------------
ok 4000 dload filename ---------------------------
In the above example, filename must be relative to the server's root. Use 4000 (hex) as the address for dload input. dload uses the trivial file transfer protocol (TFTP), so the server may need to have its permissions adjusted for this to work.
Forth programs loaded with dload must be ASCII files beginning with the two characters "\ " (backslash and space). To execute the loaded Forth program, type:
------------------------------
ok 4000 file-size @ eval ------------------------------
In the above example, file-size contains the size of the loaded image.
FCode programs loaded with dload must be Client program header files. To execute the loaded FCode program, type:
-----------------------
ok 4000 1 byte-load -----------------------
byte-load is used by OpenBoot to interpret FCode programs on expansion boards such as SBus. The 1 in the example is a specific value of a parameter that specifies the separation between FCode bytes in the general case. Since dload loads into system memory, 1 is the correct spacing.
dload requires binary programs to be in Client program header. Executable binary programs loaded must be either linked to dload's input address (e.g., 4000) or be position independent. To execute the binary program, type:
---------
ok go ---------
To run the program again, type:
----------------------
ok init-program go ----------------------
dload does not use intermediate booters (unlike the boot command). Thus, any symbol information included in the Client program header file is available to the User Interface's symbolic debugging capability. (See Chapter 6, "Debugging" for more information on symbolic debugging.)
Once a program has been loaded into the system, ?go can be used to execute that program regardless of the type of the program.
?go examines the start of the loaded image. If the image begins with the string "\ " (backslash and space), the image is assumed to be Forth text. The Forth interpreter is invoked to interpret the image.
If the image does not start with "\ ", ?go checks the start of the image for the string "CODE". If this string is found, the image is assumed to be FCode.
If the image does not start with "CODE", ?go executes the image as a binary program.
