This chapter helps you gain experience with the pSOSystem operating system (OS). The tutorial in this chapter tells you how to build, download, and execute an executable image. The executable image contains a sample application called HELLO. The HELLO sample resembles the Hello World program familiar to most C programmers. HELLO prints a short message and exits.
The tutorial in this chapter requires a workstation host. For the PC-based pSOSystem tutorial, refer to Chapter 3, ``pSOSystem Tutorial for PCs."
By following the examples in this chapter, you can learn:
This chapter contains explanations and commands you can execute with the following hardware and software:
The examples in this tutorial have target hardware dependencies. To accommodate these dependencies, the pSOSystem environment includes fully operable board-support packages (BSPs) for the CPU boards described in Appendix B, ``Board-Specific Information." This chapter is based on the use of these supported boards because:
If your target is not a supported board, you should try to obtain a supported board for temporary use. The supported boards are widely available, but if you cannot obtain one, you should still read this section then proceed to Chapter 7, ``Understanding and Developing Board-Support Packages".
Before you begin this tutorial, create your own copy of the HELLO sample application code in the working directory. The easiest way to do this is with a copy command that copies an entire directory tree, as the following example shows. Be sure to substitute the pathname of your pSOSystem root directory for PSS_ROOT in this example.
cp -r $PSS_ROOT/apps/hello working_directory cd working_directory
where working_directory is the name of a working directory that does not yet exist. A listing of the working directory contains the following:
The file default.bld provides information to the pRISM builder for building the executable image. Before you start the pRISM Integrated Development Environment (IDE), you must edit default.bld and change it to specify the BSP you plan to use. (This chapter introduces the pRISM editor, but you can use any standard text editor.) In default.bld, locate the following line
:target=PSS_BSP/psosmips.bld
and substitute the full pathname of the BSP you plan to use for PSS_BSP. For example, if the board is an IDT 79S460 and the pSOSystem root directory is /usr/psosmips, you change the line to:
:target=/usr/psosmips/bsps/idt79460/psosmips.bld
The pRISM IDE is an integrated development environment in which you can edit source files and build, download, and debug pSOSystem executable images. For detailed information on the pRISM IDE and SpOTLIGHT debugger, refer to the MULTI Software Development Environment User's Guide and SpOTLIGHT Debug Server User's Manual.
Start the pRISM IDE from within the working directory you just created:
multi &
The pRISM Builder window appears on your screen, as in Figure 2-1.
NOTE: To make the cxx application work on a board with an R4xxx processor, use the deflt_40.bld build file. To make it work on a board with an R3xxx processor, use the default.bld build file.
The root.c file contains the code for the HELLO sample's ROOT task. This code prints a message to the console or SpOTLIGHT In/Out window then suspends itself, which causes the IDLE task to run indefinitely. This section contains directions for examining root.c.To examine root.c, click once on the Edit button in the pRISM Builder window. A file selection window appears as in Figure 2-2.
Next, double-click on root.c (scroll to it if necessary) to select it. The file selection window closes, and an editor window appears as in Figure 2-3.
NOTE: This behavior only occurs if the EDITOR environment variable is not set. If it is set, the Builder brings up the specified text editor.
The editor window includes a scroll bar on its left side. You can use the scroll bar or [PgUp] and [PgDn] on the keyboard to move around the file.
The source code in root.c illustrates some of the basic elements of constructing pSOSystem application code. As you examine the contents of root.c, note the following:
You can click on the SpOTLIGHT Editor's Done button to remove the window from your screen.
If a system has the pSOS+m multiprocessor kernel, you must edit the sys_conf.h file before you build the executable image. You can start the pRISM Editor for this by selecting the Edit button in the pRISM Builder window. In the sys_conf.h file, search for the following two lines:
#define SC_PSOS YES
#define SC_PSOSM NO
Change these lines to show YES for the pSOS+m kernel and NO for the pSOS+ kernel.
You now proceed to building the executable image. In the main pRISM window, select the Build button. A progress window subsequently displays messages while each module compiles. The final message Build completed should appear to indicate that the executable image has finished building.
The executable image contains the HELLO sample application and a pSOSystem OS for the selected hardware.
After the build completes, verify that it made the output files ram.map, ram.elf, and ram.hex. ram.hex contains the executable image in Motorola S-record format. ram.elf is an ELF/Dwarf file of the executable image. ram.map is a map file.
If any errors occurred during the build process, first check to see if you performed the copy commands correctly. If you did, then the installed pRISM tools probably contain a problem. If you cannot locate the problem, contact Integrated Systems Technical Support.
To run the executable image you created in the previous section, you must first download it to the target system. This section describes the download sequence.
The examples in this chapter depend on the use of the pSOSystem Boot ROMs, although the pSOSystem OS itself does not require them. The Boot ROMs rely on the pROBE+ debugger for loading and other services (see Chapter 1, ``Introduction to the pSOSystem Environment"). Boot ROMs can operate the pROBE+ debugger in the following modes:
This chapter demonstrates each mode. Integrated Systems recommends you perform all the exercises or at least read all the sections.
The target board must connect to an ASCII terminal through an RS-232 connection. A terminal emulation program running on the host is preferable to a dumb terminal because, with a terminal emulator, you can use the same channel to download. If a target board has more than one RS-232 port, refer to Appendix B to determine which port to use.
Set the terminal or emulator characteristics to:
When you power up or reset the board, the terminal should display a message similar to the one in Figure 2-4.
If a message like the one in Figure 2-4 does not appear, check for the following:
If the ROMs still do not operate, contact Integrated Systems Technical Support.
The message in Figure 2-4 shows the default ROM configuration parameters. After the startup message appears, the ROMs wait 60 seconds for keyboard input. If you do not enter a character within this period, the ROMs proceed to operate with the current configuration.
The startup mode in Figure 2-4 shows that the pROBE+ debugger mode is stand-alone, and the startup code has a wait period of 60 seconds. Use this mode and the 60-second wait for now. After the wait period has elapsed, a message similar to the following appears. It indicates that the ROM-PROBE+ debugger is waiting for input:
pROBE+/MIPS PS V3.0.5.b pROBE+/MIPS CE V3.0.5.b pROBE+/MIPS QS V3.0.5.b pROBE+/MIPS DI V3.0.5.b pROBE+>
You can now use ROM-pROBE+ to download the S-record file that contains the executable image ram.hex. The next section explains how.
Appendix B contains installation instructions for the ROMs.
To download the S-record file that contains the executable image, first enter the pROBE+ dl command, as follows:
pROBE+> dl
Next, enter the commands necessary to cause the terminal emulation program to transmit ram.hex over the serial channel. For example, on a UNIX system that uses the cu terminal emulator, you can enter the following command:
~$cat ram.hex
If the download is successful, the pROBE+ debugger should display a message similar to the following (the number of records may vary):
9840 records read pROBE+>
Often, the terminal emulation program misses part or all of this message. If so, you can obtain the results of the most recent download by entering the pROBE+ dl command again with the prev option, as follows:
pROBE+> dl prev 9840 records read
The pROBE+ go command is used to begin (or continue) execution. When you enter go with the start address, the executable image is started by passing control to its start address. An executable image is started by passing control to the image's load address. Consult Appendix B to determine the start address for individual boards.
Once you have the board's start address, enter the command with the start address, as in the following example:
pROBE+> go 80060000
A message similar to the following should appear:
pROBE+/MIPS PS V3.0.5.b pROBE+/MIPS CE V3.0.5.b pROBE+/MIPS QS V3.0.5.b pROBE+/MIPS DI V3.0.5.b pROBE+>
This is the point at which the HELLO sample application can run. Although this message may look similar to the one that appeared when the Boot ROMs started, the message comes from the downloaded pROBE+ debugger rather than the ROM-PROBE+ debugger. The ROM-PROBE+ debugger is no longer functioning and can regain control only if you reset the board.
Like the ROM-PROBE+ debugger, the downloaded pROBE+ debugger is running in stand-alone mode. If the setting for the parameter SE_DEBUG_MODE in sys_conf.h is STORAGE, the downloaded pROBE+ debugger operates in the same mode as the ROM-PROBE+ debugger. This is the default and is usually the most convenient approach. However, the ROM and downloaded pROBE+ debuggers do not need to operate in the same mode. If SE_DEBUG_MODE is set to either DBG_SA, DBG_XS, or DBG_XN, the downloaded debugger operates in the mode specified by the SE_DEBUG_MODE setting regardless of the ROM-PROBE+ operating mode.
The pROBE+ gs command passes control to pSOS+ startup. pSOS+ startup initializes the pSOS+ kernel and any other software components then returns control to the pROBE+ debugger. Enter the gs command:
pROBE+> gs
The register contents subsequently appear similar to those in Figure 2-5.
The pSOS+ kernel is now initialized, and execution of the ROOT task is pending. Since pSOS+ initialization has just finished, two tasks are in the system. You can verify this by entering the pROBE+ qt command:
pROBE+> qt
The task information subsequently appears as in Figure 2-6.
You can use the pROBE+ di command to examine the code that is ready to execute, as follows:
pROBE+> di
Figure 2-7 shows output from the di command (actual output may vary).
As explained previously, the HELLO sample's ROOT task prints a message on the console then suspends itself with a t_suspend() call. Once ROOT is suspended, control passes to the IDLE task since no other tasks are in the system.
Since the IDLE task executes forever, returning control to the pROBE+ debugger when the ROOT task blocks is best. The pROBE+ debugger lets you define a break condition that is triggered when any task makes a specified pSOS+ service call. For example, define a breakpoint on t_suspend() by entering:
pROBE+> db se t_suspend * *
Figure 2-8 shows the output after you define the breakpoint.
Now resume execution with the go command. Figure 2-9 on page 2-15 shows the subsequent HELLO output.
Note that ROOT is about to suspend itself.
This concludes the demonstration of the pROBE+ stand-alone mode.
You can restart the HELLO sample application without downloading by entering the gs command. The terminal displays the output shown in Figure 2-10.
You can then continue by entering the go command. The HELLO sample output appears as in Figure 2-11. Note that gs did not clear the break condition on t_suspend(), so you did not need to re-enter the break command.
This concludes the HELLO demonstration with the ROM-PROBE+ debugger and downloaded pROBE+ debugger in stand-alone mode.
This section describes how to run the HELLO sample by using the SpOTLIGHT debug server connected to the target over a serial channel. In this section, both the ROM-PROBE+ debugger and downloaded pROBE+ debugger operate in remote mode talking to the SpOTLIGHT debug server over a serial channel. As explained previously, the operating modes of the ROM-PROBE+ debugger and downloaded pROBE+ debugger do not need to be the same, but in most cases they are.
To assign a serial port, set the SC_RBUG_PORT variable in the sys_conf.h file to the port number you plan to use for debugging the target application using SpOTLIGHT. This setting should not be the same as the SC_APP_CONSOLE value.
NOTE: Refer to Chapter 8, ``Configuration and Startup", for detailed descriptions of SC_RBUG_PORT and SC_APP_CONSOLE.
For both single-channel and multi-channel boards, the directives in this section apply for changing the printing method.
Some of the boards the pSOSystem OS supports have only a single serial channel. If the communication between the SpOTLIGHT debug server and the pROBE+ debugger takes place on a single channel, then neither a pSOS+ serial driver nor the HELLO sample application can use the channel. To resolve this conflict, the pROBE+ debugger provides the service call db_output(). When called by the application code, db_output() sends text to the SpOTLIGHT In/Out window. To use db_output(), you first need to change a line in the root.c file. In root.c, look for the following:
#define OUTPUT_TO_DEBUGGER 0
The preceding line causes the ROOT task to use the standard pSOSystem device driver for output.
To configure the ROOT task to use db_output(), change the 0 to a 1 in the preceding definition, as follows:
#define OUTPUT_TO_DEBUGGER 1
When a system has a single serial channel, OUTPUT_TO_DEBUGGER must be 1. For this tutorial, change the preceding line as instructed whether or not you have a single serial channel.
You now need to modify the sys_conf.h file with a text editor. Because debugging takes place from the host debugger, the pSOSystem environment must include the pROBE+ RBUG module. To add this module to the downloaded system, change the following statement in the sys_conf.h file:
#define SC_PROBE_DEBUG NO
#define SC_PROBE_DEBUG YES
After you have made the changes that preceding sections describe, rebuild the executable image by clicking on Build in the pRISM Builder.
To reconfigure the ROMs so they communicate with the SpOTLIGHT debug server, reset the target CPU board then enter a character before the specified time elapses. A message similar to the following appears:
(M)odify any of this or (C)ontinue? [m]
Enter an m. A message similar to the following should appear:
For each of the following questions, press <Return> to keep the
value in braces, or you can enter a new value.
How should the board boot? 1. pROBE+ standalone mode 2. pROBE+ waiting for host debugger via serial 3. pROBE+ waiting for host debugger via network 4. Run the TFTP bootloader which one do you want? [1]
Since the intention now is to use the SpOTLIGHT debug server over a serial channel, enter a 2.
The remaining parameters do not need changing, so you can answer each of the remaining questions by pressing [Return] until the following question appears:
How long (in seconds) should CPU delay before starting up? [60]
Since you now understand how to use the ROMs after a reset, 60 seconds is unnecessarily long. Enter a more suitable value, such as 3. You should then see a display similar to the one in Figure 2-12.
If a terminal emulator is running, exit it now because the next section requires the use of the SpOTLIGHT debug server, and this requires the use of the serial channel. NOTE: Resetting a board does not cause the ROMs to revert to their default configuration. Furthermore, since configuration data is stored in battery-backed or non-volatile RAM when available, powering down a board causes a return to default values only if the board lacks non-volatile storage capability.
The pRISM IDE communicates with the target system through the SpOTLIGHT debug server, which oversees the target's communication. (For a detailed description of the SpOTLIGHT debug server and SpOTLIGHT debug client, refer to the SpOTLIGHT Debug Server User's Manual.)
To invoke the SpOTLIGHT debug server, do the following:
remote spotlight -c s[device]
where device is the device name of the serial channel you use to communicate with the target system.
Now that the pRISM IDE is communicating with the target system, you load the symbol information into the pRISM IDE and load the executable image onto the target system. In the debugger's command subwindow, enter the command load to begin downloading the executable image.
If you plan to use the SpOTLIGHT debug server over a serial channel often, refer to Section 2.10, ``Changing the Baud Rate," for a description of how to increase the baud rate beyond the default 9600.
Note the following:
Your next step is to pass control to the operating system in the executable image. The next section explains this process.
The SpOTLIGHT debug server has a special command called osboot to pass control to the operating system in the executable image. The osboot command causes the SpOTLIGHT debug server to do the following:
osboot
The osboot command will use the start address in the executable as the OS start address.
After you enter osboot in the source level debugger window, the following message appears after its execution finishes:
OSBOOT completed
This message indicates that the downloaded operating system has successfully started and the downloaded pROBE+ debugger has connected to the SpOTLIGHT debug server.
Start the pSOS+ kernel by entering:
gs
The gs command passes control to pSOS+ startup in the same way as the pROBE+ gs command. A message similar to the following should appear in the debugger command window:
pSOS+ initialized Running: `ROOT' -#00020000
Note that the source code in root.c now appears in the SpOTLIGHT debugger window. The first source line of procedure root is highlighted to indicate that its execution is pending.
You can now request a break condition when the ROOT task makes a t_suspend() call. To do this with the SpOTLIGHT debugger, enter the following in the debugger window:
db se t_suspend * *
Output similar to that in Figure 2-14 appears in the command subwindow.
pSOS+ initialized Running: `ROOT' -#00020000 db se t_suspend * * SERVICE_BREAK____SERVICE________BY_TASK____PARAMETER____ 0 T_SUSPEND ***ANY*** Task: ANY ---------------------------------------------------------------------------------
Now, run the application by clicking on the go button. A message similar to the following appears:
Service breakpoint #0 Running: `ROOT' -#00020000
Before this message appears, the SpOTLIGHT In/Out window should have displayed the message from the HELLO sample:
Hello, world
This concludes the demonstration of the SpOTLIGHT debug server over a serial channel. If you want to experiment further, restart the HELLO sample by entering the gs command.
This section describes how to run the HELLO sample by using the SpOTLIGHT debug server over an Ethernet connection. The exercises in this section require the pNA+ network manager in the system.
To use Ethernet, the target and host must connect over Ethernet. Many users make this connection by adding the target system to the office network, but some do it with a private network.
Before you proceed, the file sys_conf.h requires editing. Because communication takes place over Ethernet, the pSOSystem environment must include the pNA+. network manager. To include the pNA+ network manager, change the following statement in sys_conf.h.:
#define SC_PNA NO to #define SC_PNA YES
In sys_conf.h you could also change the pROBE+ operating mode to Remote Debugger Over a Network, add an Ethernet interface, and assign an IP address to the Ethernet interface. However, as long as SC_SD_PARAMETERS is set to STORAGE, the downloaded system uses the same settings as the pSOSystem ROMs, so you don't need to change these parameters in sys_conf.h. (Section 2.8.5, ``Reconfiguring the ROMs," describes changes to the ROM parameters.)
Recall that when the pROBE+ debugger runs in stand-alone mode, the HELLO sample output goes to the standard pSOSystem console. When you connected the SpOTLIGHT debug server to the serial channel, you had to change the HELLO sample source code to use the db_output() routine. To do this, you changed OUTPUT_TO_DEBUGGER in root.c. Now that the SpOTLIGHT debug server is to connect over Ethernet for this part of the tutorial, either method of output works. To use the pSOSystem console driver, connect a terminal to the serial channel to see the output.
Rebuild the executable image by selecting Build in the pRISM window.
The steps in this section are done through an ASCII terminal regardless of the subsequent operating mode of the ROMs.
This section describes how to reconfigure the ROMs to communicate with SpOTLIGHT debug server over Ethernet. To do so, reset the board and enter a character before the time limit expires, then enter an m to modify the configuration parameters.
When the following prompt appears, enter a 3:
How should the board boot?
1. pROBE+ standalone mode 2. pROBE+ waiting for host debugger via serial 3. pROBE+ waiting for host debugger via network 4. Run the TFTP bootloader
Entering a 3 causes a response similar to the following:
NETWORK INTERFACE PARAMETERS: Do you want a LAN interface? [N] y
Enter a y (n would apply to multiprocessor systems wherein some boards communicate through shared memory rather than Ethernet). The next prompt is as follows:
This board's LAN IP address? (0.0.0.0 = RARP)? [999.9.999.9] Enter the IP address of the CPU board with the standard internet dot notation for internet addresses (four numeric fields, each separated by a period).
Answer n to the next two questions because they enable features that are useful only in multiprocessor target systems:
Use a subnet mask for the LAN interface? [N] Do you want a shared memory network interface? [N]
The next question is:
Should there be a default gateway for packet routing? [N]
The usual answer is n unless the target and host systems are on different networks connected through a gateway. If you are not sure about how to answer this, see your system administrator.
This concludes ROM configuration steps for operation over a network. The remaining questions are those you have seen before and can answer as before. The final summary you see after answering all questions resembles the output shown in Figure 2-15.
Enter c to continue. No pROBE+ prompt appears because the pROBE+ debugger is waiting for a connection from the SpOTLIGHT debug server over the network.
Section 2.7, ``Using the SpOTLIGHT Debugger Over a Serial Channel," shows how to invoke the SpOTLIGHT debug server for use over a serial channel. Invoking the SpOTLIGHT debug server for use over Ethernet is similar except that you enter the following on the command line:
spotlight -c u[target]
where target is the host name or IP address of the target system.
From this point forward, the SpOTLIGHT debugger operates exactly as described in Section 2.7.8, ``Starting the Downloaded Operating System."
The apps directory contains a number of sample applications other than HELLO. Chapter 4, ``SpOTLIGHT Debugger Tutorial for Workstations," refers to the SpOTLIGHT demo application. The remaining sample applications demonstrate various pSOSystem capabilities. Instructions for using the other sample applications appear in the README file in each sample application directory.
If you are using the SpOTLIGHT debug server over a serial channel, you may want to increase the baud rate of the channel. You can increase it to either 19200 or 38400 baud if the host and target both support the higher rate. You must change the baud rate in several places:
remote spotlight -c s/dev/ttya,19200
Copyright © 1996, Integrated Systems, Inc. All rights reserved.
