TOC PREV NEXT INDEX DOC LIST MASTER INDEX


Building a Custom Configuration

The general introduction to using Rational Exec as well as the steps for getting started using one of the board support packages (BSP) provided in the release are in "Getting Started" in the Programming for Rational Exec.

An overview of the configuration components and structures used in building a board support package (BSP) configuration for your target is in Configuration Overview.

This chapter contains the instructions for building a custom BSP and some additional materials of interest in Considerations for TDM.

Building a Custom BSP

Follow these steps either to modify an existing BSP configuration or to create a new one for a specific hardware configuration that is not included in the release.

After completing the configuration of your BSP, you are ready to build, edit, compile and link your test program.

Refer to the "Tutorial" in Programming for Rational Exec for an example.

Considerations for TDM

Create a New BSP

To modify a BSP, or create a new one, you must copy a set of working views to work in.

Use File > New > New BSP to copy a source model.

In the New Board Support Package dialog, click on the Navigator icon at the Source Model field to display the New View - Select New Model dialog. This dialog displays the available source models. The source model that you select can be a supplied BSP that you modify or one of the template BSPs.

Templates

The templates contain the compiler_variant name, board. These templates are a skeletal configurations with null bodies for all the configuration subprograms, and dummy values for the configuration parameters. They serve as a foundation upon which to build a custom board configuration.

Supplied BSP

Use the pull-down menus in the New View - Select New Model dialog to limit the list of models visible.

You have the option to specify a new Destination Base for your new BSPs subsystems.

If you use the default Destination Base, leave this field blank, the models for your new BSP are visible in the File > New > View dialog that you use in the next step.

Create a Working View For Your Application

Use the File > New > View dialog to create a working view for your application. Fill in the view name.

If you specified a value other than the default for Destination Base, your new model.ss is not visible to the Navigator icon of the Model field. You must type the fill path to your new model.ss view.

Configure TDM

The Apex Target Debug Monitor (TDM) runs on the embedded target system and offers the same functions as a typical ROM debug monitor. TDM downloads, reads and writes memory and registers, single steps, and sets and removes breakpoints. TDM communicates with the host-resident debugger through an RS-232 port.

Note: It is invaluable to have the reference manual for your target system's serial controller component (for example, UART/USART) and the for the component that is used for the timer.

You can also run applications without using TDM. This is described in Running an Application Without TDM.

Configuring TDM and getting it working consists of the following steps:

Edit the Configuration Files

The TDM configuration files contain the parameters that enable TDM to run as a stand-alone, bootable program on the target system.

The following sections provide details about each of the configuration parameters. The configuration parameters are target processor dependent.

Implement Serial Support

Note: To assist in writing Init, Get and Put, refer to package V_Tdm_Conf.Serial_Support in v_tdm_conf.2.ada in the example configuration directory. It contains a working version of these routines for real hardware serial ports.

Most serial communication devices are programmed with memory-mapped I/O registers. In order for your serial driver software to work correctly, it must be able to read and write these registers reliably.

The serial device usually requires that register accesses occur as a single memory read or write operation of a particular size and alignment (for example, byte or word). It can also require that accesses occur in some strict sequence and that a certain number of cycles elapse between accesses. Refer to the serial device documentation for specifics.

Examine the serial support package for the provided example BSP configuration to get an idea of the programming techniques that can be used to ensure that the requirements of the hardware are met.

Caching presents another possible pitfall. In order to function correctly, accesses to memory-mapped registers must not be cached. Some boards automatically inhibit caching of these addresses using hardware signals. On other boards it is necessary to explicitly inhibit caching, either by disabling caching when referencing memory-mapped registers or by using the Block Address Translation registers to inhibit caching on the block of memory where the I/O registers reside. In the case of MIPS architecture, for example, unchecked accesses can be made by accessing the device through kseg1.

Develop and test the serial drivers independently before trying to run TDM.

Test Serial Support

Use the following the steps to build a TDM test program. In addition, add statements there to call the routines of V_Tdm_Conf.Serial_Support in v_tdm_conf.2.ada.

First, write code to test Put, by writing out a string of ASCII characters one at a time.

Next, build the TDM program on the host and download it.

Then, disconnect the serial port from the host and connect it directly to a CRT. Finally, start TDM and it should print out the string.

When Put is working, use it to prompt the user for input and call Get to read the input. The easiest test is to echo the input by immediately calling Put.

The only thing left at this point is testing the Control-C interrupt. Call Enable_Get_Interrupt and then go into an infinite loop testing a variable to see if it changes value. When any character is sent to the input port, your interrupt handler should get the interrupt and call a routine to change the value of the variable. Then your program should print out a message like "success".

Compile All Ada Files

Use the GUI or the command line to compile all the Ada files in the current view:

GUI Command
Command Line
Highlight the files to compile in the current view: Compile > Code...
code [options] [program_units | directories |
views | configurations...]

Check and Change the Linker Description File For TDM

Edit the linker description file to meet the needs of your configuration.

The beginning of the default Link.des file:

The MAP option produces a link map that is placed in a file with the same name as the executable but with the extension .map.

The ORIGIN option locates TDM in memory.

The rest of the Link.des file completes the layout of the TDM components.

The linker links TDM so that it references data items from the data_image. This allows TDM to be restarted with out being reloaded. It also permits TDM to be placed in ROM.

For most targets, a similar division of exception handler images allow them to be re-initialized when TDM is reset each time a program is downloaded and run or a program is loaded by the debugger. This means TDM can be put into ROM.

Details of the linker description file are found in the "Linking and Executing Programs" section of the Programming for Rational Exec.

Link the TDM Program

Finally, link the TDM program using the provided Build.script. This produces the file v_tdm_main which is the TDM executable program in VOX format

Note that the Link.des file for TDM specifies the map option. You find the start address of TDM by looking at the Entry line of the map header in the file, v_tdm_main.map.

In this case, we see that the starting address is the symbol __start which has address 020000.

Download TDM

TDM must be downloaded onto the target system. Consult your board documentation for the compatible file formats and facilities available on your board. The sections in Board Specific Download TDM Instructions provide some examples for downloading TDM.

Booting TDM on a PC Target

Rational provides a method for booting a PC target (that has an i386 or later processor). It supports the creation of a bootable floppy that can automatically load and start TDM and optionally, the kernel and applications programs. The method voxboot utilizes the PC's BIOS and DOS for boot support.

Verify That TDM Works

Several things must be verified after TDM is downloaded:

TDM is implemented so that if it receives the two character sequence Del Control-d (0x7F 0x04), it responds with the TDM test message.

Use this test to verify that TDM is working in one of several ways.

Terminal Emulation

Use a terminal emulation program (such as tip) to connect directly to the target with a host serial port. You can then send the Del Control-d sequence from your terminal and have the TDM test message print out on your screen.

The key or key sequence that sends the Del character varies from terminal to terminal. It can be Delete, Rub Out or even Control-Backspace on your terminal.

Refer to your operating system documentation for more information on using tip or to determine if other facilities are available for connecting to the target board from the host.

Connect To The Target Board

Connect a terminal directly to the serial port of the target board and type Del Control-d. The TDM Test Message appears on the screen.

Note: Connecting a terminal to the target board may require a different cable than the one required for connecting the target board to the host.
Create a Program

Create a program that writes Del Control-d (0x7F 0x04) on the host serial port connected to TDM. The program should then read the characters that TDM sends back to the host port and print them on the screen.

Write TDM to ROM

Modify the linker description file Link.des to generate an executable TDM image suitable for writing into ROM. Then TDM begins executing upon CPU reset or power-up.

Instructions are available for changes to the Link.des file for each family of target processors:

Configure the Kernel

Configure the no-tasking kernel and the full kernel with the steps that follow, as they apply.

The no-kernel program is described in The No-Kernel Program.

Configuring the Kernel Services Package

v_krn_srv.1.ada in the krn_conf.ss subsystem contains the kernel services dispatch table, V_Krn_Srv.Krn_Srv_Table. The default version of v_krn_srv.1.ada does not eliminate any services.

Apex provides a tool that allows you to configure-out kernel services that your user program is not using, thereby reducing the size of the kernel.

The tool can be used from the GUI, via Tools > Kernel Services > Configure, or from the command line as apex_create_kernel_interface.

The GUI looks like this:

The GUI can operate in any of three modes, as selected by the radio buttons in the middle of the window, labeled by Service Selection Mode. A description of these three modes follows:

Manually Select Kernel Services

In the this mode, you can choose which sets of kernel services you want removed from the kernel manually. Each selection on the upper left window pane labeled Include These Kernel Services:, selects a group of kernel services to include in the kernel. If a particular button is left not set, indicating that service is not to be included in the kernel, the kernel service table entries associated with that button are removed from the service table, and, in some cases, routines are stubbed out in the kernel.

Compute Basic Kernel Services Required for Above Files (manual additions allowed)

This mode is similar to the first, except that the tool helps you choose which sets of services you can remove from kernel, based on one or more user program VOX files that you have added to the window pane labeled "User Program VOX Files:". The tool figures out the default selections based on which kernel services are used by the given user programs. After the tool has shown you which are the minimal set of services needed, you can include other services that you feel might be needed later by selecting the various features. However, the tool will gray out and not allow you to unselect features that are required by the given user program VOX files unless you first switch back to the Manually Select Kernel Services mode, so that you do not end up with a kernel which will not work with your user programs.

Compute Minimal Kernel Services Required for Above Files (manual additions not allowed)

This mode is, again, similar to the second, except in this case, the tool has removed as many services as possible from the kernel based on the given user program VOX files. The services removed can be outside the group that is selectable via the given switches. In this mode, the tool will gray out all of the kernel service selections, so that you can not select more services to include (due to possible internal conflicts), nor can you deselect services that the tool has chosen to include.

In the Manually Select Kernel Services mode, once you have selected the kernels services to include, you just need to click the OK or Apply button and the tool will generate a v_krn_srv.1.ada file and possibly a v_krn_srv.2.ada file if any kernel stubs were needed.

In Compute Basic Kernel Services mode, you need to add your user program VOX files to the list box, click on the Perform Computation and Update Kernel Services Selections button, select any extra kernel services you want included, then click the OK or Apply button.

In Compute Minimal Kernel Services mode, you need to add your user program VOX files to the list box, click on the Perform Computation and Update Kernel Services Selections button, then click the OK or Apply button.

Recommendations on mode usage

If you are just experimenting with reducing the size of the kernel, and do not have any representative user program VOX files available at the moment, use the Manually Select Kernel Services mode.

If you have development versions of your user program VOX files available, use the Compute Basic Kernel Services Required for Above Files mode.

If you are trying to squeeze every last byte out of the kernel, and you have final (or nearly final) versions of your user programs VOX files available, use the Compute Minimal Kernel Services Required for Above Files mode.

If you inadvertently eliminate a called service that one of your programs has used, the kernel panic exits with the error message: "unsupported/invalid kernel service".

The command line version of the tool, apex_create_kernel_interface works in a similar way to the GUI, except the idea there is that you select services to remove, via command line switches, rather than include them.

apex_create_kernel_interface has the following syntax:

or

or

The first form is analogous to the Manually Select Kernel Services mode in the GUI.

The second form is used to show the switch settings that are derived from the given user program VOX files. This can aid you in determining which switches to set using the first form. The optional -verbose switch will tell you which services were used which caused a particular set of services not to be eliminated.

The third form is analogous to the Compute Minimal Kernel Services mode in the GUI. Using it will produce a minimal kernel services table.

Checking Compatibility of a Kernel with a User Program

In one possible software development scenario, you have configured a kernel that you had felt would be compatible with future releases of the user program. If you want to verify that your assumptions are true, you can use two approaches:

1 . Reconfigure the kernel services using the latest user program VOX file(s) as a basis for elimination of unused services.

2 . Check your current kernel against the latest user program VOX file(s).

Previously in this section, we showed you how to use approach 1. Approach 2 is easier: you can use the GUI tool Tools > Kernel Services > Check Compatibility.

You simply enter the path of your kernel VOX file into the Kernel VOX File: box, then add your user program VOX files above, and hit OK or Apply. The tool will compare the kernel services available in the kernel program VOX file against the services required by the user program VOX files. If conflicts are found, they are reported in the Messages window.

The command line version of this GUI is a variation of the apex_create_kernel_interface command:

Edit the Configuration Files

Note: Changes to the kernel configuration parameters must conform to the target hardware.

In the kernel configuration file, v_krn_conf.2.ada, supply the kernel with a description of the target environment and supply the routines needed by the kernel to interface to the target system.The contents of these files are target-specific.

A Recommended Approach

If you are building your own configuration, a recommended approach is to configure the kernel twice. The first configuration can be a simple kernel using the default timer. If your target has at least 1 MB of RAM at the following address, you can use many of the default memory layout values

68k, PowerPC
address 0 .. 16#FFFFF#
MIPS
address 16#8000_0000# .. 16#800F_FFFF#
RH32
address 0 .. 16#FFFFF#
i386
address 0 .. 16#FFFFF#

After verifying that this kernel works, you can alter the configuration to make it more specific for your hardware, for example, add in support for your specific timer hardware.

While the exact configuration parameters are target-specific, there are some general comments about configuration parameters which may exist for your target.

Startup Table
The default is set up for an 8MB system.
Interrupt Vector Table
Must be kept up to date with TDM
Configuration Table
If you have at least 8MB of RAM in your target, no changes are necessary. For the PowerPC, the second time through, change these parameters to match your system's memory using io_conf.l.ada in board_common.ss.
Initialization Routines
May need to add code to initialize your board upon reset.

V_Start is the starting point of the kernel. Pragma Export associates this routine with the external symbol __start, the default entry point of a Apex linked program.

V_Start provides a place to put any hardware initialization that must occur immediately upon reset. Most applications can put all of their target-specific hardware initialization logic in either V_Immediate_Initialization or V_Hardware_Initialization and require no modification to V_Start. Some hardware environments, however, require specific instant actions after machine reset.

Kernel Configuration Parameters

The parameters specific to your target are found in Kernel Configuration Parameters.

Timer Models for the Rational Exec Microkernel

Part of configuring the Rational Exec Microkernel requires that you supply a timer package called V_Timer_Support. For this package to agree with the Ada.Real_Time package and the implementation of delay statements, it must reflect the constants defined in the Apex_Real_Time_Conf package in the real_time_systems.ss subsystem (see "Configuring the User Library", Chapter 12 of the Runtime Guide). This package specifies the relationship between the Ada representation of time and the underlying hardware support for clock and delay operations. V_Timer_Support always contains a subprogram, called during runtime initialization through the external name V_TIMER_INIT, that should either assure that the package supports the Apex_Real_Time_Conf configuration or reject it by terminating the program. Note that the configuration in Apex_Real_Time_Conf can be changed; it just needs to reflect what the hardware is doing so that the Ada runtime will be able to interpret time correctly.

This section discusses these two timer models and offers some suggestions for the best way to set up timers.

Periodic Timer

A periodic timer is programmed to interrupt at fixed intervals; this interval is called the period of the timer. Depending on the physical hardware, it may be automatically re-armed or need to be programmatically re-armed to generate the next interrupt. If the timer automatically rearms itself, the clock's current time should not lose any accuracy over long periods of time. Some hardware timers offer no choice; they only generate fixed rate interrupts, where the time between interrupts is not programmable. In that case, you are forced to use a periodic timer model.

To comply with the configuration in the Apex_Real_Time_Conf package, the interrupt needs to come in at intervals of

Time_Unit * Time_Units_Per_Hardware_Tick * Hardware_Ticks_Per_Delay_Interrupt

seconds. Either the hardware must be programmed for this interrupt interval, or the Real_Time_Conf configuration should be rejected by terminating the program.

The periodic interrupt is used to maintain a clock with resolution equal to the period of the timer; current time is maintained by simply bumping it by the period for each timer interrupt. On some hardware, this is the most accurate clock that the periodic model can provide, but there are cases where greater resolution can be achieved. The periodic interrupt is often driven by a hardware register that is incremented (or decremented) at some much smaller interval, the hardware tick, generating an interrupt when it reaches a specific value. Some hardware configurations allow this register to be read, providing the number of ticks since the current time was last incremented. This can be used to adjust the accumulated current time to provide a much more accurate clock. However, care must be taken to ensure that the value of this register is synchronized to the interrupt, or clock inaccuracies or even backward jumps can result. For example, if the hardware reloads the count register before the timer interrupt handler can increment the current time, the clock will appear to have jumped backward.

The key advantages to periodic timers are: it's a very simple model, its ISR processing is minimal and it should maintain accurate current time if it automatically re-arms itself. Its major drawback is that it cannot be programmed to have really small delays because of the high interrupt processing overhead.

Ideal Timer

The ideal timer model uses two hardware timers: a periodic timer to maintain long term timer accuracy, and a count-down timer for shorter delays. An example of this kind of hardware support is the built in Time Base and Decrementer, respectively, of the PowerPC 603 and related processors.

The periodic timer is incremented by the hardware at some fixed interval, the tick, usually much smaller than would be feasible for a periodic interrupt. This is then read and used to provide the current time. The tick should be reflected in the definitions in the Real_Time_Conf package:

Tick = Time_Unit * Time_Units_Per_Hardware_Tick

The count-down timer is continually reprogrammed to generate the next timer interrupt. If there are not any outstanding alarms, it is reprogrammed with its highest possible count-down value. This reduces the rate of interrupts. If an alarm needs to occur before the remaining time is counted down, the timer is reprogrammed on the spot. The count-down timer is assumed to be decremented (or incremented) every tick toward some fixed value, typically zero, at which point it generates an interrupt. The Apex time model assumes that there is only one hardware tick interval, so that the periodic timer and count-down timer ticks must be the same.

Since the clock is read directly, and since the hardware count-down timer is programmed to the nearest tick, the resolution of both the Clock function and delay clauses is 1 hardware tick. The Real_Time_Conf package should reflect this:

Hardware_Ticks_Per_Ada_Tick = 1;
Hardware_Ticks_Per_Delay_Interrupt = 1;

The V_Timer_Conf.Init_Interval_Timer should reject configurations where this is not true.

The ideal timer provides for more accurate clocks and delays using much less frequent interrupts. Its key disadvantage is that it's a more complicated model.

The Rational Exec Microkernel has provided both a ideal and periodic timer model as a starting point for you to build your own timer models. You can use these or any other model you choose, as long as it satisfies the V_Timer_Support package specification requirements in the kernel configuration package files, v_krn_conf.1.ada and v_krn_conf.2.ada.

Compile All Ada Files

Use the GUI or the command line to compile all the Ada files in the current view.

GUI Command
Command Line
Highlight the files to compile in the current view: Compile > Code... 
    code [options] [program_units | 
directories |
    views | configurations...]

Check And Change the Linker Description File

Edit the linker description for the kernel to meet the needs of your configuration.

The beginning of the default Link.des file:

The MAP option tells the linker to produce a link map. It is placed in a file with the same name as the executable but with the extension .map appended.

The ORIGIN option tells the linker where the kernel should be located in memory. After you have a final configuration of your kernel, you may want to study the link map to see how much space it uses and then move the kernel to one end of the memory space (or put it into ROM).

The rest of the Link.des file tells the linker to layout the components of the kernel in the order: Text, Const, Data, Data_Image and Bss. The Data_Image group is an copy of the data group. When the kernel starts up, one of the first things it does is copy everything from the data group to the Data_Image group. The linker links the kernel so that it references only data items from the Data_Image. This allows the kernel to be restarted with out being reload. It also permits the kernel to be placed in ROM.

Note: The text group is placed first in the list of groups and that V_Start.O'TEXT is placed first in the text group. This has the effect of putting the kernel's entry point at the origin.

Link the Kernel

Finally, link the kernel program.

No-Tasking Kernel

Link the no-tasking kernel with the following commands from an apex shell in the krn_conf.ss view for your board:

Full Kernel

Link the full kernel using the provided Build.script command. It builds:

These files are kernel executable programs in VOX format.

The Link.des file for the kernel specifies the map option. You can find the start address of the kernel by looking at the ENTRY line of the map header in the file v_krn_main.map.

Download the Kernel

The kernel can be downloaded by the debugger, the GUI File > Download command, or the apex_download command line command.

GUI Command
Command Line
In the krn_conf.ss view for your board: File > Download...

The kernel starts when you run your application program. Both the debugger and apex_download search in the Apex view to find a KERNEL_START switch. This directive provides the starting address of the kernel and both of these Apex tools use this address as the starting address. We recommend that you put this directive into the user library, as discussed in Configure the User Library. The starting address of the kernel is the address of the symbol __start and is also shown at the top of the link map as ENTRY.

The kernel does not need to be reloaded each time a user application is reloaded. The kernel is linked so it can be placed into ROM and it completely re-initializes itself when it is restarted.

Write the Kernel to ROM

The procedure for writing the kernel to ROM is target specific but identical to the procedure used for writing TDM to ROM. Refer to Write TDM to ROM. Make the same changes to the kernel linker options file, and relink the kernel to produce a kernel program image that can be run out of ROM.

For PowerPC, MIPS, M68000 Family, i386 Family, and RH32, the kernel can be configured to begin executing immediately after the target system is reset, just as TDM can.

Change the linker option files to locate the exception procedure handlers in ROM and have the reset exception procedure branch to __start.

For RH32, i386 Family, and MIPS, the kernel configuration library contains an additional routine for starting the kernel from a CPU reset, v_reset.2.ada. This file is identical to the one included in the TDM configuration. To configure the kernel to start upon CPU reset, refer to the changes in the file tdm_link.opt. Make the same changes in your kernel configuration library. Compile v_reset.2.ada and relink the kernel, v_krn_main.

Note: For all systems, if you configure TDM to boot up upon CPU reset, you cannot make this same modification to the kernel.

If you are placing both programs in ROM you must take care not to allow overlaps in the link maps of these programs, just as you do when TDM and the kernel are downloaded into RAM. Make sure to take this into consideration when locating both the read only sections (Text, Const, Data) and the read/write sections (Data, Image and Bss) of TDM and the kernel.

If you want your application to automatically start upon CPU reset and you want the ability to attach the host debugger to your running program at a later time, then place the TDM, kernel and user programs in ROM, configure TDM to boot upon CPU reset and update the following parameters in the Configuration_Table in v_tdm_conf.2.ada:

After TDM installs its exception/interrupt vectors, initializes the UART and does any remaining initialization, it jumps to the kernel's starting address. The kernel does its normal initialization (when started by TDM) and starts the user program. The kernel and user programs replace the exception/interrupt vectors they handle.

Control is only transferred back to TDM when the CPU generates an exception (such as address error) or receives an external interrupt (such as Control-C interrupt) for a vector with a handler in TDM that wasn't replaced by the kernel or user program. Via the Control-C interrupt, the host debugger can sync up with the application at a later time.

Configure the User Library

The user library contains support routines for user programs. Many of the functions in the user library are called implicitly by the compiler-generated code.

The primary focus of configuring the user library is the user task stack sizes and memory management support underlying allocators. The default configuration is sufficient for most applications.

However, some applications that make extensive use of heap storage find that the general algorithms provided in the default configuration are too slow. It is for these applications that Rational provides configuration support. The specific configuration parameters are listed in User Library Configuration Parameters.

The only file that may require changing to configure the user library is v_usr_conf.2.ada. Examine the file and, if acceptable, use the default values. You may want to change the default values for the parameters Main_Task_Stack_Size (default=0x10000) and Default_Task_Stack_Size (default=10240).

During development, user program startup usually occurs under control of the debugger, apex_execute, or File > Run.All of these programs look through the imports and included views to find a KERNEL_START switch. This directive should contain the starting address of the kernel.

When the debugger, apex_execute, or File > Run start the program they always start at the kernel's starting address. The kernel goes through hardware and kernel initialization and then transfers control to the user program by using an address in the KERNEL_START switch.

While debugging the user program, the debugger may need to access symbols for the kernel program. The KERNEL_VOX switch specifies the full path name of the v_krn_main file. The debugger automatically reads symbols from this file. This is necessary to do stack unwinding through kernel frames.

The KERNEL_START and KERNEL_VOX switches are normally kept in the Policy/Switches file in the user library.

To complete the configuration process for the user library, the following tasks must be completed:

Edit the User Configuration File

In this step you change the user configuration file v_usr_conf.2.ada. For many user library configurations, it's unusual for any configuration file changes to be required; the defaults are sufficient for most applications. However, if you do change the file, you must code the view.

The user library configuration parameters are not target processor specific.

Check and Change the Linker Description File

The linker description file in the user library is typically the file that controls linking for the user program.

Edit the linker description file, Link.des, to meet your needs.

The MAP option tells the linker to produce a link map. It is placed in a file with the same name as the executable but with the extension .map appended.

The ORIGIN option tells the linker where the user program is located in memory. If you have a 1 MB system and are configuring things for the first time and have been using the defaults for TDM and the kernel, leave the origin at the default value. After you have spent some time developing your application you may want to fine tune where TDM, the kernel and the user program(s) all fit into memory.

The rest of the Link.des file tells the linker to layout the components of the user program in the order: Text, Const, Data, Data_Image and Bss. The data_image group is a copy of the data group. When the user program starts up, one of the first things it does is copy everything from the data group to the data_image group. The linker links the user program so that it only references data items from the data_image. This way, the user program can be restarted without having to be reloaded. This also means the user program can be put into ROM.

Board Specific Download TDM Instructions

Motorola 1603 VME Board and Motorola 167 VME Board - Serial Download

The Motorola 1603 VME Board has a monitor in PROM that provides a facility for downloading TDM. It recognizes the Motorola s-record3 format. Convert the v_tdm_main file that you built in your user board configuration area to s-record format using the apex_convert or Tools > Convert command:

Now you are ready to download this file to the target. Use a terminal emulation program (such as tip) to connect to the target via a host serial port. Once connected, reset the board (either power-cycle or via the reset button on the board) to initialize the monitor. You should see a series of startup messages as the monitor tests the various parts of the board. Eventually you are presented with the monitor prompt (>).

The following is a sample session for downloading the tdm.s3 file using tip. The comments provide the information for you to modify the steps to fit the terminal emulation program you are using.

At the monitor prompt, type:

This starts the monitor loading program. Now, begin the download of the v_tdm_main.s3 file - for tip, the command sequence is ~> - this causes tip to print out a request for the filename to use:

Enter the following:

The monitor prints out messages as the download progresses. Eventually, you are returned to the monitor prompt.

Start the TDM:

At this point, you should be able to send the test sequence to TDM. This should cause it to print out its test message. Type Del Control-d.

TDM should print out the test message

For PowerPC it is: "Hello from Apex TDM!"

Disconnect from the target. If you are using tip, the sequence ~. breaks the connection.

Now, you can use apex_execute or the debugger to download the kernel and user programs.

IDT 79S381, IDT 79S465 Boards - Serial Download

The IDT 79S381 board has a monitor in PROM that provides a facility for downloading TDM. It recognizes the Motorola 32-bit format called S3. This board's monitor is unusual in that it requires an "optional" S0 (s-zero) Sign-On record. Convert the tdm file that you build in your board configuration area to S3 format using Tools > Convert or the apex_convert command:

Now you are ready to download this file to the target. There are two ways to download to this target: over a serial line, or over ethernet. As ethernet may require more assistance from your network administrator, we show the serial downloading method instead.

Use a terminal emulation program (such as tip) to connect to the target via a host serial port. Once connected, reset the board (either power-cycle or via the reset button on the board) to initialize the monitor. You should see a series of startup messages as the monitor tests the various parts of the board. Eventually you are presented with the monitor prompt <IDT>.

The following is a sample session for downloading the v_tdm_main.s3 file using tip. The comments provide the information for you to modify the steps to fit the terminal emulation program you are using:

At the monitor prompt, type:

This starts the monitor loading from serial port 0 (the console port you are now connected to). Now you should send the v_tdm_main.s3 file down to the target. For this target, using the ~> tip command won't work because it sends the records down too quickly for the target to keep up. Instead, you need to get out of your terminal emulator (~. using tip) and then use the Apex slowcat command, which is provided with the release.

Assume your board is connected to /dev/tty0. Experience has shown that the following command should work correctly. If you fail with this, perhaps because your host is faster than ours, you may want to try increase the number after the -d option, which is the number of milliseconds to delay between sending each record. The -p option tells slowcat to display the download progress.

Once this command has completed successfully, re-enter your terminal emulation program, and hit Return a couple of times to get the monitor prompt. If there is no prompt, the board may be hung waiting for more s-records. This indicates that the file did not download correctly. Try hitting Control-d and beginning again, this time increasing the -delay amount.

If you do get the prompt, type the g command:

If the board crashes, it's likely that the file didn't download correctly. Try the whole process again with a higher -delay amount.

If it didn't crash, you should be able to send the test sequence to TDM. This should cause it to print out its test message. Type Del Control-d.

TDM prints out the test message.

Disconnect from the target (~. in tip).

Now, you can use apex_execute or the debugger to download the kernel and user programs.

Honeywell RH32 PDU - Serial Download

The RH32 has a monitor in the Start Up ROM called the SUROM Monitor. This monitor communicates with the host system through an RS-232 serial line. The SUROM does not have any direct commands for download of executable images. Use a special program called tdm_load to download TDM. Tdm_load performs the download function by reading TDM's executable memory image, represented as a file containing a series of Motorola S-records, and then issuing a sequence of write memory requests

In order to download TDM, you must first convert the TDM executable file into an S-record file, using either the apex_convert or Tools > Convert command:

You also need to add a line to the /etc/remote file in order to condition the serial port, and to set the baud rate. Here is a /etc/remote entry, that uses the b port and to communicate with the remote host pdu:

The remote host description above sets the serial port's baud rate to 19200 baud, which is the baud rate typically used by SUROM, and sets up the line in half duplex mode, which enables local echo of all characters sent from the host.

Now you are ready to download the S-record file down to the target. Use a terminal emulation program (such as tip) to connect to the target vie a host serial port. Once connected, reset the board (either by cycling power to the PDU, or by depressing the Reset button) to initialize the SUROM monitor. You should see a start up message once the SUROM monitor has initialized the board, and a prompt:

Once you determine that the SUROM monitor has properly initialized, you should disconnect your terminal emulation program (enter tilde followed by a period or "~." when using tip) from the board and then issue the tdm_load command as follows:

The environment variable, APEX_PORT, is required; it tells tdm_load the name of the serial port attached to the RH32 PDU. When present, the -v option causes tdm_load to periodically print periods that indicate the download process is proceeding:

Once tdm_load completes with the start address: message, reenter your terminal emulation program and type Del Control-d. TDM should print out the test message:

At this point TDM is up and running. Disconnect your terminal emulation program from the target. You should be able execute or debug programs on the RH32 PDU target system.

Methods For Booting TDM On a PC Target

This section includes two methods for booting TDM on a PC target:

voxboot

The voxboot method makes use of a DOS executable, VOXBOOT.EXE, forms. The executable and its sources can be found in the i386pc view in board_common.ss.

VOXBOOT.EXE is a DOS program that knows how to load vox format executables into memory. For example, the DOS command:

would execute the voxboot program which in turn would load and begin the execution of the TDM program. More than one program can be loaded by voxboot, for example:

loads the three vox executables into memory and then start the first one, TDM in this example (which would presumably start the kernel which would in turn start the hello program).

Note that once voxboot starts the execution of TDM, TDM takes over complete control of the PC, there is no return to DOS. Consequently, no other DOS programs should be running when voxboot is executed.

Making a floppy that automatically starts TDM when the PC is powered-up is very straight-forward:

1 . Format the floppy for DOS. Either use the DOS format command, or from Solaris, use fdformat with the -d option.

2 . Make the floppy bootable for DOS. Use the DOS sys command to install the system tracks and COMMAND.COM on the floppy (this could also have been accomplished with the /S option on the DOS format command).

3 . Copy VOXBOOT.EXE and TDM (and optionally the kernel and applications) to the floppy (you can use Solaris's vol manager or pcfs to accomplish this). Note that the default names for the TDM and kernel executables, v_tdm_main and v_krn_main, exceed DOS's file name length limit, and so they must be given different names, for example, tdm.vox and krn.vox.

4 . Write an AUTOEXEC.BAT script and place it on the floppy. The last (and possibly only) line of the script should be something like:

As voxboot executes it outputs messages to the PC's display indicating what it is loading and where it is loading it. The address that it is using as the start address for the (first) loaded program is also displayed (just before voxboot jumps to that address), for example:

The default TDM configuration for the PC writes a startup message to the PC's display after the serial communications port has been initialized. This message should appear on the same screen as the voxboot output, immediately after voxboot's "starting at entry" message.

Note that the default baud rate for the serial communications channel is 38400 (for the TDM in the i386pc view). If the serial port (COM1) on the PC is connected directly to a Sun workstation then the serial port on the Sun must also be set to 38400. There are several ways to accomplish this; a simple mechanism that is suitable for initial testing is to run a command such as:

which starts a background process that holds the baud rate of the /dev/ttya serial port at 38400 for an hour. (The baud rate for TDM can be changed in V_Tdm_Conf.V_Serial_Support package).

One restriction of the current voxboot implementation is that all loaded programs must reside in the bottom 640KB of memory (the exact locations available for loading are displayed by the voxboot program when it runs).

Write TDM to ROM

Writing TDM to ROM requires changes to the Link.des file. Make the changes to this file for your processor.

PowerPC Target Processors:

1 . Change the ORIGIN to the address where the processor begins executing at start up. This is the reset exception vector, normally at 0fff00100.

2 . Create the program data image group and place it in RAM. Normally, this area is placed after the exception vector table. Copy this image group from ROM to RAM in init_ram in v_tdm_conf.2.ada. The bss group follows the data group in RAM.

3 . Locate the image groups for each of the exception handlers in the processor's exception vector table in the RAM exception vector table which normally starts at 000000000.

These image groups are copied from ROM to RAM the first time in init_ram in v_tdm_conf.2.ada and again each time a reset message is received by TDM. v_reset_tdm in v_tdm_conf.2.ada is executed when the load command is entered in the debugger.

Each exception handler image is created and located in the same way. The Data_Access exception is shown below:

4 . After editing the linker options file, relink to produce a ROM version of TDM.

5 . Use the apex_convert or Tools > Convert command to convert the VOX file produced by the linker to an S-Record file that is readable by your ROM programmer.

6 . Download the S-Records and program TDM ROM according to instructions in your ROM programmer's reference manual.

MIPS Family Target Processors:

All that is necessary is to locate the Text, Const and Data sections in ROM at the starting address of 16#BFC00000# and the Bss and program data image sections into RAM.

1 . Change the ORIGIN to point to the reset exception vector address of 16#BFC00000#.

2 . Add the following line within the OPTIONS section:

3 . Insert a group containing V_Reset to force the inclusion of a reset exception vector that jumps to V_Start.

4 . Locate the Program_Text group above the exception vector locations. To do this, change its FOR USE AT. The line, FOR program_text USE AT *; must be updated, changing the * to an address above the boot exception vectors. For example:

5 . Place the Program_Data_Image group which is read/write in RAM. Change its FOR USE AT. The line:, FOR program_date_image USE AT *;, must be updated, changing the * to a specific address. For example:

6 . Explicitly include the Bss section in the options file so that it is also located in RAM.

7 . After compiling v_reset.2.ada and editing the linker options file, relink to produce a ROM version of TDM.

8 . Use the apex_convert or Tools > Convert command to convert the VOX file produced by the linker to an S-Record file that is readable by your ROM programmer.

9 . Download the S-Records and program TDM ROM according to instructions in your ROM programmer's reference manual.

i386 Family Target Processors:

After a CPU reset, the i386 begins execution at physical address 0FFFFFFF0. package V_Reset in file v_reset.2.ada contains a jump to __start, the entry point for TDM. This package is Withed by package V_Tdm_Main. You add a group definition to the linker options file that locates procedure V_Reset at address 0FFFFFFF0.

You must change the linker options file to place all read-only sections in ROM and to place all read/write sections in RAM.

Modify the example TDM options file as follows:

1 . Change the ORIGIN to point to the beginning of ROM.

The read only groups remain as they are (Program_Text, Program_Const and Program_Data).

2 . Place the Program_Data_Image group which is read/write in RAM. Its FOR USE AT must be changed as follows:

3 . Explicitly include the BSS section in the options file so that it is also located in RAM.

4 . Add the following group definition at the end of the linker options file. This group definition locates the CPU reset jump instructions at address 0FFFFFFF0.

5 . After editing the linker options file, relink to produce a ROM version of TDM.

6 . Use the apex_convert or Tools > Convert command to convert the VOX file produced by the linker to an S-Record file that is readable by your ROM programmer.

7 . Download the S-Records and program TDM ROM according to instructions in your ROM programmer's reference manual.

M68000 Family Target Processors:

1 . Change the ORIGIN to point to the address where you want the TEXT section of TDM to begin in ROM. Reserve 8 bytes for the reset exception vector table. For example, if the ROM area on the board begins at address FFF00000 and address 0 is mapped to the beginning of the ROM area during a CPU reset, the TEXT section of TDM should be located after address FFF00007.

The read only groups that immediately follow the Reset_Const group remain as they are (Program_Text, Program_Const and Program_Data).

2 . Place the Program_Data_Image group which is read/write in RAM. Its FOR USE AT must be changed. The line:

3 . Explicitly include the BSS section in the options file so that it is also located in RAM.

4 . After recompiling v_reset.2.ada and v_tdm_main.2.ada and editing the linker options file, relink to produce a ROM version of TDM.

5 . Use the apex_convert or Tools > Convert command to convert the VOX file produced by the linker to an S-Record file that is readable by your ROM programmer.

6 . Download the S-Records and program TDM ROM according to instructions in your ROM programmer's reference manual.

In order to configure TDM so that it boots up upon CPU reset, you must place it in ROM using the procedure outlined above, with the addition of a few more steps.

7 . You must modify and recompile the files v_reset.2.ada and v_main.2.ada to locate the stack pointer and program counter (exception vectors 0 and 1) at the location in ROM that is mapped to memory address 0 during a CPU reset, ensuring that control transfers to TDM after a reset.

8 . Use an Ada address clause to locate the reset table at the correct address for your target board. The reset exception vector table is declared in package V_Reset in the file v_reset.2.ada. Vector 1, the reset program counter, points to __start.

9 . Change procedure V_Tdm_Main to with in package V_Reset. (The file v_tdm_main.2.ada includes the line, "-- with V_Reset;". Simply uncomment this line.) Many target boards map address 0 to the first location in ROM during a CPU reset. After fetching the stack pointer and program counter from exception vectors 0 and 1, the normal mapping of address 0 to physical memory is restored. For more details refer to the hardware reference manual for your target board.

10 . Uncomment the linker directive INCLUDE V_Reset_Table in the OPTIONS section. This directive generates a reference to V_Reset_Table so that it is included in the link image.

RH32 Target Processors

All that is necessary is to locate the Text, Const and Data sections in ROM at the starting address of 16#00000000# and the Bss and program data image sections into RAM.

1 . Change the ORIGIN to point to the reset exception vector address of 16#00000000#.

2 . Add the following line within the OPTIONS section:

3 . Insert a group containing V_Reset to force the inclusion of a reset exception vector that jumps to V_Start.

4 . Locate the Program_Text group above the exception vector locations. To do this, change its FOR USE AT. The line:

5 . Place the Program_Data_Image group which is read/write in RAM. Its FOR USE AT must be changed. The line FOR program_date_image USE AT *; must be updated, changing the * to a specific address. For example:

6 . Explicitly include the BSS section in the options file so that it is also located in RAM.

7 . After compiling v_reset.2.ada and editing the linker options file, relink to produce a ROM version of TDM.

8 . Use the apex_convert or Tools > Convert command to convert the VOX file produced by the linker to an S-Record file that is readable by your ROM programmer.

9 . Download the S-Records and program TDM ROM according to instructions in your ROM programmer's reference manual.

Running an Application Without TDM

It is possible to run an application without using TDM. However, you must be aware of the following:

TDM can be left in a deployed system for debugging in the field. To do this, follow these steps:

Rational Software Corporation 
http://www.rational.com
support@rational.com
techpubs@rational.com
Copyright © 1993-2002, Rational Software Corporation. All rights reserved.
TOC PREV NEXT INDEX DOC LIST MASTER INDEX TECHNOTES APEX TIPS