interesting
/
riscv-openocd
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
10,526 Commits 65 Branches 14 Tags 110 MiB
C 88.7%
Perl 2.3%
HTML 2%
Tcl 1.9%
Assembly 1.9%
Other 3.1%
Go to file
Tim Newsome 9e097d0fc4
From upstream (#684) 
* flash/nor/atsame5: add LAN9255 devices

Support Microchip LAN9255 devices with embedded SAME53J MCU.

Signed-off-by: Hans-Erik Floryd <hans-erik.floryd@rt-labs.com>
Change-Id: Ia811c593bf7cf73e588d32873c68eb67c6fafad7
Reviewed-on: https://review.openocd.org/c/openocd/+/6811
Tested-by: jenkins
Reviewed-by: Antonio Borneo <borneo.antonio@gmail.com>
Reviewed-by: Tomas Vanek <vanekt@fbl.cz>

* tcl/board: Add EVB-LAN9255 config

Config for EVB-LAN9255, tested using Atmel-ICE debugger on J10
connector.

Signed-off-by: Hans-Erik Floryd <hans-erik.floryd@rt-labs.com>
Change-Id: I8bcf779e9363499a98aa0b7d10819c53da6a19e7
Reviewed-on: https://review.openocd.org/c/openocd/+/6812
Tested-by: jenkins
Reviewed-by: Antonio Borneo <borneo.antonio@gmail.com>

* aarch64: support for aarch32 ARM_MODE_UND

Fix:
unrecognized psr mode: 0x1b
cannot read system control register in this mode: (UNRECOGNIZED : 0x1b)

Change-Id: I4dc3e72f90d57e52c0fe63cb59a7529a398757b3

Signed-off-by: Julien Massot <julien.massot@iot.bzh>
Change-Id: Ifa5d21ae97492fde9e8c79ee7d99d8a2a871b1b5
Reviewed-on: https://review.openocd.org/c/openocd/+/6808
Tested-by: jenkins
Reviewed-by: Antonio Borneo <borneo.antonio@gmail.com>

* Combine register lists of smp targets.

This is helpful when you want to pretend to gdb that your heterogeneous
multicore system is homogeneous, because gdb cannot handle heterogeneous
systems. This won't always works, but works fine if e.g. one of the
cores has an FPU while the other does not. (Specifically, HiFive
Unleashed has 1 core with no FPU, plus 4 cores with an FPU.)

Signed-off-by: Tim Newsome <tim@sifive.com>
Change-Id: I05ff4c28646778fbc00327bc510be064bfe6c9f0
Reviewed-on: https://review.openocd.org/c/openocd/+/6362
Tested-by: jenkins
Reviewed-by: Antonio Borneo <borneo.antonio@gmail.com>

* semihosting: use open mode flags from GDB, not from sys/stat.h

Values defined in sys/stat.h are not guaranteed to match
the constants defined by the GDB remote protocol, which are defined in
https://sourceware.org/gdb/onlinedocs/gdb/Open-Flags.html#Open-Flags.
On my local system (Manjaro 21.2.1 x86_64), for example, O_TRUNC is
defined as 0x40, whereas GDB requires it to be 0x400,
causing all "w" file open modes to misbehave.

This patch has been tested with STM32F446.

Change-Id: Ifb2c740fd689e71d6f1a4bde1edaecd76fdca910
Signed-off-by: Pavel Kirienko <pavel.kirienko@gmail.com>
Reviewed-on: https://review.openocd.org/c/openocd/+/6804
Tested-by: jenkins
Reviewed-by: Antonio Borneo <borneo.antonio@gmail.com>

* semihosting: User defined operation, Tcl command exec on host

Enabling a portion (0x100 - 0x107) of the user defined semihosting
operation number range (0x100 - 0x1FF) to be processed with the help of
the existing target event mechanism, to implement a general-purpose Tcl
interface for the target available on the host, via semihosting
interface.

Example usage:
- The user configures a Tcl command as a callback for one of the newly
	defined events (semihosting-user-cmd-0x10X) in the configuration
	file.
- The target can make a semihosting call with <opnum>, passing optional
	parameters for the call.

If there is no callback registered to the user defined operation number,
nothing happens.

Example usage: Configure RTT automatically with the exact, linked
control block location from target.

Signed-off-by: Zoltán Dudás <zedudi@gmail.com>
Change-Id: I10e1784b1fecd4e630d78df81cb44bf1aa2fc247
Reviewed-on: https://review.openocd.org/c/openocd/+/6748
Tested-by: jenkins
Reviewed-by: Oleksij Rempel <linux@rempel-privat.de>
Reviewed-by: Antonio Borneo <borneo.antonio@gmail.com>

* target/smp: use a struct list_head to hold the smp targets

Instead of reinventing a simply linked list, reuse the list helper
for the list of targets in a smp cluster.
Using the existing helper, that implements a double linked list,
makes trivial going through the list in reverse order.

Change-Id: Ib36ad2955f15cd2a601b0b9e36ca6d948b12d00f
Signed-off-by: Antonio Borneo <borneo.antonio@gmail.com>
Reviewed-on: https://review.openocd.org/c/openocd/+/6783
Tested-by: jenkins

* helper/list: add list_for_each_entry_direction()

Use a bool flag to specify if the list should be forward or
backward iterated.

Change-Id: Ied19d049f46cdcb7f50137d459cc7c02014526bc
Signed-off-by: Antonio Borneo <borneo.antonio@gmail.com>
Reviewed-on: https://review.openocd.org/c/openocd/+/6784
Tested-by: jenkins

* target/riscv: revive 'riscv resume_order'

This functionality was lost in [1], which was merged as commit
615709d140 ("Upstream a whole host of RISC-V changes.").
Now it works as expected again.

Add convenience macro foreach_smp_target_direction().

Link: [1] https://github.com/riscv/riscv-openocd/pull/567
Change-Id: I1545fa6b45b8a07e27c8ff9dcdcfa2fc4f950cd1
Signed-off-by: Tim Newsome <tim@sifive.com>
Signed-off-by: Antonio Borneo <borneo.antonio@gmail.com>
Reviewed-on: https://review.openocd.org/c/openocd/+/6785
Tested-by: jenkins

* doxygen: fix some function prototype description

Change-Id: I49311a643ea73143839d2f6bde976cfd76f8c67f
Signed-off-by: Antonio Borneo <borneo.antonio@gmail.com>
Reviewed-on: https://review.openocd.org/c/openocd/+/6830
Tested-by: jenkins

* Cadence virtual debug interface (vdebug) integration

Change-Id: I1bc105b3addc3f34161c2356c482ff3011e3f2cc
Signed-off-by: Jacek Wuwer <jacekmw8@gmail.com>
Reviewed-on: https://review.openocd.org/c/openocd/+/6097
Tested-by: jenkins
Reviewed-by: Oleksij Rempel <linux@rempel-privat.de>
Reviewed-by: zapb <dev@zapb.de>
Reviewed-by: Antonio Borneo <borneo.antonio@gmail.com>

* gdb_server: Include thread name as XML attribute

Explicitly providing a thread name in the "thread" element produces
better thread visualizations in downstream tools like IDEs.

Signed-off-by: Ben McMorran <bemcmorr@microsoft.com>
Change-Id: I102c14ddb8b87757fa474de8e3a3f6a1cfe10d98
Reviewed-on: https://review.openocd.org/c/openocd/+/6828
Tested-by: jenkins
Reviewed-by: zapb <dev@zapb.de>
Reviewed-by: Antonio Borneo <borneo.antonio@gmail.com>

* Fix small memory leak.

See https://github.com/riscv/riscv-openocd/pull/672

Change-Id: Ia11ab9bcf860f770ea64ad867102c74b898f6b66
Signed-off-by: Tim Newsome <tim@sifive.com>
Reviewed-on: https://review.openocd.org/c/openocd/+/6831
Tested-by: jenkins
Reviewed-by: zapb <dev@zapb.de>
Reviewed-by: Antonio Borneo <borneo.antonio@gmail.com>

* server: remove remaining crust from dropped eCos code

Commit 39650e2273 ("ecosboard: delete bit-rotted eCos code") has
removed eCos code but has left some empty function that was used
during non-eCos build to replace eCos mutex.

Drop the functions and the file that contain them.

Change-Id: I31bc0237ea699c11bd70921660f960ee406ffa80
Signed-off-by: Antonio Borneo <borneo.antonio@gmail.com>
Reviewed-on: https://review.openocd.org/c/openocd/+/6835
Tested-by: jenkins
Reviewed-by: Tomas Vanek <vanekt@fbl.cz>

* rtos: threadx: Add hla_target support for ThreadX

Tested with an AZ3166 dev board (which uses the STM32F412ZGT6) running
the Azure RTOS ThreadX demonstration system.

Signed-off-by: Ben McMorran <bemcmorr@microsoft.com>
Change-Id: I44c8f7701d9f1aaa872274166321cd7d34fb1855
Reviewed-on: https://review.openocd.org/c/openocd/+/6829
Tested-by: jenkins
Reviewed-by: Antonio Borneo <borneo.antonio@gmail.com>

* .gitmodules: switch away from repo.or.cz

The host repo.or.cz is often offline, creating issues for cloning
and building OpenOCD from scratch.
Already 'jimtcl' developer has dropped repo.or.cz, triggering the
OpenOCD commit 861e75f54e ("jimtcl: switch to github").

Change also the link of the remaining submodules 'git2cl' and
'libjaylink' to their respective main repository.

Change-Id: Ib513237427635359ce36a480a8f2060e2fb12ba4
Signed-off-by: Antonio Borneo <borneo.antonio@gmail.com>
Reviewed-on: https://review.openocd.org/c/openocd/+/6834
Tested-by: jenkins
Reviewed-by: zapb <dev@zapb.de>

* flash/nor/stm32f2x: Fix erase of bank 2 sectors

This commit corrects the erase function for stm32f2x when dealing with
sectors in bank 2, for STM32F42x/43x devices with 1MB flash.

On STM32F42x/43x with 1MB flash in dual bank configuration, the sector
numbering is not consecutive. The last sector in bank 1 is number 7, and
the first sector in bank 2 is number 12.
The sector indices used by openocd, however, _are_ consecutive (0 to 15
in this case). The arguments "first" and "last" to stm32x_erase() are of
this type, and so the logic surrounding sector numbers needed to be
corrected.
Since the two banks in dual bank mode have the same number of sectors, a
sector index in bank 2 is larger than or equal to half the total number
of sectors.

Change-Id: I15260f8a86d9002769a1ae1c40ebdf62142dae18
Signed-off-by: Simon Johansson <ampleyfly@gmail.com>
Reviewed-on: https://review.openocd.org/c/openocd/+/6810
Tested-by: jenkins
Reviewed-by: Tomas Vanek <vanekt@fbl.cz>
Reviewed-by: Tarek BOCHKATI <tarek.bouchkati@gmail.com>

* target/cortex_m: fix target_to_cm() helper

The third parameter of container_of() should point to the same member
as target->arch_info points to, struct arm.

It worked just because struct arm is the first member in
struct armv7m_common.
If you move arm member from the first place, OpenOCD fails heavily.

Change-Id: I0c0a5221490945563e17a0a34d99a603f1d6c2ff
Signed-off-by: Tomas Vanek <vanekt@fbl.cz>
Reviewed-on: https://review.openocd.org/c/openocd/+/6749
Tested-by: jenkins
Reviewed-by: Antonio Borneo <borneo.antonio@gmail.com>

* target/armv7m,cortex_m: introduce checked arch_info cast routines

target_to_armv7m() and target_to_cm() do not match the magic number
so they are not suitable for use outside of target driver code.

Add checked versions of pointer getters. Match the magic number
to ensure the returned value points to struct of the correct type.

Change-Id: If90ef7e969ef04f0f2103e0da29dcbe8e1ac1c0d
Signed-off-by: Tomas Vanek <vanekt@fbl.cz>
Reviewed-on: https://review.openocd.org/c/openocd/+/6750
Tested-by: jenkins
Reviewed-by: Antonio Borneo <borneo.antonio@gmail.com>

* target/cortex_m: add Cortex-M part number getter

The getter checks the magic numbers in arch_info to detect eventual
type mismatch.

Change-Id: I61134b05310a97ae9831517d0516c7b4240d35a5
Signed-off-by: Tomas Vanek <vanekt@fbl.cz>
Reviewed-on: https://review.openocd.org/c/openocd/+/6751
Tested-by: jenkins
Reviewed-by: Antonio Borneo <borneo.antonio@gmail.com>
Reviewed-by: Tarek BOCHKATI <tarek.bouchkati@gmail.com>

* flash/nor/stm32xx: fix segfault accessing Cortex-M part number

Some of STM32 flash drivers read Cortex-M part number from
cortex_m->core_info.
In corner cases the core_info pointer was observed uninitialised
even if target_was_examined() returned true. See also [1]

Use the new and safe helper to get Cortex-M part number.

While on it switch also target_to_cm()/target_to_armv7m() to the safe
versions. This prevents a crash when the flash bank is misconfigured
with non-Cortex-M target.

Add missing checks for target_was_examined() to flash probes.

[1] 6545: fix crash in case cortex_m->core_info is not set
    https://review.openocd.org/c/openocd/+/6545

Change-Id: If2471af74ebfe22f14442f48ae109b2e1bb5fa3b
Signed-off-by: Tomas Vanek <vanekt@fbl.cz>
Fixes: f5898bd93f (flash/stm32fxx.c: do not read CPUID as this info is stored in cortex_m_common)
Reviewed-on: https://review.openocd.org/c/openocd/+/6752
Tested-by: jenkins
Reviewed-by: Antonio Borneo <borneo.antonio@gmail.com>
Reviewed-by: Tarek BOCHKATI <tarek.bouchkati@gmail.com>

* cpld: altera-epm240: Add additional IDCODEs

This adds some additional IDCODEs from the datasheet. It also adds
support for customizing the tap name.

Signed-off-by: Sean Anderson <sean.anderson@seco.com>
Change-Id: I7cda10b92c229b61836c12cd9ca410de358ede2e
Reviewed-on: https://review.openocd.org/c/openocd/+/6846
Tested-by: jenkins
Reviewed-by: Antonio Borneo <borneo.antonio@gmail.com>

* cpld: altera-epm240: Increase adapter speed

According to the datasheet, the minimum clock period with Vccio1 = 1.5V
(the lowest voltage supported) is 143ns, or around 6MHz. Set the default
adapter speed to 5 MHz.

Signed-off-by: Sean Anderson <sean.anderson@seco.com>
Change-Id: I21cad33fa7f1e25e81f43b5d2214d1fa4ec924de
Reviewed-on: https://review.openocd.org/c/openocd/+/6847
Tested-by: jenkins
Reviewed-by: Antonio Borneo <borneo.antonio@gmail.com>

* target: Add support for ls1088a

The LS1088A is an octo-core aarch64 processor from NXP in the layerscape
family. The JTAG is undocumented, but I was able to figure things out
from the output of `dap info`. This is the first in-tree example of
using the hwthread rtos (as far as I know), so hopefully it can serve as
an example to other developers. There are some ETMs, but I was unable to
try them out because I got 'invalid command name "etm"' when trying to
test things out.

Signed-off-by: Sean Anderson <sean.anderson@seco.com>
Change-Id: I9b0791d27d8c41170a413a8d86431107a85feba2
Reviewed-on: https://review.openocd.org/c/openocd/+/6848
Tested-by: jenkins
Reviewed-by: Antonio Borneo <borneo.antonio@gmail.com>

* target: ls1088a: Add service processor

Normally the service processor is not necessary for debugging. However,
if you are using the hard-coded RCW or your boot source is otherwise
corrupt, then the general purpose processors will never be released from
hold-off. This will cause GDB to become confused if it tries to attach,
since they will appear to be running arm32 processors. To deal with
this, we can release the CPUs manually with the BRRL register. This
register cannot be written to from the axi target, so we need to do it
from the service processor target. This involves halting the service
processor, modifying the register, and then resuming it again. We try
and determine what state the service processor was in to avoid resuming
it if it was already halted.

The reset vector for the general purpose processors is determined by the
boot logation pointer registers in the device configuration unit.
Normally these are set using pre-boot initialization commands, but if
they are not set then they default to 0. This will cause the CPU to
almost immediately hit an illegal instruction. This is fine because we
will almost certainly want to attach to the processor and load a program
anyway.

I considered adding this as an event handler for either gdb-attach or
reset-init. However, this command shouldn't be necessary most of the
time, and so I don't think we should run it automatically.

Signed-off-by: Sean Anderson <sean.anderson@seco.com>
Change-Id: I1b725292d8a11274d03af5313dc83678e10e944c
Reviewed-on: https://review.openocd.org/c/openocd/+/6850
Tested-by: jenkins
Reviewed-by: Antonio Borneo <borneo.antonio@gmail.com>

* board: Add NXP LS1088ARDB

This adds a board file for the NXP LS1088ARDB. This only covers the
"primary" JTAG header J55, and not the PCIe header (J91). The only
oddity is that the LS1088A and CPLD are muxed by adding/removing a
jumper from J48. Unfortunately, it doesn't look like OpenOCD supports
this CPLD beyond determining the irlen, so it's not very useful. Those
who are interested in experimenting can define CWTAP to access the CPLD,
but the default is to access the CPU.

Signed-off-by: Sean Anderson <sean.anderson@seco.com>
Change-Id: Ia07436a534f86bd907aa5fe2a78a326a27855a24
Reviewed-on: https://review.openocd.org/c/openocd/+/6849
Tested-by: jenkins
Reviewed-by: Antonio Borneo <borneo.antonio@gmail.com>

* gdb_server: fix double free

Commit 6541233aa7 ("Combine register lists of smp targets.")
unconditionally assigns the output pointers of the function
smp_reg_list_noread(), even if the function fails and returns
error.
This causes a double free from the caller, that has assigned NULL
to the pointers to simplify the error handling.

Use local variables in smp_reg_list_noread() and assign the output
pointers only on success.

Change-Id: Ic0fd2f26520566cf322f0190780e15637c01cfae
Fixes: 6541233aa7 ("Combine register lists of smp targets.")
Reported-by: Michele Bisogno <michele.bisogno.ct@renesas.com>
Signed-off-by: Antonio Borneo <borneo.antonio@gmail.com>
Reviewed-on: https://review.openocd.org/c/openocd/+/6852
Tested-by: jenkins
Reviewed-by: Michele Bisogno <michele.bisogno.ct@renesas.com>
Reviewed-by: Tim Newsome <tim@sifive.com>

* gdb_server: check target examined while combining reg list

Commit 6541233aa7 ("Combine register lists of smp targets.")
assumes that all the targets in the SMP cluster are already
examined and unconditionally call target_get_gdb_reg_list_noread()
that will in turn return error if the target is not examined yet.

Skip targets not examined yet.
Add an additional check in case the register list cannot be built,
e.g. because no target in the SMP cluster is examined. This should
never happen, but it's better to play safe.

Change-Id: I8609815c3d5144790fb05a870cb0c931540aef8a
Fixes: 6541233aa7 ("Combine register lists of smp targets.")
Reported-by: Michele Bisogno <michele.bisogno.ct@renesas.com>
Signed-off-by: Antonio Borneo <borneo.antonio@gmail.com>
Reviewed-on: https://review.openocd.org/c/openocd/+/6853
Tested-by: jenkins
Reviewed-by: Michele Bisogno <michele.bisogno.ct@renesas.com>
Reviewed-by: Tim Newsome <tim@sifive.com>

* flash/stm32l4x: fix maybe-uninitialized compiler error

using gcc (Ubuntu 9.3.0-17ubuntu1~20.04) 9.3.0 we get:
error: ‘retval’ may be used uninitialized in this function

fixes: 13cd75b6ec (flash/nor/stm32xx: fix segfault accessing Cortex-M part number)
Change-Id: I897c40c5d2233f50a5385d251ebfa536023e5cf7
Signed-off-by: Tarek BOCHKATI <tarek.bouchkati@gmail.com>
Reviewed-on: https://review.openocd.org/c/openocd/+/6861
Tested-by: jenkins
Reviewed-by: Tomas Vanek <vanekt@fbl.cz>
Reviewed-by: Antonio Borneo <borneo.antonio@gmail.com>

* Fix build.

Change-Id: Ia60246246dd859d75659a43d1c59588dbb274d46
Signed-off-by: Tim Newsome <tim@sifive.com>

Co-authored-by: Hans-Erik Floryd <hans-erik.floryd@rt-labs.com>
Co-authored-by: Julien Massot <julien.massot@iot.bzh>
Co-authored-by: Pavel Kirienko <pavel.kirienko@gmail.com>
Co-authored-by: Zoltán Dudás <zedudi@gmail.com>
Co-authored-by: Antonio Borneo <borneo.antonio@gmail.com>
Co-authored-by: Jacek Wuwer <jacekmw8@gmail.com>
Co-authored-by: Ben McMorran <bemcmorr@microsoft.com>
Co-authored-by: Simon Johansson <ampleyfly@gmail.com>
Co-authored-by: Tomas Vanek <vanekt@fbl.cz>
Co-authored-by: Sean Anderson <sean.anderson@seco.com>
Co-authored-by: Tarek BOCHKATI <tarek.bouchkati@gmail.com>
 		2022-03-03 10:03:55 -08:00
.github/workflows Don't use oscan1 on 32-bit build. 2021-12-13 13:36:06 -08:00
LICENSES From upstream (#620) 2021-06-11 13:01:55 -07:00
contrib Merge branch 'master' into from_upstream 2021-12-28 10:45:40 -08:00
doc From upstream (#684) 2022-03-03 10:03:55 -08:00
git-hooks Attempt to enforce signed-off-by lines in commits. (#523) 2020-09-10 13:55:45 -07:00
jimtcl@70b007b636 jimtcl: update to version 0.81 (2021-11-28) 2021-12-03 21:47:07 +00:00
src From upstream (#684) 2022-03-03 10:03:55 -08:00
tcl From upstream (#684) 2022-03-03 10:03:55 -08:00
testing Remove remaining references to FTD2XX driver 2021-11-05 22:44:19 +00:00
tools Properly handle held-in-reset targets. (#654) 2021-10-21 17:08:49 -07:00
.gitignore gitignore: Add GNU Global tag files 2021-10-02 13:18:34 +00:00
.gitmodules .gitmodules: switch away from repo.or.cz 2022-02-10 10:29:16 -08:00
.travis.yml RISC-V Freertos support (#582) 2021-03-05 15:52:33 -08:00
AUTHORS Add AUTHORS for 0.2.0 release. 2009-07-02 11:17:21 +00:00
AUTHORS.ChangeLog Add AUTHORS.ChangeLog file suitable to be passed to 'svn2cl --authors'. 2009-07-02 11:18:45 +00:00
BUGS docs: update OpenOCD url's to openocd.org domain 2015-04-16 20:28:21 +01:00
COPYING LICENSES: add 'license-rules.txt' 2021-04-11 20:52:43 +01:00
ChangeLog fix typos in documentation 2009-11-26 10:12:22 -08:00
Doxyfile.in From upstream (#580) 2021-02-11 11:27:18 -08:00
HACKING Merge branch 'master' into from_upstream 2021-10-05 17:46:02 -07:00
Makefile.am Merge branch 'master' into from_upstream 2021-11-30 10:38:55 -08:00
NEWS Restore normal development cycle 2021-03-07 15:44:45 +03:00
NEWS-0.2.0 whitespace cleanup, mostly for docs 2009-12-30 11:51:29 -08:00
NEWS-0.3.0 Version 0.4.0-dev 2009-11-04 19:44:36 -08:00
NEWS-0.4.0 Open the merge window for the 0.5.0 release cycle. 2010-02-21 13:27:37 -08:00
NEWS-0.5.0 coding style: doc: remove empty lines at end of text files 2020-02-24 10:31:29 +00:00
NEWS-0.6.0 Restore -dev suffix, archive NEWS file, add new blank NEWS file - start 2012-09-07 11:04:05 +02:00
NEWS-0.7.0 Restore normal development cycle 2013-05-05 10:45:03 +02:00
NEWS-0.8.0 Restore normal development cycle 2014-04-27 15:07:08 +04:00
NEWS-0.9.0 Restore normal development cycle 2015-05-18 00:34:18 +03:00
NEWS-0.10.0 Restore normal development cycle 2017-01-23 00:46:51 +03:00
NEWS-0.11.0 Restore normal development cycle 2021-03-07 15:44:45 +03:00
NEWTAPS Fix spelling of ARM Cortex 2016-05-20 21:38:03 +01:00
README openocd: drop dependency from libusb0 2021-04-05 23:25:34 +01:00
README.Windows openocd: drop dependency from libusb0 2021-04-05 23:25:34 +01:00
README.macOS openocd: drop dependency from libusb0 2021-04-05 23:25:34 +01:00
TODO swim: add new transport 2020-05-24 21:32:05 +01:00
bootstrap Remove gnulib. (#615) 2021-05-28 13:24:51 -07:00
config_subdir.m4 From upstream (#620) 2021-06-11 13:01:55 -07:00
configure.ac From upstream (#684) 2022-03-03 10:03:55 -08:00
guess-rev.sh guess-rev.sh: fix minor typo 2019-05-23 22:14:30 +01:00
uncrustify.cfg build: update uncrustify config 2012-02-06 10:40:25 +00:00

README 

Welcome to OpenOCD!
===================

OpenOCD provides on-chip programming and debugging support with a
layered architecture of JTAG interface and TAP support including:

- (X)SVF playback to facilitate automated boundary scan and FPGA/CPLD
  programming;
- debug target support (e.g. ARM, MIPS): single-stepping,
  breakpoints/watchpoints, gprof profiling, etc;
- flash chip drivers (e.g. CFI, NAND, internal flash);
- embedded TCL interpreter for easy scripting.

Several network interfaces are available for interacting with OpenOCD:
telnet, TCL, and GDB. The GDB server enables OpenOCD to function as a
"remote target" for source-level debugging of embedded systems using
the GNU GDB program (and the others who talk GDB protocol, e.g. IDA
Pro).

This README file contains an overview of the following topics:

- quickstart instructions,
- how to find and build more OpenOCD documentation,
- list of the supported hardware,
- the installation and build process,
- packaging tips.


============================
Quickstart for the impatient
============================

If you have a popular board then just start OpenOCD with its config,
e.g.:

  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/stlink.cfg -c "transport select hla_swd" \
          -f target/stm32l0.cfg

After OpenOCD startup, connect GDB with

  (gdb) target extended-remote localhost:3333


=====================
OpenOCD Documentation
=====================

In addition to the in-tree documentation, the latest manuals may be
viewed online at the following URLs:

  OpenOCD User's Guide:
    http://openocd.org/doc/html/index.html

  OpenOCD Developer's Manual:
    http://openocd.org/doc/doxygen/html/index.html

These reflect the latest development versions, so the following section
introduces how to build the complete documentation from the package.

For more information, refer to these documents or contact the developers
by subscribing to the OpenOCD developer mailing list:

	openocd-devel@lists.sourceforge.net

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


==================
Supported hardware
==================

JTAG adapters
-------------

AICE, ARM-JTAG-EW, ARM-USB-OCD, ARM-USB-TINY, AT91RM9200, axm0432, BCM2835,
Bus Blaster, Buspirate, Cadence DPI, Chameleon, CMSIS-DAP, Cortino,
Cypress KitProg, DENX, Digilent JTAG-SMT2, DLC 5, DLP-USB1232H,
embedded projects, eStick, FlashLINK, FlossJTAG, Flyswatter, Flyswatter2,
FTDI FT232R, Gateworks, Hoegl, ICDI, ICEBear, J-Link, JTAG VPI, JTAGkey,
JTAGkey2, JTAG-lock-pick, KT-Link, Linux GPIOD, Lisa/L, LPC1768-Stick,
Mellanox rshim, MiniModule, NGX, Nuvoton Nu-Link, Nu-Link2, NXHX, NXP IMX GPIO,
OOCDLink, Opendous, OpenJTAG, Openmoko, OpenRD, OSBDM, Presto, Redbee,
Remote Bitbang, RLink, SheevaPlug devkit, Stellaris evkits,
ST-LINK (SWO tracing supported), STM32-PerformanceStick, STR9-comStick,
sysfsgpio, TI XDS110, TUMPA, Turtelizer, ULINK, USB-A9260, USB-Blaster,
USB-JTAG, USBprog, VPACLink, VSLLink, Wiggler, XDS100v2, Xilinx XVC/PCIe,
Xverve.

Debug targets
-------------

ARM: AArch64, ARM11, ARM7, ARM9, Cortex-A/R (v7-A/R), Cortex-M (ARMv{6/7/8}-M),
FA526, Feroceon/Dragonite, XScale.
ARCv2, AVR32, DSP563xx, DSP5680xx, EnSilica eSi-RISC, EJTAG (MIPS32, MIPS64),
Intel Quark, LS102x-SAP, NDS32, RISC-V, ST STM8.

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,
i.MX31, Kinetis, LPC8xx/LPC1xxx/LPC2xxx/LPC541xx, LPC2900, LPC3180, LPC32xx,
LPCSPIFI, Marvell QSPI, MAX32, Milandr, MXC, NIIET, nRF51, nRF52 , NuMicro,
NUC910, Orion/Kirkwood, PIC32mx, PSoC4/5LP/6, Renesas RPC HF and SH QSPI,
S3C24xx, S3C6400, SiM3x, SiFive Freedom E, Stellaris, ST BlueNRG, STM32,
STM32 QUAD/OCTO-SPI for Flash/FRAM/EEPROM, STMSMI, STR7x, STR9x, SWM050,
TI CC13xx, TI CC26xx, TI CC32xx, TI MSP432, Winner Micro w600, Xilinx XCF,
XMC1xxx, XMC4xxx.


==================
Installing OpenOCD
==================

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
you in a convenient-enough package.

Such packages may be more stable than git mainline, where
bleeding-edge development takes place. These "Packagers" produce
binary releases of OpenOCD after the developers produces new "release"
versions of the source code. Previous versions of OpenOCD cannot be
used to diagnose problems with the current release, so users are
encouraged to keep in contact with their distribution package
maintainers or interface vendors to ensure suitable upgrades appear
regularly.

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

You are a PACKAGER of OpenOCD if you:

- Sell dongles and include pre-built binaries;
- Supply tools or IDEs (a development solution integrating OpenOCD);
- Build packages (e.g. RPM or DEB files for a GNU/Linux distribution).

As a PACKAGER, you will experience first reports of most issues.
When you fix those problems for your users, your solution may help
prevent hundreds (if not thousands) of other questions from other users.

If something does not work for you, please work to inform the OpenOCD
developers know how to improve the system or documentation to avoid
future problems, and follow-up to help us ensure the issue will be fully
resolved in our future releases.

That said, the OpenOCD developers would also like you to follow a few
suggestions:

- Send patches, including config files, upstream, participate in the
  discussions;
- Enable all the options OpenOCD supports, even those unrelated to your
  particular hardware;
- Use "ftdi" interface adapter driver for the FTDI-based devices.


================
Building OpenOCD
================

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.

The remainder of this document tries to provide some instructions for
those looking for a quick-install.

OpenOCD Dependencies
--------------------

GCC or Clang is currently required to build OpenOCD. The developers
have begun to enforce strict code warnings (-Wall, -Werror, -Wextra,
and more) and use C99-specific features: inline functions, named
initializers, mixing declarations with code, and other tricks. While
it may be possible to use other compilers, they must be somewhat
modern and could require extending support to conditionally remove
GCC-specific extensions.

You'll also need:

- make
- libtool
- pkg-config >= 0.23 (or compatible)

Additionally, for building from git:

- autoconf >= 2.69
- automake >= 1.14
- texinfo >= 5.0

USB-based adapters depend on libusb-1.0. A compatible implementation, such as
FreeBSD's, additionally needs the corresponding .pc files.

USB-Blaster, ASIX Presto and OpenJTAG interface adapter
drivers need:
  - libftdi: http://www.intra2net.com/en/developer/libftdi/index.php

CMSIS-DAP support needs HIDAPI library.

Permissions delegation
----------------------

Running OpenOCD with root/administrative permissions is strongly
discouraged for security reasons.

For USB devices on GNU/Linux you should use the contrib/60-openocd.rules
file. It probably belongs somewhere in /etc/udev/rules.d, but
consult your operating system documentation to be sure. Do not forget
to add yourself to the "plugdev" group.

For parallel port adapters on GNU/Linux and FreeBSD please change your
"ppdev" (parport* or ppi*) device node permissions accordingly.

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

To build OpenOCD, use the following sequence of commands:

  ./bootstrap (when building from the git repository)
  ./configure [options]
  make
  sudo make install

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
the files in the required location.

To see the list of all the supported options, run
  ./configure --help

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]

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

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.

For a more or less complete script that does all this for you, see

  contrib/cross-build.sh

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
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
if you want to use giveio instead of ioperm parallel port access
method.


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

You may prefer to use a mirror:

   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

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

Snapshots are compressed tarballs of the source tree, about 1.3 MBytes
each at this writing.