## 7 Server Configuration ¶

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.

### 7.1 Configuration Stage ¶

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.

Command: command mode [command_name] ¶

  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.

### 7.2 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.

Config Command: init ¶

  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:

  Config Command: target init ¶
  Command: transport init ¶
  Command: dap init ¶
  Config Command: flash init ¶
  Config Command: nand init ¶
  Config Command: pld init ¶
  Command: tpiu init ¶

  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 !"}

Config Command: noinit ¶

  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.

Overridable Procedure: jtag_init ¶

  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`).

### 7.3 TCP/IP Ports ¶

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". If you disable all access through TCP/IP, you will need to use the command line `-pipe` option.

Config Command: gdb_port [number] ¶

  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 gdb_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".

Config Command: tcl_port [number] ¶

  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.

Config Command: telnet_port [number] ¶

  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.

### 7.4 GDB Configuration ¶

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.

Command: gdb_breakpoint_override [`hard`|`soft`|`disable`] ¶

  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.

Config Command: gdb_flash_program (`enable`|`disable`) ¶

  Set to `enable` to cause OpenOCD to program the flash memory when a vFlash packet is received. The default behaviour is `enable`.

Config Command: gdb_memory_map (`enable`|`disable`) ¶

  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.

Config Command: gdb_report_data_abort (`enable`|`disable`) ¶

  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.

Config Command: gdb_report_register_access_error (`enable`|`disable`) ¶

  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.

Config Command: gdb_target_description (`enable`|`disable`) ¶

  Set to `enable` to cause OpenOCD to send the target descriptions to gdb via qXfer:features:read packet. The default behaviour is `enable`.

Command: gdb_save_tdesc ¶

  Saves the target description file to the local file system.

  The file name is target_name.xml.

### 7.5 Event Polling ¶

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:

- One of the targets can stop running ... maybe it triggers a code breakpoint or data watchpoint, or halts itself.
- Messages may be sent over “debug message” channels ... many targets support such messages sent over JTAG, for receipt by the person debugging or tools.
- Loss of power ... some adapters can detect these events.
- Resets not issued through JTAG ... such reset sources can include button presses or other system hardware, sometimes including the target itself (perhaps through a watchdog).
- Debug instrumentation sometimes supports event triggering such as “trace buffer full” (so it can quickly be emptied) or other signals (to correlate with code behavior).

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.

Command: poll [`on`|`off`] ¶

  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
      >