This chapter contains the following sections:
Introduction
CrossView Pro's Features
Source Level Debugging
How CrossView Pro Works
Program Development
Getting Started
Before Starting
Setting Up the Execution Environment
Starting CrossView Pro
CrossView Pro Target 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 Embedded 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 can enter C expressions, CrossView Pro commands or any combination of the two for CrossView Pro to evaluate. Expression evaluation is an ideal way to test subroutines by passing them sample values and checking the results.
Breakpoints halt program execution and return control to you. There are several types of breakpoints: code, data, instruction count, cycle count, timer and sequence.
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.
An instruction count breakpoint halts the program after a specified number of instructions have been executed; a cycle count breakpoint stops the program after a number of CPU cycles; a timer breakpoint stops the program after a number of micro seconds or ticks and sequence breakpoints stop the program when a number of breakpoints are hit in a specified sequence.
Data breakpoints, instruction count breakpoints, cycle count breakpoints and timer breakpoints are not available for all execution environments, please check the Addendum.
A breakpoint can be treated as a probe point. When a probe point breakpoint is hit, the associated commands are executed and program execution is continued. Probe points are used with File I/O simulation and sequence breakpoints.
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 I/O simulation you can debug programs before the actual input and output devices are present. CrossView Pro can read input data from the keyboard or a file, or can send output to a window or a file. You can view the data in several formats, including hexadecimal and character. You can have an unlimited number of simulated I/O 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.
When you click on a Help button or when you press the F1 function key in an active window, the CrossView Pro help system opens at the appropriate section. From this point, you can also access the rest of the 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 or assembly code. CrossView Pro 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 Generic Debug Instrument (GDI) calls towards a shared library for the simulator, or using a connection 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 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:
ccr8c The control program which activates the C compiler, assembler, linker and/or locator depending on its input.
cr8c The R8C C compiler. This is a dedicated R8C C compiler which translates a C source program into a highly optimized assembly source file, using the R8C assembly language specification.
asr8c The assembler program which produces a relocatable object file from a given assembly file.
lkr8c A linker that links combining objects and object libraries into one relocatable object file and produces one absolute load file in ELF/DWARF 2 object format. This program can also produce files in the Intel Hex format or Motorola S-record.
arr8c An ELF archiver. With this utility you create and maintain object library files.
mkr8c 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.
xfwr8c The CrossView Pro debugger using R8C execution environments.
Figure 1-3: Toolchain development flow
For a full description of all available utility programs see the chapter Using the Utilities in the R8C C Compiler, Assembler, Linker 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.
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 (*.elf) 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/XP/NT/2000, and dropping it there or associating CrossView Pro to be the application to start when double-clicking an .elf icon. CrossView Pro will start and load the symbol information from that file.
You can specify specific CrossView Pro startup settings in the Target Settings dialog.
To open the Target Settings dialog:
Figure 1-5: CrossView Pro Target 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.
An information line has the following synopsis:
field one of the keywords described below
field-value the value assigned to the field
comment optional comment
The fields listed in the configuration file are:
Field | Description |
title | The full name of the configuration. This name will be displayed in the Target configuration field of the Target Settings dialog. |
cpu_type | The name of the CPU. |
debug_instrument_module | The name of the Debug Instrument (using GDI) used for debugging: 'simr8c' for the instruction set simulator, 'dimonr8c' for the ROM monitor. |
radm | The name of the Debug Instrument (using KDI) used for RTOS aware debugging. (optional). |
Notes:
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 Comunication page of the CrossView Pro
entry in the Project | Project Options dialog.
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
You can use the File | Compare Application... dialog to check if a file matches the downloaded application. This can be useful when your program has changed some of your code.
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 (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 or a structure:
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 choose to clear the command edit field after executing a command. From the File menu, select Options... and select the Desktop tab. Enable the Clear command line after executing command check box. You can use the clear command to clear the Output Window.
To quit a debugging session:
If you selected one or more items in the Options dialog, your settings will be saved in the initialization file xvw.ini. This file is located in the startup directory.
If you have set the Save desktop and target settings check box in the Save tab, CrossView Pro will create a workspace file (.cws) for each debugged or loaded application. The settings will be restored in a following debug session. If CrossView Pro cannot find a workspace file for a loaded application it uses the default workspace file xvw.cws in the etc directory.
A CrossView Pro workspace file contains:
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 R8C toolchain.
In order to debug your programs, you will have to compile, assemble, link and locate them for debugging using the TASKING R8C 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 and develop your application.
To use EDE on the demo program, located in the subdirectory xvw in the examples subdirectory of the R8C product tree, follow the steps below.
A detailed description of the process creating the sample program 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 toolbar (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 have more than one TASKING product installed and you want to change toolchains, do the following:
1. From the Project menu, select Select Toolchain...
The Select Toolchain dialog appears.
2. Select the toolchain you want. You can do this by clicking on a toolchain in the Toolchains list box and click 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. From the Project menu, select Set Current ->.
2. Select the project file to open. For the demo program select the file sim.pjt, located in the subdirectory xvw in the examples subdirectory of the R8C product tree. If you have used the defaults, the file sim.pjt is in the directory c:\...\cr8c\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. From the Project menu, select Load Files...
The Choose Project Files to Edit dialog appears.
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 click OK.
This launches the file(s) so you can edit it (them).
1. From the Project menu, select Directories...
The Directories dialog appears.
2. Check the directory paths for programs, include files and libraries. You can add your own directories here, separated by semicolons.
3. Click OK.
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 keep temporary files that are generated during a build.
1. From the Build menu, select Options...
The Build Options dialog appears.
2. Make your changes and press the OK button.
3. From the Build menu, select Scan All Dependencies.
4. Click on the Execute 'Make' command button. The following button is the execute Make button which is located in the toolbar.
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.yrz Build nnn SN 00000000 Compiling "demo.c" Assembling "demo.src" Assembling "addone.src" Assembling "sim_cstart.src" Linking to "sim.elf"
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 toolbar.
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. From the File menu, select New Project Space...
The Create a New Project Space dialog appears.
2. Give your project space a name and then click OK.
The Project Properties dialog box appears.
3. Click on the Add new project to project space button.
The Add New Project to Project Space dialog appears.
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. From the Project menu, select Load Files... to open the 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.elf 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 ccr8c:
ccr8c -g demo.c addone.src -o demo.elf
The -g option enables symbolic debug information.
The -o option specifies the name of the output file.
The command in step 3 generates the linker map file demo.map and the absolute output file demo.elf. The file demo.elf is in the ELF/DWARF 2 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, and linker, you can use the -n option or -v option. The -n option only displays the invocations without executing them. The -v option also executes them.
ccr8c -g demo.c addone.src -o demo.elf -n
The control program shows the following command invocations without executing them (UNIX output):
+ cr8c -g -o demo.src demo.c + asr8c -ghl -o addone.obj addone.src + asr8c -ghl -o demo.obj demo.src + lkr8c addone.obj demo.obj -o demo.elf --map-file -lc -lfp -lrt
The -lc, -lfp and -lrt options of the linker specify to link the appropriate C library, floating-point library and run-time library. The --map-file option specifies to generate a linker map file.
By default, the control program removes the intermediate output files (demo.src, demo.obj and addone.obj in the example above) afterwards, unless you specify the command line option -t (--keep-temporary-files).
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.
The subdirectories in the examples directory each contain a makefile which can be processed by mkr8c. 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 mkr8c 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 mkr8c:
mkr8c
This command will build the example using the file makefile.
To see which commands are invoked by mkr8c without actually executing them, type:
mkr8c -n
This command produces the following output:
TASKING R8C program builder vx.yrz Build nnn Copyright years Altium BV Serial# 00000000 ccr8c -c -o demo.obj -s -g demo.c ccr8c -c -o addone.obj addone.src ccr8c -o demo.elf demo.obj addone.obj
The -s option in the makefile instructs the compiler to include C source lines as comments in the assembly output. The -g option is used to instruct the C compiler to generate symbolic debug information. This information makes an application written in C much easier to debug.
To remove all generated files type:
mkr8c clean