X-Git-Url: https://review.openocd.org/gitweb?p=openocd.git;a=blobdiff_plain;f=doc%2Fopenocd.texi;h=1cca4ab11a626d8f43982aaa0955203213de7317;hp=1d517213d8c3ab5e49e1a02c64bf77e61e88e10e;hb=c0e7ccbd87cf491b065bf18bbdb6a73b741c2698;hpb=800fe0b8855165d48ae227fd07657e1fa2c1b2d4 diff --git a/doc/openocd.texi b/doc/openocd.texi index 1d517213d8..1cca4ab11a 100644 --- a/doc/openocd.texi +++ b/doc/openocd.texi @@ -66,7 +66,7 @@ Free Documentation License''. * Running:: Running OpenOCD * OpenOCD Project Setup:: OpenOCD Project Setup * Config File Guidelines:: Config File Guidelines -* Daemon Configuration:: Daemon Configuration +* Server Configuration:: Server Configuration * Debug Adapter Configuration:: Debug Adapter Configuration * Reset Configuration:: Reset Configuration * TAP Declaration:: TAP Declaration @@ -752,13 +752,13 @@ on the command line or, if there were no @option{-c command} or At the end of the configuration stage it verifies the JTAG scan chain defined using those commands; your configuration should ensure that this always succeeds. -Normally, OpenOCD then starts running as a daemon. +Normally, OpenOCD then starts running as a server. Alternatively, commands may be used to terminate the configuration stage early, perform work (such as updating some flash memory), -and then shut down without acting as a daemon. +and then shut down without acting as a server. -Once OpenOCD starts running as a daemon, it waits for connections from -clients (Telnet, GDB, Other) and processes the commands issued through +Once OpenOCD starts running as a server, it waits for connections from +clients (Telnet, GDB, RPC) and processes the commands issued through those channels. If you are having problems, you can enable internal debug messages via @@ -775,7 +775,7 @@ informational messages, warnings and errors. You can also change this setting from within a telnet or gdb session using @command{debug_level} (@pxref{debuglevel,,debug_level}). -You can redirect all output from the daemon to a file using the +You can redirect all output from the server to a file using the @option{-l } switch. Note! OpenOCD will launch the GDB & telnet server even if it can not @@ -898,7 +898,7 @@ using a Signalyzer FT2232-based JTAG adapter to talk to a board with an Atmel AT91SAM7X256 microcontroller: @example -source [find interface/signalyzer.cfg] +source [find interface/ftdi/signalyzer.cfg] # GDB can also flash my flash! gdb_memory_map enable @@ -910,7 +910,7 @@ source [find target/sam7x256.cfg] Here is the command line equivalent of that configuration: @example -openocd -f interface/signalyzer.cfg \ +openocd -f interface/ftdi/signalyzer.cfg \ -c "gdb_memory_map enable" \ -c "gdb_flash_program enable" \ -f target/sam7x256.cfg @@ -1994,8 +1994,8 @@ proc setc15 @{regs value@} @{ -@node Daemon Configuration -@chapter Daemon Configuration +@node Server Configuration +@chapter Server Configuration @cindex initialization 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 @@ -2097,7 +2097,7 @@ 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 zero. +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 @option{-pipe} option. @@ -2109,7 +2109,7 @@ communicate via pipes(stdin/out or named pipes). The name the normal use cases. No arguments reports GDB port. "pipe" means listen to stdin -output to stdout, an integer is base port number, "disable" +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 @@ -2140,7 +2140,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 "disabled", this service is not activated. @end deffn @deffn {Command} telnet_port [number] @@ -2149,7 +2149,7 @@ 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 @var{number} defaults to 4444. -When specified as zero, this port is not activated. +When specified as "disabled", this service is not activated. @end deffn @anchor{gdbconfiguration} @@ -2403,109 +2403,12 @@ A dummy software-only driver for debugging. Cirrus Logic EP93xx based single-board computer bit-banging (in development) @end deffn -@deffn {Interface Driver} {ft2232} -FTDI FT2232 (USB) based devices over one of the userspace libraries. - -Note that this driver has several flaws and the @command{ftdi} driver is -recommended as its replacement. - -These interfaces have several commands, used to configure the driver -before initializing the JTAG scan chain: - -@deffn {Config Command} {ft2232_device_desc} description -Provides the USB device description (the @emph{iProduct string}) -of the FTDI FT2232 device. If not -specified, the FTDI default value is used. This setting is only valid -if compiled with FTD2XX support. -@end deffn - -@deffn {Config Command} {ft2232_serial} serial-number -Specifies the @var{serial-number} of the FTDI FT2232 device to use, -in case the vendor provides unique IDs and more than one FT2232 device -is connected to the host. -If not specified, serial numbers are not considered. -(Note that USB serial numbers can be arbitrary Unicode strings, -and are not restricted to containing only decimal digits.) -@end deffn - -@deffn {Config Command} {ft2232_layout} name -Each vendor's FT2232 device can use different GPIO signals -to control output-enables, reset signals, and LEDs. -Currently valid layout @var{name} values include: -@itemize @minus -@item @b{axm0432_jtag} Axiom AXM-0432 -@item @b{comstick} Hitex STR9 comstick -@item @b{cortino} Hitex Cortino JTAG interface -@item @b{evb_lm3s811} TI/Luminary Micro EVB_LM3S811 as a JTAG interface, -either for the local Cortex-M3 (SRST only) -or in a passthrough mode (neither SRST nor TRST) -This layout can not support the SWO trace mechanism, and should be -used only for older boards (before rev C). -@item @b{luminary_icdi} This layout should be used with most TI/Luminary -eval boards, including Rev C LM3S811 eval boards and the eponymous -ICDI boards, to debug either the local Cortex-M3 or in passthrough mode -to debug some other target. It can support the SWO trace mechanism. -@item @b{flyswatter} Tin Can Tools Flyswatter -@item @b{icebear} ICEbear JTAG adapter from Section 5 -@item @b{jtagkey} Amontec JTAGkey and JTAGkey-Tiny (and compatibles) -@item @b{jtagkey2} Amontec JTAGkey2 (and compatibles) -@item @b{m5960} American Microsystems M5960 -@item @b{olimex-jtag} Olimex ARM-USB-OCD and ARM-USB-Tiny -@item @b{oocdlink} OOCDLink -@c oocdlink ~= jtagkey_prototype_v1 -@item @b{redbee-econotag} Integrated with a Redbee development board. -@item @b{redbee-usb} Integrated with a Redbee USB-stick development board. -@item @b{sheevaplug} Marvell Sheevaplug development kit -@item @b{signalyzer} Xverve Signalyzer -@item @b{stm32stick} Hitex STM32 Performance Stick -@item @b{turtelizer2} egnite Software turtelizer2 -@item @b{usbjtag} "USBJTAG-1" layout described in the OpenOCD diploma thesis -@end itemize -@end deffn - -@deffn {Config Command} {ft2232_vid_pid} [vid pid]+ -The vendor ID and product ID of the FTDI FT2232 device. If not specified, the FTDI -default values are used. -Currently, up to eight [@var{vid}, @var{pid}] pairs may be given, e.g. -@example -ft2232_vid_pid 0x0403 0xcff8 0x15ba 0x0003 -@end example -@end deffn - -@deffn {Config Command} {ft2232_latency} ms -On some systems using FT2232 based JTAG interfaces the FT_Read function call in -ft2232_read() fails to return the expected number of bytes. This can be caused by -USB communication delays and has proved hard to reproduce and debug. Setting the -FT2232 latency timer to a larger value increases delays for short USB packets but it -also reduces the risk of timeouts before receiving the expected number of bytes. -The OpenOCD default value is 2 and for some systems a value of 10 has proved useful. -@end deffn - -@deffn {Config Command} {ft2232_channel} channel -Used to select the channel of the ft2232 chip to use (between 1 and 4). -The default value is 1. -@end deffn - -For example, the interface config file for a -Turtelizer JTAG Adapter looks something like this: - -@example -interface ft2232 -ft2232_device_desc "Turtelizer JTAG/RS232 Adapter" -ft2232_layout turtelizer2 -ft2232_vid_pid 0x0403 0xbdc8 -@end example -@end deffn - @deffn {Interface Driver} {ftdi} This driver is for adapters using the MPSSE (Multi-Protocol Synchronous Serial Engine) mode built into many FTDI chips, such as the FT2232, FT4232 and FT232H. -It is a complete rewrite to address a large number of problems with the ft2232 -interface driver. The driver is using libusb-1.0 in asynchronous mode to talk to the FTDI device, -bypassing intermediate libraries like libftdi of D2XX. Performance-wise it is -consistently faster than the ft2232 driver, sometimes several times faster. +bypassing intermediate libraries like libftdi of D2XX. A major improvement of this driver is that support for new FTDI based adapters can be added competely through configuration files, without the need to patch @@ -2515,7 +2418,8 @@ The driver uses a signal abstraction to enable Tcl configuration files to define outputs for one or several FTDI GPIO. These outputs can then be controlled using the @command{ftdi_set_signal} command. Special signal names are reserved for nTRST, nSRST and LED (for blink) so that they, if defined, -will be used for their customary purpose. +will be used for their customary purpose. Inputs can be read using the +@command{ftdi_get_signal} command. Depending on the type of buffer attached to the FTDI GPIO, the outputs have to be controlled differently. In order to support tristateable signals such as @@ -2582,7 +2486,7 @@ minimal impact on the target system. Avoid floating inputs, conflicting outputs and initially asserted reset signals. @end deffn -@deffn {Config Command} {ftdi_layout_signal} name [@option{-data}|@option{-ndata} data_mask] [@option{-oe}|@option{-noe} oe_mask] [@option{-alias}|@option{-nalias} name] +@deffn {Config Command} {ftdi_layout_signal} name [@option{-data}|@option{-ndata} data_mask] [@option{-input}|@option{-ninput} input_mask] [@option{-oe}|@option{-noe} oe_mask] [@option{-alias}|@option{-nalias} name] Creates a signal with the specified @var{name}, controlled by one or more FTDI GPIO pins via a range of possible buffer connections. The masks are FTDI GPIO register bitmasks to tell the driver the connection and type of the output @@ -2590,7 +2494,9 @@ buffer driving the respective signal. @var{data_mask} is the bitmask for the pin(s) connected to the data input of the output buffer. @option{-ndata} is used with inverting data inputs and @option{-data} with non-inverting inputs. The @option{-oe} (or @option{-noe}) option tells where the output-enable (or -not-output-enable) input to the output buffer is connected. +not-output-enable) input to the output buffer is connected. The options +@option{-input} and @option{-ninput} specify the bitmask for pins to be read +with the method @command{ftdi_get_signal}. Both @var{data_mask} and @var{oe_mask} need not be specified. For example, a simple open-collector transistor driver would be specified with @option{-oe} @@ -2620,6 +2526,10 @@ Set a previously defined signal to the specified level. @end itemize @end deffn +@deffn {Command} {ftdi_get_signal} name +Get the value of a previously defined signal. +@end deffn + @deffn {Command} {ftdi_tdo_sample_edge} @option{rising}|@option{falling} Configure TCK edge at which the adapter samples the value of the TDO signal @@ -2714,7 +2624,7 @@ reset_config srst_only @end example @end deffn -@deffn {Command} {usb_blaster_lowlevel_driver} (@option{ftdi}|@option{ftd2xx}|@option{ublast2}) +@deffn {Command} {usb_blaster_lowlevel_driver} (@option{ftdi}|@option{ublast2}) Chooses the low level access method for the adapter. If not specified, @option{ftdi} is selected unless it wasn't enabled during the configure stage. USB-Blaster II needs @option{ublast2}. @@ -4213,9 +4123,14 @@ The value should normally correspond to a static mapping for the @anchor{rtostype} @item @code{-rtos} @var{rtos_type} -- enable rtos support for target, @var{rtos_type} can be one of @option{auto}|@option{eCos}|@option{ThreadX}| -@option{FreeRTOS}|@option{linux}|@option{ChibiOS}|@option{embKernel}|@option{mqx} +@option{FreeRTOS}|@option{linux}|@option{ChibiOS}|@option{embKernel}|@option{mqx}| +@option{uCOS-III} @xref{gdbrtossupport,,RTOS Support}. +@item @code{-defer-examine} -- skip target examination at initial JTAG chain +scan and after a reset. A manual call to arp_examine is required to +access the target for debugging. + @end itemize @end deffn @@ -4252,7 +4167,7 @@ omap3530.cpu mww 0x5555 123 The commands supported by OpenOCD target objects are: -@deffn Command {$target_name arp_examine} +@deffn Command {$target_name arp_examine} @option{allow-defer} @deffnx Command {$target_name arp_halt} @deffnx Command {$target_name arp_poll} @deffnx Command {$target_name arp_reset} @@ -4739,8 +4654,10 @@ and display that status. The @var{num} parameter is a value shown by @command{flash banks}. @end deffn -@deffn Command {flash info} num -Print info about flash bank @var{num} +@deffn Command {flash info} num [sectors] +Print info about flash bank @var{num}, a list of protection blocks +and their status. Use @option{sectors} to show a list of sectors instead. + The @var{num} parameter is a value shown by @command{flash banks}. This command will first query the hardware, it does not print cached and possibly stale information. @@ -5279,15 +5196,37 @@ identification register, and autoconfigures itself. flash bank $_FLASHNAME kinetis 0 0 0 0 $_TARGETNAME @end example +@deffn Command {kinetis fcf_source} [protection|write] +Select what source is used when writing to a Flash Configuration Field. +@option{protection} mode builds FCF content from protection bits previously +set by 'flash protect' command. +This mode is default. MCU is protected from unwanted locking by immediate +writing FCF after erase of relevant sector. +@option{write} mode enables direct write to FCF. +Protection cannot be set by 'flash protect' command. FCF is written along +with the rest of a flash image. +@emph{BEWARE: Incorrect flash configuration may permanently lock the device!} +@end deffn + +@deffn Command {kinetis fopt} [num] +Set value to write to FOPT byte of Flash Configuration Field. +Used in kinetis 'fcf_source protection' mode only. +@end deffn + @deffn Command {kinetis mdm check_security} Checks status of device security lock. Used internally in examine-end event. @end deffn +@deffn Command {kinetis mdm halt} +Issues a halt via the MDM-AP. This command can be used to break a watchdog reset +loop when connecting to an unsecured target. +@end deffn + @deffn Command {kinetis mdm mass_erase} -Issues a complete Flash erase via the MDM-AP. -This can be used to erase a chip back to its factory state. -Command removes security lock from a device (use of SRST highly recommended). -It does not require the processor to be halted. +Issues a complete flash erase via the MDM-AP. This can be used to erase a chip +back to its factory state, removing security. It does not require the processor +to be halted, however the target will remain in a halted state after this +command completes. @end deffn @deffn Command {kinetis nvm_partition} @@ -5320,6 +5259,11 @@ kinetis nvm_partition eebkp 16 1024 1024 off @end example @end deffn +@deffn Command {kinetis mdm reset} +Issues a reset via the MDM-AP. This causes the MCU to output a low pulse on the +RESET pin, which can be used to reset other hardware on board. +@end deffn + @deffn Command {kinetis disable_wdog} For Kx devices only (KLx has different COP watchdog, it is not supported). Command disables watchdog timer. @@ -5827,8 +5771,8 @@ The @var{num} parameter is a value shown by @command{flash banks}. @end deffn @deffn {Flash Driver} stm32f2x -All members of the STM32F2 and STM32F4 microcontroller families from ST Microelectronics -include internal flash and use ARM Cortex-M3/M4 cores. +All members of the STM32F2, STM32F4 and STM32F7 microcontroller families from ST Microelectronics +include internal flash and use ARM Cortex-M3/M4/M7 cores. The driver automatically recognizes a number of these chips using the chip identification register, and autoconfigures itself. @@ -5851,6 +5795,19 @@ The @var{num} parameter is a value shown by @command{flash banks}. Unlocks the entire stm32 device. The @var{num} parameter is a value shown by @command{flash banks}. @end deffn + +@deffn Command {stm32f2x options_read} num +Reads and displays user options and (where implemented) boot_addr0 and boot_addr1. +The @var{num} parameter is a value shown by @command{flash banks}. +@end deffn + +@deffn Command {stm32f2x options_write} num user_options boot_addr0 boot_addr1 +Writes user options and (where implemented) boot_addr0 and boot_addr1 in raw format. +Warning: The meaning of the various bits depends on the device, always check datasheet! +The @var{num} parameter is a value shown by @command{flash banks}, user_options a +12 bit value, consisting of bits 31-28 and 7-0 of FLASH_OPTCR, boot_addr0 and boot_addr1 +two halfwords (of FLASH_OPTCR1). +@end deffn @end deffn @deffn {Flash Driver} stm32lx @@ -6666,7 +6623,7 @@ port is 5555. @end itemize -@section Daemon Commands +@section Server Commands @deffn {Command} exit Exits the current telnet session. @@ -6692,7 +6649,7 @@ Useful in connection with script files @end deffn @deffn Command shutdown [@option{error}] -Close the OpenOCD daemon, disconnecting all clients (GDB, telnet, +Close the OpenOCD server, disconnecting all clients (GDB, telnet, other). If option @option{error} is used, OpenOCD will return a non-zero exit code to the parent process. @end deffn @@ -7028,6 +6985,13 @@ The file format may optionally be specified This will first attempt a comparison using a CRC checksum, if this fails it will try a binary compare. @end deffn +@deffn Command {verify_image_checksum} filename address [@option{bin}|@option{ihex}|@option{elf}] +Verify @var{filename} against target memory starting at @var{address}. +The file format may optionally be specified +(@option{bin}, @option{ihex}, or @option{elf}) +This perform a comparison using a CRC checksum only +@end deffn + @section Breakpoint and Watchpoint commands @cindex breakpoint @@ -7440,6 +7404,17 @@ requests by using a special SVC instruction that is trapped at the Supervisor Call vector by OpenOCD. @end deffn +@deffn Command {arm semihosting_fileio} [@option{enable}|@option{disable}] +@cindex ARM semihosting +Display status of semihosting fileio, after optionally changing that +status. + +Enabling this option forwards semihosting I/O to GDB process using the +File-I/O remote protocol extension. This is especially useful for +interacting with remote files or displaying console messages in the +debugger. +@end deffn + @section ARMv4 and ARMv5 Architecture @cindex ARMv4 @cindex ARMv5 @@ -7836,6 +7811,12 @@ Displays ID register from AP @var{num}, defaulting to the currently selected AP. @end deffn +@deffn Command {dap apreg} ap_num reg [value] +Displays content of a register @var{reg} from AP @var{ap_num} +or set a new value @var{value}. +@var{reg} is byte address of a word register, 0, 4, 8 ... 0xfc. +@end deffn + @deffn Command {dap apsel} [num] Select AP @var{num}, defaulting to 0. @end deffn @@ -8864,6 +8845,7 @@ Currently supported rtos's include: @item @option{ChibiOS} @item @option{embKernel} @item @option{mqx} +@item @option{uCOS-III} @end itemize @quotation Note @@ -8897,10 +8879,12 @@ Rtos::sCurrentTask, Rtos::sListReady, Rtos::sListSleep, Rtos::sListSuspended, Rtos::sMaxPriorities, Rtos::sCurrentTaskCount. @item mqx symbols _mqx_kernel_data, MQX_init_struct. +@item uC/OS-III symbols +OSRunning, OSTCBCurPtr, OSTaskDbgListPtr, OSTaskQty @end table For most RTOS supported the above symbols will be exported by default. However for -some, eg. FreeRTOS, extra steps must be taken. +some, eg. FreeRTOS and uC/OS-III, extra steps must be taken. These RTOSes may require additional OpenOCD-specific file to be linked along with the project: @@ -8908,6 +8892,8 @@ along with the project: @table @code @item FreeRTOS contrib/rtos-helpers/FreeRTOS-openocd.c +@item uC/OS-III +contrib/rtos-helpers/uCOS-III-openocd.c @end table @node Tcl Scripting API @@ -9289,16 +9275,6 @@ supply stable enough for the Amontec JTAGkey to be operated. @b{Laptops running on battery have this problem too...} -@item @b{USB Power} When using the Amontec JTAGkey, sometimes OpenOCD crashes with the -following error messages: "Error: ft2232.c:201 ft2232_read(): FT_Read returned: -4" and "Error: ft2232.c:365 ft2232_send_and_recv(): couldn't read from FT2232". -What does that mean and what might be the reason for this? - -First of all, the reason might be the USB power supply. Try using a self-powered -hub instead of a direct connection to your computer. Secondly, the error code 4 -corresponds to an FT_IO_ERROR, which means that the driver for the FTDI USB -chip ran into some sort of error - this points us to a USB problem. - @item @b{GDB Disconnects} When using the Amontec JTAGkey, sometimes OpenOCD crashes with the following error message: "Error: gdb_server.c:101 gdb_get_char(): read: 10054". What does that mean and what might be the reason for this?