This chapter helps you gain experience with the pSOSystem environment. The tutorial in this chapter tells you how to build, download, and run an executable image. The executable image contains a sample application called hello. The hello sample program resembles the Hello World program familiar to most programmers; hello prints a short message and exits.
The tutorial in this chapter requires a PC running Windows 3.0 or later. For other PC system requirements, see the pRISM Environment for Windows document. For a workstation-based pSOSystem tutorial, refer to Chapter 3, ``pSOSystem Tutorial for PCs."
By following the examples in this chapter, you can learn how to perform the following tasks:
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 could read this chapter and then proceed to Chapter 7, ``Understanding and Developing Board-Support Packages."
Before you begin this tutorial, you should create your own copy of the hello sample application code in a working directory. To do this, start the pRISM command-line interpreter by clicking the command-line icon, as shown in Figure 3-1.
Once you start the pRISM interpreter, you are working in a window that emulates a UNIX environment, similar to the window shown in Figure 3-2.
From the pRISM command-line prompt, enter the following commands:
mkdir c:/workdir cd c:/workdir cp c:/psos/apps/hello* .
where workdir is the name of a working directory created with the mkdir command and psos is the directory where pSOSystem is loaded.
You can enter forward or backward slashes from an interpreter window. The interpreter correctly converts them for DOS as needed.
The working directory contains the following files:
readme drv_conf.c sys_conf.h
default.bld root.c userapp.bld
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 79S465 and the pSOSystem root directory is c:/usr/psosmips, change the line to:
:target=/usr/psosmips/bsps/idt79S465/psosmips.bld
If you plan to use SpOTLIGHT, you can make an additional change to the default.bld file. Locate the following line:
:remote=spotlight -c TARGET_STRING
If you are using serial communication, change the line to:
:remote=spotlight -c s[device]
where device is the device name of the serial channel you use to communicate with the target system. For example:
s/dev/ttya
If you are using Ethernet with User Datagram Protocol (UDP), change the line to:
:remote=spotlight -c u[target]
where target is the host name or the IP address of the target system. For example:
u199.19.199.19
You can also use the pRISM Integrated Development Environment (IDE) to configure the SpOTLIGHT debugger as described in the following sections and in the SpOTLIGHT Debug Server User's Manual.
The pRISM IDE is an integrated development environment where 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 pRISM Integrated Development Environment User's Guide and the 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 shown in Figure
3-3.
The root.c file contains the code for the hello program's ROOT task. This code prints a message to the console or SpOTLIGHT In/Out window, then suspends itself, causing 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 3-4.
Next, double-click on root.c (scroll to it if necessary) to select it. The file selection window closes, and the pRISM editor window appears as shown in Figure 3-5.
The pRISM 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 root.c 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 the pRISM Editor's Done button to remove the window from your screen.
If your 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 lines:
#define SC_PSOS YES #define SC_PSOSM NO
Change these lines to show YES for the pSOS+m kernel, SC_PSOSM, and NO for the pSOS+ kernel, SC_PSOS.
You now proceed to build the executable image. In the pRISM Builder 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 version of pSOSystem for the selected hardware.
After the build completes, verify that it created the following files:
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 may 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 process.
The examples in this chapter depend on the use of the pSOSystem Boot ROMs, although the pSOSystem software does not require them. The Boot ROMs rely on the pROBE+ debugger for loading and other services, as described in 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 ASCII 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, ``Board-Specific Information," to determine which port to use.
Set the terminal or emulator characteristics to the following:
When you power up or reset the board, the terminal should display a pSOSystem startup message similar to the one in Figure 3-6.
If a message like the one in Figure 3-6 does not appear, check for the following:
If the ROMs still do not operate, contact Integrated Systems Technical Support.
The message in Figure 3-6 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 3-6 shows that the pROBE+ debugger mode is standalone, 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 is over, a message similar to the following 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 RD 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.
For additional information about the ROMs, see Appendix B, ``Board-Specific Information."
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 Windows 3.x host you can take the following steps:
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 begins or continues execution. When you enter go with the start address, the executable image is started by passing control to its start address. The start address is the image's load address + 4. To determine the start address for an individual board, see Appendix B, ``Board-Specific Information."
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 appears:
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+>
The RBUG (RD) module does not display after you download the executable image.
This is the point at which the hello sample program 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 standalone 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 (Go Start) command passes control to pSOS+ startup. pSOS+ startup initializes the pSOS+ kernel and any other software components, and then returns control to the pROBE+ debugger. Enter the gs command from the pROBE+ prompt:
pROBE+> gs
The register contents appear as shown in Figure 3-7.
The pSOS+ kernel is now initialized, and execution of the ROOT task is pending. Because pSOS+ initialization has just finished, two tasks are in the system. You can verify this by entering the pROBE+ qt (Query Task) command:
pROBE+> qt
The task information displayed by the pROBE+ qt command is shown in Figure 3-8.
You can use the pROBE+ di (Disassemble Memory) command to examine the code that is ready to execute, as follows:
pROBE+> di
Figure 3-9 shows output from the di command starting at address 06E3C (actual output may vary).
As explained previously, the hello sample program's ROOT task prints a message on the console, and then suspends itself with a t_suspend() call. Once ROOT is suspended, control passes to the IDLE task because no other tasks are in the system.
The IDLE task executes indefinitely; therefore, 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 the db (Define Breakpoint) command with the following syntax:
pROBE+> db se q_send * *
Figure 3-10 shows the DB SE output after you define the breakpoint.
Now resume execution with the go (Start) command. Figure 3-11 shows the subsequent hello output.
Note that ROOT is about to suspend itself.
You can restart the hello sample program without downloading again by entering the gs command. The terminal displays the gs output as shown in Figure 3-12.
You can then continue by entering the go command. The sample go command output appears as in Figure 3-13. Note that gs did not clear the break condition on t_suspend(), so you did not need to re-enter the break command. In this example, the go command displays the same output as shown in Figure 3-11 on page 3-18.
This concludes the hello demonstration with the ROM-PROBE+ debugger and downloaded pROBE+ debugger in standalone mode.
This section describes how to run the hello sample program 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 communicating with 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 usually 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.
Refer to Chapter 8, ``Configuration and Startup", for detailed descriptions of SC_RBUG_PORT and SC_APP_CONSOLE.
For both single-channel and multichannel boards, the directives in this section apply for changing the printing method.
Some of the boards the pSOSystem environment 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, even if you have more than one 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 to #define SC_PROBE_DEBUG YES
After you have made the changes described above, rebuild the executable image by clicking 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 60 seconds 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]
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]
Now that you understand how to use the ROMs after a reset, 60 seconds is unnecessarily long. Enter a more suitable value, such as 3. You then see a ROM startup display similar to the one in Figure 3-14.
If a terminal emulator is running, close it now because the next section requires the use of the SpOTLIGHT debug server, and this requires the use of the serial channel.
Resetting a board does not cause the ROMs to revert to their default configuration. Furthermore, configuration data is stored in battery-backed or nonvolatile RAM when available; therefore, powering down a board causes a return to default values only if the board lacks nonvolatile storage capability.
The pRISM IDE communicates with the target system through the SpOTLIGHT debug server, which oversees the target's communication. You load the SpOTLIGHT debug server through the pRISM Builder Window as shown in Figure 3-15.
To invoke the SpOTLIGHT debugger, do the following:
remote spotlight -c s[device]
where device is the device name of the serial channel (s) you use to communicate (-c) with the target system. For example, for COM1, you enter:
remote spotlight -c sCOM1
click the Remote button in the pRISM Builder window (if you have configured the SpOTLIGHT debug server as indicated in section 3.2.2 on page 3-5).
For a detailed description of the SpOTLIGHT debug server and SpOTLIGHT debug client, refer to the SpOTLIGHT Debug Server User's Manual.
Now that the pRISM IDE is communicating with the target system, you can load the executable image onto the target system. In the Main Debugger Window, shown in Figure 3-16 on page 3-26, 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 3.10, ``Changing the Baud Rate," for a description of how to increase the baud rate beyond the default of 9600 baud.
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:
Enter the following command:
osboot
The osboot command uses the start address in the executable as the OS start address.
When 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 the pSOS+ Go Start command:
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 Define Service Breaks command in the debugger command window:
db se t_suspend * *
Output similar to that in Figure 3-17 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 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 program:
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 program by entering the gs command.
This section describes how to run the hello sample program by using the SpOTLIGHT debug server over an Ethernet connection. The exercises in this section require the pNA+ network manager and your host and target must both be physically connected to an Ethernet network.
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 to #define SC_PROBE_DEBUG YES
Because communication takes place over Ethernet, the pSOSystem environment must include the pNA+ TCP/IP network manager. To add the pNA+ network manager to the downloaded system, 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 3.8.6, ``Reconfiguring the ROMs for Ethernet," describes changes to the ROM parameters.)
Before using an Ethernet connection, verify that your host has one of the supported TCP/IP networking packages installed. For more information, see the SpOTLIGHT Debug Server User's Manual.
Recall that when the pROBE+ debugger runs in standalone mode, the hello 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 connected over Ethernet, 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 from an ASCII terminal regardless of the subsequent operating mode of the ROMs.
This section describes how to reconfigure the ROMs to communicate with a 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 which one do you want? [2]
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 applies to multiprocessor systems where some boards communicate through shared memory rather than Ethernet). The next prompt is similar to the following:
This board's LAN IP address? (0.0.0.0 = RARP)? [999.9.999.9]
Enter the IP address of the CPU board using standard dot notation for internet addresses (four numeric fields, each separated by a period).
Enter an n to the next questions unless your board is using a subnet mask (if you enter a y, you are prompted from the subnet mask):
Use a subnet mask for the LAN interface? [N]
Answer n to the next question because it enables the shared memory network features useful only in multiprocessor target systems:
Do you want a shared memory network interface? [N]
For information on the shared memory, see Chapter 6, ``Shared Memory MultiProcessing Tutorial."
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 how to answer this, see your network administrator.
This concludes the ROM configuration steps for operation over a network. The final summary you see after answering all questions resembles the output shown in Figure 3-18.
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 3.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 in the debugger command window:
remote spotlight -c u[target]
where -c is the SpOTLIGHT communications string option, u indicates Ethernet using User Datagram Protocol (UDP), and target is the host name or IP address of the target system.
replace TARGET_STRING in the default.bld file, as described in Section 3.2.2, ``Configuring SpOTLIGHT," with the following:
u[target]
where target is the host name or IP address of the target system and u indicates Ethernet over User Datagram Protocol (UDP).
From this point forward, the SpOTLIGHT debugger operates exactly as described in Section 3.7.8, ``Starting the Downloaded Operating System."
The apps directory contains a number of sample applications other than hello. Chapter 5, ``SpOTLIGHT Debugger Tutorial for PCs," describes 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. For a detailed list of the contents, see Appendix A, ``pSOSystem Files and Directories."
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.
If you change the baud rate, you must change it in the following places:
remote spotlight -c sCOM1,19200
Copyright © 1996, Integrated Systems, Inc. All rights reserved.
