This chapter contains the following sections:
Introduction
CrossView Pro's Features
Source Level Debugging
How CrossView Pro Works
XA Program Development
Getting Started
Before Starting
Setting Up the Execution Environment
Starting CrossView Pro
CrossView Pro Startup Settings
Configuring CrossView Pro
Loading Symbolic Debug Information
Executing an Application
Debugging an Application
CrossView Pro Output
Exiting CrossView Pro
What You May Have Done Wrong
Building Your Executable
Using EDE
Using the Control Program
Using the Makefile
This chapter highlights many of the features and capabilities of CrossView Pro, including an Introduction to Source Level Debugging and the XA Development Environment.
This chapter also contains the section Getting Started, which shows you how to compile a program to work with the debugger.
CrossView Pro is TASKING's high-level language debugger. CrossView Pro is a real-time, source-level debugger that lets you debug embedded microprocessor systems at your highest level of productivity. Its powerful capabilities include:
This interface uses your host's native windowing system, so that you already know how to open, close and resize windows. With windows you can keep track of information concerning registers, the stack, and variables. CrossView Pro automatically updates each window whenever execution stops.
You have great freedom in designing a suitable display. You can hide and resize the various windows if you choose.
You can enter C expressions, CrossView Pro commands or any combination of the two for CrossView Pro to evaluate. You may also call functions defined in your source code from the command line. Expression evaluation is an ideal way to test subroutines by passing them sample values and checking the results.
Code breakpoints let you halt the program at critical junctures of program execution and observe values of important variables.
You may place data breakpoints to determine when memory addresses are read from, written to, or both. With data breakpoints, you can easily track the use and misuse of variables. Data breakpoints are not supported by all execution environments.
A powerful assertion mechanism lets you catch hard-to-find-errors. An assertion is a command, or series of commands, executed after every line of source code. You may use assertions to test for all sorts of error conditions throughout the entire length of your program.
CrossView Pro has a separate window that displays the most recently executed C statements or machine instructions. This feature uses the execution environment's trace buffer along with symbolic information generated during compilation. This feature is depending on the execution environment.
With FSS you can debug programs before the actual input and output devices are present. Input data from the keyboard or file, or output to a window or a file. You can view the data in several formats, including hexadecimal and character. You can have up to eight separate FSS ports, which can be associated with the screen and displayed in windows.
You may place variables and expressions in the Data window, where CrossView Pro updates their values when execution stops.
With CrossView Pro, you can single step through your code at source level or at assembly level, into or over procedure calls. Running your program one line at a time lets you check variables and program flow.
When a command such as StepInto or Continue executes the application, CrossView Pro traces all memory access, i.e. memory read, memory write and instruction fetch. Through code coverage you can find executed and non-executed areas of the application program. Areas of unexecuted code may exist because of programming errors or because of unnecessary code. It may be that 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, you can see stack and heap usage. The availability of this feature depends on the execution environment.
Profiling allows you to perform timing analysis on your software. Two forms of profiling are implemented in CrossView Pro.
Function profiling, also called cumulative profiling, gives you timing information about a particular function or set of functions. CrossView Pro shows: the number of times a function is called, the time spent in the function, the percentage of time spent in the function, and the minimum/maximum/average time spent in the function. The timing results include the time spent in functions called by the profiled function.
Code range profiling presents timing information about a consecutive range of program instructions. CrossView Pro displays the time consumed by each line (source or disassembly) in the Source Window. Next to this, the Profile Report dialog shows the time spend in each function. The timing results do not include the time consumed in functions called by the profiled function.
The availability of profiling depends on the execution environment. Function profiling can be supported if the execution environment provides a clock that starts and stops whenever execution starts and stops. Code range profiling heavily relies on special profiling features in the execution environment. Normally code range profiling is only supported by instruction set simulators.
Macros let you store and recall complex commands and expressions with a minimal number of keystrokes. You can store macros in a "toolbox", making it possible to execute complex functions with the touch of a mouse button. You can also place macros in command lists of breakpoints and assertions. You can use flow control statements within macros, and macros can call other macros, allowing you to construct arbitrarily complex sequences. Macros can accept multiple parameters, be saved and loaded from files and can even rename existing CrossView Pro commands.
At any time, you can record the commands you type, and optionally their output, to a file. You can also play back files of commands all at once or in a single-step playback mode. These functions are helpful for setting up standardized debugging tests or to save results for later study or comparison.
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.
All the major windows and dialog boxes contain a Help button. Clicking on this button wherever it appears, or pressing the function key F1, opens the CrossView Pro help system at the appropriate section. From this point, you can also access the rest of the help system. The MS-Windows version of CrossView Pro uses the native help system.
CrossView Pro has a comprehensive set of documentation for both new and experienced users. The manual includes an installation guide, description of debugging with CrossView Pro, error messages, and a command reference section. The documentation tries to cover a wide range of expertise, by making few assumptions about the technical experience of the reader.
CrossView Pro is a source level debugger. Source level means that debugging works on the actual C code. Traditional debuggers are symbolic, not source, level. Generally speaking, symbolic debuggers are limited to dealing with global, non-dynamic variables and know nothing of data types. Symbolic debuggers translate global names and global subroutines into addresses. A symbolic debugger usually cannot deal with variables that are placed on the stack, since stack resident data do not have absolute addresses.
CrossView Pro, unlike a symbolic debugger, can deal with global and local variables that are both statically and dynamically allocated variables. Therefore, it can deal with compiled addresses of variables that move around the stack. CrossView Pro knows the compiler's addressing conventions for variables of any type.
All debugging configurations follow a similar pattern. There is a host system where the debugger runs, and a target system (usually an execution environment), where the program being debugged runs. There may also be a probe that can plug into the actual hardware of the embedded system being designed.
CrossView Pro provides a high-level interface between you, the user, working at the host system and a program running at the target system (execution environment). This means that you may issue commands that refer directly to the variables, source files, and line numbers as they appear in the source program. You can do this because CrossView Pro uses symbol information generated during compilation to translate the high-level commands that you type into a series of low level instructions that the target system understands. Using a connection (usually an RS-232 cable or LAN) between the host and target, CrossView Pro finds out information about the state of the target program and then tells the target to perform the requested actions.
A host-target arrangement can perform functions beyond the reach of traditional software-based debuggers. Since the target contains the actual chip, CrossView Pro can observe its operations without interfering. The existence of CrossView Pro and the host is invisible to the target program. This means that the program under debug runs exactly the same as the final program will in a real embedded system (except for real-time situations like timings).
With CrossView Pro, you may also take advantage of any advanced capabilities of your target hardware through emulator mode (transparency mode). In transparency mode you can communicate with the target as if the host system were a terminal directly connected to the target. You can enter and leave transparency mode freely without restarting the debugger or the target system. CrossView Pro therefore does not interfere with the normal operation of the target hardware. Thus the debugger is a powerful accessory to the machine-level debugging that you might do with the target system alone. The transparency mode is not available for all execution environments.
Although it is not necessary to know how CrossView Pro performs its debugging, you may be curious how CrossView Pro works.
Whenever you enter a debugger command, CrossView Pro obtains information from or controls the execution environment by sending appropriate commands over the host-target link. A typical session may go something like this:
1. Highlight initval and click on the Show selected source expression button in the Source Window.
Figure 1-1: Inspect a variable
2. CrossView Pro converts this action into a command. Depending on preferences you have set, the variable is shown in the Data Window or the Expression Evaluation dialog is shown.
3. CrossView Pro consults the symbol table to deduce the type and address of initval. Suppose initval is a variable of type int which lies at absolute location 100.
4. The debugger forms a command asking the target system to read two bytes starting at address 100 (the size of an int equals 2).
5. CrossView Pro then transmits the command to the target system and receives the response.
6. CrossView Pro interprets the response, and for example determines that initval equals 17.
7. CrossView Pro then displays initval=17 since it knows initval's type.
Figure 1-2: CrossView Pro Command Output
This is a simplified example, many CrossView Pro commands require several complex transactions, but all take place without you being aware of them.
The CrossView Pro debugger package is part of a toolchain that provides an environment for modular program development and debugging. The figure below shows the structure of the toolchain. The toolchain contains the following programs:
ccxa The control program which activates the C compiler, assembler, linker and/or locator depending on its input.
cpxa The C++ compiler which translates C++ source into C source suitable for the C compiler. Must be ordered separately.
cxa The XA C compiler. This is a dedicated XA C compiler which translates a C source program into a highly optimized assembly source file, using the XA assembly language specification.
mppxa A string-macro preprocessor allowing macro substitution, file inclusion and conditional assembly, according to the Macro Preprocessor Language syntax specification. It is recommended that you use the internal preprocessor of the assembler asxa. Preprocessor mppxa is supplied for those who need an Intel MPL compatible preprocessor syntax.
asxa The assembler program which produces a relocatable object file from a given assembly file.
lkxa A linker combining objects and object libraries into one relocatable object file.
lcxa A locator that links an arbitrary number of linker output files to one absolute load file in the IEEE Std. 695 debugging connection format. This program can also produce files in the Intel Hex format or Motorola S-record.
arxa A librarian program, which can be used to create and maintain object libraries.
prxa A utility to view the contents of a relocatable object file or an absolute file.
mkxa A program builder which uses a set of dependency rules in a 'makefile' to build only the parts of an application which are out of date.
Figure 1-3: XA development flow
xfwxa The CrossView Pro debugger using XA execution environments.
For a full description of all available utility programs see the chapter Utilities in the XA Cross-Assembler, Linker/Locator, Utilities User's Guide.
Before using CrossView Pro, there are several things that you must do:
For the purpose of getting you started quickly, we have supplied you with a demo program that you can debug. The demo program is demo.abs.
The following text only applies to ROM monitor and emulator versions of CrossView Pro. Within CrossView Pro simulator versions the execution environment is part of the CrossView Pro executable.
In order for the host and execution environment to communicate, a proper connection must exist between the two machines. Here are some important considerations:
To invoke CrossView Pro, simply double-click on its icon. CrossView Pro starts up and opens the command window, source window and other windows.
Figure 1-4: Command Window
CrossView Pro can be passed the name of an execution (*.abs) file. This can be done from a command line, but the native windowing system often provides alternatives. Usually this involves dragging the program to be debugged onto the CrossView Pro executable from the Windows Explorer for Windows 95/98/NT/2000, and dropping it there or associating CrossView Pro to be the application to start when double-clicking an .abs icon. CrossView Pro will start and load the symbol information from that file.
You can specify specific CrossView Pro startup settings in the CrossView Startup dialog.
To open the CrossView Startup dialog:
Figure 1-5: CrossView Pro Startup Settings
You can set the following items in this dialog:
The available targets are described by the target configuration files (*.cfg in the etc subdirectory). The target configuration files are text files and can be edited with any text editor.
Empty lines, lines consisting of only white space are allowed. Comment starts at an exclamation-sign ('!') and ends at the end of the line.
The following configuration items are defined in a target configuration file:
title: title of the configuration file.
cpu_type: cpu type. You can specify multiple cpu types separated by white space.
debug_instrument_module: name of the DLL used for debugging.
ksm_dll_name: name of the DLL used for RTOS aware debugging (optional).
For each target a different set of extensions can be added to this list.
You may have to configure CrossView Pro to talk to the emulator or ROM monitor. If you have a simulator version this step is not needed and the associated menu item is grayed. To configure CrossView Pro:
Figure 1-6: Setting up CrossView Pro Communications
From EDE you can set the communication parameters in
the Settings tab
of the EDE | CrossView Pro Options... menu item.
You must tell CrossView Pro which program that you want to debug. To do this:
CrossView Pro remembers all previously saved settings. In this case, the Load Symbolic Debug Info dialog already contains the previously saved configuration, so you only have to click the Load button to perform your actions.
Figure 1-7: Loading Symbolic Debug Information
To view your source while debugging, the Source Window must be open. To open this window,
Before starting execution you have to reset the target system to its initial state. The program counter, stack pointer and any other registers must be set to their initial value. The easiest way to do this is:
Depending on your execution environment a target system
reset may have undesired side effects. For this reason, the target system
reset is executed before the code is downloaded to the target.
If you have not checked these items:
The first single step executes the startup code and stops at the first line of code in main(). You should see your program's source code.
Another way of getting there is:
To set a breakpoint you can:
Figure 1-8: Getting Control
Now it is time to execute your program:
In the Source Window the current execution position (i.e. the statement at the address identified by the current value of the program counter) is higlighted in blue. As a result, when execution stops, the line you set a breakpoint on is highlighted. You can now single step through your program using the Step Into and Step Over buttons in the Source Window. Or you may choose to execute the rest of the program (or at least until the next breakpoint) with the Run button.
At any point you can interrupt the emulator and regain control by clicking on the Halt button in either the Source Window or the Command Window.
For more information on executing a program, see the chapter Controlling Program Execution.
When debugging your application you probably want to see the calling sequence of your program, and inspect the contents of variables and data structures used within your program.
To see the calling sequence of your program the Stack Window must be open. The stack window shows the functions that are currently on the stack. To open the stack window,
To see the value of the local variables of a function,
Figure 1-9: Watch variables
To inspect the value of global variables and data structures,
Depending on preferences you have set, the variable is shown in the Data Window as shown in figure 1-9 or the dialog displayed in figure 1-10 is shown.
Figure 1-10: Expression evaluation
Pointers, structures and arrays displayed in the data window have a compact and expanded form. The compact form for a structure is just <struct>, while the expanded form shows all the fields. The compact form of a pointer is the value of the pointer, while the expanded form shows the pointed-to object. The compact form is indicated by putting a '+' at the start of the display. (i.e., the object is expandable), while a '-' indicates the expanded form (i.e., the object is contractible). Nesting is supported, so structures within structures can likewise be expanded, ad infinitum.
To expand a pointer, structure or an array:
Nearly every CrossView Pro command can be given using the graphical user interface. These commands and the debugger's response is logged in the Command Output Window which is the upper part of the Command Window. Alternatively, CrossView Pro commands can be entered directly (without using the menu system) in the command edit field of the command window.
To open the Command Window:
Figure 1-11 shows an example of the Command Window. Commands can be typed into the command edit field (bottom field) or selected from the command history list (middle field) and edited then executed. The top field is referred to as the Command Output Window. Each command, echoed from the command edit field, is displayed with a '>' prefix. CrossView's response to the command is displayed below the command.
Figure 1-11: CrossView Pro Command Output
You can change the behavior of the command edit field in the Options | Desktop Setup dialog.
To quit a debugging session:
CrossView Pro will exit immediately. If you selected one or more items in the Save Options dialog your settings will be saved in the initialization file xvw.ini. This file is located in the startup directory.
Most problems in starting up CrossView Pro for a debugging session stem from improperly setting up the execution environment or from an improper connection between the host computer and the execution environment. Some targets will require you to enter transparency mode to set the execution environment for a debugging session. Check the notes for your particular execution environment.
Here are some other common problems:
The subdirectory xvw in the examples subdirectory contains a demo program for the XA toolchain.
In order to debug your programs, you will have to compile, assemble, link and locate them for debugging using the TASKING XA tools. You can do this with one call to the control program or you can use EDE, the Embedded Development Environment (which uses a project file and a makefile) or you can call the makefile from the command line.
EDE stands for "Embedded Development Environment" and is the Windows oriented Integrated Development Environment you can use with your TASKING toolchain to design your application.
To use EDE on the demo program, located in the subdirectory xvw in the examples subdirectory of the XA product tree, follow the steps below.
A detailed description of the process creating the sample program demo.abs is described below. This procedure is outlined as a guide for you to build your own executables for debugging.
The dialog boxes shown in this manual serve as an example. They may slightly differ from the ones in your product.
You can launch EDE by double-clicking on the EDE shortcut on your desktop.
The EDE screen provides you with a menu bar, a ribbon bar (command buttons) and one or more windows (for example, for source files), a status bar and numerous dialog boxes.
EDE supports all the TASKING toolchains. When you first start EDE, the correct toolchain of the product you purchased is selected and displayed in the title of the EDE desktop window.
If you selected the wrong toolchain or if you want to change toolchains do the following:
1. Access the EDE menu and select the Select Toolchain... menu item. This opens the Select Toolchain dialog.
2. Select the toolchain you want. You can do this by clicking on a toolchain in the Toolchains list box and press OK.
If no toolchains are present, use the Browse... or Scan Disk... button to search for a toolchain directory. Use the Browse... button if you know the installation directory of another TASKING product. Use the Scan Disk... button to search for all TASKING products present on a specific drive. Then return to step 2.
Follow these steps to open an existing project:
1. Access the Project menu and select Set Current....
2. Select the project file to open and then click OK. For the demo program select the file demo.pjt, located in the subdirectory xvw in the examples subdirectory of the XA product tree. If you have used the defaults, the file demo.pjt is in the directory c:\cxa\examples\xvw.
The next two steps are not needed for the demo program because the files addone.src and demo.c are already open. To load the file you want to look at:
1. In the Project menu click on Load files....
This opens the Choose Project Files to Edit dialog.
2. Choose the file(s) you want to open by clicking on it. You can select multiple files by pressing the <Ctrl> or <Shift> key while you click on a file. With the <Ctrl> key you can make single selections and with the <Shift> key you can select everything from the first selected file to the file you click on. Then press the OK button.
This launches the file(s) so you can edit it (them).
The next step is to compile the file(s) together with its dependent files so you can debug the application.
Steps 1 and 2 are optional. Follow these steps if you want to specify additional build options such as to stop the build process on errors and to select a command to be executed as foreground or background process.
1. Access the EDE menu and select the Build Options... menu item.
This opens the Build Options dialog.
If you set the Show command line options at the bottom of a tool tab check box EDE shows the command line equivalent of the selected tool option. You can get the same effect when you select the button left from the OK button in a tool options dialog.
2. Make your changes and press the OK button.
3. Select the EDE | Directories menu item and check the directory paths for programs, include files and libraries. You can add your own directories here, separated by semicolons.
4. Access the EDE menu and select the Scan All Dependencies menu item.
5. Click on the Execute 'Make' command button. The following button is the execute Make button which is located in the ribbon bar.
If there are any unsaved files, EDE will ask you in a separate dialog if you want to save them before starting the build.
Once the files have been processed you can inspect the generated messages in the Build tab:
TASKING program builder vx.y rz SN00000001-020 (c) year TASKING, Inc. Assembling addone.src Compiling demo.c Assembling demo.src Linking to demo.out Creating IEEE-695 absolute file demo.abs
Once the files have been compiled, assembled, linked, located and formatted they can be executed by CrossView Pro.
To execute CrossView Pro:
1. Click on the Debug application button. The following button is the Debug application button which is located in the ribbon bar.
CrossView Pro is launched. CrossView Pro will automatically download the compiled file for debugging.
When you first use EDE you need to setup a project space and add a new project:
1. Access the Project menu and select Project Space | New....
2. Give your project space a name and then click OK.
3. Click on the Add new project to project space button.
4. Give your project a name and then click OK.
The Project Properties dialog box then appears for you to identify the files to be added.
5. Add all the files you want to be part of your project. Then press the OK button. To add files, use one of the 3 methods described below.
The new project is now open.
6. Click Project | Load Files to open files you want on your EDE desktop.
EDE automatically creates a makefile for the project. EDE updates the makefile every time you modify your project.
A detailed description of the process creating the sample program demo.abs is described below. This procedure is outlined as a guide for you to build your own executables for debugging.
1. Make the subdirectory xvw of the examples directory the current working directory.
2. Be sure that the directory of the binaries is present in the PATH environment variable.
3. Compile, assemble, link and locate the modules using one call to the control program ccxa:
ccxa -g -M demo.c addone.src -o demo.abs
The -g option specifies to generate symbolic debugging information. This option must always be specified when debugging with CrossView Pro.
The -M option specifies to generate map files.
The -o option specifies the name of the output file.
The command in step 3 generates the object files demo.obj and addone.obj, the linker map file demo.lnl, the locator map file demo.map and the absolute output file demo.abs. The file demo.abs is in the IEEE Std. 695 format, and can directly be used by CrossView Pro. No separate formatter is needed.
Now you have created all the files necessary for debugging with CrossView Pro using one call to the control program.
If you want to see how the control program calls the compiler, assembler, linker and locator, you can use the -v0 option or -v option. The -v0 option only displays the invocations without executing them. The -v option also executes them.
ccxa -g -M demo.c addone.src -o demo.abs -v0
The control program shows the following command invocations without executing them (UNIX output):
XA control program vx.y rz SN00000000-003 (c) year TASKING, Inc. demo.c: + cxa -e -g -Mt -o /tmp/cc30104b.src demo.c + asxa /tmp/cc30104b.src -e -g -o demo.obj addone.src: + asxa addone.src -e -g -o addone.obj + lkxa -e demo.obj addone.obj -lct -lfpt -dxa_t.dsc -o/tmp/cc30104c.out + lcxa -e -M -dxa_t.dsc /tmp/cc30104c.out -odemo.abs
The -e option removes output files after errors occur. The -Mt option selects the tiny memory model. The -lct and -lfpt options of the linker specify to link the appropriate C libraries. The -d option of the linker and locator specifies the name of the description file.
As you can see, the tools use temporary files for intermediate results. Also the .out file will be removed afterwards. If you want to keep the intermediate files you can use the -tmp option. The following command makes this clear.
ccxa -g -M demo.c addone.src -o demo.abs -v0 -tmp
This command produces the following output:
XA control program vx.y rz SN00000000-003 (c) year TASKING, Inc. demo.c: + cxa -e -g -Mt -o demo.src demo.c + asxa demo.src -e -g -o demo.obj addone.src: + asxa addone.src -e -g -o addone.obj + lkxa -e demo.obj addone.obj -lct -lfpt -dxa_t.dsc -odemo.out + lcxa -e -M -dxa_t.dsc demo.out -odemo.abs
As you can see, if you use the -tmp option, the assembly source files and linker output file will remain in your current directory.
Of course, you will get the same result if you invoke the tools separately using the same calling scheme as the control program.
As you can see, the control program automatically calls each tool with the correct options and controls.
The subdirectories in the examples directory each contain a makefile which can be processed by mkxa. Also each subdirectory contains a readme.txt file with a description of how to build the example.
To build the demo example follow the steps below. This procedure is outlined as a guide for you to build your own executables for debugging.
1. Make the subdirectory xvw of the examples directory the current working directory.
This directory contains a makefile for building the demo example. It uses the default mkxa rules.
2. Be sure that the directory of the binaries is present in the PATH environment variable.
3. Compile, assemble, link and locate the modules using one call to the program builder mkxa:
mkxa
This command will build the example using the file makefile.
To see which commands are invoked by mkxa without actually executing them, type:
mkxa -n
To remove all generated files type:
mkxa clean