X-Git-Url: https://review.openocd.org/gitweb?p=openocd.git;a=blobdiff_plain;f=doc%2Fopenocd.texi;h=027e6d2edbb9d915b7e41da99d989d0a1bb20872;hp=3c1e33d6d886934848bfa71cfe7e85e52183c444;hb=246782229f8f7536bee66322dbe7f366b85628ec;hpb=dd9b7296bdbc236e0eeab35e00fc77f5ba9e565c diff --git a/doc/openocd.texi b/doc/openocd.texi index 3c1e33d6d8..027e6d2edb 100644 --- a/doc/openocd.texi +++ b/doc/openocd.texi @@ -1802,10 +1802,11 @@ displayed by the GDB session @pxref{usingopenocdsmpwithgdb,,Using OpenOCD SMP wi The SMP behaviour can be disabled/enabled dynamically. On cortex_a following command have been implemented. @itemize @bullet -@item cortex_a smp_on : enable SMP mode, behaviour is as described above. -@item cortex_a smp_off : disable SMP mode, the current target is the one +@item cortex_a smp on : enable SMP mode, behaviour is as described above. +@item cortex_a smp off : disable SMP mode, the current target is the one displayed in the GDB session, only this target is now controlled by GDB session. This behaviour is useful during system boot up. +@item cortex_a smp : display current SMP mode. @item cortex_a smp_gdb : display/fix the core id displayed in GDB session see following example. @end itemize @@ -2368,7 +2369,8 @@ the hardware can support. Returns the name of the debug adapter driver being used. @end deffn -@deffn Command {adapter usb location} :[.]... +@anchor{adapter_usb_location} +@deffn Command {adapter usb location} -[.]... Specifies the physical USB port of the adapter to use. The path roots at @var{bus} and walks down the physical ports, with each @var{port} option specifying a deeper level in the bus topology, the last @@ -2510,7 +2512,10 @@ If not specified, serial numbers are not considered. and are not restricted to containing only decimal digits.) @end deffn -@deffn {Config Command} {ftdi_location} :[,]... +@deffn {Config Command} {ftdi_location} -[.]... +@emph{DEPRECATED -- avoid using this. +Use the @xref{adapter_usb_location, adapter usb location} command instead.} + Specifies the physical USB port of the adapter to use. The path roots at @var{bus} and walks down the physical ports, with each @var{port} option specifying a deeper level in the bus topology, the last @@ -6641,6 +6646,17 @@ the chip identification register, and autoconfigures itself. flash bank $_FLASHNAME stm32f2x 0 0 0 0 $_TARGETNAME @end example +If you use OTP (One-Time Programmable) memory define it as a second bank +as per the following example. +@example +flash bank $_FLASHNAME stm32f2x 0x1FFF7800 0 0 0 $_TARGETNAME +@end example + +@deffn Command {stm32f2x otp } num (@option{enable}|@option{disable}|@option{show}) +Enables or disables OTP write commands for bank @var{num}. +The @var{num} parameter is a value shown by @command{flash banks}. +@end deffn + Note that some devices have been found that have a flash size register that contains an invalid value, to workaround this issue you can override the probed value used by the flash driver. @@ -8925,12 +8941,8 @@ Initialize core debug Enables debug by unlocking the Software Lock and clearing sticky powerdown indications @end deffn -@deffn Command {cortex_a smp_off} -Disable SMP mode -@end deffn - -@deffn Command {cortex_a smp_on} -Enable SMP mode +@deffn Command {cortex_a smp} [on|off] +Display/set the current SMP mode @end deffn @deffn Command {cortex_a smp_gdb} [core_id] @@ -9141,8 +9153,8 @@ target code relies on. In a configuration file, the command would typically be c However, normally it is not necessary to use the command at all. @end deffn -@deffn Command {aarch64 smp_on|smp_off} -Enable and disable SMP handling. The state of SMP handling influences the way targets in an SMP group +@deffn Command {aarch64 smp} [on|off] +Display, enable or disable SMP handling mode. The state of SMP handling influences the way targets in an SMP group are handled by the run control. With SMP handling enabled, issuing halt or resume to one core will trigger halting or resuming of all cores in the group. The command @code{target smp} defines which targets are in the SMP group. With SMP handling disabled, all targets need to be treated individually. @@ -9330,6 +9342,14 @@ be copied to an in-memory buffer identified by the @option{address} and @option{size} options using DMA. @end deffn +@deffn Command {$target_name catch_exc} [@option{off}|@option{sec_el1}|@option{sec_el3}|@option{nsec_el1}|@option{nsec_el2}]+ +Cause @command{$target_name} to halt when an exception is taken. Any combination of +Secure (sec) EL1/EL3 or Non-Secure (nsec) EL1/EL2 is valid. The target +@command{$target_name} will halt before taking the exception. In order to resume +the target, the exception catch must be disabled again with @command{$target_name catch_exc off}. +Issuing the command without options prints the current configuration. +@end deffn + @section Intel Architecture Intel Quark X10xx is the first product in the Quark family of SoCs. It is an IA-32 @@ -9443,6 +9463,14 @@ command can be used if OpenOCD gets this wrong, or a target implements custom CSRs. @end deffn +@deffn Command {riscv expose_custom} n0[-m0][,n1[-m1]]... +The RISC-V Debug Specification allows targets to expose custom registers +through abstract commands. (See Section 3.5.1.1 in that document.) This command +configures a list of inclusive ranges of those registers to expose. Number 0 +indicates the first custom register, whose abstract command number is 0xc000. +This command must be executed before `init`. +@end deffn + @deffn Command {riscv set_command_timeout_sec} [seconds] Set the wall-clock timeout (in seconds) for individual commands. The default should work fine for all but the slowest targets (eg. simulators). @@ -9463,6 +9491,17 @@ When on, prefer to use System Bus Access to access memory. When off, prefer to use the Program Buffer to access memory. @end deffn +@deffn Command {riscv set_ir} (@option{idcode}|@option{dtmcs}|@option{dmi}) [value] +Set the IR value for the specified JTAG register. This is useful, for +example, when using the existing JTAG interface on a Xilinx FPGA by +way of BSCANE2 primitives that only permit a limited selection of IR +values. + +When utilizing version 0.11 of the RISC-V Debug Specification, +@option{dtmcs} and @option{dmi} set the IR values for the DTMCONTROL +and DBUS registers, respectively. +@end deffn + @subsection RISC-V Authentication Commands The following commands can be used to authenticate to a RISC-V system. Eg. a @@ -10176,55 +10215,6 @@ 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 -For SMP support following GDB serial protocol packet have been defined : -@itemize @bullet -@item j - smp status request -@item J - smp set request -@end itemize - -OpenOCD implements : -@itemize @bullet -@item @option{jc} packet for reading core id displayed by -GDB connection. Reply is @option{XXXXXXXX} (8 hex digits giving core id) or - @option{E01} for target not smp. -@item @option{JcXXXXXXXX} (8 hex digits) packet for setting core id displayed at next GDB continue -(core id -1 is reserved for returning to normal resume mode). Reply @option{E01} -for target not smp or @option{OK} on success. -@end itemize - -Handling of this packet within GDB can be done : -@itemize @bullet -@item by the creation of an internal variable (i.e @option{_core}) by mean -of function allocate_computed_value allowing following GDB command. -@example -set $_core 1 -#Jc01 packet is sent -print $_core -#jc packet is sent and result is affected in $ -@end example - -@item by the usage of GDB maintenance command as described in following example (2 cpus in SMP with -core id 0 and 1 @pxref{definecputargetsworkinginsmp,,Define CPU targets working in SMP}). - -@example -# toggle0 : force display of coreid 0 -define toggle0 -maint packet Jc0 -continue -main packet Jc-1 -end -# toggle1 : force display of coreid 1 -define toggle1 -maint packet Jc1 -continue -main packet Jc-1 -end -@end example -@end itemize - @section RTOS Support @cindex RTOS Support @anchor{gdbrtossupport} @@ -10255,12 +10245,11 @@ Currently supported rtos's include: @item @option{mqx} @item @option{uCOS-III} @item @option{nuttx} +@item @option{hwthread} (This is not an actual RTOS. @xref{usingopenocdsmpwithgdb,,Using OpenOCD SMP with GDB}.) @end itemize -@quotation Note Before an RTOS can be detected, it must export certain symbols; otherwise, it cannot be used by OpenOCD. Below is a list of the required symbols for each supported RTOS. -@end quotation @table @code @item eCos symbols @@ -10307,6 +10296,72 @@ contrib/rtos-helpers/FreeRTOS-openocd.c contrib/rtos-helpers/uCOS-III-openocd.c @end table +@anchor{usingopenocdsmpwithgdb} +@section Using OpenOCD SMP with GDB +@cindex SMP +@cindex RTOS +@cindex hwthread +OpenOCD includes a pseudo RTOS called @emph{hwthread} that presents CPU cores +("hardware threads") in an SMP system as threads to GDB. With this extension, +GDB can be used to inspect the state of an SMP system in a natural way. +After halting the system, using the GDB command @command{info threads} will +list the context of each active CPU core in the system. GDB's @command{thread} +command can be used to switch the view to a different CPU core. +The @command{step} and @command{stepi} commands can be used to step a specific core +while other cores are free-running or remain halted, depending on the +scheduler-locking mode configured in GDB. + +@section Legacy SMP core switching support +@quotation Note +This method is deprecated in favor of the @emph{hwthread} pseudo RTOS. +@end quotation + +For SMP support following GDB serial protocol packet have been defined : +@itemize @bullet +@item j - smp status request +@item J - smp set request +@end itemize + +OpenOCD implements : +@itemize @bullet +@item @option{jc} packet for reading core id displayed by +GDB connection. Reply is @option{XXXXXXXX} (8 hex digits giving core id) or + @option{E01} for target not smp. +@item @option{JcXXXXXXXX} (8 hex digits) packet for setting core id displayed at next GDB continue +(core id -1 is reserved for returning to normal resume mode). Reply @option{E01} +for target not smp or @option{OK} on success. +@end itemize + +Handling of this packet within GDB can be done : +@itemize @bullet +@item by the creation of an internal variable (i.e @option{_core}) by mean +of function allocate_computed_value allowing following GDB command. +@example +set $_core 1 +#Jc01 packet is sent +print $_core +#jc packet is sent and result is affected in $ +@end example + +@item by the usage of GDB maintenance command as described in following example (2 cpus in SMP with +core id 0 and 1 @pxref{definecputargetsworkinginsmp,,Define CPU targets working in SMP}). + +@example +# toggle0 : force display of coreid 0 +define toggle0 +maint packet Jc0 +continue +main packet Jc-1 +end +# toggle1 : force display of coreid 1 +define toggle1 +maint packet Jc1 +continue +main packet Jc-1 +end +@end example +@end itemize + @node Tcl Scripting API @chapter Tcl Scripting API @cindex Tcl Scripting API