Olimex Debugger User's Manual 翻译与总结

Olimex 推出的 ARM-USB-TINY-H 是一款 OPENOCD ARM JTAG DEBUGGERS,也是 Bitcraze 官方实验也是我们所使用的 JTAG Debugger,这份 USER’S MANUAL 也是重要的参考来源。
以下内容基于版本 Document revision G, October 2020,是对其中值得注意的内容的翻译与再总结。

Chapter 1: Overview

Basic Information

  • ARM-USB-TINY-H 与 ARM-USB-TINY 两款产品基本上没什么区别,唯一的区别是ARM-USB-TINY-H 在于其名字中的 H 代表 HighSpeed,即拥有更低的延迟,RTCK的 JTAG 时钟达到30Mhz,并且相比普通版有 3-5 倍快的编程吞吐量。
  • Programmer/Debugger 是 ARM MCU 开发不可缺少的工具, ARM-USB-TINY是一款利用 OS 上的 Openocd 来利用板子上的 JTAG 接口进行软硬件开发的产品。
  • 可以为开发板供电。
  • 除了 JTAG 接口,还有 SWD 接口有相同的功能。可以使用 adapter 将 JTAG 信号转换成 SWD 信号利用我们的 debugger 进行调试。

Comparison among 4 Debuggers

img

  • ARM-USB-TINY-H更被推荐用于家庭使用,研究与开发
  • 四款产品拥有相同的 Vendor ID,以及不同的 Product ID。(USB 接口设备有一个 ID 数据库

img

Chapter 2: Device Description

LED

Debugger 有一个红色的 LED 灯在 JTAG 接口端。通电后会亮,正在进行读写操作时会闪烁。

Ports and Connectors

Ports 指 Debugger 自身的两个端口,USB-B 与 JTAG 20 male
Connectors 指将 Debugger 连接到 PC 和开发板的线。在我们的场景下,分别需要 USB A-B,JTAG 20-10 adapter 线。

  • Port: USB Type B

    • 需要一根 USB A-B 线来连接到 PC
    • USB 连接基于其中的一块 FTDI Chip,driver需要更改 VID 与 PID 使用上面提供的 Olimex 对应的 ID。
  • Port: JTAG

    • 是一个 20 口的公线(有针的是 male,有孔的是 female)
    • 2.54mm间距(IEEE 1149.1)
    • 注意 JTAG 线因为形状原因无法直接分辨正反。通常会用一些手段,比如 Debugger 的 JTAG端会有一个卡槽与连接线对应。同时连接线也有标红的一根线来表明这是 1 号线。
    • JTAG 端的引脚如图

img

      • PIN1 和 PIN2 用于探测目标板是否已经被供电,如果没有,通过 PIN19 来供电。USB 允许有限的供电输出功率,对于更大的板子还是希望通过外部的供电方式来进行。
    • JTAG 接口通常是 20PIN (2.54mm)或者是 mini 版本的 10PIN(1.27mm)。我们的 AI-deck 就是 mini 版本的,所以还需要一个 20-10 的转接器。

Chapter 3: Setting up ARM-USB-TINY

Hardware Requirement

  • 我们得有一块开发板/MCU和一台 PC 才能完成 debug/programming 任务

  • ARM-USB-TINY 附带一根 20-20 pin female-female 2.54mm/0.1inch connector 线

  • ARM-USB-TINY 不附带 USB Type A-B 线

  • 需要的硬件根据实际情况会有所不同,例如

    • 需要 JTAG 20-10 pin adapter 如果板子上的 JTAG 调试接口是 mini 接口
    • 需要 JTAG-SWD adapter 如果板子只支持 SWD 信号

Software Configuration

OpenOCD

    • 可以看出 ARM-USB-TINY 默认就是为 OpenOCD 这一软件 tool 服务的
    • 不同系统有不同方式,对于 Mac 的话就是简单的brew install openocd
    • 也可以选择自行 compile 的方式还实现更多自定义配置

Driver

    • 使用 USB 就需要 driver
    • 有很多可用的 driver(因为最初使用的是 FTDI 的 driver,不是开源的,与 OpenOCD 的开源理念违背,所以有很多人自发编写维护了很多 driver)
    • Driver installation in Windows 在 Page 14-16
    • Driver installation in Linux 在 Page 16-17
    • Driver installation in MAC OS X 在 Page 17-18

Driver installation in MAC OS X

  • MacOS 的 driver 主要在

    • /System/Library/Extensions/目录下的 Kernel 插件
    • Application Bundle 中
  • kextunload可以卸载 Kernal 插件

  • kextstat可以查看被加载的 Kernal 插件

验证 USB 被识别可以点击 –>关于本机–>系统报告–>硬件–>USB 查看是否有目标 USB
或者在命令行输入 ​lsusb​ 查看

Basic OpenOCD connection

  • 最容易判断 debugger 软硬件安装是否正确的方式还是建立一个到目标的连接,连接建立后

    • 可以本地或者远程地访问 GDB server
    • 可以使用 telnet 访问 server 来执行 debug
    • 可以配置一个图形界面连接到 GDB server

Starting OpenOCD GDB server via FTDI drivers

这是 0.8.0 及之后版本的 OpenOCD 默认使用的连接方式

例如,使用 openocd 在 ARM-USB-TINY-H 和一个 STM32F1 开发板之间建立连接

1
openocd-x64-0.8.0.exe -f ./interface/ftdi/olimex-arm-usb-tiny-h.cfg -f ./target/stm32f1x.cfg

我们需要指明可执行程序的文件夹

典型的成功响应例如

1
2
3
Info: JTAG tap: stm32f1x.cpu tap/device found: 0x3ba00477 (mfg: 0x23b, part: 0xba00, ver: 0x3)
Info: JTAG tap: stm32f1x.bs tap/device found: 0x06418041 (mfg: 0x020, part: 0x6418, ver: 0x0)
Info: stm32f1x.cpu: hardware has 6 breakpoints, 4 watchpoints

TAP是开发板上的组件,用于 debug 调试,有支持 JTAG 的,也有支持 SWD 的。可能不止一个。

连接建立成功后(即 GDB Server 启动成功后)可以再开启一个终端使用 telnet 连接到默认端口 4444,使用细节可以参考 Using OpenOCD with TELNET connection

Starting OpenOCD GDB server via LibUSB drivers

这是 0.8.0 之前版本的 OpenOCD 默认使用的连接方式

同样,建立连接的命令(接口配置文件地址不一样)

1
openocd -f interface/olimex-arm-usb-tiny-h.cfg -f target/stm32f1x.cfg

成功后的响应结果

1
2
3
Info : JTAG tap: stm32f1x.cpu tap/device found: 0x3ba00477 (mfg: 0x23b, part: 0xba00, ver: 0x3)
Info : JTAG tap: stm32f1x.bs tap/device found: 0x06418041 (mfg: 0x020, part: 0x6418, ver: 0x0)
Info : stm32f1x.cpu: hardware has 6 breakpoints, 4 watchpoints

Starting OpenOCD GDB to a SWD target connection with ARM-JTAG-SWD

0.9.0 及之后版本的 OpenOCD 增加了对 SWD 的支持

建立连接的命令

1
openocd -f interface/ftdi/olimex-arm-usb-tiny-h.cfg -f interface/ftdi/olimexarm-jtag-swd.cfg -f target/stm32f1x.cfg

成功后的响应结果

1
2
3
Info : FTDI SWD mode enabled adapter speed: 1000 kHz adapter_nsrst_delay: 100 cortex_m reset_config sysresetreq
Info : clock speed 1000 kHz
Info : SWD IDCODE 0x1ba01477 Info : stm32f1x.cpu: hardware has 6 breakpoints, 4 watchpoints

Advanced OpenOCD practices

Using multiple ARM-USB-TINY interfaces

在同一台 PC 上使用多个同款 debugger 也是可以的,虽然他们的 VendorID 和 ProductID 都是相同的,但是可以根据 serial numbers(序列号)来进行区分。在 Linux 下使用lsusb -v就能看到序列号。

如果有多个同款 debugger 被同时使用,我们需要为每个 debugger 分别编写 cfg 接口配置文件,在文件内指定目标的序列号,例如如下两个 cfg 文件即可区分同型号的两个 debugger:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
-olimex-arm-usb-tiny-h1.cfg

interface ftdi
ftdi_device_desc "Olimex OpenOCD JTAG ARM-USB-TINY-H"
ftdi_vid_pid 0x15ba 0x002a
ftdi_serial OLYMTEEY


-olimex-arm-usb-tiny-h2.cfg

interface ftdi
ftdi_device_desc "Olimex OpenOCD JTAG ARM-USB-TINY-H"
ftdi_vid_pid 0x15ba 0x002a
ftdi_serial OLYMTGH5

Changing the VID and PID of the debugger

修改 debugger 的 VID 与 PID 对于初学者是不推荐的,因为很有可能改不回来~
一般的使用场景并不需要我们修改 ID,所以这是不被推荐的行为

修改 VID 和 PID 不需要硬件工具,通过软件就可以改变。

一旦修改了 ID,drivers 和 script 也得跟着修改,需要一个新的 driver。

完成修改需要一个软件:MProg。具体细节请查看原文档 Page22-23。

Some graphical tools

有几款界面工具可以帮助我们可视化地看到调试信息。

  • IAR Embedded Workbench for ARM

    • 商业版,可免费试用一段时间
  • Rowley Crossworks for ARM

    • 推荐配合 FTDI 驱动使用,虽然也支持 LibUSB 驱动
    • 支持 ARM-JTAG-SWD 转换器
  • STM32CubeIDE

  • CooCox IDE (discontinued)

    • 停止维护
  • Olimex Open Development Suite (ODS) package (discontinued)

    • 停止维护

Chapter 4: Frequently Asked Questions

  • A: What USB cable do I need?

    • 我应该用什么 USB 线?
  • Q: You should have a USB type A-B cable to connect to PC, all PC USB hosts have USB-A connector while ARM-USB-TINY has USB-B connector so the cable should be USB A-to-B type. Note that such a cable is not included in the package.

    • 您应该有一个 USB A-B 的线连接到PC。所有的 PC USB 接口都是 USB-A 接口,而 ARM-USB-TINY 则是 USB-B 接口,所以 USB 线应该是 USB A-to-B 型。请注意,包装中没有这根线。
  • Q: Does your JTAG connector layout differ from the JTAG connector layout of other debuggers?

    • 你们的 JATG 连接器的针脚布局与其他的 debugger 有什么区别吗?
  • A: No. It is the standard 20-pin ARM JTAG layout.

    • 不。它就是标准的 20-pin ARM JTAG 的布局。
  • Q: What are the LEDs for?

    • LED 灯的用途是?
  • A: The LED is mainly meant to indicate programming/debugging in progress. The red LED should blink when you have an on-going operation (read, write).

    • LED 的主要目的是指明是否正在进行 programming/debugging。当我们进行读写操作时红色的 LED 灯会闪烁。
  • Q: I have downloaded the latest version of OpenOCD but there is no configuration for my target. Send me one please.

    • 我已经下载了最新版本的 OpenOCD,但是里面没有适配我的调试对象的配置文件,请发给我一个。
  • A: We commit or forward everything we have done directly to the OpenOCD repositories. If you can’t find a suitable cfg there – you are out of luck. You either have write it yourself or ask politely somebody at the OpenOCD community to do it for you.

    • 我们将所做的一切直接提交或转发到了 OpenOCD 库。如果你在那里找不到合适的 cfg 配置文件,那你就有点不幸。你要么自己写,要么礼貌地请 OpenOCD 社区的人帮你写。
  • Q: I can’t write proper makefile for my board under your Eclipse-like IDE. Can you please write it for me?

    • 我写不出来适合我的开发板的 Makefile 在你们的类 Eclipse IDE 环境下。可以请你们为我写一个吗?
  • A: No. That’s the bad (good?) side of open software – it is a community effort – everybody has to write and commit something. You learn something in the end, however.

    • 不可以。这就是开源软件好或不好的一点,它需要一个社区的努力,每个人都得为社区贡献些东西。当然,你最终也会学到一些东西。
  • Q: I have LPC1227 board and can’t program it with your OpenOCD debugger. What do I do wrong?

    • 我有一个 LPC1227 开发板但是不能用你们的 OpenOCD 调试器,我做错了什么?
  • A: LPC1227 lacks JTAG according to the microcontroller’s datasheet. The board can be programmed only via SWD (Serial Wire Debug) interface. Olimex OpenOCD debuggers have JTAG by default. You would need an additional adapter – ARM-JTAG-SWD.

    • 根据参数表来看,LPC1227 缺少 JTAG 接口。这块开发板只能通过 SWD 接口来编程。Olimex OpenOCD 的 debugger 默认支持 JTAG。你需要一个附加的转接器——ARM-JTAG-SWD。
  • Q: Howdy, guys. I can’t program my MSP430 and PIC16 boards with your robust debugger. I need help ASAP.

    • 你好。我用不了你们强大的 debugger 来编程我的 MSP430 和 PIC16 开发板。我需要尽快的帮忙。
  • A: Technically, it is possible to program targets different than ARM using our OpenOCD debugger. Practically, almost all users use the debugger for ARM programming and only ARM targets are officially supported. There is a reason that the prefix in the name of the debugger is ‘ARM-‘.

    • 从技术上讲,使用我们的 OpenOCD 调试器可以编程非 ARM 架构的目标。实际上,几乎所有用户都使用调试器进行ARM编程,只有ARM目标才得到官方支持。调试器名称中的前缀是“ARM-”是有原因的。

Chapter 5: Revision History and Support

Revision History

  • 第一版始于 2014.07.16,此文对应的是 2020.10.08 出版的 Document Revision G

我们在其全球经销商,贸泽电子 MOUSER ELECTRONICS 购买过,还不错。美国仓库发货,比淘宝便宜但是耗时久一些。