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
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
@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
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.
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
@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
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
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}
@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}
@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}
@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!),
@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
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
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,
@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}
@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
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.
@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
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
projects / openocd / blobdiff