X-Git-Url: https://review.openocd.org/gitweb?p=openocd.git;a=blobdiff_plain;f=doc%2Fopenocd.texi;h=ebd03c4cb2b02b181d9cee5cb5fc1d65b941b8f3;hp=ac09db5e2ca9cee46c28d80a16a75b0d0d651d4a;hb=19f8f58c0d4d9ee618969254a368e4396657b946;hpb=fffe8e672572da46046b12a5d6b037057059393e diff --git a/doc/openocd.texi b/doc/openocd.texi index ac09db5e2c..ebd03c4cb2 100644 --- a/doc/openocd.texi +++ b/doc/openocd.texi @@ -682,7 +682,8 @@ bash$ openocd --help --version | -v display OpenOCD version --file | -f use configuration file --search | -s dir to search for config files and scripts ---debug | -d set debug level <0-3> +--debug | -d set debug level to 3 + | -d set debug level to --log_output | -l redirect log output to file --command | -c run @end verbatim @@ -2947,8 +2948,8 @@ Specifies the serial number of the adapter. Specifies the adapter layout to use. @end deffn -@deffn {Config Command} {hla_vid_pid} vid pid -The vendor ID and product ID of the device. +@deffn {Config Command} {hla_vid_pid} [vid pid]+ +Pairs of vendor IDs and product IDs of the device. @end deffn @deffn {Command} {hla_command} command @@ -4502,12 +4503,6 @@ and (if the target is using it) after SRST has been released on the scan chain. @item @b{reset-end} @* Issued as the final step in @command{reset} processing. -@ignore -@item @b{reset-halt-post} -@* Currently not used -@item @b{reset-halt-pre} -@* Currently not used -@end ignore @item @b{reset-init} @* Used by @b{reset init} command for board-specific initialization. This event fires after @emph{reset-deassert-post}. @@ -4524,12 +4519,6 @@ before @command{reset_init} 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, when reset disables PLLs needed to use a fast clock. -@ignore -@item @b{reset-wait-pos} -@* Currently not used -@item @b{reset-wait-pre} -@* Currently not used -@end ignore @item @b{resume-start} @* Before any target is resumed @item @b{resume-end} @@ -4715,15 +4704,18 @@ each block, and the specified length must stay within that bank. @end deffn @comment no current checks for errors if fill blocks touch multiple banks! -@deffn Command {flash write_bank} num filename offset +@deffn Command {flash write_bank} num filename [offset] Write the binary @file{filename} to flash bank @var{num}, -starting at @var{offset} bytes from the beginning of the bank. +starting at @var{offset} bytes from the beginning of the bank. If @var{offset} +is omitted, start at the beginning of the flash bank. The @var{num} parameter is a value shown by @command{flash banks}. @end deffn -@deffn Command {flash read_bank} num filename offset length +@deffn Command {flash read_bank} num filename [offset [length]] Read @var{length} bytes from the flash bank @var{num} starting at @var{offset} -and write the contents to the binary @file{filename}. +and write the contents to the binary @file{filename}. If @var{offset} is +omitted, start at the beginning of the flash bank. If @var{length} is omitted, +read the remaining bytes from the flash bank. The @var{num} parameter is a value shown by @command{flash banks}. @end deffn @@ -5368,10 +5360,21 @@ recognizes flash size and a number of flash banks (1-4) using the chip identification register, and autoconfigures itself. Use kinetis_ke driver for KE0x devices. +The @var{kinetis} driver defines option: +@itemize +@item -sim-base @var{addr} ... base of System Integration Module where chip identification resides. Driver tries two known locations if option is omitted. +@end itemize + @example flash bank $_FLASHNAME kinetis 0 0 0 0 $_TARGETNAME @end example +@deffn Command {kinetis create_banks} +Configuration command enables automatic creation of additional flash banks +based on real flash layout of device. Banks are created during device probe. +Use 'flash probe 0' to force probe. +@end deffn + @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 @@ -5752,17 +5755,19 @@ Show information about flash driver. @end deffn -@deffn {Flash Driver} nrf51 +@deffn {Flash Driver} nrf5 All members of the nRF51 microcontroller families from Nordic Semiconductor include internal flash and use ARM Cortex-M0 core. +Also, the nRF52832 microcontroller from Nordic Semiconductor, which include +internal flash and use an ARM Cortex-M4F core. @example -flash bank $_FLASHNAME nrf51 0 0x00000000 0 0 $_TARGETNAME +flash bank $_FLASHNAME nrf5 0 0x00000000 0 0 $_TARGETNAME @end example -Some nrf51-specific commands are defined: +Some nrf5-specific commands are defined: -@deffn Command {nrf51 mass_erase} +@deffn Command {nrf5 mass_erase} Erases the contents of the code memory and user information configuration registers as well. It must be noted that this command works only for chips that do not have factory pre-programmed region 0 @@ -5871,9 +5876,6 @@ All members of the Stellaris LM3Sxxx, LM4x and Tiva C microcontroller families from Texas Instruments include internal flash. The driver automatically recognizes a number of these chips using the chip identification register, and autoconfigures itself. -@footnote{Currently there is a @command{stellaris mass_erase} command. -That seems pointless since the same effect can be had using the -standard @command{flash erase_address} command.} @example flash bank $_FLASHNAME stellaris 0 0 0 0 $_TARGETNAME @@ -5919,11 +5921,7 @@ as per the following example. flash bank $_FLASHNAME stm32f1x 0x08080000 0 0 0 $_TARGETNAME @end example -Some stm32f1x-specific commands -@footnote{Currently there is a @command{stm32f1x mass_erase} command. -That seems pointless since the same effect can be had using the -standard @command{flash erase_address} command.} -are defined: +Some stm32f1x-specific commands are defined: @deffn Command {stm32f1x lock} num Locks the entire stm32 device. @@ -5935,6 +5933,11 @@ Unlocks the entire stm32 device. The @var{num} parameter is a value shown by @command{flash banks}. @end deffn +@deffn Command {stm32f1x mass_erase} num +Mass erases the entire stm32f1x device. +The @var{num} parameter is a value shown by @command{flash banks}. +@end deffn + @deffn Command {stm32f1x options_read} num Read and display the stm32 option bytes written by the @command{stm32f1x options_write} command. @@ -5953,6 +5956,10 @@ 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. +@example +flash bank $_FLASHNAME stm32f2x 0 0 0 0 $_TARGETNAME +@end example + 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. @@ -5973,17 +5980,63 @@ Unlocks the entire stm32 device. The @var{num} parameter is a value shown by @command{flash banks}. @end deffn +@deffn Command {stm32f2x mass_erase} num +Mass erases the entire stm32f2x 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. +Reads and displays user options and (where implemented) boot_addr0, boot_addr1, optcr2. 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). +The @var{num} parameter is a value shown by @command{flash banks}, @var{user_options} a +12 bit value, consisting of bits 31-28 and 7-0 of FLASH_OPTCR, @var{boot_addr0} and +@var{boot_addr1} two halfwords (of FLASH_OPTCR1). +@end deffn + +@deffn Command {stm32f2x optcr2_write} num optcr2 +Writes FLASH_OPTCR2 options. Warning: Clearing PCROPi bits requires a full mass erase! +The @var{num} parameter is a value shown by @command{flash banks}, @var{optcr2} a 32-bit word. +@end deffn +@end deffn + +@deffn {Flash Driver} stm32h7x +All members of the STM32H7 microcontroller families from ST Microelectronics +include internal flash and use ARM Cortex-M7 core. +The driver automatically recognizes a number of these chips using +the chip identification register, and autoconfigures itself. + +@example +flash bank $_FLASHNAME stm32h7x 0 0 0 0 $_TARGETNAME +@end example + +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. + +@example +flash bank $_FLASHNAME stm32h7x 0 0x20000 0 0 $_TARGETNAME +@end example + +Some stm32h7x-specific commands are defined: + +@deffn Command {stm32h7x lock} num +Locks the entire stm32 device. +The @var{num} parameter is a value shown by @command{flash banks}. +@end deffn + +@deffn Command {stm32h7x unlock} num +Unlocks the entire stm32 device. +The @var{num} parameter is a value shown by @command{flash banks}. +@end deffn + +@deffn Command {stm32h7x mass_erase} num +Mass erases the entire stm32h7x device. +The @var{num} parameter is a value shown by @command{flash banks}. @end deffn @end deffn @@ -5993,6 +6046,10 @@ include internal flash and use ARM Cortex-M3 and Cortex-M0+ cores. The driver automatically recognizes a number of these chips using the chip identification register, and autoconfigures itself. +@example +flash bank $_FLASHNAME stm32lx 0 0 0 0 $_TARGETNAME +@end example + 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. If you use 0 as the bank base address, it tells the @@ -6005,6 +6062,16 @@ flash bank $_FLASHNAME stm32lx 0x08000000 0x20000 0 0 $_TARGETNAME Some stm32lx-specific commands are defined: +@deffn Command {stm32lx lock} num +Locks the entire stm32 device. +The @var{num} parameter is a value shown by @command{flash banks}. +@end deffn + +@deffn Command {stm32lx unlock} num +Unlocks the entire stm32 device. +The @var{num} parameter is a value shown by @command{flash banks}. +@end deffn + @deffn Command {stm32lx mass_erase} num Mass erases the entire stm32lx device (all flash banks and EEPROM data). This is the only way to unlock a protected flash (unless RDP @@ -6013,6 +6080,42 @@ The @var{num} parameter is a value shown by @command{flash banks}. @end deffn @end deffn +@deffn {Flash Driver} stm32l4x +All members of the STM32L4 microcontroller families from ST Microelectronics +include internal flash and use ARM Cortex-M4 cores. +The driver automatically recognizes a number of these chips using +the chip identification register, and autoconfigures itself. + +@example +flash bank $_FLASHNAME stm32l4x 0 0 0 0 $_TARGETNAME +@end example + +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. + +@example +flash bank $_FLASHNAME stm32l4x 0x08000000 0x40000 0 0 $_TARGETNAME +@end example + +Some stm32l4x-specific commands are defined: + +@deffn Command {stm32l4x lock} num +Locks the entire stm32 device. +The @var{num} parameter is a value shown by @command{flash banks}. +@end deffn + +@deffn Command {stm32l4x unlock} num +Unlocks the entire stm32 device. +The @var{num} parameter is a value shown by @command{flash banks}. +@end deffn + +@deffn Command {stm32l4x mass_erase} num +Mass erases the entire stm32l4x device. +The @var{num} parameter is a value shown by @command{flash banks}. +@end deffn +@end deffn + @deffn {Flash Driver} str7x All members of the STR7 microcontroller family from ST Microelectronics include internal flash and use ARM7TDMI cores. @@ -6835,12 +6938,13 @@ non-zero exit code to the parent process. @deffn Command debug_level [n] @cindex message level Display debug level. -If @var{n} (from 0..3) is provided, then set it to that level. +If @var{n} (from 0..4) is provided, then set it to that level. This affects the kind of messages sent to the server log. Level 0 is error messages only; level 1 adds warnings; level 2 adds informational messages; -and level 3 adds debugging messages. +level 3 adds debugging messages; +and level 4 adds verbose low-level debug messages. The default is level 2, but that can be overridden on the command line along with the location of that log file (which is normally the server's standard output). @@ -7581,6 +7685,20 @@ requests by using a special SVC instruction that is trapped at the Supervisor Call vector by OpenOCD. @end deffn +@deffn Command {arm semihosting_cmdline} [@option{enable}|@option{disable}] +@cindex ARM semihosting +Set the command line to be passed to the debuggee. + +@example +arm semihosting_cmdline argv0 argv1 argv2 ... +@end example + +This option lets one set the command line arguments to be passed to +the program. The first argument (argv0) is the program name in a +standard C environment (argv[0]). Depending on the program (not much +programs look at argv[0]), argv0 is ignored and can be any string. +@end deffn + @deffn Command {arm semihosting_fileio} [@option{enable}|@option{disable}] @cindex ARM semihosting Display status of semihosting fileio, after optionally changing that