浅聊深入浅出RISC-V调试

一、JTAG简介

目前RISC-V官方支持的调试方式是JTAG(Joint Test Action Group)，而ARM支持的调试方式有JTAG和SWD(Serial Wire Debug)这两种。
JTAG是一种国际标准的调试方式(IEEE1149.1)，而SWD是ARM开发的。标准JTAG采用四线方式，分别是TCK、TMS、TDI和TDO，有一个可选的TRST引脚。

● TCK：测试时钟输入。
● TMS：测试模式选择。
● TDI：测试数据输入。
● TDO：测试数据输出。

在调试时需要用到一个工具，比如JLink或者CMSIS-DAP，对于这个工具，在这里称为JTAG主机(JTAG host)，而嵌入在芯片内部的JTAG称为JTAG从机(JTAG slave)，需要注意的是上面这些信号的输入输出方向是对于JTAG从机来说的。下文中如无特别说明，JTAG都是指JTAG从机。
一个JTAG主机可以同时对多个JTAG从机进行调试，这通过JTAG扫描链(JTAG Scan Chain)完成，如图1所示。

图1 一个JTAG主机连接多个JTAG从机

JTAG内部有一个TAP(Test Access Port)控制器(或者说状态机)，通过TCK和TMS信号来改变状态机的状态。这个状态机的核心是两路SCAN，分别是IR SCAN和DR SCAN，TAP状态机如图2所示。

图2 TAP状态机
箭头上的0或1表示的是TMS信号的电平。JTAG在每一个TCK信号的上升沿采样TMS信号和TDI信号，决定状态机的状态是否发生变化，在每一个TCK信号的下降沿输出TDO信号。可以看到，无论TAP目前处于哪一个状态，只要TMS保持高电平并持续5个TCK时钟，则TAP一定会回到Test-Logic-Reset状态。
JTAG内部有一个IR(instruction register)寄存器和多个DR(data register)寄存器，IR寄存器决定要访问的是哪一个DR寄存器。DR寄存器有IDCODE、BYPASS等。在Test-Logic-Reset状态下IR寄存器默认选择的是IDCODE这个DR寄存器。
JTAG主机通过IR SCAN设置IR寄存器的值，然后通过DR SCAN来读、写相应的DR寄存器。

二、RISC-V调试Spec

调试模块在CPU芯片设计里是最为不起眼的，但又是最为复杂的模块之一，大部分开源的处理器IP都没有调试模块。
下面的内容基于RISC-V debug spec 0.13版本。
目前RISC-V的官方调试上位机是openocd，调试工具可以是JLink或者CMSIS-DAP，RISC-V调试系统框架如图3所示。

图3 RISC-V调试系统框架

可以看到主要分为3个部分，分别是Debug Host，可以理解为PC；Debug Hardware，可以理解为JLink或者CMSIS-DAP这样的调试工具；第三部分就是嵌入在芯片内部的调试模块。在调试模块内部，与调试工具直接交互的是DTM模块，DTM模块通过DMI接口与DM模块交互。

1>DTM模块

在DTM模块里实现了一个TAP控制器(状态机)，其中IR寄存器的长度最少为5位，当TAP控制器复位时，IR的值默认为5'b00001，即选择的是IDCODE寄存器。DTM模块的寄存器(DR寄存器)定义如图4所示。

图4 DTM寄存器
其中红色框起来的寄存器是必须要实现的。下面简单介绍一下这几个寄存器。

① IDCODE寄存器(0x01)
当TAP状态机复位时，IR寄存器的值默认为0x01，即选择的是IDCODE寄存器。IDCODE寄存器的每一位含义如图5所示。IDCODE是只读寄存器。

图5 IDCODE寄存器
● Version：只读，版本号，可为任意值。
● PartNumber：只读，可为任意值。
● Manufld：只读，厂商号，遵循JEP106标准分配，实际中可为任意值，只要不与已分配的厂商号冲突即可。

② DTM控制和状态寄存器(dtmcs，0x10)
dtmcs寄存器的每一位含义如图6所示。

图6 dtmcs寄存器

● dmihardreset：DTM模块硬复位，写1有效。
● dmireset：清除出错，写1有效。
● idle：只读，JTAG 主机在Run-Test-Idle状态停留的时钟周期数，0表示不需要进入Run-Test-Idle状态，1表示进入Run-Test-Idle状态后可以马上进入下一个状态，以此类推。
● dmistat：只读，上一次操作的状态。0表示无出错，1或者2表示操作出错，3表示操作还未完成。
● abits：只读，dmi寄存器中address域的大小(位数)。
● version：只读，实现所对应的spec版本，0表示0.11版本，1表示0.13版本。

③ DM模块接口访问寄存器(dmi，0x11)
dmi寄存器的每一位含义如图7所示。

图7 dmi寄存器
● address：可读可写，DM寄存器的长度(位数)。
● data：可读可写，往DM寄存器读、写的数据，固定为32位。
● op：可读可写，读或者写这个域时有不同的含义。当写这个域时，写0表示忽略address和data的值，相当于nop操作；写1表示从address指定的寄存器读数据；写2表示把data的数据写到address指定的寄存器。写3为保留值。当读这个域时，0表示上一个操作正确完成；1为保留值；2表示上一个操作失败，这个状态是会被记住的，因此需要往dtmcs寄存器的dmireset域写1才能清除这个状态。3表示上一个操作还未完成。

在Update-DR状态时，DTM开始执行op指定的操作。在Capture-DR状态时，DTM更新data域。

④ BYPASS寄存器(0x1f)
只读，长度为1，值固定为0。

2>DM模块

从图3可知，DM模块访问RISC-V Core有两种方式，一种是通过abstract command，另一种是通过system bus。abstract command方式是必须要实现的，system bus的方式是可选的。
DM模块的寄存器都为32位，定义如图8所示。

图8 DM寄存器

下面介绍一下红色框起来这几个重要的寄存器。

① data寄存器(data0-data11，0x04-0x0f)
这12个寄存器是用于abstract command的数据寄存器，长度为32位，可读可写。

② DM控制寄存器(dmcontrol，0x10)
dmcontrol寄存器的每一位含义如图9所示。

图9 dmcontrol寄存器

● haltreq：只写，写1表示halt(暂停)当前hart(hart表示CPU核，存在多核的情况)。
● resumereq：只能写1，写1表示resume(恢复)当前hart，即go。
● hartreset：可读可写，写1表示复位DM模块，写0表示撤销复位，这是一个可选的位。
● ackhavereset：只能写1，写1表示清除当前hart的havereset状态。
● hasel：可读可写，0表示当前只有一个已经被选择了的hart，1表示当前可能有多个已经被选择了的hart。
● hartsello：可读可写，当前选择的hart的低10位。1位表示一个hart。
● hartselhi：可读可写，当前选择的hart的高10位。1位表示一个hart。如果只有一个hart，那么hasel的值为0，hartsello的值为1，hartselhi的值为0。
● setresethaltreq：只能写1，写1表示当前选择的hart复位后处于harted状态。
● clrresethaltreq：只能写1，写1表示清除setresethaltreq的值。
● ndmreset：可读可写，写1表示复位整个系统，写0表示撤销复位。
● dmactive：可读可写，写0表示复位DM模块，写1表示让DM模块正常工作。正常调试时，此位必须为1。

③ DM状态寄存器(dmstatus，0x11)
dmstatus寄存器是一个只读寄存器，每一位含义如图10所示。

图10 dmstatus寄存器

● impebreak：1表示执行完progbuf的指令后自动插入一条ebreak指令，这样就可以节省一个progbuf。当progbufsize的值为1时，此值必须为1。
● allhavereset：1表示当前选择的hart已经复位。
● anyhavereset：1表示当前选择的hart至少有一个已经复位。
● allresumeack：1表示当前选择的所有hart已经应答上一次的resume请求。
● anyresumeack：1表示当前选择的hart至少有一个已经应答上一次的resume请求。
● allnonexistent：1表示当前选择的hart不存在于当前平台。
● anynonexistent：1表示至少有一个选择了的hart不存在于当前平台。
● allunavail：1表示当前选择的hart都不可用。
● anyunavail：1表示至少有一个选择了的hart不可用。
● allrunning：1表示当前选择的hart都处于running状态。
● anyrunning：1表示至少有一个选择了的hart处于running状态。
● allhalted：1表示当前选择的hart都处于halted状态。
● anyhalted：1表示至少有一个选择了的hart处于halted状态。
● authenticated：0表示使用DM模块之前需要进行认证，1表示已经通过认证。
● authbusy：0表示可以进行正常的认证，1表示认证处于忙状态。
● hasresethaltreq：1表示DM模块支持复位后处于halted状态，0表示不支持。
● confstrptrvalid：1表示confstrptr0~3寄存器保存了配置字符串的地址。
● version：0表示DM模块不存在，1表示DM模块的版本为0.11，2表示DM模块的版本为0.13。

④ abstract控制和状态寄存器(abstractcs，0x16)
abstractcs寄存器定义如图11所示。

图11 abstractcs寄存器

● progbufsize：只读，program buffer的个数，取值范围为0~16，每一个的大小为32位。
● busy：只读，1表示abstract命令正在执行，当写command寄存器后该位应该马上被置位直到命令执行完成。
● cmderr：可读、只能写1，cmderr的值仅当busy位为0时有效。0表示无错误，1表示正在操作command、abstractcs、data或者progbuf寄存器，2表示不支持当前命令，3表示执行命令时出现异常，4表示由于当前hart不可用，或者不是处于halted/running状态而不能被执行，5表示由于总线出错(对齐、访问大小、超时)导致的错误，7表示其他错误。写1清零cmderr。
● datacount：只读，所实现的data寄存器的个数。

⑤ abstract命令寄存器(command，0x17)
当写这个寄存器时，相应的操作就会被执行。command寄存器只能写，定义如图12所示。

图12 command寄存器

● cmdtype：只写，命令类型，0为表示访问寄存器，1表示快速访问，2表示访问内存。
● control：只写，不同的命令类型有不同的含义，说明如下。

当cmdtype为0时，control定义如图13所示。

图13 访问寄存器

● cmdtype：值为0。
● aarsize：2表示访问寄存器的最低32位，3表示访问寄存器的最低64位，4表示访问寄存器的最低128位。如果大于实际寄存器的大小则此次访问是失败的。
● aarpostincrement：1表示成功访问寄存器后自动增加regno的值。
● postexec：1表示执行progbuf里的内容(指令)。
● transfer：0表示不执行write指定的操作，1表示执行write指定的操作。
● write：0表示从指定的寄存器拷贝数据到arg0指定的data寄存器。1表示从arg0指定的data寄存器拷贝数据到指定的寄存器。
● regno：要访问的寄存器。

综上，可知：
Ⅰ. 当write=0，transfer=1时，从regno指定的寄存器拷贝数据到arg0对应的data寄存器。
Ⅱ. 当write=1，transfer=1时，从arg0对应的data寄存器拷贝数据到regno指定的寄存器。
Ⅲ. 当aarpostincrement=1时，将regno的值加1。
Ⅳ. 当postexec=1时，执行progbuf寄存器里的指令。

arg对应的data寄存器如图14所示。

图14 arg对应的data寄存器

即当访问的寄存器位数为32位时，arg0对应data0寄存器，arg1对应data1寄存器，arg2对应data2寄存器。

当cmdtype为1时，control定义如图15所示。

图15 快速访问

● cmdtyte：值为1。

此命令会执行以下操作：
1）halt住当前hart。
2）执行progbuf寄存器里的指令。
3）resume当前hart。

当cmdtype为2时，control定义如图16所示。

图16 访问内存

● cmdtype：值为2。
● aamvirtual：0表示访问的是物理地址，1表示访问的是虚拟地址。
● aamsize：0表示访问内存的低8位，1表示访问内存的低16位，2表示访问内存的低32位，3表示访问内存的低64位，4表示访问内存的低128位。
● aampostincrement：1表示访问成功后，将arg1对应的data寄存器的值加上aamsize对应的字节数。
● write：0表示从arg1指定的地址拷贝数据到arg0指定的data寄存器，1表示从arg0指定的data寄存器拷贝数据到arg1指定的地址。
● target-specific：保留。

综上，可知：
Ⅰ. 当write=0时，从arg1指定的地址拷贝数据到arg0指定的data寄存器。
Ⅱ. 当write=1时，从arg0指定的data寄存器拷贝数据到arg1指定的地址。
Ⅲ. 当aampostincrement=1时，增加arg1对应的data寄存器的值。

⑥ 系统总线访问控制和状态寄存器(sbcs，0x38)
sbcs寄存器定义如图17所示。

图17 sbcs寄存器

● sbversion：只读，0表示system bus是2018.1.1之前的版本，1表示当前debug spec的版本，即0.13版本。
● sbbusyerror：只读，写1清零，当debugger要进行system bus访问操作时，如果上一次的system bus访问还在进行中，此时会置位该位。
● sbbusy：只读，1表示system bus正在忙。在进行system bus访问前必须确保该位为0。
● sbreadonaddr：可读可写，1表示每次往sbaddress0寄存器写数据时，将会自动触发system bus从新的地址读取数据。
● sbaccess：可读可写，访问的数据宽度，0表示8位，1表示16位，2表示32位，3表示64位，4表示128位。
● sbautoincrement：可读可写，1表示每次system bus访问后自动将sbaddress的值加上sbaccess的大小(字节)。
● sbreadondata：可读可写，1表示每次从sbdata0寄存器读数据后将自动触发system bus从新的地址读取数据。
● sberror：可读，写1清零，0表示无错误，1表示超时，2表示访问地址错误，3表示地址对齐错误，4表示访问大小错误，7表示其他错误。
● sbasize：只读，system bus地址宽度(位数)，0表示不支持system bus访问。
● sbaccess128：只读，1表示system bus支持128位访问。
● sbaccess64：只读，1表示system bus支持64位访问。
● sbaccess32：只读，1表示system bus支持32位访问。
● sbaccess16：只读，1表示system bus支持16位访问。
● sbaccess8：只读，1表示system bus支持8位访问。

⑦ 系统总线地址0寄存器(sbaddress0，0x39)
可读可写，如果sbcs寄存器中的sbasize的值为0，那么此寄存器可以不用实现。

当写该寄存器时，会执行以下流程：
Ⅰ. 设置sbcs.sbbusy的值为1。
Ⅱ. 从新的sbaddress地址读取数据。
Ⅲ. 如果读取成功并且sbcs.sbautoincrement的值为1，则增加sbaddress的值。
Ⅳ. 设置sbcs.sbbusy的值为0。

⑧ 系统总线数据0寄存器(sbdata0，0x3c)
可读可写，如果sbcs寄存器中的所有sbaccessxx的值都为0，那么此寄存器可以不用实现。

当写该寄存器时，会执行以下流程：
Ⅰ. 设置sbcs.sbbusy的值为1。
Ⅱ. 将sbdata的值写到sbaddress指定的地址。
Ⅲ. 如果写成功并且sbcs.sbautoincrement的值为1，则增加sbaddress的值。
Ⅳ. 设置sbcs.sbbusy的值为0。

当读该寄存器时，会执行以下流程：
Ⅰ. 准备返回读取的数据。
Ⅱ. 设置sbcs.sbbusy的值为1。
Ⅲ. 如果sbcs.sbautoincrement的值为1，则增加sbaddress的值。
Ⅳ. 如果sbcs.sbreadondata的值为1，则开始下一次读操作。
Ⅴ. 设置sbcs.sbbusy的值为0。

三、RISC-V调试上位机分析

RISC-V官方支持的调试器上位机是openocd。openocd是地表最强大(没有之一)的开源调试上位机，支持各种target(ARM(M、A系列)、FPGA、RISC-V等)，支持各种调试器(Jlink、CMSIS-DAP、FTDI等)，支持JTAG和SWD接口。
这里不打算详细分析整个openocd的实现，只是重点关注针对RISC-V平台的初始化、读写寄存器和读写内存这几个流程。

1>openocd启动过程

openocd启动时需要通过-f参数制定一个cfg文件，比如：

openocd.exe -f riscv.cfg

riscv.cfg文件的内容如下：

adapter_khz     1000
reset_config srst_only
adapter_nsrst_assert_width 100
interface cmsis-dap
transport select jtag
set _CHIPNAME riscv
jtag newtap $_CHIPNAME cpu -irlen 5 -expected-id 0x1e200a6d
set _TARGETNAME $_CHIPNAME.cpu
target create $_TARGETNAME riscv -chain-position $_TARGETNAME

■ 第一行设置TCK的时钟为1000KHz。
■ 第二行表示不支持通过TRST引脚复位，只支持TMS为高电平并持续5个TCK时钟这种方式的复位。
■ 第三行是复位持续的延时。
■ 第四行指定调试器为CMSIS-DAP。
■ 第五行指定调试接口为JTAG。
■ 第六行指定调试的target类型为riscv。
■ 第七行指定生成一个IR寄存器长度为5位、IDCODE为0x1e200a6d的JTAG TAP。
■ 第八、九行指定生成一个riscv target。

openocd启动时的主要流程如图18所示。

图18 openocd启动流程

下面重点关注一下examine target这个流程。
这里的target是指riscv，对于riscv，首先会读取dtmcontrol这个寄存器，因为openocd支持0.11和0.13版本的DTM，通过这个寄存器可以知道当前调试的DTM是哪一个版本。这里选择0.13版本来分析。通过读取dtmcontrol，还可以知道idle、abits这些参数。接下来会将dmcontrol这个寄存器的dmactive域写0后再写1来复位DM模块。接下来再读取dmstatus，判断version域是否为2。接下来还会读取sbcs和abstractcs寄存器，最后就是初始化每一个hart的寄存器。

2>read register过程

读寄存器时，先构建command寄存器的内容，首先将cmdtype的值设为0，aarsize的值设为2(寄存器的宽度为32位)，transfer的值设为1，regno的值设为要读的寄存器的number，其他值设为0，然后写到command寄存器里。然后一直读取abstractcs寄存器，直到abstractcs寄存器的busy位为0或者超时。然后再判断abstractcs寄存器的cmderr的值是否为0，如果不为0则表示此次读取寄存器失败，如果为0则继续读取data0寄存器，这样就可以得到想要读的寄存器的值。

3>write register过程

写寄存器时，先将需要写的值写到data0寄存器，然后构建command寄存器的内容，首先将cmdtype的值设为0，aarsize的值设为2(寄存器的宽度为32位)，transfer的值设为1，write的值设为1，regno的值设为要写的寄存器的number，其他值设为0，然后写到command寄存器里。然后一直读取abstractcs寄存器，直到abstractcs寄存器的busy位为0或者超时。然后再判断abstractcs寄存器的cmderr的值是否为0，如果不为0则表示此次写寄存器失败，如果为0则表示写寄存器成功。

4>read memory过程

如果progbufsize的值大于等于2，则会优先使用通过执行指令的方式来读取内存。这里不分析这种方式，而是分析使用system bus的方式。通过前面的分析可知，system bus有两个版本V0和V1，这里以V1版本来说明。
先将sbcs寄存器的sbreadonaddr的值设为1，sbaccess的值设为2(32位)，然后将要读内存的地址写入sbaddress0寄存器。接着读sbdata0寄存器，最后读sbcs寄存器，如果其中的sbbusy、sberror和sbbusyerror都为0，则从sbdata0读取到的内容就是要读的内存的值。

5>write memory过程

和read memory类似，同样以V1版本来说明。
先将要写的内存地址写到sbaddress0寄存器，然后将要写的数据写到data0寄存器，最后读sbcs寄存器，如果其中的sbbusy、sberror和sbbusyerror都为0，则此次写内存成功。

四、RISC-V JTAG的实现

通过在STM32F103C8T6上实现(模拟)RISC-V调试标准，进一步加深对RISC-V JTAG调试的理解。
使用STM32的四个GPIO作为JTAG信号的四根线，其中TCK所在的引脚设为外部中断，即上升沿和下降沿触发方式，实现了可以通过openocd以RISC-V的调试标准来访问STM32的寄存器和内存。程序流程如图19所示。

图19 JTAG实现的程序流程

五、参考资料

1、在STM32上模拟RISC-V JTAG的实现：stm32_riscv_jtag_slave
2、一个从零开始写的易懂的RISC-V处理器核：tinyriscv