X-Git-Url: https://review.openocd.org/gitweb?p=openocd.git;a=blobdiff_plain;f=doc%2Fopenocd.texi;h=70d789a7691ab55277f8c52d31102c34b4ea79b3;hp=97d2e816704e914963aa5488b00b0c9714b8ea8f;hb=42082f7c23ded282489e8ac6ec52fe94fa097cde;hpb=a463670c312befd86224e74a79aa804ee5fbae03 diff --git a/doc/openocd.texi b/doc/openocd.texi index 97d2e81670..70d789a769 100644 --- a/doc/openocd.texi +++ b/doc/openocd.texi @@ -124,7 +124,7 @@ different messaging protocols on top of that signaling). There are many types of debug adapter, and little uniformity in what they are called. (There are also product naming differences.) -These adapters are sometimes packaged as discrete dongles. which +These adapters are sometimes packaged as discrete dongles, which may generically be called @dfn{hardware interface dongles}. Some development boards also integrate them directly, which may let the development board can be directly connected to the debug @@ -574,7 +574,6 @@ bash$ openocd --help --debug | -d set debug level <0-3> --log_output | -l redirect log output to file --command | -c run ---pipe | -p use pipes when talking to gdb @end verbatim If you don't give any @option{-f} or @option{-c} options, @@ -1911,12 +1910,29 @@ use the command line @option{-pipe} option. @deffn {Command} gdb_port [number] @cindex GDB server -Specify or query the first port used for incoming GDB connections. -The GDB port for the -first target will be gdb_port, the second target will listen on gdb_port + 1, and so on. +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, "disable" +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. + +The -p/--pipe option is deprecated and a warning is printed +as it is equivalent to passing in -c "gdb_port pipe; log_output openocd.log". + +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 @var{number} defaults to 3333. -When specified as zero, GDB remote access ports are not activated. @end deffn @deffn {Command} tcl_port [number] @@ -1926,7 +1942,7 @@ output from the Tcl engine. Intended as a machine interface. When not specified during the configuration stage, the port @var{number} defaults to 6666. -When specified as zero, this port is not activated. + @end deffn @deffn {Command} telnet_port [number] @@ -2259,11 +2275,11 @@ default values are used. Currently, only one @var{vid}, @var{pid} pair may be given, e.g. for Altera USB-Blaster (default): @example -ft2232_vid_pid 0x09FB 0x6001 +usb_blaster_vid_pid 0x09FB 0x6001 @end example The following VID/PID is for Kolja Waschk's USB JTAG: @example -ft2232_vid_pid 0x16C0 0x06AD +usb_blaster_vid_pid 0x16C0 0x06AD @end example @end deffn @@ -4236,6 +4252,34 @@ flash bank $_FLASHNAME cfi 0x00000000 0x02000000 2 4 $_TARGETNAME @c "cfi part_id" disabled @end deffn +@deffn {Flash Driver} stmsmi +@cindex STMicroelectronics Serial Memory Interface +@cindex SMI +@cindex stmsmi +Some devices form STMicroelectronics (e.g. STR75x MCU family, +SPEAr MPU family) include a proprietary +``Serial Memory Interface'' (SMI) controller able to drive external +SPI flash devices. +Depending on specific device and board configuration, up to 4 external +flash devices can be connected. + +SMI makes the flash content directly accessible in the CPU address +space; each external device is mapped in a memory bank. +CPU can directly read data, execute code and boot from SMI banks. +Normal OpenOCD commands like @command{mdw} can be used to display +the flash content. + +The setup command only requires the @var{base} parameter in order +to identify the memory bank. +All other parameters are ignored. Additional information, like +flash size, are detected automatically. + +@example +flash bank $_FLASHNAME stmsmi 0xf8000000 0 0 0 $_TARGETNAME +@end example + +@end deffn + @subsection Internal Flash (Microcontrollers) @deffn {Flash Driver} aduc702x @@ -5430,9 +5474,10 @@ file (which is normally the server's standard output). @xref{Running}. @end deffn -@deffn Command echo message +@deffn Command echo [-n] message Logs a message at "user" priority. Output @var{message} to stdout. +Option "-n" suppresses trailing newline. @example echo "Downloading kernel -- please wait" @end example @@ -6337,10 +6382,10 @@ handler. However, this means that the complete first cacheline in the mini-IC is marked valid, which makes the CPU fetch all exception handlers from the mini-IC, ignoring the code in RAM. -OpenOCD currently does not sync the mini-IC entries with the RAM -contents (which would fail anyway while the target is running), so -the user must provide appropriate values using the @code{xscale -vector_table} command. +To address this situation, OpenOCD provides the @code{xscale +vector_table} command, which allows the user to explicity write +individual entries to either the high or low vector table stored in +the mini-IC. It is recommended to place a pc-relative indirect branch in the vector table, and put the branch destination somewhere in memory. Doing so @@ -6367,11 +6412,38 @@ _vectors: .long real_fiq_handler @end example +Alternatively, you may choose to keep some or all of the mini-IC +vector table entries synced with those written to memory by your +system software. The mini-IC can not be modified while the processor +is executing, but for each vector table entry not previously defined +using the @code{xscale vector_table} command, OpenOCD will copy the +value from memory to the mini-IC every time execution resumes from a +halt. This is done for both high and low vector tables (although the +table not in use may not be mapped to valid memory, and in this case +that copy operation will silently fail). This means that you will +need to briefly halt execution at some strategic point during system +start-up; e.g., after the software has initialized the vector table, +but before exceptions are enabled. A breakpoint can be used to +accomplish this once the appropriate location in the start-up code has +been identified. A watchpoint over the vector table region is helpful +in finding the location if you're not sure. Note that the same +situation exists any time the vector table is modified by the system +software. + The debug handler must be placed somewhere in the address space using the @code{xscale debug_handler} command. The allowed locations for the debug handler are either (0x800 - 0x1fef800) or (0xfe000800 - 0xfffff800). The default value is 0xfe000800. +XScale has resources to support two hardware breakpoints and two +watchpoints. However, the following restrictions on watchpoint +functionality apply: (1) the value and mask arguments to the @code{wp} +command are not supported, (2) the watchpoint length must be a +power of two and not less than four, and can not be greater than the +watchpoint address, and (3) a watchpoint with a length greater than +four consumes all the watchpoint hardware resources. This means that +at any one time, you can have enabled either two watchpoints with a +length of four, or one watchpoint with a length greater than four. These commands are available to XScale based CPUs, which are implementations of the ARMv5TE architecture. @@ -6574,6 +6646,21 @@ must also be explicitly enabled. This finishes by listing the current vector catch configuration. @end deffn +@deffn Command {cortex_m3 reset_config} (@option{srst}|@option{sysresetreq}|@option{vectreset}) +Control reset handling. The default @option{srst} is to use srst if fitted, +otherwise fallback to @option{vectreset}. +@itemize @minus +@item @option{srst} use hardware srst if fitted otherwise fallback to @option{vectreset}. +@item @option{sysresetreq} use NVIC SYSRESETREQ to reset system. +@item @option{vectreset} use NVIC VECTRESET to reset system. +@end itemize +Using @option{vectreset} is a safe option for all current Cortex-M3 cores. +This however has the disadvantage of only resetting the core, all peripherals +are uneffected. A solution would be to use a @code{reset-init} event handler to manually reset +the peripherals. +@xref{Target Events}. +@end deffn + @anchor{Software Debug Messages and Tracing} @section Software Debug Messages and Tracing @cindex Linux-ARM DCC support @@ -7010,11 +7097,12 @@ This would cause GDB to connect to the gdbserver on the local pc using port 3333 @item A pipe connection is typically started as follows: @example -target remote | openocd --pipe +target remote | openocd -c "gdb_port pipe; log_output openocd.log" @end example This would cause GDB to run OpenOCD and communicate using pipes (stdin/stdout). Using this method has the advantage of GDB starting/stopping OpenOCD for the debug -session. +session. log_output sends the log output to a file to ensure that the pipe is +not saturated when using higher debug level outputs. @end enumerate To list the available OpenOCD commands type @command{monitor help} on the @@ -7191,10 +7279,10 @@ Low-level commands are (should be) prefixed with "ocd_", e.g. is the low level API upon which @command{flash banks} is implemented. @itemize @bullet -@item @b{ocd_mem2array} <@var{varname}> <@var{width}> <@var{addr}> <@var{nelems}> +@item @b{mem2array} <@var{varname}> <@var{width}> <@var{addr}> <@var{nelems}> Read memory and return as a Tcl array for script processing -@item @b{ocd_array2mem} <@var{varname}> <@var{width}> <@var{addr}> <@var{nelems}> +@item @b{array2mem} <@var{varname}> <@var{width}> <@var{addr}> <@var{nelems}> Convert a Tcl array to memory locations and write the values @item @b{ocd_flash_banks} <@var{driver}> <@var{base}> <@var{size}> <@var{chip_width}> <@var{bus_width}> <@var{target}> [@option{driver options} ...]