This chapter contains the following sections:
Transparency Mode
Simulated Input/Output
Setting Up Simulated I/O
Viewing Current Stream Settings
Changing Stream's Properties
Changing the Simulated Input Prompt
Directing I/O to a File
The Simulated I/O Window
Simulated I/O Libraries
Background Mode
Configuration
Entering Background Mode
Leaving Background Mode
The Stack in Background Mode
Local and Global Variables
Refresh Limitation
Assertions
Transparency mode allows you to communicate directly with the execution environment. Most of the time CrossView Pro will handle all the low level communications, freeing you to concentrate on the high level C code. Depending on the type of execution environment, however, you may have to enter transparency mode to set up the execution environment when the machine is first turned on.
To enter transparency mode:
Select the View | Command | Emulator menu item.
All commands entered in the Emulator Command Window are passed directly to the execution environment.
To exit transparency mode:
Select the View | Command | CrossView menu item.
In CrossView Pro, you can pass a string directly to the execution environment without leaving CrossView Pro with the o command:
o map
This passes the command map directly to the execution environment, while you remain in CrossView Pro. Naturally you will have to learn your execution environment's command set to make use of the o command.
FUNCTION: Pass a command to the execution environment.
COMMAND: o string
Do not issue one-shot transparency commands that result
in large output (or otherwise require intervention other than a carriage
return to terminate output). Instead, enter transparency mode first, then
issue the command.
You may also enter transparency mode upon startup with the -T option. See the section on startup options.
CrossView Pro supports RTOS (Real-Time Operating System) aware debugging for various kernels. Since each kernel is different, the RTOS aware features are not implemented in the CrossView Pro executable, but in a library that will be loaded at run-time by CrossView Pro. The amount of windows and dialogs and their contents is kernel dependent.
Within the CrossView Startup dialog (Options | Startup | CrossView) you select the CrossView configuration you will use by selecting a "target configuration file". These target configuration files are normal ASCII text files. The name of the shared library that contains the kernel aware code can be specified in the target configuration. The "radm" configuration item specifies the name of the shared library that contains the kernel aware code.
The syntax of a target configuration file is:
field one of the defined keywords
field-value the value assigned to the field
comment optional comment
Empty lines, lines consisting of only white space are allowed. Comments start at an exclamation-sign ('!') and end at the end of the line.
The line for the shared library that supports RTOS aware code could be:
radm: yourrtos.dll
You can only use this feature if it is supported by the
execution environment (see the addendum).
When the application program is executed as a result of a command such as StepInto or Continue, CrossView Pro traces all memory access, i.e. memory read, memory write and instruction fetch. Through code coverage, executed and not execute areas of the application program can be found. Areas of unexecuted code may exist in case of programming errors or simply dead code which could be eliminated. Alternatively, your program input, your test set, is incomplete. It does not cover all paths in the program. Data coverage allows you to verify which memory locations, i.e. which variables, are accessed during program execution. Additionally, stack and heap usage can be shown.
To enable/disable coverage:
Select the Run | Coverage checked menu item.
When the menu item is checked, coverage is enabled. Select the menu item again to disable coverage.
Type the ce or cd command on the command line:
ce
FUNCTION: Enable coverage.
COMMAND: ce
FUNCTION: Disable coverage.
COMMAND: cd
Two dialogs are present to give you coverage information. The code coverage dialog shows the percentage of executed code within application, module and function scope. Code coverage information can also be displayed in the Source Window. The data coverage dialog shows the data access of HLL variables in the executed program. Data coverage can also be displayed in the Memory Window. The coverage dialogs can be opened via the Debug menu.
You can display code coverage information in the Source Window by clicking on the Display coverage button in the Source Window. In this case an extra column appears to the right of the breakpoint toggles (to the left of the source line). For each source code line that is executed (covered), the source line is marked. The not executed lines are not marked. CrossView Pro has special commands to move the cursor to the next or previous covered or uncovered line:
FUNCTION: Move cursor to next covered line.
COMMAND: nC
FUNCTION: Move cursor to next uncovered line.
COMMAND: nU
FUNCTION: Move cursor to previous covered line.
COMMAND: pC
FUNCTION: Move cursor to previous uncovered line.
COMMAND: pU
You can display data coverage information in the Memory Window by clicking on the Display coverage button in the Memory Window. Besides the current value of memory locations, the memory window also displays whether memory locations have been accessed during program execution. An application program may read from, write to, or fetch an instruction from a memory location. Of course all combinations may be legal. Although writing data to a memory location from which an instruction has been fetched is suspicious. All types of accesss, read, write, fetch or combinations of these, can be shown using different foreground and background colors. The color combination used to show "rwx" access are specified in the Desktop Setup dialog. It is advised to change the background color if instructions are fetched from a memory location, and to change the foreground color to show read and write access.
You can only use this feature if it is supported by the
execution environment (see the addendum).
Profiling allows you to perform timing analysis on your software. Two forms of profiling are implemented in CrossView Pro. Both forms of profiling are fully implemented in the CrossView Pro debugger. You do not have to recompile your source code to enable the profiling features.
Function profiling, also called cumulative profiling, gives timing information about a particular function or set of functions. The time spent in functions called by the function being profiled is included in the timing results. Within the Cumulative Profiling Setup dialog you select one or more functions to be profiled. The gathered profile is shown in the Cumulative Profiling Report dialog. For each function the number of calls, the minimum/maximum/average and total time spent in the function are shown. Also, the relative amount of time consumed by a function in respect to the time consumed by the application is shown.
Function profile data is gathered whenever the program is executed using the Continue command (not single stepped). Function profiling can be supported if the execution environment provides a clock that starts and stops whenever execution starts and stops. Basically function profiling is implemented by using a special type of breakpoint. Breakpoints are inserted at the function entry address and all it's return addressed. Whenever execution stops due to a profile-breakpoint hit, CrossView Pro will read the clock, update the internal profile tables, and restart execution.
To specify the functions to be profiled:
Select the Debug | Cumulative Profiling Setup... menu item.
To view the profiling results:
Select the Debug | Cumulative Profiling Report... menu item.
Code range profiling presents timing information about a consecutive range of program instructions. CrossView Pro displays the time consumed by each statement, C or assembly, in the source window. The timing data can be displayed in three different formats: absolute, relative to program, and relative to function. To change the display format: position the cursor on the profile column and click the right mouse button. Select the appropriate format from the popup menu.
Next to the source window, the profile report dialog shows the time spend in each function. The time consumed by functions called from the function being profiled is not included in the displayed time.
Code range profiling data is gathered whenever the program is executed. It does not matter if the program executes due to a continue, step-over or step-into command. Code range profiling heavily relies on special profiling features in the execution environment. Normally code range profiling is only supported by instruction set simulators.
To enable/disable profiling:
Select the Run | Profiling checked menu item.
When the menu item is checked, code range profiling is enabled. Enabled means that the execution environment starts gathering profiling data. Select the menu item again to disable profiling.
Type the pe or pd command on the command line:
pe
FUNCTION: Enable profiling.
COMMAND: pe
FUNCTION: Disable profiling.
COMMAND: pd
Select the Display profiling button in the Source Window to display profile data in the Source Window. (If profiling is not enabled, clicking the accelerator button also enables the gathering of profiling data.)
Normally both function and code range profiling will
slow down the execution speed of the application being debugged. Therefore,
switch off profiling whenever the timing information is not required.
File system simulation enables the application on the target board to use system calls (such as open, read, write) that are handled by the host system file I/O services. These files can be read directly from the host system, and output can be written to a file on the host system or in a CrossView Pro window. File system simulation is available for all execution environments.
The File System Simulation (FSS) feature addresses I/O to a VIO (Virtual I/O) Window if the filename FSS_windowx is used in the "open" call, x is a number in the range of 0..7.
You can specify a root directory for FSS. If you specify a filename that does not contain an absolute path, CrossView Pro will search for the file in the specified FSS root directory. You can do this in the Virtual I/O Setup dialog, by entering a directory name in the FSS root directory field. This setting is saved in the xvw.ini file. Another possibility is to set a temporary resource by specifying the command line option --fss_root_dir="path" on CrossView Pro startup.
The libraries have been optimized to only attach the file I/O routines if the application actually uses file I/O. This includes the exit() routine, that must close all opened streams before returning to the debugger. The default I/O streams stdin, stdout and stderr are opened on the fly whenever file I/O is used; this behavior is transparent to the user. It is no longer necessary to inform CrossView Pro about the use of any streams.
To redirect the output of a stream to a file use the commands:
For example,
FSS_stdio_open myfile.out,w,1 FSS_stdio_close 1
will redirect stream 1 (output, so w for writable) to the file myfile.out. When done, the second command is used to close the stream.
The functions _read() and _write() of the C library are modified to use File System Simulation. This redirects all high-level I/O calls such as printf() and scanf() type functions through CrossView Pro's FSS feature, allowing you to perform stdin, stdout and stderr I/O by just using these standard C library functions.
For more information see the section C Library Interface Description in the C Cross-Compiler User's Guide.
Simulated I/O allows you to observe the input and output of your program before the hardware is in place. In CrossView Pro, simulated I/O operates through special function calls.
I/O calls in your XA C program like printf() and getchar() call the low-level function _iowrite() and _ioread(). In the distributed C libraries these functions call _simo() and _simi(), respectively. So, all your XA programs support simulated I/O by default. Stream number 0 is for input, for example by getchar(); stream number 1 is for output functions like printf(); stream number 2 is for error messages.
To use simulated I/O, you will need to add two special function calls to your application. The _simi and _simo routines allow CrossView Pro to trap I/O for debugging purposes. The _simi and _simo routines, found in the C library or supplied with CrossView Pro as source code in a module called lib/src/_simio.c, are simple stubs as shown below:
int _simi( unsigned stream, char *port, unsigned len) { return len + stream + *port; /* names used by CrossView Pro */ }
int _simo( unsigned stream, char *port, unsigned len) { return len + stream + *port; /* names used by CrossView Pro */ }
The parameters for this function are:
stream The stream number used to identify the particular I/O.
port The address of the input or output buffer where your program reads or writes its input/output data (the name 'port' is used for historical reasons).
len The length of the input data or size of the output data.
Example:
_simo(OUTPUT_STREAM, outbuf, 80);
OUTPUT_STREAM is the stream number used to identify this I/O; outbuf is the address of the output buffer where your program writes its output data; and 80 is the size of the output buffer. Note that outbuf must always be the same physical buffer. So, copy your data into it before calling _simo.
The _simi call (for simulated input) has a similar form:
_simi(INPUT_STREAM, inbuf, 2)
INPUT_STREAM is the identifying I/O number; inbuf is the address where the input data will be received; and 2 is the size of the input buffer: two bytes.
If you have several I/O routines that you want to simulate, be sure to give each one a different stream number. Valid stream numbers are 0 through 7.
Once your code has been compiled with the appropriate _simi/_simo calls, and CrossView Pro is up and running, you have to define the simulated streams.
You can set up an input or output stream. For input you may specify either a file or the keyboard, for output either a file or the screen. Each stream has its own identifying number. There can be as many as eight streams.
You may also specify the format of the stream's values. The default is character, but you may want to use hexadecimal or octal values when directing data to or from a file.
To set up a simulated I/O stream:
From the menu system:
Enter the sio o or sio i command in the Command Window.
FUNCTION: Create an output stream.
COMMAND: stream sio o {file | screen} [/format]
To set up a simulated output stream, you could type:
1 sio o screen
This creates an output stream number 1 (corresponding to the OUTPUT_STREAM #define in the source). The output is directed to the screen. CrossView Pro automatically assigns the stream a simulated I/O window where the output appears.
To create a simulated input stream, type:
0 sio i screen
FUNCTION: Create an input stream.
COMMAND: stream sio i {file | screen} [/format]
This creates an input stream number 0 (corresponding to the INPUT_STREAM #define in the source), and directs the input from the keyboard while prompted on the screen.
Using the hexadecimal or octal format, CrossView Pro requires
a space between each hexidecimal/octal value as input.
To view the number and types of current streams:
Follow these steps:
Enter the sio command
in the Command Window.
sio stream: 0 screen input format x adr: 0x190 len: 2 stream: 1 screen output adr: 0x140 len: 80
CrossView Pro shows each stream's characteristics: file or screen, input or output, its format, location in memory, and its length (defined in the _simi and _simo calls). Note that the program must run and call a simulated I/O function at least once in order for a stream to have the address and length information displayed.
FUNCTION: View simulated I/O status.
COMMAND: sio
When CrossView Pro requests the simulated input from the keyboard, it displays the prompt and waits for your typed input. If you want, you may also input hexadecimal characters by changing the format of the I/O stream.
To change stream properties:
Delete the previous stream with the sio
d command in the Command Window and create a new stream.
For example, to change stream 0 first, delete the previous stream:
0 sio d
FUNCTION: Delete an I/O stream.
COMMAND: stream sio d
Then create a new stream. For example, to change stream 0 to hexadecimal format:
0 sio i screen /x
Now the values you enter must be hexadecimal numbers. For instance, to enter the ASCII value of `y' you would type:
SIO_input>79
You can specify one of three types of formats: c (character), x (hexadecimal) and o (octal). The default format is character.
Each of the eight simulated I/O streams has a corresponding dedicated buffer. For instance, output stream 1 corresponds to a different buffer than output stream 2. Once a stream corresponds to a buffer, it is always with that buffer. You cannot select a new buffer after the initial call to either _simi or _simo.
The address and size of each simulated I/O stream buffer
is determined the first time a call to either _simi or _simo is made. Thereafter, every call to either _simi or _simo using that stream will use the same buffer size and address as the first call. The buffer size
and address for a stream cannot be changed once it has been initially
set. You have to delete the stream first.
I/O streams that correspond to files instead of the screen also have their buffers set to a fixed size on the first call.
Any output to a buffer that is too small results in truncated output at the limit of the buffer. If 40 characters go to a 20 character buffer, it discards 20 characters. Any input to a buffer that is too small results in limiting the input to the size of the buffer.
To change the prompt for simulated input:
Follow these steps:
Enter the sio p command
in the Command Window.
To change the prompt for the input stream number 0, type:
0 sio p "Enter>"
The quotation marks are not strictly necessary, but they help to distinguish the prompt from other CrossView Pro commands.
FUNCTION: Change prompt of an I/O stream.
COMMAND: stream sio p prompt
For more complicated I/O you may want to direct information to or from a file. Enter the filename in the corresponding edit field of the Simulated I/O Setup dialog box. When you use the keyboard, type the filename after the sio command.
In the demo example, you direct the output stream to file myfile, by typing:
1 sio o myfile
Now CrossView Pro sends the simulated output to the file myfile. Similarly, if you want the information recorded in hexadecimal format, you type:
1 sio o myfile /x
In order for CrossView Pro to close the output file, you must delete the stream:
1 sio d
If the output from the program does not fill the length specified, CrossView Pro fills the additional space with null (zero) values.
Inputting data from a file is an identical process. To input octal data from the file myfile, you type:
0 sio i myfile /o
If you direct simulated I/O to the screen, CrossView Pro displays the output in the Simulated I/O window. Depending on the number of streams, the window shows from one to eight streams at a time.
Similarly, if you direct input from the keyboard; whatever you input appears in the appropriate simulated I/O window.
See chapter Using CrossView Pro for examples of Simulated I/O Windows.
Usually, the functions _ioread() and _iowrite() of the C run-time library, are modified to use _simi() and _simo(). This redirects all high-level I/O calls through CrossView Pro's simulated I/O. In this way you are able to simulate the printf() output and the scanf() input, using the following stream numbers:
0 stdin
1 stdout
2 stderr
This is demonstrated in the file lib/src/_iowrite.c.
For more information see the section C Library Interface Description in the C Cross-Compiler User's Guide.
Background mode is a feature for running the application under debug and CrossView Pro at the same time. This allows you to monitor the target application using CrossView Pro, while the application is running. Depending on the target hardware and/or debug instrument connected to CrossView, target execution can even be real-time.
Since CrossView's monitoring of the target hardware must be non-intrusive, not all functions of the debugger are enabled while running in background mode.
You can only use this feature if it is supported by the
execution environment (see the addendum).
CrossView can be instructed to automatically refresh one or more windows of the debugger periodically while running in background mode. You can use the Background Mode Setup dialog for specifying the desired set of windows to be refreshed.
Use menu item Options|Background Mode Setup... to open the Background Mode Setup dialog.
A distinction has been made between updating the Source
lines window and updating the Disassembly window. Updating the Disassembly window may be to time-consuming, so you may want to disable its updating in Background mode, while still keeping the Source lines window up-to-date when that is displayed on screen.
Use the u command to toggle the
updating of windows in background mode.
FUNCTION: Toggle update of window in background mode.
COMMAND: [interval] u [d|k|r|cd|ck|cr|s|a|mem|t]
The following windows can be updated in background mode:
Initially only the data window will be updated. CrossView Pro repeatedly looks at the execution environment to react on changes. It pseudo-simultaneously looks for user commands from the keyboard (or from the playback file), and periodically it updates the windows.
If all windows would be updated the update frequency would drop. That is why you can toggle a switch for each window. To toggle the updating of the register window, you can type:
xvw% u r
If the switch for a window is 'on', it will be updated, otherwise it will be skipped.
You can also specify a new update interval.
Without arguments, CrossView Pro displays all windows updated periodically plus the update interval.
Notice that simulated I/O is done through 'invisible'
breakpoints, and these must be handled inside the loop. Hence, if updating the windows takes a lot of time (many monitor commands), it will also
slow down simulated I/O.
If you have windows which you do not want to refresh periodically, you can disable them in the Background Mode Setup dialog's refresh list, and refresh these windows manually.
Select the View | Background Mode menu item and select one of the refresh options.
Use the ubgw command.
FUNCTION: Update the appropriate window when the target runs in the background.
COMMAND: ubgw [ s | a | k | r | d | mem | t | all ]]
Section Refresh Limitation in this chapter.
To run a program in background mode:
Select menu item Run|Background Mode|Run in Background.
Type the CB command
on the command line.
FUNCTION: Run a program in background mode.
COMMAND: [count] CB [linenumber]
This will start the application under debug to run continuously (as with the C command), and switch CrossView Pro from Halted to Background Mode. count is assigned to the breakpoint at the current execution position as the number of times to hit this breakpoint before execution to stop. linenumber specifies the source line to place a temporary breakpoint.
The mouse pointer changes to an arrow with a small watch face underneath. This indicates that CrossView Pro is now in background mode. Some commands are treated a little different in this mode, because they can otherwise influence the running program badly. Commands that need information from the stack (like bU, bu, bb or bB) are not allowed because that information is not reliable. Other commands require great care, for example the o command.
For example if you type the g while in background mode you will see:
xvw% g 56 Command "g" is not allowed while the emulator is running in background.
You can leave Background Mode in three ways:
7. Stop the target immediately:
Select menu item Run|Background Mode|Halt Target.
Enter the st command:
xvw% st
8. Let CrossView wait for the target to stop:
Select menu item Run|Background Mode|Wait for Target to Stop.
To wait to come to a breakpoint, you
can use the wt command:
xvw% wt
9. A program running in background mode also stops when it encounters a breakpoint.
FUNCTION: Stop a program in background mode.
COMMAND: st
The wt command behaves just as if you have typed the C command. CrossView Pro returns with a prompt, after the program hits a breakpoint. However, there is an interesting difference with the C command. If you push the Halt button, it returns with the background prompt. The program that runs in the execution environment continues without interruption.
FUNCTION: Wait for the running process to stop
COMMAND: wt
While the execution environment runs in background, CrossView Pro does not allow the use of information that comes from the stack. The reason is that the running program must be stopped in order to get consistent information from the stack. Stopping (and afterwards continuing) the program conflicts with the "real-time" nature of the background mode.
If there is a need for it, you can make a macro that performs the desired operations.
In background mode you can continuously monitor variables. However, realize that local variables (in CrossView Pro variables are called 'local' if they reside on the stack) cannot be monitored. Instead you will see "unknown name". Global variables have a fixed address, so CrossView Pro knows where to get their contents from.
If you are very anxious to see local variables you can first get an address and then use that address to monitor the contents. For example:
$adr_sum = &sum m *(adr_sum)/x4
In this example sum is a long (4 bytes). You must be sure that sum remains at that address while the program is running.
The values you get this way are only valid under specific conditions. Local variables from the function main normally meet these conditions.
While running the application in the background mode, the automatic refresh functionality may not be able to keep up with all the debugging information produced by the running target. Typically, the collected information will be correctly displayed and automatically updated in the current open views and no information will be lost. You might lose the debugging information when scrolling these views during the background mode. The reason is that either CrossView Pro does not run fast enough or the communication with the target hardware is not handled fast enough by the operating system.
The information that cannot be processed by CrossView Pro within the specified update interval, is displayed as either '<unknown>' or dashes. The way the lost information is displayed depends on the internal communication level within CrossView Pro where the information is lost. Information lost during communication with the target hardware is displayed as '<unknown>'. Information lost by CrossView Pro while processing and interpreting this information, is displayed as dashes.
On the next automatic or manual update, all debugging information in the currently open views is automatically updated. All visible '<unknown>' values and dashes are replaced with their actual values as produced by the running target.
CrossView Pro automatically suspends assertions with the CB command.