flash/nor/psoc4: drop jtag_poll_mask() from flash write
[openocd.git] / README
blob2f71cfc6a3de41b7689ea5e9b33b6bcab9562584
1 Welcome to OpenOCD!
2 ===================
4 OpenOCD provides on-chip programming and debugging support with a
5 layered architecture of JTAG interface and TAP support including:
7 - (X)SVF playback to facilitate automated boundary scan and FPGA/CPLD
8   programming;
9 - debug target support (e.g. ARM, MIPS): single-stepping,
10   breakpoints/watchpoints, gprof profiling, etc;
11 - flash chip drivers (e.g. CFI, NAND, internal flash);
12 - embedded TCL interpreter for easy scripting.
14 Several network interfaces are available for interacting with OpenOCD:
15 telnet, TCL, and GDB. The GDB server enables OpenOCD to function as a
16 "remote target" for source-level debugging of embedded systems using
17 the GNU GDB program (and the others who talk GDB protocol, e.g. IDA
18 Pro).
20 This README file contains an overview of the following topics:
22 - quickstart instructions,
23 - how to find and build more OpenOCD documentation,
24 - list of the supported hardware,
25 - the installation and build process,
26 - packaging tips.
29 ============================
30 Quickstart for the impatient
31 ============================
33 If you have a popular board then just start OpenOCD with its config,
34 e.g.:
36   openocd -f board/stm32f4discovery.cfg
38 If you are connecting a particular adapter with some specific target,
39 you need to source both the jtag interface and the target configs,
40 e.g.:
42   openocd -f interface/ftdi/jtagkey2.cfg -c "transport select jtag" \
43           -f target/ti_calypso.cfg
45   openocd -f interface/stlink.cfg -c "transport select hla_swd" \
46           -f target/stm32l0.cfg
48 After OpenOCD startup, connect GDB with
50   (gdb) target extended-remote localhost:3333
53 =====================
54 OpenOCD Documentation
55 =====================
57 In addition to the in-tree documentation, the latest manuals may be
58 viewed online at the following URLs:
60   OpenOCD User's Guide:
61     http://openocd.org/doc/html/index.html
63   OpenOCD Developer's Manual:
64     http://openocd.org/doc/doxygen/html/index.html
66 These reflect the latest development versions, so the following section
67 introduces how to build the complete documentation from the package.
69 For more information, refer to these documents or contact the developers
70 by subscribing to the OpenOCD developer mailing list:
72         openocd-devel@lists.sourceforge.net
74 Building the OpenOCD Documentation
75 ----------------------------------
77 By default the OpenOCD build process prepares documentation in the
78 "Info format" and installs it the standard way, so that "info openocd"
79 can access it.
81 Additionally, the OpenOCD User's Guide can be produced in the
82 following different formats:
84   # If PDFVIEWER is set, this creates and views the PDF User Guide.
85   make pdf && ${PDFVIEWER} doc/openocd.pdf
87   # If HTMLVIEWER is set, this creates and views the HTML User Guide.
88   make html && ${HTMLVIEWER} doc/openocd.html/index.html
90 The OpenOCD Developer Manual contains information about the internal
91 architecture and other details about the code:
93   # NB! make sure doxygen is installed, type doxygen --version
94   make doxygen && ${HTMLVIEWER} doxygen/index.html
97 ==================
98 Supported hardware
99 ==================
101 JTAG adapters
102 -------------
104 AM335x, ARM-JTAG-EW, ARM-USB-OCD, ARM-USB-TINY, AT91RM9200, axm0432, BCM2835,
105 Bus Blaster, Buspirate, Cadence DPI, Cadence vdebug, Chameleon, CMSIS-DAP,
106 Cortino, Cypress KitProg, DENX, Digilent JTAG-SMT2, DLC 5, DLP-USB1232H,
107 embedded projects, Espressif USB JTAG Programmer,
108 eStick, FlashLINK, FlossJTAG, Flyswatter, Flyswatter2,
109 FTDI FT232R, Gateworks, Hoegl, ICDI, ICEBear, J-Link, JTAG VPI, JTAGkey,
110 JTAGkey2, JTAG-lock-pick, KT-Link, Linux GPIOD, Lisa/L, LPC1768-Stick,
111 Mellanox rshim, MiniModule, NGX, Nuvoton Nu-Link, Nu-Link2, NXHX, NXP IMX GPIO,
112 OOCDLink, Opendous, OpenJTAG, Openmoko, OpenRD, OSBDM, Presto, Redbee,
113 Remote Bitbang, RLink, SheevaPlug devkit, Stellaris evkits,
114 ST-LINK (SWO tracing supported), STM32-PerformanceStick, STR9-comStick,
115 sysfsgpio, Tigard, TI XDS110, TUMPA, Turtelizer, ULINK, USB-A9260, USB-Blaster,
116 USB-JTAG, USBprog, VPACLink, VSLLink, Wiggler, XDS100v2, Xilinx XVC/PCIe,
117 Xverve.
119 Debug targets
120 -------------
122 ARM: AArch64, ARM11, ARM7, ARM9, Cortex-A/R (v7-A/R), Cortex-M (ARMv{6/7/8}-M),
123 FA526, Feroceon/Dragonite, XScale.
124 ARCv2, AVR32, DSP563xx, DSP5680xx, EnSilica eSi-RISC, EJTAG (MIPS32, MIPS64),
125 ESP32, ESP32-S2, ESP32-S3, Intel Quark, LS102x-SAP, RISC-V, ST STM8,
126 Xtensa.
128 Flash drivers
129 -------------
131 ADUC702x, AT91SAM, AT91SAM9 (NAND), ATH79, ATmega128RFA1, Atmel SAM, AVR, CFI,
132 DSP5680xx, EFM32, EM357, eSi-RISC, eSi-TSMC, EZR32HG, FM3, FM4, Freedom E SPI,
133 GD32, i.MX31, Kinetis, LPC8xx/LPC1xxx/LPC2xxx/LPC541xx, LPC2900, LPC3180, LPC32xx,
134 LPCSPIFI, Marvell QSPI, MAX32, Milandr, MXC, NIIET, nRF51, nRF52 , NuMicro,
135 NUC910, Nuvoton NPCX, onsemi RSL10, Orion/Kirkwood, PIC32mx, PSoC4/5LP/6,
136 Raspberry RP2040, Renesas RPC HF and SH QSPI,
137 S3C24xx, S3C6400, SiM3x, SiFive Freedom E, Stellaris, ST BlueNRG, STM32,
138 STM32 QUAD/OCTO-SPI for Flash/FRAM/EEPROM, STMSMI, STR7x, STR9x, SWM050,
139 TI CC13xx, TI CC26xx, TI CC32xx, TI MSP432, Winner Micro w600, Xilinx XCF,
140 XMC1xxx, XMC4xxx.
143 ==================
144 Installing OpenOCD
145 ==================
147 A Note to OpenOCD Users
148 -----------------------
150 If you would rather be working "with" OpenOCD rather than "on" it, your
151 operating system or JTAG interface supplier may provide binaries for
152 you in a convenient-enough package.
154 Such packages may be more stable than git mainline, where
155 bleeding-edge development takes place. These "Packagers" produce
156 binary releases of OpenOCD after the developers produces new "release"
157 versions of the source code. Previous versions of OpenOCD cannot be
158 used to diagnose problems with the current release, so users are
159 encouraged to keep in contact with their distribution package
160 maintainers or interface vendors to ensure suitable upgrades appear
161 regularly.
163 Users of these binary versions of OpenOCD must contact their Packager to
164 ask for support or newer versions of the binaries; the OpenOCD
165 developers do not support packages directly.
167 A Note to OpenOCD Packagers
168 ---------------------------
170 You are a PACKAGER of OpenOCD if you:
172 - Sell dongles and include pre-built binaries;
173 - Supply tools or IDEs (a development solution integrating OpenOCD);
174 - Build packages (e.g. RPM or DEB files for a GNU/Linux distribution).
176 As a PACKAGER, you will experience first reports of most issues.
177 When you fix those problems for your users, your solution may help
178 prevent hundreds (if not thousands) of other questions from other users.
180 If something does not work for you, please work to inform the OpenOCD
181 developers know how to improve the system or documentation to avoid
182 future problems, and follow-up to help us ensure the issue will be fully
183 resolved in our future releases.
185 That said, the OpenOCD developers would also like you to follow a few
186 suggestions:
188 - Send patches, including config files, upstream, participate in the
189   discussions;
190 - Enable all the options OpenOCD supports, even those unrelated to your
191   particular hardware;
192 - Use "ftdi" interface adapter driver for the FTDI-based devices.
195 ================
196 Building OpenOCD
197 ================
199 The INSTALL file contains generic instructions for running 'configure'
200 and compiling the OpenOCD source code. That file is provided by
201 default for all GNU autotools packages. If you are not familiar with
202 the GNU autotools, then you should read those instructions first.
204 The remainder of this document tries to provide some instructions for
205 those looking for a quick-install.
207 OpenOCD Dependencies
208 --------------------
210 GCC or Clang is currently required to build OpenOCD. The developers
211 have begun to enforce strict code warnings (-Wall, -Werror, -Wextra,
212 and more) and use C99-specific features: inline functions, named
213 initializers, mixing declarations with code, and other tricks. While
214 it may be possible to use other compilers, they must be somewhat
215 modern and could require extending support to conditionally remove
216 GCC-specific extensions.
218 You'll also need:
220 - make
221 - libtool
222 - pkg-config >= 0.23 or pkgconf
224 OpenOCD uses jimtcl library; build from git can retrieve jimtcl as git
225 submodule.
227 Additionally, for building from git:
229 - autoconf >= 2.69
230 - automake >= 1.14
231 - texinfo >= 5.0
233 Optional USB-based adapter drivers need libusb-1.0.
235 Optional USB-Blaster, ASIX Presto and OpenJTAG interface adapter
236 drivers need:
237   - libftdi: http://www.intra2net.com/en/developer/libftdi/index.php
239 Optional CMSIS-DAP adapter driver needs HIDAPI library.
241 Optional linuxgpiod adapter driver needs libgpiod library.
243 Optional JLink adapter driver needs libjaylink; build from git can
244 retrieve libjaylink as git submodule.
246 Optional ARM disassembly needs capstone library.
248 Optional development script checkpatch needs:
250 - perl
251 - python
252 - python-ply
254 Permissions delegation
255 ----------------------
257 Running OpenOCD with root/administrative permissions is strongly
258 discouraged for security reasons.
260 For USB devices on GNU/Linux you should use the contrib/60-openocd.rules
261 file. It probably belongs somewhere in /etc/udev/rules.d, but
262 consult your operating system documentation to be sure. Do not forget
263 to add yourself to the "plugdev" group.
265 For parallel port adapters on GNU/Linux and FreeBSD please change your
266 "ppdev" (parport* or ppi*) device node permissions accordingly.
268 For parport adapters on Windows you need to run install_giveio.bat
269 (it's also possible to use "ioperm" with Cygwin instead) to give
270 ordinary users permissions for accessing the "LPT" registers directly.
272 Compiling OpenOCD
273 -----------------
275 To build OpenOCD, use the following sequence of commands:
277   ./bootstrap (when building from the git repository)
278   ./configure [options]
279   make
280   sudo make install
282 The 'configure' step generates the Makefiles required to build
283 OpenOCD, usually with one or more options provided to it. The first
284 'make' step will build OpenOCD and place the final executable in
285 './src/'. The final (optional) step, ``make install'', places all of
286 the files in the required location.
288 To see the list of all the supported options, run
289   ./configure --help
291 Cross-compiling Options
292 -----------------------
294 Cross-compiling is supported the standard autotools way, you just need
295 to specify the cross-compiling target triplet in the --host option,
296 e.g. for cross-building for Windows 32-bit with MinGW on Debian:
298   ./configure --host=i686-w64-mingw32 [options]
300 To make pkg-config work nicely for cross-compiling, you might need an
301 additional wrapper script as described at
303   https://autotools.io/pkgconfig/cross-compiling.html
305 This is needed to tell pkg-config where to look for the target
306 libraries that OpenOCD depends on. Alternatively, you can specify
307 *_CFLAGS and *_LIBS environment variables directly, see "./configure
308 --help" for the details.
310 For a more or less complete script that does all this for you, see
312   contrib/cross-build.sh
314 Parallel Port Dongles
315 ---------------------
317 If you want to access the parallel port using the PPDEV interface you
318 have to specify both --enable-parport AND --enable-parport-ppdev, since
319 the later option is an option to the parport driver.
321 The same is true for the --enable-parport-giveio option, you have to
322 use both the --enable-parport AND the --enable-parport-giveio option
323 if you want to use giveio instead of ioperm parallel port access
324 method.
327 ==========================
328 Obtaining OpenOCD From GIT
329 ==========================
331 You can download the current GIT version with a GIT client of your
332 choice from the main repository:
334    git://git.code.sf.net/p/openocd/code
336 You may prefer to use a mirror:
338    http://repo.or.cz/r/openocd.git
339    git://repo.or.cz/openocd.git
341 Using the GIT command line client, you might use the following command
342 to set up a local copy of the current repository (make sure there is no
343 directory called "openocd" in the current directory):
345    git clone git://git.code.sf.net/p/openocd/code openocd
347 Then you can update that at your convenience using
349    git pull
351 There is also a gitweb interface, which you can use either to browse
352 the repository or to download arbitrary snapshots using HTTP:
354    http://repo.or.cz/w/openocd.git
356 Snapshots are compressed tarballs of the source tree, about 1.3 MBytes
357 each at this writing.