flash: add padded_value cmd
[openocd.git] / doc / openocd.texi
index 8373593..a2bcaf8 100644 (file)
@@ -410,8 +410,12 @@ to be available anymore as of April 2012.
 (OpenHardware).
 @item @b{JTAG-lock-pick Tiny 2}
 @* Link @url{http://www.distortec.com/jtag-lock-pick-tiny-2} FT232H-based
-@end itemize
 
+@item @b{GW16042}
+@* Link: @url{http://shop.gateworks.com/index.php?route=product/product&path=70_80&product_id=64}
+FT2232H-based
+
+@end itemize
 @section USB-JTAG / Altera USB-Blaster compatibles
 
 These devices also show up as FTDI devices, but are not
@@ -534,9 +538,6 @@ produced, PDF schematics are easily found and it is easy to make.
 @item @b{Amontec - JTAG Accelerator}
 @* Link: @url{http://www.amontec.com/jtag_accelerator.shtml}
 
-@item @b{GW16402}
-@* Link: @url{http://www.gateworks.com/products/avila_accessories/gw16042.php}
-
 @item @b{Wiggler2}
 @* Link: @url{http://www.ccac.rwth-aachen.de/~michaels/index.php/hardware/armjtag}
 
@@ -577,6 +578,10 @@ produced, PDF schematics are easily found and it is easy to make.
 @item @b{bcm2835gpio}
 @* A BCM2835-based board (e.g. Raspberry Pi) using the GPIO pins of the expansion header.
 
+@item @b{jtag_vpi}
+@* A JTAG driver acting as a client for the JTAG VPI server interface.
+@* Link: @url{http://github.com/fjullien/jtag_vpi}
+
 @end itemize
 
 @node About Jim-Tcl
@@ -1305,23 +1310,23 @@ hilscher_nxhx500_re.cfg   opendous_ftdi.cfg          vsllink.cfg
 hilscher_nxhx50_etm.cfg   openocd-usb.cfg            xds100v2.cfg
 
 interface/ftdi:
-axm0432.cfg               icebear.cfg                oocdlink.cfg
-calao-usb-a9260-c01.cfg   jtagkey2.cfg               opendous_ftdi.cfg
-calao-usb-a9260-c02.cfg   jtagkey2p.cfg              openocd-usb.cfg
-cortino.cfg               jtagkey.cfg                openocd-usb-hs.cfg
-dlp-usb1232h.cfg          jtag-lock-pick_tiny_2.cfg  openrd.cfg
-dp_busblaster.cfg         kt-link.cfg                redbee-econotag.cfg
-flossjtag.cfg             lisa-l.cfg                 redbee-usb.cfg
-flossjtag-noeeprom.cfg    luminary.cfg               sheevaplug.cfg
-flyswatter2.cfg           luminary-icdi.cfg          signalyzer.cfg
-flyswatter.cfg            luminary-lm3s811.cfg       signalyzer-lite.cfg
+axm0432.cfg               hitex_str9-comstick.cfg    olimex-jtag-tiny.cfg
+calao-usb-a9260-c01.cfg   icebear.cfg                oocdlink.cfg
+calao-usb-a9260-c02.cfg   jtagkey2.cfg               opendous_ftdi.cfg
+cortino.cfg               jtagkey2p.cfg              openocd-usb.cfg
+dlp-usb1232h.cfg          jtagkey.cfg                openocd-usb-hs.cfg
+dp_busblaster.cfg         jtag-lock-pick_tiny_2.cfg  openrd.cfg
+flossjtag.cfg             kt-link.cfg                redbee-econotag.cfg
+flossjtag-noeeprom.cfg    lisa-l.cfg                 redbee-usb.cfg
+flyswatter2.cfg           luminary.cfg               sheevaplug.cfg
+flyswatter.cfg            luminary-icdi.cfg          signalyzer.cfg
+gw16042.cfg               luminary-lm3s811.cfg       signalyzer-lite.cfg
 hilscher_nxhx10_etm.cfg   minimodule.cfg             stm32-stick.cfg
 hilscher_nxhx500_etm.cfg  neodb.cfg                  turtelizer2-revB.cfg
 hilscher_nxhx500_re.cfg   ngxtech.cfg                turtelizer2-revC.cfg
 hilscher_nxhx50_etm.cfg   olimex-arm-usb-ocd.cfg     vpaclink.cfg
 hilscher_nxhx50_re.cfg    olimex-arm-usb-ocd-h.cfg   xds100v2.cfg
 hitex_lpc1768stick.cfg    olimex-arm-usb-tiny-h.cfg
-hitex_str9-comstick.cfg   olimex-jtag-tiny.cfg
 $
 @end example
 @item @file{board} ...
@@ -2353,6 +2358,17 @@ 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{disable}.
+@end deffn
+
+@deffn {Command} gdb_save_tdesc
+Saves the target descripton file to the local file system.
+
+The file name is @i{target_name}.xml.
+@end deffn
+
 @anchor{eventpolling}
 @section Event Polling
 
@@ -3027,6 +3043,13 @@ The vendor ID and product ID of the device.
 @deffn {Config Command} {stlink_api} api_level
 Manually sets the stlink api used, valid options are 1 or 2. (@b{STLINK Only}).
 @end deffn
+
+@deffn {Config Command} {trace} output_file_path source_clock_hz
+Enable SWO tracing (if supported), trace data is appended to the specified
+output file and the file is created if it does not exist.  The source clock
+rate for the trace port must be specified, this is typically the CPU clock
+rate.
+@end deffn
 @end deffn
 
 @deffn {Interface Driver} {opendous}
@@ -3081,7 +3104,7 @@ version of OpenOCD.
 @deffn Command {transport select} transport_name
 Select which of the supported transports to use in this OpenOCD session.
 The transport must be supported by the debug adapter hardware and by the
-version of OPenOCD you are using (including the adapter's driver).
+version of OpenOCD you are using (including the adapter's driver).
 No arguments: returns name of session's selected transport.
 @end deffn
 
@@ -4156,6 +4179,17 @@ There are several variants defined:
 @code{pxa26x} ... instruction register length is 5 bits
 @item @code{pxa3xx} ... instruction register length is 11 bits
 @end itemize
+@item @code{openrisc} -- this is an OpenRISC 1000 core.
+The current implementation supports two JTAG TAP cores:
+@itemize @minus
+@item @code{OpenCores TAP} (See: @emph{http://opencores.org/project,jtag})
+@item @code{Altera Virtual JTAG TAP} (See: @emph{http://www.altera.com/literature/ug/ug_virtualjtag.pdf})
+@end itemize
+And two debug interfaces cores:
+@itemize @minus
+@item @code{Advanced debug interface} (See: @emph{http://opencores.org/project,adv_debug_sys})
+@item @code{SoC Debug Interface} (See: @emph{http://opencores.org/project,dbg_interface})
+@end itemize
 @end itemize
 @end deffn
 
@@ -4299,9 +4333,11 @@ base @var{address} to be used when an MMU is active.
 The value should normally correspond to a static mapping for the
 @code{-work-area-phys} address, set up by the current operating system.
 
+@anchor{rtostype}
 @item @code{-rtos} @var{rtos_type} -- enable rtos support for target,
 @var{rtos_type} can be one of @option{auto}|@option{eCos}|@option{ThreadX}|
-@option{FreeRTOS}|@option{linux}|@option{ChibiOS}|@option{embKernel}.
+@option{FreeRTOS}|@option{linux}|@option{ChibiOS}|@option{embKernel}
+@xref{gdbrtossupport,,RTOS Support}.
 
 @end itemize
 @end deffn
@@ -4826,6 +4862,12 @@ 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 padded_value} num value
+Sets the default value used for padding any image sections, This should
+normally match the flash bank erased value. If not specified by this
+comamnd or the flash driver then it defaults to 0xff.
+@end deffn
+
 @anchor{program}
 @deffn Command {program} filename [verify] [reset] [offset]
 This is a helper script that simplifies using OpenOCD as a standalone
@@ -7468,6 +7510,51 @@ the peripherals.
 @xref{targetevents,,Target Events}.
 @end deffn
 
+@section OpenRISC Architecture
+
+The OpenRISC CPU is a soft core. It is used in a programmable SoC which can be
+configured with any of the TAP / Debug Unit available.
+
+@subsection TAP and Debug Unit selection commands
+@deffn Command {tap_select} (@option{vjtag}|@option{mohor})
+Select between the Altera Virtual JTAG and Mohor TAP.
+@end deffn
+@deffn Command {du_select} (@option{adv}|@option{mohor}) [option]
+Select between the Advanced Debug Interface and the classic one.
+
+An option can be passed as a second argument to the debug unit.
+
+When using the Advanced Debug Interface, option = 1 means the RTL core is
+configured with ADBG_USE_HISPEED = 1. This configuration skips status checking
+between bytes while doing read or write bursts.
+@end deffn
+
+@subsection Registers commands
+@deffn Command {addreg} [name] [address] [feature] [reg_group]
+Add a new register in the cpu register list. This register will be
+included in the generated target descriptor file.
+
+@strong{[feature]} must be "org.gnu.gdb.or1k.group[0..10]".
+
+@strong{[reg_group]} can be anything. The default register list defines "system",
+ "dmmu", "immu", "dcache", "icache", "mac", "debug", "perf", "power", "pic"
+ and "timer" groups.
+
+@emph{example:}
+@example
+addreg rtest 0x1234 org.gnu.gdb.or1k.group0 system
+@end example
+
+
+@end deffn
+@deffn Command {readgroup} (@option{group})
+Display all registers in @emph{group}.
+
+@emph{group} can be "system",
+ "dmmu", "immu", "dcache", "icache", "mac", "debug", "perf", "power", "pic",
+ "timer" or any new group created with addreg command.
+@end deffn
+
 @anchor{softwaredebugmessagesandtracing}
 @section Software Debug Messages and Tracing
 @cindex Linux-ARM DCC support
@@ -8089,6 +8176,57 @@ end
 @end example
 @end itemize
 
+@section RTOS Support
+@cindex RTOS Support
+@anchor{gdbrtossupport}
+
+OpenOCD includes RTOS support, this will however need enabling as it defaults to disabled.
+It can be enabled by passing @option{-rtos} arg to the target @xref{rtostype,,RTOS Type}.
+
+@* An example setup is below:
+
+@example
+$_TARGETNAME configure -rtos auto
+@end example
+
+This will attempt to auto detect the RTOS within your application.
+
+Currently supported rtos's include:
+@itemize @bullet
+@item @option{eCos}
+@item @option{ThreadX}
+@item @option{FreeRTOS}
+@item @option{linux}
+@item @option{ChibiOS}
+@item @option{embKernel}
+@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
+Cyg_Thread::thread_list, Cyg_Scheduler_Base::current_thread.
+@item ThreadX symbols
+_tx_thread_current_ptr, _tx_thread_created_ptr, _tx_thread_created_count.
+@item FreeRTOS symbols
+pxCurrentTCB, pxReadyTasksLists, xDelayedTaskList1, xDelayedTaskList2,
+pxDelayedTaskList, pxOverflowDelayedTaskList, xPendingReadyList,
+xTasksWaitingTermination, xSuspendedTaskList, uxCurrentNumberOfTasks, uxTopUsedPriority.
+@item linux symbols
+init_task.
+@item ChibiOS symbols
+rlist, ch_debug, chSysInit.
+@item embKernel symbols
+Rtos::sCurrentTask, Rtos::sListReady, Rtos::sListSleep,
+Rtos::sListSuspended, Rtos::sMaxPriorities, Rtos::sCurrentTaskCount.
+@end table
+
+For most RTOS supported the above symbols will be exported by default. However for
+some, eg. FreeRTOS @option{xTasksWaitingTermination} is only exported
+if @option{INCLUDE_vTaskDelete} is defined during the build.
 
 @node Tcl Scripting API
 @chapter Tcl Scripting API