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.
|
|||
|
|