7100 lines
315 KiB
Plaintext
7100 lines
315 KiB
Plaintext
This is openocd.info, produced by makeinfo version 6.7 from
|
||
openocd.texi.
|
||
|
||
This User's Guide documents release 0.11.0+dev, dated 10 January 2022,
|
||
of the Open On-Chip Debugger (OpenOCD).
|
||
|
||
* Copyright (C) 2008 The OpenOCD Project
|
||
* Copyright (C) 2007-2008 Spencer Oliver <spen@spen-soft.co.uk>
|
||
* Copyright (C) 2008-2010 Oyvind Harboe <oyvind.harboe@zylin.com>
|
||
* Copyright (C) 2008 Duane Ellis <openocd@duaneellis.com>
|
||
* Copyright (C) 2009-2010 David Brownell
|
||
|
||
Permission is granted to copy, distribute and/or modify this
|
||
document under the terms of the GNU Free Documentation License,
|
||
Version 1.2 or any later version published by the Free Software
|
||
Foundation; with no Invariant Sections, no Front-Cover Texts, and
|
||
no Back-Cover Texts. A copy of the license is included in the
|
||
section entitled "GNU Free Documentation License".
|
||
INFO-DIR-SECTION Development
|
||
START-INFO-DIR-ENTRY
|
||
* OpenOCD: (openocd). OpenOCD User's Guide
|
||
END-INFO-DIR-ENTRY
|
||
|
||
|
||
File: openocd.info, Node: Top, Next: About, Up: (dir)
|
||
|
||
OpenOCD User's Guide
|
||
********************
|
||
|
||
This User's Guide documents release 0.11.0+dev, dated 10 January 2022,
|
||
of the Open On-Chip Debugger (OpenOCD).
|
||
|
||
* Copyright (C) 2008 The OpenOCD Project
|
||
* Copyright (C) 2007-2008 Spencer Oliver <spen@spen-soft.co.uk>
|
||
* Copyright (C) 2008-2010 Oyvind Harboe <oyvind.harboe@zylin.com>
|
||
* Copyright (C) 2008 Duane Ellis <openocd@duaneellis.com>
|
||
* Copyright (C) 2009-2010 David Brownell
|
||
|
||
Permission is granted to copy, distribute and/or modify this
|
||
document under the terms of the GNU Free Documentation License,
|
||
Version 1.2 or any later version published by the Free Software
|
||
Foundation; with no Invariant Sections, no Front-Cover Texts, and
|
||
no Back-Cover Texts. A copy of the license is included in the
|
||
section entitled "GNU Free Documentation License".
|
||
|
||
* Menu:
|
||
|
||
* About:: About OpenOCD
|
||
* Developers:: OpenOCD Developer Resources
|
||
* Debug Adapter Hardware:: Debug Adapter Hardware
|
||
* About Jim-Tcl:: About Jim-Tcl
|
||
* Running:: Running OpenOCD
|
||
* OpenOCD Project Setup:: OpenOCD Project Setup
|
||
* Config File Guidelines:: Config File Guidelines
|
||
* Server Configuration:: Server Configuration
|
||
* Debug Adapter Configuration:: Debug Adapter Configuration
|
||
* Reset Configuration:: Reset Configuration
|
||
* TAP Declaration:: TAP Declaration
|
||
* CPU Configuration:: CPU Configuration
|
||
* Flash Commands:: Flash Commands
|
||
* Flash Programming:: Flash Programming
|
||
* PLD/FPGA Commands:: PLD/FPGA Commands
|
||
* General Commands:: General Commands
|
||
* Architecture and Core Commands:: Architecture and Core Commands
|
||
* JTAG Commands:: JTAG Commands
|
||
* Boundary Scan Commands:: Boundary Scan Commands
|
||
* Utility Commands:: Utility Commands
|
||
* GDB and OpenOCD:: Using GDB and OpenOCD
|
||
* Tcl Scripting API:: Tcl Scripting API
|
||
* FAQ:: Frequently Asked Questions
|
||
* Tcl Crash Course:: Tcl Crash Course
|
||
* License:: GNU Free Documentation License
|
||
|
||
* OpenOCD Concept Index:: Concept Index
|
||
* Command and Driver Index:: Command and Driver Index
|
||
|
||
|
||
File: openocd.info, Node: About, Next: Developers, Prev: Top, Up: Top
|
||
|
||
About
|
||
*****
|
||
|
||
OpenOCD was created by Dominic Rath as part of a 2005 diploma thesis
|
||
written at the University of Applied Sciences Augsburg
|
||
(<http://www.hs-augsburg.de>). Since that time, the project has grown
|
||
into an active open-source project, supported by a diverse community of
|
||
software and hardware developers from around the world.
|
||
|
||
What is OpenOCD?
|
||
================
|
||
|
||
The Open On-Chip Debugger (OpenOCD) aims to provide debugging, in-system
|
||
programming and boundary-scan testing for embedded target devices.
|
||
|
||
It does so with the assistance of a "debug adapter", which is a small
|
||
hardware module which helps provide the right kind of electrical
|
||
signaling to the target being debugged. These are required since the
|
||
debug host (on which OpenOCD runs) won't usually have native support for
|
||
such signaling, or the connector needed to hook up to the target.
|
||
|
||
Such debug adapters support one or more "transport" protocols, each of
|
||
which involves different electrical signaling (and uses different
|
||
messaging protocols on top of that signaling). There are many types of
|
||
debug adapter, and little uniformity in what they are called. (There
|
||
are also product naming differences.)
|
||
|
||
These adapters are sometimes packaged as discrete dongles, which may
|
||
generically be called "hardware interface dongles". Some development
|
||
boards also integrate them directly, which may let the development board
|
||
connect directly to the debug host over USB (and sometimes also to power
|
||
it over USB).
|
||
|
||
For example, a "JTAG Adapter" supports JTAG signaling, and is used to
|
||
communicate with JTAG (IEEE 1149.1) compliant TAPs on your target board.
|
||
A "TAP" is a "Test Access Port", a module which processes special
|
||
instructions and data. TAPs are daisy-chained within and between chips
|
||
and boards. JTAG supports debugging and boundary scan operations.
|
||
|
||
There are also "SWD Adapters" that support Serial Wire Debug (SWD)
|
||
signaling to communicate with some newer ARM cores, as well as debug
|
||
adapters which support both JTAG and SWD transports. SWD supports only
|
||
debugging, whereas JTAG also supports boundary scan operations.
|
||
|
||
For some chips, there are also "Programming Adapters" supporting special
|
||
transports used only to write code to flash memory, without support for
|
||
on-chip debugging or boundary scan. (At this writing, OpenOCD does not
|
||
support such non-debug adapters.)
|
||
|
||
Dongles: OpenOCD currently supports many types of hardware dongles:
|
||
USB-based, parallel port-based, and other standalone boxes that run
|
||
OpenOCD internally. *Note Debug Adapter Hardware::.
|
||
|
||
GDB Debug: It allows ARM7 (ARM7TDMI and ARM720t), ARM9 (ARM920T,
|
||
ARM922T, ARM926EJ-S, ARM966E-S), XScale (PXA25x, IXP42x), Cortex-M3
|
||
(Stellaris LM3, STMicroelectronics STM32 and Energy Micro EFM32) and
|
||
Intel Quark (x10xx) based cores to be debugged via the GDB protocol.
|
||
|
||
Flash Programming: Flash writing is supported for external
|
||
CFI-compatible NOR flashes (Intel and AMD/Spansion command set) and
|
||
several internal flashes (LPC1700, LPC1800, LPC2000, LPC4300, AT91SAM7,
|
||
AT91SAM3U, STR7x, STR9x, LM3, STM32x and EFM32). Preliminary support
|
||
for various NAND flash controllers (LPC3180, Orion, S3C24xx, more) is
|
||
included.
|
||
|
||
OpenOCD Web Site
|
||
================
|
||
|
||
The OpenOCD web site provides the latest public news from the community:
|
||
|
||
<http://openocd.org/>
|
||
|
||
Latest User's Guide:
|
||
====================
|
||
|
||
The user's guide you are now reading may not be the latest one
|
||
available. A version for more recent code may be available. Its HTML
|
||
form is published regularly at:
|
||
|
||
<http://openocd.org/doc/html/index.html>
|
||
|
||
PDF form is likewise published at:
|
||
|
||
<http://openocd.org/doc/pdf/openocd.pdf>
|
||
|
||
OpenOCD User's Forum
|
||
====================
|
||
|
||
There is an OpenOCD forum (phpBB) hosted by SparkFun, which might be
|
||
helpful to you. Note that if you want anything to come to the attention
|
||
of developers, you should post it to the OpenOCD Developer Mailing List
|
||
instead of this forum.
|
||
|
||
<http://forum.sparkfun.com/viewforum.php?f=18>
|
||
|
||
OpenOCD User's Mailing List
|
||
===========================
|
||
|
||
The OpenOCD User Mailing List provides the primary means of
|
||
communication between users:
|
||
|
||
<https://lists.sourceforge.net/mailman/listinfo/openocd-user>
|
||
|
||
OpenOCD IRC
|
||
===========
|
||
|
||
Support can also be found on irc: <irc://irc.libera.chat/openocd>
|
||
|
||
|
||
File: openocd.info, Node: Developers, Next: Debug Adapter Hardware, Prev: About, Up: Top
|
||
|
||
1 OpenOCD Developer Resources
|
||
*****************************
|
||
|
||
If you are interested in improving the state of OpenOCD's debugging and
|
||
testing support, new contributions will be welcome. Motivated
|
||
developers can produce new target, flash or interface drivers, improve
|
||
the documentation, as well as more conventional bug fixes and
|
||
enhancements.
|
||
|
||
The resources in this chapter are available for developers wishing to
|
||
explore or expand the OpenOCD source code.
|
||
|
||
1.1 OpenOCD Git Repository
|
||
==========================
|
||
|
||
During the 0.3.x release cycle, OpenOCD switched from Subversion to a
|
||
Git repository hosted at SourceForge. The repository URL is:
|
||
|
||
<git://git.code.sf.net/p/openocd/code>
|
||
|
||
or via http
|
||
|
||
<http://git.code.sf.net/p/openocd/code>
|
||
|
||
You may prefer to use a mirror and the HTTP protocol:
|
||
|
||
<http://repo.or.cz/r/openocd.git>
|
||
|
||
With standard Git tools, use 'git clone' to initialize a local
|
||
repository, and 'git pull' to update it. There are also gitweb pages
|
||
letting you browse the repository with a web browser, or download
|
||
arbitrary snapshots without needing a Git client:
|
||
|
||
<http://repo.or.cz/w/openocd.git>
|
||
|
||
The 'README' file contains the instructions for building the project
|
||
from the repository or a snapshot.
|
||
|
||
Developers that want to contribute patches to the OpenOCD system are
|
||
strongly encouraged to work against mainline. Patches created against
|
||
older versions may require additional work from their submitter in order
|
||
to be updated for newer releases.
|
||
|
||
1.2 Doxygen Developer Manual
|
||
============================
|
||
|
||
During the 0.2.x release cycle, the OpenOCD project began providing a
|
||
Doxygen reference manual. This document contains more technical
|
||
information about the software internals, development processes, and
|
||
similar documentation:
|
||
|
||
<http://openocd.org/doc/doxygen/html/index.html>
|
||
|
||
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.
|
||
|
||
1.3 Gerrit Review System
|
||
========================
|
||
|
||
All changes in the OpenOCD Git repository go through the web-based
|
||
Gerrit Code Review System:
|
||
|
||
<https://review.openocd.org/>
|
||
|
||
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 '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.
|
||
|
||
1.4 OpenOCD Developer Mailing List
|
||
==================================
|
||
|
||
The OpenOCD Developer Mailing List provides the primary means of
|
||
communication between developers:
|
||
|
||
<https://lists.sourceforge.net/mailman/listinfo/openocd-devel>
|
||
|
||
1.5 OpenOCD Bug Tracker
|
||
=======================
|
||
|
||
The OpenOCD Bug Tracker is hosted on SourceForge:
|
||
|
||
<http://bugs.openocd.org/>
|
||
|
||
|
||
File: openocd.info, Node: Debug Adapter Hardware, Next: About Jim-Tcl, Prev: Developers, Up: Top
|
||
|
||
2 Debug Adapter Hardware
|
||
************************
|
||
|
||
Defined: dongle: A small device that plugs into a computer and serves as
|
||
an adapter .... [snip]
|
||
|
||
In the OpenOCD case, this generally refers to a small adapter that
|
||
attaches to your computer via USB or the parallel port.
|
||
|
||
2.1 Choosing a Dongle
|
||
=====================
|
||
|
||
There are several things you should keep in mind when choosing a dongle.
|
||
|
||
1. Transport Does it support the kind of communication that you need?
|
||
OpenOCD focuses mostly on JTAG. Your version may also support other
|
||
ways to communicate with target devices.
|
||
2. Voltage What voltage is your target - 1.8, 2.8, 3.3, or 5V? Does
|
||
your dongle support it? You might need a level converter.
|
||
3. Pinout What pinout does your target board use? Does your dongle
|
||
support it? You may be able to use jumper wires, or an "octopus"
|
||
connector, to convert pinouts.
|
||
4. Connection Does your computer have the USB, parallel, or Ethernet
|
||
port needed?
|
||
5. RTCK Do you expect to use it with ARM chips and boards with RTCK
|
||
support (also known as "adaptive clocking")?
|
||
|
||
2.2 USB FT2232 Based
|
||
====================
|
||
|
||
There are many USB JTAG dongles on the market, many of them based on a
|
||
chip from "Future Technology Devices International" (FTDI) known as the
|
||
FTDI FT2232; this is a USB full speed (12 Mbps) chip. See:
|
||
<http://www.ftdichip.com> for more information. In summer 2009, USB
|
||
high speed (480 Mbps) versions of these FTDI chips started to become
|
||
available in JTAG adapters. Around 2012, a new variant appeared -
|
||
FT232H - this is a single-channel version of FT2232H. (Adapters using
|
||
those high speed FT2232H or FT232H chips may support adaptive clocking.)
|
||
|
||
The FT2232 chips are flexible enough to support some other transport
|
||
options, such as SWD or the SPI variants used to program some chips.
|
||
They have two communications channels, and one can be used for a UART
|
||
adapter at the same time the other one is used to provide a debug
|
||
adapter.
|
||
|
||
Also, some development boards integrate an FT2232 chip to serve as a
|
||
built-in low-cost debug adapter and USB-to-serial solution.
|
||
|
||
* usbjtag
|
||
Link
|
||
<http://elk.informatik.fh-augsburg.de/hhweb/doc/openocd/usbjtag/usbjtag.html>
|
||
* jtagkey
|
||
See: <http://www.amontec.com/jtagkey.shtml>
|
||
* jtagkey2
|
||
See: <http://www.amontec.com/jtagkey2.shtml>
|
||
* oocdlink
|
||
See: <http://www.oocdlink.com> By Joern Kaipf
|
||
* signalyzer
|
||
See: <http://www.signalyzer.com>
|
||
* Stellaris Eval Boards
|
||
See: <http://www.ti.com> - The Stellaris eval boards bundle
|
||
FT2232-based JTAG and SWD support, which can be used to debug the
|
||
Stellaris chips. Using separate JTAG adapters is optional. These
|
||
boards can also be used in a "pass through" mode as JTAG adapters
|
||
to other target boards, disabling the Stellaris chip.
|
||
* TI/Luminary ICDI
|
||
See: <http://www.ti.com> - TI/Luminary In-Circuit Debug Interface
|
||
(ICDI) Boards are included in Stellaris LM3S9B9x Evaluation Kits.
|
||
Like the non-detachable FT2232 support on the other Stellaris eval
|
||
boards, they can be used to debug other target boards.
|
||
* olimex-jtag
|
||
See: <http://www.olimex.com>
|
||
* Flyswatter/Flyswatter2
|
||
See: <http://www.tincantools.com>
|
||
* turtelizer2
|
||
See: Turtelizer 2
|
||
(http://www.ethernut.de/en/hardware/turtelizer/index.html), or
|
||
<http://www.ethernut.de>
|
||
* comstick
|
||
Link: <http://www.hitex.com/index.php?id=383>
|
||
* stm32stick
|
||
Link <http://www.hitex.com/stm32-stick>
|
||
* axm0432_jtag
|
||
Axiom AXM-0432 Link <http://www.axman.com> - NOTE: This JTAG does
|
||
not appear to be available anymore as of April 2012.
|
||
* cortino
|
||
Link <http://www.hitex.com/index.php?id=cortino>
|
||
* dlp-usb1232h
|
||
Link <http://www.dlpdesign.com/usb/usb1232h.shtml>
|
||
* digilent-hs1
|
||
Link <http://www.digilentinc.com/Products/Detail.cfm?Prod=JTAG-HS1>
|
||
* opendous
|
||
Link <http://code.google.com/p/opendous/wiki/JTAG> FT2232H-based
|
||
(OpenHardware).
|
||
* JTAG-lock-pick Tiny 2
|
||
Link <http://www.distortec.com/jtag-lock-pick-tiny-2> FT232H-based
|
||
|
||
* GW16042
|
||
Link:
|
||
<http://shop.gateworks.com/index.php?route=product/product&path=70_80&product_id=64>
|
||
FT2232H-based
|
||
|
||
2.3 USB-JTAG / Altera USB-Blaster compatibles
|
||
=============================================
|
||
|
||
These devices also show up as FTDI devices, but are not
|
||
protocol-compatible with the FT2232 devices. They are, however,
|
||
protocol-compatible among themselves. USB-JTAG devices typically
|
||
consist of a FT245 followed by a CPLD that understands a particular
|
||
protocol, or emulates this protocol using some other hardware.
|
||
|
||
They may appear under different USB VID/PID depending on the particular
|
||
product. The driver can be configured to search for any VID/PID pair
|
||
(see the section on driver commands).
|
||
|
||
* USB-JTAG Kolja Waschk's USB Blaster-compatible adapter
|
||
Link: <http://ixo-jtag.sourceforge.net/>
|
||
* Altera USB-Blaster
|
||
Link: <http://www.altera.com/literature/ug/ug_usb_blstr.pdf>
|
||
|
||
2.4 USB J-Link based
|
||
====================
|
||
|
||
There are several OEM versions of the SEGGER J-Link adapter. It is an
|
||
example of a microcontroller based JTAG adapter, it uses an AT91SAM764
|
||
internally.
|
||
|
||
* SEGGER J-Link
|
||
Link: <http://www.segger.com/jlink.html>
|
||
* Atmel SAM-ICE (Only works with Atmel chips!)
|
||
Link: <http://www.atmel.com/tools/atmelsam-ice.aspx>
|
||
* IAR J-Link
|
||
|
||
2.5 USB RLINK based
|
||
===================
|
||
|
||
Raisonance has an adapter called RLink. It exists in a stripped-down
|
||
form on the STM32 Primer, permanently attached to the JTAG lines. It
|
||
also exists on the STM32 Primer2, but that is wired for SWD and not
|
||
JTAG, thus not supported.
|
||
|
||
* Raisonance RLink
|
||
Link:
|
||
<http://www.mcu-raisonance.com/~rlink-debugger-programmer__microcontrollers__tool~tool__T018:4cn9ziz4bnx6.html>
|
||
* STM32 Primer
|
||
Link: <http://www.stm32circle.com/resources/stm32primer.php>
|
||
* STM32 Primer2
|
||
Link: <http://www.stm32circle.com/resources/stm32primer2.php>
|
||
|
||
2.6 USB ST-LINK based
|
||
=====================
|
||
|
||
STMicroelectronics has an adapter called ST-LINK. They only work with
|
||
STMicroelectronics chips, notably STM32 and STM8.
|
||
|
||
* ST-LINK
|
||
This is available standalone and as part of some kits, eg.
|
||
STM32VLDISCOVERY.
|
||
Link: <http://www.st.com/internet/evalboard/product/219866.jsp>
|
||
* ST-LINK/V2
|
||
This is available standalone and as part of some kits, eg.
|
||
STM32F4DISCOVERY.
|
||
Link: <http://www.st.com/internet/evalboard/product/251168.jsp>
|
||
* STLINK-V3
|
||
This is available standalone and as part of some kits.
|
||
Link: <http://www.st.com/stlink-v3>
|
||
|
||
For info the original ST-LINK enumerates using the mass storage usb
|
||
class; however, its implementation is completely broken. The result is
|
||
this causes issues under Linux. The simplest solution is to get Linux
|
||
to ignore the ST-LINK using one of the following methods:
|
||
* modprobe -r usb-storage && modprobe usb-storage quirks=483:3744:i
|
||
* add "options usb-storage quirks=483:3744:i" to /etc/modprobe.conf
|
||
|
||
2.7 USB TI/Stellaris ICDI based
|
||
===============================
|
||
|
||
Texas Instruments has an adapter called ICDI. It is not to be confused
|
||
with the FTDI based adapters that were originally fitted to their
|
||
evaluation boards. This is the adapter fitted to the Stellaris
|
||
LaunchPad.
|
||
|
||
2.8 USB Nuvoton Nu-Link
|
||
=======================
|
||
|
||
Nuvoton has an adapter called Nu-Link. It is available either as
|
||
stand-alone dongle and embedded on development boards. It supports SWD,
|
||
serial port bridge and mass storage for firmware update. Both Nu-Link
|
||
v1 and v2 are supported.
|
||
|
||
2.9 USB CMSIS-DAP based
|
||
=======================
|
||
|
||
ARM has released a interface standard called CMSIS-DAP that simplifies
|
||
connecting debuggers to ARM Cortex based targets
|
||
<http://www.keil.com/support/man/docs/dapdebug/dapdebug_introduction.htm>.
|
||
|
||
2.10 USB Other
|
||
==============
|
||
|
||
* USBprog
|
||
Link: <http://shop.embedded-projects.net/> - which uses an Atmel
|
||
MEGA32 and a UBN9604
|
||
|
||
* USB - Presto
|
||
Link: <http://tools.asix.net/prg_presto.htm>
|
||
|
||
* Versaloon-Link
|
||
Link: <http://www.versaloon.com>
|
||
|
||
* ARM-JTAG-EW
|
||
Link: <http://www.olimex.com/dev/arm-jtag-ew.html>
|
||
|
||
* Buspirate
|
||
Link: <http://dangerousprototypes.com/bus-pirate-manual/>
|
||
|
||
* opendous
|
||
Link: <http://code.google.com/p/opendous-jtag/> - which uses an
|
||
AT90USB162
|
||
|
||
* estick
|
||
Link: <http://code.google.com/p/estick-jtag/>
|
||
|
||
* Keil ULINK v1
|
||
Link: <http://www.keil.com/ulink1/>
|
||
|
||
* TI XDS110 Debug Probe
|
||
Link:
|
||
<https://software-dl.ti.com/ccs/esd/documents/xdsdebugprobes/emu_xds110.html>
|
||
|
||
Link:
|
||
<https://software-dl.ti.com/ccs/esd/documents/xdsdebugprobes/emu_xds_software_package_download.html#xds110-support-utilities>
|
||
|
||
2.11 IBM PC Parallel Printer Port Based
|
||
=======================================
|
||
|
||
The two well-known "JTAG Parallel Ports" cables are the Xilinx DLC5 and
|
||
the Macraigor Wiggler. There are many clones and variations of these on
|
||
the market.
|
||
|
||
Note that parallel ports are becoming much less common, so if you have
|
||
the choice you should probably avoid these adapters in favor of
|
||
USB-based ones.
|
||
|
||
* Wiggler - There are many clones of this.
|
||
Link: <http://www.macraigor.com/wiggler.htm>
|
||
|
||
* DLC5 - From XILINX - There are many clones of this
|
||
Link: Search the web for: "XILINX DLC5" - it is no longer produced,
|
||
PDF schematics are easily found and it is easy to make.
|
||
|
||
* Amontec - JTAG Accelerator
|
||
Link: <http://www.amontec.com/jtag_accelerator.shtml>
|
||
|
||
* Wiggler2
|
||
Link:
|
||
<http://www.ccac.rwth-aachen.de/~michaels/index.php/hardware/armjtag>
|
||
|
||
* Wiggler_ntrst_inverted
|
||
Yet another variation - See the source code, src/jtag/parport.c
|
||
|
||
* old_amt_wiggler
|
||
Unknown - probably not on the market today
|
||
|
||
* arm-jtag
|
||
Link: Most likely <http://www.olimex.com/dev/arm-jtag.html>
|
||
[another wiggler clone]
|
||
|
||
* chameleon
|
||
Link: <http://www.amontec.com/chameleon.shtml>
|
||
|
||
* Triton
|
||
Unknown.
|
||
|
||
* Lattice
|
||
ispDownload from Lattice Semiconductor
|
||
<http://www.latticesemi.com/lit/docs/devtools/dlcable.pdf>
|
||
|
||
* flashlink
|
||
From STMicroelectronics;
|
||
Link:
|
||
<http://www.st.com/internet/com/TECHNICAL_RESOURCES/TECHNICAL_LITERATURE/DATA_BRIEF/DM00039500.pdf>
|
||
|
||
2.12 Other...
|
||
=============
|
||
|
||
* ep93xx
|
||
An EP93xx based Linux machine using the GPIO pins directly.
|
||
|
||
* at91rm9200
|
||
Like the EP93xx - but an ATMEL AT91RM9200 based solution using the
|
||
GPIO pins on the chip.
|
||
|
||
* bcm2835gpio
|
||
A BCM2835-based board (e.g. Raspberry Pi) using the GPIO pins of
|
||
the expansion header.
|
||
|
||
* imx_gpio
|
||
A NXP i.MX-based board (e.g. Wandboard) using the GPIO pins
|
||
(should work on any i.MX processor).
|
||
|
||
* jtag_vpi
|
||
A JTAG driver acting as a client for the JTAG VPI server interface.
|
||
|
||
Link: <http://github.com/fjullien/jtag_vpi>
|
||
|
||
* jtag_dpi
|
||
A JTAG driver acting as a client for the SystemVerilog Direct
|
||
Programming Interface (DPI) for JTAG devices. DPI allows OpenOCD
|
||
to connect to the JTAG interface of a hardware model written in
|
||
SystemVerilog, for example, on an emulation model of target
|
||
hardware.
|
||
|
||
* xlnx_pcie_xvc
|
||
A JTAG driver exposing Xilinx Virtual Cable over PCI Express to
|
||
OpenOCD as JTAG/SWD interface.
|
||
|
||
* linuxgpiod
|
||
A bitbang JTAG driver using Linux GPIO through library libgpiod.
|
||
|
||
* sysfsgpio
|
||
A bitbang JTAG driver using Linux legacy sysfs GPIO. This is
|
||
deprecated from Linux v5.3; prefer using linuxgpiod.
|
||
|
||
|
||
File: openocd.info, Node: About Jim-Tcl, Next: Running, Prev: Debug Adapter Hardware, Up: Top
|
||
|
||
3 About Jim-Tcl
|
||
***************
|
||
|
||
OpenOCD uses a small "Tcl Interpreter" known as Jim-Tcl. This
|
||
programming language provides a simple and extensible command
|
||
interpreter.
|
||
|
||
All commands presented in this Guide are extensions to Jim-Tcl. You can
|
||
use them as simple commands, without needing to learn much of anything
|
||
about Tcl. Alternatively, you can write Tcl programs with them.
|
||
|
||
You can learn more about Jim at its website, <http://jim.tcl.tk>. There
|
||
is an active and responsive community, get on the mailing list if you
|
||
have any questions. Jim-Tcl maintainers also lurk on the OpenOCD
|
||
mailing list.
|
||
|
||
* Jim vs. Tcl
|
||
Jim-Tcl is a stripped down version of the well known Tcl language,
|
||
which can be found here: <http://www.tcl.tk>. Jim-Tcl has far
|
||
fewer features. Jim-Tcl is several dozens of .C files and .H files
|
||
and implements the basic Tcl command set. In contrast: Tcl 8.6 is
|
||
a 4.2 MB .zip file containing 1540 files.
|
||
|
||
* Missing Features
|
||
Our practice has been: Add/clone the real Tcl feature if/when
|
||
needed. We welcome Jim-Tcl improvements, not bloat. Also there
|
||
are a large number of optional Jim-Tcl features that are not
|
||
enabled in OpenOCD.
|
||
|
||
* Scripts
|
||
OpenOCD configuration scripts are Jim-Tcl Scripts. OpenOCD's
|
||
command interpreter today is a mixture of (newer) Jim-Tcl commands,
|
||
and the (older) original command interpreter.
|
||
|
||
* Commands
|
||
At the OpenOCD telnet command line (or via the GDB monitor command)
|
||
one can type a Tcl for() loop, set variables, etc. Some of the
|
||
commands documented in this guide are implemented as Tcl scripts,
|
||
from a 'startup.tcl' file internal to the server.
|
||
|
||
* Historical Note
|
||
Jim-Tcl was introduced to OpenOCD in spring 2008. Fall 2010,
|
||
before OpenOCD 0.5 release, OpenOCD switched to using Jim-Tcl as a
|
||
Git submodule, which greatly simplified upgrading Jim-Tcl to
|
||
benefit from new features and bugfixes in Jim-Tcl.
|
||
|
||
* Need a crash course in Tcl?
|
||
*Note Tcl Crash Course::.
|
||
|
||
|
||
File: openocd.info, Node: Running, Next: OpenOCD Project Setup, Prev: About Jim-Tcl, Up: Top
|
||
|
||
4 Running
|
||
*********
|
||
|
||
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 '/etc/udev/rules.d,' so OpenOCD has permissions.
|
||
An example rules file that works for many common adapters is shipped
|
||
with OpenOCD in the '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.
|
||
|
||
Then later you will invoke the OpenOCD server, with various options to
|
||
tell it how each debug session should work. The '--help' option shows:
|
||
bash$ openocd --help
|
||
|
||
--help | -h display this help
|
||
--version | -v display OpenOCD version
|
||
--file | -f use configuration file <name>
|
||
--search | -s dir to search for config files and scripts
|
||
--debug | -d set debug level to 3
|
||
| -d<n> set debug level to <level>
|
||
--log_output | -l redirect log output to file <name>
|
||
--command | -c run <command>
|
||
|
||
If you don't give any '-f' or '-c' options, OpenOCD tries to read the
|
||
configuration file 'openocd.cfg'. To specify one or more different
|
||
configuration files, use '-f' options. For example:
|
||
|
||
openocd -f config1.cfg -f config2.cfg -f config3.cfg
|
||
|
||
Configuration files and scripts are searched for in
|
||
1. the current directory,
|
||
2. any search dir specified on the command line using the '-s' option,
|
||
3. any search dir specified using the 'add_script_search_dir' command,
|
||
4. a directory in the 'OPENOCD_SCRIPTS' environment variable (if set),
|
||
5. '%APPDATA%/OpenOCD' (only on Windows),
|
||
6. '$HOME/Library/Preferences/org.openocd' (only on Darwin),
|
||
7. '$XDG_CONFIG_HOME/openocd' ('$XDG_CONFIG_HOME' defaults to
|
||
'$HOME/.config'),
|
||
8. '$HOME/.openocd',
|
||
9. the site wide script library '$pkgdatadir/site' and
|
||
10. the OpenOCD-supplied script library '$pkgdatadir/scripts'.
|
||
The first found file with a matching file name will be used.
|
||
|
||
Note: Don't try to use configuration script names or paths which
|
||
include the "#" character. That character begins Tcl comments.
|
||
|
||
4.1 Simple setup, no customization
|
||
==================================
|
||
|
||
In the best case, you can use two scripts from one of the script
|
||
libraries, hook up your JTAG adapter, and start the server ... and your
|
||
JTAG setup will just work "out of the box". Always try to start by
|
||
reusing those scripts, but assume you'll need more customization even if
|
||
this works. *Note OpenOCD Project Setup::.
|
||
|
||
If you find a script for your JTAG adapter, and for your board or
|
||
target, you may be able to hook up your JTAG adapter then start the
|
||
server with some variation of one of the following:
|
||
|
||
openocd -f interface/ADAPTER.cfg -f board/MYBOARD.cfg
|
||
openocd -f interface/ftdi/ADAPTER.cfg -f board/MYBOARD.cfg
|
||
|
||
You might also need to configure which reset signals are present, using
|
||
'-c 'reset_config trst_and_srst'' or something similar. If all goes
|
||
well you'll see output something like
|
||
|
||
Open On-Chip Debugger 0.4.0 (2010-01-14-15:06)
|
||
For bug reports, read
|
||
http://openocd.org/doc/doxygen/bugs.html
|
||
Info : JTAG tap: lm3s.cpu tap/device found: 0x3ba00477
|
||
(mfg: 0x23b, part: 0xba00, ver: 0x3)
|
||
|
||
Seeing that "tap/device found" message, and no warnings, means the JTAG
|
||
communication is working. That's a key milestone, but you'll probably
|
||
need more project-specific setup.
|
||
|
||
4.2 What OpenOCD does as it starts
|
||
==================================
|
||
|
||
OpenOCD starts by processing the configuration commands provided on the
|
||
command line or, if there were no '-c command' or '-f file.cfg' options
|
||
given, in 'openocd.cfg'. *Note Configuration Stage: configurationstage.
|
||
At the end of the configuration stage it verifies the JTAG scan chain
|
||
defined using those commands; your configuration should ensure that this
|
||
always succeeds. Normally, OpenOCD then starts running as a server.
|
||
Alternatively, commands may be used to terminate the configuration stage
|
||
early, perform work (such as updating some flash memory), and then shut
|
||
down without acting as a server.
|
||
|
||
Once OpenOCD starts running as a server, it waits for connections from
|
||
clients (Telnet, GDB, RPC) and processes the commands issued through
|
||
those channels.
|
||
|
||
If you are having problems, you can enable internal debug messages via
|
||
the '-d' option.
|
||
|
||
Also it is possible to interleave Jim-Tcl commands w/config scripts
|
||
using the '-c' command line switch.
|
||
|
||
To enable debug output (when reporting problems or working on OpenOCD
|
||
itself), use the '-d' command line switch. This sets the 'debug_level'
|
||
to "3", outputting the most information, including debug messages. The
|
||
default setting is "2", outputting only informational messages, warnings
|
||
and errors. You can also change this setting from within a telnet or
|
||
gdb session using 'debug_level<n>' (*note debug_level: debuglevel.).
|
||
|
||
You can redirect all output from the server to a file using the '-l
|
||
<logfile>' switch.
|
||
|
||
Note! OpenOCD will launch the GDB & telnet server even if it can not
|
||
establish a connection with the target. In general, it is possible for
|
||
the JTAG controller to be unresponsive until the target is set up
|
||
correctly via e.g. GDB monitor commands in a GDB init script.
|
||
|
||
|
||
File: openocd.info, Node: OpenOCD Project Setup, Next: Config File Guidelines, Prev: Running, Up: Top
|
||
|
||
5 OpenOCD Project Setup
|
||
***********************
|
||
|
||
To use OpenOCD with your development projects, you need to do more than
|
||
just connect the JTAG adapter hardware (dongle) to your development
|
||
board and start the OpenOCD server. You also need to configure your
|
||
OpenOCD server so that it knows about your adapter and board, and helps
|
||
your work. You may also want to connect OpenOCD to GDB, possibly using
|
||
Eclipse or some other GUI.
|
||
|
||
5.1 Hooking up the JTAG Adapter
|
||
===============================
|
||
|
||
Today's most common case is a dongle with a JTAG cable on one side (such
|
||
as a ribbon cable with a 10-pin or 20-pin IDC connector) and a USB cable
|
||
on the other. Instead of USB, some dongles use Ethernet; older ones may
|
||
use a PC parallel port, or even a serial port.
|
||
|
||
1. _Start with power to your target board turned off_, and nothing
|
||
connected to your JTAG adapter. If you're particularly paranoid,
|
||
unplug power to the board. It's important to have the ground
|
||
signal properly set up, unless you are using a JTAG adapter which
|
||
provides galvanic isolation between the target board and the
|
||
debugging host.
|
||
|
||
2. _Be sure it's the right kind of JTAG connector._ If your dongle
|
||
has a 20-pin ARM connector, you need some kind of adapter (or
|
||
octopus, see below) to hook it up to boards using 14-pin or 10-pin
|
||
connectors ... or to 20-pin connectors which don't use ARM's
|
||
pinout.
|
||
|
||
In the same vein, make sure the voltage levels are compatible. Not
|
||
all JTAG adapters have the level shifters needed to work with 1.2
|
||
Volt boards.
|
||
|
||
3. _Be certain the cable is properly oriented_ or you might damage
|
||
your board. In most cases there are only two possible ways to
|
||
connect the cable. Connect the JTAG cable from your adapter to the
|
||
board. Be sure it's firmly connected.
|
||
|
||
In the best case, the connector is keyed to physically prevent you
|
||
from inserting it wrong. This is most often done using a slot on
|
||
the board's male connector housing, which must match a key on the
|
||
JTAG cable's female connector. If there's no housing, then you
|
||
must look carefully and make sure pin 1 on the cable hooks up to
|
||
pin 1 on the board. Ribbon cables are frequently all grey except
|
||
for a wire on one edge, which is red. The red wire is pin 1.
|
||
|
||
Sometimes dongles provide cables where one end is an "octopus" of
|
||
color coded single-wire connectors, instead of a connector block.
|
||
These are great when converting from one JTAG pinout to another,
|
||
but are tedious to set up. Use these with connector pinout
|
||
diagrams to help you match up the adapter signals to the right
|
||
board pins.
|
||
|
||
4. _Connect the adapter's other end_ once the JTAG cable is connected.
|
||
A USB, parallel, or serial port connector will go to the host which
|
||
you are using to run OpenOCD. For Ethernet, consult the
|
||
documentation and your network administrator.
|
||
|
||
For USB-based JTAG adapters you have an easy sanity check at this
|
||
point: does the host operating system see the JTAG adapter? If
|
||
you're running Linux, try the 'lsusb' command. If that host is an
|
||
MS-Windows host, you'll need to install a driver before OpenOCD
|
||
works.
|
||
|
||
5. _Connect the adapter's power supply, if needed._ This step is
|
||
primarily for non-USB adapters, but sometimes USB adapters need
|
||
extra power.
|
||
|
||
6. _Power up the target board._ Unless you just let the magic smoke
|
||
escape, you're now ready to set up the OpenOCD server so you can
|
||
use JTAG to work with that board.
|
||
|
||
Talk with the OpenOCD server using telnet ('telnet localhost 4444' on
|
||
many systems) or GDB. *Note GDB and OpenOCD::.
|
||
|
||
5.2 Project Directory
|
||
=====================
|
||
|
||
There are many ways you can configure OpenOCD and start it up.
|
||
|
||
A simple way to organize them all involves keeping a single directory
|
||
for your work with a given board. When you start OpenOCD from that
|
||
directory, it searches there first for configuration files, scripts,
|
||
files accessed through semihosting, and for code you upload to the
|
||
target board. It is also the natural place to write files, such as log
|
||
files and data you download from the board.
|
||
|
||
5.3 Configuration Basics
|
||
========================
|
||
|
||
There are two basic ways of configuring OpenOCD, and a variety of ways
|
||
you can mix them. Think of the difference as just being how you start
|
||
the server:
|
||
|
||
* Many '-f file' or '-c command' options on the command line
|
||
* No options, but a "user config file" in the current directory named
|
||
'openocd.cfg'
|
||
|
||
Here is an example 'openocd.cfg' file for a setup using a Signalyzer
|
||
FT2232-based JTAG adapter to talk to a board with an Atmel AT91SAM7X256
|
||
microcontroller:
|
||
|
||
source [find interface/ftdi/signalyzer.cfg]
|
||
|
||
# GDB can also flash my flash!
|
||
gdb_memory_map enable
|
||
gdb_flash_program enable
|
||
|
||
source [find target/sam7x256.cfg]
|
||
|
||
Here is the command line equivalent of that configuration:
|
||
|
||
openocd -f interface/ftdi/signalyzer.cfg \
|
||
-c "gdb_memory_map enable" \
|
||
-c "gdb_flash_program enable" \
|
||
-f target/sam7x256.cfg
|
||
|
||
You could wrap such long command lines in shell scripts, each supporting
|
||
a different development task. One might re-flash the board with a
|
||
specific firmware version. Another might set up a particular debugging
|
||
or run-time environment.
|
||
|
||
Important: At this writing (October 2009) the command line method
|
||
has problems with how it treats variables. For example, after '-c
|
||
"set VAR value"', or doing the same in a script, the variable VAR
|
||
will have no value that can be tested in a later script.
|
||
|
||
Here we will focus on the simpler solution: one user config file,
|
||
including basic configuration plus any TCL procedures to simplify your
|
||
work.
|
||
|
||
5.4 User Config Files
|
||
=====================
|
||
|
||
A user configuration file ties together all the parts of a project in
|
||
one place. One of the following will match your situation best:
|
||
|
||
* Ideally almost everything comes from configuration files provided
|
||
by someone else. For example, OpenOCD distributes a 'scripts'
|
||
directory (probably in '/usr/share/openocd/scripts' on Linux).
|
||
Board and tool vendors can provide these too, as can individual
|
||
user sites; the '-s' command line option lets you say where to find
|
||
these files. (*Note Running::.) The AT91SAM7X256 example above
|
||
works this way.
|
||
|
||
Three main types of non-user configuration file each have their own
|
||
subdirectory in the 'scripts' directory:
|
||
|
||
1. interface - one for each different debug adapter;
|
||
2. board - one for each different board
|
||
3. target - the chips which integrate CPUs and other JTAG TAPs
|
||
|
||
Best case: include just two files, and they handle everything else.
|
||
The first is an interface config file. The second is
|
||
board-specific, and it sets up the JTAG TAPs and their GDB targets
|
||
(by deferring to some 'target.cfg' file), declares all flash
|
||
memory, and leaves you nothing to do except meet your deadline:
|
||
|
||
source [find interface/olimex-jtag-tiny.cfg]
|
||
source [find board/csb337.cfg]
|
||
|
||
Boards with a single microcontroller often won't need more than the
|
||
target config file, as in the AT91SAM7X256 example. That's because
|
||
there is no external memory (flash, DDR RAM), and the board
|
||
differences are encapsulated by application code.
|
||
|
||
* Maybe you don't know yet what your board looks like to JTAG. Once
|
||
you know the 'interface.cfg' file to use, you may need help from
|
||
OpenOCD to discover what's on the board. Once you find the JTAG
|
||
TAPs, you can just search for appropriate target and board
|
||
configuration files ... or write your own, from the bottom up.
|
||
*Note Autoprobing: autoprobing.
|
||
|
||
* You can often reuse some standard config files but need to write a
|
||
few new ones, probably a 'board.cfg' file. You will be using
|
||
commands described later in this User's Guide, and working with the
|
||
guidelines in the next chapter.
|
||
|
||
For example, there may be configuration files for your JTAG adapter
|
||
and target chip, but you need a new board-specific config file
|
||
giving access to your particular flash chips. Or you might need to
|
||
write another target chip configuration file for a new chip built
|
||
around the Cortex-M3 core.
|
||
|
||
Note: When you write new configuration files, please submit
|
||
them for inclusion in the next OpenOCD release. For example,
|
||
a 'board/newboard.cfg' file will help the next users of that
|
||
board, and a 'target/newcpu.cfg' will help support users of
|
||
any board using that chip.
|
||
|
||
* You may need to write some C code. It may be as simple as
|
||
supporting a new FT2232 or parport based adapter; a bit more
|
||
involved, like a NAND or NOR flash controller driver; or a big
|
||
piece of work like supporting a new chip architecture.
|
||
|
||
Reuse the existing config files when you can. Look first in the
|
||
'scripts/boards' area, then 'scripts/targets'. You may find a board
|
||
configuration that's a good example to follow.
|
||
|
||
When you write config files, separate the reusable parts (things every
|
||
user of that interface, chip, or board needs) from ones specific to your
|
||
environment and debugging approach.
|
||
|
||
* For example, a 'gdb-attach' event handler that invokes the 'reset
|
||
init' command will interfere with debugging early boot code, which
|
||
performs some of the same actions that the 'reset-init' event
|
||
handler does.
|
||
|
||
* Likewise, the 'arm9 vector_catch' command (or its siblings 'xscale
|
||
vector_catch' and 'cortex_m vector_catch') can be a time-saver
|
||
during some debug sessions, but don't make everyone use that
|
||
either. Keep those kinds of debugging aids in your user config
|
||
file, along with messaging and tracing setup. (*Note Software
|
||
Debug Messages and Tracing: softwaredebugmessagesandtracing.)
|
||
|
||
* You might need to override some defaults. For example, you might
|
||
need to move, shrink, or back up the target's work area if your
|
||
application needs much SRAM.
|
||
|
||
* TCP/IP port configuration is another example of something which is
|
||
environment-specific, and should only appear in a user config file.
|
||
*Note TCP/IP Ports: tcpipports.
|
||
|
||
5.5 Project-Specific Utilities
|
||
==============================
|
||
|
||
A few project-specific utility routines may well speed up your work.
|
||
Write them, and keep them in your project's user config file.
|
||
|
||
For example, if you are making a boot loader work on a board, it's nice
|
||
to be able to debug the "after it's loaded to RAM" parts separately from
|
||
the finicky early code which sets up the DDR RAM controller and clocks.
|
||
A script like this one, or a more GDB-aware sibling, may help:
|
||
|
||
proc ramboot { } {
|
||
# Reset, running the target's "reset-init" scripts
|
||
# to initialize clocks and the DDR RAM controller.
|
||
# Leave the CPU halted.
|
||
reset init
|
||
|
||
# Load CONFIG_SKIP_LOWLEVEL_INIT version into DDR RAM.
|
||
load_image u-boot.bin 0x20000000
|
||
|
||
# Start running.
|
||
resume 0x20000000
|
||
}
|
||
|
||
Then once that code is working you will need to make it boot from NOR
|
||
flash; a different utility would help. Alternatively, some developers
|
||
write to flash using GDB. (You might use a similar script if you're
|
||
working with a flash based microcontroller application instead of a boot
|
||
loader.)
|
||
|
||
proc newboot { } {
|
||
# Reset, leaving the CPU halted. The "reset-init" event
|
||
# proc gives faster access to the CPU and to NOR flash;
|
||
# "reset halt" would be slower.
|
||
reset init
|
||
|
||
# Write standard version of U-Boot into the first two
|
||
# sectors of NOR flash ... the standard version should
|
||
# do the same lowlevel init as "reset-init".
|
||
flash protect 0 0 1 off
|
||
flash erase_sector 0 0 1
|
||
flash write_bank 0 u-boot.bin 0x0
|
||
flash protect 0 0 1 on
|
||
|
||
# Reboot from scratch using that new boot loader.
|
||
reset run
|
||
}
|
||
|
||
You may need more complicated utility procedures when booting from NAND.
|
||
That often involves an extra bootloader stage, running from on-chip SRAM
|
||
to perform DDR RAM setup so it can load the main bootloader code (which
|
||
won't fit into that SRAM).
|
||
|
||
Other helper scripts might be used to write production system images,
|
||
involving considerably more than just a three stage bootloader.
|
||
|
||
5.6 Target Software Changes
|
||
===========================
|
||
|
||
Sometimes you may want to make some small changes to the software you're
|
||
developing, to help make JTAG debugging work better. For example, in C
|
||
or assembly language code you might use '#ifdef JTAG_DEBUG' (or its
|
||
converse) around code handling issues like:
|
||
|
||
* Watchdog Timers... Watchdog timers are typically used to
|
||
automatically reset systems if some application task doesn't
|
||
periodically reset the timer. (The assumption is that the system
|
||
has locked up if the task can't run.) When a JTAG debugger halts
|
||
the system, that task won't be able to run and reset the timer ...
|
||
potentially causing resets in the middle of your debug sessions.
|
||
|
||
It's rarely a good idea to disable such watchdogs, since their
|
||
usage needs to be debugged just like all other parts of your
|
||
firmware. That might however be your only option.
|
||
|
||
Look instead for chip-specific ways to stop the watchdog from
|
||
counting while the system is in a debug halt state. It may be
|
||
simplest to set that non-counting mode in your debugger startup
|
||
scripts. You may however need a different approach when, for
|
||
example, a motor could be physically damaged by firmware remaining
|
||
inactive in a debug halt state. That might involve a type of
|
||
firmware mode where that "non-counting" mode is disabled at the
|
||
beginning then re-enabled at the end; a watchdog reset might fire
|
||
and complicate the debug session, but hardware (or people) would be
|
||
protected.(1)
|
||
|
||
* ARM Semihosting... When linked with a special runtime library
|
||
provided with many toolchains(2), your target code can use I/O
|
||
facilities on the debug host. That library provides a small set of
|
||
system calls which are handled by OpenOCD. It can let the debugger
|
||
provide your system console and a file system, helping with early
|
||
debugging or providing a more capable environment for
|
||
sometimes-complex tasks like installing system firmware onto NAND
|
||
or SPI flash.
|
||
|
||
* ARM Wait-For-Interrupt... Many ARM chips synchronize the JTAG
|
||
clock using the core clock. Low power states which stop that core
|
||
clock thus prevent JTAG access. Idle loops in tasking environments
|
||
often enter those low power states via the 'WFI' instruction (or
|
||
its coprocessor equivalent, before ARMv7).
|
||
|
||
You may want to _disable that instruction_ in source code, or
|
||
otherwise prevent using that state, to ensure you can get JTAG
|
||
access at any time.(3) For example, the OpenOCD 'halt' command may
|
||
not work for an idle processor otherwise.
|
||
|
||
* Delay after reset... Not all chips have good support for debugger
|
||
access right after reset; many LPC2xxx chips have issues here.
|
||
Similarly, applications that reconfigure pins used for JTAG access
|
||
as they start will also block debugger access.
|
||
|
||
To work with boards like this, _enable a short delay loop_ the
|
||
first thing after reset, before "real" startup activities. For
|
||
example, one second's delay is usually more than enough time for a
|
||
JTAG debugger to attach, so that early code execution can be
|
||
debugged or firmware can be replaced.
|
||
|
||
* Debug Communications Channel (DCC)... Some processors include
|
||
mechanisms to send messages over JTAG. Many ARM cores support
|
||
these, as do some cores from other vendors. (OpenOCD may be able
|
||
to use this DCC internally, speeding up some operations like
|
||
writing to memory.)
|
||
|
||
Your application may want to deliver various debugging messages
|
||
over JTAG, by _linking with a small library of code_ provided with
|
||
OpenOCD and using the utilities there to send various kinds of
|
||
message. *Note Software Debug Messages and Tracing:
|
||
softwaredebugmessagesandtracing.
|
||
|
||
5.7 Target Hardware Setup
|
||
=========================
|
||
|
||
Chip vendors often provide software development boards which are highly
|
||
configurable, so that they can support all options that product boards
|
||
may require. _Make sure that any jumpers or switches match the system
|
||
configuration you are working with._
|
||
|
||
Common issues include:
|
||
|
||
* JTAG setup ... Boards may support more than one JTAG
|
||
configuration. Examples include jumpers controlling pullups versus
|
||
pulldowns on the nTRST and/or nSRST signals, and choice of
|
||
connectors (e.g. which of two headers on the base board, or one
|
||
from a daughtercard). For some Texas Instruments boards, you may
|
||
need to jumper the EMU0 and EMU1 signals (which OpenOCD won't
|
||
currently control).
|
||
|
||
* Boot Modes ... Complex chips often support multiple boot modes,
|
||
controlled by external jumpers. Make sure this is set up
|
||
correctly. For example many i.MX boards from NXP need to be
|
||
jumpered to "ATX mode" to start booting using the on-chip ROM, when
|
||
using second stage bootloader code stored in a NAND flash chip.
|
||
|
||
Such explicit configuration is common, and not limited to booting
|
||
from NAND. You might also need to set jumpers to start booting
|
||
using code loaded from an MMC/SD card; external SPI flash;
|
||
Ethernet, UART, or USB links; NOR flash; OneNAND flash; some
|
||
external host; or various other sources.
|
||
|
||
* Memory Addressing ... Boards which support multiple boot modes may
|
||
also have jumpers to configure memory addressing. One board, for
|
||
example, jumpers external chipselect 0 (used for booting) to
|
||
address either a large SRAM (which must be pre-loaded via JTAG),
|
||
NOR flash, or NAND flash. When it's jumpered to address NAND
|
||
flash, that board must also be told to start booting from on-chip
|
||
ROM.
|
||
|
||
Your 'board.cfg' file may also need to be told this jumper
|
||
configuration, so that it can know whether to declare NOR flash
|
||
using 'flash bank' or instead declare NAND flash with 'nand
|
||
device'; and likewise which probe to perform in its 'reset-init'
|
||
handler.
|
||
|
||
A closely related issue is bus width. Jumpers might need to
|
||
distinguish between 8 bit or 16 bit bus access for the flash used
|
||
to start booting.
|
||
|
||
* Peripheral Access ... Development boards generally provide access
|
||
to every peripheral on the chip, sometimes in multiple modes (such
|
||
as by providing multiple audio codec chips). This interacts with
|
||
software configuration of pin multiplexing, where for example a
|
||
given pin may be routed either to the MMC/SD controller or the GPIO
|
||
controller. It also often interacts with configuration jumpers.
|
||
One jumper may be used to route signals to an MMC/SD card slot or
|
||
an expansion bus (which might in turn affect booting); others might
|
||
control which audio or video codecs are used.
|
||
|
||
Plus you should of course have 'reset-init' event handlers which set up
|
||
the hardware to match that jumper configuration. That includes in
|
||
particular any oscillator or PLL used to clock the CPU, and any memory
|
||
controllers needed to access external memory and peripherals. Without
|
||
such handlers, you won't be able to access those resources without
|
||
working target firmware which can do that setup ... this can be awkward
|
||
when you're trying to debug that target firmware. Even if there's a ROM
|
||
bootloader which handles a few issues, it rarely provides full access to
|
||
all board-specific capabilities.
|
||
|
||
---------- Footnotes ----------
|
||
|
||
(1) Note that many systems support a "monitor mode" debug that is a
|
||
somewhat cleaner way to address such issues. You can think of it as
|
||
only halting part of the system, maybe just one task, instead of the
|
||
whole thing. At this writing, January 2010, OpenOCD based debugging
|
||
does not support monitor mode debug, only "halt mode" debug.
|
||
|
||
(2) See chapter 8 "Semihosting" in ARM DUI 0203I
|
||
(http://infocenter.arm.com/help/topic/com.arm.doc.dui0203i/DUI0203I_rvct_developer_guide.pdf),
|
||
the "RealView Compilation Tools Developer Guide". The CodeSourcery EABI
|
||
toolchain also includes a semihosting library.
|
||
|
||
(3) As a more polite alternative, some processors have special
|
||
debug-oriented registers which can be used to change various features
|
||
including how the low power states are clocked while debugging. The
|
||
STM32 DBGMCU_CR register is an example; at the cost of extra power
|
||
consumption, JTAG can be used during low power states.
|
||
|
||
|
||
File: openocd.info, Node: Config File Guidelines, Next: Server Configuration, Prev: OpenOCD Project Setup, Up: Top
|
||
|
||
6 Config File Guidelines
|
||
************************
|
||
|
||
This chapter is aimed at any user who needs to write a config file,
|
||
including developers and integrators of OpenOCD and any user who needs
|
||
to get a new board working smoothly. It provides guidelines for
|
||
creating those files.
|
||
|
||
You should find the following directories under $(INSTALLDIR)/scripts,
|
||
with config files maintained upstream. Use them as-is where you can; or
|
||
as models for new files.
|
||
* 'interface' ... These are for debug adapters. Files that specify
|
||
configuration to use specific JTAG, SWD and other adapters go here.
|
||
* 'board' ... Think Circuit Board, PWA, PCB, they go by many names.
|
||
Board files contain initialization items that are specific to a
|
||
board.
|
||
|
||
They reuse target configuration files, since the same
|
||
microprocessor chips are used on many boards, but support for
|
||
external parts varies widely. For example, the SDRAM
|
||
initialization sequence for the board, or the type of external
|
||
flash and what address it uses. Any initialization sequence to
|
||
enable that external flash or SDRAM should be found in the board
|
||
file. Boards may also contain multiple targets: two CPUs; or a CPU
|
||
and an FPGA.
|
||
* 'target' ... Think chip. The "target" directory represents the
|
||
JTAG TAPs on a chip which OpenOCD should control, not a board. Two
|
||
common types of targets are ARM chips and FPGA or CPLD chips. When
|
||
a chip has multiple TAPs (maybe it has both ARM and DSP cores), the
|
||
target config file defines all of them.
|
||
* _more_ ... browse for other library files which may be useful.
|
||
For example, there are various generic and CPU-specific utilities.
|
||
|
||
The 'openocd.cfg' user config file may override features in any of the
|
||
above files by setting variables before sourcing the target file, or by
|
||
adding commands specific to their situation.
|
||
|
||
6.1 Interface Config Files
|
||
==========================
|
||
|
||
The user config file should be able to source one of these files with a
|
||
command like this:
|
||
|
||
source [find interface/FOOBAR.cfg]
|
||
|
||
A preconfigured interface file should exist for every debug adapter in
|
||
use today with OpenOCD. That said, perhaps some of these config files
|
||
have only been used by the developer who created it.
|
||
|
||
A separate chapter gives information about how to set these up. *Note
|
||
Debug Adapter Configuration::. Read the OpenOCD source code (and
|
||
Developer's Guide) if you have a new kind of hardware interface and need
|
||
to provide a driver for it.
|
||
|
||
-- Command: find 'filename'
|
||
Prints full path to FILENAME according to OpenOCD search rules.
|
||
|
||
-- Command: ocd_find 'filename'
|
||
Prints full path to FILENAME according to OpenOCD search rules.
|
||
This is a low level function used by the 'find'. Usually you want
|
||
to use 'find', instead.
|
||
|
||
6.2 Board Config Files
|
||
======================
|
||
|
||
The user config file should be able to source one of these files with a
|
||
command like this:
|
||
|
||
source [find board/FOOBAR.cfg]
|
||
|
||
The point of a board config file is to package everything about a given
|
||
board that user config files need to know. In summary the board files
|
||
should contain (if present)
|
||
|
||
1. One or more 'source [find target/...cfg]' statements
|
||
2. NOR flash configuration (*note NOR Configuration:
|
||
norconfiguration.)
|
||
3. NAND flash configuration (*note NAND Configuration:
|
||
nandconfiguration.)
|
||
4. Target 'reset' handlers for SDRAM and I/O configuration
|
||
5. JTAG adapter reset configuration (*note Reset Configuration::)
|
||
6. All things that are not "inside a chip"
|
||
|
||
Generic things inside target chips belong in target config files, not
|
||
board config files. So for example a 'reset-init' event handler should
|
||
know board-specific oscillator and PLL parameters, which it passes to
|
||
target-specific utility code.
|
||
|
||
The most complex task of a board config file is creating such a
|
||
'reset-init' event handler. Define those handlers last, after you
|
||
verify the rest of the board configuration works.
|
||
|
||
6.2.1 Communication Between Config files
|
||
----------------------------------------
|
||
|
||
In addition to target-specific utility code, another way that board and
|
||
target config files communicate is by following a convention on how to
|
||
use certain variables.
|
||
|
||
The full Tcl/Tk language supports "namespaces", but Jim-Tcl does not.
|
||
Thus the rule we follow in OpenOCD is this: Variables that begin with a
|
||
leading underscore are temporary in nature, and can be modified and used
|
||
at will within a target configuration file.
|
||
|
||
Complex board config files can do the things like this, for a board with
|
||
three chips:
|
||
|
||
# Chip #1: PXA270 for network side, big endian
|
||
set CHIPNAME network
|
||
set ENDIAN big
|
||
source [find target/pxa270.cfg]
|
||
# on return: _TARGETNAME = network.cpu
|
||
# other commands can refer to the "network.cpu" target.
|
||
$_TARGETNAME configure .... events for this CPU..
|
||
|
||
# Chip #2: PXA270 for video side, little endian
|
||
set CHIPNAME video
|
||
set ENDIAN little
|
||
source [find target/pxa270.cfg]
|
||
# on return: _TARGETNAME = video.cpu
|
||
# other commands can refer to the "video.cpu" target.
|
||
$_TARGETNAME configure .... events for this CPU..
|
||
|
||
# Chip #3: Xilinx FPGA for glue logic
|
||
set CHIPNAME xilinx
|
||
unset ENDIAN
|
||
source [find target/spartan3.cfg]
|
||
|
||
That example is oversimplified because it doesn't show any flash memory,
|
||
or the 'reset-init' event handlers to initialize external DRAM or
|
||
(assuming it needs it) load a configuration into the FPGA. Such features
|
||
are usually needed for low-level work with many boards, where "low
|
||
level" implies that the board initialization software may not be
|
||
working. (That's a common reason to need JTAG tools. Another is to
|
||
enable working with microcontroller-based systems, which often have no
|
||
debugging support except a JTAG connector.)
|
||
|
||
Target config files may also export utility functions to board and user
|
||
config files. Such functions should use name prefixes, to help avoid
|
||
naming collisions.
|
||
|
||
Board files could also accept input variables from user config files.
|
||
For example, there might be a 'J4_JUMPER' setting used to identify what
|
||
kind of flash memory a development board is using, or how to set up
|
||
other clocks and peripherals.
|
||
|
||
6.2.2 Variable Naming Convention
|
||
--------------------------------
|
||
|
||
Most boards have only one instance of a chip. However, it should be
|
||
easy to create a board with more than one such chip (as shown above).
|
||
Accordingly, we encourage these conventions for naming variables
|
||
associated with different 'target.cfg' files, to promote consistency and
|
||
so that board files can override target defaults.
|
||
|
||
Inputs to target config files include:
|
||
|
||
* 'CHIPNAME' ... This gives a name to the overall chip, and is used
|
||
as part of tap identifier dotted names. While the default is
|
||
normally provided by the chip manufacturer, board files may need to
|
||
distinguish between instances of a chip.
|
||
* 'ENDIAN' ... By default 'little' - although chips may hard-wire
|
||
'big'. Chips that can't change endianness don't need to use this
|
||
variable.
|
||
* 'CPUTAPID' ... When OpenOCD examines the JTAG chain, it can be
|
||
told verify the chips against the JTAG IDCODE register. The target
|
||
file will hold one or more defaults, but sometimes the chip in a
|
||
board will use a different ID (perhaps a newer revision).
|
||
|
||
Outputs from target config files include:
|
||
|
||
* '_TARGETNAME' ... By convention, this variable is created by the
|
||
target configuration script. The board configuration file may make
|
||
use of this variable to configure things like a "reset init"
|
||
script, or other things specific to that board and that target. If
|
||
the chip has 2 targets, the names are '_TARGETNAME0',
|
||
'_TARGETNAME1', ... etc.
|
||
|
||
6.2.3 The reset-init Event Handler
|
||
----------------------------------
|
||
|
||
Board config files run in the OpenOCD configuration stage; they can't
|
||
use TAPs or targets, since they haven't been fully set up yet. This
|
||
means you can't write memory or access chip registers; you can't even
|
||
verify that a flash chip is present. That's done later in event
|
||
handlers, of which the target 'reset-init' handler is one of the most
|
||
important.
|
||
|
||
Except on microcontrollers, the basic job of 'reset-init' event handlers
|
||
is setting up flash and DRAM, as normally handled by boot loaders.
|
||
Microcontrollers rarely use boot loaders; they run right out of their
|
||
on-chip flash and SRAM memory. But they may want to use one of these
|
||
handlers too, if just for developer convenience.
|
||
|
||
Note: Because this is so very board-specific, and chip-specific, no
|
||
examples are included here. Instead, look at the board config
|
||
files distributed with OpenOCD. If you have a boot loader, its
|
||
source code will help; so will configuration files for other JTAG
|
||
tools (*note Translating Configuration Files:
|
||
translatingconfigurationfiles.).
|
||
|
||
Some of this code could probably be shared between different boards.
|
||
For example, setting up a DRAM controller often doesn't differ by much
|
||
except the bus width (16 bits or 32?) and memory timings, so a reusable
|
||
TCL procedure loaded by the 'target.cfg' file might take those as
|
||
parameters. Similarly with oscillator, PLL, and clock setup; and
|
||
disabling the watchdog. Structure the code cleanly, and provide
|
||
comments to help the next developer doing such work. (_You might be
|
||
that next person_ trying to reuse init code!)
|
||
|
||
The last thing normally done in a 'reset-init' handler is probing
|
||
whatever flash memory was configured. For most chips that needs to be
|
||
done while the associated target is halted, either because JTAG memory
|
||
access uses the CPU or to prevent conflicting CPU access.
|
||
|
||
6.2.4 JTAG Clock Rate
|
||
---------------------
|
||
|
||
Before your 'reset-init' handler has set up the PLLs and clocking, you
|
||
may need to run with a low JTAG clock rate. *Note JTAG Speed:
|
||
jtagspeed. Then you'd increase that rate after your handler has made it
|
||
possible to use the faster JTAG clock. When the initial low speed is
|
||
board-specific, for example because it depends on a board-specific
|
||
oscillator speed, then you should probably set it up in the board config
|
||
file; if it's target-specific, it belongs in the target config file.
|
||
|
||
For most ARM-based processors the fastest JTAG clock(1) is one sixth of
|
||
the CPU clock; or one eighth for ARM11 cores. Consult chip
|
||
documentation to determine the peak JTAG clock rate, which might be less
|
||
than that.
|
||
|
||
Warning: On most ARMs, JTAG clock detection is coupled to the core
|
||
clock, so software using a 'wait for interrupt' operation blocks
|
||
JTAG access. Adaptive clocking provides a partial workaround, but
|
||
a more complete solution just avoids using that instruction with
|
||
JTAG debuggers.
|
||
|
||
If both the chip and the board support adaptive clocking, use the
|
||
'jtag_rclk' command, in case your board is used with JTAG adapter which
|
||
also supports it. Otherwise use 'adapter speed'. Set the slow rate at
|
||
the beginning of the reset sequence, and the faster rate as soon as the
|
||
clocks are at full speed.
|
||
|
||
6.2.5 The init_board procedure
|
||
------------------------------
|
||
|
||
The concept of 'init_board' procedure is very similar to 'init_targets'
|
||
(*Note The init_targets procedure: theinittargetsprocedure.) - it's a
|
||
replacement of "linear" configuration scripts. This procedure is meant
|
||
to be executed when OpenOCD enters run stage (*Note Entering the Run
|
||
Stage: enteringtherunstage,) after 'init_targets'. The idea to have
|
||
separate 'init_targets' and 'init_board' procedures is to allow the
|
||
first one to configure everything target specific (internal flash,
|
||
internal RAM, etc.) and the second one to configure everything board
|
||
specific (reset signals, chip frequency, reset-init event handler,
|
||
external memory, etc.). Additionally "linear" board config file will
|
||
most likely fail when target config file uses 'init_targets' scheme
|
||
("linear" script is executed before 'init' and 'init_targets' - after),
|
||
so separating these two configuration stages is very convenient, as the
|
||
easiest way to overcome this problem is to convert board config file to
|
||
use 'init_board' procedure. Board config scripts don't need to override
|
||
'init_targets' defined in target config files when they only need to add
|
||
some specifics.
|
||
|
||
Just as 'init_targets', the 'init_board' procedure can be overridden by
|
||
"next level" script (which sources the original), allowing greater code
|
||
reuse.
|
||
|
||
### board_file.cfg ###
|
||
|
||
# source target file that does most of the config in init_targets
|
||
source [find target/target.cfg]
|
||
|
||
proc enable_fast_clock {} {
|
||
# enables fast on-board clock source
|
||
# configures the chip to use it
|
||
}
|
||
|
||
# initialize only board specifics - reset, clock, adapter frequency
|
||
proc init_board {} {
|
||
reset_config trst_and_srst trst_pulls_srst
|
||
|
||
$_TARGETNAME configure -event reset-start {
|
||
adapter speed 100
|
||
}
|
||
|
||
$_TARGETNAME configure -event reset-init {
|
||
enable_fast_clock
|
||
adapter speed 10000
|
||
}
|
||
}
|
||
|
||
6.3 Target Config Files
|
||
=======================
|
||
|
||
Board config files communicate with target config files using naming
|
||
conventions as described above, and may source one or more target config
|
||
files like this:
|
||
|
||
source [find target/FOOBAR.cfg]
|
||
|
||
The point of a target config file is to package everything about a given
|
||
chip that board config files need to know. In summary the target files
|
||
should contain
|
||
|
||
1. Set defaults
|
||
2. Add TAPs to the scan chain
|
||
3. Add CPU targets (includes GDB support)
|
||
4. CPU/Chip/CPU-Core specific features
|
||
5. On-Chip flash
|
||
|
||
As a rule of thumb, a target file sets up only one chip. For a
|
||
microcontroller, that will often include a single TAP, which is a CPU
|
||
needing a GDB target, and its on-chip flash.
|
||
|
||
More complex chips may include multiple TAPs, and the target config file
|
||
may need to define them all before OpenOCD can talk to the chip. For
|
||
example, some phone chips have JTAG scan chains that include an ARM core
|
||
for operating system use, a DSP, another ARM core embedded in an image
|
||
processing engine, and other processing engines.
|
||
|
||
6.3.1 Default Value Boiler Plate Code
|
||
-------------------------------------
|
||
|
||
All target configuration files should start with code like this, letting
|
||
board config files express environment-specific differences in how
|
||
things should be set up.
|
||
|
||
# Boards may override chip names, perhaps based on role,
|
||
# but the default should match what the vendor uses
|
||
if { [info exists CHIPNAME] } {
|
||
set _CHIPNAME $CHIPNAME
|
||
} else {
|
||
set _CHIPNAME sam7x256
|
||
}
|
||
|
||
# ONLY use ENDIAN with targets that can change it.
|
||
if { [info exists ENDIAN] } {
|
||
set _ENDIAN $ENDIAN
|
||
} else {
|
||
set _ENDIAN little
|
||
}
|
||
|
||
# TAP identifiers may change as chips mature, for example with
|
||
# new revision fields (the "3" here). Pick a good default; you
|
||
# can pass several such identifiers to the "jtag newtap" command.
|
||
if { [info exists CPUTAPID ] } {
|
||
set _CPUTAPID $CPUTAPID
|
||
} else {
|
||
set _CPUTAPID 0x3f0f0f0f
|
||
}
|
||
|
||
_Remember:_ Board config files may include multiple target config files,
|
||
or the same target file multiple times (changing at least 'CHIPNAME').
|
||
|
||
Likewise, the target configuration file should define '_TARGETNAME' (or
|
||
'_TARGETNAME0' etc) and use it later on when defining debug targets:
|
||
|
||
set _TARGETNAME $_CHIPNAME.cpu
|
||
target create $_TARGETNAME arm7tdmi -chain-position $_TARGETNAME
|
||
|
||
6.3.2 Adding TAPs to the Scan Chain
|
||
-----------------------------------
|
||
|
||
After the "defaults" are set up, add the TAPs on each chip to the JTAG
|
||
scan chain. *Note TAP Declaration::, and the naming convention for
|
||
taps.
|
||
|
||
In the simplest case the chip has only one TAP, probably for a CPU or
|
||
FPGA. The config file for the Atmel AT91SAM7X256 looks (in part) like
|
||
this:
|
||
|
||
jtag newtap $_CHIPNAME cpu -irlen 4 -expected-id $_CPUTAPID
|
||
|
||
A board with two such at91sam7 chips would be able to source such a
|
||
config file twice, with different values for 'CHIPNAME', so it adds a
|
||
different TAP each time.
|
||
|
||
If there are nonzero '-expected-id' values, OpenOCD attempts to verify
|
||
the actual tap id against those values. It will issue error messages if
|
||
there is mismatch, which can help to pinpoint problems in OpenOCD
|
||
configurations.
|
||
|
||
JTAG tap: sam7x256.cpu tap/device found: 0x3f0f0f0f
|
||
(Manufacturer: 0x787, Part: 0xf0f0, Version: 0x3)
|
||
ERROR: Tap: sam7x256.cpu - Expected id: 0x12345678, Got: 0x3f0f0f0f
|
||
ERROR: expected: mfg: 0x33c, part: 0x2345, ver: 0x1
|
||
ERROR: got: mfg: 0x787, part: 0xf0f0, ver: 0x3
|
||
|
||
There are more complex examples too, with chips that have multiple TAPs.
|
||
Ones worth looking at include:
|
||
|
||
* 'target/omap3530.cfg' - with disabled ARM and DSP, plus a JRC to
|
||
enable them
|
||
* 'target/str912.cfg' - with flash, CPU, and boundary scan
|
||
* 'target/ti_dm355.cfg' - with ETM, ARM, and JRC (this JRC is not
|
||
currently used)
|
||
|
||
6.3.3 Add CPU targets
|
||
---------------------
|
||
|
||
After adding a TAP for a CPU, you should set it up so that GDB and other
|
||
commands can use it. *Note CPU Configuration::. For the at91sam7
|
||
example above, the command can look like this; note that '$_ENDIAN' is
|
||
not needed, since OpenOCD defaults to little endian, and this chip
|
||
doesn't support changing that.
|
||
|
||
set _TARGETNAME $_CHIPNAME.cpu
|
||
target create $_TARGETNAME arm7tdmi -chain-position $_TARGETNAME
|
||
|
||
Work areas are small RAM areas associated with CPU targets. They are
|
||
used by OpenOCD to speed up downloads, and to download small snippets of
|
||
code to program flash chips. If the chip includes a form of
|
||
"on-chip-ram" - and many do - define a work area if you can. Again
|
||
using the at91sam7 as an example, this can look like:
|
||
|
||
$_TARGETNAME configure -work-area-phys 0x00200000 \
|
||
-work-area-size 0x4000 -work-area-backup 0
|
||
|
||
6.3.4 Define CPU targets working in SMP
|
||
---------------------------------------
|
||
|
||
After setting targets, you can define a list of targets working in SMP.
|
||
|
||
set _TARGETNAME_1 $_CHIPNAME.cpu1
|
||
set _TARGETNAME_2 $_CHIPNAME.cpu2
|
||
target create $_TARGETNAME_1 cortex_a -chain-position $_CHIPNAME.dap \
|
||
-coreid 0 -dbgbase $_DAP_DBG1
|
||
target create $_TARGETNAME_2 cortex_a -chain-position $_CHIPNAME.dap \
|
||
-coreid 1 -dbgbase $_DAP_DBG2
|
||
#define 2 targets working in smp.
|
||
target smp $_CHIPNAME.cpu2 $_CHIPNAME.cpu1
|
||
In the above example on cortex_a, 2 cpus are working in SMP. In SMP only
|
||
one GDB instance is created and :
|
||
* a set of hardware breakpoint sets the same breakpoint on all
|
||
targets in the list.
|
||
* halt command triggers the halt of all targets in the list.
|
||
* resume command triggers the write context and the restart of all
|
||
targets in the list.
|
||
* following a breakpoint: the target stopped by the breakpoint is
|
||
displayed to the GDB session.
|
||
* dedicated GDB serial protocol packets are implemented for
|
||
switching/retrieving the target displayed by the GDB session *note
|
||
Using OpenOCD SMP with GDB: usingopenocdsmpwithgdb.
|
||
|
||
The SMP behaviour can be disabled/enabled dynamically. On cortex_a
|
||
following command have been implemented.
|
||
* cortex_a smp on : enable SMP mode, behaviour is as described above.
|
||
* cortex_a smp off : disable SMP mode, the current target is the one
|
||
displayed in the GDB session, only this target is now controlled by
|
||
GDB session. This behaviour is useful during system boot up.
|
||
* cortex_a smp : display current SMP mode.
|
||
* cortex_a smp_gdb : display/fix the core id displayed in GDB session
|
||
see following example.
|
||
|
||
>cortex_a smp_gdb
|
||
gdb coreid 0 -> -1
|
||
#0 : coreid 0 is displayed to GDB ,
|
||
#-> -1 : next resume triggers a real resume
|
||
> cortex_a smp_gdb 1
|
||
gdb coreid 0 -> 1
|
||
#0 :coreid 0 is displayed to GDB ,
|
||
#->1 : next resume displays coreid 1 to GDB
|
||
> resume
|
||
> cortex_a smp_gdb
|
||
gdb coreid 1 -> 1
|
||
#1 :coreid 1 is displayed to GDB ,
|
||
#->1 : next resume displays coreid 1 to GDB
|
||
> cortex_a smp_gdb -1
|
||
gdb coreid 1 -> -1
|
||
#1 :coreid 1 is displayed to GDB,
|
||
#->-1 : next resume triggers a real resume
|
||
|
||
6.3.5 Chip Reset Setup
|
||
----------------------
|
||
|
||
As a rule, you should put the 'reset_config' command into the board
|
||
file. Most things you think you know about a chip can be tweaked by the
|
||
board.
|
||
|
||
Some chips have specific ways the TRST and SRST signals are managed. In
|
||
the unusual case that these are _chip specific_ and can never be changed
|
||
by board wiring, they could go here. For example, some chips can't
|
||
support JTAG debugging without both signals.
|
||
|
||
Provide a 'reset-assert' event handler if you can. Such a handler uses
|
||
JTAG operations to reset the target, letting this target config be used
|
||
in systems which don't provide the optional SRST signal, or on systems
|
||
where you don't want to reset all targets at once. Such a handler might
|
||
write to chip registers to force a reset, use a JRC to do that
|
||
(preferable - the target may be wedged!), or force a watchdog timer to
|
||
trigger. (For Cortex-M targets, this is not necessary. The target
|
||
driver knows how to use trigger an NVIC reset when SRST is not
|
||
available.)
|
||
|
||
Some chips need special attention during reset handling if they're going
|
||
to be used with JTAG. An example might be needing to send some commands
|
||
right after the target's TAP has been reset, providing a
|
||
'reset-deassert-post' event handler that writes a chip register to
|
||
report that JTAG debugging is being done. Another would be
|
||
reconfiguring the watchdog so that it stops counting while the core is
|
||
halted in the debugger.
|
||
|
||
JTAG clocking constraints often change during reset, and in some cases
|
||
target config files (rather than board config files) are the right
|
||
places to handle some of those issues. For example, immediately after
|
||
reset most chips run using a slower clock than they will use later.
|
||
That means that after reset (and potentially, as OpenOCD first starts
|
||
up) they must use a slower JTAG clock rate than they will use later.
|
||
*Note JTAG Speed: jtagspeed.
|
||
|
||
Important: When you are debugging code that runs right after chip
|
||
reset, getting these issues right is critical. In particular, if
|
||
you see intermittent failures when OpenOCD verifies the scan chain
|
||
after reset, look at how you are setting up JTAG clocking.
|
||
|
||
6.3.6 The init_targets procedure
|
||
--------------------------------
|
||
|
||
Target config files can either be "linear" (script executed line-by-line
|
||
when parsed in configuration stage, *Note Configuration Stage:
|
||
configurationstage,) or they can contain a special procedure called
|
||
'init_targets', which will be executed when entering run stage (after
|
||
parsing all config files or after 'init' command, *Note Entering the Run
|
||
Stage: enteringtherunstage.) Such procedure can be overridden by "next
|
||
level" script (which sources the original). This concept facilitates
|
||
code reuse when basic target config files provide generic configuration
|
||
procedures and 'init_targets' procedure, which can then be sourced and
|
||
enhanced or changed in a "more specific" target config file. This is
|
||
not possible with "linear" config scripts, because sourcing them
|
||
executes every initialization commands they provide.
|
||
|
||
### generic_file.cfg ###
|
||
|
||
proc setup_my_chip {chip_name flash_size ram_size} {
|
||
# basic initialization procedure ...
|
||
}
|
||
|
||
proc init_targets {} {
|
||
# initializes generic chip with 4kB of flash and 1kB of RAM
|
||
setup_my_chip MY_GENERIC_CHIP 4096 1024
|
||
}
|
||
|
||
### specific_file.cfg ###
|
||
|
||
source [find target/generic_file.cfg]
|
||
|
||
proc init_targets {} {
|
||
# initializes specific chip with 128kB of flash and 64kB of RAM
|
||
setup_my_chip MY_CHIP_WITH_128K_FLASH_64KB_RAM 131072 65536
|
||
}
|
||
|
||
The easiest way to convert "linear" config files to 'init_targets'
|
||
version is to enclose every line of "code" (i.e. not 'source' commands,
|
||
procedures, etc.) in this procedure.
|
||
|
||
For an example of this scheme see LPC2000 target config files.
|
||
|
||
The 'init_boards' procedure is a similar concept concerning board config
|
||
files (*Note The init_board procedure: theinitboardprocedure.)
|
||
|
||
6.3.7 The init_target_events procedure
|
||
--------------------------------------
|
||
|
||
A special procedure called 'init_target_events' is run just after
|
||
'init_targets' (*Note The init_targets procedure:
|
||
theinittargetsprocedure.) and before 'init_board' (*Note The init_board
|
||
procedure: theinitboardprocedure.) It is used to set up default target
|
||
events for the targets that do not have those events already assigned.
|
||
|
||
6.3.8 ARM Core Specific Hacks
|
||
-----------------------------
|
||
|
||
If the chip has a DCC, enable it. If the chip is an ARM9 with some
|
||
special high speed download features - enable it.
|
||
|
||
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".
|
||
(*Note ARM Hardware Tracing: armhardwaretracing.) If you are using an
|
||
external trace port, configure it in your board config file. If you are
|
||
using an on-chip "Embedded Trace Buffer" (ETB), configure it in your
|
||
target config file.
|
||
|
||
etm config $_TARGETNAME 16 normal full etb
|
||
etb config $_TARGETNAME $_CHIPNAME.etb
|
||
|
||
6.3.9 Internal Flash Configuration
|
||
----------------------------------
|
||
|
||
This applies ONLY TO MICROCONTROLLERS that have flash built in.
|
||
|
||
Never ever in the "target configuration file" define any type of flash
|
||
that is external to the chip. (For example a BOOT flash on Chip Select
|
||
0.) Such flash information goes in a board file - not the TARGET (chip)
|
||
file.
|
||
|
||
Examples:
|
||
* at91sam7x256 - has 256K flash YES enable it.
|
||
* str912 - has flash internal YES enable it.
|
||
* imx27 - uses boot flash on CS0 - it goes in the board file.
|
||
* pxa270 - again - CS0 flash - it goes in the board file.
|
||
|
||
6.4 Translating Configuration Files
|
||
===================================
|
||
|
||
If you have a configuration file for another hardware debugger or
|
||
toolset (Abatron, BDI2000, BDI3000, CCS, Lauterbach, SEGGER, Macraigor,
|
||
etc.), translating it into OpenOCD syntax is often quite
|
||
straightforward. The most tricky part of creating a configuration
|
||
script is oftentimes the reset init sequence where e.g. PLLs, DRAM and
|
||
the like is set up.
|
||
|
||
One trick that you can use when translating is to write small Tcl
|
||
procedures to translate the syntax into OpenOCD syntax. This can avoid
|
||
manual translation errors and make it easier to convert other scripts
|
||
later on.
|
||
|
||
Example of transforming quirky arguments to a simple search and replace
|
||
job:
|
||
|
||
# Lauterbach syntax(?)
|
||
#
|
||
# Data.Set c15:0x042f %long 0x40000015
|
||
#
|
||
# OpenOCD syntax when using procedure below.
|
||
#
|
||
# setc15 0x01 0x00050078
|
||
|
||
proc setc15 {regs value} {
|
||
global TARGETNAME
|
||
|
||
echo [format "set p15 0x%04x, 0x%08x" $regs $value]
|
||
|
||
arm mcr 15 [expr ($regs>>12)&0x7] \
|
||
[expr ($regs>>0)&0xf] [expr ($regs>>4)&0xf] \
|
||
[expr ($regs>>8)&0x7] $value
|
||
}
|
||
|
||
---------- Footnotes ----------
|
||
|
||
(1) A FAQ <http://www.arm.com/support/faqdev/4170.html> gives
|
||
details.
|
||
|
||
|
||
File: openocd.info, Node: Server Configuration, Next: Debug Adapter Configuration, Prev: Config File Guidelines, Up: Top
|
||
|
||
7 Server Configuration
|
||
**********************
|
||
|
||
The commands here are commonly found in the openocd.cfg file and are
|
||
used to specify what TCP/IP ports are used, and how GDB should be
|
||
supported.
|
||
|
||
7.1 Configuration Stage
|
||
=======================
|
||
|
||
When the OpenOCD server process starts up, it enters a _configuration
|
||
stage_ which is the only time that certain commands, _configuration
|
||
commands_, may be issued. Normally, configuration commands are only
|
||
available inside startup scripts.
|
||
|
||
In this manual, the definition of a configuration command is presented
|
||
as a _Config Command_, not as a _Command_ which may be issued
|
||
interactively. The runtime 'help' command also highlights configuration
|
||
commands, and those which may be issued at any time.
|
||
|
||
Those configuration commands include declaration of TAPs, flash banks,
|
||
the interface used for JTAG communication, and other basic setup. The
|
||
server must leave the configuration stage before it may access or
|
||
activate TAPs. After it leaves this stage, configuration commands may
|
||
no longer be issued.
|
||
|
||
-- Command: command mode [command_name]
|
||
Returns the command modes allowed by a command: 'any', 'config', or
|
||
'exec'. If no command is specified, returns the current command
|
||
mode. Returns 'unknown' if an unknown command is given. Command
|
||
can be multiple tokens. (command valid any time)
|
||
|
||
In this document, the modes are described as stages, 'config' and
|
||
'exec' mode correspond configuration stage and run stage. 'any'
|
||
means the command can be executed in either stages. *Note
|
||
Configuration Stage: configurationstage, and *Note Entering the Run
|
||
Stage: enteringtherunstage.
|
||
|
||
7.2 Entering the Run Stage
|
||
==========================
|
||
|
||
The first thing OpenOCD does after leaving the configuration stage is to
|
||
verify that it can talk to the scan chain (list of TAPs) which has been
|
||
configured. It will warn if it doesn't find TAPs it expects to find, or
|
||
finds TAPs that aren't supposed to be there. You should see no errors
|
||
at this point. If you see errors, resolve them by correcting the
|
||
commands you used to configure the server. Common errors include using
|
||
an initial JTAG speed that's too fast, and not providing the right
|
||
IDCODE values for the TAPs on the scan chain.
|
||
|
||
Once OpenOCD has entered the run stage, a number of commands become
|
||
available. A number of these relate to the debug targets you may have
|
||
declared. For example, the 'mww' command will not be available until a
|
||
target has been successfully instantiated. If you want to use those
|
||
commands, you may need to force entry to the run stage.
|
||
|
||
-- Config Command: init
|
||
This command terminates the configuration stage and enters the run
|
||
stage. This helps when you need to have the startup scripts manage
|
||
tasks such as resetting the target, programming flash, etc. To
|
||
reset the CPU upon startup, add "init" and "reset" at the end of
|
||
the config script or at the end of the OpenOCD command line using
|
||
the '-c' command line switch.
|
||
|
||
If this command does not appear in any startup/configuration file
|
||
OpenOCD executes the command for you after processing all
|
||
configuration files and/or command line options.
|
||
|
||
NOTE: This command normally occurs near the end of your openocd.cfg
|
||
file to force OpenOCD to "initialize" and make the targets ready.
|
||
For example: If your openocd.cfg file needs to read/write memory on
|
||
your target, 'init' must occur before the memory read/write
|
||
commands. This includes 'nand probe'.
|
||
|
||
'init' calls the following internal OpenOCD commands to initialize
|
||
corresponding subsystems:
|
||
-- Config Command: target init
|
||
-- Command: transport init
|
||
-- Command: dap init
|
||
-- Config Command: flash init
|
||
-- Config Command: nand init
|
||
-- Config Command: pld init
|
||
-- Command: tpiu init
|
||
|
||
-- Config Command: noinit
|
||
Prevent OpenOCD from implicit 'init' call at the end of startup.
|
||
Allows issuing configuration commands over telnet or Tcl
|
||
connection. When you are done with configuration use 'init' to
|
||
enter the run stage.
|
||
|
||
-- Overridable Procedure: jtag_init
|
||
This is invoked at server startup to verify that it can talk to the
|
||
scan chain (list of TAPs) which has been configured.
|
||
|
||
The default implementation first tries 'jtag arp_init', which uses
|
||
only a lightweight JTAG reset before examining the scan chain. If
|
||
that fails, it tries again, using a harder reset from the
|
||
overridable procedure 'init_reset'.
|
||
|
||
Implementations must have verified the JTAG scan chain before they
|
||
return. This is done by calling 'jtag arp_init' (or 'jtag
|
||
arp_init-reset').
|
||
|
||
7.3 TCP/IP Ports
|
||
================
|
||
|
||
The OpenOCD server accepts remote commands in several syntaxes. Each
|
||
syntax uses a different TCP/IP port, which you may specify only during
|
||
configuration (before those ports are opened).
|
||
|
||
For reasons including security, you may wish to prevent remote access
|
||
using one or more of these ports. In such cases, just specify the
|
||
relevant port number as "disabled". If you disable all access through
|
||
TCP/IP, you will need to use the command line '-pipe' option.
|
||
|
||
-- Config Command: gdb_port [number]
|
||
Normally gdb listens to a TCP/IP port, but GDB can also communicate
|
||
via pipes(stdin/out or named pipes). The name "gdb_port" stuck
|
||
because it covers probably more than 90% of the normal use cases.
|
||
|
||
No arguments reports GDB port. "pipe" means listen to stdin output
|
||
to stdout, an integer is base port number, "disabled" disables the
|
||
gdb server.
|
||
|
||
When using "pipe", also use log_output to redirect the log output
|
||
to a file so as not to flood the stdin/out pipes.
|
||
|
||
Any other string is interpreted as named pipe to listen to. Output
|
||
pipe is the same name as input pipe, but with 'o' appended, e.g.
|
||
/var/gdb, /var/gdbo.
|
||
|
||
The GDB port for the first target will be the base port, the second
|
||
target will listen on gdb_port + 1, and so on. When not specified
|
||
during the configuration stage, the port NUMBER defaults to 3333.
|
||
When NUMBER is not a numeric value, incrementing it to compute the
|
||
next port number does not work. In this case, specify the proper
|
||
NUMBER for each target by using the option '-gdb-port' of the
|
||
commands 'target create' or '$target_name configure'. *Note option
|
||
-gdb-port: gdbportoverride.
|
||
|
||
Note: when using "gdb_port pipe", increasing the default remote
|
||
timeout in gdb (with 'set remotetimeout') is recommended. An
|
||
insufficient timeout may cause initialization to fail with "Unknown
|
||
remote qXfer reply: OK".
|
||
|
||
-- Config Command: tcl_port [number]
|
||
Specify or query the port used for a simplified RPC connection that
|
||
can be used by clients to issue TCL commands and get the output
|
||
from the Tcl engine. Intended as a machine interface. When not
|
||
specified during the configuration stage, the port NUMBER defaults
|
||
to 6666. When specified as "disabled", this service is not
|
||
activated.
|
||
|
||
-- Config Command: telnet_port [number]
|
||
Specify or query the port on which to listen for incoming telnet
|
||
connections. This port is intended for interaction with one human
|
||
through TCL commands. When not specified during the configuration
|
||
stage, the port NUMBER defaults to 4444. When specified as
|
||
"disabled", this service is not activated.
|
||
|
||
7.4 GDB Configuration
|
||
=====================
|
||
|
||
You can reconfigure some GDB behaviors if needed. The ones listed here
|
||
are static and global. *Note Target Configuration: targetconfiguration,
|
||
about configuring individual targets. *Note Target Events:
|
||
targetevents, about configuring target-specific event handling.
|
||
|
||
-- Command: gdb_breakpoint_override ['hard'|'soft'|'disable']
|
||
Force breakpoint type for gdb 'break' commands. This option
|
||
supports GDB GUIs which don't distinguish hard versus soft
|
||
breakpoints, if the default OpenOCD and GDB behaviour is not
|
||
sufficient. GDB normally uses hardware breakpoints if the memory
|
||
map has been set up for flash regions.
|
||
|
||
-- Config Command: gdb_flash_program ('enable'|'disable')
|
||
Set to 'enable' to cause OpenOCD to program the flash memory when a
|
||
vFlash packet is received. The default behaviour is 'enable'.
|
||
|
||
-- Config Command: gdb_memory_map ('enable'|'disable')
|
||
Set to '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.
|
||
'gdb_flash_program enable' must also be enabled for flash
|
||
programming to work. Default behaviour is 'enable'. *Note
|
||
gdb_flash_program: gdbflashprogram.
|
||
|
||
-- Config Command: gdb_report_data_abort ('enable'|'disable')
|
||
Specifies whether data aborts cause an error to be reported by GDB
|
||
memory read packets. The default behaviour is 'disable'; use
|
||
'enable' see these errors reported.
|
||
|
||
-- Config Command: gdb_report_register_access_error
|
||
('enable'|'disable')
|
||
Specifies whether register accesses requested by GDB register
|
||
read/write packets report errors or not. The default behaviour is
|
||
'disable'; use 'enable' see these errors reported.
|
||
|
||
-- Config Command: gdb_target_description ('enable'|'disable')
|
||
Set to 'enable' to cause OpenOCD to send the target descriptions to
|
||
gdb via qXfer:features:read packet. The default behaviour is
|
||
'enable'.
|
||
|
||
-- Command: gdb_save_tdesc
|
||
Saves the target description file to the local file system.
|
||
|
||
The file name is target_name.xml.
|
||
|
||
7.5 Event Polling
|
||
=================
|
||
|
||
Hardware debuggers are parts of asynchronous systems, where significant
|
||
events can happen at any time. The OpenOCD server needs to detect some
|
||
of these events, so it can report them to through TCL command line or to
|
||
GDB.
|
||
|
||
Examples of such events include:
|
||
|
||
* One of the targets can stop running ... maybe it triggers a code
|
||
breakpoint or data watchpoint, or halts itself.
|
||
* Messages may be sent over "debug message" channels ... many
|
||
targets support such messages sent over JTAG, for receipt by the
|
||
person debugging or tools.
|
||
* Loss of power ... some adapters can detect these events.
|
||
* Resets not issued through JTAG ... such reset sources can include
|
||
button presses or other system hardware, sometimes including the
|
||
target itself (perhaps through a watchdog).
|
||
* Debug instrumentation sometimes supports event triggering such as
|
||
"trace buffer full" (so it can quickly be emptied) or other signals
|
||
(to correlate with code behavior).
|
||
|
||
None of those events are signaled through standard JTAG signals.
|
||
However, most conventions for JTAG connectors include voltage level and
|
||
system reset (SRST) signal detection. Some connectors also include
|
||
instrumentation signals, which can imply events when those signals are
|
||
inputs.
|
||
|
||
In general, OpenOCD needs to periodically check for those events, either
|
||
by looking at the status of signals on the JTAG connector or by sending
|
||
synchronous "tell me your status" JTAG requests to the various active
|
||
targets. There is a command to manage and monitor that polling, which
|
||
is normally done in the background.
|
||
|
||
-- Command: poll ['on'|'off']
|
||
Poll the current target for its current state. (Also, *note target
|
||
curstate: targetcurstate.) If that target is in debug mode,
|
||
architecture specific information about the current state is
|
||
printed. An optional parameter allows background polling to be
|
||
enabled and disabled.
|
||
|
||
You could use this from the TCL command shell, or from GDB using
|
||
'monitor poll' command. Leave background polling enabled while
|
||
you're using GDB.
|
||
> poll
|
||
background polling: on
|
||
target state: halted
|
||
target halted in ARM state due to debug-request, \
|
||
current mode: Supervisor
|
||
cpsr: 0x800000d3 pc: 0x11081bfc
|
||
MMU: disabled, D-Cache: disabled, I-Cache: enabled
|
||
>
|
||
|
||
|
||
File: openocd.info, Node: Debug Adapter Configuration, Next: Reset Configuration, Prev: Server Configuration, Up: Top
|
||
|
||
8 Debug Adapter Configuration
|
||
*****************************
|
||
|
||
Correctly installing OpenOCD includes making your operating system give
|
||
OpenOCD access to debug adapters. Once that has been done, Tcl commands
|
||
are used to select which one is used, and to configure how it is used.
|
||
|
||
Note: Because OpenOCD started out with a focus purely on JTAG, you
|
||
may find places where it wrongly presumes JTAG is the only
|
||
transport protocol in use. Be aware that recent versions of
|
||
OpenOCD are removing that limitation. JTAG remains more functional
|
||
than most other transports. Other transports do not support
|
||
boundary scan operations, or may be specific to a given chip
|
||
vendor. Some might be usable only for programming flash memory,
|
||
instead of also for debugging.
|
||
|
||
Debug Adapters/Interfaces/Dongles are normally configured through
|
||
commands in an interface configuration file which is sourced by your
|
||
'openocd.cfg' file, or through a command line '-f interface/....cfg'
|
||
option.
|
||
|
||
source [find interface/olimex-jtag-tiny.cfg]
|
||
|
||
These commands tell OpenOCD what type of JTAG adapter you have, and how
|
||
to talk to it. A few cases are so simple that you only need to say what
|
||
driver to use:
|
||
|
||
# jlink interface
|
||
adapter driver jlink
|
||
|
||
Most adapters need a bit more configuration than that.
|
||
|
||
8.1 Adapter Configuration
|
||
=========================
|
||
|
||
The 'adapter driver' command tells OpenOCD what type of debug adapter
|
||
you are using. Depending on the type of adapter, you may need to use
|
||
one or more additional commands to further identify or configure the
|
||
adapter.
|
||
|
||
-- Config Command: adapter driver name
|
||
Use the adapter driver NAME to connect to the target.
|
||
|
||
-- Command: adapter list
|
||
List the debug adapter drivers that have been built into the
|
||
running copy of OpenOCD.
|
||
-- Config Command: adapter transports transport_name+
|
||
Specifies the transports supported by this debug adapter. The
|
||
adapter driver builds-in similar knowledge; use this only when
|
||
external configuration (such as jumpering) changes what the
|
||
hardware can support.
|
||
|
||
-- Command: adapter name
|
||
Returns the name of the debug adapter driver being used.
|
||
|
||
-- Config Command: adapter usb location [<bus>-<port>[.<port>]...]
|
||
Displays or specifies the physical USB port of the adapter to use.
|
||
The path roots at BUS and walks down the physical ports, with each
|
||
PORT option specifying a deeper level in the bus topology, the last
|
||
PORT denoting where the target adapter is actually plugged. The
|
||
USB bus topology can be queried with the command _lsusb -t_ or
|
||
_dmesg_.
|
||
|
||
This command is only available if your libusb1 is at least version
|
||
1.0.16.
|
||
|
||
-- Config Command: adapter serial serial_string
|
||
Specifies the SERIAL_STRING of the adapter to use. If this command
|
||
is not specified, serial strings are not checked. Only the
|
||
following adapter drivers use the serial string from this command:
|
||
aice (aice_usb), arm-jtag-ew, cmsis_dap, ft232r, ftdi, hla (stlink,
|
||
ti-icdi), jlink, kitprog, opendus, openjtag, osbdm, presto, rlink,
|
||
st-link, usb_blaster (ublast2), usbprog, vsllink, xds110.
|
||
|
||
8.2 Interface Drivers
|
||
=====================
|
||
|
||
Each of the interface drivers listed here must be explicitly enabled
|
||
when OpenOCD is configured, in order to be made available at run time.
|
||
|
||
-- Interface Driver: amt_jtagaccel
|
||
Amontec Chameleon in its JTAG Accelerator configuration, connected
|
||
to a PC's EPP mode parallel port. This defines some
|
||
driver-specific commands:
|
||
|
||
-- Config Command: parport port number
|
||
Specifies either the address of the I/O port (default: 0x378
|
||
for LPT1) or the number of the '/dev/parport' device.
|
||
|
||
-- Config Command: rtck ['enable'|'disable']
|
||
Displays status of RTCK option. Optionally sets that option
|
||
first.
|
||
|
||
-- Interface Driver: arm-jtag-ew
|
||
Olimex ARM-JTAG-EW USB adapter This has one driver-specific
|
||
command:
|
||
|
||
-- Command: armjtagew_info
|
||
Logs some status
|
||
|
||
-- Interface Driver: at91rm9200
|
||
Supports bitbanged JTAG from the local system, presuming that
|
||
system is an Atmel AT91rm9200 and a specific set of GPIOs is used.
|
||
|
||
-- Interface Driver: cmsis-dap
|
||
ARM CMSIS-DAP compliant based adapter v1 (USB HID based) or v2 (USB
|
||
bulk).
|
||
|
||
-- Config Command: cmsis_dap_vid_pid [vid pid]+
|
||
The vendor ID and product ID of the CMSIS-DAP device. If not
|
||
specified the driver will attempt to auto detect the CMSIS-DAP
|
||
device. Currently, up to eight [VID, PID] pairs may be given,
|
||
e.g.
|
||
cmsis_dap_vid_pid 0xc251 0xf001 0x0d28 0x0204
|
||
|
||
-- Config Command: cmsis_dap_backend ['auto'|'usb_bulk'|'hid']
|
||
Specifies how to communicate with the adapter:
|
||
|
||
- 'hid' Use HID generic reports - CMSIS-DAP v1
|
||
- 'usb_bulk' Use USB bulk - CMSIS-DAP v2
|
||
- 'auto' First try USB bulk CMSIS-DAP v2, if not found try
|
||
HID CMSIS-DAP v1. This is the default if
|
||
'cmsis_dap_backend' is not specified.
|
||
|
||
-- Config Command: cmsis_dap_usb interface [number]
|
||
Specifies the NUMBER of the USB interface to use in v2 mode
|
||
(USB bulk). In most cases need not to be specified and
|
||
interfaces are searched by interface string or for user class
|
||
interface.
|
||
|
||
-- Command: cmsis-dap info
|
||
Display various device information, like hardware version,
|
||
firmware version, current bus status.
|
||
|
||
-- Command: cmsis-dap cmd number number ...
|
||
Execute an arbitrary CMSIS-DAP command. Use for adapter
|
||
testing or for handling of an adapter vendor specific command
|
||
from a Tcl script.
|
||
|
||
Take given numbers as bytes, assemble a CMSIS-DAP protocol
|
||
command packet from them and send it to the adapter. The
|
||
first 4 bytes of the adapter response are logged. See
|
||
<https://arm-software.github.io/CMSIS_5/DAP/html/group__DAP__Commands__gr.html>
|
||
|
||
-- Interface Driver: dummy
|
||
A dummy software-only driver for debugging.
|
||
|
||
-- Interface Driver: ep93xx
|
||
Cirrus Logic EP93xx based single-board computer bit-banging (in
|
||
development)
|
||
|
||
-- Interface Driver: ftdi
|
||
This driver is for adapters using the MPSSE (Multi-Protocol
|
||
Synchronous Serial Engine) mode built into many FTDI chips, such as
|
||
the FT2232, FT4232 and FT232H.
|
||
|
||
The driver is using libusb-1.0 in asynchronous mode to talk to the
|
||
FTDI device, bypassing intermediate libraries like libftdi.
|
||
|
||
Support for new FTDI based adapters can be added completely through
|
||
configuration files, without the need to patch and rebuild OpenOCD.
|
||
|
||
The driver uses a signal abstraction to enable Tcl configuration
|
||
files to define outputs for one or several FTDI GPIO. These outputs
|
||
can then be controlled using the 'ftdi set_signal' command.
|
||
Special signal names are reserved for nTRST, nSRST and LED (for
|
||
blink) so that they, if defined, will be used for their customary
|
||
purpose. Inputs can be read using the 'ftdi get_signal' command.
|
||
|
||
To support SWD, a signal named SWD_EN must be defined. It is set
|
||
to 1 when the SWD protocol is selected. When set, the adapter
|
||
should route the SWDIO pin to the data input. An SWDIO_OE signal,
|
||
if defined, will be set to 1 or 0 as required by the protocol, to
|
||
tell the adapter to drive the data output onto the SWDIO pin or
|
||
keep the SWDIO pin Hi-Z, respectively.
|
||
|
||
Depending on the type of buffer attached to the FTDI GPIO, the
|
||
outputs have to be controlled differently. In order to support
|
||
tristateable signals such as nSRST, both a data GPIO and an
|
||
output-enable GPIO can be specified for each signal. The following
|
||
output buffer configurations are supported:
|
||
|
||
- Push-pull with one FTDI output as (non-)inverted data line
|
||
- Open drain with one FTDI output as (non-)inverted
|
||
output-enable
|
||
- Tristate with one FTDI output as (non-)inverted data line and
|
||
another FTDI output as (non-)inverted output-enable
|
||
- Unbuffered, using the FTDI GPIO as a tristate output directly
|
||
by switching data and direction as necessary
|
||
|
||
These interfaces have several commands, used to configure the
|
||
driver before initializing the JTAG scan chain:
|
||
|
||
-- Config Command: ftdi vid_pid [vid pid]+
|
||
The vendor ID and product ID of the adapter. Up to eight
|
||
[VID, PID] pairs may be given, e.g.
|
||
ftdi vid_pid 0x0403 0xcff8 0x15ba 0x0003
|
||
|
||
-- Config Command: ftdi device_desc description
|
||
Provides the USB device description (the _iProduct string_) of
|
||
the adapter. If not specified, the device description is
|
||
ignored during device selection.
|
||
|
||
-- Config Command: ftdi channel channel
|
||
Selects the channel of the FTDI device to use for MPSSE
|
||
operations. Most adapters use the default, channel 0, but
|
||
there are exceptions.
|
||
|
||
-- Config Command: ftdi layout_init data direction
|
||
Specifies the initial values of the FTDI GPIO data and
|
||
direction registers. Each value is a 16-bit number
|
||
corresponding to the concatenation of the high and low FTDI
|
||
GPIO registers. The values should be selected based on the
|
||
schematics of the adapter, such that all signals are set to
|
||
safe levels with minimal impact on the target system. Avoid
|
||
floating inputs, conflicting outputs and initially asserted
|
||
reset signals.
|
||
|
||
-- Command: ftdi layout_signal name ['-data'|'-ndata' data_mask]
|
||
['-input'|'-ninput' input_mask] ['-oe'|'-noe' oe_mask]
|
||
['-alias'|'-nalias' name]
|
||
Creates a signal with the specified 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 buffer
|
||
driving the respective signal. DATA_MASK is the bitmask for
|
||
the pin(s) connected to the data input of the output buffer.
|
||
'-ndata' is used with inverting data inputs and '-data' with
|
||
non-inverting inputs. The '-oe' (or '-noe') option tells
|
||
where the output-enable (or not-output-enable) input to the
|
||
output buffer is connected. The options '-input' and
|
||
'-ninput' specify the bitmask for pins to be read with the
|
||
method 'ftdi get_signal'.
|
||
|
||
Both DATA_MASK and OE_MASK need not be specified. For
|
||
example, a simple open-collector transistor driver would be
|
||
specified with '-oe' only. In that case the signal can only
|
||
be set to drive low or to Hi-Z and the driver will complain if
|
||
the signal is set to drive high. Which means that if it's a
|
||
reset signal, 'reset_config' must be specified as
|
||
'srst_open_drain', not 'srst_push_pull'.
|
||
|
||
A special case is provided when '-data' and '-oe' is set to
|
||
the same bitmask. Then the FTDI pin is considered being
|
||
connected straight to the 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 '-alias' or '-nalias' is used, the signal is created
|
||
identical (or with data inverted) to an already specified
|
||
signal NAME.
|
||
|
||
-- Command: ftdi set_signal name '0'|'1'|'z'
|
||
Set a previously defined signal to the specified level.
|
||
- '0', drive low
|
||
- '1', drive high
|
||
- 'z', set to high-impedance
|
||
|
||
-- Command: ftdi get_signal name
|
||
Get the value of a previously defined signal.
|
||
|
||
-- Command: ftdi tdo_sample_edge 'rising'|'falling'
|
||
Configure TCK edge at which the adapter samples the value of
|
||
the TDO signal
|
||
|
||
Due to signal propagation delays, sampling TDO on rising TCK
|
||
can become quite peculiar at high JTAG clock speeds. However,
|
||
FTDI chips offer a possibility to sample TDO on falling edge
|
||
of TCK. With some board/adapter configurations, this may
|
||
increase stability at higher JTAG clocks.
|
||
- 'rising', sample TDO on rising edge of TCK - this is the
|
||
default
|
||
- 'falling', sample TDO on falling edge of TCK
|
||
|
||
For example adapter definitions, see the configuration files
|
||
shipped in the 'interface/ftdi' directory.
|
||
|
||
-- Interface Driver: ft232r
|
||
This driver is implementing synchronous bitbang mode of an FTDI
|
||
FT232R, FT230X, FT231X and similar USB UART bridge ICs by reusing
|
||
RS232 signals as GPIO. It currently doesn't support using CBUS pins
|
||
as GPIO.
|
||
|
||
List of connections (default physical pin numbers for FT232R in
|
||
28-pin SSOP package):
|
||
- RXD(5) - TDI
|
||
- TXD(1) - TCK
|
||
- RTS(3) - TDO
|
||
- CTS(11) - TMS
|
||
- DTR(2) - TRST
|
||
- DCD(10) - SRST
|
||
|
||
User can change default pinout by supplying configuration commands
|
||
with GPIO numbers or RS232 signal names. GPIO numbers correspond
|
||
to bit numbers in FTDI GPIO register. They differ from physical
|
||
pin numbers. For details see actual FTDI chip datasheets. Every
|
||
JTAG line must be configured to unique GPIO number different than
|
||
any other JTAG line, even those lines that are sometimes not used
|
||
like TRST or SRST.
|
||
|
||
FT232R
|
||
- bit 7 - RI
|
||
- bit 6 - DCD
|
||
- bit 5 - DSR
|
||
- bit 4 - DTR
|
||
- bit 3 - CTS
|
||
- bit 2 - RTS
|
||
- bit 1 - RXD
|
||
- bit 0 - TXD
|
||
|
||
These interfaces have several commands, used to configure the
|
||
driver before initializing the JTAG scan chain:
|
||
|
||
-- Config Command: ft232r vid_pid VID PID
|
||
The vendor ID and product ID of the adapter. If not
|
||
specified, default 0x0403:0x6001 is used.
|
||
|
||
-- Config Command: ft232r jtag_nums TCK TMS TDI TDO
|
||
Set four JTAG GPIO numbers at once. If not specified, default
|
||
0 3 1 2 or TXD CTS RXD RTS is used.
|
||
|
||
-- Config Command: ft232r tck_num TCK
|
||
Set TCK GPIO number. If not specified, default 0 or TXD is
|
||
used.
|
||
|
||
-- Config Command: ft232r tms_num TMS
|
||
Set TMS GPIO number. If not specified, default 3 or CTS is
|
||
used.
|
||
|
||
-- Config Command: ft232r tdi_num TDI
|
||
Set TDI GPIO number. If not specified, default 1 or RXD is
|
||
used.
|
||
|
||
-- Config Command: ft232r tdo_num TDO
|
||
Set TDO GPIO number. If not specified, default 2 or RTS is
|
||
used.
|
||
|
||
-- Config Command: ft232r trst_num TRST
|
||
Set TRST GPIO number. If not specified, default 4 or DTR is
|
||
used.
|
||
|
||
-- Config Command: ft232r srst_num SRST
|
||
Set SRST GPIO number. If not specified, default 6 or DCD is
|
||
used.
|
||
|
||
-- Config Command: ft232r restore_serial WORD
|
||
Restore serial port after JTAG. This USB bitmode control word
|
||
(16-bit) will be sent before quit. Lower byte should set GPIO
|
||
direction register to a "sane" state: 0x15 for TXD RTS DTR as
|
||
outputs (1), others as inputs (0). Higher byte is usually 0
|
||
to disable bitbang mode. When kernel driver reattaches,
|
||
serial port should continue to work. Value 0xFFFF disables
|
||
sending control word and serial port, then kernel driver will
|
||
not reattach. If not specified, default 0xFFFF is used.
|
||
|
||
-- Interface Driver: remote_bitbang
|
||
Drive JTAG from a remote process. This sets up a UNIX or TCP
|
||
socket connection with a remote process and sends ASCII encoded
|
||
bitbang requests to that process instead of directly driving JTAG.
|
||
|
||
The remote_bitbang driver is useful for debugging software running
|
||
on processors which are being simulated.
|
||
|
||
-- Config Command: remote_bitbang port number
|
||
Specifies the TCP port of the remote process to connect to or
|
||
0 to use UNIX sockets instead of TCP.
|
||
|
||
-- Config Command: remote_bitbang host hostname
|
||
Specifies the hostname of the remote process to connect to
|
||
using TCP, or the name of the UNIX socket to use if
|
||
remote_bitbang port is 0.
|
||
|
||
For example, to connect remotely via TCP to the host foobar you
|
||
might have something like:
|
||
|
||
adapter driver remote_bitbang
|
||
remote_bitbang port 3335
|
||
remote_bitbang host foobar
|
||
|
||
To connect to another process running locally via UNIX sockets with
|
||
socket named mysocket:
|
||
|
||
adapter driver remote_bitbang
|
||
remote_bitbang port 0
|
||
remote_bitbang host mysocket
|
||
|
||
-- Interface Driver: usb_blaster
|
||
USB JTAG/USB-Blaster compatibles over one of the userspace
|
||
libraries for FTDI chips. These interfaces have several commands,
|
||
used to configure the driver before initializing the JTAG scan
|
||
chain:
|
||
|
||
-- Config Command: usb_blaster vid_pid vid pid
|
||
The vendor ID and product ID of the FTDI FT245 device. If not
|
||
specified, default values are used. Currently, only one VID,
|
||
PID pair may be given, e.g. for Altera USB-Blaster (default):
|
||
usb_blaster vid_pid 0x09FB 0x6001
|
||
The following VID/PID is for Kolja Waschk's USB JTAG:
|
||
usb_blaster vid_pid 0x16C0 0x06AD
|
||
|
||
-- Command: usb_blaster pin ('pin6'|'pin8') ('0'|'1'|'s'|'t')
|
||
Sets the state or function of the unused GPIO pins on
|
||
USB-Blasters (pins 6 and 8 on the female JTAG header). These
|
||
pins can be used as SRST and/or TRST provided the appropriate
|
||
connections are made on the target board.
|
||
|
||
For example, to use pin 6 as SRST:
|
||
usb_blaster pin pin6 s
|
||
reset_config srst_only
|
||
|
||
-- Config Command: usb_blaster lowlevel_driver ('ftdi'|'ublast2')
|
||
Chooses the low level access method for the adapter. If not
|
||
specified, 'ftdi' is selected unless it wasn't enabled during
|
||
the configure stage. USB-Blaster II needs 'ublast2'.
|
||
|
||
-- Config Command: usb_blaster firmware PATH
|
||
This command specifies PATH to access USB-Blaster II firmware
|
||
image. To be used with USB-Blaster II only.
|
||
|
||
-- Interface Driver: gw16012
|
||
Gateworks GW16012 JTAG programmer. This has one driver-specific
|
||
command:
|
||
|
||
-- Config Command: parport port [port_number]
|
||
Display either the address of the I/O port (default: 0x378 for
|
||
LPT1) or the number of the '/dev/parport' device. If a
|
||
parameter is provided, first switch to use that port. This is
|
||
a write-once setting.
|
||
|
||
-- Interface Driver: jlink
|
||
SEGGER J-Link family of USB adapters. It currently supports JTAG
|
||
and SWD transports.
|
||
|
||
Compatibility Note: SEGGER released many firmware versions for
|
||
the many hardware versions they produced. OpenOCD was
|
||
extensively tested and intended to run on all of them, but
|
||
some combinations were reported as incompatible. As a general
|
||
recommendation, it is advisable to use the latest firmware
|
||
version available for each hardware version. However the
|
||
current V8 is a moving target, and SEGGER firmware versions
|
||
released after the OpenOCD was released may not be compatible.
|
||
In such cases it is recommended to revert to the last known
|
||
functional version. For 0.5.0, this is from "Feb 8 2012
|
||
14:30:39", packed with 4.42c. For 0.6.0, the last known
|
||
version is from "May 3 2012 18:36:22", packed with 4.46f.
|
||
|
||
-- Command: jlink hwstatus
|
||
Display various hardware related information, for example
|
||
target voltage and pin states.
|
||
-- Command: jlink freemem
|
||
Display free device internal memory.
|
||
-- Command: jlink jtag ['2'|'3']
|
||
Set the JTAG command version to be used. Without argument,
|
||
show the actual JTAG command version.
|
||
-- Command: jlink config
|
||
Display the device configuration.
|
||
-- Command: jlink config targetpower ['on'|'off']
|
||
Set the target power state on JTAG-pin 19. Without argument,
|
||
show the target power state.
|
||
-- Command: jlink config mac ['ff:ff:ff:ff:ff:ff']
|
||
Set the MAC address of the device. Without argument, show the
|
||
MAC address.
|
||
-- Command: jlink config ip ['A.B.C.D'('/E'|'F.G.H.I')]
|
||
Set the IP configuration of the device, where A.B.C.D is the
|
||
IP address, E the bit of the subnet mask and F.G.H.I the
|
||
subnet mask. Without arguments, show the IP configuration.
|
||
-- Command: jlink config usb ['0' to '3']
|
||
Set the USB address of the device. This will also change the
|
||
USB Product ID (PID) of the device. Without argument, show
|
||
the USB address.
|
||
-- Command: jlink config reset
|
||
Reset the current configuration.
|
||
-- Command: jlink config write
|
||
Write the current configuration to the internal persistent
|
||
storage.
|
||
-- Command: jlink emucom write <channel> <data>
|
||
Write data to an EMUCOM channel. The data needs to be encoded
|
||
as hexadecimal pairs.
|
||
|
||
The following example shows how to write the three bytes 0xaa,
|
||
0x0b and 0x23 to the EMUCOM channel 0x10:
|
||
> jlink emucom write 0x10 aa0b23
|
||
-- Command: jlink emucom read <channel> <length>
|
||
Read data from an EMUCOM channel. The read data is encoded as
|
||
hexadecimal pairs.
|
||
|
||
The following example shows how to read 4 bytes from the
|
||
EMUCOM channel 0x0:
|
||
> jlink emucom read 0x0 4
|
||
77a90000
|
||
-- Config Command: jlink usb <'0' to '3'>
|
||
Set the USB address of the interface, in case more than one
|
||
adapter is connected to the host. If not specified, USB
|
||
addresses are not considered. Device selection via USB
|
||
address is not always unambiguous. It is recommended to use
|
||
the serial number instead, if possible.
|
||
|
||
As a configuration command, it can be used only before 'init'.
|
||
|
||
-- Interface Driver: kitprog
|
||
This driver is for Cypress Semiconductor's KitProg adapters. The
|
||
KitProg is an SWD-only adapter that is designed to be used with
|
||
Cypress's PSoC and PRoC device families, but it is possible to use
|
||
it with some other devices. If you are using this adapter with a
|
||
PSoC or a PRoC, you may need to add 'kitprog_init_acquire_psoc' or
|
||
'kitprog acquire_psoc' to your configuration script.
|
||
|
||
Note that this driver is for the proprietary KitProg protocol, not
|
||
the CMSIS-DAP mode introduced in firmware 2.14. If the KitProg is
|
||
in CMSIS-DAP mode, it cannot be used with this driver, and must
|
||
either be used with the cmsis-dap driver or switched back to
|
||
KitProg mode. See the Cypress KitProg User Guide for instructions
|
||
on how to switch KitProg modes.
|
||
|
||
Known limitations:
|
||
* The frequency of SWCLK cannot be configured, and varies
|
||
between 1.6 MHz and 2.7 MHz.
|
||
* For firmware versions below 2.14, "JTAG to SWD" sequences are
|
||
replaced by "SWD line reset" in the driver. This is for two
|
||
reasons. First, the KitProg does not support sending
|
||
arbitrary SWD sequences, and only firmware 2.14 and later
|
||
implement both "JTAG to SWD" and "SWD line reset" in firmware.
|
||
Earlier firmware versions only implement "SWD line reset".
|
||
Second, due to a firmware quirk, an SWD sequence must be sent
|
||
after every target reset in order to re-establish
|
||
communications with the target.
|
||
* Due in part to the limitation above, KitProg devices with
|
||
firmware below version 2.14 will need to use
|
||
'kitprog_init_acquire_psoc' in order to communicate with PSoC
|
||
5LP devices. This is because, assuming debug is not disabled
|
||
on the PSoC, the PSoC 5LP needs its JTAG interface switched to
|
||
SWD mode before communication can begin, but prior to firmware
|
||
2.14, "JTAG to SWD" could only be sent with an acquisition
|
||
sequence.
|
||
|
||
-- Config Command: kitprog_init_acquire_psoc
|
||
Indicate that a PSoC acquisition sequence needs to be run
|
||
during adapter init. Please be aware that the acquisition
|
||
sequence hard-resets the target.
|
||
|
||
-- Command: kitprog acquire_psoc
|
||
Run a PSoC acquisition sequence immediately. Typically, this
|
||
should not be used outside of the target-specific
|
||
configuration scripts since it hard-resets the target as a
|
||
side-effect. This is necessary for "reset halt" on some PSoC
|
||
4 series devices.
|
||
|
||
-- Command: kitprog info
|
||
Display various adapter information, such as the hardware
|
||
version, firmware version, and target voltage.
|
||
|
||
-- Interface Driver: parport
|
||
Supports PC parallel port bit-banging cables: Wigglers, PLD
|
||
download cable, and more. These interfaces have several commands,
|
||
used to configure the driver before initializing the JTAG scan
|
||
chain:
|
||
|
||
-- Config Command: parport cable name
|
||
Set the layout of the parallel port cable used to connect to
|
||
the target. This is a write-once setting. Currently valid
|
||
cable NAME values include:
|
||
|
||
- altium Altium Universal JTAG cable.
|
||
- arm-jtag Same as original wiggler except SRST and TRST
|
||
connections reversed and TRST is also inverted.
|
||
- chameleon The Amontec Chameleon's CPLD when operated in
|
||
configuration mode. This is only used to program the
|
||
Chameleon itself, not a connected target.
|
||
- dlc5 The Xilinx Parallel cable III.
|
||
- flashlink The ST Parallel cable.
|
||
- lattice Lattice ispDOWNLOAD Cable
|
||
- old_amt_wiggler The Wiggler configuration that comes with
|
||
some versions of Amontec's Chameleon Programmer. The new
|
||
version available from the website uses the original
|
||
Wiggler layout ('WIGGLER')
|
||
- triton The parallel port adapter found on the "Karo
|
||
Triton 1 Development Board". This is also the layout
|
||
used by the HollyGates design (see
|
||
<http://www.lartmaker.nl/projects/jtag/>).
|
||
- wiggler The original Wiggler layout, also supported by
|
||
several clones, such as the Olimex ARM-JTAG
|
||
- wiggler2 Same as original wiggler except an led is fitted
|
||
on D5.
|
||
- wiggler_ntrst_inverted Same as original wiggler except
|
||
TRST is inverted.
|
||
|
||
-- Config Command: parport port [port_number]
|
||
Display either the address of the I/O port (default: 0x378 for
|
||
LPT1) or the number of the '/dev/parport' device. If a
|
||
parameter is provided, first switch to use that port. This is
|
||
a write-once setting.
|
||
|
||
When using PPDEV to access the parallel port, use the number
|
||
of the parallel port: 'parport port 0' (the default). If
|
||
'parport port 0x378' is specified you may encounter a problem.
|
||
|
||
-- Config Command: parport toggling_time [nanoseconds]
|
||
Displays how many nanoseconds the hardware needs to toggle
|
||
TCK; the parport driver uses this value to obey the 'adapter
|
||
speed' configuration. When the optional NANOSECONDS parameter
|
||
is given, that setting is changed before displaying the
|
||
current value.
|
||
|
||
The default setting should work reasonably well on commodity
|
||
PC hardware. However, you may want to calibrate for your
|
||
specific hardware.
|
||
Tip: To measure the toggling time with a logic analyzer
|
||
or a digital storage oscilloscope, follow the procedure
|
||
below:
|
||
> parport toggling_time 1000
|
||
> adapter speed 500
|
||
This sets the maximum JTAG clock speed of the hardware,
|
||
but the actual speed probably deviates from the requested
|
||
500 kHz. Now, measure the time between the two closest
|
||
spaced TCK transitions. You can use 'runtest 1000' or
|
||
something similar to generate a large set of samples.
|
||
Update the setting to match your measurement:
|
||
> parport toggling_time <measured nanoseconds>
|
||
Now the clock speed will be a better match for 'adapter
|
||
speed' command given in OpenOCD scripts and event
|
||
handlers.
|
||
|
||
You can do something similar with many digital
|
||
multimeters, but note that you'll probably need to run
|
||
the clock continuously for several seconds before it
|
||
decides what clock rate to show. Adjust the toggling
|
||
time up or down until the measured clock rate is a good
|
||
match with the rate you specified in the 'adapter speed'
|
||
command; be conservative.
|
||
|
||
-- Config Command: parport write_on_exit ('on'|'off')
|
||
This will configure the parallel driver to write a known
|
||
cable-specific value to the parallel interface on exiting
|
||
OpenOCD.
|
||
|
||
For example, the interface configuration file for a classic
|
||
"Wiggler" cable on LPT2 might look something like this:
|
||
|
||
adapter driver parport
|
||
parport port 0x278
|
||
parport cable wiggler
|
||
|
||
-- Interface Driver: presto
|
||
ASIX PRESTO USB JTAG programmer.
|
||
|
||
-- Interface Driver: rlink
|
||
Raisonance RLink USB adapter
|
||
|
||
-- Interface Driver: usbprog
|
||
usbprog is a freely programmable USB adapter.
|
||
|
||
-- Interface Driver: vsllink
|
||
vsllink is part of Versaloon which is a versatile USB programmer.
|
||
|
||
Note: This defines quite a few driver-specific commands, which
|
||
are not currently documented here.
|
||
|
||
-- Interface Driver: hla
|
||
This is a driver that supports multiple High Level Adapters. This
|
||
type of adapter does not expose some of the lower level api's that
|
||
OpenOCD would normally use to access the target.
|
||
|
||
Currently supported adapters include the STMicroelectronics
|
||
ST-LINK, TI ICDI and Nuvoton Nu-Link. ST-LINK firmware version >=
|
||
V2.J21.S4 recommended due to issues with earlier versions of
|
||
firmware where serial number is reset after first use. Suggest
|
||
using ST firmware update utility to upgrade ST-LINK firmware even
|
||
if current version reported is V2.J21.S4.
|
||
|
||
-- Config Command: hla_device_desc description
|
||
Currently Not Supported.
|
||
|
||
-- Config Command: hla_layout ('stlink'|'icdi'|'nulink')
|
||
Specifies the adapter layout to use.
|
||
|
||
-- Config Command: hla_vid_pid [vid pid]+
|
||
Pairs of vendor IDs and product IDs of the device.
|
||
|
||
-- Config Command: hla_stlink_backend (usb | tcp [port])
|
||
_ST-Link only:_ Choose between 'exclusive' USB communication
|
||
(the default backend) or 'shared' mode using ST-Link TCP
|
||
server (the default port is 7184).
|
||
|
||
_Note:_ ST-Link TCP server is a binary application provided by
|
||
ST available from ST-LINK server software module
|
||
(https://www.st.com/en/development-tools/st-link-server.html).
|
||
|
||
-- Command: hla_command command
|
||
Execute a custom adapter-specific command. The COMMAND string
|
||
is passed as is to the underlying adapter layout handler.
|
||
|
||
-- Interface Driver: st-link
|
||
This is a driver that supports STMicroelectronics adapters
|
||
ST-LINK/V2 (from firmware V2J24) and STLINK-V3, thanks to a new API
|
||
that provides directly access the arm ADIv5 DAP.
|
||
|
||
The new API provide access to multiple AP on the same DAP, but the
|
||
maximum number of the AP port is limited by the specific firmware
|
||
version (e.g. firmware V2J29 has 3 as maximum AP number, while
|
||
V2J32 has 8). An error is returned for any AP number above the
|
||
maximum allowed value.
|
||
|
||
_Note:_ Either these same adapters and their older versions are
|
||
also supported by *note the hla interface driver: hla_interface.
|
||
|
||
-- Config Command: st-link backend (usb | tcp [port])
|
||
Choose between 'exclusive' USB communication (the default
|
||
backend) or 'shared' mode using ST-Link TCP server (the
|
||
default port is 7184).
|
||
|
||
_Note:_ ST-Link TCP server is a binary application provided by
|
||
ST available from ST-LINK server software module
|
||
(https://www.st.com/en/development-tools/st-link-server.html).
|
||
|
||
_Note:_ ST-Link TCP server does not support the SWIM
|
||
transport.
|
||
|
||
-- Config Command: st-link vid_pid [vid pid]+
|
||
Pairs of vendor IDs and product IDs of the device.
|
||
|
||
-- Command: st-link cmd rx_n (tx_byte)+
|
||
Sends an arbitrary command composed by the sequence of bytes
|
||
TX_BYTE and receives RX_N bytes.
|
||
|
||
For example, the command to read the target's supply voltage
|
||
is one byte 0xf7 followed by 15 bytes zero. It returns 8
|
||
bytes, where the first 4 bytes represent the ADC sampling of
|
||
the reference voltage 1.2V and the last 4 bytes represent the
|
||
ADC sampling of half the target's supply voltage.
|
||
> st-link cmd 8 0xf7 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
|
||
0xf1 0x05 0x00 0x00 0x0b 0x08 0x00 0x00
|
||
The result can be converted to Volts (ignoring the most
|
||
significant bytes, always zero)
|
||
> set a [st-link cmd 8 0xf7 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0]
|
||
> echo [expr 2*1.2*([lindex $a 4]+256*[lindex $a 5])/([lindex $a 0]+256*[lindex $a 1])]
|
||
3.24891518738
|
||
|
||
-- Interface Driver: opendous
|
||
opendous-jtag is a freely programmable USB adapter.
|
||
|
||
-- Interface Driver: ulink
|
||
This is the Keil ULINK v1 JTAG debugger.
|
||
|
||
-- Interface Driver: xds110
|
||
The XDS110 is included as the embedded debug probe on many Texas
|
||
Instruments LaunchPad evaluation boards. The XDS110 is also
|
||
available as a stand-alone USB debug probe with the added
|
||
capability to supply power to the target board. The following
|
||
commands are supported by the XDS110 driver:
|
||
|
||
-- Config Command: xds110 supply voltage_in_millivolts
|
||
Available only on the XDS110 stand-alone probe. Sets the
|
||
voltage level of the XDS110 power supply. A value of 0 leaves
|
||
the supply off. Otherwise, the supply can be set to any value
|
||
in the range 1800 to 3600 millivolts.
|
||
|
||
-- Command: xds110 info
|
||
Displays information about the connected XDS110 debug probe
|
||
(e.g. firmware version).
|
||
|
||
-- Interface Driver: xlnx_pcie_xvc
|
||
This driver supports the Xilinx Virtual Cable (XVC) over PCI
|
||
Express. It is commonly found in Xilinx based PCI Express designs.
|
||
It allows debugging fabric based JTAG/SWD devices such as
|
||
Cortex-M1/M3 microcontrollers. Access to this is exposed via
|
||
extended capability registers in the PCI Express configuration
|
||
space.
|
||
|
||
For more information see Xilinx PG245 (Section on From_PCIE_to_JTAG
|
||
mode).
|
||
|
||
-- Config Command: xlnx_pcie_xvc config device
|
||
Specifies the PCI Express device via parameter DEVICE to use.
|
||
|
||
The correct value for DEVICE can be obtained by looking at the
|
||
output of lscpi -D (first column) for the corresponding
|
||
device.
|
||
|
||
The string will be of the format "DDDD:BB:SS.F" such as
|
||
"0000:65:00.1".
|
||
|
||
-- Interface Driver: bcm2835gpio
|
||
This SoC is present in Raspberry Pi which is a cheap single-board
|
||
computer exposing some GPIOs on its expansion header.
|
||
|
||
The driver accesses memory-mapped GPIO peripheral registers
|
||
directly for maximum performance, but the only possible race
|
||
condition is for the pins' modes/muxing (which is highly unlikely),
|
||
so it should be able to coexist nicely with both sysfs bitbanging
|
||
and various peripherals' kernel drivers. The driver restores the
|
||
previous configuration on exit.
|
||
|
||
GPIO numbers >= 32 can't be used for performance reasons.
|
||
|
||
See 'interface/raspberrypi-native.cfg' for a sample config and
|
||
pinout.
|
||
|
||
-- Config Command: bcm2835gpio jtag_nums TCK TMS TDI TDO
|
||
Set JTAG transport GPIO numbers for TCK, TMS, TDI, and TDO (in
|
||
that order). Must be specified to enable JTAG transport.
|
||
These pins can also be specified individually.
|
||
|
||
-- Config Command: bcm2835gpio tck_num TCK
|
||
Set TCK GPIO number. Must be specified to enable JTAG
|
||
transport. Can also be specified using the configuration
|
||
command 'bcm2835gpio jtag_nums'.
|
||
|
||
-- Config Command: bcm2835gpio tms_num TMS
|
||
Set TMS GPIO number. Must be specified to enable JTAG
|
||
transport. Can also be specified using the configuration
|
||
command 'bcm2835gpio jtag_nums'.
|
||
|
||
-- Config Command: bcm2835gpio tdo_num TDO
|
||
Set TDO GPIO number. Must be specified to enable JTAG
|
||
transport. Can also be specified using the configuration
|
||
command 'bcm2835gpio jtag_nums'.
|
||
|
||
-- Config Command: bcm2835gpio tdi_num TDI
|
||
Set TDI GPIO number. Must be specified to enable JTAG
|
||
transport. Can also be specified using the configuration
|
||
command 'bcm2835gpio jtag_nums'.
|
||
|
||
-- Config Command: bcm2835gpio swd_nums SWCLK SWDIO
|
||
Set SWD transport GPIO numbers for SWCLK and SWDIO (in that
|
||
order). Must be specified to enable SWD transport. These
|
||
pins can also be specified individually.
|
||
|
||
-- Config Command: bcm2835gpio swclk_num SWCLK
|
||
Set SWCLK GPIO number. Must be specified to enable SWD
|
||
transport. Can also be specified using the configuration
|
||
command 'bcm2835gpio swd_nums'.
|
||
|
||
-- Config Command: bcm2835gpio swdio_num SWDIO
|
||
Set SWDIO GPIO number. Must be specified to enable SWD
|
||
transport. Can also be specified using the configuration
|
||
command 'bcm2835gpio swd_nums'.
|
||
|
||
-- Config Command: bcm2835gpio swdio_dir_num SWDIO DIR
|
||
Set SWDIO direction control pin GPIO number. If specified,
|
||
this pin can be used to control the direction of an external
|
||
buffer on the SWDIO pin (set=output mode, clear=input mode).
|
||
If not specified, this feature is disabled.
|
||
|
||
-- Config Command: bcm2835gpio srst_num SRST
|
||
Set SRST GPIO number. Must be specified to enable SRST.
|
||
|
||
-- Config Command: bcm2835gpio trst_num TRST
|
||
Set TRST GPIO number. Must be specified to enable TRST.
|
||
|
||
-- Config Command: bcm2835gpio speed_coeffs SPEED_COEFF
|
||
SPEED_OFFSET
|
||
Set SPEED_COEFF and SPEED_OFFSET for delay calculations. If
|
||
unspecified, speed_coeff defaults to 113714, and speed_offset
|
||
defaults to 28.
|
||
|
||
-- Config Command: bcm2835gpio peripheral_base BASE
|
||
Set the peripheral base register address to access GPIOs. For
|
||
the RPi1, use 0x20000000. For RPi2 and RPi3, use 0x3F000000.
|
||
For RPi4, use 0xFE000000. A full list can be found in the
|
||
official guide
|
||
(https://www.raspberrypi.org/documentation/hardware/raspberrypi/peripheral_addresses.md).
|
||
|
||
-- Interface Driver: imx_gpio
|
||
i.MX SoC is present in many community boards. Wandboard is an
|
||
example of the one which is most popular.
|
||
|
||
This driver is mostly the same as bcm2835gpio.
|
||
|
||
See 'interface/imx-native.cfg' for a sample config and pinout.
|
||
|
||
-- Interface Driver: linuxgpiod
|
||
Linux provides userspace access to GPIO through libgpiod since
|
||
Linux kernel version v4.6. The driver emulates either JTAG and SWD
|
||
transport through bitbanging.
|
||
|
||
See 'interface/dln-2-gpiod.cfg' for a sample config.
|
||
|
||
-- Interface Driver: sysfsgpio
|
||
Linux legacy userspace access to GPIO through sysfs is deprecated
|
||
from Linux kernel version v5.3. Prefer using linuxgpiod, instead.
|
||
|
||
See 'interface/sysfsgpio-raspberrypi.cfg' for a sample config.
|
||
|
||
-- Interface Driver: openjtag
|
||
OpenJTAG compatible USB adapter. This defines some driver-specific
|
||
commands:
|
||
|
||
-- Config Command: openjtag variant variant
|
||
Specifies the variant of the OpenJTAG adapter (see
|
||
<http://www.openjtag.org/>). Currently valid VARIANT values
|
||
include:
|
||
|
||
- standard Standard variant (default).
|
||
- cy7c65215 Cypress CY7C65215 Dual Channel USB-Serial
|
||
Bridge Controller (see
|
||
<http://www.cypress.com/?rID=82870>).
|
||
|
||
-- Config Command: openjtag device_desc string
|
||
The USB device description string of the adapter. This value
|
||
is only used with the standard variant.
|
||
|
||
-- Interface Driver: jtag_dpi
|
||
SystemVerilog Direct Programming Interface (DPI) compatible driver
|
||
for JTAG devices in emulation. The driver acts as a client for the
|
||
SystemVerilog DPI server interface.
|
||
|
||
-- Config Command: jtag_dpi set_port port
|
||
Specifies the TCP/IP port number of the SystemVerilog DPI
|
||
server interface.
|
||
|
||
-- Config Command: jtag_dpi set_address address
|
||
Specifies the TCP/IP address of the SystemVerilog DPI server
|
||
interface.
|
||
|
||
-- Interface Driver: buspirate
|
||
|
||
This driver is for the Bus Pirate (see
|
||
<http://dangerousprototypes.com/docs/Bus_Pirate>) and compatible
|
||
devices. It uses a simple data protocol over a serial port
|
||
connection.
|
||
|
||
Most hardware development boards have a UART, a real serial port,
|
||
or a virtual USB serial device, so this driver allows you to start
|
||
building your own JTAG adapter without the complexity of a custom
|
||
USB connection.
|
||
|
||
-- Config Command: buspirate port serial_port
|
||
Specify the serial port's filename. For example:
|
||
buspirate port /dev/ttyUSB0
|
||
|
||
-- Config Command: buspirate speed (normal|fast)
|
||
Set the communication speed to 115k (normal) or 1M (fast).
|
||
For example:
|
||
buspirate speed normal
|
||
|
||
-- Config Command: buspirate mode (normal|open-drain)
|
||
Set the Bus Pirate output mode.
|
||
- In normal mode (push/pull), do not enable the pull-ups,
|
||
and do not connect I/O header pin VPU to JTAG VREF.
|
||
- In open drain mode, you will then need to enable the
|
||
pull-ups.
|
||
For example:
|
||
buspirate mode normal
|
||
|
||
-- Config Command: buspirate pullup (0|1)
|
||
Whether to connect (1) or not (0) the I/O header pin VPU (JTAG
|
||
VREF) to the pull-up/pull-down resistors on MOSI (JTAG TDI),
|
||
CLK (JTAG TCK), MISO (JTAG TDO) and CS (JTAG TMS). For
|
||
example:
|
||
buspirate pullup 0
|
||
|
||
-- Config Command: buspirate vreg (0|1)
|
||
Whether to enable (1) or disable (0) the built-in voltage
|
||
regulator, which can be used to supply power to a test circuit
|
||
through I/O header pins +3V3 and +5V. For example:
|
||
buspirate vreg 0
|
||
|
||
-- Command: buspirate led (0|1)
|
||
Turns the Bus Pirate's LED on (1) or off (0). For example:
|
||
buspirate led 1
|
||
|
||
8.3 Transport Configuration
|
||
===========================
|
||
|
||
As noted earlier, depending on the version of OpenOCD you use, and the
|
||
debug adapter you are using, several transports may be available to
|
||
communicate with debug targets (or perhaps to program flash memory).
|
||
-- Command: transport list
|
||
displays the names of the transports supported by this version of
|
||
OpenOCD.
|
||
|
||
-- Command: transport select 'transport_name'
|
||
Select which of the supported transports to use in this OpenOCD
|
||
session.
|
||
|
||
When invoked with 'transport_name', attempts to select the named
|
||
transport. The transport must be supported by the debug adapter
|
||
hardware and by the version of OpenOCD you are using (including the
|
||
adapter's driver).
|
||
|
||
If no transport has been selected and no 'transport_name' is
|
||
provided, 'transport select' auto-selects the first transport
|
||
supported by the debug adapter.
|
||
|
||
'transport select' always returns the name of the session's
|
||
selected transport, if any.
|
||
|
||
8.3.1 JTAG Transport
|
||
--------------------
|
||
|
||
JTAG is the original transport supported by OpenOCD, and most of the
|
||
OpenOCD commands support it. JTAG transports expose a chain of one or
|
||
more Test Access Points (TAPs), each of which must be explicitly
|
||
declared. JTAG supports both debugging and boundary scan testing.
|
||
Flash programming support is built on top of debug support.
|
||
|
||
JTAG transport is selected with the command 'transport select jtag'.
|
||
Unless your adapter uses either *note the hla interface driver:
|
||
hla_interface. (in which case the command is 'transport select
|
||
hla_jtag') or *note the st-link interface driver: st_link_dap_interface.
|
||
(in which case the command is 'transport select dapdirect_jtag').
|
||
|
||
8.3.2 SWD Transport
|
||
-------------------
|
||
|
||
SWD (Serial Wire Debug) is an ARM-specific transport which exposes one
|
||
Debug Access Point (DAP, which must be explicitly declared. (SWD uses
|
||
fewer signal wires than JTAG.) SWD is debug-oriented, and does not
|
||
support boundary scan testing. Flash programming support is built on
|
||
top of debug support. (Some processors support both JTAG and SWD.)
|
||
|
||
SWD transport is selected with the command 'transport select swd'.
|
||
Unless your adapter uses either *note the hla interface driver:
|
||
hla_interface. (in which case the command is 'transport select hla_swd')
|
||
or *note the st-link interface driver: st_link_dap_interface. (in which
|
||
case the command is 'transport select dapdirect_swd').
|
||
|
||
-- Config Command: swd newdap ...
|
||
Declares a single DAP which uses SWD transport. Parameters are
|
||
currently the same as "jtag newtap" but this is expected to change.
|
||
|
||
The newer SWD devices (SW-DP v2 or SWJ-DP v2) support the multi-drop
|
||
extension of SWD protocol: two or more devices can be connected to one
|
||
SWD adapter. SWD transport works in multi-drop mode if *note DAP:
|
||
dap_create. is configured with both '-dp-id' and '-instance-id'
|
||
parameters regardless how many DAPs are created.
|
||
|
||
Not all adapters and adapter drivers support SWD multi-drop. Only the
|
||
following adapter drivers are SWD multi-drop capable: cmsis_dap (use an
|
||
adapter with CMSIS-DAP version 2.0), ftdi, all bitbang based.
|
||
|
||
8.3.3 SPI Transport
|
||
-------------------
|
||
|
||
The Serial Peripheral Interface (SPI) is a general purpose transport
|
||
which uses four wire signaling. Some processors use it as part of a
|
||
solution for flash programming.
|
||
|
||
8.3.4 SWIM Transport
|
||
--------------------
|
||
|
||
The Single Wire Interface Module (SWIM) is a low-pin-count debug
|
||
protocol used by the STMicroelectronics MCU family STM8 and documented
|
||
in the User Manual UM470
|
||
(https://www.st.com/resource/en/user_manual/cd00173911.pdf).
|
||
|
||
SWIM does not support boundary scan testing nor multiple cores.
|
||
|
||
The SWIM transport is selected with the command 'transport select swim'.
|
||
|
||
The concept of TAPs does not fit in the protocol since SWIM does not
|
||
implement a scan chain. Nevertheless, the current SW model of OpenOCD
|
||
requires defining a virtual SWIM TAP through the command 'swim newtap
|
||
basename tap_type'. The TAP definition must precede the target
|
||
definition command 'target create target_name stm8 -chain-position
|
||
basename.tap_type'.
|
||
|
||
8.4 JTAG Speed
|
||
==============
|
||
|
||
JTAG clock setup is part of system setup. It _does not belong with
|
||
interface setup_ since any interface only knows a few of the constraints
|
||
for the JTAG clock speed. Sometimes the JTAG speed is changed during
|
||
the target initialization process: (1) slow at reset, (2) program the
|
||
CPU clocks, (3) run fast. Both the "slow" and "fast" clock rates are
|
||
functions of the oscillators used, the chip, the board design, and
|
||
sometimes power management software that may be active.
|
||
|
||
The speed used during reset, and the scan chain verification which
|
||
follows reset, can be adjusted using a 'reset-start' target event
|
||
handler. It can then be reconfigured to a faster speed by a
|
||
'reset-init' target event handler after it reprograms those CPU clocks,
|
||
or manually (if something else, such as a boot loader, sets up those
|
||
clocks). *Note Target Events: targetevents. When the initial low JTAG
|
||
speed is a chip characteristic, perhaps because of a required oscillator
|
||
speed, provide such a handler in the target config file. When that
|
||
speed is a function of a board-specific characteristic such as which
|
||
speed oscillator is used, it belongs in the board config file instead.
|
||
In both cases it's safest to also set the initial JTAG clock rate to
|
||
that same slow speed, so that OpenOCD never starts up using a clock
|
||
speed that's faster than the scan chain can support.
|
||
|
||
jtag_rclk 3000
|
||
$_TARGET.cpu configure -event reset-start { jtag_rclk 3000 }
|
||
|
||
If your system supports adaptive clocking (RTCK), configuring JTAG to
|
||
use that is probably the most robust approach. However, it introduces
|
||
delays to synchronize clocks; so it may not be the fastest solution.
|
||
|
||
NOTE: Script writers should consider using 'jtag_rclk' instead of
|
||
'adapter speed', but only for (ARM) cores and boards which support
|
||
adaptive clocking.
|
||
|
||
-- Command: adapter speed max_speed_kHz
|
||
A non-zero speed is in KHZ. Hence: 3000 is 3mhz. JTAG interfaces
|
||
usually support a limited number of speeds. The speed actually
|
||
used won't be faster than the speed specified.
|
||
|
||
Chip data sheets generally include a top JTAG clock rate. The
|
||
actual rate is often a function of a CPU core clock, and is
|
||
normally less than that peak rate. For example, most ARM cores
|
||
accept at most one sixth of the CPU clock.
|
||
|
||
Speed 0 (khz) selects RTCK method. *Note FAQ RTCK: faqrtck. If
|
||
your system uses RTCK, you won't need to change the JTAG clocking
|
||
after setup. Not all interfaces, boards, or targets support
|
||
"rtck". If the interface device can not support it, an error is
|
||
returned when you try to use RTCK.
|
||
|
||
-- Function: jtag_rclk fallback_speed_kHz
|
||
This Tcl proc (defined in 'startup.tcl') attempts to enable
|
||
RTCK/RCLK. If that fails (maybe the interface, board, or target
|
||
doesn't support it), falls back to the specified frequency.
|
||
# Fall back to 3mhz if RTCK is not supported
|
||
jtag_rclk 3000
|
||
|
||
|
||
File: openocd.info, Node: Reset Configuration, Next: TAP Declaration, Prev: Debug Adapter Configuration, Up: Top
|
||
|
||
9 Reset Configuration
|
||
*********************
|
||
|
||
Every system configuration may require a different reset configuration.
|
||
This can also be quite confusing. Resets also interact with RESET-INIT
|
||
event handlers, which do things like setting up clocks and DRAM, and
|
||
JTAG clock rates. (*Note JTAG Speed: jtagspeed.) They can also
|
||
interact with JTAG routers. Please see the various board files for
|
||
examples.
|
||
|
||
Note: To maintainers and integrators: Reset configuration touches
|
||
several things at once. Normally the board configuration file
|
||
should define it and assume that the JTAG adapter supports
|
||
everything that's wired up to the board's JTAG connector.
|
||
|
||
However, the target configuration file could also make note of
|
||
something the silicon vendor has done inside the chip, which will
|
||
be true for most (or all) boards using that chip. And when the
|
||
JTAG adapter doesn't support everything, the user configuration
|
||
file will need to override parts of the reset configuration
|
||
provided by other files.
|
||
|
||
9.1 Types of Reset
|
||
==================
|
||
|
||
There are many kinds of reset possible through JTAG, but they may not
|
||
all work with a given board and adapter. That's part of why reset
|
||
configuration can be error prone.
|
||
|
||
* _System Reset_ ... the _SRST_ hardware signal resets all chips
|
||
connected to the JTAG adapter, such as processors, power management
|
||
chips, and I/O controllers. Normally resets triggered with this
|
||
signal behave exactly like pressing a RESET button.
|
||
* _JTAG TAP Reset_ ... the _TRST_ hardware signal resets just the
|
||
TAP controllers connected to the JTAG adapter. Such resets should
|
||
not be visible to the rest of the system; resetting a device's TAP
|
||
controller just puts that controller into a known state.
|
||
* _Emulation Reset_ ... many devices can be reset through JTAG
|
||
commands. These resets are often distinguishable from system
|
||
resets, either explicitly (a "reset reason" register says so) or
|
||
implicitly (not all parts of the chip get reset).
|
||
* _Other Resets_ ... system-on-chip devices often support several
|
||
other types of reset. You may need to arrange that a watchdog
|
||
timer stops while debugging, preventing a watchdog reset. There
|
||
may be individual module resets.
|
||
|
||
In the best case, OpenOCD can hold SRST, then reset the TAPs via TRST
|
||
and send commands through JTAG to halt the CPU at the reset vector
|
||
before the 1st instruction is executed. Then when it finally releases
|
||
the SRST signal, the system is halted under debugger control before any
|
||
code has executed. This is the behavior required to support the 'reset
|
||
halt' and 'reset init' commands; after 'reset init' a board-specific
|
||
script might do things like setting up DRAM. (*Note Reset Command:
|
||
resetcommand.)
|
||
|
||
9.2 SRST and TRST Issues
|
||
========================
|
||
|
||
Because SRST and TRST are hardware signals, they can have a variety of
|
||
system-specific constraints. Some of the most common issues are:
|
||
|
||
* _Signal not available_ ... Some boards don't wire SRST or TRST to
|
||
the JTAG connector. Some JTAG adapters don't support such signals
|
||
even if they are wired up. Use the 'reset_config' SIGNALS options
|
||
to say when either of those signals is not connected. When SRST is
|
||
not available, your code might not be able to rely on controllers
|
||
having been fully reset during code startup. Missing TRST is not a
|
||
problem, since JTAG-level resets can be triggered using with TMS
|
||
signaling.
|
||
|
||
* _Signals shorted_ ... Sometimes a chip, board, or adapter will
|
||
connect SRST to TRST, instead of keeping them separate. Use the
|
||
'reset_config' COMBINATION options to say when those signals aren't
|
||
properly independent.
|
||
|
||
* _Timing_ ... Reset circuitry like a resistor/capacitor delay
|
||
circuit, reset supervisor, or on-chip features can extend the
|
||
effect of a JTAG adapter's reset for some time after the adapter
|
||
stops issuing the reset. For example, there may be chip or board
|
||
requirements that all reset pulses last for at least a certain
|
||
amount of time; and reset buttons commonly have hardware
|
||
debouncing. Use the 'adapter srst delay' and 'jtag_ntrst_delay'
|
||
commands to say when extra delays are needed.
|
||
|
||
* _Drive type_ ... Reset lines often have a pullup resistor, letting
|
||
the JTAG interface treat them as open-drain signals. But that's
|
||
not a requirement, so the adapter may need to use push/pull output
|
||
drivers. Also, with weak pullups it may be advisable to drive
|
||
signals to both levels (push/pull) to minimize rise times. Use the
|
||
'reset_config' TRST_TYPE and SRST_TYPE parameters to say how to
|
||
drive reset signals.
|
||
|
||
* _Special initialization_ ... Targets sometimes need special JTAG
|
||
initialization sequences to handle chip-specific issues (not
|
||
limited to errata). For example, certain JTAG commands might need
|
||
to be issued while the system as a whole is in a reset state (SRST
|
||
active) but the JTAG scan chain is usable (TRST inactive). Many
|
||
systems treat combined assertion of SRST and TRST as a trigger for
|
||
a harder reset than SRST alone. Such custom reset handling is
|
||
discussed later in this chapter.
|
||
|
||
There can also be other issues. Some devices don't fully conform to the
|
||
JTAG specifications. Trivial system-specific differences are common,
|
||
such as SRST and TRST using slightly different names. There are also
|
||
vendors who distribute key JTAG documentation for their chips only to
|
||
developers who have signed a Non-Disclosure Agreement (NDA).
|
||
|
||
Sometimes there are chip-specific extensions like a requirement to use
|
||
the normally-optional TRST signal (precluding use of JTAG adapters which
|
||
don't pass TRST through), or needing extra steps to complete a TAP
|
||
reset.
|
||
|
||
In short, SRST and especially TRST handling may be very finicky, needing
|
||
to cope with both architecture and board specific constraints.
|
||
|
||
9.3 Commands for Handling Resets
|
||
================================
|
||
|
||
-- Command: adapter srst pulse_width milliseconds
|
||
Minimum amount of time (in milliseconds) OpenOCD should wait after
|
||
asserting nSRST (active-low system reset) before allowing it to be
|
||
deasserted.
|
||
|
||
-- Command: adapter srst delay milliseconds
|
||
How long (in milliseconds) OpenOCD should wait after deasserting
|
||
nSRST (active-low system reset) before starting new JTAG
|
||
operations. When a board has a reset button connected to SRST line
|
||
it will probably have hardware debouncing, implying you should use
|
||
this.
|
||
|
||
-- Command: jtag_ntrst_assert_width milliseconds
|
||
Minimum amount of time (in milliseconds) OpenOCD should wait after
|
||
asserting nTRST (active-low JTAG TAP reset) before allowing it to
|
||
be deasserted.
|
||
|
||
-- Command: jtag_ntrst_delay milliseconds
|
||
How long (in milliseconds) OpenOCD should wait after deasserting
|
||
nTRST (active-low JTAG TAP reset) before starting new JTAG
|
||
operations.
|
||
|
||
-- Command: reset_config mode_flag ...
|
||
This command displays or modifies the reset configuration of your
|
||
combination of JTAG board and target in target configuration
|
||
scripts.
|
||
|
||
Information earlier in this section describes the kind of problems
|
||
the command is intended to address (*note SRST and TRST Issues:
|
||
srstandtrstissues.). As a rule this command belongs only in board
|
||
config files, describing issues like _board doesn't connect TRST_;
|
||
or in user config files, addressing limitations derived from a
|
||
particular combination of interface and board. (An unlikely
|
||
example would be using a TRST-only adapter with a board that only
|
||
wires up SRST.)
|
||
|
||
The MODE_FLAG options can be specified in any order, but only one
|
||
of each type - SIGNALS, COMBINATION, GATES, TRST_TYPE, SRST_TYPE
|
||
and CONNECT_TYPE - may be specified at a time. If you don't
|
||
provide a new value for a given type, its previous value (perhaps
|
||
the default) is unchanged. For example, this means that you don't
|
||
need to say anything at all about TRST just to declare that if the
|
||
JTAG adapter should want to drive SRST, it must explicitly be
|
||
driven high ('srst_push_pull').
|
||
|
||
* SIGNALS can specify which of the reset signals are connected.
|
||
For example, If the JTAG interface provides SRST, but the
|
||
board doesn't connect that signal properly, then OpenOCD can't
|
||
use it. Possible values are 'none' (the default),
|
||
'trst_only', 'srst_only' and 'trst_and_srst'.
|
||
|
||
Tip: If your board provides SRST and/or TRST through the
|
||
JTAG connector, you must declare that so those signals
|
||
can be used.
|
||
|
||
* The COMBINATION is an optional value specifying broken reset
|
||
signal implementations. The default behaviour if no option
|
||
given is 'separate', indicating everything behaves normally.
|
||
'srst_pulls_trst' states that the test logic is reset together
|
||
with the reset of the system (e.g. NXP LPC2000, "broken"
|
||
board layout), 'trst_pulls_srst' says that the system is reset
|
||
together with the test logic (only hypothetical, I haven't
|
||
seen hardware with such a bug, and can be worked around).
|
||
'combined' implies both 'srst_pulls_trst' and
|
||
'trst_pulls_srst'.
|
||
|
||
* The GATES tokens control flags that describe some cases where
|
||
JTAG may be unavailable during reset. 'srst_gates_jtag'
|
||
(default) indicates that asserting SRST gates the JTAG clock.
|
||
This means that no communication can happen on JTAG while SRST
|
||
is asserted. Its converse is 'srst_nogate', indicating that
|
||
JTAG commands can safely be issued while SRST is active.
|
||
|
||
* The CONNECT_TYPE tokens control flags that describe some cases
|
||
where SRST is asserted while connecting to the target.
|
||
'srst_nogate' is required to use this option.
|
||
'connect_deassert_srst' (default) indicates that SRST will not
|
||
be asserted while connecting to the target. Its converse is
|
||
'connect_assert_srst', indicating that SRST will be asserted
|
||
before any target connection. Only some targets support this
|
||
feature, STM32 and STR9 are examples. This feature is useful
|
||
if you are unable to connect to your target due to incorrect
|
||
options byte config or illegal program execution.
|
||
|
||
The optional TRST_TYPE and SRST_TYPE parameters allow the driver
|
||
mode of each reset line to be specified. These values only affect
|
||
JTAG interfaces with support for different driver modes, like the
|
||
Amontec JTAGkey and JTAG Accelerator. Also, they are necessarily
|
||
ignored if the relevant signal (TRST or SRST) is not connected.
|
||
|
||
* Possible TRST_TYPE driver modes for the test reset signal
|
||
(TRST) are the default 'trst_push_pull', and
|
||
'trst_open_drain'. Most boards connect this signal to a
|
||
pulldown, so the JTAG TAPs never leave reset unless they are
|
||
hooked up to a JTAG adapter.
|
||
|
||
* Possible SRST_TYPE driver modes for the system reset signal
|
||
(SRST) are the default 'srst_open_drain', and
|
||
'srst_push_pull'. Most boards connect this signal to a
|
||
pullup, and allow the signal to be pulled low by various
|
||
events including system power-up and pressing a reset button.
|
||
|
||
9.4 Custom Reset Handling
|
||
=========================
|
||
|
||
OpenOCD has several ways to help support the various reset mechanisms
|
||
provided by chip and board vendors. The commands shown in the previous
|
||
section give standard parameters. There are also _event handlers_
|
||
associated with TAPs or Targets. Those handlers are Tcl procedures you
|
||
can provide, which are invoked at particular points in the reset
|
||
sequence.
|
||
|
||
_When SRST is not an option_ you must set up a 'reset-assert' event
|
||
handler for your target. For example, some JTAG adapters don't include
|
||
the SRST signal; and some boards have multiple targets, and you won't
|
||
always want to reset everything at once.
|
||
|
||
After configuring those mechanisms, you might still find your board
|
||
doesn't start up or reset correctly. For example, maybe it needs a
|
||
slightly different sequence of SRST and/or TRST manipulations, because
|
||
of quirks that the 'reset_config' mechanism doesn't address; or
|
||
asserting both might trigger a stronger reset, which needs special
|
||
attention.
|
||
|
||
Experiment with lower level operations, such as 'adapter assert',
|
||
'adapter deassert' and the 'jtag arp_*' operations shown here, to find a
|
||
sequence of operations that works. *Note JTAG Commands::. When you
|
||
find a working sequence, it can be used to override 'jtag_init', which
|
||
fires during OpenOCD startup (*note Configuration Stage:
|
||
configurationstage.); or 'init_reset', which fires during reset
|
||
processing.
|
||
|
||
You might also want to provide some project-specific reset schemes. For
|
||
example, on a multi-target board the standard 'reset' command would
|
||
reset all targets, but you may need the ability to reset only one target
|
||
at time and thus want to avoid using the board-wide SRST signal.
|
||
|
||
-- Overridable Procedure: init_reset mode
|
||
This is invoked near the beginning of the 'reset' command, usually
|
||
to provide as much of a cold (power-up) reset as practical. By
|
||
default it is also invoked from 'jtag_init' if the scan chain does
|
||
not respond to pure JTAG operations. The MODE parameter is the
|
||
parameter given to the low level reset command ('halt', 'init', or
|
||
'run'), 'setup', or potentially some other value.
|
||
|
||
The default implementation just invokes 'jtag arp_init-reset'.
|
||
Replacements will normally build on low level JTAG operations such
|
||
as 'adapter assert' and 'adapter deassert'. Operations here must
|
||
not address individual TAPs (or their associated targets) until the
|
||
JTAG scan chain has first been verified to work.
|
||
|
||
Implementations must have verified the JTAG scan chain before they
|
||
return. This is done by calling 'jtag arp_init' (or 'jtag
|
||
arp_init-reset').
|
||
|
||
-- Command: jtag arp_init
|
||
This validates the scan chain using just the four standard JTAG
|
||
signals (TMS, TCK, TDI, TDO). It starts by issuing a JTAG-only
|
||
reset. Then it performs checks to verify that the scan chain
|
||
configuration matches the TAPs it can observe. Those checks
|
||
include checking IDCODE values for each active TAP, and verifying
|
||
the length of their instruction registers using TAP '-ircapture'
|
||
and '-irmask' values. If these tests all pass, TAP 'setup' events
|
||
are issued to all TAPs with handlers for that event.
|
||
|
||
-- Command: jtag arp_init-reset
|
||
This uses TRST and SRST to try resetting everything on the JTAG
|
||
scan chain (and anything else connected to SRST). It then invokes
|
||
the logic of 'jtag arp_init'.
|
||
|
||
|
||
File: openocd.info, Node: TAP Declaration, Next: CPU Configuration, Prev: Reset Configuration, Up: Top
|
||
|
||
10 TAP Declaration
|
||
******************
|
||
|
||
_Test Access Ports_ (TAPs) are the core of JTAG. TAPs serve many roles,
|
||
including:
|
||
|
||
* Debug Target A CPU TAP can be used as a GDB debug target.
|
||
* Flash Programming Some chips program the flash directly via JTAG.
|
||
Others do it indirectly, making a CPU do it.
|
||
* Program Download Using the same CPU support GDB uses, you can
|
||
initialize a DRAM controller, download code to DRAM, and then start
|
||
running that code.
|
||
* Boundary Scan Most chips support boundary scan, which helps test
|
||
for board assembly problems like solder bridges and missing
|
||
connections.
|
||
|
||
OpenOCD must know about the active TAPs on your board(s). Setting up
|
||
the TAPs is the core task of your configuration files. Once those TAPs
|
||
are set up, you can pass their names to code which sets up CPUs and
|
||
exports them as GDB targets, probes flash memory, performs low-level
|
||
JTAG operations, and more.
|
||
|
||
10.1 Scan Chains
|
||
================
|
||
|
||
TAPs are part of a hardware "scan chain", which is a daisy chain of
|
||
TAPs. They also need to be added to OpenOCD's software mirror of that
|
||
hardware list, giving each member a name and associating other data with
|
||
it. Simple scan chains, with a single TAP, are common in systems with a
|
||
single microcontroller or microprocessor. More complex chips may have
|
||
several TAPs internally. Very complex scan chains might have a dozen or
|
||
more TAPs: several in one chip, more in the next, and connecting to
|
||
other boards with their own chips and TAPs.
|
||
|
||
You can display the list with the 'scan_chain' command. (Don't confuse
|
||
this with the list displayed by the 'targets' command, presented in the
|
||
next chapter. That only displays TAPs for CPUs which are configured as
|
||
debugging targets.) Here's what the scan chain might look like for a
|
||
chip more than one TAP:
|
||
|
||
TapName Enabled IdCode Expected IrLen IrCap IrMask
|
||
-- ------------------ ------- ---------- ---------- ----- ----- ------
|
||
0 omap5912.dsp Y 0x03df1d81 0x03df1d81 38 0x01 0x03
|
||
1 omap5912.arm Y 0x0692602f 0x0692602f 4 0x01 0x0f
|
||
2 omap5912.unknown Y 0x00000000 0x00000000 8 0x01 0x03
|
||
|
||
OpenOCD can detect some of that information, but not all of it. *Note
|
||
Autoprobing: autoprobing. Unfortunately, those TAPs can't always be
|
||
autoconfigured, because not all devices provide good support for that.
|
||
JTAG doesn't require supporting IDCODE instructions, and chips with JTAG
|
||
routers may not link TAPs into the chain until they are told to do so.
|
||
|
||
The configuration mechanism currently supported by OpenOCD requires
|
||
explicit configuration of all TAP devices using 'jtag newtap' commands,
|
||
as detailed later in this chapter. A command like this would declare
|
||
one tap and name it 'chip1.cpu':
|
||
|
||
jtag newtap chip1 cpu -irlen 4 -expected-id 0x3ba00477
|
||
|
||
Each target configuration file lists the TAPs provided by a given chip.
|
||
Board configuration files combine all the targets on a board, and so
|
||
forth. Note that _the order in which TAPs are declared is very
|
||
important._ That declaration order must match the order in the JTAG
|
||
scan chain, both inside a single chip and between them. *Note FAQ TAP
|
||
Order: faqtaporder.
|
||
|
||
For example, the STMicroelectronics STR912 chip has three separate
|
||
TAPs(1). To configure those taps, 'target/str912.cfg' includes commands
|
||
something like this:
|
||
|
||
jtag newtap str912 flash ... params ...
|
||
jtag newtap str912 cpu ... params ...
|
||
jtag newtap str912 bs ... params ...
|
||
|
||
Actual config files typically use a variable such as '$_CHIPNAME'
|
||
instead of literals like 'str912', to support more than one chip of each
|
||
type. *Note Config File Guidelines::.
|
||
|
||
-- Command: jtag names
|
||
Returns the names of all current TAPs in the scan chain. Use 'jtag
|
||
cget' or 'jtag tapisenabled' to examine attributes and state of
|
||
each TAP.
|
||
foreach t [jtag names] {
|
||
puts [format "TAP: %s\n" $t]
|
||
}
|
||
|
||
-- Command: scan_chain
|
||
Displays the TAPs in the scan chain configuration, and their
|
||
status. The set of TAPs listed by this command is fixed by exiting
|
||
the OpenOCD configuration stage, but systems with a JTAG router can
|
||
enable or disable TAPs dynamically.
|
||
|
||
10.2 TAP Names
|
||
==============
|
||
|
||
When TAP objects are declared with 'jtag newtap', a "dotted.name" is
|
||
created for the TAP, combining the name of a module (usually a chip) and
|
||
a label for the TAP. For example: 'xilinx.tap', 'str912.flash',
|
||
'omap3530.jrc', 'dm6446.dsp', or 'stm32.cpu'. Many other commands use
|
||
that dotted.name to manipulate or refer to the TAP. For example, CPU
|
||
configuration uses the name, as does declaration of NAND or NOR flash
|
||
banks.
|
||
|
||
The components of a dotted name should follow "C" symbol name rules:
|
||
start with an alphabetic character, then numbers and underscores are OK;
|
||
while others (including dots!) are not.
|
||
|
||
10.3 TAP Declaration Commands
|
||
=============================
|
||
|
||
-- Config Command: jtag newtap chipname tapname configparams...
|
||
Declares a new TAP with the dotted name CHIPNAME.TAPNAME, and
|
||
configured according to the various CONFIGPARAMS.
|
||
|
||
The CHIPNAME is a symbolic name for the chip. Conventionally
|
||
target config files use '$_CHIPNAME', defaulting to the model name
|
||
given by the chip vendor but overridable.
|
||
|
||
The TAPNAME reflects the role of that TAP, and should follow this
|
||
convention:
|
||
|
||
* 'bs' - For boundary scan if this is a separate TAP;
|
||
* 'cpu' - The main CPU of the chip, alternatively 'arm' and
|
||
'dsp' on chips with both ARM and DSP CPUs, 'arm1' and 'arm2'
|
||
on chips with two ARMs, and so forth;
|
||
* 'etb' - For an embedded trace buffer (example: an ARM ETB11);
|
||
* 'flash' - If the chip has a flash TAP, like the str912;
|
||
* 'jrc' - For JTAG route controller (example: the ICEPick
|
||
modules on many Texas Instruments chips, like the OMAP3530 on
|
||
Beagleboards);
|
||
* 'tap' - Should be used only for FPGA- or CPLD-like devices
|
||
with a single TAP;
|
||
* 'unknownN' - If you have no idea what the TAP is for (N is a
|
||
number);
|
||
* _when in doubt_ - Use the chip maker's name in their data
|
||
sheet. For example, the Freescale i.MX31 has a SDMA (Smart
|
||
DMA) with a JTAG TAP; that TAP should be named 'sdma'.
|
||
|
||
Every TAP requires at least the following CONFIGPARAMS:
|
||
|
||
* '-irlen' NUMBER
|
||
The length in bits of the instruction register, such as 4 or 5
|
||
bits.
|
||
|
||
A TAP may also provide optional CONFIGPARAMS:
|
||
|
||
* '-disable' (or '-enable')
|
||
Use the '-disable' parameter to flag a TAP which is not linked
|
||
into the scan chain after a reset using either TRST or the
|
||
JTAG state machine's RESET state. You may use '-enable' to
|
||
highlight the default state (the TAP is linked in). *Note
|
||
Enabling and Disabling TAPs: enablinganddisablingtaps.
|
||
* '-expected-id' NUMBER
|
||
A non-zero NUMBER represents a 32-bit IDCODE which you expect
|
||
to find when the scan chain is examined. These codes are not
|
||
required by all JTAG devices. _Repeat the option_ as many
|
||
times as required if more than one ID code could appear (for
|
||
example, multiple versions). Specify NUMBER as zero to
|
||
suppress warnings about IDCODE values that were found but not
|
||
included in the list.
|
||
|
||
Provide this value if at all possible, since it lets OpenOCD
|
||
tell when the scan chain it sees isn't right. These values
|
||
are provided in vendors' chip documentation, usually a
|
||
technical reference manual. Sometimes you may need to probe
|
||
the JTAG hardware to find these values. *Note Autoprobing:
|
||
autoprobing.
|
||
* '-ignore-version'
|
||
Specify this to ignore the JTAG version field in the
|
||
'-expected-id' option. When vendors put out multiple versions
|
||
of a chip, or use the same JTAG-level ID for several
|
||
largely-compatible chips, it may be more practical to ignore
|
||
the version field than to update config files to handle all of
|
||
the various chip IDs. The version field is defined as bit
|
||
28-31 of the IDCODE.
|
||
* '-ircapture' NUMBER
|
||
The bit pattern loaded by the TAP into the JTAG shift register
|
||
on entry to the IRCAPTURE state, such as 0x01. JTAG requires
|
||
the two LSBs of this value to be 01. By default, '-ircapture'
|
||
and '-irmask' are set up to verify that two-bit value. You
|
||
may provide additional bits if you know them, or indicate that
|
||
a TAP doesn't conform to the JTAG specification.
|
||
* '-irmask' NUMBER
|
||
A mask used with '-ircapture' to verify that instruction scans
|
||
work correctly. Such scans are not used by OpenOCD except to
|
||
verify that there seems to be no problems with JTAG scan chain
|
||
operations.
|
||
* '-ignore-syspwrupack'
|
||
Specify this to ignore the CSYSPWRUPACK bit in the ARM DAP DP
|
||
CTRL/STAT register during initial examination and when
|
||
checking the sticky error bit. This bit is normally checked
|
||
after setting the CSYSPWRUPREQ bit, but some devices do not
|
||
set the ack bit until sometime later.
|
||
|
||
10.4 Other TAP commands
|
||
=======================
|
||
|
||
-- Command: jtag cget dotted.name '-idcode'
|
||
Get the value of the IDCODE found in hardware.
|
||
|
||
-- Command: jtag cget dotted.name '-event' event_name
|
||
-- Command: jtag configure dotted.name '-event' event_name handler
|
||
At this writing this TAP attribute mechanism is limited and used
|
||
mostly for event handling. (It is not a direct analogue of the
|
||
'cget'/'configure' mechanism for debugger targets.) See the next
|
||
section for information about the available events.
|
||
|
||
The 'configure' subcommand assigns an event handler, a TCL string
|
||
which is evaluated when the event is triggered. The 'cget'
|
||
subcommand returns that handler.
|
||
|
||
10.5 TAP Events
|
||
===============
|
||
|
||
OpenOCD includes two event mechanisms. The one presented here applies
|
||
to all JTAG TAPs. The other applies to debugger targets, which are
|
||
associated with certain TAPs.
|
||
|
||
The TAP events currently defined are:
|
||
|
||
* post-reset
|
||
The TAP has just completed a JTAG reset. The tap may still be in
|
||
the JTAG RESET state. Handlers for these events might perform
|
||
initialization sequences such as issuing TCK cycles, TMS sequences
|
||
to ensure exit from the ARM SWD mode, and more.
|
||
|
||
Because the scan chain has not yet been verified, handlers for
|
||
these events _should not issue commands which scan the JTAG IR or
|
||
DR registers_ of any particular target. NOTE: As this is written
|
||
(September 2009), nothing prevents such access.
|
||
* setup
|
||
The scan chain has been reset and verified. This handler may
|
||
enable TAPs as needed.
|
||
* tap-disable
|
||
The TAP needs to be disabled. This handler should implement 'jtag
|
||
tapdisable' by issuing the relevant JTAG commands.
|
||
* tap-enable
|
||
The TAP needs to be enabled. This handler should implement 'jtag
|
||
tapenable' by issuing the relevant JTAG commands.
|
||
|
||
If you need some action after each JTAG reset which isn't actually
|
||
specific to any TAP (since you can't yet trust the scan chain's contents
|
||
to be accurate), you might:
|
||
|
||
jtag configure CHIP.jrc -event post-reset {
|
||
echo "JTAG Reset done"
|
||
... non-scan jtag operations to be done after reset
|
||
}
|
||
|
||
10.6 Enabling and Disabling TAPs
|
||
================================
|
||
|
||
In some systems, a "JTAG Route Controller" (JRC) is used to enable
|
||
and/or disable specific JTAG TAPs. Many ARM-based chips from Texas
|
||
Instruments include an "ICEPick" module, which is a JRC. Such chips
|
||
include DaVinci and OMAP3 processors.
|
||
|
||
A given TAP may not be visible until the JRC has been told to link it
|
||
into the scan chain; and if the JRC has been told to unlink that TAP, it
|
||
will no longer be visible. Such routers address problems that JTAG
|
||
"bypass mode" ignores, such as:
|
||
|
||
* The scan chain can only go as fast as its slowest TAP.
|
||
* Having many TAPs slows instruction scans, since all TAPs receive
|
||
new instructions.
|
||
* TAPs in the scan chain must be powered up, which wastes power and
|
||
prevents debugging some power management mechanisms.
|
||
|
||
The IEEE 1149.1 JTAG standard has no concept of a "disabled" tap, as
|
||
implied by the existence of JTAG routers. However, the upcoming IEEE
|
||
1149.7 framework (layered on top of JTAG) does include a kind of JTAG
|
||
router functionality.
|
||
|
||
In OpenOCD, tap enabling/disabling is invoked by the Tcl commands shown
|
||
below, and is implemented using TAP event handlers. So for example,
|
||
when defining a TAP for a CPU connected to a JTAG router, your
|
||
'target.cfg' file should define TAP event handlers using code that looks
|
||
something like this:
|
||
|
||
jtag configure CHIP.cpu -event tap-enable {
|
||
... jtag operations using CHIP.jrc
|
||
}
|
||
jtag configure CHIP.cpu -event tap-disable {
|
||
... jtag operations using CHIP.jrc
|
||
}
|
||
|
||
Then you might want that CPU's TAP enabled almost all the time:
|
||
|
||
jtag configure $CHIP.jrc -event setup "jtag tapenable $CHIP.cpu"
|
||
|
||
Note how that particular setup event handler declaration uses quotes to
|
||
evaluate '$CHIP' when the event is configured. Using brackets { } would
|
||
cause it to be evaluated later, at runtime, when it might have a
|
||
different value.
|
||
|
||
-- Command: jtag tapdisable dotted.name
|
||
If necessary, disables the tap by sending it a 'tap-disable' event.
|
||
Returns the string "1" if the tap specified by DOTTED.NAME is
|
||
enabled, and "0" if it is disabled.
|
||
|
||
-- Command: jtag tapenable dotted.name
|
||
If necessary, enables the tap by sending it a 'tap-enable' event.
|
||
Returns the string "1" if the tap specified by DOTTED.NAME is
|
||
enabled, and "0" if it is disabled.
|
||
|
||
-- Command: jtag tapisenabled dotted.name
|
||
Returns the string "1" if the tap specified by DOTTED.NAME is
|
||
enabled, and "0" if it is disabled.
|
||
|
||
Note: Humans will find the 'scan_chain' command more helpful
|
||
for querying the state of the JTAG taps.
|
||
|
||
10.7 Autoprobing
|
||
================
|
||
|
||
TAP configuration is the first thing that needs to be done after
|
||
interface and reset configuration. Sometimes it's hard finding out what
|
||
TAPs exist, or how they are identified. Vendor documentation is not
|
||
always easy to find and use.
|
||
|
||
To help you get past such problems, OpenOCD has a limited _autoprobing_
|
||
ability to look at the scan chain, doing a "blind interrogation" and
|
||
then reporting the TAPs it finds. To use this mechanism, start the
|
||
OpenOCD server with only data that configures your JTAG interface, and
|
||
arranges to come up with a slow clock (many devices don't support fast
|
||
JTAG clocks right when they come out of reset).
|
||
|
||
For example, your 'openocd.cfg' file might have:
|
||
|
||
source [find interface/olimex-arm-usb-tiny-h.cfg]
|
||
reset_config trst_and_srst
|
||
jtag_rclk 8
|
||
|
||
When you start the server without any TAPs configured, it will attempt
|
||
to autoconfigure the TAPs. There are two parts to this:
|
||
|
||
1. _TAP discovery_ ... After a JTAG reset (sometimes a system reset
|
||
may be needed too), each TAP's data registers will hold the
|
||
contents of either the IDCODE or BYPASS register. If JTAG
|
||
communication is working, OpenOCD will see each TAP, and report
|
||
what '-expected-id' to use with it.
|
||
2. _IR Length discovery_ ... Unfortunately JTAG does not provide a
|
||
reliable way to find out the value of the '-irlen' parameter to use
|
||
with a TAP that is discovered. If OpenOCD can discover the length
|
||
of a TAP's instruction register, it will report it. Otherwise you
|
||
may need to consult vendor documentation, such as chip data sheets
|
||
or BSDL files.
|
||
|
||
In many cases your board will have a simple scan chain with just a
|
||
single device. Here's what OpenOCD reported with one board that's a bit
|
||
more complex:
|
||
|
||
clock speed 8 kHz
|
||
There are no enabled taps. AUTO PROBING MIGHT NOT WORK!!
|
||
AUTO auto0.tap - use "jtag newtap auto0 tap -expected-id 0x2b900f0f ..."
|
||
AUTO auto1.tap - use "jtag newtap auto1 tap -expected-id 0x07926001 ..."
|
||
AUTO auto2.tap - use "jtag newtap auto2 tap -expected-id 0x0b73b02f ..."
|
||
AUTO auto0.tap - use "... -irlen 4"
|
||
AUTO auto1.tap - use "... -irlen 4"
|
||
AUTO auto2.tap - use "... -irlen 6"
|
||
no gdb ports allocated as no target has been specified
|
||
|
||
Given that information, you should be able to either find some existing
|
||
config files to use, or create your own. If you create your own, you
|
||
would configure from the bottom up: first a 'target.cfg' file with these
|
||
TAPs, any targets associated with them, and any on-chip resources; then
|
||
a 'board.cfg' with off-chip resources, clocking, and so forth.
|
||
|
||
10.8 DAP declaration (ARMv6-M, ARMv7 and ARMv8 targets)
|
||
=======================================================
|
||
|
||
Since OpenOCD version 0.11.0, the Debug Access Port (DAP) is no longer
|
||
implicitly created together with the target. It must be explicitly
|
||
declared using the 'dap create' command. For all ARMv6-M, ARMv7 and
|
||
ARMv8 targets, the option "'-dap' DAP_NAME" has to be used instead of
|
||
"'-chain-position' DOTTED.NAME" when the target is created.
|
||
|
||
The 'dap' command group supports the following sub-commands:
|
||
|
||
-- Command: dap create dap_name '-chain-position' dotted.name
|
||
configparams...
|
||
Declare a DAP instance named DAP_NAME linked to the JTAG tap
|
||
DOTTED.NAME. This also creates a new command ('dap_name') which is
|
||
used for various purposes including additional configuration.
|
||
There can only be one DAP for each JTAG tap in the system.
|
||
|
||
A DAP may also provide optional CONFIGPARAMS:
|
||
|
||
* '-ignore-syspwrupack'
|
||
Specify this to ignore the CSYSPWRUPACK bit in the ARM DAP DP
|
||
CTRL/STAT register during initial examination and when
|
||
checking the sticky error bit. This bit is normally checked
|
||
after setting the CSYSPWRUPREQ bit, but some devices do not
|
||
set the ack bit until sometime later.
|
||
|
||
* '-dp-id' NUMBER
|
||
Debug port identification number for SWD DPv2 multidrop. The
|
||
NUMBER is written to bits 0..27 of DP TARGETSEL during DP
|
||
selection. To find the id number of a single connected device
|
||
read DP TARGETID: 'device.dap dpreg 0x24' Use bits 0..27 of
|
||
TARGETID.
|
||
|
||
* '-instance-id' NUMBER
|
||
Instance identification number for SWD DPv2 multidrop. The
|
||
NUMBER is written to bits 28..31 of DP TARGETSEL during DP
|
||
selection. To find the instance number of a single connected
|
||
device read DP DLPIDR: 'device.dap dpreg 0x34' The instance
|
||
number is in bits 28..31 of DLPIDR value.
|
||
|
||
-- Command: dap names
|
||
This command returns a list of all registered DAP objects. It it
|
||
useful mainly for TCL scripting.
|
||
|
||
-- Command: dap info [num]
|
||
Displays the ROM table for MEM-AP NUM, defaulting to the currently
|
||
selected AP of the currently selected target.
|
||
|
||
-- Command: dap init
|
||
Initialize all registered DAPs. This command is used internally
|
||
during initialization. It can be issued at any time after the
|
||
initialization, too.
|
||
|
||
The following commands exist as subcommands of DAP instances:
|
||
|
||
-- Command: $dap_name info [num]
|
||
Displays the ROM table for MEM-AP NUM, defaulting to the currently
|
||
selected AP.
|
||
|
||
-- Command: $dap_name apid [num]
|
||
Displays ID register from AP NUM, defaulting to the currently
|
||
selected AP.
|
||
|
||
-- Command: $dap_name apreg ap_num reg [value]
|
||
Displays content of a register REG from AP AP_NUM or set a new
|
||
value VALUE. REG is byte address of a word register, 0, 4, 8 ...
|
||
0xfc.
|
||
|
||
-- Command: $dap_name apsel [num]
|
||
Select AP NUM, defaulting to 0.
|
||
|
||
-- Command: $dap_name dpreg reg [value]
|
||
Displays the content of DP register at address REG, or set it to a
|
||
new value VALUE.
|
||
|
||
In case of SWD, REG is a value in packed format dpbanksel << 4 |
|
||
addr and assumes values 0, 4, 8 ... 0xfc. In case of JTAG it only
|
||
assumes values 0, 4, 8 and 0xc.
|
||
|
||
_Note:_ Consider using 'poll off' to avoid any disturbing
|
||
background activity by OpenOCD while you are operating at such
|
||
low-level.
|
||
|
||
-- Command: $dap_name baseaddr [num]
|
||
Displays debug base address from MEM-AP NUM, defaulting to the
|
||
currently selected AP.
|
||
|
||
-- Command: $dap_name memaccess [value]
|
||
Displays the number of extra tck cycles in the JTAG idle to use for
|
||
MEM-AP memory bus access [0-255], giving additional time to respond
|
||
to reads. If VALUE is defined, first assigns that.
|
||
|
||
-- Command: $dap_name apcsw [value [mask]]
|
||
Displays or changes CSW bit pattern for MEM-AP transfers.
|
||
|
||
At the begin of each memory access the CSW pattern is extended
|
||
(bitwise or-ed) by "Size" and "AddrInc" bit-fields according to
|
||
transfer requirements and the result is written to the real CSW
|
||
register. All bits except dynamically updated fields "Size" and
|
||
"AddrInc" can be changed by changing the CSW pattern. Refer to ARM
|
||
ADI v5 manual chapter 7.6.4 and appendix A for details.
|
||
|
||
Use VALUE only syntax if you want to set the new CSW pattern as a
|
||
whole. The example sets HPROT1 bit (required by Cortex-M) and
|
||
clears the rest of the pattern:
|
||
kx.dap apcsw 0x2000000
|
||
|
||
If MASK is also used, the CSW pattern is changed only on bit
|
||
positions where the mask bit is 1. The following example sets
|
||
HPROT3 (cacheable) and leaves the rest of the pattern intact. It
|
||
configures memory access through DCache on Cortex-M7.
|
||
set CSW_HPROT3_CACHEABLE [expr 1 << 27]
|
||
samv.dap apcsw $CSW_HPROT3_CACHEABLE $CSW_HPROT3_CACHEABLE
|
||
|
||
Another example clears SPROT bit and leaves the rest of pattern
|
||
intact:
|
||
set CSW_SPROT [expr 1 << 30]
|
||
samv.dap apcsw 0 $CSW_SPROT
|
||
|
||
_Note:_ If you want to check the real value of CSW, not CSW
|
||
pattern, use 'xxx.dap apreg 0'. *Note DAP subcommand apreg::.
|
||
|
||
_Warning:_ Some of the CSW bits are vital for working memory
|
||
transfer. If you set a wrong CSW pattern and MEM-AP stopped
|
||
working, use the following example with a proper dap name:
|
||
xxx.dap apcsw default
|
||
|
||
-- Config Command: $dap_name ti_be_32_quirks ['enable']
|
||
Set/get quirks mode for TI TMS450/TMS570 processors Disabled by
|
||
default
|
||
|
||
---------- Footnotes ----------
|
||
|
||
(1) See the ST document titled: _STR91xFAxxx, Section 3.15 Jtag
|
||
Interface, Page: 28/102, Figure 3: JTAG chaining inside the STR91xFA_.
|
||
<http://eu.st.com/stonline/products/literature/ds/13495.pdf>
|
||
|
||
|
||
File: openocd.info, Node: CPU Configuration, Next: Flash Commands, Prev: TAP Declaration, Up: Top
|
||
|
||
11 CPU Configuration
|
||
********************
|
||
|
||
This chapter discusses how to set up GDB debug targets for CPUs. You
|
||
can also access these targets without GDB (*note Architecture and Core
|
||
Commands::, and *note Target State handling: targetstatehandling.) and
|
||
through various kinds of NAND and NOR flash commands. If you have
|
||
multiple CPUs you can have multiple such targets.
|
||
|
||
We'll start by looking at how to examine the targets you have, then look
|
||
at how to add one more target and how to configure it.
|
||
|
||
11.1 Target List
|
||
================
|
||
|
||
All targets that have been set up are part of a list, where each member
|
||
has a name. That name should normally be the same as the TAP name. You
|
||
can display the list with the 'targets' (plural!) command. This
|
||
display often has only one CPU; here's what it might look like with more
|
||
than one:
|
||
TargetName Type Endian TapName State
|
||
-- ------------------ ---------- ------ ------------------ ------------
|
||
0* at91rm9200.cpu arm920t little at91rm9200.cpu running
|
||
1 MyTarget cortex_m little mychip.foo tap-disabled
|
||
|
||
One member of that list is the "current target", which is implicitly
|
||
referenced by many commands. It's the one marked with a '*' near the
|
||
target name. In particular, memory addresses often refer to the address
|
||
space seen by that current target. Commands like 'mdw' (memory display
|
||
words) and 'flash erase_address' (erase NOR flash blocks) are examples;
|
||
and there are many more.
|
||
|
||
Several commands let you examine the list of targets:
|
||
|
||
-- Command: target current
|
||
Returns the name of the current target.
|
||
|
||
-- Command: target names
|
||
Lists the names of all current targets in the list.
|
||
foreach t [target names] {
|
||
puts [format "Target: %s\n" $t]
|
||
}
|
||
|
||
-- Command: targets [name]
|
||
_Note: the name of this command is plural. Other target command
|
||
names are singular._
|
||
|
||
With no parameter, this command displays a table of all known
|
||
targets in a user friendly form.
|
||
|
||
With a parameter, this command sets the current target to the given
|
||
target with the given NAME; this is only relevant on boards which
|
||
have more than one target.
|
||
|
||
11.2 Target CPU Types
|
||
=====================
|
||
|
||
Each target has a "CPU type", as shown in the output of the 'targets'
|
||
command. You need to specify that type when calling 'target create'.
|
||
The CPU type indicates more than just the instruction set. It also
|
||
indicates how that instruction set is implemented, what kind of debug
|
||
support it integrates, whether it has an MMU (and if so, what kind),
|
||
what core-specific commands may be available (*note Architecture and
|
||
Core Commands::), and more.
|
||
|
||
It's easy to see what target types are supported, since there's a
|
||
command to list them.
|
||
|
||
-- Command: target types
|
||
Lists all supported target types. At this writing, the supported
|
||
CPU types are:
|
||
|
||
* 'aarch64' - this is an ARMv8-A core with an MMU.
|
||
* 'arm11' - this is a generation of ARMv6 cores.
|
||
* 'arm720t' - this is an ARMv4 core with an MMU.
|
||
* 'arm7tdmi' - this is an ARMv4 core.
|
||
* 'arm920t' - this is an ARMv4 core with an MMU.
|
||
* 'arm926ejs' - this is an ARMv5 core with an MMU.
|
||
* 'arm946e' - this is an ARMv5 core with an MMU.
|
||
* 'arm966e' - this is an ARMv5 core.
|
||
* 'arm9tdmi' - this is an ARMv4 core.
|
||
* 'avr' - implements Atmel's 8-bit AVR instruction set.
|
||
(Support for this is preliminary and incomplete.)
|
||
* 'avr32_ap7k' - this an AVR32 core.
|
||
* 'cortex_a' - this is an ARMv7-A core with an MMU.
|
||
* 'cortex_m' - this is an ARMv7-M core, supporting only the
|
||
compact Thumb2 instruction set. Supports also ARMv6-M and
|
||
ARMv8-M cores
|
||
* 'cortex_r4' - this is an ARMv7-R core.
|
||
* 'dragonite' - resembles arm966e.
|
||
* 'dsp563xx' - implements Freescale's 24-bit DSP. (Support for
|
||
this is still incomplete.)
|
||
* 'dsp5680xx' - implements Freescale's 5680x DSP.
|
||
* 'esirisc' - this is an EnSilica eSi-RISC core. The current
|
||
implementation supports eSi-32xx cores.
|
||
* 'fa526' - resembles arm920 (w/o Thumb).
|
||
* 'feroceon' - resembles arm926.
|
||
* 'hla_target' - a Cortex-M alternative to work with HL adapters
|
||
like ST-Link.
|
||
* 'ls1_sap' - this is the SAP on NXP LS102x CPUs, allowing
|
||
access to physical memory addresses independently of CPU
|
||
cores.
|
||
* 'mem_ap' - this is an ARM debug infrastructure Access Port
|
||
without a CPU, through which bus read and write cycles can be
|
||
generated; it may be useful for working with non-CPU hardware
|
||
behind an AP or during development of support for new CPUs.
|
||
It's possible to connect a GDB client to this target (the GDB
|
||
port has to be specified, *Note option -gdb-port:
|
||
gdbportoverride.), and a fake ARM core will be emulated to
|
||
comply to GDB remote protocol.
|
||
* 'mips_m4k' - a MIPS core.
|
||
* 'mips_mips64' - a MIPS64 core.
|
||
* 'nds32_v2' - this is an Andes NDS32 v2 core.
|
||
* 'nds32_v3' - this is an Andes NDS32 v3 core.
|
||
* 'nds32_v3m' - this is an Andes NDS32 v3m core.
|
||
* 'or1k' - this is an OpenRISC 1000 core. The current
|
||
implementation supports three JTAG TAP cores:
|
||
- 'OpenCores TAP' (See:
|
||
<http://opencores.org/project,jtag>)
|
||
- 'Altera Virtual JTAG TAP' (See:
|
||
<http://www.altera.com/literature/ug/ug_virtualjtag.pdf>)
|
||
- 'Xilinx BSCAN_* virtual JTAG interface' (See:
|
||
<http://www.xilinx.com/support/documentation/sw_manuals/xilinx14_2/spartan6_hdl.pdf>)
|
||
And two debug interfaces cores:
|
||
- 'Advanced debug interface'
|
||
(See: <http://opencores.org/project,adv_debug_sys>)
|
||
- 'SoC Debug Interface'
|
||
(See: <http://opencores.org/project,dbg_interface>)
|
||
* 'quark_d20xx' - an Intel Quark D20xx core.
|
||
* 'quark_x10xx' - an Intel Quark X10xx core.
|
||
* 'riscv' - a RISC-V core.
|
||
* 'stm8' - implements an STM8 core.
|
||
* 'testee' - a dummy target for cases without a real CPU, e.g.
|
||
CPLD.
|
||
* 'xscale' - this is actually an architecture, not a CPU type.
|
||
It is based on the ARMv5 architecture.
|
||
|
||
To avoid being confused by the variety of ARM based cores, remember this
|
||
key point: _ARM is a technology licencing company_. (See:
|
||
<http://www.arm.com>.) The CPU name used by OpenOCD will reflect the
|
||
CPU design that was licensed, not a vendor brand which incorporates that
|
||
design. Name prefixes like arm7, arm9, arm11, and cortex reflect design
|
||
generations; while names like ARMv4, ARMv5, ARMv6, ARMv7 and ARMv8
|
||
reflect an architecture version implemented by a CPU design.
|
||
|
||
11.3 Target Configuration
|
||
=========================
|
||
|
||
Before creating a "target", you must have added its TAP to the scan
|
||
chain. When you've added that TAP, you will have a 'dotted.name' which
|
||
is used to set up the CPU support. The chip-specific configuration file
|
||
will normally configure its CPU(s) right after it adds all of the chip's
|
||
TAPs to the scan chain.
|
||
|
||
Although you can set up a target in one step, it's often clearer if you
|
||
use shorter commands and do it in two steps: create it, then configure
|
||
optional parts. All operations on the target after it's created will
|
||
use a new command, created as part of target creation.
|
||
|
||
The two main things to configure after target creation are a work area,
|
||
which usually has target-specific defaults even if the board setup code
|
||
overrides them later; and event handlers (*note Target Events:
|
||
targetevents.), which tend to be much more board-specific. The key
|
||
steps you use might look something like this
|
||
|
||
dap create mychip.dap -chain-position mychip.cpu
|
||
target create MyTarget cortex_m -dap mychip.dap
|
||
MyTarget configure -work-area-phys 0x08000 -work-area-size 8096
|
||
MyTarget configure -event reset-deassert-pre { jtag_rclk 5 }
|
||
MyTarget configure -event reset-init { myboard_reinit }
|
||
|
||
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 more.
|
||
|
||
Warning: On more complex chips, the work area can become
|
||
inaccessible when application code (such as an operating system)
|
||
enables or disables the MMU. For example, the particular MMU
|
||
context used to access the virtual address will probably matter ...
|
||
and that context might not have easy access to other addresses
|
||
needed. At this writing, OpenOCD doesn't have much MMU
|
||
intelligence.
|
||
|
||
It's often very useful to define a 'reset-init' event handler. For
|
||
systems that are normally used with a boot loader, common tasks include
|
||
updating clocks and initializing memory controllers. That may be needed
|
||
to let you write the boot loader into flash, in order to "de-brick" your
|
||
board; or to load programs into external DDR memory without having run
|
||
the boot loader.
|
||
|
||
-- Config Command: target create target_name type configparams...
|
||
This command creates a GDB debug target that refers to a specific
|
||
JTAG tap. It enters that target into a list, and creates a new
|
||
command ('TARGET_NAME') which is used for various purposes
|
||
including additional configuration.
|
||
|
||
* TARGET_NAME ... is the name of the debug target. By
|
||
convention this should be the same as the _dotted.name_ of the
|
||
TAP associated with this target, which must be specified here
|
||
using the '-chain-position DOTTED.NAME' configparam.
|
||
|
||
This name is also used to create the target object command,
|
||
referred to here as '$target_name', and in other places the
|
||
target needs to be identified.
|
||
* TYPE ... specifies the target type. *Note target types:
|
||
targettypes.
|
||
* CONFIGPARAMS ... all parameters accepted by '$target_name
|
||
configure' are permitted. If the target is big-endian, set it
|
||
here with '-endian big'.
|
||
|
||
You _must_ set the '-chain-position DOTTED.NAME' or '-dap
|
||
DAP_NAME' here.
|
||
|
||
-- Command: $target_name configure configparams...
|
||
The options accepted by this command may also be specified as
|
||
parameters to 'target create'. Their values can later be queried
|
||
one at a time by using the '$target_name cget' command.
|
||
|
||
_Warning:_ changing some of these after setup is dangerous. For
|
||
example, moving a target from one TAP to another; and changing its
|
||
endianness.
|
||
|
||
* '-chain-position' DOTTED.NAME - names the TAP used to access
|
||
this target.
|
||
|
||
* '-dap' DAP_NAME - names the DAP used to access this target.
|
||
*Note DAP declaration: dapdeclaration, on how to create and
|
||
manage DAP instances.
|
||
|
||
* '-endian' ('big'|'little') - specifies whether the CPU uses
|
||
big or little endian conventions
|
||
|
||
* '-event' EVENT_NAME EVENT_BODY - *Note Target Events:
|
||
targetevents. Note that this updates a list of named event
|
||
handlers. Calling this twice with two different event names
|
||
assigns two different handlers, but calling it twice with the
|
||
same event name assigns only one handler.
|
||
|
||
Current target is temporarily overridden to the event issuing
|
||
target before handler code starts and switched back after
|
||
handler is done.
|
||
|
||
* '-work-area-backup' ('0'|'1') - says whether the work area
|
||
gets backed up; by default, _it is not backed up._ When
|
||
possible, use a working_area that doesn't need to be backed
|
||
up, since performing a backup slows down operations. For
|
||
example, the beginning of an SRAM block is likely to be used
|
||
by most build systems, but the end is often unused.
|
||
|
||
* '-work-area-size' SIZE - specify work are size, in bytes. The
|
||
same size applies regardless of whether its physical or
|
||
virtual address is being used.
|
||
|
||
* '-work-area-phys' ADDRESS - set the work area base ADDRESS to
|
||
be used when no MMU is active.
|
||
|
||
* '-work-area-virt' ADDRESS - set the work area base ADDRESS to
|
||
be used when an MMU is active. _Do not specify a value for
|
||
this except on targets with an MMU._ The value should normally
|
||
correspond to a static mapping for the '-work-area-phys'
|
||
address, set up by the current operating system.
|
||
|
||
* '-rtos' RTOS_TYPE - enable rtos support for target, RTOS_TYPE
|
||
can be one of 'auto', 'eCos', 'ThreadX', 'FreeRTOS', 'linux',
|
||
'ChibiOS', 'embKernel', 'mqx', 'uCOS-III', 'nuttx', 'RIOT',
|
||
'Zephyr' *Note RTOS Support: gdbrtossupport.
|
||
|
||
* '-defer-examine' - skip target examination at initial JTAG
|
||
chain scan and after a reset. A manual call to arp_examine is
|
||
required to access the target for debugging.
|
||
|
||
* '-ap-num' AP_NUMBER - set DAP access port for target,
|
||
AP_NUMBER is the numeric index of the DAP AP the target is
|
||
connected to. Use this option with systems where multiple,
|
||
independent cores are connected to separate access ports of
|
||
the same DAP.
|
||
|
||
* '-cti' CTI_NAME - set Cross-Trigger Interface (CTI) connected
|
||
to the target. Currently, only the 'aarch64' target makes use
|
||
of this option, where it is a mandatory configuration for the
|
||
target run control. *Note ARM Cross-Trigger Interface:
|
||
armcrosstrigger, for instruction on how to declare and control
|
||
a CTI instance.
|
||
|
||
* '-gdb-port' NUMBER - see command 'gdb_port' for the possible
|
||
values of the parameter NUMBER, which are not only numeric
|
||
values. Use this option to override, for this target only,
|
||
the global parameter set with command 'gdb_port'. *Note
|
||
command gdb_port: gdb_port.
|
||
|
||
* '-gdb-max-connections' NUMBER - EXPERIMENTAL: set the maximum
|
||
number of GDB connections that are allowed for the target.
|
||
Default is 1. A negative value for NUMBER means unlimited
|
||
connections. See *Note Using GDB as a non-intrusive memory
|
||
inspector: gdbmeminspect.
|
||
|
||
11.4 Other $target_name Commands
|
||
================================
|
||
|
||
The Tcl/Tk language has the concept of object commands, and OpenOCD
|
||
adopts that same model for targets.
|
||
|
||
A good Tk example is a on screen button. Once a button is created a
|
||
button has a name (a path in Tk terms) and that name is useable as a
|
||
first class command. For example in Tk, one can create a button and
|
||
later configure it like this:
|
||
|
||
# Create
|
||
button .foobar -background red -command { foo }
|
||
# Modify
|
||
.foobar configure -foreground blue
|
||
# Query
|
||
set x [.foobar cget -background]
|
||
# Report
|
||
puts [format "The button is %s" $x]
|
||
|
||
In OpenOCD's terms, the "target" is an object just like a Tcl/Tk button,
|
||
and its object commands are invoked the same way.
|
||
|
||
str912.cpu mww 0x1234 0x42
|
||
omap3530.cpu mww 0x5555 123
|
||
|
||
The commands supported by OpenOCD target objects are:
|
||
|
||
-- Command: $target_name arp_examine 'allow-defer'
|
||
-- Command: $target_name arp_halt
|
||
-- Command: $target_name arp_poll
|
||
-- Command: $target_name arp_reset
|
||
-- Command: $target_name arp_waitstate
|
||
Internal OpenOCD scripts (most notably 'startup.tcl') use these to
|
||
deal with specific reset cases. They are not otherwise documented
|
||
here.
|
||
|
||
-- Command: $target_name array2mem arrayname width address count
|
||
-- Command: $target_name mem2array arrayname width address count
|
||
These provide an efficient script-oriented interface to memory.
|
||
The 'array2mem' primitive writes bytes, halfwords, words or
|
||
double-words; while 'mem2array' reads them. In both cases, the TCL
|
||
side uses an array, and the target side uses raw memory.
|
||
|
||
The efficiency comes from enabling the use of bulk JTAG data
|
||
transfer operations. The script orientation comes from working
|
||
with data values that are packaged for use by TCL scripts; 'mdw'
|
||
type primitives only print data they retrieve, and neither store
|
||
nor return those values.
|
||
|
||
* ARRAYNAME ... is the name of an array variable
|
||
* WIDTH ... is 8/16/32/64 - indicating the memory access size
|
||
* ADDRESS ... is the target memory address
|
||
* COUNT ... is the number of elements to process
|
||
|
||
-- Command: $target_name cget queryparm
|
||
Each configuration parameter accepted by '$target_name configure'
|
||
can be individually queried, to return its current value. The
|
||
QUERYPARM is a parameter name accepted by that command, such as
|
||
'-work-area-phys'. There are a few special cases:
|
||
|
||
* '-event' EVENT_NAME - returns the handler for the event named
|
||
EVENT_NAME. This is a special case because setting a handler
|
||
requires two parameters.
|
||
* '-type' - returns the target type. This is a special case
|
||
because this is set using 'target create' and can't be changed
|
||
using '$target_name configure'.
|
||
|
||
For example, if you wanted to summarize information about all the
|
||
targets you might use something like this:
|
||
|
||
foreach name [target names] {
|
||
set y [$name cget -endian]
|
||
set z [$name cget -type]
|
||
puts [format "Chip %d is %s, Endian: %s, type: %s" \
|
||
$x $name $y $z]
|
||
}
|
||
|
||
-- Command: $target_name curstate
|
||
Displays the current target state: 'debug-running', 'halted',
|
||
'reset', 'running', or 'unknown'. (Also, *note Event Polling:
|
||
eventpolling.)
|
||
|
||
-- Command: $target_name eventlist
|
||
Displays a table listing all event handlers currently associated
|
||
with this target. *Note Target Events: targetevents.
|
||
|
||
-- Command: $target_name invoke-event event_name
|
||
Invokes the handler for the event named EVENT_NAME. (This is
|
||
primarily intended for use by OpenOCD framework code, for example
|
||
by the reset code in 'startup.tcl'.)
|
||
|
||
-- Command: $target_name mdd [phys] addr [count]
|
||
-- Command: $target_name mdw [phys] addr [count]
|
||
-- Command: $target_name mdh [phys] addr [count]
|
||
-- Command: $target_name mdb [phys] addr [count]
|
||
Display contents of address ADDR, as 64-bit doublewords ('mdd'),
|
||
32-bit words ('mdw'), 16-bit halfwords ('mdh'), or 8-bit bytes
|
||
('mdb'). When the current target has an MMU which is present and
|
||
active, ADDR is interpreted as a virtual address. Otherwise, or if
|
||
the optional PHYS flag is specified, ADDR is interpreted as a
|
||
physical address. If COUNT is specified, displays that many units.
|
||
(If you want to manipulate the data instead of displaying it, see
|
||
the 'mem2array' primitives.)
|
||
|
||
-- Command: $target_name mwd [phys] addr doubleword [count]
|
||
-- Command: $target_name mww [phys] addr word [count]
|
||
-- Command: $target_name mwh [phys] addr halfword [count]
|
||
-- Command: $target_name mwb [phys] addr byte [count]
|
||
Writes the specified DOUBLEWORD (64 bits), WORD (32 bits), HALFWORD
|
||
(16 bits), or BYTE (8-bit) value, at the specified address ADDR.
|
||
When the current target has an MMU which is present and active,
|
||
ADDR is interpreted as a virtual address. Otherwise, or if the
|
||
optional PHYS flag is specified, ADDR is interpreted as a physical
|
||
address. If COUNT is specified, fills that many units of
|
||
consecutive address.
|
||
|
||
11.5 Target Events
|
||
==================
|
||
|
||
At various times, certain things can happen, or you want them to happen.
|
||
For example:
|
||
* What should happen when GDB connects? Should your target reset?
|
||
* When GDB tries to flash the target, do you need to enable the flash
|
||
via a special command?
|
||
* Is using SRST appropriate (and possible) on your system? Or
|
||
instead of that, do you need to issue JTAG commands to trigger
|
||
reset? SRST usually resets everything on the scan chain, which can
|
||
be inappropriate.
|
||
* During reset, do you need to write to certain memory locations to
|
||
set up system clocks or to reconfigure the SDRAM? How about
|
||
configuring the watchdog timer, or other peripherals, to stop
|
||
running while you hold the core stopped for debugging?
|
||
|
||
All of the above items can be addressed by target event handlers. These
|
||
are set up by '$target_name configure -event' or 'target create ...
|
||
-event'.
|
||
|
||
The programmer's model matches the '-command' option used in Tcl/Tk
|
||
buttons and events. The two examples below act the same, but one
|
||
creates and invokes a small procedure while the other inlines it.
|
||
|
||
proc my_init_proc { } {
|
||
echo "Disabling watchdog..."
|
||
mww 0xfffffd44 0x00008000
|
||
}
|
||
mychip.cpu configure -event reset-init my_init_proc
|
||
mychip.cpu configure -event reset-init {
|
||
echo "Disabling watchdog..."
|
||
mww 0xfffffd44 0x00008000
|
||
}
|
||
|
||
The following target events are defined:
|
||
|
||
* debug-halted
|
||
The target has halted for debug reasons (i.e.: breakpoint)
|
||
* debug-resumed
|
||
The target has resumed (i.e.: GDB said run)
|
||
* early-halted
|
||
Occurs early in the halt process
|
||
* examine-start
|
||
Before target examine is called.
|
||
* examine-end
|
||
After target examine is called with no errors.
|
||
* examine-fail
|
||
After target examine fails.
|
||
* gdb-attach
|
||
When GDB connects. Issued before any GDB communication with the
|
||
target starts. GDB expects the target is halted during attachment.
|
||
*Note GDB as a non-intrusive memory inspector: gdbmeminspect, how
|
||
to connect GDB to running target. The event can be also used to
|
||
set up the target so it is possible to probe flash. Probing flash
|
||
is necessary during GDB connect if you want to use *note
|
||
programming using GDB: programmingusinggdb. Another use of the
|
||
flash memory map is for GDB to automatically choose hardware or
|
||
software breakpoints depending on whether the breakpoint is in RAM
|
||
or read only memory. Default is 'halt'
|
||
* gdb-detach
|
||
When GDB disconnects
|
||
* gdb-end
|
||
When the target has halted and GDB is not doing anything (see early
|
||
halt)
|
||
* gdb-flash-erase-start
|
||
Before the GDB flash process tries to erase the flash (default is
|
||
'reset init')
|
||
* gdb-flash-erase-end
|
||
After the GDB flash process has finished erasing the flash
|
||
* gdb-flash-write-start
|
||
Before GDB writes to the flash
|
||
* gdb-flash-write-end
|
||
After GDB writes to the flash (default is 'reset halt')
|
||
* gdb-start
|
||
Before the target steps, GDB is trying to start/resume the target
|
||
* halted
|
||
The target has halted
|
||
* reset-assert-pre
|
||
Issued as part of 'reset' processing after 'reset-start' was
|
||
triggered but before either SRST alone is asserted on the scan
|
||
chain, or 'reset-assert' is triggered.
|
||
* reset-assert
|
||
Issued as part of 'reset' processing after 'reset-assert-pre' was
|
||
triggered. When such a handler is present, cores which support
|
||
this event will use it instead of asserting SRST. This support is
|
||
essential for debugging with JTAG interfaces which don't include an
|
||
SRST line (JTAG doesn't require SRST), and for selective reset on
|
||
scan chains that have multiple targets.
|
||
* reset-assert-post
|
||
Issued as part of 'reset' processing after 'reset-assert' has been
|
||
triggered. or the target asserted SRST on the entire scan chain.
|
||
* reset-deassert-pre
|
||
Issued as part of 'reset' processing after 'reset-assert-post' has
|
||
been triggered.
|
||
* reset-deassert-post
|
||
Issued as part of 'reset' processing after 'reset-deassert-pre' has
|
||
been triggered and (if the target is using it) after SRST has been
|
||
released on the scan chain.
|
||
* reset-end
|
||
Issued as the final step in 'reset' processing.
|
||
* reset-init
|
||
Used by reset init command for board-specific initialization. This
|
||
event fires after _reset-deassert-post_.
|
||
|
||
This is where you would configure PLLs and clocking, set up DRAM so
|
||
you can download programs that don't fit in on-chip SRAM, set up
|
||
pin multiplexing, and so on. (You may be able to switch to a fast
|
||
JTAG clock rate here, after the target clocks are fully set up.)
|
||
* reset-start
|
||
Issued as the first step in 'reset' processing before
|
||
'reset-assert-pre' is called.
|
||
|
||
This is the most robust place to use 'jtag_rclk' or 'adapter speed'
|
||
to switch to a low JTAG clock rate, when reset disables PLLs needed
|
||
to use a fast clock.
|
||
* resume-start
|
||
Before any target is resumed
|
||
* resume-end
|
||
After all targets have resumed
|
||
* resumed
|
||
Target has resumed
|
||
* step-start
|
||
Before a target is single-stepped
|
||
* step-end
|
||
After single-step has completed
|
||
* trace-config
|
||
After target hardware trace configuration was changed
|
||
|
||
Note: OpenOCD events are not supposed to be preempt by another
|
||
event, but this is not enforced in current code. Only the target
|
||
event resumed is executed with polling disabled; this avoids
|
||
polling to trigger the event halted, reversing the logical order of
|
||
execution of their handlers. Future versions of OpenOCD will
|
||
prevent the event preemption and will disable the schedule of
|
||
polling during the event execution. Do not rely on polling in any
|
||
event handler; this means, don't expect the status of a core to
|
||
change during the execution of the handler. The event handler will
|
||
have to enable polling or use '$target_name arp_poll' to check if
|
||
the core has changed status.
|
||
|
||
|
||
File: openocd.info, Node: Flash Commands, Next: Flash Programming, Prev: CPU Configuration, Up: Top
|
||
|
||
12 Flash Commands
|
||
*****************
|
||
|
||
OpenOCD has different commands for NOR and NAND flash; the "flash"
|
||
command works with NOR flash, while the "nand" command works with NAND
|
||
flash. This partially reflects different hardware technologies: NOR
|
||
flash usually supports direct CPU instruction and data bus access, while
|
||
data from a NAND flash must be copied to memory before it can be used.
|
||
(SPI flash must also be copied to memory before use.) However, the
|
||
documentation also uses "flash" as a generic term; for example, "Put
|
||
flash configuration in board-specific files".
|
||
|
||
Flash Steps:
|
||
1. Configure via the command 'flash bank'
|
||
Do this in a board-specific configuration file, passing parameters
|
||
as needed by the driver.
|
||
2. Operate on the flash via 'flash subcommand'
|
||
Often commands to manipulate the flash are typed by a human, or run
|
||
via a script in some automated way. Common tasks include writing a
|
||
boot loader, operating system, or other data.
|
||
3. GDB Flashing
|
||
Flashing via GDB requires the flash be configured via "flash bank",
|
||
and the GDB flash features be enabled. *Note GDB Configuration:
|
||
gdbconfiguration.
|
||
|
||
Many CPUs have the ability to "boot" from the first flash bank. This
|
||
means that misprogramming that bank can "brick" a system, so that it
|
||
can't boot. JTAG tools, like OpenOCD, are often then used to "de-brick"
|
||
the board by (re)installing working boot firmware.
|
||
|
||
12.1 Flash Configuration Commands
|
||
=================================
|
||
|
||
-- Config Command: flash bank name driver base size chip_width
|
||
bus_width target [driver_options]
|
||
Configures a flash bank which provides persistent storage for
|
||
addresses from base to base + size - 1. These banks will often be
|
||
visible to GDB through the target's memory map. In some cases,
|
||
configuring a flash bank will activate extra commands; see the
|
||
driver-specific documentation.
|
||
|
||
* NAME ... may be used to reference the flash bank in other
|
||
flash commands. A number is also available.
|
||
* DRIVER ... identifies the controller driver associated with
|
||
the flash bank being declared. This is usually 'cfi' for
|
||
external flash, or else the name of a microcontroller with
|
||
embedded flash memory. *Note Flash Driver List:
|
||
flashdriverlist.
|
||
* BASE ... Base address of the flash chip.
|
||
* SIZE ... Size of the chip, in bytes. For some drivers, this
|
||
value is detected from the hardware.
|
||
* CHIP_WIDTH ... Width of the flash chip, in bytes; ignored for
|
||
most microcontroller drivers.
|
||
* BUS_WIDTH ... Width of the data bus used to access the chip,
|
||
in bytes; ignored for most microcontroller drivers.
|
||
* TARGET ... Names the target used to issue commands to the
|
||
flash controller.
|
||
* DRIVER_OPTIONS ... drivers may support, or require,
|
||
additional parameters. See the driver-specific documentation
|
||
for more information.
|
||
Note: This command is not available after OpenOCD
|
||
initialization has completed. Use it in board specific
|
||
configuration files, not interactively.
|
||
|
||
-- Command: flash banks
|
||
Prints a one-line summary of each device that was declared using
|
||
'flash bank', numbered from zero. Note that this is the _plural_
|
||
form; the _singular_ form is a very different command.
|
||
|
||
-- Command: flash list
|
||
Retrieves a list of associative arrays for each device that was
|
||
declared using 'flash bank', numbered from zero. This returned
|
||
list can be manipulated easily from within scripts.
|
||
|
||
-- Command: flash probe num
|
||
Identify the flash, or validate the parameters of the configured
|
||
flash. Operation depends on the flash type. The NUM parameter is
|
||
a value shown by 'flash banks'. Most flash commands will
|
||
implicitly _autoprobe_ the bank; flash drivers can distinguish
|
||
between probing and autoprobing, but most don't bother.
|
||
|
||
12.2 Preparing a Target before Flash Programming
|
||
================================================
|
||
|
||
The target device should be in well defined state before the flash
|
||
programming begins.
|
||
|
||
_Always issue_ 'reset init' before *note Flash Programming Commands:
|
||
flashprogrammingcommands. Do not issue another 'reset' or 'reset halt'
|
||
or 'resume' until the programming session is finished.
|
||
|
||
If you use *note Programming using GDB: programmingusinggdb, the target
|
||
is prepared automatically in the event gdb-flash-erase-start
|
||
|
||
The jimtcl script 'program' calls 'reset init' explicitly.
|
||
|
||
12.3 Erasing, Reading, Writing to Flash
|
||
=======================================
|
||
|
||
One feature distinguishing NOR flash from NAND or serial flash
|
||
technologies is that for read access, it acts exactly like any other
|
||
addressable memory. This means you can use normal memory read commands
|
||
like 'mdw' or 'dump_image' with it, with no special 'flash' subcommands.
|
||
*Note Memory access: memoryaccess, and *note Image access: imageaccess.
|
||
|
||
Write access works differently. Flash memory normally needs to be
|
||
erased before it's written. Erasing a sector turns all of its bits to
|
||
ones, and writing can turn ones into zeroes. This is why there are
|
||
special commands for interactive erasing and writing, and why GDB needs
|
||
to know which parts of the address space hold NOR flash memory.
|
||
|
||
Note: Most of these erase and write commands leverage the fact that
|
||
NOR flash chips consume target address space. They implicitly
|
||
refer to the current JTAG target, and map from an address in that
|
||
target's address space back to a flash bank. A few commands use
|
||
abstract addressing based on bank and sector numbers, and don't
|
||
depend on searching the current target and its address space.
|
||
Avoid confusing the two command models.
|
||
|
||
Some flash chips implement software protection against accidental
|
||
writes, since such buggy writes could in some cases "brick" a system.
|
||
For such systems, erasing and writing may require sector protection to
|
||
be disabled first. Examples include CFI flash such as "Intel Advanced
|
||
Bootblock flash", and AT91SAM7 on-chip flash. *Note flash protect:
|
||
flashprotect.
|
||
|
||
-- Command: flash erase_sector num first last
|
||
Erase sectors in bank NUM, starting at sector FIRST up to and
|
||
including LAST. Sector numbering starts at 0. Providing a LAST
|
||
sector of 'last' specifies "to the end of the flash bank". The NUM
|
||
parameter is a value shown by 'flash banks'.
|
||
|
||
-- Command: flash erase_address ['pad'] ['unlock'] address length
|
||
Erase sectors starting at ADDRESS for LENGTH bytes. Unless 'pad'
|
||
is specified, address must begin a flash sector, and address +
|
||
length - 1 must end a sector. Specifying 'pad' erases extra data
|
||
at the beginning and/or end of the specified region, as needed to
|
||
erase only full sectors. The flash bank to use is inferred from
|
||
the ADDRESS, and the specified length must stay within that bank.
|
||
As a special case, when LENGTH is zero and ADDRESS is the start of
|
||
the bank, the whole flash is erased. If 'unlock' is specified,
|
||
then the flash is unprotected before erase starts.
|
||
|
||
-- Command: flash filld address double-word length
|
||
-- Command: flash fillw address word length
|
||
-- Command: flash fillh address halfword length
|
||
-- Command: flash fillb address byte length
|
||
Fills flash memory with the specified DOUBLE-WORD (64 bits), WORD
|
||
(32 bits), HALFWORD (16 bits), or BYTE (8-bit) pattern, starting at
|
||
ADDRESS and continuing for LENGTH units (word/halfword/byte). No
|
||
erasure is done before writing; when needed, that must be done
|
||
before issuing this command. Writes are done in blocks of up to
|
||
1024 bytes, and each write is verified by reading back the data and
|
||
comparing it to what was written. The flash bank to use is
|
||
inferred from the ADDRESS of each block, and the specified length
|
||
must stay within that bank.
|
||
|
||
-- Command: flash mdw addr [count]
|
||
-- Command: flash mdh addr [count]
|
||
-- Command: flash mdb addr [count]
|
||
Display contents of address ADDR, as 32-bit words ('mdw'), 16-bit
|
||
halfwords ('mdh'), or 8-bit bytes ('mdb'). If COUNT is specified,
|
||
displays that many units. Reads from flash using the flash driver,
|
||
therefore it enables reading from a bank not mapped in target
|
||
address space. The flash bank to use is inferred from the ADDRESS
|
||
of each block, and the specified length must stay within that bank.
|
||
|
||
-- Command: flash write_bank num filename [offset]
|
||
Write the binary 'filename' to flash bank NUM, starting at OFFSET
|
||
bytes from the beginning of the bank. If OFFSET is omitted, start
|
||
at the beginning of the flash bank. The NUM parameter is a value
|
||
shown by 'flash banks'.
|
||
|
||
-- Command: flash read_bank num filename [offset [length]]
|
||
Read LENGTH bytes from the flash bank NUM starting at OFFSET and
|
||
write the contents to the binary 'filename'. If OFFSET is omitted,
|
||
start at the beginning of the flash bank. If LENGTH is omitted,
|
||
read the remaining bytes from the flash bank. The NUM parameter is
|
||
a value shown by 'flash banks'.
|
||
|
||
-- Command: flash verify_bank num filename [offset]
|
||
Compare the contents of the binary file FILENAME with the contents
|
||
of the flash bank NUM starting at OFFSET. If OFFSET is omitted,
|
||
start at the beginning of the flash bank. Fail if the contents do
|
||
not match. The NUM parameter is a value shown by 'flash banks'.
|
||
|
||
-- Command: flash write_image [erase] [unlock] filename [offset] [type]
|
||
Write the image 'filename' to the current target's flash bank(s).
|
||
Only loadable sections from the image are written. A relocation
|
||
OFFSET may be specified, in which case it is added to the base
|
||
address for each section in the image. The file [TYPE] can be
|
||
specified explicitly as 'bin' (binary), 'ihex' (Intel hex), 'elf'
|
||
(ELF file), 's19' (Motorola s19). 'mem', or 'builder'. The
|
||
relevant flash sectors will be erased prior to programming if the
|
||
'erase' parameter is given. If 'unlock' is provided, then the
|
||
flash banks are unlocked before erase and program. The flash bank
|
||
to use is inferred from the address of each image section.
|
||
|
||
Warning: Be careful using the 'erase' flag when the flash is
|
||
holding data you want to preserve. Portions of the flash
|
||
outside those described in the image's sections might be
|
||
erased with no notice.
|
||
* When a section of the image being written does not fill
|
||
out all the sectors it uses, the unwritten parts of those
|
||
sectors are necessarily also erased, because sectors
|
||
can't be partially erased.
|
||
* Data stored in sector "holes" between image sections are
|
||
also affected. For example, "'flash write_image erase
|
||
...'" of an image with one byte at the beginning of a
|
||
flash bank and one byte at the end erases the entire bank
|
||
- not just the two sectors being written.
|
||
Also, when flash protection is important, you must re-apply it
|
||
after it has been removed by the 'unlock' flag.
|
||
|
||
-- Command: flash verify_image filename [offset] [type]
|
||
Verify the image 'filename' to the current target's flash bank(s).
|
||
Parameters follow the description of 'flash write_image'. In
|
||
contrast to the 'verify_image' command, for banks with specific
|
||
verify method, that one is used instead of the usual target's read
|
||
memory methods. This is necessary for flash banks not readable by
|
||
ordinary memory reads. This command gives only an overall good/bad
|
||
result for each bank, not addresses of individual failed bytes as
|
||
it's intended only as quick check for successful programming.
|
||
|
||
12.4 Other Flash commands
|
||
=========================
|
||
|
||
-- Command: flash erase_check num
|
||
Check erase state of sectors in flash bank NUM, and display that
|
||
status. The NUM parameter is a value shown by 'flash banks'.
|
||
|
||
-- Command: flash info num [sectors]
|
||
Print info about flash bank NUM, a list of protection blocks and
|
||
their status. Use 'sectors' to show a list of sectors instead.
|
||
|
||
The NUM parameter is a value shown by 'flash banks'. This command
|
||
will first query the hardware, it does not print cached and
|
||
possibly stale information.
|
||
|
||
-- Command: flash protect num first last ('on'|'off')
|
||
Enable ('on') or disable ('off') protection of flash blocks in
|
||
flash bank NUM, starting at protection block FIRST and continuing
|
||
up to and including LAST. Providing a LAST block of 'last'
|
||
specifies "to the end of the flash bank". The NUM parameter is a
|
||
value shown by 'flash banks'. The protection block is usually
|
||
identical to a flash sector. Some devices may utilize a protection
|
||
block distinct from flash sector. See 'flash info' for a list of
|
||
protection blocks.
|
||
|
||
-- 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 command or the flash driver then it defaults to
|
||
0xff.
|
||
|
||
-- Command: program filename [preverify] [verify] [reset] [exit]
|
||
[offset]
|
||
This is a helper script that simplifies using OpenOCD as a
|
||
standalone programmer. The only required parameter is 'filename',
|
||
the others are optional. *Note Flash Programming::.
|
||
|
||
12.5 Flash Driver List
|
||
======================
|
||
|
||
As noted above, the 'flash bank' command requires a driver name, and
|
||
allows driver-specific options and behaviors. Some drivers also
|
||
activate driver-specific commands.
|
||
|
||
-- Flash Driver: virtual
|
||
This is a special driver that maps a previously defined bank to
|
||
another address. All bank settings will be copied from the master
|
||
physical bank.
|
||
|
||
The VIRTUAL driver defines one mandatory parameters,
|
||
|
||
* MASTER_BANK The bank that this virtual address refers to.
|
||
|
||
So in the following example addresses 0xbfc00000 and 0x9fc00000
|
||
refer to the flash bank defined at address 0x1fc00000. Any command
|
||
executed on the virtual banks is actually performed on the physical
|
||
banks.
|
||
flash bank $_FLASHNAME pic32mx 0x1fc00000 0 0 0 $_TARGETNAME
|
||
flash bank vbank0 virtual 0xbfc00000 0 0 0 \
|
||
$_TARGETNAME $_FLASHNAME
|
||
flash bank vbank1 virtual 0x9fc00000 0 0 0 \
|
||
$_TARGETNAME $_FLASHNAME
|
||
|
||
12.5.1 External Flash
|
||
---------------------
|
||
|
||
-- Flash Driver: cfi
|
||
The "Common Flash Interface" (CFI) is the main standard for
|
||
external NOR flash chips, each of which connects to a specific
|
||
external chip select on the CPU. Frequently the first such chip is
|
||
used to boot the system. Your board's 'reset-init' handler might
|
||
need to configure additional chip selects using other commands
|
||
(like: 'mww' to configure a bus and its timings), or perhaps
|
||
configure a GPIO pin that controls the "write protect" pin on the
|
||
flash chip. The CFI driver can use a target-specific working area
|
||
to significantly speed up operation.
|
||
|
||
The CFI driver can accept the following optional parameters, in any
|
||
order:
|
||
|
||
* JEDEC_PROBE ... is used to detect certain non-CFI flash ROMs,
|
||
like AM29LV010 and similar types.
|
||
* X16_AS_X8 ... when a 16-bit flash is hooked up to an 8-bit
|
||
bus.
|
||
* BUS_SWAP ... when data bytes in a 16-bit flash needs to be
|
||
swapped.
|
||
* DATA_SWAP ... when data bytes in a 16-bit flash needs to be
|
||
swapped when writing data values (i.e. not CFI commands).
|
||
|
||
To configure two adjacent banks of 16 MBytes each, both sixteen
|
||
bits (two bytes) wide on a sixteen bit bus:
|
||
|
||
flash bank $_FLASHNAME cfi 0x00000000 0x01000000 2 2 $_TARGETNAME
|
||
flash bank $_FLASHNAME cfi 0x01000000 0x01000000 2 2 $_TARGETNAME
|
||
|
||
To configure one bank of 32 MBytes built from two sixteen bit (two
|
||
byte) wide parts wired in parallel to create a thirty-two bit (four
|
||
byte) bus with doubled throughput:
|
||
|
||
flash bank $_FLASHNAME cfi 0x00000000 0x02000000 2 4 $_TARGETNAME
|
||
|
||
-- Flash Driver: jtagspi
|
||
Several FPGAs and CPLDs can retrieve their configuration
|
||
(bitstream) from a SPI flash connected to them. To access this
|
||
flash from the host, the device is first programmed with a special
|
||
proxy bitstream that exposes the SPI flash on the device's JTAG
|
||
interface. The flash can then be accessed through JTAG.
|
||
|
||
Since signaling between JTAG and SPI is compatible, all that is
|
||
required for a proxy bitstream is to connect TDI-MOSI, TDO-MISO,
|
||
TCK-CLK and activate the flash chip select when the JTAG state
|
||
machine is in SHIFT-DR. Such a bitstream for several Xilinx FPGAs
|
||
can be found in 'contrib/loaders/flash/fpga/xilinx_bscan_spi.py'.
|
||
It requires migen (https://github.com/m-labs/migen) and a Xilinx
|
||
toolchain to build.
|
||
|
||
This flash bank driver requires a target on a JTAG tap and will
|
||
access that tap directly. Since no support from the target is
|
||
needed, the target can be a "testee" dummy. Since the target does
|
||
not expose the flash memory mapping, target commands that would
|
||
otherwise be expected to access the flash will not work. These
|
||
include all '*_image' and '$target_name m*' commands as well as
|
||
'program'. Equivalent functionality is available through the
|
||
'flash write_bank', 'flash read_bank', and 'flash verify_bank'
|
||
commands.
|
||
|
||
According to device size, 1- to 4-byte addresses are sent.
|
||
However, some flash chips additionally have to be switched to
|
||
4-byte addresses by an extra command, see below.
|
||
|
||
* IR ... is loaded into the JTAG IR to map the flash as the
|
||
JTAG DR. For the bitstreams generated from
|
||
'xilinx_bscan_spi.py' this is the USER1 instruction.
|
||
|
||
target create $_TARGETNAME testee -chain-position $_CHIPNAME.fpga
|
||
set _XILINX_USER1 0x02
|
||
flash bank $_FLASHNAME spi 0x0 0 0 0 \
|
||
$_TARGETNAME $_XILINX_USER1
|
||
|
||
-- Command: jtagspi set bank_id name total_size page_size read_cmd
|
||
unused pprg_cmd mass_erase_cmd sector_size
|
||
sector_erase_cmd
|
||
Sets flash parameters: NAME human readable string, TOTAL_SIZE
|
||
size in bytes, PAGE_SIZE is write page size. READ_CMD and
|
||
PPRG_CMD are commands for read and page program, respectively.
|
||
MASS_ERASE_CMD, SECTOR_SIZE and SECTOR_ERASE_CMD are optional.
|
||
jtagspi set 0 w25q128 0x1000000 0x100 0x03 0 0x02 0xC7 0x10000 0xD8
|
||
|
||
-- Command: jtagspi cmd bank_id resp_num cmd_byte ...
|
||
Sends command CMD_BYTE and at most 20 following bytes and
|
||
reads RESP_NUM bytes afterwards. E.g. for 'Enter 4-byte
|
||
address mode'
|
||
jtagspi cmd 0 0 0xB7
|
||
|
||
-- Command: jtagspi always_4byte bank_id [ on | off ]
|
||
Some devices use 4-byte addresses for all commands except the
|
||
legacy 0x03 read regardless of device size. This command
|
||
controls the corresponding hack.
|
||
|
||
-- Flash Driver: xcf
|
||
Xilinx FPGAs can be configured from specialized flash ICs named
|
||
Platform Flash. It is (almost) regular NOR flash with erase
|
||
sectors, program pages, etc. The only difference is special
|
||
registers controlling its FPGA specific behavior. They must be
|
||
properly configured for successful FPGA loading using additional
|
||
XCF driver command:
|
||
|
||
-- Command: xcf ccb <bank_id>
|
||
command accepts additional parameters:
|
||
* EXTERNAL|INTERNAL ... selects clock source.
|
||
* SERIAL|PARALLEL ... selects serial or parallel data bus
|
||
mode.
|
||
* SLAVE|MASTER ... selects slave of master mode for flash
|
||
device.
|
||
* 40|20 ... selects clock frequency in MHz for internal
|
||
clock in master mode.
|
||
xcf ccb 0 external parallel slave 40
|
||
All of them must be specified even if clock frequency is
|
||
pointless in slave mode. If only bank id specified than
|
||
command prints current CCB register value. Note: there is no
|
||
need to write this register every time you erase/program data
|
||
sectors because it stores in dedicated sector.
|
||
|
||
-- Command: xcf configure <bank_id>
|
||
Initiates FPGA loading procedure. Useful if your board has no
|
||
"configure" button.
|
||
xcf configure 0
|
||
|
||
Additional driver notes:
|
||
* Only single revision supported.
|
||
* Driver automatically detects need of bit reverse, but only
|
||
"bin" (raw binary, do not confuse it with "bit") and "mcs"
|
||
(Intel hex) file types supported.
|
||
* For additional info check xapp972.pdf and ug380.pdf.
|
||
|
||
-- Flash Driver: lpcspifi
|
||
NXP's LPC43xx and LPC18xx families include a proprietary SPI Flash
|
||
Interface (SPIFI) peripheral that can drive and provide memory
|
||
mapped access to external SPI flash devices.
|
||
|
||
The lpcspifi driver initializes this interface and provides program
|
||
and erase functionality for these serial flash devices. Use of
|
||
this driver requires a working area of at least 1kB to be
|
||
configured on the target device; more than this will significantly
|
||
reduce flash programming times.
|
||
|
||
The setup command only requires the BASE parameter. All other
|
||
parameters are ignored, and the flash size and layout are
|
||
configured by the driver.
|
||
|
||
flash bank $_FLASHNAME lpcspifi 0x14000000 0 0 0 $_TARGETNAME
|
||
|
||
-- Flash Driver: stmsmi
|
||
Some devices from STMicroelectronics (e.g. STR75x MCU family,
|
||
SPEAr MPU family) include a proprietary "Serial Memory Interface"
|
||
(SMI) controller able to drive external SPI flash devices.
|
||
Depending on specific device and board configuration, up to 4
|
||
external flash devices can be connected.
|
||
|
||
SMI makes the flash content directly accessible in the CPU address
|
||
space; each external device is mapped in a memory bank. CPU can
|
||
directly read data, execute code and boot from SMI banks. Normal
|
||
OpenOCD commands like 'mdw' can be used to display the flash
|
||
content.
|
||
|
||
The setup command only requires the BASE parameter in order to
|
||
identify the memory bank. All other parameters are ignored.
|
||
Additional information, like flash size, are detected
|
||
automatically.
|
||
|
||
flash bank $_FLASHNAME stmsmi 0xf8000000 0 0 0 $_TARGETNAME
|
||
|
||
-- Flash Driver: stmqspi
|
||
Some devices from STMicroelectronics include a proprietary "QuadSPI
|
||
Interface" (e.g. STM32F4, STM32F7, STM32L4) or "OctoSPI Interface"
|
||
(e.g. STM32L4+) controller able to drive one or even two (dual
|
||
mode) external SPI flash devices. The OctoSPI is a superset of
|
||
QuadSPI, its presence is detected automatically. Currently only
|
||
the regular command mode is supported, whereas the HyperFlash mode
|
||
is not.
|
||
|
||
QuadSPI/OctoSPI makes the flash contents directly accessible in the
|
||
CPU address space; in case of dual mode both devices must be of the
|
||
same type and are mapped in the same memory bank (even and odd
|
||
addresses interleaved). CPU can directly read data, execute code
|
||
(but not boot) from QuadSPI bank.
|
||
|
||
The 'flash bank' command only requires the BASE parameter and the
|
||
extra parameter IO_BASE in order to identify the memory bank. Both
|
||
are fixed by hardware, see datasheet or RM. All other parameters
|
||
are ignored.
|
||
|
||
The controller must be initialized after each reset and properly
|
||
configured for memory-mapped read operation for the particular
|
||
flash chip(s), for the full list of available register settings cf.
|
||
the controller's RM. This setup is quite board specific (that's why
|
||
booting from this memory is not possible). The flash driver infers
|
||
all parameters from current controller register values when 'flash
|
||
probe BANK_ID' is executed.
|
||
|
||
Normal OpenOCD commands like 'mdw' can be used to display the flash
|
||
content, but only after proper controller initialization as
|
||
described above. However, due to a silicon bug in some devices,
|
||
attempting to access the very last word should be avoided.
|
||
|
||
It is possible to use two (even different) flash chips
|
||
alternatingly, if individual bank chip selects are available. For
|
||
some package variants, this is not the case due to limited pin
|
||
count. To switch from one to another, adjust FSEL bit accordingly
|
||
and re-issue 'flash probe bank_id'. Note that the bank base
|
||
address will _not_ change, so the address spaces of both devices
|
||
will overlap. In dual flash mode both chips must be identical
|
||
regarding size and most other properties.
|
||
|
||
Block or sector protection internal to the flash chip is not
|
||
handled by this driver at all, but can be dealt with manually by
|
||
the 'cmd' command, see below. The sector protection via 'flash
|
||
protect' command etc. is completely internal to openocd, intended
|
||
only to prevent accidental erase or overwrite and it does not
|
||
persist across openocd invocations.
|
||
|
||
OpenOCD contains a hardcoded list of flash devices with their
|
||
properties, these are auto-detected. If a device is not included
|
||
in this list, SFDP discovery is attempted. If this fails or gives
|
||
inappropriate results, manual setting is required (see 'set'
|
||
command).
|
||
|
||
flash bank $_FLASHNAME stmqspi 0x90000000 0 0 0 \
|
||
$_TARGETNAME 0xA0001000
|
||
flash bank $_FLASHNAME stmqspi 0x70000000 0 0 0 \
|
||
$_TARGETNAME 0xA0001400
|
||
|
||
There are three specific commands
|
||
-- Command: stmqspi mass_erase bank_id
|
||
Clears sector protections and performs a mass erase. Works
|
||
only if there is no chip specific write protection engaged.
|
||
|
||
-- Command: stmqspi set bank_id name total_size page_size read_cmd
|
||
fread_cmd pprg_cmd mass_erase_cmd sector_size
|
||
sector_erase_cmd
|
||
Set flash parameters: NAME human readable string, TOTAL_SIZE
|
||
size in bytes, PAGE_SIZE is write page size. READ_CMD,
|
||
FREAD_CMD and PPRG_CMD are commands for reading and page
|
||
programming. FREAD_CMD is used in DPI and QPI modes, READ_CMD
|
||
in normal SPI (single line) mode. MASS_ERASE_CMD, SECTOR_SIZE
|
||
and SECTOR_ERASE_CMD are optional.
|
||
|
||
This command is required if chip id is not hardcoded yet and
|
||
e.g. for EEPROMs or FRAMs which don't support an id command.
|
||
|
||
In dual mode parameters of both chips are set identically.
|
||
The parameters refer to a single chip, so the whole bank gets
|
||
twice the specified capacity etc.
|
||
|
||
-- Command: stmqspi cmd bank_id resp_num cmd_byte ...
|
||
If RESP_NUM is zero, sends command CMD_BYTE and following data
|
||
bytes. In dual mode command byte is sent to _both_ chips but
|
||
data bytes are sent _alternatingly_ to chip 1 and 2, first to
|
||
flash 1, second to flash 2, etc., i.e. the total number of
|
||
bytes (including cmd_byte) must be odd.
|
||
|
||
If RESP_NUM is not zero, cmd and at most four following data
|
||
bytes are sent, in dual mode _simultaneously_ to both chips.
|
||
Then RESP_NUM bytes are read interleaved from both chips
|
||
starting with chip 1. In this case RESP_NUM must be even.
|
||
|
||
Note the hardware dictated subtle difference of those two
|
||
cases in dual-flash mode.
|
||
|
||
To check basic communication settings, issue
|
||
stmqspi cmd bank_id 0 0x04; stmqspi cmd bank_id 1 0x05
|
||
stmqspi cmd bank_id 0 0x06; stmqspi cmd bank_id 1 0x05
|
||
for single flash mode or
|
||
stmqspi cmd bank_id 0 0x04; stmqspi cmd bank_id 2 0x05
|
||
stmqspi cmd bank_id 0 0x06; stmqspi cmd bank_id 2 0x05
|
||
for dual flash mode. This should return the status register
|
||
contents.
|
||
|
||
In 8-line mode, CMD_BYTE is sent twice - first time as given,
|
||
second time complemented. Additionally, in 8-line mode only,
|
||
some commands (e.g. Read Status) need a dummy address, e.g.
|
||
stmqspi cmd bank_id 1 0x05 0x00 0x00 0x00 0x00
|
||
should return the status register contents.
|
||
|
||
-- Flash Driver: mrvlqspi
|
||
This driver supports QSPI flash controller of Marvell's Wireless
|
||
Microcontroller platform.
|
||
|
||
The flash size is autodetected based on the table of known JEDEC
|
||
IDs hardcoded in the OpenOCD sources.
|
||
|
||
flash bank $_FLASHNAME mrvlqspi 0x0 0 0 0 $_TARGETNAME 0x46010000
|
||
|
||
-- Flash Driver: ath79
|
||
Members of ATH79 SoC family from Atheros include a SPI interface
|
||
with 3 chip selects. On reset a SPI flash connected to the first
|
||
chip select (CS0) is made directly read-accessible in the CPU
|
||
address space (up to 16MBytes) and is usually used to store the
|
||
bootloader and operating system. Normal OpenOCD commands like
|
||
'mdw' can be used to display the flash content while it is in
|
||
memory-mapped mode (only the first 4MBytes are accessible without
|
||
additional configuration on reset).
|
||
|
||
The setup command only requires the BASE parameter in order to
|
||
identify the memory bank. The actual value for the base address is
|
||
not otherwise used by the driver. However the mapping is passed to
|
||
gdb. Thus for the memory mapped flash (chipselect CS0) the base
|
||
address should be the actual memory mapped base address. For
|
||
unmapped chipselects (CS1 and CS2) care should be taken to use a
|
||
base address that does not overlap with real memory regions.
|
||
Additional information, like flash size, are detected
|
||
automatically. An optional additional parameter sets the
|
||
chipselect for the bank, with the default CS0. CS1 and CS2 require
|
||
additional GPIO setup before they can be used since the alternate
|
||
function must be enabled on the GPIO pin CS1/CS2 is routed to on
|
||
the given SoC.
|
||
|
||
flash bank $_FLASHNAME ath79 0xbf000000 0 0 0 $_TARGETNAME
|
||
|
||
# When using multiple chipselects the base should be different
|
||
# for each, otherwise the write_image command is not able to
|
||
# distinguish the banks.
|
||
flash bank flash0 ath79 0xbf000000 0 0 0 $_TARGETNAME cs0
|
||
flash bank flash1 ath79 0x10000000 0 0 0 $_TARGETNAME cs1
|
||
flash bank flash2 ath79 0x20000000 0 0 0 $_TARGETNAME cs2
|
||
|
||
-- Flash Driver: fespi
|
||
|
||
SiFive's Freedom E SPI controller, used in HiFive and other boards.
|
||
|
||
flash bank $_FLASHNAME fespi 0x20000000 0 0 0 $_TARGETNAME
|
||
|
||
12.5.2 Internal Flash (Microcontrollers)
|
||
----------------------------------------
|
||
|
||
-- Flash Driver: aduc702x
|
||
The ADUC702x analog microcontrollers from Analog Devices include
|
||
internal flash and use ARM7TDMI cores. The aduc702x flash driver
|
||
works with models ADUC7019 through ADUC7028. The setup command
|
||
only requires the TARGET argument since all devices in this family
|
||
have the same memory layout.
|
||
|
||
flash bank $_FLASHNAME aduc702x 0 0 0 0 $_TARGETNAME
|
||
|
||
-- Flash Driver: ambiqmicro
|
||
All members of the Apollo microcontroller family from Ambiq Micro
|
||
include internal flash and use ARM's Cortex-M4 core. The host
|
||
connects over USB to an FTDI interface that communicates with the
|
||
target using SWD.
|
||
|
||
The AMBIQMICRO driver reads the Chip Information Register detect
|
||
the device class of the MCU. The Flash and SRAM sizes directly
|
||
follow device class, and are used to set up the flash banks. If
|
||
this fails, the driver will use default values set to the minimum
|
||
sizes of an Apollo chip.
|
||
|
||
All Apollo chips have two flash banks of the same size. In all
|
||
cases the first flash bank starts at location 0, and the second
|
||
bank starts after the first.
|
||
|
||
# Flash bank 0
|
||
flash bank $_FLASHNAME ambiqmicro 0 0x00040000 0 0 $_TARGETNAME
|
||
# Flash bank 1 - same size as bank0, starts after bank 0.
|
||
flash bank $_FLASHNAME ambiqmicro 0x00040000 0x00040000 0 0 \
|
||
$_TARGETNAME
|
||
|
||
Flash is programmed using custom entry points into the bootloader.
|
||
This is the only way to program the flash as no flash control
|
||
registers are available to the user.
|
||
|
||
The AMBIQMICRO driver adds some additional commands:
|
||
|
||
-- Command: ambiqmicro mass_erase <bank>
|
||
Erase entire bank.
|
||
-- Command: ambiqmicro page_erase <bank> <first> <last>
|
||
Erase device pages.
|
||
-- Command: ambiqmicro program_otp <bank> <offset> <count>
|
||
Program OTP is a one time operation to create write protected
|
||
flash. The user writes sectors to SRAM starting at
|
||
0x10000010. Program OTP will write these sectors from SRAM to
|
||
flash, and write protect the flash.
|
||
|
||
-- Flash Driver: at91samd
|
||
All members of the ATSAM D2x, D1x, D0x, ATSAMR, ATSAML and ATSAMC
|
||
microcontroller families from Atmel include internal flash and use
|
||
ARM's Cortex-M0+ core.
|
||
|
||
Do not use for ATSAM D51 and E5x: use *Note atsame5::.
|
||
|
||
The devices have one flash bank:
|
||
|
||
flash bank $_FLASHNAME at91samd 0x00000000 0 1 1 $_TARGETNAME
|
||
|
||
-- Command: at91samd chip-erase
|
||
Issues a complete Flash erase via the Device Service Unit
|
||
(DSU). This can be used to erase a chip back to its factory
|
||
state and does not require the processor to be halted.
|
||
|
||
-- Command: at91samd set-security
|
||
Secures the Flash via the Set Security Bit (SSB) command.
|
||
This prevents access to the Flash and can only be undone by
|
||
using the chip-erase command which erases the Flash contents
|
||
and turns off the security bit. Warning: at this time,
|
||
openocd will not be able to communicate with a secured chip
|
||
and it is therefore not possible to chip-erase it without
|
||
using another tool.
|
||
|
||
at91samd set-security enable
|
||
|
||
-- Command: at91samd eeprom
|
||
Shows or sets the EEPROM emulation size configuration, stored
|
||
in the User Row of the Flash. When setting, the EEPROM size
|
||
must be specified in bytes and it must be one of the permitted
|
||
sizes according to the datasheet. Settings are written
|
||
immediately but only take effect on MCU reset. EEPROM
|
||
emulation requires additional firmware support and the minimum
|
||
EEPROM size may not be the same as the minimum that the
|
||
hardware supports. Set the EEPROM size to 0 in order to
|
||
disable this feature.
|
||
|
||
at91samd eeprom
|
||
at91samd eeprom 1024
|
||
|
||
-- Command: at91samd bootloader
|
||
Shows or sets the bootloader size configuration, stored in the
|
||
User Row of the Flash. This is called the BOOTPROT region.
|
||
When setting, the bootloader size must be specified in bytes
|
||
and it must be one of the permitted sizes according to the
|
||
datasheet. Settings are written immediately but only take
|
||
effect on MCU reset. Setting the bootloader size to 0
|
||
disables bootloader protection.
|
||
|
||
at91samd bootloader
|
||
at91samd bootloader 16384
|
||
|
||
-- Command: at91samd dsu_reset_deassert
|
||
This command releases internal reset held by DSU and prepares
|
||
reset vector catch in case of reset halt. Command is used
|
||
internally in event reset-deassert-post.
|
||
|
||
-- Command: at91samd nvmuserrow
|
||
Writes or reads the entire 64 bit wide NVM user row register
|
||
which is located at 0x804000. This register includes various
|
||
fuses lock-bits and factory calibration data. Reading the
|
||
register is done by invoking this command without any
|
||
arguments. Writing is possible by giving 1 or 2 hex values.
|
||
The first argument is the register value to be written and the
|
||
second one is an optional changemask. Every bit which value
|
||
in changemask is 0 will stay unchanged. The lock- and
|
||
reserved-bits are masked out and cannot be changed.
|
||
|
||
# Read user row
|
||
>at91samd nvmuserrow
|
||
NVMUSERROW: 0xFFFFFC5DD8E0C788
|
||
# Write 0xFFFFFC5DD8E0C788 to user row
|
||
>at91samd nvmuserrow 0xFFFFFC5DD8E0C788
|
||
# Write 0x12300 to user row but leave other bits and low
|
||
# byte unchanged
|
||
>at91samd nvmuserrow 0x12345 0xFFF00
|
||
|
||
-- Flash Driver: at91sam3
|
||
All members of the AT91SAM3 microcontroller family from Atmel
|
||
include internal flash and use ARM's Cortex-M3 core. The driver
|
||
currently (6/22/09) recognizes the AT91SAM3U[1/2/4][C/E] chips.
|
||
Note that the driver was orginaly developed and tested using the
|
||
AT91SAM3U4E, using a SAM3U-EK eval board. Support for other chips
|
||
in the family was cribbed from the data sheet. _Note to future
|
||
readers/updaters: Please remove this worrisome comment after other
|
||
chips are confirmed._
|
||
|
||
The AT91SAM3U4[E/C] (256K) chips have two flash banks; most other
|
||
chips have one flash bank. In all cases the flash banks are at the
|
||
following fixed locations:
|
||
|
||
# Flash bank 0 - all chips
|
||
flash bank $_FLASHNAME at91sam3 0x00080000 0 1 1 $_TARGETNAME
|
||
# Flash bank 1 - only 256K chips
|
||
flash bank $_FLASHNAME at91sam3 0x00100000 0 1 1 $_TARGETNAME
|
||
|
||
Internally, the AT91SAM3 flash memory is organized as follows.
|
||
Unlike the AT91SAM7 chips, these are not used as parameters to the
|
||
'flash bank' command:
|
||
|
||
* _N-Banks:_ 256K chips have 2 banks, others have 1 bank.
|
||
* _Bank Size:_ 128K/64K Per flash bank
|
||
* _Sectors:_ 16 or 8 per bank
|
||
* _SectorSize:_ 8K Per Sector
|
||
* _PageSize:_ 256 bytes per page. Note that OpenOCD operates on
|
||
'sector' sizes, not page sizes.
|
||
|
||
The AT91SAM3 driver adds some additional commands:
|
||
|
||
-- Command: at91sam3 gpnvm
|
||
-- Command: at91sam3 gpnvm clear number
|
||
-- Command: at91sam3 gpnvm set number
|
||
-- Command: at91sam3 gpnvm show ['all'|number]
|
||
With no parameters, 'show' or 'show all', shows the status of
|
||
all GPNVM bits. With 'show' NUMBER, displays that bit.
|
||
|
||
With 'set' NUMBER or 'clear' NUMBER, modifies that GPNVM bit.
|
||
|
||
-- Command: at91sam3 info
|
||
This command attempts to display information about the
|
||
AT91SAM3 chip. _First_ it read the 'CHIPID_CIDR' [address
|
||
0x400e0740, see Section 28.2.1, page 505 of the AT91SAM3U
|
||
29/may/2009 datasheet, document id: doc6430A] and decodes the
|
||
values. _Second_ it reads the various clock configuration
|
||
registers and attempts to display how it believes the chip is
|
||
configured. By default, the SLOWCLK is assumed to be 32768
|
||
Hz, see the command 'at91sam3 slowclk'.
|
||
|
||
-- Command: at91sam3 slowclk [value]
|
||
This command shows/sets the slow clock frequency used in the
|
||
'at91sam3 info' command calculations above.
|
||
|
||
-- Flash Driver: at91sam4
|
||
All members of the AT91SAM4 microcontroller family from Atmel
|
||
include internal flash and use ARM's Cortex-M4 core. This driver
|
||
uses the same command names/syntax as *Note at91sam3::.
|
||
|
||
-- Flash Driver: at91sam4l
|
||
All members of the AT91SAM4L microcontroller family from Atmel
|
||
include internal flash and use ARM's Cortex-M4 core. This driver
|
||
uses the same command names/syntax as *Note at91sam3::.
|
||
|
||
The AT91SAM4L driver adds some additional commands:
|
||
-- Command: at91sam4l smap_reset_deassert
|
||
This command releases internal reset held by SMAP and prepares
|
||
reset vector catch in case of reset halt. Command is used
|
||
internally in event reset-deassert-post.
|
||
|
||
-- Flash Driver: atsame5
|
||
All members of the SAM E54, E53, E51 and D51 microcontroller
|
||
families from Microchip (former Atmel) include internal flash and
|
||
use ARM's Cortex-M4 core.
|
||
|
||
The devices have two ECC flash banks with a swapping feature. This
|
||
driver handles both banks together as it were one. Bank swapping
|
||
is not supported yet.
|
||
|
||
flash bank $_FLASHNAME atsame5 0x00000000 0 1 1 $_TARGETNAME
|
||
|
||
-- Command: atsame5 bootloader
|
||
Shows or sets the bootloader size configuration, stored in the
|
||
User Page of the Flash. This is called the BOOTPROT region.
|
||
When setting, the bootloader size must be specified in bytes.
|
||
The nearest bigger protection size is used. Settings are
|
||
written immediately but only take effect on MCU reset.
|
||
Setting the bootloader size to 0 disables bootloader
|
||
protection.
|
||
|
||
atsame5 bootloader
|
||
atsame5 bootloader 16384
|
||
|
||
-- Command: atsame5 chip-erase
|
||
Issues a complete Flash erase via the Device Service Unit
|
||
(DSU). This can be used to erase a chip back to its factory
|
||
state and does not require the processor to be halted.
|
||
|
||
-- Command: atsame5 dsu_reset_deassert
|
||
This command releases internal reset held by DSU and prepares
|
||
reset vector catch in case of reset halt. Command is used
|
||
internally in event reset-deassert-post.
|
||
|
||
-- Command: atsame5 userpage
|
||
Writes or reads the first 64 bits of NVM User Page which is
|
||
located at 0x804000. This field includes various fuses.
|
||
Reading is done by invoking this command without any
|
||
arguments. Writing is possible by giving 1 or 2 hex values.
|
||
The first argument is the value to be written and the second
|
||
one is an optional bit mask (a zero bit in the mask means the
|
||
bit stays unchanged). The reserved fields are always masked
|
||
out and cannot be changed.
|
||
|
||
# Read
|
||
>atsame5 userpage
|
||
USER PAGE: 0xAEECFF80FE9A9239
|
||
# Write
|
||
>atsame5 userpage 0xAEECFF80FE9A9239
|
||
# Write 2 to SEESBLK and 4 to SEEPSZ fields but leave other
|
||
# bits unchanged (setup SmartEEPROM of virtual size 8192
|
||
# bytes)
|
||
>atsame5 userpage 0x4200000000 0x7f00000000
|
||
|
||
-- Flash Driver: atsamv
|
||
All members of the ATSAMV7x, ATSAMS70, and ATSAME70 families from
|
||
Atmel include internal flash and use ARM's Cortex-M7 core. This
|
||
driver uses the same command names/syntax as *Note at91sam3::.
|
||
|
||
flash bank $_FLASHNAME atsamv 0x00400000 0 0 0 $_TARGETNAME
|
||
|
||
-- Command: atsamv gpnvm ['show' ['all'|number]]
|
||
-- Command: atsamv gpnvm ('clr'|'set') number
|
||
With no parameters, 'show' or 'show all', shows the status of
|
||
all GPNVM bits. With 'show' NUMBER, displays that bit.
|
||
|
||
With 'set' NUMBER or 'clear' NUMBER, modifies that GPNVM bit.
|
||
|
||
-- Flash Driver: at91sam7
|
||
All members of the AT91SAM7 microcontroller family from Atmel
|
||
include internal flash and use ARM7TDMI cores. The driver
|
||
automatically recognizes a number of these chips using the chip
|
||
identification register, and autoconfigures itself.
|
||
|
||
flash bank $_FLASHNAME at91sam7 0 0 0 0 $_TARGETNAME
|
||
|
||
For chips which are not recognized by the controller driver, you
|
||
must provide additional parameters in the following order:
|
||
|
||
* CHIP_MODEL ... label used with 'flash info'
|
||
* BANKS
|
||
* SECTORS_PER_BANK
|
||
* PAGES_PER_SECTOR
|
||
* PAGES_SIZE
|
||
* NUM_NVM_BITS
|
||
* FREQ_KHZ ... required if an external clock is provided,
|
||
optional (but recommended) when the oscillator frequency is
|
||
known
|
||
|
||
It is recommended that you provide zeroes for all of those values
|
||
except the clock frequency, so that everything except that
|
||
frequency will be autoconfigured. Knowing the frequency helps
|
||
ensure correct timings for flash access.
|
||
|
||
The flash controller handles erases automatically on a page
|
||
(128/256 byte) basis, so explicit erase commands are not necessary
|
||
for flash programming. However, there is an "EraseAll" command
|
||
that can erase an entire flash plane (of up to 256KB), and it will
|
||
be used automatically when you issue 'flash erase_sector' or 'flash
|
||
erase_address' commands.
|
||
|
||
-- Command: at91sam7 gpnvm bitnum ('set'|'clear')
|
||
Set or clear a "General Purpose Non-Volatile Memory" (GPNVM)
|
||
bit for the processor. Each processor has a number of such
|
||
bits, used for controlling features such as brownout detection
|
||
(so they are not truly general purpose).
|
||
Note: This assumes that the first flash bank (number 0)
|
||
is associated with the appropriate at91sam7 target.
|
||
|
||
-- Flash Driver: avr
|
||
The AVR 8-bit microcontrollers from Atmel integrate flash memory.
|
||
_The current implementation is incomplete._
|
||
|
||
-- Flash Driver: bluenrg-x
|
||
STMicroelectronics BlueNRG-1, BlueNRG-2 and BlueNRG-LP Bluetooth
|
||
low energy wireless system-on-chip. They include ARM Cortex-M0/M0+
|
||
core and internal flash memory. The driver automatically
|
||
recognizes these chips using the chip identification registers, and
|
||
autoconfigures itself.
|
||
|
||
flash bank $_FLASHNAME bluenrg-x 0 0 0 0 $_TARGETNAME
|
||
|
||
Note that when users ask to erase all the sectors of the flash, a
|
||
mass erase command is used which is faster than erasing each single
|
||
sector one by one.
|
||
|
||
flash erase_sector 0 0 last # It will perform a mass erase
|
||
|
||
Triggering a mass erase is also useful when users want to disable
|
||
readout protection.
|
||
|
||
-- Flash Driver: cc26xx
|
||
All versions of the SimpleLink CC13xx and CC26xx microcontrollers
|
||
from Texas Instruments include internal flash. The cc26xx flash
|
||
driver supports both the CC13xx and CC26xx family of devices. The
|
||
driver automatically recognizes the specific version's flash
|
||
parameters and autoconfigures itself. The flash bank starts at
|
||
address 0.
|
||
|
||
flash bank $_FLASHNAME cc26xx 0 0 0 0 $_TARGETNAME
|
||
|
||
-- Flash Driver: cc3220sf
|
||
The CC3220SF version of the SimpleLink CC32xx microcontrollers from
|
||
Texas Instruments includes 1MB of internal flash. The cc3220sf
|
||
flash driver only supports the internal flash. The serial flash on
|
||
SimpleLink boards is programmed via the bootloader over a UART
|
||
connection. Security features of the CC3220SF may erase the
|
||
internal flash during power on reset. Refer to documentation at
|
||
<www.ti.com/cc3220sf> for details on security features and
|
||
programming the serial flash.
|
||
|
||
flash bank $_FLASHNAME cc3220sf 0 0 0 0 $_TARGETNAME
|
||
|
||
-- Flash Driver: efm32
|
||
All members of the EFM32 microcontroller family from Energy Micro
|
||
include internal flash and use ARM Cortex-M3 cores. The driver
|
||
automatically recognizes a number of these chips using the chip
|
||
identification register, and autoconfigures itself.
|
||
flash bank $_FLASHNAME efm32 0 0 0 0 $_TARGETNAME
|
||
A special feature of efm32 controllers is that it is possible to
|
||
completely disable the debug interface by writing the correct
|
||
values to the 'Debug Lock Word'. OpenOCD supports this via the
|
||
following command:
|
||
efm32 debuglock num
|
||
The NUM parameter is a value shown by 'flash banks'. Note that in
|
||
order for this command to take effect, the target needs to be
|
||
reset. _The current implementation is incomplete. Unprotecting
|
||
flash pages is not supported._
|
||
|
||
-- Flash Driver: esirisc
|
||
Members of the eSi-RISC family may optionally include internal
|
||
flash programmed via the eSi-TSMC Flash interface. Additional
|
||
parameters are required to configure the driver: 'cfg_address' is
|
||
the base address of the configuration register interface,
|
||
'clock_hz' is the expected clock frequency, and 'wait_states' is
|
||
the number of configured read wait states.
|
||
|
||
flash bank $_FLASHNAME esirisc base_address size_bytes 0 0 \
|
||
$_TARGETNAME cfg_address clock_hz wait_states
|
||
|
||
-- Command: esirisc flash mass_erase bank_id
|
||
Erase all pages in data memory for the bank identified by
|
||
'bank_id'.
|
||
|
||
-- Command: esirisc flash ref_erase bank_id
|
||
Erase the reference cell for the bank identified by 'bank_id'.
|
||
_This is an uncommon operation._
|
||
|
||
-- Flash Driver: fm3
|
||
All members of the FM3 microcontroller family from Fujitsu include
|
||
internal flash and use ARM Cortex-M3 cores. The FM3 driver uses
|
||
the TARGET parameter to select the correct bank config, it can
|
||
currently be one of the following: 'mb9bfxx1.cpu', 'mb9bfxx2.cpu',
|
||
'mb9bfxx3.cpu', 'mb9bfxx4.cpu', 'mb9bfxx5.cpu' or 'mb9bfxx6.cpu'.
|
||
|
||
flash bank $_FLASHNAME fm3 0 0 0 0 $_TARGETNAME
|
||
|
||
-- Flash Driver: fm4
|
||
All members of the FM4 microcontroller family from Spansion
|
||
(formerly Fujitsu) include internal flash and use ARM Cortex-M4
|
||
cores. The FM4 driver uses a FAMILY parameter to select the
|
||
correct bank config, it can currently be one of the following:
|
||
'MB9BFx64', 'MB9BFx65', 'MB9BFx66', 'MB9BFx67', 'MB9BFx68',
|
||
'S6E2Cx8', 'S6E2Cx9', 'S6E2CxA' or 'S6E2Dx', with 'x' treated as
|
||
wildcard and otherwise case (and any trailing characters) ignored.
|
||
|
||
flash bank ${_FLASHNAME}0 fm4 0x00000000 0 0 0 \
|
||
$_TARGETNAME S6E2CCAJ0A
|
||
flash bank ${_FLASHNAME}1 fm4 0x00100000 0 0 0 \
|
||
$_TARGETNAME S6E2CCAJ0A
|
||
_The current implementation is incomplete. Protection is not
|
||
supported, nor is Chip Erase (only Sector Erase is implemented)._
|
||
|
||
-- Flash Driver: kinetis
|
||
Kx, KLx, KVx and KE1x members of the Kinetis microcontroller family
|
||
from NXP (former Freescale) include internal flash and use ARM
|
||
Cortex-M0+ or M4 cores. The driver automatically recognizes flash
|
||
size and a number of flash banks (1-4) using the chip
|
||
identification register, and autoconfigures itself. Use kinetis_ke
|
||
driver for KE0x and KEAx devices.
|
||
|
||
The KINETIS driver defines option:
|
||
* -sim-base ADDR ... base of System Integration Module where
|
||
chip identification resides. Driver tries two known locations
|
||
if option is omitted.
|
||
|
||
flash bank $_FLASHNAME kinetis 0 0 0 0 $_TARGETNAME
|
||
|
||
-- Config Command: kinetis create_banks
|
||
Configuration command enables automatic creation of additional
|
||
flash banks based on real flash layout of device. Banks are
|
||
created during device probe. Use 'flash probe 0' to force
|
||
probe.
|
||
|
||
-- Command: kinetis fcf_source [protection|write]
|
||
Select what source is used when writing to a Flash
|
||
Configuration Field. 'protection' mode builds FCF content
|
||
from protection bits previously set by 'flash protect'
|
||
command. This mode is default. MCU is protected from
|
||
unwanted locking by immediate writing FCF after erase of
|
||
relevant sector. 'write' mode enables direct write to FCF.
|
||
Protection cannot be set by 'flash protect' command. FCF is
|
||
written along with the rest of a flash image. _BEWARE:
|
||
Incorrect flash configuration may permanently lock the
|
||
device!_
|
||
|
||
-- Command: kinetis fopt [num]
|
||
Set value to write to FOPT byte of Flash Configuration Field.
|
||
Used in kinetis 'fcf_source protection' mode only.
|
||
|
||
-- Command: kinetis mdm check_security
|
||
Checks status of device security lock. Used internally in
|
||
examine-end and examine-fail event.
|
||
|
||
-- Command: kinetis mdm halt
|
||
Issues a halt via the MDM-AP. This command can be used to
|
||
break a watchdog reset loop when connecting to an unsecured
|
||
target.
|
||
|
||
-- Command: kinetis mdm mass_erase
|
||
Issues a complete flash erase via the MDM-AP. This can be used
|
||
to erase a chip back to its factory state, removing security.
|
||
It does not require the processor to be halted, however the
|
||
target will remain in a halted state after this command
|
||
completes.
|
||
|
||
-- Command: kinetis nvm_partition
|
||
For FlexNVM devices only (KxxDX and KxxFX). Command shows or
|
||
sets data flash or EEPROM backup size in kilobytes, sets two
|
||
EEPROM blocks sizes in bytes and enables/disables loading of
|
||
EEPROM contents to FlexRAM during reset.
|
||
|
||
For details see device reference manual, Flash Memory Module,
|
||
Program Partition command.
|
||
|
||
Setting is possible only once after mass_erase. Reset the
|
||
device after partition setting.
|
||
|
||
Show partition size:
|
||
kinetis nvm_partition info
|
||
|
||
Set 32 KB data flash, rest of FlexNVM is EEPROM backup.
|
||
EEPROM has two blocks of 512 and 1536 bytes and its contents
|
||
is loaded to FlexRAM during reset:
|
||
kinetis nvm_partition dataflash 32 512 1536 on
|
||
|
||
Set 16 KB EEPROM backup, rest of FlexNVM is a data flash.
|
||
EEPROM has two blocks of 1024 bytes and its contents is not
|
||
loaded to FlexRAM during reset:
|
||
kinetis nvm_partition eebkp 16 1024 1024 off
|
||
|
||
-- Command: kinetis mdm reset
|
||
Issues a reset via the MDM-AP. This causes the MCU to output a
|
||
low pulse on the RESET pin, which can be used to reset other
|
||
hardware on board.
|
||
|
||
-- Command: kinetis disable_wdog
|
||
For Kx devices only (KLx has different COP watchdog, it is not
|
||
supported). Command disables watchdog timer.
|
||
|
||
-- Flash Driver: kinetis_ke
|
||
KE0x and KEAx members of the Kinetis microcontroller family from
|
||
NXP include internal flash and use ARM Cortex-M0+. The driver
|
||
automatically recognizes the KE0x sub-family using the chip
|
||
identification register, and autoconfigures itself. Use kinetis
|
||
(not kinetis_ke) driver for KE1x devices.
|
||
|
||
flash bank $_FLASHNAME kinetis_ke 0 0 0 0 $_TARGETNAME
|
||
|
||
-- Command: kinetis_ke mdm check_security
|
||
Checks status of device security lock. Used internally in
|
||
examine-end event.
|
||
|
||
-- Command: kinetis_ke mdm mass_erase
|
||
Issues a complete Flash erase via the MDM-AP. This can be used
|
||
to erase a chip back to its factory state. Command removes
|
||
security lock from a device (use of SRST highly recommended).
|
||
It does not require the processor to be halted.
|
||
|
||
-- Command: kinetis_ke disable_wdog
|
||
Command disables watchdog timer.
|
||
|
||
-- Flash Driver: lpc2000
|
||
This is the driver to support internal flash of all members of the
|
||
LPC11(x)00 and LPC1300 microcontroller families and most members of
|
||
the LPC800, LPC1500, LPC1700, LPC1800, LPC2000, LPC4000, LPC54100,
|
||
LPC8Nxx and NHS31xx microcontroller families from NXP.
|
||
|
||
Note: There are LPC2000 devices which are not supported by the
|
||
LPC2000 driver: The LPC2888 is supported by the LPC288X
|
||
driver. The LPC29xx family is supported by the LPC2900
|
||
driver.
|
||
|
||
The LPC2000 driver defines two mandatory and two optional
|
||
parameters, which must appear in the following order:
|
||
|
||
* VARIANT ... required, may be 'lpc2000_v1' (older LPC21xx and
|
||
LPC22xx) 'lpc2000_v2' (LPC213x, LPC214x, LPC210[123], LPC23xx
|
||
and LPC24xx) 'lpc1700' (LPC175x and LPC176x and LPC177x/8x)
|
||
'lpc4300' - available also as 'lpc1800' alias (LPC18x[2357]
|
||
and LPC43x[2357]) 'lpc800' (LPC8xx) 'lpc1100' (LPC11(x)xx and
|
||
LPC13xx) 'lpc1500' (LPC15xx) 'lpc54100' (LPC541xx) 'lpc4000'
|
||
(LPC40xx) or 'auto' - automatically detects flash variant and
|
||
size for LPC11(x)00, LPC8xx, LPC13xx, LPC17xx, LPC40xx,
|
||
LPC8Nxx and NHS31xx
|
||
* CLOCK_KHZ ... the frequency, in kiloHertz, at which the core
|
||
is running
|
||
* 'calc_checksum' ... optional (but you probably want to
|
||
provide this!), telling the driver to calculate a valid
|
||
checksum for the exception vector table.
|
||
Note: If you don't provide 'calc_checksum' when you're
|
||
writing the vector table, the boot ROM will almost
|
||
certainly ignore your flash image. However, if you do
|
||
provide it, with most tool chains 'verify_image' will
|
||
fail.
|
||
* 'iap_entry' ... optional telling the driver to use a
|
||
different ROM IAP entry point.
|
||
|
||
LPC flashes don't require the chip and bus width to be specified.
|
||
|
||
flash bank $_FLASHNAME lpc2000 0x0 0x7d000 0 0 $_TARGETNAME \
|
||
lpc2000_v2 14765 calc_checksum
|
||
|
||
-- Command: lpc2000 part_id bank
|
||
Displays the four byte part identifier associated with the
|
||
specified flash BANK.
|
||
|
||
-- Flash Driver: lpc288x
|
||
The LPC2888 microcontroller from NXP needs slightly different flash
|
||
support from its lpc2000 siblings. The LPC288X driver defines one
|
||
mandatory parameter, the programming clock rate in Hz. LPC flashes
|
||
don't require the chip and bus width to be specified.
|
||
|
||
flash bank $_FLASHNAME lpc288x 0 0 0 0 $_TARGETNAME 12000000
|
||
|
||
-- Flash Driver: lpc2900
|
||
This driver supports the LPC29xx ARM968E based microcontroller
|
||
family from NXP.
|
||
|
||
The predefined parameters BASE, SIZE, CHIP_WIDTH and BUS_WIDTH of
|
||
the 'flash bank' command are ignored. Flash size and sector layout
|
||
are auto-configured by the driver. The driver has one additional
|
||
mandatory parameter: The CPU clock rate (in kHz) at the time the
|
||
flash operations will take place. Most of the time this will not
|
||
be the crystal frequency, but a higher PLL frequency. The
|
||
'reset-init' event handler in the board script is usually the place
|
||
where you start the PLL.
|
||
|
||
The driver rejects flashless devices (currently the LPC2930).
|
||
|
||
The EEPROM in LPC2900 devices is not mapped directly into the
|
||
address space. It must be handled much more like NAND flash
|
||
memory, and will therefore be handled by a separate
|
||
'lpc2900_eeprom' driver (not yet available).
|
||
|
||
Sector protection in terms of the LPC2900 is handled transparently.
|
||
Every time a sector needs to be erased or programmed, it is
|
||
automatically unprotected. What is shown as protection status in
|
||
the 'flash info' command, is actually the LPC2900 _sector
|
||
security_. This is a mechanism to prevent a sector from ever being
|
||
erased or programmed again. As this is an irreversible mechanism,
|
||
it is handled by a special command ('lpc2900 secure_sector'), and
|
||
not by the standard 'flash protect' command.
|
||
|
||
Example for a 125 MHz clock frequency:
|
||
flash bank $_FLASHNAME lpc2900 0 0 0 0 $_TARGETNAME 125000
|
||
|
||
Some 'lpc2900'-specific commands are defined. In the following
|
||
command list, the BANK parameter is the bank number as obtained by
|
||
the 'flash banks' command.
|
||
|
||
-- Command: lpc2900 signature bank
|
||
Calculates a 128-bit hash value, the _signature_, from the
|
||
whole flash content. This is a hardware feature of the flash
|
||
block, hence the calculation is very fast. You may use this
|
||
to verify the content of a programmed device against a known
|
||
signature. Example:
|
||
lpc2900 signature 0
|
||
signature: 0x5f40cdc8:0xc64e592e:0x10490f89:0x32a0f317
|
||
|
||
-- Command: lpc2900 read_custom bank filename
|
||
Reads the 912 bytes of customer information from the flash
|
||
index sector, and saves it to a file in binary format.
|
||
Example:
|
||
lpc2900 read_custom 0 /path_to/customer_info.bin
|
||
|
||
The index sector of the flash is a _write-only_ sector. It cannot
|
||
be erased! In order to guard against unintentional write access,
|
||
all following commands need to be preceded by a successful call to
|
||
the 'password' command:
|
||
|
||
-- Command: lpc2900 password bank password
|
||
You need to use this command right before each of the
|
||
following commands: 'lpc2900 write_custom', 'lpc2900
|
||
secure_sector', 'lpc2900 secure_jtag'.
|
||
|
||
The password string is fixed to "I_know_what_I_am_doing".
|
||
Example:
|
||
lpc2900 password 0 I_know_what_I_am_doing
|
||
Potentially dangerous operation allowed in next command!
|
||
|
||
-- Command: lpc2900 write_custom bank filename type
|
||
Writes the content of the file into the customer info space of
|
||
the flash index sector. The filetype can be specified with
|
||
the TYPE field. Possible values for TYPE are: BIN (binary),
|
||
IHEX (Intel hex format), ELF (ELF binary) or S19 (Motorola
|
||
S-records). The file must contain a single section, and the
|
||
contained data length must be exactly 912 bytes.
|
||
Attention: This cannot be reverted! Be careful!
|
||
Example:
|
||
lpc2900 write_custom 0 /path_to/customer_info.bin bin
|
||
|
||
-- Command: lpc2900 secure_sector bank first last
|
||
Secures the sector range from FIRST to LAST (including)
|
||
against further program and erase operations. The sector
|
||
security will be effective after the next power cycle.
|
||
Attention: This cannot be reverted! Be careful!
|
||
Secured sectors appear as _protected_ in the 'flash info'
|
||
command. Example:
|
||
lpc2900 secure_sector 0 1 1
|
||
flash info 0
|
||
#0 : lpc2900 at 0x20000000, size 0x000c0000, (...)
|
||
# 0: 0x00000000 (0x2000 8kB) not protected
|
||
# 1: 0x00002000 (0x2000 8kB) protected
|
||
# 2: 0x00004000 (0x2000 8kB) not protected
|
||
|
||
-- Command: lpc2900 secure_jtag bank
|
||
Irreversibly disable the JTAG port. The new JTAG security
|
||
setting will be effective after the next power cycle.
|
||
Attention: This cannot be reverted! Be careful!
|
||
Examples:
|
||
lpc2900 secure_jtag 0
|
||
|
||
-- Flash Driver: mdr
|
||
This drivers handles the integrated NOR flash on Milandr Cortex-M
|
||
based controllers. A known limitation is that the Info memory
|
||
can't be read or verified as it's not memory mapped.
|
||
|
||
flash bank <name> mdr <base> <size> \
|
||
0 0 <target#> TYPE PAGE_COUNT SEC_COUNT
|
||
|
||
* TYPE - 0 for main memory, 1 for info memory
|
||
* PAGE_COUNT - total number of pages
|
||
* SEC_COUNT - number of sector per page count
|
||
|
||
Example usage:
|
||
if { [info exists IMEMORY] && [string equal $IMEMORY true] } {
|
||
flash bank ${_CHIPNAME}_info.flash mdr 0x00000000 0x01000 \
|
||
0 0 $_TARGETNAME 1 1 4
|
||
} else {
|
||
flash bank $_CHIPNAME.flash mdr 0x00000000 0x20000 \
|
||
0 0 $_TARGETNAME 0 32 4
|
||
}
|
||
|
||
-- Flash Driver: msp432
|
||
All versions of the SimpleLink MSP432 microcontrollers from Texas
|
||
Instruments include internal flash. The msp432 flash driver
|
||
automatically recognizes the specific version's flash parameters
|
||
and autoconfigures itself. Main program flash starts at address 0.
|
||
The information flash region on MSP432P4 versions starts at address
|
||
0x200000.
|
||
|
||
flash bank $_FLASHNAME msp432 0 0 0 0 $_TARGETNAME
|
||
|
||
-- Command: msp432 mass_erase bank_id [main|all]
|
||
Performs a complete erase of flash. By default, 'mass_erase'
|
||
will erase only the main program flash.
|
||
|
||
On MSP432P4 versions, using 'mass_erase all' will erase both
|
||
the main program and information flash regions. To also erase
|
||
the BSL in information flash, the user must first use the
|
||
'bsl' command.
|
||
|
||
-- Command: msp432 bsl bank_id [unlock|lock]
|
||
On MSP432P4 versions, 'bsl' unlocks and locks the bootstrap
|
||
loader (BSL) region in information flash so that flash
|
||
commands can erase or write the BSL. Leave the BSL locked to
|
||
prevent accidentally corrupting the bootstrap loader.
|
||
|
||
To erase and program the BSL:
|
||
msp432 bsl unlock
|
||
flash erase_address 0x202000 0x2000
|
||
flash write_image bsl.bin 0x202000
|
||
msp432 bsl lock
|
||
|
||
-- Flash Driver: niietcm4
|
||
This drivers handles the integrated NOR flash on NIIET Cortex-M4
|
||
based controllers. Flash size and sector layout are
|
||
auto-configured by the driver. Main flash memory is called
|
||
"Bootflash" and has main region and info region. Info region is
|
||
NOT memory mapped by default, but it can replace first part of main
|
||
region if needed. Full erase, single and block writes are
|
||
supported for both main and info regions. There is additional not
|
||
memory mapped flash called "Userflash", which also have division
|
||
into regions: main and info. Purpose of userflash - to store
|
||
system and user settings. Driver has special commands to perform
|
||
operations with this memory.
|
||
|
||
flash bank $_FLASHNAME niietcm4 0 0 0 0 $_TARGETNAME
|
||
|
||
Some niietcm4-specific commands are defined:
|
||
|
||
-- Command: niietcm4 uflash_read_byte bank ('main'|'info') address
|
||
Read byte from main or info userflash region.
|
||
|
||
-- Command: niietcm4 uflash_write_byte bank ('main'|'info')
|
||
address value
|
||
Write byte to main or info userflash region.
|
||
|
||
-- Command: niietcm4 uflash_full_erase bank
|
||
Erase all userflash including info region.
|
||
|
||
-- Command: niietcm4 uflash_erase bank ('main'|'info')
|
||
first_sector last_sector
|
||
Erase sectors of main or info userflash region, starting at
|
||
sector first up to and including last.
|
||
|
||
-- Command: niietcm4 uflash_protect_check bank ('main'|'info')
|
||
Check sectors protect.
|
||
|
||
-- Command: niietcm4 uflash_protect bank ('main'|'info')
|
||
first_sector last_sector ('on'|'off')
|
||
Protect sectors of main or info userflash region, starting at
|
||
sector first up to and including last.
|
||
|
||
-- Command: niietcm4 bflash_info_remap bank ('on'|'off')
|
||
Enable remapping bootflash info region to 0x00000000 (or
|
||
0x40000000 if external memory boot used).
|
||
|
||
-- Command: niietcm4 extmem_cfg bank
|
||
('gpioa'|'gpiob'|'gpioc'|'gpiod'|'gpioe'|'gpiof'|'gpiog'|'gpioh')
|
||
pin_num ('func1'|'func3')
|
||
Configure external memory interface for boot.
|
||
|
||
-- Command: niietcm4 service_mode_erase bank
|
||
Perform emergency erase of all flash (bootflash and
|
||
userflash).
|
||
|
||
-- Command: niietcm4 driver_info bank
|
||
Show information about flash driver.
|
||
|
||
-- Flash Driver: npcx
|
||
All versions of the NPCX microcontroller families from Nuvoton
|
||
include internal flash. The NPCX flash driver supports the NPCX
|
||
family of devices. The driver automatically recognizes the
|
||
specific version's flash parameters and autoconfigures itself. The
|
||
flash bank starts at address 0x64000000.
|
||
|
||
flash bank $_FLASHNAME npcx 0x64000000 0 0 0 $_TARGETNAME
|
||
|
||
-- Flash Driver: nrf5
|
||
All members of the nRF51 microcontroller families from Nordic
|
||
Semiconductor include internal flash and use ARM Cortex-M0 core.
|
||
nRF52 family powered by ARM Cortex-M4 or M4F core is supported too.
|
||
nRF52832 is fully supported including BPROT flash protection
|
||
scheme. nRF52833 and nRF52840 devices are supported with the
|
||
exception of security extensions (flash access control list - ACL).
|
||
|
||
flash bank $_FLASHNAME nrf5 0 0x00000000 0 0 $_TARGETNAME
|
||
|
||
Some nrf5-specific commands are defined:
|
||
|
||
-- Command: nrf5 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.
|
||
|
||
-- Command: nrf5 info
|
||
Decodes and shows information from FICR and UICR registers.
|
||
|
||
-- Flash Driver: ocl
|
||
This driver is an implementation of the "on chip flash loader"
|
||
protocol proposed by Pavel Chromy.
|
||
|
||
It is a minimalistic command-response protocol intended to be used
|
||
over a DCC when communicating with an internal or external flash
|
||
loader running from RAM. An example implementation for AT91SAM7x is
|
||
available in 'contrib/loaders/flash/at91sam7x/'.
|
||
|
||
flash bank $_FLASHNAME ocl 0 0 0 0 $_TARGETNAME
|
||
|
||
-- Flash Driver: pic32mx
|
||
The PIC32MX microcontrollers are based on the MIPS 4K cores, and
|
||
integrate flash memory.
|
||
|
||
flash bank $_FLASHNAME pix32mx 0x1fc00000 0 0 0 $_TARGETNAME
|
||
flash bank $_FLASHNAME pix32mx 0x1d000000 0 0 0 $_TARGETNAME
|
||
|
||
Some pic32mx-specific commands are defined:
|
||
-- Command: pic32mx pgm_word address value bank
|
||
Programs the specified 32-bit VALUE at the given ADDRESS in
|
||
the specified chip BANK.
|
||
-- Command: pic32mx unlock bank
|
||
Unlock and erase specified chip BANK. This will remove any
|
||
Code Protection.
|
||
|
||
-- Flash Driver: psoc4
|
||
All members of the PSoC 41xx/42xx microcontroller family from
|
||
Cypress include internal flash and use ARM Cortex-M0 cores. The
|
||
driver automatically recognizes a number of these chips using the
|
||
chip identification register, and autoconfigures itself.
|
||
|
||
Note: Erased internal flash reads as 00. System ROM of PSoC 4 does
|
||
not implement erase of a flash sector.
|
||
|
||
flash bank $_FLASHNAME psoc4 0 0 0 0 $_TARGETNAME
|
||
|
||
psoc4-specific commands
|
||
-- Command: psoc4 flash_autoerase num (on|off)
|
||
Enables or disables autoerase mode for a flash bank.
|
||
|
||
If flash_autoerase is off, use mass_erase before flash
|
||
programming. Flash erase command fails if region to erase is
|
||
not whole flash memory.
|
||
|
||
If flash_autoerase is on, a sector is both erased and
|
||
programmed in one system ROM call. Flash erase command is
|
||
ignored. This mode is suitable for gdb load.
|
||
|
||
The NUM parameter is a value shown by 'flash banks'.
|
||
|
||
-- Command: psoc4 mass_erase num
|
||
Erases the contents of the flash memory, protection and
|
||
security lock.
|
||
|
||
The NUM parameter is a value shown by 'flash banks'.
|
||
|
||
-- Flash Driver: psoc5lp
|
||
All members of the PSoC 5LP microcontroller family from Cypress
|
||
include internal program flash and use ARM Cortex-M3 cores. The
|
||
driver probes for a number of these chips and autoconfigures
|
||
itself, apart from the base address.
|
||
|
||
flash bank $_FLASHNAME psoc5lp 0x00000000 0 0 0 $_TARGETNAME
|
||
|
||
Note: PSoC 5LP chips can be configured to have ECC enabled or
|
||
disabled.
|
||
Attention: If flash operations are performed in ECC-disabled
|
||
mode, they will also affect the ECC flash region. Erasing a
|
||
16k flash sector in the 0x00000000 area will then also erase
|
||
the corresponding 2k data bytes in the 0x48000000 area.
|
||
Writing to the ECC data bytes in ECC-disabled mode is not
|
||
implemented.
|
||
|
||
Commands defined in the PSOC5LP driver:
|
||
|
||
-- Command: psoc5lp mass_erase
|
||
Erases all flash data and ECC/configuration bytes, all flash
|
||
protection rows, and all row latches in all flash arrays on
|
||
the device.
|
||
|
||
-- Flash Driver: psoc5lp_eeprom
|
||
All members of the PSoC 5LP microcontroller family from Cypress
|
||
include internal EEPROM and use ARM Cortex-M3 cores. The driver
|
||
probes for a number of these chips and autoconfigures itself, apart
|
||
from the base address.
|
||
|
||
flash bank $_CHIPNAME.eeprom psoc5lp_eeprom 0x40008000 0 0 0 \
|
||
$_TARGETNAME
|
||
|
||
-- Flash Driver: psoc5lp_nvl
|
||
All members of the PSoC 5LP microcontroller family from Cypress
|
||
include internal Nonvolatile Latches and use ARM Cortex-M3 cores.
|
||
The driver probes for a number of these chips and autoconfigures
|
||
itself.
|
||
|
||
flash bank $_CHIPNAME.nvl psoc5lp_nvl 0 0 0 0 $_TARGETNAME
|
||
|
||
PSoC 5LP chips have multiple NV Latches:
|
||
|
||
* Device Configuration NV Latch - 4 bytes
|
||
* Write Once (WO) NV Latch - 4 bytes
|
||
|
||
Note: This driver only implements the Device Configuration NVL.
|
||
|
||
The PSOC5LP driver reads the ECC mode from Device Configuration
|
||
NVL.
|
||
Attention: Switching ECC mode via write to Device
|
||
Configuration NVL will require a reset after successful write.
|
||
|
||
-- Flash Driver: psoc6
|
||
Supports PSoC6 (CY8C6xxx) family of Cypress microcontrollers.
|
||
PSoC6 is a dual-core device with CM0+ and CM4 cores. Both cores
|
||
share the same Flash/RAM/MMIO address space.
|
||
|
||
Flash in PSoC6 is split into three regions:
|
||
* Main Flash - this is the main storage for user application.
|
||
Total size varies among devices, sector size: 256 kBytes, row
|
||
size: 512 bytes. Supports erase operation on individual rows.
|
||
* Work Flash - intended to be used as storage for user data
|
||
(e.g. EEPROM emulation). Total size: 32 KBytes, sector size:
|
||
32 KBytes, row size: 512 bytes.
|
||
* Supervisory Flash - special region which contains
|
||
device-specific service data. This region does not support
|
||
erase operation. Only few rows can be programmed by the user,
|
||
most of the rows are read only. Programming operation will
|
||
erase row automatically.
|
||
|
||
All three flash regions are supported by the driver. Flash
|
||
geometry is detected automatically by parsing data in
|
||
SPCIF_GEOMETRY register.
|
||
|
||
PSoC6 is equipped with NOR Flash so erased Flash reads as 0x00.
|
||
|
||
flash bank main_flash_cm0 psoc6 0x10000000 0 0 0 \
|
||
${TARGET}.cm0
|
||
flash bank work_flash_cm0 psoc6 0x14000000 0 0 0 \
|
||
${TARGET}.cm0
|
||
flash bank super_flash_user_cm0 psoc6 0x16000800 0 0 0 \
|
||
${TARGET}.cm0
|
||
flash bank super_flash_nar_cm0 psoc6 0x16001A00 0 0 0 \
|
||
${TARGET}.cm0
|
||
flash bank super_flash_key_cm0 psoc6 0x16005A00 0 0 0 \
|
||
${TARGET}.cm0
|
||
flash bank super_flash_toc2_cm0 psoc6 0x16007C00 0 0 0 \
|
||
${TARGET}.cm0
|
||
|
||
flash bank main_flash_cm4 psoc6 0x10000000 0 0 0 \
|
||
${TARGET}.cm4
|
||
flash bank work_flash_cm4 psoc6 0x14000000 0 0 0 \
|
||
${TARGET}.cm4
|
||
flash bank super_flash_user_cm4 psoc6 0x16000800 0 0 0 \
|
||
${TARGET}.cm4
|
||
flash bank super_flash_nar_cm4 psoc6 0x16001A00 0 0 0 \
|
||
${TARGET}.cm4
|
||
flash bank super_flash_key_cm4 psoc6 0x16005A00 0 0 0 \
|
||
${TARGET}.cm4
|
||
flash bank super_flash_toc2_cm4 psoc6 0x16007C00 0 0 0 \
|
||
${TARGET}.cm4
|
||
|
||
psoc6-specific commands
|
||
-- Command: psoc6 reset_halt
|
||
Command can be used to simulate broken Vector Catch from
|
||
gdbinit or tcl scripts. When invoked for CM0+ target, it will
|
||
set break point at application entry point and issue
|
||
SYSRESETREQ. This will reset both cores and all peripherals.
|
||
CM0+ will reset CM4 during boot anyway so this is safe. On
|
||
CM4 target, VECTRESET is used instead of SYSRESETREQ to avoid
|
||
unwanted reset of CM0+;
|
||
|
||
-- Command: psoc6 mass_erase num
|
||
Erases the contents given flash bank. The NUM parameter is a
|
||
value shown by 'flash banks'. Note: only Main and Work flash
|
||
regions support Erase operation.
|
||
|
||
-- Flash Driver: rp2040
|
||
Supports RP2040 "Raspberry Pi Pico" microcontroller. RP2040 is a
|
||
dual-core device with two CM0+ cores. Both cores share the same
|
||
Flash/RAM/MMIO address space. Non-volatile storage is achieved
|
||
with an external QSPI flash; a Boot ROM provides helper functions.
|
||
|
||
flash bank $_FLASHNAME rp2040_flash $_FLASHBASE $_FLASHSIZE 1 32 $_TARGETNAME
|
||
|
||
-- Flash Driver: sim3x
|
||
All members of the SiM3 microcontroller family from Silicon
|
||
Laboratories include internal flash and use ARM Cortex-M3 cores.
|
||
It supports both JTAG and SWD interface. The SIM3X driver tries to
|
||
probe the device to auto detect the MCU. If this fails, it will use
|
||
the SIZE parameter as the size of flash bank.
|
||
|
||
flash bank $_FLASHNAME sim3x 0 $_CPUROMSIZE 0 0 $_TARGETNAME
|
||
|
||
There are 2 commands defined in the SIM3X driver:
|
||
|
||
-- Command: sim3x mass_erase
|
||
Erases the complete flash. This is used to unlock the flash.
|
||
And this command is only possible when using the SWD
|
||
interface.
|
||
|
||
-- Command: sim3x lock
|
||
Lock the flash. To unlock use the 'sim3x mass_erase' command.
|
||
|
||
-- Flash Driver: stellaris
|
||
All members of the Stellaris LM3Sxxx, LM4x and Tiva C
|
||
microcontroller families from Texas Instruments include internal
|
||
flash. The driver automatically recognizes a number of these chips
|
||
using the chip identification register, and autoconfigures itself.
|
||
|
||
flash bank $_FLASHNAME stellaris 0 0 0 0 $_TARGETNAME
|
||
|
||
-- Command: stellaris recover
|
||
Performs the _Recovering a "Locked" Device_ procedure to
|
||
restore the flash and its associated nonvolatile registers to
|
||
their factory default values (erased). This is the only way
|
||
to remove flash protection or re-enable debugging if that
|
||
capability has been disabled.
|
||
|
||
Note that the final "power cycle the chip" step in this
|
||
procedure must be performed by hand, since OpenOCD can't do
|
||
it.
|
||
Warning: if more than one Stellaris chip is connected,
|
||
the procedure is applied to all of them.
|
||
|
||
-- Flash Driver: stm32f1x
|
||
All members of the STM32F0, STM32F1 and STM32F3 microcontroller
|
||
families from STMicroelectronics and all members of the GD32F1x0,
|
||
GD32F3x0 and GD32E23x microcontroller families from GigaDevice
|
||
include internal flash and use ARM Cortex-M0/M3/M4/M23 cores. The
|
||
driver automatically recognizes a number of these chips using the
|
||
chip identification register, and autoconfigures itself.
|
||
|
||
flash bank $_FLASHNAME stm32f1x 0 0 0 0 $_TARGETNAME
|
||
|
||
Note that some devices have been found that have a flash size
|
||
register that contains an invalid value, to workaround this issue
|
||
you can override the probed value used by the flash driver.
|
||
|
||
flash bank $_FLASHNAME stm32f1x 0 0x20000 0 0 $_TARGETNAME
|
||
|
||
If you have a target with dual flash banks then define the second
|
||
bank as per the following example.
|
||
flash bank $_FLASHNAME stm32f1x 0x08080000 0 0 0 $_TARGETNAME
|
||
|
||
Some stm32f1x-specific commands are defined:
|
||
|
||
-- Command: stm32f1x lock num
|
||
Locks the entire stm32 device against reading. The NUM
|
||
parameter is a value shown by 'flash banks'.
|
||
|
||
-- Command: stm32f1x unlock num
|
||
Unlocks the entire stm32 device for reading. This command
|
||
will cause a mass erase of the entire stm32 device if
|
||
previously locked. The NUM parameter is a value shown by
|
||
'flash banks'.
|
||
|
||
-- Command: stm32f1x mass_erase num
|
||
Mass erases the entire stm32 device. The NUM parameter is a
|
||
value shown by 'flash banks'.
|
||
|
||
-- Command: stm32f1x options_read num
|
||
Reads and displays active stm32 option bytes loaded during POR
|
||
or upon executing the 'stm32f1x options_load' command. The
|
||
NUM parameter is a value shown by 'flash banks'.
|
||
|
||
-- Command: stm32f1x options_write num ('SWWDG'|'HWWDG')
|
||
('RSTSTNDBY'|'NORSTSTNDBY') ('RSTSTOP'|'NORSTSTOP')
|
||
('USEROPT' user_data)
|
||
Writes the stm32 option byte with the specified values. The
|
||
NUM parameter is a value shown by 'flash banks'. The
|
||
USER_DATA parameter is content of higher 16 bits of the option
|
||
byte register (Data0 and Data1 as one 16bit number).
|
||
|
||
-- Command: stm32f1x options_load num
|
||
Generates a special kind of reset to re-load the stm32 option
|
||
bytes written by the 'stm32f1x options_write' or 'flash
|
||
protect' commands without having to power cycle the target.
|
||
Not applicable to stm32f1x devices. The NUM parameter is a
|
||
value shown by 'flash banks'.
|
||
|
||
-- Flash Driver: stm32f2x
|
||
All members of the STM32F2, STM32F4 and STM32F7 microcontroller
|
||
families from STMicroelectronics include internal flash and use ARM
|
||
Cortex-M3/M4/M7 cores. The driver automatically recognizes a
|
||
number of these chips using the chip identification register, and
|
||
autoconfigures itself.
|
||
|
||
flash bank $_FLASHNAME stm32f2x 0 0 0 0 $_TARGETNAME
|
||
|
||
If you use OTP (One-Time Programmable) memory define it as a second
|
||
bank as per the following example.
|
||
flash bank $_FLASHNAME stm32f2x 0x1FFF7800 0 0 0 $_TARGETNAME
|
||
|
||
-- Command: stm32f2x otp num ('enable'|'disable'|'show')
|
||
Enables or disables OTP write commands for bank NUM. The NUM
|
||
parameter is a value shown by 'flash banks'.
|
||
|
||
Note that some devices have been found that have a flash size
|
||
register that contains an invalid value, to workaround this issue
|
||
you can override the probed value used by the flash driver.
|
||
|
||
flash bank $_FLASHNAME stm32f2x 0 0x20000 0 0 $_TARGETNAME
|
||
|
||
Some stm32f2x-specific commands are defined:
|
||
|
||
-- Command: stm32f2x lock num
|
||
Locks the entire stm32 device. The NUM parameter is a value
|
||
shown by 'flash banks'.
|
||
|
||
-- Command: stm32f2x unlock num
|
||
Unlocks the entire stm32 device. The NUM parameter is a value
|
||
shown by 'flash banks'.
|
||
|
||
-- Command: stm32f2x mass_erase num
|
||
Mass erases the entire stm32f2x device. The NUM parameter is
|
||
a value shown by 'flash banks'.
|
||
|
||
-- Command: stm32f2x options_read num
|
||
Reads and displays user options and (where implemented)
|
||
boot_addr0, boot_addr1, optcr2. The NUM parameter is a value
|
||
shown by 'flash banks'.
|
||
|
||
-- Command: stm32f2x options_write num user_options boot_addr0
|
||
boot_addr1
|
||
Writes user options and (where implemented) boot_addr0 and
|
||
boot_addr1 in raw format. Warning: The meaning of the various
|
||
bits depends on the device, always check datasheet! The NUM
|
||
parameter is a value shown by 'flash banks', USER_OPTIONS a 12
|
||
bit value, consisting of bits 31-28 and 7-0 of FLASH_OPTCR,
|
||
BOOT_ADDR0 and BOOT_ADDR1 two halfwords (of FLASH_OPTCR1).
|
||
|
||
-- Command: stm32f2x optcr2_write num optcr2
|
||
Writes FLASH_OPTCR2 options. Warning: Clearing PCROPi bits
|
||
requires a full mass erase! The NUM parameter is a value
|
||
shown by 'flash banks', OPTCR2 a 32-bit word.
|
||
|
||
-- Flash Driver: stm32h7x
|
||
All members of the STM32H7 microcontroller families from
|
||
STMicroelectronics include internal flash and use ARM Cortex-M7
|
||
core. The driver automatically recognizes a number of these chips
|
||
using the chip identification register, and autoconfigures itself.
|
||
|
||
flash bank $_FLASHNAME stm32h7x 0 0 0 0 $_TARGETNAME
|
||
|
||
Note that some devices have been found that have a flash size
|
||
register that contains an invalid value, to workaround this issue
|
||
you can override the probed value used by the flash driver.
|
||
|
||
flash bank $_FLASHNAME stm32h7x 0 0x20000 0 0 $_TARGETNAME
|
||
|
||
Some stm32h7x-specific commands are defined:
|
||
|
||
-- Command: stm32h7x lock num
|
||
Locks the entire stm32 device. The NUM parameter is a value
|
||
shown by 'flash banks'.
|
||
|
||
-- Command: stm32h7x unlock num
|
||
Unlocks the entire stm32 device. The NUM parameter is a value
|
||
shown by 'flash banks'.
|
||
|
||
-- Command: stm32h7x mass_erase num
|
||
Mass erases the entire stm32h7x device. The NUM parameter is
|
||
a value shown by 'flash banks'.
|
||
|
||
-- Command: stm32h7x option_read num reg_offset
|
||
Reads an option byte register from the stm32h7x device. The
|
||
NUM parameter is a value shown by 'flash banks', REG_OFFSET is
|
||
the register offset of the option byte to read from the used
|
||
bank registers' base. For example: in STM32H74x/H75x the bank
|
||
1 registers' base is 0x52002000 and 0x52002100 for bank 2.
|
||
|
||
Example usage:
|
||
# read OPTSR_CUR
|
||
stm32h7x option_read 0 0x1c
|
||
# read WPSN_CUR1R
|
||
stm32h7x option_read 0 0x38
|
||
# read WPSN_CUR2R
|
||
stm32h7x option_read 1 0x38
|
||
|
||
-- Command: stm32h7x option_write num reg_offset value [reg_mask]
|
||
Writes an option byte register of the stm32h7x device. The
|
||
NUM parameter is a value shown by 'flash banks', REG_OFFSET is
|
||
the register offset of the option byte to write from the used
|
||
bank register base, and REG_MASK is the mask to apply when
|
||
writing the register (only bits with a '1' will be touched).
|
||
|
||
Example usage:
|
||
# swap bank 1 and bank 2 in dual bank devices
|
||
# by setting SWAP_BANK_OPT bit in OPTSR_PRG
|
||
stm32h7x option_write 0 0x20 0x8000000 0x8000000
|
||
|
||
-- Flash Driver: stm32lx
|
||
All members of the STM32L0 and STM32L1 microcontroller families
|
||
from STMicroelectronics include internal flash and use ARM
|
||
Cortex-M3 and Cortex-M0+ cores. The driver automatically
|
||
recognizes a number of these chips using the chip identification
|
||
register, and autoconfigures itself.
|
||
|
||
flash bank $_FLASHNAME stm32lx 0 0 0 0 $_TARGETNAME
|
||
|
||
Note that some devices have been found that have a flash size
|
||
register that contains an invalid value, to workaround this issue
|
||
you can override the probed value used by the flash driver. If you
|
||
use 0 as the bank base address, it tells the driver to autodetect
|
||
the bank location assuming you're configuring the second bank.
|
||
|
||
flash bank $_FLASHNAME stm32lx 0x08000000 0x20000 0 0 $_TARGETNAME
|
||
|
||
Some stm32lx-specific commands are defined:
|
||
|
||
-- Command: stm32lx lock num
|
||
Locks the entire stm32 device. The NUM parameter is a value
|
||
shown by 'flash banks'.
|
||
|
||
-- Command: stm32lx unlock num
|
||
Unlocks the entire stm32 device. The NUM parameter is a value
|
||
shown by 'flash banks'.
|
||
|
||
-- Command: stm32lx mass_erase num
|
||
Mass erases the entire stm32lx device (all flash banks and
|
||
EEPROM data). This is the only way to unlock a protected
|
||
flash (unless RDP Level is 2 which can't be unlocked at all).
|
||
The NUM parameter is a value shown by 'flash banks'.
|
||
|
||
-- Flash Driver: stm32l4x
|
||
All members of the STM32 G0, G4, L4, L4+, L5, U5, WB and WL
|
||
microcontroller families from STMicroelectronics include internal
|
||
flash and use ARM Cortex-M0+, M4 and M33 cores. The driver
|
||
automatically recognizes a number of these chips using the chip
|
||
identification register, and autoconfigures itself.
|
||
|
||
flash bank $_FLASHNAME stm32l4x 0 0 0 0 $_TARGETNAME
|
||
|
||
If you use OTP (One-Time Programmable) memory define it as a second
|
||
bank as per the following example.
|
||
flash bank $_FLASHNAME stm32l4x 0x1FFF7000 0 0 0 $_TARGETNAME
|
||
|
||
-- Command: stm32l4x otp num ('enable'|'disable'|'show')
|
||
Enables or disables OTP write commands for bank NUM. The NUM
|
||
parameter is a value shown by 'flash banks'.
|
||
|
||
Note that some devices have been found that have a flash size
|
||
register that contains an invalid value, to workaround this issue
|
||
you can override the probed value used by the flash driver.
|
||
However, specifying a wrong value might lead to a completely wrong
|
||
flash layout, so this feature must be used carefully.
|
||
|
||
flash bank $_FLASHNAME stm32l4x 0x08000000 0x40000 0 0 $_TARGETNAME
|
||
|
||
Some stm32l4x-specific commands are defined:
|
||
|
||
-- Command: stm32l4x lock num
|
||
Locks the entire stm32 device. The NUM parameter is a value
|
||
shown by 'flash banks'.
|
||
|
||
_Note:_ To apply the protection change immediately, use
|
||
'stm32l4x option_load'.
|
||
|
||
-- Command: stm32l4x unlock num
|
||
Unlocks the entire stm32 device. The NUM parameter is a value
|
||
shown by 'flash banks'.
|
||
|
||
_Note:_ To apply the protection change immediately, use
|
||
'stm32l4x option_load'.
|
||
|
||
-- Command: stm32l4x mass_erase num
|
||
Mass erases the entire stm32l4x device. The NUM parameter is
|
||
a value shown by 'flash banks'.
|
||
|
||
-- Command: stm32l4x option_read num reg_offset
|
||
Reads an option byte register from the stm32l4x device. The
|
||
NUM parameter is a value shown by 'flash banks', REG_OFFSET is
|
||
the register offset of the Option byte to read.
|
||
|
||
For example to read the FLASH_OPTR register:
|
||
stm32l4x option_read 0 0x20
|
||
# Option Register (for STM32L4x): <0x40022020> = 0xffeff8aa
|
||
# Option Register (for STM32WBx): <0x58004020> = ...
|
||
# The correct flash base address will be used automatically
|
||
|
||
The above example will read out the FLASH_OPTR register which
|
||
contains the RDP option byte, Watchdog configuration, BOR
|
||
level etc.
|
||
|
||
-- Command: stm32l4x option_write num reg_offset reg_mask
|
||
Write an option byte register of the stm32l4x device. The NUM
|
||
parameter is a value shown by 'flash banks', REG_OFFSET is the
|
||
register offset of the Option byte to write, and REG_MASK is
|
||
the mask to apply when writing the register (only bits with a
|
||
'1' will be touched).
|
||
|
||
_Note:_ To apply the option bytes change immediately, use
|
||
'stm32l4x option_load'.
|
||
|
||
For example to write the WRP1AR option bytes:
|
||
stm32l4x option_write 0 0x28 0x00FF0000 0x00FF00FF
|
||
|
||
The above example will write the WRP1AR option register
|
||
configuring the Write protection Area A for bank 1. The above
|
||
example set WRP1AR_END=255, WRP1AR_START=0. This will
|
||
effectively write protect all sectors in flash bank 1.
|
||
|
||
-- Command: stm32l4x wrp_info num [device_bank]
|
||
List the protected areas using WRP. The NUM parameter is a
|
||
value shown by 'flash banks'. DEVICE_BANK parameter is
|
||
optional, possible values 'bank1' or 'bank2', if not
|
||
specified, the command will display the whole flash protected
|
||
areas.
|
||
|
||
Note: DEVICE_BANK is different from banks created using 'flash
|
||
bank'. Devices supported in this flash driver, can have main
|
||
flash memory organized in single or dual-banks mode. Thus the
|
||
usage of DEVICE_BANK is meaningful only in dual-bank mode, to
|
||
get write protected areas in a specific DEVICE_BANK
|
||
|
||
-- Command: stm32l4x option_load num
|
||
Forces a re-load of the option byte registers. Will cause a
|
||
system reset of the device. The NUM parameter is a value
|
||
shown by 'flash banks'.
|
||
|
||
-- Command: stm32l4x trustzone num ['enable' | 'disable']
|
||
Enables or disables Global TrustZone Security, using the TZEN
|
||
option bit. If neither 'enabled' nor 'disable' are specified,
|
||
the command will display the TrustZone status. _Note:_ This
|
||
command works only with devices with TrustZone, eg. STM32L5.
|
||
_Note:_ This command will perform an OBL_Launch after
|
||
modifying the TZEN.
|
||
|
||
-- Flash Driver: str7x
|
||
All members of the STR7 microcontroller family from
|
||
STMicroelectronics include internal flash and use ARM7TDMI cores.
|
||
The STR7X driver defines one mandatory parameter, VARIANT, which is
|
||
either 'STR71x', 'STR73x' or 'STR75x'.
|
||
|
||
flash bank $_FLASHNAME str7x \
|
||
0x40000000 0x00040000 0 0 $_TARGETNAME STR71x
|
||
|
||
-- Command: str7x disable_jtag bank
|
||
Activate the Debug/Readout protection mechanism for the
|
||
specified flash bank.
|
||
|
||
-- Flash Driver: str9x
|
||
Most members of the STR9 microcontroller family from
|
||
STMicroelectronics include internal flash and use ARM966E cores.
|
||
The str9 needs the flash controller to be configured using the
|
||
'str9x flash_config' command prior to Flash programming.
|
||
|
||
flash bank $_FLASHNAME str9x 0x40000000 0x00040000 0 0 $_TARGETNAME
|
||
str9x flash_config 0 4 2 0 0x80000
|
||
|
||
-- Command: str9x flash_config num bbsr nbbsr bbadr nbbadr
|
||
Configures the str9 flash controller. The NUM parameter is a
|
||
value shown by 'flash banks'.
|
||
|
||
* BBSR - Boot Bank Size register
|
||
* NBBSR - Non Boot Bank Size register
|
||
* BBADR - Boot Bank Start Address register
|
||
* NBBADR - Boot Bank Start Address register
|
||
|
||
-- Flash Driver: str9xpec
|
||
|
||
Only use this driver for locking/unlocking the device or
|
||
configuring the option bytes. Use the standard str9 driver for
|
||
programming. Before using the flash commands the turbo mode must
|
||
be enabled using the 'str9xpec enable_turbo' command.
|
||
|
||
Here is some background info to help you better understand how this
|
||
driver works. OpenOCD has two flash drivers for the str9:
|
||
1. Standard driver 'str9x' programmed via the str9 core.
|
||
Normally used for flash programming as it is faster than the
|
||
'str9xpec' driver.
|
||
2. Direct programming 'str9xpec' using the flash controller.
|
||
This is an ISC compliant (IEEE 1532) tap connected in series
|
||
with the str9 core. The str9 core does not need to be running
|
||
to program using this flash driver. Typical use for this
|
||
driver is locking/unlocking the target and programming the
|
||
option bytes.
|
||
|
||
Before we run any commands using the 'str9xpec' driver we must
|
||
first disable the str9 core. This example assumes the 'str9xpec'
|
||
driver has been configured for flash bank 0.
|
||
# assert srst, we do not want core running
|
||
# while accessing str9xpec flash driver
|
||
adapter assert srst
|
||
# turn off target polling
|
||
poll off
|
||
# disable str9 core
|
||
str9xpec enable_turbo 0
|
||
# read option bytes
|
||
str9xpec options_read 0
|
||
# re-enable str9 core
|
||
str9xpec disable_turbo 0
|
||
poll on
|
||
reset halt
|
||
The above example will read the str9 option bytes. When performing
|
||
a unlock remember that you will not be able to halt the str9 - it
|
||
has been locked. Halting the core is not required for the
|
||
'str9xpec' driver as mentioned above, just issue the commands above
|
||
manually or from a telnet prompt.
|
||
|
||
Several str9xpec-specific commands are defined:
|
||
|
||
-- Command: str9xpec disable_turbo num
|
||
Restore the str9 into JTAG chain.
|
||
|
||
-- Command: str9xpec enable_turbo num
|
||
Enable turbo mode, will simply remove the str9 from the chain
|
||
and talk directly to the embedded flash controller.
|
||
|
||
-- Command: str9xpec lock num
|
||
Lock str9 device. The str9 will only respond to an unlock
|
||
command that will erase the device.
|
||
|
||
-- Command: str9xpec part_id num
|
||
Prints the part identifier for bank NUM.
|
||
|
||
-- Command: str9xpec options_cmap num ('bank0'|'bank1')
|
||
Configure str9 boot bank.
|
||
|
||
-- Command: str9xpec options_lvdsel num ('vdd'|'vdd_vddq')
|
||
Configure str9 lvd source.
|
||
|
||
-- Command: str9xpec options_lvdthd num ('2.4v'|'2.7v')
|
||
Configure str9 lvd threshold.
|
||
|
||
-- Command: str9xpec options_lvdwarn bank ('vdd'|'vdd_vddq')
|
||
Configure str9 lvd reset warning source.
|
||
|
||
-- Command: str9xpec options_read num
|
||
Read str9 option bytes.
|
||
|
||
-- Command: str9xpec options_write num
|
||
Write str9 option bytes.
|
||
|
||
-- Command: str9xpec unlock num
|
||
unlock str9 device.
|
||
|
||
-- Flash Driver: swm050
|
||
All members of the swm050 microcontroller family from Foshan Synwit
|
||
Tech.
|
||
|
||
flash bank $_FLASHNAME swm050 0x0 0x2000 0 0 $_TARGETNAME
|
||
|
||
One swm050-specific command is defined:
|
||
|
||
-- Command: swm050 mass_erase bank_id
|
||
Erases the entire flash bank.
|
||
|
||
-- Flash Driver: tms470
|
||
Most members of the TMS470 microcontroller family from Texas
|
||
Instruments include internal flash and use ARM7TDMI cores. This
|
||
driver doesn't require the chip and bus width to be specified.
|
||
|
||
Some tms470-specific commands are defined:
|
||
|
||
-- Command: tms470 flash_keyset key0 key1 key2 key3
|
||
Saves programming keys in a register, to enable flash erase
|
||
and write commands.
|
||
|
||
-- Command: tms470 osc_megahertz clock_mhz
|
||
Reports the clock speed, which is used to calculate timings.
|
||
|
||
-- Command: tms470 plldis (0|1)
|
||
Disables (1) or enables (0) use of the PLL to speed up the
|
||
flash clock.
|
||
|
||
-- Flash Driver: w600
|
||
W60x series Wi-Fi SoC from WinnerMicro are designed with ARM
|
||
Cortex-M3 and have 1M Byte QFLASH inside. The W600 driver uses the
|
||
TARGET parameter to select the correct bank config.
|
||
|
||
flash bank $_FLASHNAME w600 0x08000000 0 0 0 $_TARGETNAMEs
|
||
|
||
-- Flash Driver: xmc1xxx
|
||
All members of the XMC1xxx microcontroller family from Infineon.
|
||
This driver does not require the chip and bus width to be
|
||
specified.
|
||
|
||
-- Flash Driver: xmc4xxx
|
||
All members of the XMC4xxx microcontroller family from Infineon.
|
||
This driver does not require the chip and bus width to be
|
||
specified.
|
||
|
||
Some xmc4xxx-specific commands are defined:
|
||
|
||
-- Command: xmc4xxx flash_password bank_id passwd1 passwd2
|
||
Saves flash protection passwords which are used to lock the
|
||
user flash
|
||
|
||
-- Command: xmc4xxx flash_unprotect bank_id user_level[0-1]
|
||
Removes Flash write protection from the selected user bank
|
||
|
||
12.6 NAND Flash Commands
|
||
========================
|
||
|
||
Compared to NOR or SPI flash, NAND devices are inexpensive and high
|
||
density. Today's NAND chips, and multi-chip modules, commonly hold
|
||
multiple GigaBytes of data.
|
||
|
||
NAND chips consist of a number of "erase blocks" of a given size (such
|
||
as 128 KBytes), each of which is divided into a number of pages (of
|
||
perhaps 512 or 2048 bytes each). Each page of a NAND flash has an "out
|
||
of band" (OOB) area to hold Error Correcting Code (ECC) and other
|
||
metadata, usually 16 bytes of OOB for every 512 bytes of page data.
|
||
|
||
One key characteristic of NAND flash is that its error rate is higher
|
||
than that of NOR flash. In normal operation, that ECC is used to
|
||
correct and detect errors. However, NAND blocks can also wear out and
|
||
become unusable; those blocks are then marked "bad". NAND chips are
|
||
even shipped from the manufacturer with a few bad blocks. The highest
|
||
density chips use a technology (MLC) that wears out more quickly, so ECC
|
||
support is increasingly important as a way to detect blocks that have
|
||
begun to fail, and help to preserve data integrity with techniques such
|
||
as wear leveling.
|
||
|
||
Software is used to manage the ECC. Some controllers don't support ECC
|
||
directly; in those cases, software ECC is used. Other controllers speed
|
||
up the ECC calculations with hardware. Single-bit error correction
|
||
hardware is routine. Controllers geared for newer MLC chips may correct
|
||
4 or more errors for every 512 bytes of data.
|
||
|
||
You will need to make sure that any data you write using OpenOCD
|
||
includes the appropriate kind of ECC. For example, that may mean passing
|
||
the 'oob_softecc' flag when writing NAND data, or ensuring that the
|
||
correct hardware ECC mode is used.
|
||
|
||
The basic steps for using NAND devices include:
|
||
1. Declare via the command 'nand device'
|
||
Do this in a board-specific configuration file, passing parameters
|
||
as needed by the controller.
|
||
2. Configure each device using 'nand probe'.
|
||
Do this only after the associated target is set up, such as in its
|
||
reset-init script or in procures defined to access that device.
|
||
3. Operate on the flash via 'nand subcommand'
|
||
Often commands to manipulate the flash are typed by a human, or run
|
||
via a script in some automated way. Common task include writing a
|
||
boot loader, operating system, or other data needed to initialize
|
||
or de-brick a board.
|
||
|
||
NOTE: At the time this text was written, the largest NAND flash fully
|
||
supported by OpenOCD is 2 GiBytes (16 GiBits). This is because the
|
||
variables used to hold offsets and lengths are only 32 bits wide.
|
||
(Larger chips may work in some cases, unless an offset or length is
|
||
larger than 0xffffffff, the largest 32-bit unsigned integer.) Some
|
||
larger devices will work, since they are actually multi-chip modules
|
||
with two smaller chips and individual chipselect lines.
|
||
|
||
12.6.1 NAND Configuration Commands
|
||
----------------------------------
|
||
|
||
NAND chips must be declared in configuration scripts, plus some
|
||
additional configuration that's done after OpenOCD has initialized.
|
||
|
||
-- Config Command: nand device name driver target [configparams...]
|
||
Declares a NAND device, which can be read and written to after it
|
||
has been configured through 'nand probe'. In OpenOCD, devices are
|
||
single chips; this is unlike some operating systems, which may
|
||
manage multiple chips as if they were a single (larger) device. In
|
||
some cases, configuring a device will activate extra commands; see
|
||
the controller-specific documentation.
|
||
|
||
NOTE: This command is not available after OpenOCD initialization
|
||
has completed. Use it in board specific configuration files, not
|
||
interactively.
|
||
|
||
* NAME ... may be used to reference the NAND bank in most other
|
||
NAND commands. A number is also available.
|
||
* DRIVER ... identifies the NAND controller driver associated
|
||
with the NAND device being declared. *Note NAND Driver List:
|
||
nanddriverlist.
|
||
* TARGET ... names the target used when issuing commands to the
|
||
NAND controller.
|
||
* CONFIGPARAMS ... controllers may support, or require,
|
||
additional parameters. See the controller-specific
|
||
documentation for more information.
|
||
|
||
-- Command: nand list
|
||
Prints a summary of each device declared using 'nand device',
|
||
numbered from zero. Note that un-probed devices show no details.
|
||
> nand list
|
||
#0: NAND 1GiB 3,3V 8-bit (Micron) pagesize: 2048, buswidth: 8,
|
||
blocksize: 131072, blocks: 8192
|
||
#1: NAND 1GiB 3,3V 8-bit (Micron) pagesize: 2048, buswidth: 8,
|
||
blocksize: 131072, blocks: 8192
|
||
>
|
||
|
||
-- Command: nand probe num
|
||
Probes the specified device to determine key characteristics like
|
||
its page and block sizes, and how many blocks it has. The NUM
|
||
parameter is the value shown by 'nand list'. You must
|
||
(successfully) probe a device before you can use it with most other
|
||
NAND commands.
|
||
|
||
12.6.2 Erasing, Reading, Writing to NAND Flash
|
||
----------------------------------------------
|
||
|
||
-- Command: nand dump num filename offset length [oob_option]
|
||
Reads binary data from the NAND device and writes it to the file,
|
||
starting at the specified offset. The NUM parameter is the value
|
||
shown by 'nand list'.
|
||
|
||
Use a complete path name for FILENAME, so you don't depend on the
|
||
directory used to start the OpenOCD server.
|
||
|
||
The OFFSET and LENGTH must be exact multiples of the device's page
|
||
size. They describe a data region; the OOB data associated with
|
||
each such page may also be accessed.
|
||
|
||
NOTE: At the time this text was written, no error correction was
|
||
done on the data that's read, unless raw access was disabled and
|
||
the underlying NAND controller driver had a 'read_page' method
|
||
which handled that error correction.
|
||
|
||
By default, only page data is saved to the specified file. Use an
|
||
OOB_OPTION parameter to save OOB data:
|
||
* no oob_* parameter
|
||
Output file holds only page data; OOB is discarded.
|
||
* 'oob_raw'
|
||
Output file interleaves page data and OOB data; the file will
|
||
be longer than "length" by the size of the spare areas
|
||
associated with each data page. Note that this kind of "raw"
|
||
access is different from what's implied by 'nand raw_access',
|
||
which just controls whether a hardware-aware access method is
|
||
used.
|
||
* 'oob_only'
|
||
Output file has only raw OOB data, and will be smaller than
|
||
"length" since it will contain only the spare areas associated
|
||
with each data page.
|
||
|
||
-- Command: nand erase num [offset length]
|
||
Erases blocks on the specified NAND device, starting at the
|
||
specified OFFSET and continuing for LENGTH bytes. Both of those
|
||
values must be exact multiples of the device's block size, and the
|
||
region they specify must fit entirely in the chip. If those
|
||
parameters are not specified, the whole NAND chip will be erased.
|
||
The NUM parameter is the value shown by 'nand list'.
|
||
|
||
NOTE: This command will try to erase bad blocks, when told to do
|
||
so, which will probably invalidate the manufacturer's bad block
|
||
marker. For the remainder of the current server session, 'nand
|
||
info' will still report that the block "is" bad.
|
||
|
||
-- Command: nand write num filename offset [option...]
|
||
Writes binary data from the file into the specified NAND device,
|
||
starting at the specified offset. Those pages should already have
|
||
been erased; you can't change zero bits to one bits. The NUM
|
||
parameter is the value shown by 'nand list'.
|
||
|
||
Use a complete path name for FILENAME, so you don't depend on the
|
||
directory used to start the OpenOCD server.
|
||
|
||
The OFFSET must be an exact multiple of the device's page size.
|
||
All data in the file will be written, assuming it doesn't run past
|
||
the end of the device. Only full pages are written, and any extra
|
||
space in the last page will be filled with 0xff bytes. (That
|
||
includes OOB data, if that's being written.)
|
||
|
||
NOTE: At the time this text was written, bad blocks are ignored.
|
||
That is, this routine will not skip bad blocks, but will instead
|
||
try to write them. This can cause problems.
|
||
|
||
Provide at most one OPTION parameter. With some NAND drivers, the
|
||
meanings of these parameters may change if 'nand raw_access' was
|
||
used to disable hardware ECC.
|
||
* no oob_* parameter
|
||
File has only page data, which is written. If raw access is
|
||
in use, the OOB area will not be written. Otherwise, if the
|
||
underlying NAND controller driver has a 'write_page' routine,
|
||
that routine may write the OOB with hardware-computed ECC
|
||
data.
|
||
* 'oob_only'
|
||
File has only raw OOB data, which is written to the OOB area.
|
||
Each page's data area stays untouched. This can be a
|
||
dangerous option, since it can invalidate the ECC data. You
|
||
may need to force raw access to use this mode.
|
||
* 'oob_raw'
|
||
File interleaves data and OOB data, both of which are written
|
||
If raw access is enabled, the data is written first, then the
|
||
un-altered OOB. Otherwise, if the underlying NAND controller
|
||
driver has a 'write_page' routine, that routine may modify the
|
||
OOB before it's written, to include hardware-computed ECC
|
||
data.
|
||
* 'oob_softecc'
|
||
File has only page data, which is written. The OOB area is
|
||
filled with 0xff, except for a standard 1-bit software ECC
|
||
code stored in conventional locations. You might need to
|
||
force raw access to use this mode, to prevent the underlying
|
||
driver from applying hardware ECC.
|
||
* 'oob_softecc_kw'
|
||
File has only page data, which is written. The OOB area is
|
||
filled with 0xff, except for a 4-bit software ECC specific to
|
||
the boot ROM in Marvell Kirkwood SoCs. You might need to
|
||
force raw access to use this mode, to prevent the underlying
|
||
driver from applying hardware ECC.
|
||
|
||
-- Command: nand verify num filename offset [option...]
|
||
Verify the binary data in the file has been programmed to the
|
||
specified NAND device, starting at the specified offset. The NUM
|
||
parameter is the value shown by 'nand list'.
|
||
|
||
Use a complete path name for FILENAME, so you don't depend on the
|
||
directory used to start the OpenOCD server.
|
||
|
||
The OFFSET must be an exact multiple of the device's page size.
|
||
All data in the file will be read and compared to the contents of
|
||
the flash, assuming it doesn't run past the end of the device. As
|
||
with 'nand write', only full pages are verified, so any extra space
|
||
in the last page will be filled with 0xff bytes.
|
||
|
||
The same OPTIONS accepted by 'nand write', and the file will be
|
||
processed similarly to produce the buffers that can be compared
|
||
against the contents produced from 'nand dump'.
|
||
|
||
NOTE: This will not work when the underlying NAND controller
|
||
driver's 'write_page' routine must update the OOB with a
|
||
hardware-computed ECC before the data is written. This limitation
|
||
may be removed in a future release.
|
||
|
||
12.6.3 Other NAND commands
|
||
--------------------------
|
||
|
||
-- Command: nand check_bad_blocks num [offset length]
|
||
Checks for manufacturer bad block markers on the specified NAND
|
||
device. If no parameters are provided, checks the whole device;
|
||
otherwise, starts at the specified OFFSET and continues for LENGTH
|
||
bytes. Both of those values must be exact multiples of the
|
||
device's block size, and the region they specify must fit entirely
|
||
in the chip. The NUM parameter is the value shown by 'nand list'.
|
||
|
||
NOTE: Before using this command you should force raw access with
|
||
'nand raw_access enable' to ensure that the underlying driver will
|
||
not try to apply hardware ECC.
|
||
|
||
-- Command: nand info num
|
||
The NUM parameter is the value shown by 'nand list'. This prints
|
||
the one-line summary from "nand list", plus for devices which have
|
||
been probed this also prints any known status for each block.
|
||
|
||
-- Command: nand raw_access num ('enable'|'disable')
|
||
Sets or clears an flag affecting how page I/O is done. The NUM
|
||
parameter is the value shown by 'nand list'.
|
||
|
||
This flag is cleared (disabled) by default, but changing that value
|
||
won't affect all NAND devices. The key factor is whether the
|
||
underlying driver provides 'read_page' or 'write_page' methods. If
|
||
it doesn't provide those methods, the setting of this flag is
|
||
irrelevant; all access is effectively "raw".
|
||
|
||
When those methods exist, they are normally used when reading data
|
||
('nand dump' or reading bad block markers) or writing it ('nand
|
||
write'). However, enabling raw access (setting the flag) prevents
|
||
use of those methods, bypassing hardware ECC logic. This can be a
|
||
dangerous option, since writing blocks with the wrong ECC data can
|
||
cause them to be marked as bad.
|
||
|
||
12.6.4 NAND Driver List
|
||
-----------------------
|
||
|
||
As noted above, the 'nand device' command allows driver-specific options
|
||
and behaviors. Some controllers also activate controller-specific
|
||
commands.
|
||
|
||
-- NAND Driver: at91sam9
|
||
This driver handles the NAND controllers found on AT91SAM9 family
|
||
chips from Atmel. It takes two extra parameters: address of the
|
||
NAND chip; address of the ECC controller.
|
||
nand device $NANDFLASH at91sam9 $CHIPNAME 0x40000000 0xfffffe800
|
||
AT91SAM9 chips support single-bit ECC hardware. The 'write_page'
|
||
and 'read_page' methods are used to utilize the ECC hardware unless
|
||
they are disabled by using the 'nand raw_access' command. There
|
||
are four additional commands that are needed to fully configure the
|
||
AT91SAM9 NAND controller. Two are optional; most boards use the
|
||
same wiring for ALE/CLE:
|
||
-- Config Command: at91sam9 cle num addr_line
|
||
Configure the address line used for latching commands. The
|
||
NUM parameter is the value shown by 'nand list'.
|
||
-- Config Command: at91sam9 ale num addr_line
|
||
Configure the address line used for latching addresses. The
|
||
NUM parameter is the value shown by 'nand list'.
|
||
|
||
For the next two commands, it is assumed that the pins have already
|
||
been properly configured for input or output.
|
||
-- Config Command: at91sam9 rdy_busy num pio_base_addr pin
|
||
Configure the RDY/nBUSY input from the NAND device. The NUM
|
||
parameter is the value shown by 'nand list'. PIO_BASE_ADDR is
|
||
the base address of the PIO controller and PIN is the pin
|
||
number.
|
||
-- Config Command: at91sam9 ce num pio_base_addr pin
|
||
Configure the chip enable input to the NAND device. The NUM
|
||
parameter is the value shown by 'nand list'. PIO_BASE_ADDR is
|
||
the base address of the PIO controller and PIN is the pin
|
||
number.
|
||
|
||
-- NAND Driver: davinci
|
||
This driver handles the NAND controllers found on DaVinci family
|
||
chips from Texas Instruments. It takes three extra parameters:
|
||
address of the NAND chip; hardware ECC mode to use ('hwecc1',
|
||
'hwecc4', 'hwecc4_infix'); address of the AEMIF controller on this
|
||
processor.
|
||
nand device davinci dm355.arm 0x02000000 hwecc4 0x01e10000
|
||
All DaVinci processors support the single-bit ECC hardware, and
|
||
newer ones also support the four-bit ECC hardware. The
|
||
'write_page' and 'read_page' methods are used to implement those
|
||
ECC modes, unless they are disabled using the 'nand raw_access'
|
||
command.
|
||
|
||
-- NAND Driver: lpc3180
|
||
These controllers require an extra 'nand device' parameter: the
|
||
clock rate used by the controller.
|
||
-- Command: lpc3180 select num [mlc|slc]
|
||
Configures use of the MLC or SLC controller mode. MLC implies
|
||
use of hardware ECC. The NUM parameter is the value shown by
|
||
'nand list'.
|
||
|
||
At this writing, this driver includes 'write_page' and 'read_page'
|
||
methods. Using 'nand raw_access' to disable those methods will
|
||
prevent use of hardware ECC in the MLC controller mode, but won't
|
||
change SLC behavior.
|
||
|
||
-- NAND Driver: mx3
|
||
This driver handles the NAND controller in i.MX31. The mxc driver
|
||
should work for this chip as well.
|
||
|
||
-- NAND Driver: mxc
|
||
This driver handles the NAND controller found in Freescale i.MX
|
||
chips. It has support for v1 (i.MX27 and i.MX31) and v2 (i.MX35).
|
||
The driver takes 3 extra arguments, chip ('mx27', 'mx31', 'mx35'),
|
||
ecc ('noecc', 'hwecc') and optionally if bad block information
|
||
should be swapped between main area and spare area ('biswap'),
|
||
defaults to off.
|
||
nand device mx35.nand mxc imx35.cpu mx35 hwecc biswap
|
||
-- Command: mxc biswap bank_num [enable|disable]
|
||
Turns on/off bad block information swapping from main area,
|
||
without parameter query status.
|
||
|
||
-- NAND Driver: orion
|
||
These controllers require an extra 'nand device' parameter: the
|
||
address of the controller.
|
||
nand device orion 0xd8000000
|
||
These controllers don't define any specialized commands. At this
|
||
writing, their drivers don't include 'write_page' or 'read_page'
|
||
methods, so 'nand raw_access' won't change any behavior.
|
||
|
||
-- NAND Driver: s3c2410
|
||
-- NAND Driver: s3c2412
|
||
-- NAND Driver: s3c2440
|
||
-- NAND Driver: s3c2443
|
||
-- NAND Driver: s3c6400
|
||
These S3C family controllers don't have any special 'nand device'
|
||
options, and don't define any specialized commands. At this
|
||
writing, their drivers don't include 'write_page' or 'read_page'
|
||
methods, so 'nand raw_access' won't change any behavior.
|
||
|