Entries in sys_conf.h control many system parameters, and these range from specifying the device drivers that are built into the system to the maximum number of tasks that can be active concurrently. You can easily change the pSOSystem configuration by editing the sys_conf.h file. The sys_conf.h file resides in the application directory. This chapter documents all the system parameters that sys_conf.h controls.
The pSOSystem OS is a scalable operating system, so a large part of its functionality exists in software component building blocks. Not all of the software components are necessarily built into a pSOSystem configuration. This depends on the capabilities you require.
Each software component has its own configuration and startup requirements. By default, the pSOSystem startup code takes care of these requirements. However, because you may want to customize the startup code, this chapter describes configuration and startup elements.
Software components are the basic building blocks of the pSOSystem OS. Each component has an associated configuration table, which the component uses to obtain all of its configurable parameters. Figure 8-1 shows the relationships between the various elements that the components use to find their parameters, data areas, and so on.
The Node Anchor is the single, fixed point of reference for all the installed software components in the system. This anchor is a critical link because each component is code and data position-independent and thus depends on the anchor to locate its configuration information.
In the pSOSystem environment, the global symbol anchor serves as the Node Anchor. An anchor is a pointer to the Node configuration table.
The configuration table portion of the pSOSystem Programmer's Reference describes each configuration table entry. Since the pSOSystem startup code sets up these tables, you do not at first need to understand all table entries. However, as you experiment with changing the pSOSystem configuration, the information becomes more useful.
During system startup, the pSOSystem OS initializes all the required component configuration tables. The code that initializes the configuration tables resides in shared, read-only files in directory PSS_ROOT/configs/std. The source code in these files contains many lines whose compilation depends on values defined in the application's pSOSystem configuration file, sys_conf.h. sys_conf.h determines:
Each of the sample applications supplied with the pSOSystem OS includes a sys_conf.h file that contains configuration values appropriate for that application. Section 8.2, ``sys_conf.h" explains all of the values you must define in sys_conf.h.
Sometimes the only differences between pSOSystem configurations are the values of the parameters defined in sys_conf.h. For this reason, the pSOSystem OS allows you to place some of the sys_conf.h parameter values in a dedicated storage area in the target's memory. An optional startup dialogue can be built into the operating system that allows review and possible modification of these parameters when the pSOSystem OS initializes itself. The pSOSystem Boot ROMs are an example of a pSOSystem OS and application that uses the startup dialog.
This section describes all of the parameters that sys_conf.h must supply. Parameter definitions in sys_conf.h have the form of C macro definitions, as in the following example:
#define SC_PROBE YES /* pROBE+ processor services) */ #define KC_NTASK 20 /* Max. of 20 active tasks */
You may find it helpful to refer to the example sys_conf.h files in the pSOSystem sample applications while reading this section.
To improve the readability of sys_conf.h, macros should be used to define the values of some of the parameters. The code in sysinit.c (and other files that include sys_conf.h) assumes the use of these macros. Therefore, sys_conf.h should contain the macro definitions in the list that follows before any of the parameter values are defined:
#define YES 1 #define NO 0 #define USE_RARP0 #define DBG_SA 1 #define DBG_XS 2 #define DBG_XN 3 #define DBG_AP 4 #define STORAGE 5 #define SYS_CONF6
The following four parameters determine the fashion in which many of the other parameters in sys_conf.h are used:
| PARAMETER | POSSIBLE VALUES |
|---|---|
| SC_SD_PARAMETERS | STORAGE, SYS_CONF |
| SC_STARTUP_DIALOG | NO, YES |
| SC_BOOT_ROM | NO, YES |
| SD_STARTUP_DELAY | any decimal integer |
| SE_DEBUG_MODE | DBG_SA, DBG_XS, DBG_XN, STORAGE, DBG_AP |
The values of all of the parameters in sys_conf.h whose names begin with "SD_" can be determined either by the definitions given in sys_conf.h or by the data in the target's parameter storage area. For example, if SC_SD_PARAMETERS is set to SYS_CONF, the values in sys_conf.h are always used for the SD_ parameter values. If SC_SD_PARAMETERS is STORAGE, then the pSOSystem OS attempts to use the values in the target's parameter storage area for the SD_ variables, and the values in sys_conf.h become default values to use if the parameter storage area has either not been initialized or has been corrupted.
If SC_SD_PARAMETERS is defined as STORAGE, you can enable the startup dialog by setting SC_STARTUP_DIALOG to YES. The startup dialog executes on the target system at startup time and allows you to view and optionally change the parameter values in the storage area. If the dialog is enabled, SD_STARTUP_DELAY specifies the number of seconds the dialog waits for input before it boots the system.
SE_DEBUG_MODE determines how the system operates according to the following possible values:
The following parameters indicate which components are in the system:
A component parameter set to YES causes the component to be built into the system. Note that it is erroneous to set both SC_PSOS and SC_PSOSM to YES.
The target-resident pROBE+ debugger consists of five sub-modules, which you may include in the executable image. To include any of these modules, the system must have the processor services module. To include the processor services module, set SC_PROBE to YES. SC_PROBE_DISASM and SC_PROBE_QUERY are the enables for the disassembler and query services, respectively, and both of these are optional. You should set one or both of SC_PROBE_CIE and SC_PROBE_DEBUG to YES. If you plan to use the pROBE+ debugger in console mode, set SC_PROBE_CIE to YES. If you plan to use the pROBE+ debugger as a back-end for the SpOTLIGHT debugger, set SC_PROBE_DEBUG to YES.
The designation for each serial channel on a target takes the form of the channel number. Channel numbers start at 1. For example, a target with four serial channels would have channel numbers 1, 2, 3, and 4. The following parameters control the serial channels:
| PARAMETER | POSSIBLE VALUES |
|---|---|
| SC_APP_CONSOLE | 1, 2, 3, and so on |
| SD_DEF_BAUD | 4800, 9600, 19200, and so on |
| SC_PROBE_CONSOLE | 1, 2, 3, and so on |
| SC_RBUG_PORT | 0,1,2,3, and so on |
| SC_NumNon_pSOSChan | any integer |
SC_APP_CONSOLE specifies the serial channel number used for the application's console channel. The console channel can be changed dynamically by making a de_cntrl() call to the serial driver.
When the pSOSystem serial driver (drivers/console.c) is called, the minor device number specifies the serial channel to use. For example, if the major device number specified by SC_DEV_SERIAL is 3, a de_write() call to device 3.3 writes the output on serial channel 3. Minor device number 0 is remapped to the application console channel, whose initial value is specified by SC_APP_CONSOLE. (See Section 8.2.7, ``I/O Devices" for a description of SC_DEV_SERIAL and the pSOSystem Programmer's Reference for information on major device numbers.)
SC_DEF_BAUD specifies the default baud rate for the serial channels. A de_cntrl() call can be used to change the baud rate dynamically.
SC_PROBE_CONSOLE specifies the serial channel number that the pROBE+ debugger should use for its console channel. (The pROBE+ console displays output and receives commands.)
SC_RBUG_PORT specifies the serial channel (starting from 1) that should be used if the pROBE+ debugger will communicate with the SpOTLIGHT host debugger over a serial channel.
Note that the value of SC_APP_CONSOLE and SC_RBUG_PORT should not be the same. If the pROBE+ debugger will communicate with the SpOTLIGHT host debugger over a serial channel (specified by SC_RBUG_PORT), it needs the exclusive use of this channel for this purpose. If SC_APP_CONSOLE is set to the same value as SC_RBUG_PORT, then any de_write() or printf() calls made by the application will disrupt the communication between pROBE+ and SpOTLIGHT. If the target board has only one serial channel that must be multiplexed between application output and pROBE+/SpOTLIGHT communication, the application can use the db_output() command to redirect its output to SpOTLIGHT's IN/OUT window.
SC_NumNon_pSOSChan is the number of non-pSOS users of serial channels. These are users that will be initiated before pSOS, such as pROBE+. Note: These channels will not be closed on a soft reset.
The following parameters control the configuration of the LAN interface:
If the target board has a LAN interface, you can enable it by setting SD_LAN1 to YES. If SD_LAN1 is NO, the values of the other SD_LAN1_* parameters are unused.
The following parameters control the configuration of the shared memory network interface:
On systems that support it, you can configure a shared memory network interface (SMNI) for use with the pNA+ network manager and/or a shared memory kernel interface (SMKI) for use with the pSOS+m kernel. In either case, you need to assign a node number to each target board in the system. Node numbers are integers and start at 1. The SD_SM_NODE setting must be the same as the board's node number.
SD_NISM must be either YES or NO. It depends on whether a shared memory network interface is included. If SD_NISM is YES, then SD_NISM_IP, SD_NISM_SUBNET_MASK, and SC_NISM_BUFFS specify the interface's IP address, subnet mask, and number of buffers, just as the corresponding parameters do for the LAN interface.
SD_NISM_DIRADDR is the bus address of a system-wide directory structure which must be accessible to all nodes in the system.
SC_NISM_LEVEL should be set to 2 - with one exception. For the pSOSystem Boot ROMs, it should be 1 to allow a second, downloaded shared memory system to share the same directory structure with the one the Boot ROMs use.
To configure a shared memory kernel interface (SMKI), set SD_KISM to YES and SD_KISM_DIRADDR to the bus address of the system-wide directory structure.
Usually, the directory structures are placed in one of the boards' dual-ported RAM areas. Each pSOSystem board-support package reserves some space for these structures. Refer to Appendix B to find the locations for these structures.
The parameters in the following list do not depend on each other.
| PARAMETER | EXPLANATION |
|---|---|
| SC_RAM_SIZE | Amount of target memory to use (0 for all) |
| SD_DEF_GTWY_IP | IP address of default gateway node(0 for none) |
| SD_VME_BASE_ADDR | VMEbus address of a board's dual-ported RAM |
Normally, the pSOSystem OS uses all of the unassigned memory on a board for dynamic allocation (Region 0). You can override this by setting SC_RAM_SIZE to a nonzero value. If you do, the pSOSystem OS does not touch any memory beyond SC_RAM_SIZE bytes. This is useful when building a Boot ROM because it allows you to make most of the board's RAM available for downloaded code.
SD_DEF_GTWY_IP specifies the default gateway for the pNA+ network manager to use for packet routing. The default gateway is explained in the Boot ROM section of the pSOSystem Programmer's Reference. Note that if SC_PNA is NO, SD_DEF_GTWY_IP is meaningless.
SD_VME_BASE_ADDR specifies the base address of the target board's dual-ported memory on the VMEbus. This parameter is meaningless on non-VME target boards.
The following parameters control the configuration of the I/O devices:
To include a device in the system, you must specify a major device number for it. The major device number determines the device's slot in the pSOS+ I/O switch table. To leave a device driver out of the system, use 0 or NO for the major number.
Note the following:
You should include the following lines in sys_conf.h after the SC_DEV_* definitions:
#define DEV_SERIAL (SC_DEV_SERIAL << 16) #define DEV_TIMER (SC_DEV_TIMER << 16) #define DEV_RAMDISK (SC_DEV_RAMDISK << 16) #define DEV_SCSI (SC_DEV_SCSI << 16) #define DEV_SCSI_TAPE (SC_DEV_SCSI_TAPE << 16) #define DEV_TFTP (SC_DEV_TFTP << 16)
As explained in Section 8.1, ``Overview", the values of many configuration table entries are controlled by #define statements in sys_conf.h. The forthcoming subsections list the parameters that #define statements can control. The configuration tables section of the pSOSystem Programmer's Reference describes these parameters. (Note that the names of the configuration table entries shown in this Programmer's Reference section are in lower-case, and the corresponding sys_conf.h parameters are in upper-case. For example, fc_nbuf in the pHILE+ configuration table is controlled by FC_NBUF in sys_conf.h.)
Although most of the component configuration table entries are determined by sys_conf.h, others are not because sys_conf.h cannot specify them. For example, kc_code in the pSOS+ configuration table contains the starting address of the pSOS+ kernel, but since this is determined by where the linker places the pSOS+ kernel, sys_conf.h cannot specify the address.
The following parameters in sys_conf.h control the values of the corresponding entries in the pSOS+ configuration table:
The following parameters in sys_conf.h control the values of the corresponding entries in the Multiprocessor configuration table:
The following parameters in sys_conf.h control the values of the corresponding entries in the pROBE+ configuration table:
| PARAMETER | EXPLANATION |
|---|---|
| TD_BRKTRAP | Instruction break trap number |
| TD_FLAGS | Initial flag settings |
| TD_DBGPRI | Debugger task priority |
The following parameters in sys_conf.h control the values of the corresponding entries in the pHILE+ configuration table:
The following parameters in sys_conf.h control the values of the corresponding entries in the pREPC+ configuration table:
The following parameters in sys_conf.h control the values of the corresponding entries in the pNA+ configuration table:
The following parameters in sys_conf.h control the values of the corresponding entries in the pSE+ configuration table:
The following parameters in sys_conf.h control the configuration values for TCP/IP OpEN:
The following parameters in sys_conf.h control the allocation of buffers for the General Serial Block buffer manager. These buffers are used by various drivers that use the DISI interface. See the Interfaces and Drivers section of the Programmer's Reference Manual for information on DISI.
A routine called GSblkSetup sets up the Global Serial message and data blocks. GSblkSetup uses the values given for #defines in sys_conf.h in the application directory.
Each application may have a different need for a particular size buffer, The need depends on the size of the message the application sends.
Although the code can use a zero-length block, the serial drivers currently have no use for GS_BUFS_0.
The parameter GS_MBLKS tells GSblkSetup how many message block headers to allocate.
Set GS_MBLKS to the total number of data blocks represented by the total number of buffers allocated in the preceding list. If the driver attaches user-supplied data buffers to a message block header, add an additional amount for these as necessary. For example, the pSOSystem terminal driver needs additional message block headers for user-supplied buffers.
Although the code can use a message block that does not have a data buffer attached to it, the serial drivers currently have no use for a header-only message block.
The following parameters in sys_conf.h control the configuration for Loader. See the System Services section of the Programmer's Reference Manual for more information on Loader.
| PARAMETER | EXPLANATION |
|---|---|
| LD_MAX_LOAD | Maximum number of active loads |
| LD_COFF_MODULE | Load COFF object-load-module |
| LD_SREC_MODULE | Load SREC object-load-module |
The following parameters in sys_conf.h control pMONT configuration.
To add drivers to the pSOS+ I/O driver table, edit drv_conf.c in the working directory. This file contains a function called SetUpDrivers(). SetUpDrivers() calls InstallDriver() to install each driver in the I/O table.
If you want to add a driver, you should add an InstallDriver() call to SetUpDrivers(). The parameters passed to InstallDriver() are the major device number, the pointers to the init, open, close, read, write, and ioctl functions for the driver, and the two reserved entries in the pSOS+ I/O switch table. For example, to add a driver as major device 6 (which may have only init and read calls - just as an example), you would add the following to SetUpDrivers() in sysinit.c:
InstallDriver(6, DriverInit, NULLF, NULLF, DriverRead, NULLF, NULLF, 0, 0);
where NULLF is a macro in sysinit.c defined as a null function pointer.
Network interfaces are added in a manner similar to that of pSOS+ drivers. drv_conf.c also contains a routine called SetUpNi(), which calls InstallNI() to install each network interface in the pNA+ initial interface table. The parameters to InstallNI() are documented in drv_conf.c.
Because the startup code we supply with the pSOSystem OS performs the required initialization and startup, the topics in this section are important only if you modify the pSOSystem startup code or write your own startup code. This section documents the initialization and startup requirements of the individual software components.
The following checklist shows the required items for a typical pSOSystem-based system:
In a ROM-based system, most of these items reside in ROM. For a RAM-based system or a system that is under test or integration, some of the items may be loaded into RAM either by the user's Boot module or the pROBE+ System Debug/Analyzer. Furthermore, in a memory-mapped system especially, it is possible to dynamically load the application tasks or drivers at run time.
Figure 8-2 on page 8-21 shows the possible startup sequences. Typically, power-on or reset passes control to the user- supplied Boot Code, which performs any necessary initialization and self-test. It should also set up the required configuration environment for the software components in the system. The configuration environment consists of the Node Anchor, the Node configuration table, and the other component configuration tables. You can completely set up this environment now or else allow the startup sequence to proceed incrementally. During debug, for example, you might set up the configuration environment just enough to let the pROBE+ debugger take over and execute. If the pROBE+ debugger is present, the Boot Code should pass control to it. The pROBE+ debugger can then be used to download other items on the checklist and start execution of the pSOS+ application. You can start the pSOS+ kernel in one of the following ways:
j START_of_PSOS + 0x40;
Note that this assumes the CPU is in the supervisor state. If this is not the case, you must set the system call vector to point to this pSOS+ startup address and use the syscall instruction to enter it.
Upon entry, pSOS+ startup first uses the Node Anchor to locate the pSOS+ configuration table. The pSOS+ kernel then takes a segment of memory from the beginning of memory Region 0 for its data area. Within this area, it uses the bottom part for its key data structures. The next memory segment goes to the system stack. Above the system stack, the pSOS+ kernel builds the required number of TCBs, QCBs, SCBs, MGBs, TMCBs, and the Object Tables.
Next, the pSOS+ kernel checks the Node configuration table. If other run-time components are present, the pSOS+ kernel locates and automatically calls those components' Startups to allow them to set up and initialize.
The last step in pSOS+ startup is to create and activate the 'IDLE' system daemon task and the user 'ROOT' task. Startup then dispatches ROOT, which takes over and executes.
The pSOS+ kernel treats any error it encounters during startup as a fatal error. For a discussion of fatal error handling, see pSOSystem System Concepts. Startup error codes and their meaning are in Appendix A of the pSOSystem Programmer's Reference.
Copyright © 1996, Integrated Systems, Inc. All rights reserved.
