X-Git-Url: https://review.openocd.org/gitweb?a=blobdiff_plain;f=doc%2Fopenocd.texi;h=e51de4de9108a01607e48faa8b6f5211c212eb00;hb=96549bf0121a7cff08885ddca22ab7a1c362ea24;hp=ea3db757ecaf60046554e7592ee3036c1982cd44;hpb=ee019bf5f896912761d4b16516bf562f9ffe52da;p=openocd.git diff --git a/doc/openocd.texi b/doc/openocd.texi index ea3db757ec..e51de4de91 100644 --- a/doc/openocd.texi +++ b/doc/openocd.texi @@ -156,9 +156,9 @@ USB-based, parallel port-based, and other standalone boxes that run OpenOCD internally. @xref{Debug Adapter Hardware}. @b{GDB Debug:} It allows ARM7 (ARM7TDMI and ARM720t), ARM9 (ARM920T, -ARM922T, ARM926EJ--S, ARM966E--S), XScale (PXA25x, IXP42x) and -Cortex-M3 (Stellaris LM3, ST STM32 and Energy Micro EFM32) based cores to be -debugged via the GDB protocol. +ARM922T, ARM926EJ--S, ARM966E--S), XScale (PXA25x, IXP42x), Cortex-M3 +(Stellaris LM3, ST STM32 and Energy Micro EFM32) and Intel Quark (x10xx) +based cores to be debugged via the GDB protocol. @b{Flash Programming:} Flash writing is supported for external CFI-compatible NOR flashes (Intel and AMD/Spansion command set) and several @@ -262,6 +262,25 @@ This document is a work-in-progress, but contributions would be welcome to fill in the gaps. All of the source files are provided in-tree, listed in the Doxyfile configuration at the top of the source tree. +@section Gerrit Review System + +All changes in the OpenOCD Git repository go through the web-based Gerrit +Code Review System: + +@uref{http://openocd.zylin.com/} + +After a one-time registration and repository setup, anyone can push commits +from their local Git repository directly into Gerrit. +All users and developers are encouraged to review, test, discuss and vote +for changes in Gerrit. The feedback provides the basis for a maintainer to +eventually submit the change to the main Git repository. + +The @file{HACKING} file, also available as the Patch Guide in the Doxygen +Developer Manual, contains basic information about how to connect a +repository to Gerrit, prepare and push patches. Patch authors are expected to +maintain their changes while they're in Gerrit, respond to feedback and if +necessary rework and push improved versions of the change. + @section OpenOCD Developer Mailing List The OpenOCD Developer Mailing List provides the primary means of @@ -269,10 +288,6 @@ communication between developers: @uref{https://lists.sourceforge.net/mailman/listinfo/openocd-devel} -Discuss and submit patches to this list. -The @file{HACKING} file contains basic information about how -to prepare patches. - @section OpenOCD Bug Database During the 0.4.x release cycle the OpenOCD project team began @@ -651,7 +666,9 @@ to benefit from new features and bugfixes in Jim-Tcl. Properly installing OpenOCD sets up your operating system to grant it access to the debug adapters. On Linux, this usually involves installing a file -in @file{/etc/udev/rules.d,} so OpenOCD has permissions. MS-Windows needs +in @file{/etc/udev/rules.d,} so OpenOCD has permissions. An example rules file +that works for many common adapters is shipped with OpenOCD in the +@file{contrib} directory. MS-Windows needs complex and confusing driver configuration for every peripheral. Such issues are unique to each operating system, and are not detailed in this User's Guide. @@ -2092,6 +2109,17 @@ For an example of this scheme see LPC2000 target config files. The @code{init_boards} procedure is a similar concept concerning board config files (@xref{theinitboardprocedure,,The init_board procedure}.) +@anchor{theinittargeteventsprocedure} +@subsection The init_target_events procedure +@cindex init_target_events procedure + +A special procedure called @code{init_target_events} is run just after +@code{init_targets} (@xref{theinittargetsprocedure,,The init_targets +procedure}.) and before @code{init_board} +(@xref{theinitboardprocedure,,The init_board procedure}.) It is used +to set up default target events for the targets that do not have those +events already assigned. + @subsection ARM Core Specific Hacks If the chip has a DCC, enable it. If the chip is an ARM9 with some @@ -2546,11 +2574,11 @@ and a specific set of GPIOs is used. @end deffn @deffn {Interface Driver} {cmsis-dap} -CMSIS-DAP compliant based adapter. +ARM CMSIS-DAP compliant based adapter. @deffn {Config Command} {cmsis_dap_vid_pid} [vid pid]+ The vendor ID and product ID of the CMSIS-DAP device. If not specified -known default values are used. +the driver will attempt to auto detect the CMSIS-DAP device. Currently, up to eight [@var{vid}, @var{pid}] pairs may be given, e.g. @example cmsis_dap_vid_pid 0xc251 0xf001 0x0d28 0x0204 @@ -2739,7 +2767,7 @@ minimal impact on the target system. Avoid floating inputs, conflicting outputs and initially asserted reset signals. @end deffn -@deffn {Config Command} {ftdi_layout_signal} name [@option{-data}|@option{-ndata} data_mask] [@option{-oe}|@option{-noe} oe_mask] +@deffn {Config Command} {ftdi_layout_signal} name [@option{-data}|@option{-ndata} data_mask] [@option{-oe}|@option{-noe} oe_mask] [@option{-alias}|@option{-nalias} name] Creates a signal with the specified @var{name}, controlled by one or more FTDI GPIO pins via a range of possible buffer connections. The masks are FTDI GPIO register bitmasks to tell the driver the connection and type of the output @@ -2762,6 +2790,10 @@ target without any buffer. The FTDI pin is then switched between output and input as necessary to provide the full set of low, high and Hi-Z characteristics. In all other cases, the pins specified in a signal definition are always driven by the FTDI. + +If @option{-alias} or @option{-nalias} is used, the signal is created +identical (or with data inverted) to an already specified signal +@var{name}. @end deffn @deffn {Command} {ftdi_set_signal} name @option{0}|@option{1}|@option{z} @@ -4560,13 +4592,14 @@ depending on whether the breakpoint is in RAM or read only memory. @item @b{gdb-end} @* When the target has halted and GDB is not doing anything (see early halt) @item @b{gdb-flash-erase-start} -@* Before the GDB flash process tries to erase the flash +@* Before the GDB flash process tries to erase the flash (default is +@code{reset init}) @item @b{gdb-flash-erase-end} @* After the GDB flash process has finished erasing the flash @item @b{gdb-flash-write-start} @* Before GDB writes to the flash @item @b{gdb-flash-write-end} -@* After GDB writes to the flash +@* After GDB writes to the flash (default is @code{reset halt}) @item @b{gdb-start} @* Before the target steps, gdb is trying to start/resume the target @item @b{halted} @@ -5144,9 +5177,10 @@ supported.} @end deffn @deffn {Flash Driver} lpc2000 -Most members of the LPC1700, LPC1800, LPC2000 and LPC4300 microcontroller -families from NXP include internal flash and use Cortex-M3 (LPC1700, LPC1800), -Cortex-M4 (LPC4300) or ARM7TDMI (LPC2000) cores. +All members of the LPC11(x)00 and LPC1300 microcontroller families and most members +of the LPC1700, LPC1800, LPC2000 and LPC4300 microcontroller families from NXP +include internal flash and use Cortex-M0 (LPC11(x)00), Cortex-M3 (LPC1300, LPC1700, +LPC1800), Cortex-M4 (LPC4300) or ARM7TDMI (LPC2000) cores. @quotation Note There are LPC2000 devices which are not supported by the @var{lpc2000} @@ -5163,8 +5197,11 @@ which must appear in the following order: @option{lpc2000_v1} (older LPC21xx and LPC22xx) @option{lpc2000_v2} (LPC213x, LPC214x, LPC210[123], LPC23xx and LPC24xx) @option{lpc1700} (LPC175x and LPC176x) -or @option{lpc4300} - available also as @option{lpc1800} alias (LPC18x[2357] and +@option{lpc4300} - available also as @option{lpc1800} alias (LPC18x[2357] and LPC43x[2357]) +@option{lpc1100} (LPC11(x)xx and LPC13xx) +or @option{auto} - automatically detects flash variant and size for LPC11(x)00, +LPC1300 and LPC1700 @item @var{clock_kHz} ... the frequency, in kiloHertz, at which the core is running @item @option{calc_checksum} ... optional (but you probably want to provide this!), @@ -5672,6 +5709,23 @@ unlock str9 device. @end deffn +@deffn {Flash Driver} nrf51 +All members of the nRF51 microcontroller families from Nordic Semiconductor +include internal flash and use ARM Cortex-M0 core. + +@example +flash bank $_FLASHNAME nrf51 0 0x00000000 0 0 $_TARGETNAME +@end example + +Some nrf51-specific commands are defined: + +@deffn Command {nrf51 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 +code. +@end deffn +@end deffn @section mFlash @@ -6357,7 +6411,7 @@ various operations. The current target may be changed by using @command{targets} command with the name of the target which should become current. -@deffn Command reg [(number|name) [value]] +@deffn Command reg [(number|name) [(value|'force')]] Access a single register by @var{number} or by its @var{name}. The target must generally be halted before access to CPU core registers is allowed. Depending on the hardware, some other @@ -6371,6 +6425,8 @@ which are also dirty (and will be written back later) are flagged as such. @emph{With number/name}: display that register's value. +Use @var{force} argument to read directly from the target, +bypassing any internal cache. @emph{With both number/name and value}: set register's value. Writes may be held in a writeback cache internal to OpenOCD, @@ -6675,10 +6731,12 @@ using @var{mask} to mark ``don't care'' fields. @section Misc Commands @cindex profiling -@deffn Command {profile} seconds filename +@deffn Command {profile} seconds filename [start end] Profiling samples the CPU's program counter as quickly as possible, which is useful for non-intrusive stochastic profiling. -Saves up to 10000 sampines in @file{filename} using ``gmon.out'' format. +Saves up to 10000 samples in @file{filename} using ``gmon.out'' +format. Optional @option{start} and @option{end} parameters allow to +limit the address range. @end deffn @deffn Command {version} @@ -7525,6 +7583,47 @@ the peripherals. @xref{targetevents,,Target Events}. @end deffn +@section Intel Architecture + +Intel Quark X10xx is the first product in the Quark family of SoCs. It is an IA-32 +(Pentium x86 ISA) compatible SoC. The core CPU in the X10xx is codenamed Lakemont. +Lakemont version 1 (LMT1) is used in X10xx. The CPU TAP (Lakemont TAP) is used for +software debug and the CLTAP is used for SoC level operations. +Useful docs are here: https://communities.intel.com/community/makers/documentation +@itemize +@item Intel Quark SoC X1000 OpenOCD/GDB/Eclipse App Note (web search for doc num 330015) +@item Intel Quark SoC X1000 Debug Operations User Guide (web search for doc num 329866) +@item Intel Quark SoC X1000 Datasheet (web search for doc num 329676) +@end itemize + +@subsection x86 32-bit specific commands +The three main address spaces for x86 are memory, I/O and configuration space. +These commands allow a user to read and write to the 64Kbyte I/O address space. + +@deffn Command {x86_32 idw} address +Display the contents of a 32-bit I/O port from address range 0x0000 - 0xffff. +@end deffn + +@deffn Command {x86_32 idh} address +Display the contents of a 16-bit I/O port from address range 0x0000 - 0xffff. +@end deffn + +@deffn Command {x86_32 idb} address +Display the contents of a 8-bit I/O port from address range 0x0000 - 0xffff. +@end deffn + +@deffn Command {x86_32 iww} address +Write the contents of a 32-bit I/O port to address range 0x0000 - 0xffff. +@end deffn + +@deffn Command {x86_32 iwh} address +Write the contents of a 16-bit I/O port to address range 0x0000 - 0xffff. +@end deffn + +@deffn Command {x86_32 iwb} address +Write the contents of a 8-bit I/O port to address range 0x0000 - 0xffff. +@end deffn + @section OpenRISC Architecture The OpenRISC CPU is a soft core. It is used in a programmable SoC which can be @@ -8352,7 +8451,7 @@ should be passed in to the proc in question. By "low-level," we mean commands that a human would typically not invoke directly. -Low-level commands are (should be) prefixed with "ocd_"; e.g. +Some low-level commands need to be prefixed with "ocd_"; e.g. @command{ocd_flash_banks} is the low-level API upon which @command{flash banks} is implemented. @@ -8366,6 +8465,16 @@ 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 + +@item @b{capture} <@var{command}> + +Run <@var{command}> and return full log output that was produced during +its execution. Example: + +@example +> capture "reset init" +@end example + @end itemize OpenOCD commands can consist of two words, e.g. "flash banks". The @@ -8400,6 +8509,24 @@ We should add support for a variable like Tcl variable is jim, not real tcl). @end quotation +@section Tcl RPC server +@cindex RPC + +OpenOCD provides a simple RPC server that allows to run arbitrary Tcl +commands and receive the results. + +To access it, your application needs to connect to a configured TCP port +(see @command{tcl_port}). Then it can pass any string to the +interpreter terminating it with @code{0x1a} and wait for the return +value (it will be terminated with @code{0x1a} as well). This can be +repeated as many times as desired without reopening the connection. + +Remember that most of the OpenOCD commands need to be prefixed with +@code{ocd_} to get the results back. Sometimes you might also need the +@command{capture} command. + +See @file{contrib/rpc_examples/} for specific client implementations. + @node FAQ @chapter FAQ @cindex faq