X-Git-Url: https://review.openocd.org/gitweb?a=blobdiff_plain;f=doc%2Fopenocd.texi;h=a3ca12475bca36eae98d6096d1816c7cca1f0598;hb=18918a0423e04180f580a4a9453e190488aab17d;hp=9d1532b1c900a5837c0554c93f2fbb431f409ce7;hpb=b559b273b526b3077b3ca219eecc8df9f86efac0;p=openocd.git diff --git a/doc/openocd.texi b/doc/openocd.texi index 9d1532b1c9..a3ca12475b 100644 --- a/doc/openocd.texi +++ b/doc/openocd.texi @@ -21,7 +21,7 @@ of the Open On-Chip Debugger (OpenOCD). @itemize @bullet @item Copyright @copyright{} 2008 The OpenOCD Project @item Copyright @copyright{} 2007-2008 Spencer Oliver @email{spen@@spen-soft.co.uk} -@item Copyright @copyright{} 2008 Oyvind Harboe @email{oyvind.harboe@@zylin.com} +@item Copyright @copyright{} 2008-2010 Oyvind Harboe @email{oyvind.harboe@@zylin.com} @item Copyright @copyright{} 2008 Duane Ellis @email{openocd@@duaneellis.com} @item Copyright @copyright{} 2009-2010 David Brownell @end itemize @@ -332,7 +332,7 @@ and one can be used for a UART adapter at the same time the other one is used to provide a debug adapter. Also, some development boards integrate an FT2232 chip to serve as -a built-in low coast debug adapter and usb-to-serial solution. +a built-in low cost debug adapter and usb-to-serial solution. @itemize @bullet @item @b{usbjtag} @@ -537,7 +537,7 @@ command interpreter today is a mixture of (newer) JIM-Tcl commands, and (older) the orginal command interpreter. @item @b{Commands} -@* At the OpenOCD telnet command line (or via the GDB mon command) one +@* At the OpenOCD telnet command line (or via the GDB monitor command) one can type a Tcl for() loop, set variables, etc. Some of the commands documented in this guide are implemented as Tcl scripts, from a @file{startup.tcl} file internal to the server. @@ -590,6 +590,7 @@ Configuration files and scripts are searched for in @enumerate @item the current directory, @item any search dir specified on the command line using the @option{-s} option, +@item any search dir specified using the @command{add_script_search_dir} command, @item @file{$HOME/.openocd} (not on Windows), @item the site wide script library @file{$pkgdatadir/site} and @item the OpenOCD-supplied script library @file{$pkgdatadir/scripts}. @@ -2092,12 +2093,12 @@ target. @end deffn @deffn Command {interface_list} -List the interface drivers that have been built into +List the debug adapter drivers that have been built into the running copy of OpenOCD. @end deffn -@deffn Command {jtag interface} -Returns the name of the interface driver being used. +@deffn Command {adapter_name} +Returns the name of the debug adapter driver being used. @end deffn @section Interface Drivers @@ -2643,7 +2644,7 @@ needing to cope with both architecture and board specific constraints. @section Commands for Handling Resets -@deffn {Command} jtag_nsrst_assert_width milliseconds +@deffn {Command} adapter_nsrst_assert_width milliseconds Minimum amount of time (in milliseconds) OpenOCD should wait after asserting nSRST (active-low system reset) before allowing it to be deasserted. @@ -3431,7 +3432,7 @@ At this writing, the supported CPU types and variants are: @item @code{arm11} -- this is a generation of ARMv6 cores @item @code{arm720t} -- this is an ARMv4 core with an MMU @item @code{arm7tdmi} -- this is an ARMv4 core -@item @code{arm920t} -- this is an ARMv5 core with an MMU +@item @code{arm920t} -- this is an ARMv4 core with an MMU @item @code{arm926ejs} -- this is an ARMv5 core with an MMU @item @code{arm966e} -- this is an ARMv5 core @item @code{arm9tdmi} -- this is an ARMv4 core @@ -3453,14 +3454,6 @@ be detected and the normal reset behaviour used. @item @code{fa526} -- resembles arm920 (w/o Thumb) @item @code{feroceon} -- resembles arm926 @item @code{mips_m4k} -- a MIPS core. This supports one variant: -@itemize @minus -@item @code{ejtag_srst} ... Use this when debugging targets that do not -provide a functional SRST line on the EJTAG connector. This causes -OpenOCD to instead use an EJTAG software reset command to reset the -processor. -You still need to enable @option{srst} on the @command{reset_config} -command to enable OpenOCD hardware reset functionality. -@end itemize @item @code{xscale} -- this is actually an architecture, not a CPU type. It is based on the ARMv5 architecture. There are several variants defined: @@ -3791,7 +3784,8 @@ proc my_attach_proc @{ @} @{ mychip.cpu configure -event gdb-attach my_attach_proc mychip.cpu configure -event gdb-attach @{ echo "Reset..." - reset halt + # To make flash probe and gdb load to flash work we need a reset init. + reset init @} @end example @@ -3811,7 +3805,11 @@ The following target events are defined: @* Currently not used (goal: when JTAG examine starts) @end ignore @item @b{gdb-attach} -@* When GDB connects +@* 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. @item @b{gdb-detach} @* When GDB disconnects @item @b{gdb-end} @@ -4045,7 +4043,7 @@ specifies "to the end of the flash bank". The @var{num} parameter is a value shown by @command{flash banks}. @end deffn -@deffn Command {flash erase_address} [@option{pad}] address length +@deffn Command {flash erase_address} [@option{pad}] [@option{unlock}] address length Erase sectors starting at @var{address} for @var{length} bytes. Unless @option{pad} is specified, @math{address} must begin a flash sector, and @math{address + length - 1} must end a sector. @@ -4055,6 +4053,8 @@ The flash bank to use is inferred from the @var{address}, and the specified length must stay within that bank. As a special case, when @var{length} is zero and @var{address} is the start of the bank, the whole flash is erased. +If @option{unlock} is specified, then the flash is unprotected +before erase starts. @end deffn @deffn Command {flash fillw} address word length @@ -4129,9 +4129,8 @@ The @var{num} parameter is a value shown by @command{flash banks}. @deffn Command {flash info} num Print info about flash bank @var{num} The @var{num} parameter is a value shown by @command{flash banks}. -The information includes per-sector protect status, which may be -incorrect (outdated) unless you first issue a -@command{flash protect_check num} command. +This command will first query the hardware, it does not print cached +and possibly stale information. @end deffn @anchor{flash protect} @@ -4144,14 +4143,6 @@ specifies "to the end of the flash bank". The @var{num} parameter is a value shown by @command{flash banks}. @end deffn -@deffn Command {flash protect_check} num -Check protection state of sectors in flash bank @var{num}. -The @var{num} parameter is a value shown by @command{flash banks}. -@comment @option{flash erase_sector} using the same syntax. -This updates the protection information displayed by @option{flash info}. -(Code execution may have invalidated any state records kept by OpenOCD.) -@end deffn - @anchor{Flash Driver List} @section Flash Driver List As noted above, the @command{flash bank} command requires a driver name, @@ -4187,8 +4178,8 @@ To configure two adjacent banks of 16 MBytes each, both sixteen bits (two bytes) wide on a sixteen bit bus: @example -flash bank cfi 0x00000000 0x01000000 2 2 $_TARGETNAME -flash bank cfi 0x01000000 0x01000000 2 2 $_TARGETNAME +flash bank $_FLASHNAME cfi 0x00000000 0x01000000 2 2 $_TARGETNAME +flash bank $_FLASHNAME cfi 0x01000000 0x01000000 2 2 $_TARGETNAME @end example To configure one bank of 32 MBytes @@ -4196,7 +4187,7 @@ built from two sixteen bit (two byte) wide parts wired in parallel to create a thirty-two bit (four byte) bus with doubled throughput: @example -flash bank cfi 0x00000000 0x02000000 2 4 $_TARGETNAME +flash bank $_FLASHNAME cfi 0x00000000 0x02000000 2 4 $_TARGETNAME @end example @c "cfi part_id" disabled @@ -4212,7 +4203,7 @@ The setup command only requires the @var{target} argument since all devices in this family have the same memory layout. @example -flash bank aduc702x 0 0 0 0 $_TARGETNAME +flash bank $_FLASHNAME aduc702x 0 0 0 0 $_TARGETNAME @end example @end deffn @@ -4233,9 +4224,9 @@ the following fixed locations: @example # Flash bank 0 - all chips -flash bank at91sam3 0x00080000 0 1 1 $_TARGETNAME +flash bank $_FLASHNAME at91sam3 0x00080000 0 1 1 $_TARGETNAME # Flash bank 1 - only 256K chips -flash bank at91sam3 0x00100000 0 1 1 $_TARGETNAME +flash bank $_FLASHNAME at91sam3 0x00100000 0 1 1 $_TARGETNAME @end example Internally, the AT91SAM3 flash memory is organized as follows. @@ -4287,7 +4278,7 @@ recognizes a number of these chips using the chip identification register, and autoconfigures itself. @example -flash bank at91sam7 0 0 0 0 $_TARGETNAME +flash bank $_FLASHNAME at91sam7 0 0 0 0 $_TARGETNAME @end example For chips which are not recognized by the controller driver, you must @@ -4374,7 +4365,7 @@ with most tool chains @command{verify_image} will fail. LPC flashes don't require the chip and bus width to be specified. @example -flash bank lpc2000 0x0 0x7d000 0 0 $_TARGETNAME \ +flash bank $_FLASHNAME lpc2000 0x0 0x7d000 0 0 $_TARGETNAME \ lpc2000_v2 14765 calc_checksum @end example @@ -4392,7 +4383,7 @@ the programming clock rate in Hz. LPC flashes don't require the chip and bus width to be specified. @example -flash bank lpc288x 0 0 0 0 $_TARGETNAME 12000000 +flash bank $_FLASHNAME lpc288x 0 0 0 0 $_TARGETNAME 12000000 @end example @end deffn @@ -4425,7 +4416,7 @@ and not by the standard @code{flash protect} command. Example for a 125 MHz clock frequency: @example -flash bank lpc2900 0 0 0 0 $_TARGETNAME 125000 +flash bank $_FLASHNAME lpc2900 0 0 0 0 $_TARGETNAME 125000 @end example Some @code{lpc2900}-specific commands are defined. In the following command list, @@ -4523,17 +4514,17 @@ lpc2900 secure_jtag 0 @emph{No idea what this is, other than using some arm7/arm9 core.} @example -flash bank ocl 0 0 0 0 $_TARGETNAME +flash bank $_FLASHNAME ocl 0 0 0 0 $_TARGETNAME @end example @end deffn @deffn {Flash Driver} pic32mx The PIC32MX microcontrollers are based on the MIPS 4K cores, and integrate flash memory. -@emph{The current implementation is incomplete.} @example -flash bank pix32mx 0 0 0 0 $_TARGETNAME +flash bank $_FLASHNAME pix32mx 0x1fc00000 0 0 0 $_TARGETNAME +flash bank $_FLASHNAME pix32mx 0x1d000000 0 0 0 $_TARGETNAME @end example @comment numerous *disabled* commands are defined: @@ -4545,6 +4536,10 @@ Some pic32mx-specific commands are defined: Programs the specified 32-bit @var{value} at the given @var{address} in the specified chip @var{bank}. @end deffn +@deffn Command {pic32mx unlock} bank +Unlock and erase specified chip @var{bank}. +This will remove any Code Protection. +@end deffn @end deffn @deffn {Flash Driver} stellaris @@ -4558,7 +4553,7 @@ That seems pointless since the same effect can be had using the standard @command{flash erase_address} command.} @example -flash bank stellaris 0 0 0 0 $_TARGETNAME +flash bank $_FLASHNAME stellaris 0 0 0 0 $_TARGETNAME @end example @end deffn @@ -4584,7 +4579,7 @@ The driver automatically recognizes a number of these chips using the chip identification register, and autoconfigures itself. @example -flash bank stm32x 0 0 0 0 $_TARGETNAME +flash bank $_FLASHNAME stm32x 0 0 0 0 $_TARGETNAME @end example Some stm32x-specific commands @@ -4622,7 +4617,7 @@ The @var{str7x} driver defines one mandatory parameter, @var{variant}, which is either @code{STR71x}, @code{STR73x} or @code{STR75x}. @example -flash bank str7x 0x40000000 0x00040000 0 0 $_TARGETNAME STR71x +flash bank $_FLASHNAME str7x 0x40000000 0x00040000 0 0 $_TARGETNAME STR71x @end example @deffn Command {str7x disable_jtag} bank @@ -4638,7 +4633,7 @@ The str9 needs the flash controller to be configured using the @command{str9x flash_config} command prior to Flash programming. @example -flash bank str9x 0x40000000 0x00040000 0 0 $_TARGETNAME +flash bank $_FLASHNAME str9x 0x40000000 0x00040000 0 0 $_TARGETNAME str9x flash_config 0 4 2 0 0x80000 @end example @@ -4677,6 +4672,26 @@ the flash clock. @end deffn @end deffn +@deffn {Flash Driver} virtual +This is a special driver that maps a previously defined bank to another +address. All bank settings will be copied from the master physical bank. + +The @var{virtual} driver defines one mandatory parameters, + +@itemize +@item @var{master_bank} The bank that this virtual address refers to. +@end itemize + +So in the following example addresses 0xbfc00000 and 0x9fc00000 refer to +the flash bank defined at address 0x1fc00000. Any cmds executed on +the virtual banks are actually performed on the physical banks. +@example +flash bank $_FLASHNAME pic32mx 0x1fc00000 0 0 0 $_TARGETNAME +flash bank vbank0 virtual 0xbfc00000 0 0 0 $_TARGETNAME $_FLASHNAME +flash bank vbank1 virtual 0x9fc00000 0 0 0 $_TARGETNAME $_FLASHNAME +@end example +@end deffn + @subsection str9xpec driver @cindex str9xpec @@ -4788,13 +4803,13 @@ Currently, the mflash driver supports s3c2440 and pxa270. Example for s3c2440 mflash where @var{RST pin} is GPIO B1: @example -mflash bank s3c2440 0x10000000 1b 0 +mflash bank $_FLASHNAME s3c2440 0x10000000 1b 0 @end example Example for pxa270 mflash where @var{RST pin} is GPIO 43: @example -mflash bank pxa270 0x08000000 43 0 +mflash bank $_FLASHNAME pxa270 0x08000000 43 0 @end example @end deffn @@ -5404,6 +5419,10 @@ Redirect logging to @var{filename}; the initial log output channel is stderr. @end deffn +@deffn Command add_script_search_dir [directory] +Add @var{directory} to the file/script search path. +@end deffn + @anchor{Target State handling} @section Target State handling @cindex reset @@ -5665,10 +5684,20 @@ separately. @end deffn @anchor{load_image} -@deffn Command {load_image} filename address [@option{bin}|@option{ihex}|@option{elf}] -Load image from file @var{filename} to target memory at @var{address}. +@deffn Command {load_image} filename address [[@option{bin}|@option{ihex}|@option{elf}] @option{min_addr} @option{max_length}] +Load image from file @var{filename} to target memory offset by @var{address} from its load address. The file format may optionally be specified -(@option{bin}, @option{ihex}, or @option{elf}) +(@option{bin}, @option{ihex}, or @option{elf}). +In addition the following arguments may be specifed: +@var{min_addr} - ignore data below @var{min_addr} (this is w.r.t. to the target's load address + @var{address}) +@var{max_length} - maximum number of bytes to load. +@example +proc load_image_bin @{fname foffset address length @} @{ + # Load data from fname filename at foffset offset to + # target at address. Load at most length bytes. + load_image $fname [expr $address - $foffset] bin $address $length +@} +@end example @end deffn @deffn Command {test_image} filename [address [@option{bin}|@option{ihex}|@option{elf}]] @@ -7405,8 +7434,8 @@ has closed the connection to OpenOCD. This might be a GDB issue. @item @b{LPC2000 Flash} In the configuration file in the section where flash device configurations are described, there is a parameter for specifying the clock frequency -for LPC2000 internal flash devices (e.g. @option{flash bank lpc2000 -0x0 0x40000 0 0 0 lpc2000_v1 14746 calc_checksum}), which must be +for LPC2000 internal flash devices (e.g. @option{flash bank $_FLASHNAME lpc2000 +0x0 0x40000 0 0 $_TARGETNAME lpc2000_v1 14746 calc_checksum}), which must be specified in kilohertz. However, I do have a quartz crystal of a frequency that contains fractions of kilohertz (e.g. 14,745,600 Hz, i.e. 14,745.600 kHz). Is it possible to specify real numbers for the