target/cortex_m: allow setting the type of a breakpoint

[openocd.git] / doc / openocd.texi

diff --git a/doc/openocd.texi b/doc/openocd.texi
index d0a3d49b8d12b203437011812697258f53febf4a..a4724460783cd7db943db66ed03070ba771949ae 100644 (file)
--- a/doc/openocd.texi
+++ b/doc/openocd.texi
@@ -2200,6 +2200,13 @@ The default behaviour is @option{disable};
 use @option{enable} see these errors reported.
 @end deffn
 
+@deffn {Config Command} gdb_report_register_access_error (@option{enable}|@option{disable})
+Specifies whether register accesses requested by GDB register read/write
+packets report errors or not.
+The default behaviour is @option{disable};
+use @option{enable} see these errors reported.
+@end deffn
+
 @deffn {Config Command} gdb_target_description (@option{enable}|@option{disable})
 Set to @option{enable} to cause OpenOCD to send the target descriptions to gdb via qXfer:features:read packet.
 The default behaviour is @option{enable}.
@@ -3779,6 +3786,11 @@ a TAP doesn't conform to the JTAG specification.
 to verify that instruction scans work correctly.
 Such scans are not used by OpenOCD except to verify that
 there seems to be no problems with JTAG scan chain operations.
+@item @code{-ignore-syspwrupack}
+@*Specify this to ignore the CSYSPWRUPACK bit in the ARM DAP DP CTRL/STAT
+register during initial examination and when checking the sticky error bit.
+This bit is normally checked after setting the CSYSPWRUPREQ bit, but some
+devices do not set the ack bit until sometime later.
 @end itemize
 @end deffn
 
@@ -4014,11 +4026,21 @@ instead of "@option{-chain-position} @var{dotted.name}" when the target is creat
 
 The @command{dap} command group supports the following sub-commands:
 
-@deffn Command {dap create} dap_name @option{-chain-position} dotted.name
+@deffn Command {dap create} dap_name @option{-chain-position} dotted.name configparams...
 Declare a DAP instance named @var{dap_name} linked to the JTAG tap
 @var{dotted.name}. This also creates a new command (@command{dap_name})
 which is used for various purposes including additional configuration.
 There can only be one DAP for each JTAG tap in the system.
+
+A DAP may also provide optional @var{configparams}:
+
+@itemize @bullet
+@item @code{-ignore-syspwrupack}
+@*Specify this to ignore the CSYSPWRUPACK bit in the ARM DAP DP CTRL/STAT
+register during initial examination and when checking the sticky error bit.
+This bit is normally checked after setting the CSYSPWRUPREQ bit, but some
+devices do not set the ack bit until sometime later.
+@end itemize
 @end deffn
 
 @deffn Command {dap names}
@@ -4048,6 +4070,7 @@ defaulting to the currently selected AP.
 Displays ID register from AP @var{num}, defaulting to the currently selected AP.
 @end deffn
 
+@anchor{DAP subcommand apreg}
 @deffn Command {$dap_name apreg} ap_num reg [value]
 Displays content of a register @var{reg} from AP @var{ap_num}
 or set a new value @var{value}.
@@ -4069,9 +4092,47 @@ memory bus access [0-255], giving additional time to respond to reads.
 If @var{value} is defined, first assigns that.
 @end deffn
 
-@deffn Command {$dap_name apcsw} [0 / 1]
-fix CSW_SPROT from register AP_REG_CSW on selected dap.
-Defaulting to 0.
+@deffn Command {$dap_name apcsw} [value [mask]]
+Displays or changes CSW bit pattern for MEM-AP transfers.
+
+At the begin of each memory access the CSW pattern is extended (bitwise or-ed)
+by @dfn{Size} and @dfn{AddrInc} bit-fields according to transfer requirements
+and the result is written to the real CSW register. All bits except dynamically
+updated fields @dfn{Size} and @dfn{AddrInc} can be changed by changing
+the CSW pattern. Refer to ARM ADI v5 manual chapter 7.6.4 and appendix A
+for details.
+
+Use @var{value} only syntax if you want to set the new CSW pattern as a whole.
+The example sets HPROT1 bit (required by Cortex-M) and clears the rest of
+the pattern:
+@example
+kx.dap apcsw 0x2000000
+@end example
+
+If @var{mask} is also used, the CSW pattern is changed only on bit positions
+where the mask bit is 1. The following example sets HPROT3 (cacheable)
+and leaves the rest of the pattern intact. It configures memory access through
+DCache on Cortex-M7.
+@example
+set CSW_HPROT3_CACHEABLE [expr 1 << 27]
+samv.dap apcsw $CSW_HPROT3_CACHEABLE $CSW_HPROT3_CACHEABLE
+@end example
+
+Another example clears SPROT bit and leaves the rest of pattern intact:
+@example
+set CSW_SPROT [expr 1 << 30]
+samv.dap apcsw 0 $CSW_SPROT
+@end example
+
+@emph{Note:} If you want to check the real value of CSW, not CSW pattern, use
+@code{xxx.dap apreg 0}. @xref{DAP subcommand apreg,,}.
+
+@emph{Warning:} Some of the CSW bits are vital for working memory transfer.
+If you set a wrong CSW pattern and MEM-AP stopped working, use the following
+example with a proper dap name:
+@example
+xxx.dap apcsw default
+@end example
 @end deffn
 
 @deffn Command {$dap_name ti_be_32_quirks} [@option{enable}]
@@ -8569,9 +8630,10 @@ the next instruction where the core was halted. After the step interrupts
 are enabled again. If the interrupt handlers don't complete within 500ms,
 the step command leaves with the core running.
 
-Note that a free breakpoint is required for the @option{auto} option. If no
-breakpoint is available at the time of the step, then the step is taken
-with interrupts enabled, i.e. the same way the @option{off} option does.
+Note that a free hardware (FPB) breakpoint is required for the @option{auto}
+option. If no breakpoint is available at the time of the step, then the step
+is taken with interrupts enabled, i.e. the same way the @option{off} option
+does.
 
 Default is @option{auto}.
 @end deffn