⚠️ 本文所使用的 QEMU 版本為：v4.2.0

在之前的文章中 (Part 1., Part 2.) 我們提到了如何使用 Decodetree 來定義指令的 decoder。本篇文章就實際使用 Decodetree 來定義一個 QEMU RISC-V 目前尚未支援的指令 - B(itmanip) Extension 中的 pcnt 指令，並實做其行為。

pcnt 指令

pcnt 指令的定義如下：

This instruction counts the number of 1 bits in a register. This operations is known as population count, popcount, sideways sum, bit summation, or Hamming weight.

其指令格式為：

1
2
3

| 1 0 9 8 7 6 5 | 4 3 2 1 0 | 9 8 7 6 5 | 4 3 2 | 1 0 9 8 7 | 6 5 4 3 2 1 0 |
|===========================================================================|
|    0110000    |   00010   |    rs1    |  001  |     rd    |    0010011    | PCNT

安裝 toolchain

由於 B Extension 尚未正式定稿 (Draft)，因此必須至 riscv-bitmanip repo 下載 toolchain，並依照該 repo 的指示安裝：

1
2
3

sudo mkdir /opt/riscv64b
sudo chown $USER: /opt/riscv64b
bash build-all.sh

此安裝除了 toolchain 外，還會安裝支援 B Extension 的 Spike (riscv-isa-sim) 及 riscv-pk (P.S. 目前的 script 是寫死安裝路徑為：/opt/riscv64b)。

範例程式

在安裝好後，我們可以寫一個範例程式，並搭配 Spike 來做測試：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

#include <stdio.h>

int count_set_bits(int num)
{
    int count;
    __asm__("pcnt %0, %1\n"
            : "=r"(count)
            : "r"(num)
            :);
    return count;
}

int main(void)
{
    int num = 187;
    int result = count_set_bits(num);

    printf("num = %d\n", num);
    printf("# of set bits = %d\n", result);

    return 0;
}

此範例程式做的事情很簡單，透過 inline assembly：pcnt 指令，將 int num = 187 的 1 bits 個數給計算出來。

透過剛剛的 toolchain 編譯此程式：

1

/opt/riscv64b/bin/riscv64-unknown-elf-gcc -Wall -march=rv64gb -Os -o pcnt_example pcnt_example.c

• -march=rv64gb：指定 target ISA 為 RISC-V 64-bit + g (IMAFD base) + b (B Extension)。

透過 objdump 觀看其反組譯碼：

1

/opt/riscv64b/bin/riscv64-unknown-elf-objdump -S pcnt_example > pcnt_example.s

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

pcnt_example:     file format elf64-littleriscv

Disassembly of section .text:

00000000000100b0 < main >:
   100b0:       00017537                lui     a0,0x17
   100b4:       ff010113                addi    sp,sp,-16
   100b8:       0bb00593                li      a1,187
   100bc:       8b850513                addi    a0,a0,-1864 # 168b8 <__trunctfdf2+0x2ce>
   100c0:       00113423                sd      ra,8(sp)
   100c4:       00813023                sd      s0,0(sp)
   100c8:       2ac000ef                jal     ra,10374 <printf>
   100cc:       0bb00413                li      s0,187
   100d0:       00017537                lui     a0,0x17
   100d4:       60241413                pcnt    s0,s0
   100d8:       0004041b                sext.w  s0,s0
   100dc:       00040593                mv      a1,s0
   100e0:       8c850513                addi    a0,a0,-1848 # 168c8 <__trunctfdf2+0x2de>
   100e4:       290000ef                jal     ra,10374 <printf>
   100e8:       00813083                ld      ra,8(sp)
   100ec:       00013403                ld      s0,0(sp)
   100f0:       00000513                li      a0,0
   100f4:       01010113                addi    sp,sp,16
   100f8:       00008067                ret

可以看到 Line:15 呼叫了 pcnt 指令：pcnt s0, s0。

透過 Spike 執行程式：

1

/opt/riscv64b/bin/spike --isa=RV64GCB pk pcnt_example

1
2
3

bbl loader
num = 187
# of set bits = 6

187 的二進位為 10111011，1 bits 個數為 6，與程式輸出的結果一致。

同樣的程式，我們使用 QEMU 來執行：

1

./qemu/riscv64-linux-user/qemu-riscv64 pcnt_example

1
2

num = 187
Illegal instruction

可以看到，目前 QEMU 尚未支援 pcnt 指令，因此當執行到 pcnt 指令時，便會噴 Illegal instruction 的錯誤訊息。

在 QEMU 中新增 pcnt 指令

根據前述 B Extension spec. 所列的 pcnt 指令格式，參考目前 QEMU RISC-V 現有的 Decodetree：target/riscv/insn32.decode，pcnt 的 Pattern 可以搭配 @r2 的 Format (只有 rs1 及 rd 這兩個 Fields)，其完整定義如下：

Field

22
23

%rs1       15:5
%rd        7:5

Format

64

@r2      .......   ..... ..... ... ..... ....... %rs1 %rd

Pattern

我們可以定義 pcnt 的 Pattern 如下：

207
208

# *** RV32B Standard Extension ***
pcnt       0110000  00010 ..... 001 ..... 0010011 @r2

所會產生的 decoder 如下：

38
39
40
41

typedef struct {
    int rd;
    int rs1;
} arg_decode_insn3213;

491
492
493
494
495

static void decode_insn32_extract_r2(DisasContext *ctx, arg_decode_insn3213 *a, uint32_t insn)
{
    a->rs1 = extract32(insn, 15, 5);
    a->rd = extract32(insn, 7, 5);
}

673
674
675
676
677
678
679
680
681
682
683
684

            case 0x1:
                /* 01...... ........ .001.... .0010011 */
                decode_insn32_extract_r2(ctx, &u.f_decode_insn3213, insn);
                switch ((insn >> 20) & 0x3ff) {
                case 0x202:
                    /* 01100000 0010.... .001.... .0010011 */
                    /* /home/frankchang/qemu/target/riscv/insn32.decode:208 */
                    if (trans_pcnt(ctx, &u.f_decode_insn3213)) return true;
                    return false;
                }
                return false;
            }

由於 @r2 Format 並沒有參考任何的 Argument Set，因此 Decodetree 會自動根據 Format 所參考到的 Fields (rs1、rd) 動態產生 argument set struct: arg_decode_insn3213。

此外，由 pcnt Pattern 所產生的 decode function 會呼叫 decode_insn32_extract_r2() 這個 extract function 來解析指令中 rs2 及 rd 欄位的值，並更新所傳入 arg_decode_insn3213 對應的欄位，而後再呼叫 trans_pcnt() 來執行 pcnt 指令 (產生對應的 TCG ops)。因此，我們還必須定義 trans_pcnt() 來實作 pcnt 的指令行為。

參考 B Extension spec. 中，pcnt 指令的實作：

1
2
3
4
5
6
7

uint_xlen_t pcnt(uint_xlen_t rs1)
{
    int count = 0;
    for (int index = 0; index < XLEN; index++)
    count += (rs1 >> index) & 1;
    return count;
}

及 Spike 中，pcnt 指令的實作：

1
2
3
4
5

require_extension('B');
reg_t x = 0;
for (int i = 0; i < xlen; i++)
  if (1 & (RS1 >> i)) x++;
WRITE_RD(sext_xlen(x));

實作很簡單，每次迴圈 right shift rs1 i 個 bits 並與 1 做 AND，若為 true 就將 count 加 1，最後回傳的 count 就是 1 bits 個數。

trans_pcnt() 實作了 pcnt 指令對應的 TCG ops。QEMU 在執行時，會將 target instructions (e.g. RISC-V instructions) 轉譯成 TCG ops，而 TCG ops 則會再轉譯為 host instructions (e.g. x86 instruction)。

1
2
3
4

+---------------------+      +---------+      +-------------------+
| Target Instructions | ---> | TCG ops | ---> | Host instructions |
+---------------------+      +---------+      +-------------------+
     (e.g. RISC-V)                                  (e.g. x86)

關於 TCG 的說明，可以參考 QEMU 的 documentations：Translator Internals、TCG README。

新增一檔案：./target/riscv/insn_trans/trans_rvb.inc.c 來定義 B Extension 指令的實作 (當然，目前只有 pcnt 指令)：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

/*
 * RISC-V translation routines for the RVB Standard Extension.
 */

static bool trans_pcnt(DisasContext *ctx, arg_pcnt *a) {
    if (a->rd != 0) {
        TCGv t0 = tcg_temp_new();
        gen_get_gpr(t0, a->rs1);
        gen_helper_pcnt(cpu_gpr[a->rd], t0);
        tcg_temp_free(t0);
    }
    return true;
}

由於對 x0 (zero register) 的寫入都會被忽略，因此首先判斷 rd 是否為 0，若為 0 則不做任何的事情。

再來宣告一 TCG variable：t0，並透過 gen_get_gpr() 將 rs1 暫存器的值 (如 pcnt_example 中 pcnt s0, s0 指令，rs1 即為 s0，也就是 x8)，載入到 t0。

這邊還呼叫了我們所定義幫我們處理 pcnt 計算 1 bits 個數的 pcnt helper function：gen_helper_pcnt()。該 helper function 會在計算完後，將最後的結果存至 rd (i.e. cpu_gpr[a->rd]) 暫存器中。

最後別忘了要釋放之前所宣告的 TCG variable：t0。

P.S. 其實這邊可以更簡單的直接將 cpu_gpr[a->rs1] 傳入，省略 TCG variable：t0 的宣告：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

/*
 * RISC-V translation routines for the RVB Standard Extension.
 */

static bool trans_pcnt(DisasContext *ctx, arg_pcnt *a) {
    if (a->rd != 0) {
        gen_helper_pcnt(cpu_gpr[a->rd], cpu_gpr[a->rs1]);
    }
    return true;
}

pcnt 的 helper function 定義如下：

1
2

/* Bitmanip Extension */
DEF_HELPER_1(pcnt, tl, tl)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

/*
 * RISC-V Bitmanip Extension Helpers for QEMU.
 */
#include "qemu/osdep.h"
#include "cpu.h"
#include "exec/exec-all.h"
#include "exec/helper-proto.h"

target_ulong HELPER(pcnt)(target_ulong rs1)
{
    target_ulong count = 0;
    for (int i = 0; i < TARGET_LONG_BITS; i++) {
        count += (rs1 >> i) & 1;;
    }
    return count;
}

基本上就是實作先前在 B Extension spec. 及 Spike 中所看到的 1 bits 個數計算方式。由於 pcnt helper function 只需接收 rs1 暫存器的值，並回傳最後 1 bits 個數的結果，因此，我們定義 pcnt 的 helper function 為接收一 target_ulong 型態的 rs1 並回傳 target_ulong 型態的 1 bits 個數結果。

最後別忘了將我們新增的 bitmanip_helper.o 加入 compile objects 列表：

1

obj-y += translate.o op_helper.o cpu_helper.o cpu.o csr.o fpu_helper.o bitmanip_helper.o gdbstub.o

重新編譯 QEMU，再次執行 pcnt_example：

1

./qemu/riscv64-linux-user/qemu-riscv64 pcnt_example

1
2

num = 187
# of set bits = 6

這次 QEMU 就可以正確的 decode 並執行 pcnt 指令了。

在 QEMU 中新增指令的流程大致就如同本文所介紹，不過由於 pcnt 指令只是單純的 bit operation 指令，沒有像 csr 相關指令會涉及 CPURISCVState 的更新，以及像 jal 指令會涉及 DisasContext 的判斷，因此實作起來相對簡單。若欲讓 QEMU 支援不論是 B Extension 或是 V Extension 的其他指令，就是得好好 K spec. 並一個一個新增了。

另外最近剛好 C-Sky Microsystems 的 LIU Zhiwei <zhiwei_liu@c-sky.com> 在實作 V Extension 的 configure instructions：vsetvl 及 vsetvli，比起本文所介紹之 B Extension 的 pcnt 指令要來得複雜得多，patches 仍在被 reviewed 中，也可以做為參考。

本文所對 QEMU 做的修正，可以參考此 commit。

⚠️ 本文所使用的 QEMU 版本為：v4.2.0

延續 Part 1. 一文，本文將繼續介紹 Decodetree 中的 Patterns 及 Pattern Groups 語法。

Patterns

Pattern 實際定義了一個指令的 decode 方式。Decodetree 會根據 Patterns 的定義，來動態產生出對應的 switch-case decode 判斷式。

1
2
3
4

pat_def      := identifier ( pat_elt )+
pat_elt      := fixedbit_elt | field_elt | field_ref | args_ref | fmt_ref | const_elt
fmt_ref      := '@' identifier
const_elt    := identifier '=' number

其語法由使用者所定義的 identifier，隨後緊接著一個以上的 pat_elt。

• identifier 可由開發者自訂，如：addl_r、addli … 等。
• pat_elt 則可以採用以下不同的語法：
  • fixedbit_elt 與在 Format 中 fixedbit_elt 的定義相同。
  • field_elt 與在 Format 中 field_elt 的定義相同。
  • field_ref 與在 Format 中 field_ref 的定義相同。
  • args_ref 與在 Format 中 args_ref 的定義相同。
  • fmt_ref 直接參考一個被定義過的 Format。
  • const_elt 可以直接指定某一個 argument 的值。

由於 Pattern 實際定義了一個指令的 decode 方式，因此所有的 bits 及 arguments (如果有參考 args_ref 的話) 都必須明確的被定義，如果在搭配了所有的 pat_elt 後還有未定義的 bits 或是 arguments 的話，Decodetree 便會報錯。

此外，Pattern 所產生出來的 decoder，最後還會呼叫對應的 translator function。

• translator function 需開發者自行定義。

Examples

1

addl_i   010000 ..... ..... .... 0000000 ..... @opi

定義了 addl_i 這個指令的 Pattern，其中：

• insn[31:26] 為 010000。
• insn[11:5] 為 0000000。
• 參考了 Part 1. Examples 定義的 @opi Format。
• 由於 Pattern 的所有 bits 都必須明確的被定義，因此 @opi 必須包含其餘 insn[25:12] 及 insn[4:0] 的格式定義，否則 Decodetree 便會報錯。

最後 addl_i 的 decoder 還會呼叫 trans_addl_i() 這個 translator function。

搭配之前介紹的 Fields、Argument Sets 及 Formats，讓我們再看幾個完整的例子應該會更清楚 Decodetree 是怎產生一個指令的 decoder 的。

首先是 RISC-V 的 lui 及 auipc 指令：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

# Fields:
%rd        7:5

# immediates:
%imm_u    12:s20                 !function=ex_shift_12


# Argument sets:
&u    imm rd


# Formats:
@u       ....................      ..... ....... &u      imm=%imm_u          %rd


# Patterns
lui      ....................       ..... 0110111 @u
auipc    ....................       ..... 0010111 @u

會產生以下 lui 及 auipc 的 decoder：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

typedef struct {
    int imm;
    int rd;
} arg_u;


static void decode_insn32_extract_u(DisasContext *ctx, arg_u *a, uint32_t insn)
{
    a->imm = ex_shift_12(ctx, sextract32(insn, 12, 20));
    a->rd = extract32(insn, 7, 5);
}

static bool decode_insn32(DisasContext *ctx, uint32_t insn)
{
    union {
        arg_u f_u;
    } u;

    decode_insn32_extract_u(ctx, &u.f_u, insn);
    switch (insn & 0x0000007f) {
    case 0x00000017:
        /* ........ ........ ........ .0010111 */
        /* ./insn32.decode:18 */
        if (trans_auipc(ctx, &u.f_u)) return true;
        return false;
    case 0x00000037:
        /* ........ ........ ........ .0110111 */
        /* ./insn32.decode:17 */
        if (trans_lui(ctx, &u.f_u)) return true;
        return false;
    }
    return false;
}

回顧到目前為止所介紹的：

• Argument Sets：&u 這個 argument set 包含了 imm 及 rd 這兩個 arguments。

  1 2 3 4

  typedef struct { int imm; int rd; } arg_u;

• Fields： imm 及 rd 分別位在 insn[31:12] 及 insn[11:7]，且 imm 為 sign-extended。最後在擷取出 imm 的值後，還會呼叫 ex_shift_12()。

  1 2	a->imm = ex_shift_12(ctx, sextract32(insn, 12, 20)); a->rd = extract32(insn, 7, 5);

• Formats：@u 定義了 RISC-V U-type 指令的格式

  • 參考了 &u 這個 Argument Set，因此 decode function 會傳入 arg_u 作為參數。
  • insn[31:12] 參考了 imm_u 這個 Field (並重新命名為 imm)
  • insn[11:7] 參考了 rd 這個 Field。

  1 2 3 4 5

  static void decode_insn32_extract_u(DisasContext *ctx, arg_u *a, uint32_t insn) { a->imm = ex_shift_12(ctx, sextract32(insn, 12, 20)); a->rd = extract32(insn, 7, 5); }

• Patterns：

  • lui 的 opcode (insn[6:0]) 為 0010111，也就是 0x17，在產生出來的 switch-case 中可以看到其對應的 case。
  • lui 的 decoder 最後呼叫了 trans_lui()，並傳入 DisasContext 及經由 decode_insn32_extract_u() 所解析出來的 arg_u。
  • auipc 的 opcode (insn[6:0]) 為 0110111，也就是 0x37，在產生出來的 switch-case 中可以看到其對應的 case。
  • auipc 的 decoder 最後呼叫了 trans_auipc()，並傳入 DisasContext 及經由 decode_insn32_extract_u() 所解析出來的 arg_u。
  • P.S. 這邊由於 Decodetree 發現 lui 及 auipc 可以共用 decode_insn32_extract_u()，因此將其提到了 switch-case 之外。

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21

  static bool decode_insn32(DisasContext *ctx, uint32_t insn) { union { arg_u f_u; } u; decode_insn32_extract_u(ctx, &u.f_u, insn); switch (insn & 0x0000007f) { case 0x00000017: /* ........ ........ ........ .0010111 */ /* ./insn32.decode:18 */ if (trans_auipc(ctx, &u.f_u)) return true; return false; case 0x00000037: /* ........ ........ ........ .0110111 */ /* ./insn32.decode:17 */ if (trans_lui(ctx, &u.f_u)) return true; return false; } return false; }

  我們另外可以發現，Pattern + Format 把所有的 32-bits 都給了明確的定義：

  • Pattern 定義了 opcode (insn[6:0])。
  • Format 參考了 imm (insn[31:12]) 及 rd (insn[11:7])。

  如果有任何未明確定義的 bits 的話，Decodetree 便會報錯，例如如果我們將 lui 的 opcode 最高 2 個 bits (insn[6:5]) 由 01 改成 ..：

  1	lui .................... ..... ..10111 @u

  Decodetree 在解析時，便會報錯：

  ./insn32.decode:17: error: (‘bits left unspecified (0x00000060)’,)

  Decodetree 提醒我們，insn[6:5] (0x00000060) 尚未給出明確定義，並會顯示出其錯誤的行數。

  trans_lui() 和 trans_auipc() 被定義在 target/riscv/insn_trans/trans_rvi.inc.c：

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

  static bool trans_lui(DisasContext *ctx, arg_lui *a) { if (a->rd != 0) { tcg_gen_movi_tl(cpu_gpr[a->rd], a->imm); } return true; } static bool trans_auipc(DisasContext *ctx, arg_auipc *a) { if (a->rd != 0) { tcg_gen_movi_tl(cpu_gpr[a->rd], a->imm + ctx->base.pc_next); } return true; }

  可以看到 trans_*() 負責實際指令的 business logics 及產生對應的 TCG codes。

如同先前所介紹，Patterns 的 pat_elt 也可以採用 field_elt 語法，如 RISC-V 的 fence 指令：

1

fence    ---- pred:4 succ:4 ----- 000 ----- 0001111

• insn[27:24] 為 pred。
• insn[23:20] 為 succ。
• insn[14:12] 固定為 000。
• insn[6:0] 為 opcode (0001111)。
• 沒有參考任何的 Format。
• 剩下的 insn[31:28]、insn[19:15]、insn[11:7] 被宣告為 -，因此就算沒有被明確定義也沒有關係。

所生成 fence 的 decoder 如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

typedef struct {
    int pred;
    int succ;
} arg_decode_insn320;


static void decode_insn32_extract_decode_insn32_Fmt_0(DisasContext *ctx, arg_decode_insn320 *a, uint32_t insn)
{
    a->pred = extract32(insn, 24, 4);
    a->succ = extract32(insn, 20, 4);
}

static bool decode_insn32(DisasContext *ctx, uint32_t insn)
{
    union {
        arg_decode_insn320 f_decode_insn320;
    } u;

    decode_insn32_extract_decode_insn32_Fmt_0(ctx, &u.f_decode_insn320, insn);
    switch (insn & 0x0000707f) {
    case 0x0000000f:
        /* ........ ........ .000.... .0001111 */
        /* ./insn32.decode:2 */
        if (trans_fence(ctx, &u.f_decode_insn320)) return true;
        return false;
    }
    return false;
}

值得注意的是，雖然這次我們沒有參考任何的 Argument Set，但 Decodetree 還是替我們生成了一個包含 pred 和 succ 的 arg_decode_insn320 。

trans_fence() 同樣是被定義在 ./target/riscv/insn_trans/trans_rvi.inc.c：

1
2
3
4
5
6

static bool trans_fence(DisasContext *ctx, arg_fence *a)
{
    /* FENCE is a full memory barrier. */
    tcg_gen_mb(TCG_MO_ALL | TCG_BAR_SC);
    return true;
}

Pattern Groups

Pattern Groups 由一個以上的 Patterns 所組成，其主要差別是不同 Patterns 之間的 bits 可以 overlap。當同組中有多個 Patterns 時，會依據該組中各 Pattern 的宣告順序依序判斷目前的指令是否符合其定義。除此之外，當符合的 Pattern 其 trans_*() 回傳值為 false 時，也會被視為不相符，而繼續判斷該組中的下一個 Pattern。因此 Pattern Groups 非常適合將多個相似格式的指令給組成同一個 Pattern Group。

原文說明如下：

Unlike ungrouped patterns, grouped patterns are allowed to overlap. Conflicts are resolved by selecting the patterns in order. If all of the fixedbits for a pattern match, its translate function will be called. If the translate function returns false, then subsequent patterns within the group will be matched.

1

group    := '{' ( pat_def | group )+ '}'

各 Pattern Group 以 { 開頭，並以 } 結尾，且允許 nested pattern groups 的存在，其他語法皆與 Pattern 相同。

Examples

1
2
3
4
5
6
7

{
  {
    nop   000010 ----- ----- 0000 001001 0 00000
    copy  000010 00000 r1:5  0000 001001 0 rt:5
  }
  or      000010 rt2:5 r1:5  cf:4 001001 0 rt:5
}

會產生以下的 decoder：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

switch (insn & 0xfc000fe0) {
case 0x08000240:
    /* 000010.. ........ ....0010 010..... */
    if ((insn & 0x0000f000) == 0x00000000) {
        /* 000010.. ........ 00000010 010..... */
        if ((insn & 0x0000001f) == 0x00000000) {
            /* 000010.. ........ 00000010 01000000 */
            extract_decode_Fmt_0(&u.f_decode0, insn);
            if (trans_nop(ctx, &u.f_decode0)) return true;
						// 這邊沒有直接回傳 false，讓 switch-case 繼續往下執行
      }
      if ((insn & 0x03e00000) == 0x00000000) {
          /* 00001000 000..... 00000010 010..... */
          extract_decode_Fmt_1(&u.f_decode1, insn);
          if (trans_copy(ctx, &u.f_decode1)) return true;
				　// 這邊沒有直接回傳 false，讓 switch-case 繼續往下執行
      }
  }
  extract_decode_Fmt_2(&u.f_decode2, insn);
  if (trans_or(ctx, &u.f_decode2)) return true;
  return false;
}

當指令的值符合 nop 及 copy 這個內層 Pattern Group 時，會先判斷該指令是否符合 nop 指令的定義，且 trans_nop() 的回傳值為 true。否則的話，就會繼續判斷是否符合同組中的 copy 指令。若都不符，就會再判斷是否符合外層 Pattern Group 的 or 指令。若仍不符，才會回傳 false 表示 decode 失敗。

與單純使用 Pattern 最大不同的是，當一 Pattern 的 trans_*() 回傳值為 false 時，不會直接回傳 false (代表 decode 失敗)，而是會接續著判斷後續的 Patterns 是否相符。

RISC-V Compressed-Extension 中的 c.ebreak、c.jalr、及 c.add 指令，由於這三個指令的格式非常相似，因此非常適合使用 Pattern Group 來定義：

RISC-V spec. 中定義：

C.EBREAK shares the opcode with the C.ADD instruction, but with rd and rs2 both zero, thus can also use the CR format.

C.JALR is only valid when rs1≠x0; the code point with rs1=x0 corresponds to the C.EBREAK instruction.

C.ADD is only valid when rs2≠x0; the code points with rs2=x0 correspond to the C.JALR and C.EBREAK instructions. The code points with rs2̸=x0 and rd=x0 are HINTs.

c.ebreak、c.jalr、c.add 三個指令：

• insn[15:13]、insn[12]、insn[1:0] 的值皆相同。
• 當 insn[11:7] 且 insn[6:2] 的值皆為 0 (rs1=0 且 rs2=0) 時為 c.ebreak 指令。
• 當只有 insn[11:7] 的值為 0 (rs1=0 且 rs2≠0) 時為 c.jalr 指令。
• 否則為 c.add 指令 (rs1≠x0 且 rs2≠0)。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

# Fields
%rd        7:5
%rs2_5     2:5


# Argument Sets
&r         rd rs1 rs2   !extern
&i         imm rs1 rd   !extern


# Formats
@cr        ....  ..... .....  .. &r      rs2=%rs2_5       rs1=%rd     %rd
@c_jalr    ... . .....  ..... .. &i      imm=0 rs1=%rd


# Pattern Groups
{
  ebreak          100 1  00000  00000 10
  jalr            100 1  .....  00000 10 @c_jalr rd=1  # C.JALR
  add             100 1  .....  ..... 10 @cr
}

所生成的 decoder 如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50

static void decode_insn16_extract_c_jalr(DisasContext *ctx, arg_i *a, uint16_t insn)
{
    a->imm = 0; // 在 c_jalr 的 Format 中指定 imm 的值為 0
    a->rs1 = extract32(insn, 7, 5);
}

static void decode_insn16_extract_cr(DisasContext *ctx, arg_r *a, uint16_t insn)
{
    a->rs2 = extract32(insn, 2, 5);
    a->rs1 = extract32(insn, 7, 5);
    a->rd = extract32(insn, 7, 5);
}

static void decode_insn16_extract_decode_insn16_Fmt_2(DisasContext *ctx, arg_decode_insn162 *a, uint16_t insn)
{


static bool decode_insn16(DisasContext *ctx, uint16_t insn)
{
    union {
        arg_decode_insn162 f_decode_insn162;
        arg_i f_i;
        arg_r f_r;
    } u;

    switch (insn & 0x0000f003) {
    case 0x00009002:
        /* 1001.... ......10 */
        if ((insn & 0x00000ffc) == 0x00000000) {
            /* 10010000 00000010 */
            /* ./insn16.decode:20 */
            decode_insn16_extract_decode_insn16_Fmt_2(ctx, &u.f_decode_insn162, insn);
            if (trans_ebreak(ctx, &u.f_decode_insn162)) return true;
            // 這邊沒有直接回傳 false，讓 switch-case 繼續往下執行
        }
        if ((insn & 0x0000007c) == 0x00000000) {
            /* 1001.... .0000010 */
            /* ./insn16.decode:21 */
            decode_insn16_extract_c_jalr(ctx, &u.f_i, insn);
            u.f_i.rd = 1; // 在 jalr 的 Pattern 中指定 rd 的值為 0。
            if (trans_jalr(ctx, &u.f_i)) return true;
            // 這邊沒有直接回傳 false，讓 switch-case 繼續往下執行
        }
        /* ./insn16.decode:22 */
        decode_insn16_extract_cr(ctx, &u.f_r, insn);
        if (trans_add(ctx, &u.f_r)) return true;
        return false;
    }
    return false;
}

當指令格式符合 c.ebreak、c.jalr、c.add 的 Pattern Group 時，會依序判斷該指令是否符合 c.ebreak、c.jalr、c.add 的定義以及其對應的 trans_*()。

另外值得一提的是，在 c_jalr Format 和 jalr Pattern 中有分別指定其 imm 及 rd 的值為 0，所生成的 codes 也會分別在對應的地方將該值設為 0 (見 codes 註解說明)。

以上就是 Decodetree 的語法說明。透過 Decodetree，我們不用再像以前以樣寫一大包的 switch-case 來 decode 指令。將不同類型的指令寫至不同的 decode 檔，不僅方便維護，閱讀起來也更為容易。

⚠️ 本文所使用的 QEMU 版本為：v4.2.0

QEMU 在 decode 指令的時候，需要呼叫各平台所定義的 instruction decoders 來解析指令。如在 ARM 平台下，就定義了：disas_arm_insn()、disas_thumb_insn() 及 disas_thumb2_insn() 等來分別負責 ARM 32-bits 指令、ARM Thumb 指令及 ARM Thumb2 指令的解析。

而 Decodetree 則是由 Bastian Koppelmann 於 2017 年在 porting RISC-V QEMU 的時候所提出來的機制 (詳見：討論串 1、討論串 2)。主因是過往的 instruction decoders (如：ARM) 都是採用一大包的 switch-case 來做判斷。不僅難閱讀，也難以維護。

因此 Bastian Koppelmann 就提出了 Decodetree 的機制，開發者只需要透過 Decodetree 的語法定義各個指令的格式，便可交由 Decodetree 來動態生成對應包含 switch-case 的 instruction decoder .c 檔。

Decodetree 特別適合像 RISC-V 這種具有固定指令格式的 ISA¹。

• 因為各欄位都在固定的位置，(如 RISC-V 的 opcode 都是固定在 bits[6..0] 的位置)，各指令可重複使用的定義相較於其他的 ISA 來得多。

Decodetree 其實是由 Python script (./scripts/decodetree.py) 所撰寫的。其規格說明檔案可以參考：./docs/devel/decodetree.rst，裡面有詳細定義了其語法的格式。QEMU 在編譯時，會呼叫 Decodetree，根據各平台所定義的 decode 檔，動態生成對應的 decoder。

• 如 RISC-V 的 instruction decoders 就是被定義在：./target/riscv/*.decode 中。其 Makefile.obj 就有如下的宣告：

  1 2 3 4 5 6 7 8 9 10 11 12 13

  ... DECODETREE = $(SRC_PATH)/scripts/decodetree.py decode32-y = $(SRC_PATH)/target/riscv/insn32.decode decode32-$(TARGET_RISCV64) += $(SRC_PATH)/target/riscv/insn32-64.decode ... target/riscv/decode_insn32.inc.c: $(decode32-y) $(DECODETREE) $(call quiet-command, \ $(PYTHON) $(DECODETREE) -o $@ --static-decode decode_insn32 \ $(decode32-y), "GEN", $(TARGET_DIR)$@)

  (實際參數說明請見 decodetree 參數)

Decodetree 的語法共分為：Fields、Argument Sets、Formats、Patterns、Pattern Groups 五部分。本文將介紹如何透過 Decodetree 的語法，來動態生成一個指令的 decoder。

Fields

Field 定義如何取出一指令中，各欄位 (eg: rd, rs1, rs2, imm) 的值。

1
2

field_def     := '%' identifier ( unnamed_field )* ( !function=identifier )?
unnamed_field := number ':' ( 's' ) number

其語法由 % 開頭，隨後緊接著一個 identifier 及零個或多個 unamed_field，並可再加上可選的 !function。

• identifier 可由開發者自訂，如：rd、imm… 等。
• unamed_field 定義了該欄位的所在位元。第一個數字定義了該欄位的 least-significant bit position，第二個數字則定義了該欄位的位元長度。另外可加上可選的 s 字元來標明在取出該欄位後，是否需要做 sign-extended。
  • Eg：%rd 7:5 代表 rd 佔了指令中 bits 7 ~ bits 11 的位置 (insn[11:7])，共 5 bits。
• !function 定義在擷取出該欄位的值後，所會再呼叫的 function。

Field (32-bits 指令) 最後會生成對應的 extract32() 及 sextract32() 程式碼²，以用來取得指令中各欄位的值：

Examples

以 RISC-V 的 U-type 指令為例：

其中，imm 佔 insn[31:12]，rd 佔 insn[11:7]，且 imm 需要做 sign-extended 後 左移 12 位 (20-bit immediate is shifted left by 12 bits to form U immediates)。因此，如果我們要定義 RISC-V 的 U-type 指令，則可以宣告成：

1
2

%rd       7:5
%imm_u    12:s20                 !function=ex_shift_12

最後會生成如下的程式碼：

1
2
3
4
5

static void decode_insn32_extract_u(DisasContext *ctx, arg_u *a, uint32_t insn)
{
    a->imm = ex_shift_12(ctx, sextract32(insn, 12, 20));
    a->rd = extract32(insn, 7, 5);
}

(P.S. static void decode_insn32_extract_u() 是由 Format 定義所生成的，而 arg_u *a 則是由 Argument Set 定義所生成的，將會在後面的部分再做說明)

可以看到：

1
2

a->imm = ex_shift_12(ctx, sextract32(insn, 12, 20));
a->rd = extract32(insn, 7, 5);

• a->imm 是由 insn[31:12] 所取得並做 sign-extended，且會再呼叫 ex_shift_12() 來 左移 12 個 bits。

  • P.S. RISC-V 的 ex_shift_12() 是透過定義在./target/riscv/translate.c 中 EX_SH 這個 macro 所展開的：

  1 2 3 4 5 6 7 8 9 10

  #define EX_SH(amount) \ static int ex_shift_##amount(DisasContext *ctx, int imm) \ { \ return imm << amount; \ } EX_SH(1) EX_SH(2) EX_SH(3) EX_SH(4) EX_SH(12)

• a->rd 是由 insn[11:7] 所取得。

此外，在 Decodetree 的 spec. 中也有提到，我們可以透過只定義 !function 來直接呼叫該 function。在這種情況下，只有 DisasContext 會被傳入該 function。

One may use !function with zero unnamed_fields. This case is called a parameter, and the named function is only passed the DisasContext and returns an integral value extracted from there.

如 ARM Thumb ./target/arm/t16.decode 就有定義：

1
2

# Set S if the instruction is outside of an IT block.
%s               !function=t16_setflags

1
2
3
4
5
6
7
8

static void disas_t16_extract_addsub_2i(DisasContext *ctx, arg_s_rri_rot *a, uint16_t insn)
{
    a->imm = extract32(insn, 6, 3);
    a->rn = extract32(insn, 3, 3);
    a->rd = extract32(insn, 0, 3);
    a->s = t16_setflags(ctx); // 呼叫 t16_setflags()，並傳入 DisasContext
    a->rot = 0;
}

未包含任何 unnamed_fields 或 !function 的 Field 會被視為錯誤。

A field with no unnamed_fields and no !function is in error.

Argument Sets

Argument Set 定義用來保存從指令中所擷取出來各欄位的值。

1
2

args_def    := '&' identifier ( args_elt )+ ( !extern )?
args_elt    := identifier

其語法由 & 開頭，隨後緊接著一個或多個的 identifier ，並可再加上可選的 !extern 。

• identifier 可由開發者自訂，如：regs、loadstore… 等。
• !extern 則表示是否在其他地方已經由其他的 decoder 定義過。如果加上的話，就不會再次生成對應的 argument set struct。

Examples

1

&ampreg3 ra rb rc

會生成以下的 argument set struct：

1
2
3
4
5

typedef struct {
    int ra;
    int rb;
    int rc;
} arg_reg3;

1

&loadstore reg base offset

則會生成以下的 argument set struct：

1
2
3
4
5

typedef struct {
    int base;
    int offset;
    int reg;
} arg_loadstore;

因此，以剛剛的 RISC-V U-type 指令為例，我們需要從指令中擷取 imm 及 rd 欄位的值，可以宣告其 argument set 如下：

1

&u    imm rd

最後會生成以下的 argument set struct：

1
2
3
4

typedef struct {
    int imm;
    int rd;
} arg_u;

此 argument set struct 會被傳入由 Format 定義所生成的 extract function：

1
2
3
4
5

static void decode_insn32_extract_u(DisasContext *ctx, arg_u *a, uint32_t insn)
{
    a->imm = ex_shift_12(ctx, sextract32(insn, 12, 20));
    a->rd = extract32(insn, 7, 5);
}

所傳入的arg_u 會保存從指令中擷取出的 imm 及 rd 欄位的值，待後續使用。

Formats

Format 定義了指令的格式 (如 RISC-V 中的 R、I、S、B、U、J-type)，並會生成對應的 decode function。

1
2
3
4
5
6

fmt_def      := '@' identifier ( fmt_elt )+
fmt_elt      := fixedbit_elt | field_elt | field_ref | args_ref
fixedbit_elt := [01.-]+
field_elt    := identifier ':' 's'? number
field_ref    := '%' identifier | identifier '=' '%' identifier
args_ref     := '&' identifier

其語法由 @ 開頭，隨後緊接著一個 identifier 及一個以上的 fmt_elt。

• identifier 可由開發者自訂，如：opr、opi… 等。
• fmt_elt 則可以採用以下不同的語法：

  • fixedbit_elt 包含一個或多個 0、1、.、-，每一個代表指令中的 1 個 bit。

    • . 代表該 bit 可以用 0 或是 1 來表示。
    • - 代表該 bit 完全被忽略。

  • field_elt 可以用 Field 的語法來宣告。

    • Eg：ra:5、rb:5、lit:8

  • field_ref 有下列兩種格式 (以下範例參考上文所定義之 Field)：

    • '%' identifier：直接參考一個被定義過的 Field。

      • 如：%rd，會生成：

        1	a->rd = extract32(insn, 7, 5);

    • identifier '=' '%' identifier：直接參考一個被定義過的 Field，但透過第一個 identifier 來重新命名其所對應的 argument 名稱。此方式可以用來指定不同的 argument 名稱來參考至同一個 Field。

      • 如：my_rd=%rd，會生成：

        1	a->my_rd = extract32(insn, 7, 5); // rd 被重新命名為 my_rd

  • args_ref 指定所傳入 decode function 的 Argument Set。若沒有指定 args_ref 的話，Decodetree 會根據 field_elt 或 field_ref 自動生成一個 Argument Set。此外，一個 Format 最多隻能包含一個 args_ref。

當 fixedbit_elt 或 field_ref 被定義時，該 Foramt 的所有的 bits 都必須被定義 (可透過 fixedbit_elt 或 . 來定義各個 bits，空格會被忽略)。

Examples

1

@opi    ...... ra:5 lit:8    1 ....... rc:5

定義了 op1 這個 Format，其中：

• insn[31:26] 可為 0 或 1。
• insn[25:21] 為 ra。
• insn[20:13] 為 lit。
• insn[12] 固定為 1。
• insn[11:5] 可為 0 或 1。
• insn[4:0] 為 rc。

此 Format 會生成以下的 decode function：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

typedef struct {
    int lit;
    int ra;
    int rc;
} arg_decode_insn320;


static void decode_insn32_extract_opi(DisasContext *ctx, arg_decode_insn320 *a, uint32_t insn)
{
    a->ra = extract32(insn, 21, 5);
    a->lit = extract32(insn, 13, 8);
    a->rc = extract32(insn, 0, 5);
}

由於我們沒有指定 args_ref，因此 Decodetree 根據了 field_elt 的定義，自動生成了 arg_decode_insn320 這個 Argument Set。

以 RISC-V I-type 指令為例：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# Fields:
%rs1       15:5
%rd        7:5

# immediates:
%imm_i    20:s12

# Argment sets:
&i    imm rs1 rd

@i       ........ ........ ........ ........ &i      imm=%imm_i     %rs1 %rd

定義了 i 這個 Format，其中：

• insn[31:20] 為 imm，且為 sign-extended。
• insn[19:5] 為 rs1。
• insn[11:7] 為 rd。

此外，我們可以看到：

• 此 Format 指定了 Argument Set：&i。 &i 中必須包含所有有用到的 arguments (也就是：imm、rs1 及 rd)
• imm 是透過重新命名的方式來參考 %imm_i 這個 Field。

此範例會生成以下的 decode function：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

typedef struct {
    int imm;
    int rd;
    int rs1;
} arg_i;


static void decode_insn32extract_i(DisasContext *ctx, arg_i *a, uint32_t insn)
{
    a->imm = sextract32(insn, 20, 12); // imm_i 被重新命名為 imm
    a->rs1 = extract32(insn, 15, 5);
    a->rd = extract32(insn, 7, 5);
}

相比於第一個範例，由於這次我們有指定 args_ref：&i，因此對應的 arg_i 會被傳入 decode function。

回到先前的 RISC-V U-type 指令，我們可以如同 I-type 指令定義其格式：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# Fields:
%rd        7:5

# immediates:
%imm_u    12:s20                 !function=ex_shift_12

# Argument sets:
&u    imm rd

@u       ....................      ..... ....... &u      imm=%imm_u          %rd

定義了 u 這個 Format，其中：

• insn[31:12] 為 imm，且為 sign-extended。
• insn[11:7] 為 rd。

會生成以下的 decode function：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

typedef struct {
    int imm;
    int rd;
} arg_u;


static void decode_insn32_extract_u(DisasContext *ctx, arg_u *a, uint32_t insn)
{
    a->imm = ex_shift_12(ctx, sextract32(insn, 12, 20));
    a->rd = extract32(insn, 7, 5);
}

我們可以看到：

• 此 Format 指定了 Argument Set：&u。 &u 中必須包含所有有用到的 arguments (也就是：imm、rd)
• imm 是透過重新命名的方式來參考 %imm_u 這個 Field。

以上就是 Decodetree 的 Fields、Argument Sets 及 Formats 語法的簡介。剩下的 Patterns 及 Pattern Groups 就留到 Part 2. 再做介紹。

decodetree 參數

• --translate：translator function 的 prefix，預設為 trans。一旦指定後，translator function 的 scope 就不會再是 static。
• --decode：decode function 的 prefix，預設為 decode，且 scope 為 static。一旦指定後，decode function 的 scope 就不會再是 static。
• --static-decode：如同 --decode，不過 decode function 的 scope 仍維持為 static。
• -o / --output：指定生成的 decoder .c 檔路徑。
• -w / --insnwidth：指令長度，eg：32 or 16，預設為 32。
• --varinsnwidth：指令為不定長度。
• 最後一個參數為輸入的 decode 檔路徑。

執行範例：

1
2

./decodetree.py -o target/riscv/decode_insn16.inc.c --static-decode decode_insn16 \
    -w 16 ./insn16.decode