X-Git-Url: https://review.openocd.org/gitweb?p=openocd.git;a=blobdiff_plain;f=doc%2Fopenocd.texi;h=ce9cd3b96340f98b5df1a84bf72c88580645302c;hp=2f01153f84c641625539270db8dc98d8cdbe538c;hb=ffb93ef37134afcbed2ac958918c95d66f86b7a3;hpb=cb2f21bf3608f24de5c2e4219626cc464269e830 diff --git a/doc/openocd.texi b/doc/openocd.texi index 2f01153f84..ce9cd3b963 100644 --- a/doc/openocd.texi +++ b/doc/openocd.texi @@ -1595,8 +1595,11 @@ proc enable_fast_clock @{@} @{ proc init_board @{@} @{ reset_config trst_and_srst trst_pulls_srst + $_TARGETNAME configure -event reset-start @{ + adapter_khz 100 + @} + $_TARGETNAME configure -event reset-init @{ - adapter_khz 1 enable_fast_clock adapter_khz 10000 @} @@ -2556,6 +2559,36 @@ For example adapter definitions, see the configuration files shipped in the @end deffn +@deffn {Interface Driver} {ft232r} +This driver is implementing synchronous bitbang mode of an FTDI FT232R +USB UART bridge IC. + +List of connections (pin numbers for SSOP): +@itemize @minus +@item RXD(5) - TDI +@item TXD(1) - TCK +@item RTS(3) - TDO +@item CTS(11) - TMS +@item DTR(2) - TRST +@item DCD(10) - SRST +@end itemize + +These interfaces have several commands, used to configure the driver +before initializing the JTAG scan chain: + +@deffn {Config Command} {ft232r_vid_pid} @var{vid} @var{pid} +The vendor ID and product ID of the adapter. If not specified, default +0x0403:0x6001 is used. +@end deffn + +@deffn {Config Command} {ft232r_serial_desc} @var{serial} +Specifies the @var{serial} of the adapter to use, in case the +vendor provides unique IDs and more than one adapter is connected to +the host. If not specified, serial numbers are not considered. +@end deffn + +@end deffn + @deffn {Interface Driver} {remote_bitbang} Drive JTAG from a remote process. This sets up a UNIX or TCP socket connection with a remote process and sends ASCII encoded bitbang requests to that process @@ -4430,16 +4463,14 @@ buttons and events. The two examples below act the same, but one creates and invokes a small procedure while the other inlines it. @example -proc my_attach_proc @{ @} @{ - echo "Reset..." - reset halt +proc my_init_proc @{ @} @{ + echo "Disabling watchdog..." + mww 0xfffffd44 0x00008000 @} -mychip.cpu configure -event gdb-attach my_attach_proc -mychip.cpu configure -event gdb-attach @{ - echo "Reset..." - # To make flash probe and gdb load to flash work - # we need a reset init. - reset init +mychip.cpu configure -event reset-init my_init_proc +mychip.cpu configure -event reset-init @{ + echo "Disabling watchdog..." + mww 0xfffffd44 0x00008000 @} @end example @@ -4449,7 +4480,7 @@ The following target events are defined: @item @b{debug-halted} @* The target has halted for debug reasons (i.e.: breakpoint) @item @b{debug-resumed} -@* The target has resumed (i.e.: gdb said run) +@* The target has resumed (i.e.: GDB said run) @item @b{early-halted} @* Occurs early in the halt process @item @b{examine-start} @@ -4457,11 +4488,16 @@ The following target events are defined: @item @b{examine-end} @* After target examine is called with no errors. @item @b{gdb-attach} -@* When GDB connects. This is before any communication with the target, so this -can be used to set up the target so it is possible to probe flash. Probing flash -is necessary during gdb connect if gdb load is to write the image to flash. Another -use of the flash memory map is for GDB to automatically hardware/software breakpoints -depending on whether the breakpoint is in RAM or read only memory. +@* When GDB connects. This is before any communication with the target and GDB +expects the target is halted during attachment. +@xref{gdbmeminspect,,GDB as a non-intrusive memory inspector} for exclusion. +The event can be also used to set up the target so it is possible to probe flash. +Probing flash is necessary during GDB connect if you want to use +@pxref{programmingusinggdb,,programming using GDB}. +Another use of the flash memory map is for GDB to automatically choose +hardware or software breakpoints depending on whether the breakpoint +is in RAM or read only memory. +Default is @code{halt} @item @b{gdb-detach} @* When GDB disconnects @item @b{gdb-end} @@ -4476,13 +4512,13 @@ depending on whether the breakpoint is in RAM or read only memory. @item @b{gdb-flash-write-end} @* After GDB writes to the flash (default is @code{reset halt}) @item @b{gdb-start} -@* Before the target steps, gdb is trying to start/resume the target +@* Before the target steps, GDB is trying to start/resume the target @item @b{halted} @* The target has halted @item @b{reset-assert-pre} @* Issued as part of @command{reset} processing -after @command{reset_init} was triggered -but before either SRST alone is re-asserted on the scan chain, +after @command{reset-start} was triggered +but before either SRST alone is asserted on the scan chain, or @code{reset-assert} is triggered. @item @b{reset-assert} @* Issued as part of @command{reset} processing @@ -4516,8 +4552,8 @@ multiplexing, and so on. (You may be able to switch to a fast JTAG clock rate here, after the target clocks are fully set up.) @item @b{reset-start} -@* Issued as part of @command{reset} processing -before @command{reset_init} is called. +@* Issued as the first step in @command{reset} processing +before @command{reset-assert-pre} is called. This is the most robust place to use @command{jtag_rclk} or @command{adapter_khz} to switch to a low JTAG clock rate, @@ -9178,19 +9214,6 @@ With that particular hardware (Cortex-M3) the hardware breakpoints only work for code running from flash memory. Most other ARM systems do not have such restrictions. -Another example of useful GDB configuration came from a user who -found that single stepping his Cortex-M3 didn't work well with IRQs -and an RTOS until he told GDB to disable the IRQs while stepping: - -@example -define hook-step -mon cortex_m maskisr on -end -define hookpost-step -mon cortex_m maskisr off -end -@end example - Rather than typing such commands interactively, you may prefer to save them in a file and have GDB execute them as it starts, perhaps using a @file{.gdbinit} in your project directory or starting GDB @@ -9230,14 +9253,60 @@ GDB will look at the target memory map when a load command is given, if any areas to be programmed lie within the target flash area the vFlash packets will be used. -If the target needs configuring before GDB programming, an event -script can be executed: +If the target needs configuring before GDB programming, set target +event gdb-flash-erase-start: @example -$_TARGETNAME configure -event EVENTNAME BODY +$_TARGETNAME configure -event gdb-flash-erase-start BODY @end example +@xref{targetevents,,Target Events} for other GDB programming related events. To verify any flash programming the GDB command @option{compare-sections} can be used. + +@section Using GDB as a non-intrusive memory inspector +@cindex Using GDB as a non-intrusive memory inspector +@anchor{gdbmeminspect} + +If your project controls more than a blinking LED, let's say a heavy industrial +robot or an experimental nuclear reactor, stopping the controlling process +just because you want to attach GDB is not a good option. + +OpenOCD does not support GDB non-stop mode (might be implemented in the future). +Though there is a possible setup where the target does not get stopped +and GDB treats it as it were running. +If the target supports background access to memory while it is running, +you can use GDB in this mode to inspect memory (mainly global variables) +without any intrusion of the target process. + +Remove default setting of gdb-attach event. @xref{targetevents,,Target Events}. +Place following command after target configuration: +@example +$_TARGETNAME configure -event gdb-attach @{@} +@end example + +If any of installed flash banks does not support probe on running target, +switch off gdb_memory_map: +@example +gdb_memory_map disable +@end example + +Ensure GDB is configured without interrupt-on-connect. +Some GDB versions set it by default, some does not. +@example +set remote interrupt-on-connect off +@end example + +If you switched gdb_memory_map off, you may want to setup GDB memory map +manually or issue @command{set mem inaccessible-by-default off} + +Now you can issue GDB command @command{target remote ...} and inspect memory +of a running target. Do not use GDB commands @command{continue}, +@command{step} or @command{next} as they synchronize GDB with your target +and GDB would require stopping the target to get the prompt back. + +Do not use this mode under an IDE like Eclipse as it caches values of +previously shown varibles. + @anchor{usingopenocdsmpwithgdb} @section Using OpenOCD SMP with GDB @cindex SMP