How to build RISC-V OpenOCD on macOS.
Information
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.
The OpenOCD User's Guide: https://openocd.org/doc/pdf/openocd.pdf
Operating system used
macOS Monterey
Software prerequisites
Homebrew
Procedure
- In this tutorial I will demonstrate how to build the RISC-V OpenOCD on macOS (Monterey).
- First check which shell your Mac is using:
Type: echo $0
If the shell is not bash, change the default shell to bash by running the following command:
Type: chsh -s /bin/bash
- Installing the Mac OSX Command Line Tools, type:
xcode-select --install
- The following tools are required:
autoconf, automake, pkg-config, libtool and texinfo.
To check if the tool is installed:
which <tool>
These are my installed tool information:
- autoconf
Automatic configure script builder
which autoconf
/opt/local/bin/autoconf
autoconf --version
autoconf (GNU Autoconf) 2.71
If not found, install this tool: brew install autoconf
- automake
Tool for generating GNU Standards-compliant Makefiles
which automake
/opt/local/bin/automake
automake --version
automake (GNU automake) 1.16.3
If not found, install this tool: brew install automake
- pkg-config
pkg-config is a helper tool used when compiling applications and libraries.
which pkg-config
/opt/local/bin/pkg-config
pkg-config --version
0.29.2
If not found, install this tool: brew install pkg-config
- libtool
Generic library support script
which libtool
/usr/local/opt/libtool/libexec/gnubin/libtool
libtool --version
GNU gperf 3.0.3
This tool is installed with the Mac OSX Command Line Tools.
- texinfo
Official documentation format of the GNU project
brew info texinfo
texinfo: stable 6.8 (bottled) [keg-only]
Official documentation format of the GNU project
https://www.gnu.org/software/texinfo/
/usr/local/Cellar/texinfo/6.8 (409 files, 7.6MB)
texinfo is keg-only, which means it was not symlinked into /usr/local,
because macOS already provides this software and installing another
version in parallel can cause all kinds of trouble.
If you need to have texinfo first in your PATH, run:
echo 'export PATH="/usr/local/opt/texinfo/bin:$PATH"' >> /Users/robertlie/.bash_profile
If not found, install this tool: brew install texinfo
Update PATH in .bash_profile
Type: cd ~
Type: nano .bash_profile
Type: export PATH=/usr/local/opt/texinfo/bin:$PATH
- Create directories ~/riscv_openocd
Type: cd ~
Type: mkdir riscv_openocd
Type: cd riscv_openocd
Type: mkdir install
- Clone riscv-openocd.git:
Type: git clone --recursive https://github.com/riscv/riscv-openocd.git
Type: cd riscv-openocd
To show the last commit on this branch, type: git log
commit cc0ecfb6d5b939bd109ea84b07b5eab3cdf80316 (HEAD -> riscv, origin/riscv, origin/HEAD)
Merge: 54c951d7f d27d66bc1
Author: Tim Newsome <[email protected]>
Date: Tue Dec 28 10:45:40 2021 -0800
- Create the Makefile.
Type: ./bootstrap nosubmodule
Type: ./configure --prefix=`pwd`/../install
Output: build_riscv_openocd.txt
Note:
The ~/riscv_openocd/riscv-openocd/configure tool is a shell script.
More information about the many configure options, type: ./configure --help
See also: configure_riscv_openocd_help.txt
- Build OpenOCD, it will take approximately 1 minute depending on your machine. There are no errors.
Type: make -j`nproc`
- Install OpenOCD at ~/riscv_openocd/install.
Type: cd ~/riscv_openocd/riscv-openocd
Type: make install
This is what you see in the install directory:
- Show OpenOCD help.
Type: cd ~/riscv_openocd/riscv-openocd/install/bin
Type: ./openocd --help
See: riscv_openocd_help.txt
- Show OpenOCD version.
Type: cd ~/riscv_openocd/riscv-openocd/install/bin
Type: ./openocd --version
Open On-Chip Debugger 0.11.0+dev-02215-gcc0ecfb6d (2022-01-19-15:17)
Licensed under GNU GPL v2
For bug reports, read
http://openocd.org/doc/doxygen/bugs.html
- Update PATH in .bash_profile
Type: cd ~
Type: nano .bash_profile
Type: export PATH=$PATH:/Users/robertlie/riscv_openocd/install/bin
- I modified sipeed-rv-debugger.cfg.
This configuration file was used in tutorial:
Using Sipeed RV Debugger Plus to upload firmware and to debug code
Download the modified configuration file: sipeed-rv-debugger2.cfg and put this file into folder:
/Users/robertlie/riscv_openocd/install/bin
- Connect the Sipeed RV Debugger Plus (on the left) to the Sipeed Longan Nano Development Board (on the right) using 8 female-female jumper wires (12 cm long).
Connect the USB cable to my macbook.
More information about:
Sipeed Longan GD32VF103CBT6 MCU Nano RISC-V Development Board
Sipeed RV Debugger Plus
Connections required to upload firmware to the Sipeed Longan Nano Development Board
| GND |
GND |
| 3V3 |
3V3 |
| TX |
RO |
| RX |
TO |
| DTR (Not connected) |
- |
| RTS (Not connected) |
- |
The Sipeed RV Debugger Plus provides 3V3 to the Sipeed Longan Nano Development Board.
If the provided 3V3 (by Sipeed RV Debugger Plus) is not sufficient when you connect many other hardware components to the development board,
disconnect the 3V3 jumper wire and connect the USB A - USB C cable to the Sipeed Longan Nano Development Board as its power source.
Keep the ground jumper wire connected.
Connections required to debug code
| GND (Not connected) |
- |
| 5V (Not connected) |
- |
| TCK |
JTCK |
| TDI |
JTDI |
| TDO |
JTDO |
| TMS |
JTMS |
- Check if OpenOCD detects the Sipeed Longan Nano board.
Type: cd ~
Type: openocd -f ~/riscv_openocd/install/bin/sipeed-rv-debugger2.cfg
Open On-Chip Debugger 0.11.0+dev-02215-gcc0ecfb6d (2022-01-19-15:17)
Licensed under GNU GPL v2
For bug reports, read
http://openocd.org/doc/doxygen/bugs.html
gd32vf103.cpu
Info : Listening on port 6666 for tcl connections
Info : Listening on port 4444 for telnet connections
Info : clock speed 1000 kHz
Info : JTAG tap: gd32vf103.cpu tap/device found: 0x1000563d
(mfg: 0x31e (Andes Technology Corporation), part: 0x0005, ver: 0x1)
Info : JTAG tap: gd32vf103.bs tap/device found: 0x790007a3
(mfg: 0x3d1 (GigaDevice Semiconductor (Beijing) Inc), part: 0x9000, ver: 0x7)
Info : [gd32vf103.cpu] datacount=4 progbufsize=2
Info : Examined RISC-V core; found 1 harts
Info : hart 0: XLEN=32, misa=0x40901105
[gd32vf103.cpu] Target successfully examined.
Info : starting gdb server for gd32vf103.cpu on 3333
Info : Listening on port 3333 for gdb connections
Note 1:
If the Sipeed Longan Nano is not detected:
- Press BOOT key and keep it pressed.
- Shortly press and immediately release the RESET button.
- Then release the BOOT button.
Note 2:
If you get the following error:
Error: couldn't bind tcl to socket on port 6666: Address already in use
Report a list of all open files and the processes that opened them.
Type: lsof -i :6666
Write down the pid_number.
Type: kill -9 pid_number
- Open a new Terminal.
- To stop OpenOCD, press: CTRL + C
|
