Chapter 5 Loading and Executing Programs

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 5-1.

Table 5-1 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.

Using boot

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:

• The machine may be reset if a client program has been executed since the last reset. (The execution of a reset is implementation dependent.)

• A device is selected by parsing the boot command line to determine the boot device and the boot arguments to use. Depending on the form of the boot command, the boot device and/or argument values may be obtained from configuration variables.

• The bootpath and bootargs properties in the /chosen node of the device tree are set with the selected values.

• The selected program is loaded into memory using a protocol that depends on the type of the selected device. For example, a disk boot might read a fixed number of blocks from the beginning of the disk, while a tape boot might read a particular tape file.

• The loaded program is executed. The behavior of the program may be further controlled by the argument string (if any) that was either contained within the selected configuration variable or was passed to the boot command on the command line.

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

Using dl to Load Forth Text Files Over Serial Port A

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

1. At the ok prompt of the test system, type:

   ---

   ok dl
   

   ---

2. In the tip window of the server, type:

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

   ---

3. At the local command prompt, use cat to send the file.

   ---

   ~C (local command) cat filename
   (Away two seconds)
   Control-D 
   

   ---

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

Using load

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 may.boot

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" for the details.)

Once the device-specifier and arguments are identified, loading proceeds as follows:

1. The device-specifier and arguments are saved in the bootpath and bootargs properties, respectively, of the /chosen node.

2. If the device-specifier was obtained from a configuration variable, its value may be a list of devices. If the list contains only a single entry, that entry is used by load as the device-specifier.

   ---

   Note -

   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.

   ---

3. load attempts to open the device specified by device-specifier. If the device cannot be opened, loading is terminated.

4. If the device is successfully opened, the device's load method is invoked to load the specified program from the specified device at the system's default load address.

5. If load is successful, and if the beginning of the loaded image is a valid client program header for the system:

   1. Memory is allocated at the address and of the size specified in that header.

   2. The loaded image is moved from the default load address to the newly allocated memory.

   3. The system is initialized such that a subsequent go command will begin the execution of the loaded program.

Using dlbin to Load FCode or Binary Executables Over Serial Port A

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

1. At the test system's ok prompt, type:

   ---

    
   
   ok dlbin
   

   ---

In the tip window of the server, type:

---

~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, press Return in the tip window and repeat ~C again.

---

1. At the "local command" prompt, use cat to send the file.

   ---

   ~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 

---

Using dload to Load From Ethernet

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

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

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.

Binary Executables

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

Using ?go

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.