0. 前言

終於來到正式文章的第一篇，當然開始之前還是要先來廢話暖身一下!!!

1. OpenOCD Introduction

1.1 講古

不免俗地還是要來講古一下，算是用來擴充篇幅用的，
順便練習打字(Markdown的使用)!
  

OpenOCD，原名為Open On-Chip Debugger，
為Dominic Rath在奧格斯堡應用技術大學的畢業論文(diploma thesis )所做。

OpenOCD目前所使用的授權為GNU General Public License version 2.0 (GPLv2)，其他詳細授權內容可以參考原始碼中的README中的說明，這邊不再多加著墨。

巴拉巴拉巴拉巴拉巴拉巴拉巴拉巴拉巴拉，其他省略不重要
  
  

1.2 文件

常用的參考文件有以下兩份

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

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

1.3 其他資料

OpenOCD User’s Forum (https://forum.sparkfun.com/viewforum.php?f=18)

OpenOCD User’s Mailing List (https://lists.sourceforge.net/mailman/listinfo/openocd-user)

OpenOCD IRC (irc://irc.freenode.net/openocd)
  
  
  

02. 開發工具簡介

2.1 環境簡介

目前所使用的環境為Ubuntu 16.04，不過之前開發的經驗，其他Linux環境也行，
例如: CentOS 6.8

根據OpenOCD開發文件的README中，為了能夠順利編譯OpenOCD，需要下列套件
注意版本問題，要不然很容易在bootstrap的過程中遇到錯誤

• make
• libtool (通常我用2.4)
• pkg-config >= 0.23
• autoconf >= 2.64 (比較詭異的是我用2.65比較不會出現問題)
• automake >= 1.9
    
    

2.2 相關Source Code位置

1. libusb-0.18 (https://github.com/libusb/libusb.git)
2. RISC-V OpenOCD (https://github.com/riscv/riscv-openocd.git)
   **原OpenOCD官方Repo在 (http://repo.or.cz/openocd.git)，
   這邊使用RISC-V官方所維護的版本 **
     
     

2.3 通用OpenOCD編譯流程 (參考README中相關說明)

./bootstrap
./configure [options]
make
sudo make install
  
  

2.4 編譯用Script(build.sh)

這邊提供一個從Clone Source Code到編譯完成的完整Script

#!/bin/bash

# Parameter
# $1: build-dir (must)
# $2: source-dir (must)
# $3: 1 for checkout source code (must)


# How to run?
if [ $# -lt 2 ]; then
    echo "<Usage>: $0 build-dir source-dir [need_clone 0/1?]"
    exit 1
fi


# Param
BUILD_DIR=`readlink -f $1`
SOURCE_DIR=`readlink -f $2`
UNAMESTR=`uname`

# Setup Source path
LIBUSB_SRC_1=$SOURCE_DIR/libusb-1.0.18
OPENOCD_SRC=$SOURCE_DIR/openocd


# Clean build/source folder
rm -rf $BUILD_DIR


# Clone source or not
if [ "$3" == '1' ]; then
    CLONE_FLAG="--recursive"

    rm -rf $SOURCE_DIR
    wget https://ncu.dl.sourceforge.net/project/libusb/libusb-1.0/libusb-1.0.18/libusb-1.0.18.tar.bz2 -P $SOURCE_DIR --no-check-certificate
    git clone $CLONE_FLAG https://github.com/riscv/riscv-openocd.git $OPENOCD_SRC
else
    echo 'Do not clone openocd source codes'
fi


# Build libusb-1.0.18
printf "\n\n\nBuild libusb-1.0.18\n"
tar -jxf $SOURCE_DIR/libusb-1.0.18.tar.bz2 -C $SOURCE_DIR
mkdir -p $BUILD_DIR/build/libusb
cd $BUILD_DIR/build/libusb
$LIBUSB_SRC_1/configure --prefix=$BUILD_DIR/usr PKG_CONFIG_LIBDIR=$BUILD_DIR/usr/lib/pkgconfig --disable-shared --disable-udev --disable-timerfd 
make install -j8


# Build RISC-V OpenOCD
printf "\n\n\nBuild OpenOCD\n"
cd $OPENOCD_SRC
patch -p1 < openocd.patch
./bootstrap
mkdir -p $BUILD_DIR/build/openocd
cd $BUILD_DIR/build/openocd
$OPENOCD_SRC/configure --prefix=$BUILD_DIR/usr PKG_CONFIG_LIBDIR=$BUILD_DIR/usr/lib/pkgconfig --disable-aice --disable-ti-icdi --disable-jlink --disable-osbdm --disable-opendous --disable-vsllink --disable-usbprog --disable-rlink --disable-ulink --disable-armjtagew --disable-usb-blaster-2 --enable-stlink --enable-ftdi
make -j8
make install-strip

使用方法:
./build.sh build src 1 --> 包含clone source code
./build.sh build src --> 純build code

執行檔會在build/usb/bin中!
另外需要注意一下Linux權限問題，由於OpenOCD需要使用到USB周邊裝置，
通常需要使用root權限來執行或是參考附錄A.的說明
  
  
  

03. OpenOCD Developer

3.1 相關文件

我覺得最重要的應該就屬下面這份
OpenOCD Developer's Guide (http://openocd.org/doc-release/doxygen/index.html)

尤其其中的C Style Guide可以參考一下(http://openocd.org/doc-release/doxygen/stylec.html)

要不然送上去的Patch大概會被退個好幾次......
  
  

3.2 Patch流程

基本上就按照Patch Guidelines (http://openocd.org/doc-release/doxygen/patchguide.html) 文件中先設定好GIT相關的資料。
或是可以使用source code中tools/initial.sh 來自動化設定。

然後流程就可以簡化成

1. 發現Bug或開發新功能
2. 開始Work on Patch!!
3. git commit -s -a 將所有修改到的東西加入commit中，並加入Signed-off-by
4. 執行tools/checkpatch.sh檢查commit是否正確，commit格式錯誤可以在這邊檢查
5. git pull --rebase origin master 將目前官方最新的Repo拉下來
6. git push review

• Accept: 恭喜你，真強者 <(_ _)>
• Failed: 看看Review的comments來修改，然後重複以下動作
  • git commit --amend
  • git pull --rebase origin master
  • git push review
      
      
      

99. 結語

本篇粗淺地介紹了相關的開發環境和流程，還沒真正進入到底層的世界中~~~
持續廢話ING
  
  
  

A. 附錄:

通常為了避免使用到root來執行OpenOCD，我都會使用udev中的rules

在/etc/udev/rules.d/70-persistent-usb.rules中加入以下內容

SUBSYSTEM=="usb", ENV{DEVTYPE}=="usb_device", ATTR{idVendor}=="15ba", ATTR{idProduct}=="002a", MODE="0666"
SUBSYSTEM=="usb", ENV{DEVTYPE}=="usb_device", ATTR{idVendor}=="0403", ATTR{idProduct}=="6010", MODE="0666"
SUBSYSTEM=="usb", ENV{DEVTYPE}=="usb_device", ATTR{idVendor}=="0483", ATTR{idProduct}=="3748", MODE="0666"

• 第一行為Olimex的OpenOCD JTAG TINY (之後會用到先放入)
• 第二行為一般FTDI FT2232H的裝置
• 第三行為STMicroelectronics的ST-LINK/V2

最後將使用下面兩個Command將udev的rule重新載入，記得需要Root權限

udevadm control --reload-rules
udevadm trigger

參考資料

1. OpenOCD 官方網站 (http://openocd.org/)
2. OpenOCD README (http://openocd.org/doc-release/README)
3. OpenOCD User's Guide (http://openocd.org/doc/html/index.html)