README: Use proper Markdown syntax
The README file contains a mixture of Markdown and non-Markdown syntax. Refurbish the document and use only Markdown syntax according to the specification in [1]. [1] https://www.markdownguide.org/ Change-Id: If58f4e2971dc798a03a78841226804ab1f2d33c8 Signed-off-by: Marc Schink <dev@zapb.de> Reviewed-on: https://review.openocd.org/c/openocd/+/8387 Reviewed-by: Antonio Borneo <borneo.antonio@gmail.com> Tested-by: jenkins
This commit is contained in:
Marc Schink
Antonio Borneo
parent
a9ba96f94a
commit
63ca967032
140
README
140
README
|
|
@ -1,5 +1,4 @@
|
|||
Welcome to OpenOCD!
|
||||
===================
|
||||
# Welcome to OpenOCD!
|
||||
|
||||
OpenOCD provides on-chip programming and debugging support with a
|
||||
layered architecture of JTAG interface and TAP support including:
|
||||
|
|
@ -26,33 +25,33 @@ This README file contains an overview of the following topics:
|
|||
- packaging tips.
|
||||
|
||||
|
||||
============================
|
||||
Quickstart for the impatient
|
||||
============================
|
||||
# Quickstart for the impatient
|
||||
|
||||
If you have a popular board then just start OpenOCD with its config,
|
||||
e.g.:
|
||||
|
||||
openocd -f board/stm32f4discovery.cfg
|
||||
openocd -f board/stm32f4discovery.cfg
|
||||
|
||||
If you are connecting a particular adapter with some specific target,
|
||||
you need to source both the jtag interface and the target configs,
|
||||
e.g.:
|
||||
|
||||
openocd -f interface/ftdi/jtagkey2.cfg -c "transport select jtag" \
|
||||
-f target/ti_calypso.cfg
|
||||
```
|
||||
openocd -f interface/ftdi/jtagkey2.cfg -c "transport select jtag" \
|
||||
-f target/ti_calypso.cfg
|
||||
```
|
||||
|
||||
openocd -f interface/stlink.cfg -c "transport select hla_swd" \
|
||||
-f target/stm32l0.cfg
|
||||
```
|
||||
openocd -f interface/stlink.cfg -c "transport select hla_swd" \
|
||||
-f target/stm32l0.cfg
|
||||
```
|
||||
|
||||
After OpenOCD startup, connect GDB with
|
||||
|
||||
(gdb) target extended-remote localhost:3333
|
||||
(gdb) target extended-remote localhost:3333
|
||||
|
||||
|
||||
=====================
|
||||
OpenOCD Documentation
|
||||
=====================
|
||||
# OpenOCD Documentation
|
||||
|
||||
In addition to the in-tree documentation, the latest manuals may be
|
||||
viewed online at the following URLs:
|
||||
|
|
@ -71,35 +70,34 @@ by subscribing to the OpenOCD developer mailing list:
|
|||
|
||||
openocd-devel@lists.sourceforge.net
|
||||
|
||||
Building the OpenOCD Documentation
|
||||
----------------------------------
|
||||
## Building the OpenOCD Documentation
|
||||
|
||||
By default the OpenOCD build process prepares documentation in the
|
||||
"Info format" and installs it the standard way, so that "info openocd"
|
||||
"Info format" and installs it the standard way, so that `info openocd`
|
||||
can access it.
|
||||
|
||||
Additionally, the OpenOCD User's Guide can be produced in the
|
||||
following different formats:
|
||||
|
||||
# If PDFVIEWER is set, this creates and views the PDF User Guide.
|
||||
make pdf && ${PDFVIEWER} doc/openocd.pdf
|
||||
If `PDFVIEWER` is set, this creates and views the PDF User Guide.
|
||||
|
||||
# If HTMLVIEWER is set, this creates and views the HTML User Guide.
|
||||
make html && ${HTMLVIEWER} doc/openocd.html/index.html
|
||||
make pdf && ${PDFVIEWER} doc/openocd.pdf
|
||||
|
||||
If `HTMLVIEWER` is set, this creates and views the HTML User Guide.
|
||||
|
||||
make html && ${HTMLVIEWER} doc/openocd.html/index.html
|
||||
|
||||
The OpenOCD Developer Manual contains information about the internal
|
||||
architecture and other details about the code:
|
||||
|
||||
# NB! make sure doxygen is installed, type doxygen --version
|
||||
make doxygen && ${HTMLVIEWER} doxygen/index.html
|
||||
Note: make sure doxygen is installed, type doxygen --version
|
||||
|
||||
make doxygen && ${HTMLVIEWER} doxygen/index.html
|
||||
|
||||
|
||||
==================
|
||||
Supported hardware
|
||||
==================
|
||||
# Supported hardware
|
||||
|
||||
JTAG adapters
|
||||
-------------
|
||||
## JTAG adapters
|
||||
|
||||
AM335x, ARM-JTAG-EW, ARM-USB-OCD, ARM-USB-TINY, AT91RM9200, axm0432, BCM2835,
|
||||
Bus Blaster, Buspirate, Cadence DPI, Cadence vdebug, Chameleon, CMSIS-DAP,
|
||||
|
|
@ -116,8 +114,7 @@ sysfsgpio, Tigard, TI XDS110, TUMPA, Turtelizer, ULINK, USB-A9260, USB-Blaster,
|
|||
USB-JTAG, USBprog, VPACLink, VSLLink, Wiggler, XDS100v2, Xilinx XVC/PCIe,
|
||||
Xverve.
|
||||
|
||||
Debug targets
|
||||
-------------
|
||||
## Debug targets
|
||||
|
||||
ARM: AArch64, ARM11, ARM7, ARM9, Cortex-A/R (v7-A/R), Cortex-M (ARMv{6/7/8}-M),
|
||||
FA526, Feroceon/Dragonite, XScale.
|
||||
|
|
@ -125,8 +122,7 @@ ARCv2, AVR32, DSP563xx, DSP5680xx, EnSilica eSi-RISC, EJTAG (MIPS32, MIPS64),
|
|||
ESP32, ESP32-S2, ESP32-S3, Intel Quark, LS102x-SAP, RISC-V, ST STM8,
|
||||
Xtensa.
|
||||
|
||||
Flash drivers
|
||||
-------------
|
||||
## Flash drivers
|
||||
|
||||
ADUC702x, AT91SAM, AT91SAM9 (NAND), ATH79, ATmega128RFA1, Atmel SAM, AVR, CFI,
|
||||
DSP5680xx, EFM32, EM357, eSi-RISC, eSi-TSMC, EZR32HG, FM3, FM4, Freedom E SPI,
|
||||
|
|
@ -140,12 +136,9 @@ TI CC13xx, TI CC26xx, TI CC32xx, TI MSP432, Winner Micro w600, Xilinx XCF,
|
|||
XMC1xxx, XMC4xxx.
|
||||
|
||||
|
||||
==================
|
||||
Installing OpenOCD
|
||||
==================
|
||||
# Installing OpenOCD
|
||||
|
||||
A Note to OpenOCD Users
|
||||
-----------------------
|
||||
## A Note to OpenOCD Users
|
||||
|
||||
If you would rather be working "with" OpenOCD rather than "on" it, your
|
||||
operating system or JTAG interface supplier may provide binaries for
|
||||
|
|
@ -164,8 +157,7 @@ Users of these binary versions of OpenOCD must contact their Packager to
|
|||
ask for support or newer versions of the binaries; the OpenOCD
|
||||
developers do not support packages directly.
|
||||
|
||||
A Note to OpenOCD Packagers
|
||||
---------------------------
|
||||
## A Note to OpenOCD Packagers
|
||||
|
||||
You are a PACKAGER of OpenOCD if you:
|
||||
|
||||
|
|
@ -192,11 +184,9 @@ suggestions:
|
|||
- Use "ftdi" interface adapter driver for the FTDI-based devices.
|
||||
|
||||
|
||||
================
|
||||
Building OpenOCD
|
||||
================
|
||||
# Building OpenOCD
|
||||
|
||||
The INSTALL file contains generic instructions for running 'configure'
|
||||
The INSTALL file contains generic instructions for running `configure`
|
||||
and compiling the OpenOCD source code. That file is provided by
|
||||
default for all GNU autotools packages. If you are not familiar with
|
||||
the GNU autotools, then you should read those instructions first.
|
||||
|
|
@ -204,8 +194,7 @@ the GNU autotools, then you should read those instructions first.
|
|||
The remainder of this document tries to provide some instructions for
|
||||
those looking for a quick-install.
|
||||
|
||||
OpenOCD Dependencies
|
||||
--------------------
|
||||
## OpenOCD Dependencies
|
||||
|
||||
GCC or Clang is currently required to build OpenOCD. The developers
|
||||
have begun to enforce strict code warnings (-Wall, -Werror, -Wextra,
|
||||
|
|
@ -250,8 +239,7 @@ Optional development script checkpatch needs:
|
|||
- python
|
||||
- python-ply
|
||||
|
||||
Permissions delegation
|
||||
----------------------
|
||||
## Permissions delegation
|
||||
|
||||
Running OpenOCD with root/administrative permissions is strongly
|
||||
discouraged for security reasons.
|
||||
|
|
@ -268,89 +256,81 @@ For parport adapters on Windows you need to run install_giveio.bat
|
|||
(it's also possible to use "ioperm" with Cygwin instead) to give
|
||||
ordinary users permissions for accessing the "LPT" registers directly.
|
||||
|
||||
Compiling OpenOCD
|
||||
-----------------
|
||||
## Compiling OpenOCD
|
||||
|
||||
To build OpenOCD, use the following sequence of commands:
|
||||
|
||||
./bootstrap (when building from the git repository)
|
||||
./configure [options]
|
||||
make
|
||||
sudo make install
|
||||
./bootstrap
|
||||
./configure [options]
|
||||
make
|
||||
sudo make install
|
||||
|
||||
The 'configure' step generates the Makefiles required to build
|
||||
The `bootstrap` command is only necessary when building from the Git repository. The `configure` step generates the Makefiles required to build
|
||||
OpenOCD, usually with one or more options provided to it. The first
|
||||
'make' step will build OpenOCD and place the final executable in
|
||||
'./src/'. The final (optional) step, ``make install'', places all of
|
||||
'./src/'. The final (optional) step, `make install`, places all of
|
||||
the files in the required location.
|
||||
|
||||
To see the list of all the supported options, run
|
||||
./configure --help
|
||||
To see the list of all the supported options, run `./configure --help`
|
||||
|
||||
Cross-compiling Options
|
||||
-----------------------
|
||||
## Cross-compiling Options
|
||||
|
||||
Cross-compiling is supported the standard autotools way, you just need
|
||||
to specify the cross-compiling target triplet in the --host option,
|
||||
e.g. for cross-building for Windows 32-bit with MinGW on Debian:
|
||||
|
||||
./configure --host=i686-w64-mingw32 [options]
|
||||
./configure --host=i686-w64-mingw32 [options]
|
||||
|
||||
To make pkg-config work nicely for cross-compiling, you might need an
|
||||
additional wrapper script as described at
|
||||
|
||||
https://autotools.io/pkgconfig/cross-compiling.html
|
||||
https://autotools.io/pkgconfig/cross-compiling.html
|
||||
|
||||
This is needed to tell pkg-config where to look for the target
|
||||
libraries that OpenOCD depends on. Alternatively, you can specify
|
||||
*_CFLAGS and *_LIBS environment variables directly, see "./configure
|
||||
--help" for the details.
|
||||
`*_CFLAGS` and `*_LIBS` environment variables directly, see `./configure
|
||||
--help` for the details.
|
||||
|
||||
For a more or less complete script that does all this for you, see
|
||||
|
||||
contrib/cross-build.sh
|
||||
contrib/cross-build.sh
|
||||
|
||||
Parallel Port Dongles
|
||||
---------------------
|
||||
## Parallel Port Dongles
|
||||
|
||||
If you want to access the parallel port using the PPDEV interface you
|
||||
have to specify both --enable-parport AND --enable-parport-ppdev, since
|
||||
have to specify both `--enable-parport` and `--enable-parport-ppdev`, since
|
||||
the later option is an option to the parport driver.
|
||||
|
||||
The same is true for the --enable-parport-giveio option, you have to
|
||||
use both the --enable-parport AND the --enable-parport-giveio option
|
||||
The same is true for the `--enable-parport-giveio` option, you have to
|
||||
use both the `--enable-parport` and the `--enable-parport-giveio` option
|
||||
if you want to use giveio instead of ioperm parallel port access
|
||||
method.
|
||||
|
||||
|
||||
==========================
|
||||
Obtaining OpenOCD From GIT
|
||||
==========================
|
||||
# Obtaining OpenOCD From GIT
|
||||
|
||||
You can download the current GIT version with a GIT client of your
|
||||
choice from the main repository:
|
||||
|
||||
git://git.code.sf.net/p/openocd/code
|
||||
git://git.code.sf.net/p/openocd/code
|
||||
|
||||
You may prefer to use a mirror:
|
||||
|
||||
http://repo.or.cz/r/openocd.git
|
||||
git://repo.or.cz/openocd.git
|
||||
http://repo.or.cz/r/openocd.git
|
||||
git://repo.or.cz/openocd.git
|
||||
|
||||
Using the GIT command line client, you might use the following command
|
||||
to set up a local copy of the current repository (make sure there is no
|
||||
directory called "openocd" in the current directory):
|
||||
|
||||
git clone git://git.code.sf.net/p/openocd/code openocd
|
||||
git clone git://git.code.sf.net/p/openocd/code openocd
|
||||
|
||||
Then you can update that at your convenience using
|
||||
|
||||
git pull
|
||||
Then you can update that at your convenience using `git pull`.
|
||||
|
||||
There is also a gitweb interface, which you can use either to browse
|
||||
the repository or to download arbitrary snapshots using HTTP:
|
||||
|
||||
http://repo.or.cz/w/openocd.git
|
||||
http://repo.or.cz/w/openocd.git
|
||||
|
||||
Snapshots are compressed tarballs of the source tree, about 1.3 MBytes
|
||||
each at this writing.
|
||||
|
|
|
|||
Loading…
Reference in New Issue