Next: Debug Adapter Configuration, Previous: Config File Guidelines, Up: Top [Contents][Index]
The commands here are commonly found in the openocd.cfg file and are used to specify what TCP/IP ports are used, and how GDB should be supported.
When the OpenOCD server process starts up, it enters a configuration stage which is the only time that certain commands, configuration commands, may be issued. Normally, configuration commands are only available inside startup scripts.
In this manual, the definition of a configuration command is
presented as a Config Command, not as a Command
which may be issued interactively.
The runtime help command also highlights configuration
commands, and those which may be issued at any time.
Those configuration commands include declaration of TAPs, flash banks, the interface used for JTAG communication, and other basic setup. The server must leave the configuration stage before it may access or activate TAPs. After it leaves this stage, configuration commands may no longer be issued.
Returns the command modes allowed by a command: ’any’, ’config’, or ’exec’. If no command is specified, returns the current command mode. Returns ’unknown’ if an unknown command is given. Command can be multiple tokens. (command valid any time)
In this document, the modes are described as stages, ’config’ and ’exec’ mode correspond configuration stage and run stage. ’any’ means the command can be executed in either stages. See Configuration Stage, and See Entering the Run Stage.
The first thing OpenOCD does after leaving the configuration stage is to verify that it can talk to the scan chain (list of TAPs) which has been configured. It will warn if it doesn’t find TAPs it expects to find, or finds TAPs that aren’t supposed to be there. You should see no errors at this point. If you see errors, resolve them by correcting the commands you used to configure the server. Common errors include using an initial JTAG speed that’s too fast, and not providing the right IDCODE values for the TAPs on the scan chain.
Once OpenOCD has entered the run stage, a number of commands
become available.
A number of these relate to the debug targets you may have declared.
For example, the mww command will not be available until
a target has been successfully instantiated.
If you want to use those commands, you may need to force
entry to the run stage.
This command terminates the configuration stage and enters the run stage. This helps when you need to have the startup scripts manage tasks such as resetting the target, programming flash, etc. To reset the CPU upon startup, add "init" and "reset" at the end of the config script or at the end of the OpenOCD command line using the -c command line switch.
If this command does not appear in any startup/configuration file OpenOCD executes the command for you after processing all configuration files and/or command line options.
NOTE: This command normally occurs near the end of your
openocd.cfg file to force OpenOCD to “initialize” and make the
targets ready. For example: If your openocd.cfg file needs to
read/write memory on your target, init must occur before
the memory read/write commands. This includes nand probe.
init calls the following internal OpenOCD commands to initialize
corresponding subsystems:
At last, init executes all the commands that are specified in
the TCL list post_init_commands. The commands are executed in the
same order they occupy in the list. If one of the commands fails, then
the error is propagated and OpenOCD fails too.
lappend post_init_commands {echo "OpenOCD successfully initialized."}
lappend post_init_commands {echo "Have fun with OpenOCD !"}
Prevent OpenOCD from implicit init call at the end of startup.
Allows issuing configuration commands over telnet or Tcl connection.
When you are done with configuration use init to enter
the run stage.
This is invoked at server startup to verify that it can talk to the scan chain (list of TAPs) which has been configured.
The default implementation first tries jtag arp_init,
which uses only a lightweight JTAG reset before examining the
scan chain.
If that fails, it tries again, using a harder reset
from the overridable procedure init_reset.
Implementations must have verified the JTAG scan chain before
they return.
This is done by calling jtag arp_init
(or jtag arp_init-reset).
The OpenOCD server accepts remote commands in several syntaxes. Each syntax uses a different TCP/IP port, which you may specify only during configuration (before those ports are opened).
For reasons including security, you may wish to prevent remote access using one or more of these ports. In such cases, just specify the relevant port number as "disabled".
You can request the operating system to select one of the available ports for the server by specifying the relevant port number as "0".
Normally gdb listens to a TCP/IP port, but GDB can also communicate via pipes(stdin/out or named pipes). The name "gdb port" stuck because it covers probably more than 90% of the normal use cases.
No arguments reports GDB port. "pipe" means listen to stdin output to stdout, an integer is base port number, "disabled" disables the gdb server.
When using "pipe", also use log_output to redirect the log output to a file so as not to flood the stdin/out pipes.
Any other string is interpreted as named pipe to listen to. Output pipe is the same name as input pipe, but with ’o’ appended, e.g. /var/gdb, /var/gdbo.
The GDB port for the first target will be the base port, the
second target will listen on port + 1, and so on.
When not specified during the configuration stage,
the port number defaults to 3333.
When number is not a numeric value, incrementing it to compute
the next port number does not work. In this case, specify the proper
number for each target by using the option -gdb-port of the
commands target create or $target_name configure.
See option -gdb-port.
Note: when using "gdb port pipe", increasing the default remote timeout in gdb (with ’set remotetimeout’) is recommended. An insufficient timeout may cause initialization to fail with "Unknown remote qXfer reply: OK".
Specify or query the port used for a simplified RPC connection that can be used by clients to issue TCL commands and get the output from the Tcl engine. Intended as a machine interface. When not specified during the configuration stage, the port number defaults to 6666. When specified as "disabled", this service is not activated.
Specify or query the port on which to listen for incoming telnet connections. This port is intended for interaction with one human through TCL commands. When not specified during the configuration stage, the port number defaults to 4444. When specified as "disabled", this service is not activated.
You can reconfigure some GDB behaviors if needed. The ones listed here are static and global. See Target Configuration, about configuring individual targets. See Target Events, about configuring target-specific event handling.
Force breakpoint type for gdb break commands.
This option supports GDB GUIs which don’t
distinguish hard versus soft breakpoints, if the default OpenOCD and
GDB behaviour is not sufficient. GDB normally uses hardware
breakpoints if the memory map has been set up for flash regions.
Set to enable to cause OpenOCD to program the flash memory when a vFlash packet is received. The default behaviour is enable.
Set to enable to cause OpenOCD to send the memory configuration to GDB when
requested. GDB will then know when to set hardware breakpoints, and program flash
using the GDB load command. gdb flash_program enable must also be enabled
for flash programming to work.
Default behaviour is enable.
See gdb flash_program.
Specifies whether data aborts cause an error to be reported by GDB memory read packets. The default behaviour is disable; use enable see these errors reported.
Specifies whether register accesses requested by GDB register read/write packets report errors or not. The default behaviour is disable; use enable see these errors reported.
Set to enable to cause OpenOCD to send the target descriptions to gdb via qXfer:features:read packet. The default behaviour is enable.
Saves the target description file to the local file system.
The file name is target_name.xml.
Hardware debuggers are parts of asynchronous systems, where significant events can happen at any time. The OpenOCD server needs to detect some of these events, so it can report them to through TCL command line or to GDB.
Examples of such events include:
None of those events are signaled through standard JTAG signals. However, most conventions for JTAG connectors include voltage level and system reset (SRST) signal detection. Some connectors also include instrumentation signals, which can imply events when those signals are inputs.
In general, OpenOCD needs to periodically check for those events, either by looking at the status of signals on the JTAG connector or by sending synchronous “tell me your status” JTAG requests to the various active targets. There is a command to manage and monitor that polling, which is normally done in the background.
Poll the current target for its current state. (Also, see target curstate.) If that target is in debug mode, architecture specific information about the current state is printed. An optional parameter allows background polling to be enabled and disabled.
You could use this from the TCL command shell, or
from GDB using monitor poll command.
Leave background polling enabled while you’re using GDB.
> poll
background polling: on
target state: halted
target halted in ARM state due to debug-request, \
current mode: Supervisor
cpsr: 0x800000d3 pc: 0x11081bfc
MMU: disabled, D-Cache: disabled, I-Cache: enabled
>
Next: Debug Adapter Configuration, Previous: Config File Guidelines, Up: Top [Contents][Index]