* Target library:: Target library
* Commands:: OpenOCD Commands
* Sample Scripts:: Sample Target Scripts
+* TFTP:: TFTP
* GDB and OpenOCD:: Using GDB and OpenOCD
* TCL and OpenOCD:: Using TCL and OpenOCD
* TCL scripting API:: Tcl scripting API
first target will be gdb_port, the second target will listen on gdb_port + 1, and so on.
@item @b{gdb_breakpoint_override} <@var{hard|soft|disabled}>
@cindex gdb_breakpoint_override
+@anchor{gdb_breakpoint_override}
@*Force breakpoint type for gdb 'break' commands.
The raison d'etre for this option is to support GDB GUI's without
a hard/soft breakpoint concept where the default OpenOCD and
@cindex gdb_memory_map
@*Set to <@var{enable}> to cause OpenOCD to send the memory configuration to gdb when
requested. gdb will then know when to set hardware breakpoints, and program flash
-using the gdb load command. @option{gdb_flash_program enable} (@xref{gdb_flash_program})
-will also need enabling for flash programming to work.
+using the gdb load command. @option{gdb_flash_program enable} will also need enabling
+for flash programming to work.
Default behaviour is <@var{enable}>
+@xref{gdb_flash_program}.
@item @b{gdb_flash_program} <@var{enable|disable}>
@cindex gdb_flash_program
@anchor{gdb_flash_program}
@cindex altium
Altium Universal JTAG cable.
@end itemize
-@item @b{parport_write_on_exit} <@var{on|off}>
+@item @b{parport_write_on_exit} <@var{on}|@var{off}>
@cindex parport_write_on_exit
@*This will configure the parallel driver to write a known value to the parallel
interface on exiting OpenOCD
@cindex ft2232_device_desc
@*The USB device description of the FTDI FT2232 device. If not specified, the FTDI
default value is used. This setting is only valid if compiled with FTD2XX support.
+@item @b{ft2232_serial} <@var{serial-number}>
+@cindex ft2232_serial
+@*The serial number of the FTDI FT2232 device. If not specified, the FTDI default
+values are used.
@item @b{ft2232_layout} <@var{name}>
@cindex ft2232_layout
@*The layout of the FT2232 GPIO signals used to control output-enables and reset
@item @b{cortex_m3}
@item @b{feroceon}
@item @b{xscale}
+@item @b{arm11}
@item @b{mips_m4k}
@end itemize
If you want to use a target board that is not on this list, see Adding a new
-target board
+target board.
+The @option{target types} command can be used to get the list of targets supported from within openocd.
Endianess may be @option{little} or @option{big}.
@option{pre_resume} or @option{gdb_program_config}.
@option{post_reset} and @option{reset} will produce the same results.
-@item @b{working_area} <@var{target#}> <@var{address}> <@var{size}>
-<@var{backup}|@var{nobackup}>
+@item @b{working_area} <@var{target#}> <@var{address}> <@var{size}> <@var{backup}|@var{nobackup}> [@option{virtual address}]
@cindex working_area
@*Specifies a working area for the debugger to use. This may be used to speed-up
downloads to target memory and flash operations, or to perform otherwise unavailable
Supported variants are @option{ixp42x}, @option{ixp45x}, @option{ixp46x},
@option{pxa250}, @option{pxa255}, @option{pxa26x}.
+@subsection arm11 options
+@cindex arm11 options
+
+@subsection mips_m4k options
+@cindex mips_m4k options
+Use variant @option{ejtag_srst} 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 reset configuration command to enable openocd hardware reset functionality.
+
@section Flash configuration
@cindex Flash configuration
@item @b{mflash bank} <@var{soc}> <@var{base}> <@var{chip_width}> <@var{bus_width}>
<@var{RST pin}> <@var{WP pin}> <@var{DPD pin}> <@var{target #}>
@cindex mflash bank
-Configures a mflash for <@var{soc}> host bank at <@var{base}>. <@var{chip_width}> and
+@*Configures a mflash for <@var{soc}> host bank at <@var{base}>. <@var{chip_width}> and
<@var{bus_width}> are bytes order. Pin number format is dependent on host GPIO calling convention.
If WP or DPD pin was not used, write -1. Currently, mflash bank support s3c2440 and pxa270.
@end itemize
@subsection Target state handling
@itemize @bullet
+@item @b{power} <@var{on}|@var{off}>
+@cindex reg
+@*Turn power switch to target on/off.
+No arguments: print status.
+
+
+@item @b{reg} [@option{#}|@option{name}] [value]
+@cindex reg
+@*Access a single register by its number[@option{#}] or by its [@option{name}].
+No arguments: list all available registers for the current target.
+Number or name argument: display a register
+Number or name and value arguments: set register value
+
@item @b{poll} [@option{on}|@option{off}]
@cindex poll
@*Poll the target for its current state. If the target is in debug mode, architecture
@*Immediately halt the target, and execute the reset script (works only with certain
configurations)
@end itemize
+
+@item @b{soft_reset_halt}
+@cindex reset
+@*Requesting target halt and executing a soft reset.
@end itemize
@subsection Memory access commands
+@itemize @bullet
+@item @b{meminfo}
+
+display available ram memory.
+@end itemize
These commands allow accesses of a specific size to the memory system:
@itemize @bullet
@item @b{mdw} <@var{addr}> [@var{count}]
@item @b{load_image} <@var{file}> <@var{address}> [@option{bin}|@option{ihex}|@option{elf}]
@cindex load_image
+@anchor{load_image}
@*Load image <@var{file}> to target memory at <@var{address}>
+@item @b{fast_load_image} <@var{file}> <@var{address}> [@option{bin}|@option{ihex}|@option{elf}]
+@cindex fast_load_image
+@anchor{fast_load_image}
+@*Normally you should be using @b{load_image} or GDB load. However, for
+testing purposes or when IO overhead is significant(OpenOCD running on embedded
+host), then storing the image in memory and uploading the image to the target
+can be a way to upload e.g. multiple debug sessions when the binary does not change.
+Arguments as @b{load_image}, but image is stored in OpenOCD host
+memory, i.e. does not affect target. This approach is also useful when profiling
+target programming performance as IO and target programming can easily be profiled
+seperately.
+@item @b{fast_load}
+@cindex fast_image
+@anchor{fast_image}
+@*Loads image stored in memory by @b{fast_load_image} to current target. Must be preceeded by fast_load_image.
@item @b{dump_image} <@var{file}> <@var{address}> <@var{size}>
@cindex dump_image
+@anchor{dump_image}
@*Dump <@var{size}> bytes of target memory starting at <@var{address}> to a
(binary) <@var{file}>.
@item @b{verify_image} <@var{file}> <@var{address}> [@option{bin}|@option{ihex}|@option{elf}]
This will first attempt comparison using a crc checksum, if this fails it will try a binary compare.
@end itemize
+@subsection Breakpoint commands
+@cindex Breakpoint commands
+@itemize @bullet
+@item @b{bp} <@var{addr}> <@var{len}> [@var{hw}]
+@cindex bp
+@*set breakpoint <address> <length> [hw]
+@item @b{rbp} <@var{addr}>
+@cindex rbp
+@*remove breakpoint <adress>
+@item @b{wp} <@var{addr}> <@var{len}> <@var{r}|@var{w}|@var{a}> [@var{value}] [@var{mask}]
+@cindex wp
+@*set watchpoint <address> <length> <r/w/a> [value] [mask]
+@item @b{rwp} <@var{addr}>
+@cindex rwp
+@*remove watchpoint <adress>
+@end itemize
+
@subsection Flash commands
@cindex Flash commands
@itemize @bullet
@option{flash erase_sector} using the same syntax.
@item @b{flash erase_sector} <@var{num}> <@var{first}> <@var{last}>
@cindex flash erase_sector
+@anchor{flash erase_sector}
@*Erase sectors at bank <@var{num}>, starting at sector <@var{first}> up to and including
<@var{last}>. Sector numbering starts at 0. Depending on the flash type, erasing may
require the protection to be disabled first (e.g. Intel Advanced Bootblock flash using
@*Erase sectors starting at <@var{address}> for <@var{length}> bytes
@item @b{flash write_bank} <@var{num}> <@var{file}> <@var{offset}>
@cindex flash write_bank
+@anchor{flash write_bank}
@*Write the binary <@var{file}> to flash bank <@var{num}>, starting at
<@option{offset}> bytes from the beginning of the bank.
@item @b{flash write_image} [@var{erase}] <@var{file}> [@var{offset}] [@var{type}]
@cindex flash write_image
+@anchor{flash write_image}
@*Write the image <@var{file}> to the current target's flash bank(s). A relocation
[@var{offset}] can be specified and the file [@var{type}] can be specified
explicitly as @option{bin} (binary), @option{ihex} (Intel hex), @option{elf}
The "-event" option less you specify a TCL command to occur when a specific event occurs.
+@subsubsection Other Target Commands
+@cindex Other Target Commands
+@itemize
+@item @b{profile} <@var{seconds}> <@var{gmon.out}>
+
+Profiling samples the CPU PC as quickly as OpenOCD is able, which will be used as a random sampling of PC.
+@end itemize
+
@subsection Target Events
@cindex Target Events
safe for all but ARM7TDMI--S cores (like Philips LPC).
@item @b{arm7_9 fast_memory_access} <@var{enable}|@var{disable}>
@cindex arm7_9 fast_memory_access
+@anchor{arm7_9 fast_memory_access}
@*Allow OpenOCD to read and write memory without checking completion of
the operation. This provides a huge speed increase, especially with USB JTAG
cables (FT2232), but might be unsafe if used with targets running at a very low
@*Enable/disable target debugmsgs requests. debugmsgs enable messages to be sent to the debugger while the target is running.
@end itemize
+@node TFTP
+@chapter TFTP
+@cindex TFTP
+If OpenOCD runs on an embedded host(as ZY1000 does), then tftp can
+be used to access files on PCs(either developer PC or some other PC).
+
+The way this works is to prefix a filename by "/tftp/ip/" and append
+the tftp path on the tftp server(tftpd). E.g. "load_image /tftp/10.0.0.96/c:\temp\abc.elf"
+will load c:\temp\abc.elf from the developer pc (10.0.0.96) into memory as
+if the file was hosted on the embedded host.
+
+In order to achieve decent performance, you must choose a tftp server
+that supports a packet size bigger than the default packet size(512 bytes). There
+are numerous tftp servers out there(free and commercial) and you will have to do
+a bit of googling to find something that fits your requirements.
+
@node Sample Scripts
@chapter Sample Scripts
@cindex scripts
Informing gdb of the memory map of the target will enable gdb to protect any
flash area of the target and use hardware breakpoints by default. This means
that the OpenOCD option @option{gdb_breakpoint_override} is not required when
-using a memory map.
+using a memory map. @xref{gdb_breakpoint_override}.
To view the configured memory map in gdb, use the gdb command @option{info mem}
All other unasigned addresses within gdb are treated as RAM.
Low level commands are prefixed with "openocd_", e.g. openocd_flash_banks
is the low level API upon which "flash banks" is implemented.
+@itemize @bullet
+@item @b{ocd_mem2array} <@var{varname}> <@var{width}> <@var{addr}> <@var{nelems}>
+
+Read memory and return as a TCL array for script processing
+@item @b{ocd_array2mem} <@var{varname}> <@var{width}> <@var{addr}> <@var{nelems}>
+
+Convert a TCL array to memory locations and write the values
+@item @b{ocd_flash_banks} <@var{driver}> <@var{base}> <@var{size}> <@var{chip_width}> <@var{bus_width}> <@var{target}> [@option{driver options} ...]
+
+Return information about the flash banks
+@end itemize
+
OpenOCD commands can consist of two words, e.g. "flash banks". The
startup.tcl "unknown" proc will translate this into a tcl proc
called "flash_banks".
@itemize @bullet
@item @b{load_binary}
@cindex load_binary
-@*use @option{load_image} command with same args
+@*use @option{load_image} command with same args. @xref{load_image}.
@item @b{target}
@cindex target
@*@option{target} no longer take the reset_init, reset_run, run_and_halt, run_and_init. The @option{reset} command
always does a @option{reset run} when passed no arguments.
@item @b{dump_binary}
@cindex dump_binary
-@*use @option{dump_image} command with same args
+@*use @option{dump_image} command with same args. @xref{dump_image}.
@item @b{flash erase}
@cindex flash erase
-@*use @option{flash erase_sector} command with same args
+@*use @option{flash erase_sector} command with same args. @xref{flash erase_sector}.
@item @b{flash write}
@cindex flash write
-@*use @option{flash write_bank} command with same args
+@*use @option{flash write_bank} command with same args. @xref{flash write_bank}.
@item @b{flash write_binary}
@cindex flash write_binary
-@*use @option{flash write_bank} command with same args
+@*use @option{flash write_bank} command with same args. @xref{flash write_bank}.
@item @b{arm7_9 fast_writes}
@cindex arm7_9 fast_writes
-@*use @option{arm7_9 fast_memory_access} command with same args
+@*use @option{arm7_9 fast_memory_access} command with same args. @xref{arm7_9 fast_memory_access}.
@item @b{flash auto_erase}
@cindex flash auto_erase
-@*use @option{flash write_image} command passing @option{erase} as the first parameter.
+@*use @option{flash write_image} command passing @option{erase} as the first parameter. @xref{flash write_image}.
@item @b{daemon_startup}
@cindex daemon_startup
@*this config option has been removed, simply adding @option{init} and @option{reset halt} to
and @option{target cortex_m3 little reset_halt 0}.
@item @b{arm7_9 sw_bkpts}
@cindex arm7_9 sw_bkpts
-@*On by default. See also @option{gdb_breakpoint_override}.
+@*On by default. See also @option{gdb_breakpoint_override}. @xref{gdb_breakpoint_override}.
@item @b{arm7_9 force_hw_bkpts}
@cindex arm7_9 force_hw_bkpts
@*Use @option{gdb_breakpoint_override} instead. Note that GDB will use hardware breakpoints
for flash if the gdb memory map has been set up(default when flash is declared in
-target configuration).
+target configuration). @xref{gdb_breakpoint_override}.
@item @b{run_and_halt_time}
@cindex run_and_halt_time
@*This command has been removed for simpler reset behaviour, it can be simulated with the
@chapter FAQ
@cindex faq
@enumerate
+@item Why does not backslashes in paths under Windows doesn't work?
+
+OpenOCD uses Tcl and a backslash is an escape char. Use @{ and @}
+around Windows filenames.
+
+@smallexample
+> echo \a
+
+> echo @{\a@}
+\a
+> echo "\a"
+
+>
+@end smallexample
+To
+
@item OpenOCD complains about a missing cygwin1.dll.
Make sure you have Cygwin installed, or at least a version of OpenOCD that
Code Review / openocd.git / blobdiff