Program
To enable source-level debugging you must request debug information when you compile and link your application. In VRXCC, use the -g option (for both
compiling and linking—if done in separate steps.) This
• Instructs the compiler and linker to generate debug information in their output files.
• Preserves the .axf file produced by the linker.
Normally this file is deleted after VRXCC generates the Verix .out file. The debugger requires the .axf file as this is where all the debug information is stored.
• Sets the “debuggable” flag in the Verix .out file.
You can see (and change) this flag using the VRXHDR tool. Verix does not allow you to debug a file that does not have this flag set. VeriFone
recommends turning this flag off in released software to prevent user access.
Note that the file must be authenticated again after any modification.
When requesting debug information, the compiler normally reduces the
optimization level from 2 to 1. Fully optimized code can be difficult to debug as object instructions may be reordered with respect to the source code, variables may be optimized out of existence, and so on. However, some problems may only be exposed only at higher optimization levels, leading frustration when an existing the problem goes away when using the debugger. To get both full optimization and debug information, use the -O2 option with the -g option.
VRXDB
VRXDB is a helper program for debugging Verix applications. It has three principal functions:• Launches the ARM RealView debugger (RVD).
• Mediates communication between RVD and dbmon, the debug monitor running on the terminal. VRXDB communicates with RVD through a TCP connection, using the ARM RealView Message protocol. It talks to the monitor over a serial or USB link, using an extended version of the GNU debugger remote protocol.
• Implements Verix-specific commands, for example listing files. A command line interface is provided for this purpose.
NOTE RealView ICE (RVI) software is not required anymore with RealView debugger (RVD) version 1.7 and later, but, is required for earlier versions of RVD. RVI is not installed as part of the RVDS installation, it is provided on a separate CD if needed.
DEBUGGING
VRXDB
Running VRXDB VRXDB is a console application run from a DOS command window, the Windows Start/Run menu, or a Windows shortcut icon. The syntax is:
vrxdb -? -n -d -l -i init-file -x command name=value out-file axf-file
The following lists options. All options and arguments are optional.
At startup, VRXDB performs the following:
1 Sets properties defined on the command line.
2 Runs commands from the initialization file.
3 Runs commands specified in –x options.
4 Launches the debugger if a target program is specified.
5 Prompts for user-command input (unless –n is specified).
VRXDB terminates when a quit command executes or when no more commands remain and no debug session is in progress. To confirm that no commands remain, VRXDB must find the –n option, or an end-of-file on standard input.
-? Help. Print usage summary and exit.
-n Do not read commands from stdin. After running commands from the initialization file and –x options, VRXDB exits unless starting a debug session.
-d Launch the debugger. This is implied if a out-file argument is present. Used alone, it is equivalent to entering a debug command with no arguments.
-l
(lowercase L)
Log activity to vrxdb.log. Equivalent to setting log.level to 1.
-i file Initialization file. This file contains the VRXDB commands that run at startup. If this option is not present, VRXDB looks for a file named vrxdb.ini in the current directory. An error displays if it does not exist.
-x cmd Execute the specified command. The command string must be quoted if it contains spaces. Multiple –x options are allowed. –x commands run after the initialization file.
name=val Set a property (see Properties). Multiple property setting arguments are allowed. This must be a single argument; spaces around the equal sign (=) are not allowed.
out-file Target program .out file (on the terminal). If specified, VRXDB automatically starts the debugger. This, and the axf-file argument, are equivalent to entering the command “debug out-file axf-file.”
axf-file Target program debug information file (on the host PC).
DEBUGGING
VRXDB
Properties Properties are name-value pairs similar to environment variables. They can be set from the VRXDB command line or with the set command. The following
properties are defined:
Commands Commands can be entered from an initialization file, using –x command line options or interactively. If standard input is redirected from a file, commands are read from the file without prompting. In this case, VRXDB exits when the end of file is reached unless a debug session is in progress.
Commands are not processed when the target program is running.
Commands with the potential to produce large amounts of output (for example, dump) can be interrupted by pressing any key. See also the cmd.lines property.
Commands consist of a name followed by white space-separated arguments.
Command names can be abbreviated to any unique prefix. (The help command illustrates the minimum abbreviation.) Comments are denoted by a pound symbol or hash mark (#).
dbg.name Debugger to use. The value must be RVD.
dbg.port TCP/IP port number for debugger communication. Default is 3010. DO not change this for RVD.
dbg.tasks Control debugging of new tasks. The value can be:
• none: Do not debug new tasks
• child: Debug tasks created by tasks being debugged The default is child.
tgt.port Set the PC serial port for target terminal communication. Port 0 denotes USB (default). Changes to tgt.port and tgt.baud must be made before running any command that talks to the target. Once target communication starts, changes are ignored.
tgt.baud Serial baud rate for target communication (default 115200). Ignored for USB.
log.file Log file name (default vrxdb.log). Changing the filename does not enable logging or affect any logging in progress. See log.level.
log.level Log detail level. The log contains a record of commands, debugger messages, and so on. A level of zero (default) turns off logging; 1 turns it on; higher numbers add additional detail.
The highest level is 3. Changing the log level from zero to a positive value opens the file specified in log.file, clearing it if it already exists.
Setting the level to zero closes the log.
cmd.prompt Command prompt string (default > ).
cmd.lines If non-zero, command output pauses after each group of this many lines (default 0).
Note: This feature is enabled only for commands that have lengthy output, such as dump.
DEBUGGING
VRXDB
Verix file names entered as command arguments have the general form
drive:group/name. The drive and group prefixes are optional. If omitted, the default is I: and the current group. Using a slash that is not preceded by a number denotes GID15.
The following subsections describe the VRXDB commands. Aliases are also listed. To pass multiple args, separate with space and enclose in double quotes.
Debugging Commands
Command debug [out-file [axf-file [args...]]]
Description Launches the debugger Command free [task-number]
Description Releases a new task from debugger control. This applies only to newly created tasks where a debug session has started. Once you begin debugging a task, you must use the debugger to free or terminate it.
Arguments
out-file The Verix .out file that must be present on the terminal. The .out extension can be omitted.
axf-file The corresponding debug information file on the host PC. If this is not specified, it is assumed to be out-file with the .axf extension. (Note that this works only if the file is in the current directory.)
Arguments following axf-file are passed to the target task through argv. If arguments are specified, you must explicitly specify the .axf file to avoid ambiguity. If no target is specified, the debugger launches, but no debug session starts.
Use the Manual Startup procedure to start a debug session.
The debug command cannot be used if the debugger is already running. To start a new debug session, terminate the debugger or use the Manual Startup procedure.
args Optional debug command argument listing arguments to be passed to target task through argv. If multiple arguments are required, separate by spaces and enclose in double quotes.
task-number Releases a new task from debugger control. This applies only to newly created tasks where a debug session has started. Once you begin debugging a task, you must use the debugger to free or terminate it.
DEBUGGING
VRXDB
Verix V Utility Commands