At no time should the name ``target0'' (the default target name if
none was specified) be used. The name ``target0'' is a hard coded name
- the next target on the board will be some other number.
+In the same way, avoid using target numbers even when they are
+permitted; use the right target name(s) for your board.
The user (or board file) should reasonably be able to:
@item @b{cpu}
@item @b{flash}
@item @b{bs}
+@item @b{etb}
@item @b{jrc}
@item @b{unknownN} - it happens :-(
@end itemize
If present, the MMU, the MPU and the CACHE should be disabled.
+Some ARM cores are equipped with trace support, which permits
+examination of the instruction and data bus activity. Trace
+activity is controlled through an ``Embedded Trace Module'' (ETM)
+on one of the core's scan chains. The ETM emits voluminous data
+through a ``trace port''. The trace port is accessed in one
+of two ways. When its signals are pinned out from the chip,
+boards may provide a special high speed debugging connector;
+software support for this is not configured by default, use
+the ``--enable-oocd_trace'' option. Alternatively, trace data
+may be stored an on-chip SRAM which is packaged as an ``Embedded
+Trace Buffer'' (ETB). An ETB has its own TAP, usually right after
+its associated ARM core. OpenOCD supports the ETM, and your
+target configuration should set it up with the relevant trace
+port: ``etb'' for chips which use that, else the board-specific
+option will be either ``oocd_trace'' or ``dummy''.
+
+@example
+etm config $_TARGETNAME 16 normal full etb
+etb config $_TARGETNAME $_CHIPNAME.etb
+@end example
+
@subsection Internal Flash Configuration
This applies @b{ONLY TO MICROCONTROLLERS} that have flash built in.
@item @b{cpu} - the main CPU of the chip, alternatively @b{foo.arm} and @b{foo.dsp}
@item @b{flash} - if the chip has a flash tap, example: str912.flash
@item @b{bs} - for boundary scan if this is a seperate tap.
+@item @b{etb} - for an embedded trace buffer (example: an ARM ETB11)
@item @b{jrc} - for JTAG route controller (example: OMAP3530 found on Beagleboards)
@item @b{unknownN} - where N is a number if you have no idea what the tap is for
@item @b{Other names} - Freescale IMX31 has a SDMA (smart dma) with a JTAG tap, that tap should be called the ``sdma'' tap.
@item @b{Note: Deprecated} - Index Numbers
@* Prior to 28/nov/2008, JTAG taps where numbered from 0..N this
feature is still present, however its use is highly discouraged and
-should not be counted upon.
+should not be counted upon. Update all of your scripts to use
+TAP names rather than numbers.
@item @b{Multiple chips}
@* If your board has multiple chips, you should be
able to @b{source} two configuration files, in the proper order, and
@itemize @bullet
@item @b{NAME}
@* Is the name of the debug target. By convention it should be the tap
-DOTTED.NAME, this name is also used to create the target object
-command.
+DOTTED.NAME. This name is also used to create the target object
+command, and in other places the target needs to be identified.
@item @b{TYPE}
@* Specifies the target type, i.e.: ARM7TDMI, or Cortex-M3. Currently supported targets are:
@comment START types
@section Target Config/Cget Options
These options can be specified when the target is created, or later
via the configure option or to query the target via cget.
+
+You should specify a working area if you can; typically it uses some
+on-chip SRAM. Such a working area can speed up many things, including bulk
+writes to target memory; flash operations like checking to see if memory needs
+to be erased; GDB memory checksumming; and may help perform otherwise
+unavailable operations (like some coprocessor operations on ARM7/9 systems).
@itemize @bullet
@item @b{-type} - returns the target type
@item @b{-event NAME BODY} see Target events
-@item @b{-work-area-virt [ADDRESS]} specify/set the work area
-@item @b{-work-area-phys [ADDRESS]} specify/set the work area
+@item @b{-work-area-virt [ADDRESS]} specify/set the work area base address
+which will be used when an MMU is active.
+@item @b{-work-area-phys [ADDRESS]} specify/set the work area base address
+which will be used when an MMU is inactive.
@item @b{-work-area-size [ADDRESS]} specify/set the work area
-@item @b{-work-area-backup [0|1]} does the work area get backed up
+@item @b{-work-area-backup [0|1]} does the work area get backed up;
+by default, it doesn't. When possible, use a working_area that doesn't
+need to be backed up, since performing a backup slows down operations.
@item @b{-endian [big|little]}
@item @b{-variant [NAME]} some chips have variants OpenOCD needs to know about
@item @b{-chain-position DOTTED.NAME} the tap name this target refers to.
@end example
@* The target# is a the 0 based target numerical index.
-This command 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 operations (some
-coprocessor operations on ARM7/9 systems, for example). The last
-parameter decides whether the memory should be preserved
-(<@var{backup}>) or can simply be overwritten (<@var{nobackup}>). If
-possible, use a working_area that doesn't need to be backed up, as
-performing a backup slows down operation.
-
@node Flash Configuration
@chapter Flash programming
@cindex Flash Configuration
@example
@b{flash bank} <@var{driver}> <@var{base}> <@var{size}> <@var{chip_width}>
-<@var{bus_width}> <@var{target#}> [@var{driver_options ...}]
+<@var{bus_width}> <@var{target}> [@var{driver_options ...}]
@end example
@cindex flash bank
@*Configures a flash bank at <@var{base}> of <@var{size}> bytes and <@var{chip_width}>
on the flash chip.
@b{flash bank cfi} <@var{base}> <@var{size}> <@var{chip_width}> <@var{bus_width}>
-<@var{target#}> [@var{jedec_probe}|@var{x16_as_x8}]
-@*CFI flashes require the number of the target they're connected to as an additional
+<@var{target}> [@var{jedec_probe}|@var{x16_as_x8}]
+@*CFI flashes require the name or number of the target they're connected to
+as an additional
argument. The CFI driver makes use of a working area (specified for the target)
to significantly speed up operation.
@subsubsection lpc2000 options
@cindex lpc2000 options
-@b{flash bank lpc2000} <@var{base}> <@var{size}> 0 0 <@var{target#}> <@var{variant}>
+@b{flash bank lpc2000} <@var{base}> <@var{size}> 0 0 <@var{target}> <@var{variant}>
<@var{clock}> [@var{calc_checksum}]
@*LPC flashes don't require the chip and bus width to be specified. Additional
parameters are the <@var{variant}>, which may be @var{lpc2000_v1} (older LPC21xx and LPC22xx)
-or @var{lpc2000_v2} (LPC213x, LPC214x, LPC210[123], LPC23xx and LPC24xx), the number
-of the target this flash belongs to (first is 0), the frequency at which the core
+or @var{lpc2000_v2} (LPC213x, LPC214x, LPC210[123], LPC23xx and LPC24xx),
+the name or number of the target this flash belongs to (first is 0),
+the frequency at which the core
is currently running (in kHz - must be an integral number), and the optional keyword
@var{calc_checksum}, telling the driver to calculate a valid checksum for the exception
vector table.
@subsubsection at91sam7 options
@cindex at91sam7 options
-@b{flash bank at91sam7} 0 0 0 0 <@var{target#}>
-@*AT91SAM7 flashes only require the @var{target#}, all other values are looked up after
+@b{flash bank at91sam7} 0 0 0 0 <@var{target}>
+@*AT91SAM7 flashes only require the @var{target}, all other values are looked up after
reading the chip-id and type.
@subsubsection str7 options
@cindex str7 options
-@b{flash bank str7x} <@var{base}> <@var{size}> 0 0 <@var{target#}> <@var{variant}>
+@b{flash bank str7x} <@var{base}> <@var{size}> 0 0 <@var{target}> <@var{variant}>
@*variant can be either STR71x, STR73x or STR75x.
@subsubsection str9 options
@cindex str9 options
-@b{flash bank str9x} <@var{base}> <@var{size}> 0 0 <@var{target#}>
+@b{flash bank str9x} <@var{base}> <@var{size}> 0 0 <@var{target}>
@*The str9 needs the flash controller to be configured prior to Flash programming, e.g.
@example
str9x flash_config 0 4 2 0 0x80000
@subsubsection str9 options (str9xpec driver)
-@b{flash bank str9xpec} <@var{base}> <@var{size}> 0 0 <@var{target#}>
+@b{flash bank str9xpec} <@var{base}> <@var{size}> 0 0 <@var{target}>
@*Before using the flash commands the turbo mode must be enabled using str9xpec
@option{enable_turbo} <@var{num>.}
@subsubsection Stellaris (LM3Sxxx) options
@cindex Stellaris (LM3Sxxx) options
-@b{flash bank stellaris} <@var{base}> <@var{size}> 0 0 <@var{target#}>
-@*Stellaris flash plugin only require the @var{target#}.
+@b{flash bank stellaris} <@var{base}> <@var{size}> 0 0 <@var{target}>
+@*Stellaris flash plugin only require the @var{target}.
@subsubsection stm32x options
@cindex stm32x options
-@b{flash bank stm32x} <@var{base}> <@var{size}> 0 0 <@var{target#}>
-@*stm32x flash plugin only require the @var{target#}.
+@b{flash bank stm32x} <@var{base}> <@var{size}> 0 0 <@var{target}>
+@*stm32x flash plugin only require the @var{target}.
@subsubsection aduc702x options
@cindex aduc702x options
-@b{flash bank aduc702x} 0 0 0 0 <@var{target#}>
-@*The aduc702x flash plugin works with Analog Devices model numbers ADUC7019 through ADUC7028. The setup command only requires the @var{target#} argument (all devices in this family have the same memory layout).
+@b{flash bank aduc702x} 0 0 0 0 <@var{target}>
+@*The aduc702x flash plugin works with Analog Devices model numbers ADUC7019 through ADUC7028. The setup command only requires the @var{target} argument (all devices in this family have the same memory layout).
@subsection mFlash Configuration
@cindex mFlash Configuration
@b{mflash bank} <@var{soc}> <@var{base}> <@var{chip_width}> <@var{bus_width}>
-<@var{RST pin}> <@var{WP pin}> <@var{DPD pin}> <@var{target #}>
+<@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 <@var{bus_width}> are bytes
openocd -c "fast enable" -c "interface dummy" -f target/str710.cfg
@end example
+@subsection echo <@var{message}>
+@cindex echo
+@*Output message to stdio. e.g. echo "Programming - please wait"
+
@subsection log_output <@var{file}>
@cindex log_output
@*Redirect logging to <file> (default: stderr)
@*Enable the use of the debug communications channel (DCC) to write larger (>128 byte)
amounts of memory. DCC downloads offer a huge speed increase, but might be potentially
unsafe, especially with targets running at very low speeds. This command was introduced
-with OpenOCD rev. 60.
+with OpenOCD rev. 60, and requires a few bytes of working area.
@end itemize
@subsection ARM720T specific commands
Code Review / openocd.git / blobdiff