TDB介紹

TDB(TPU DeBugger)是針對TPU-MLIR編譯出來的BModel設計的一系列調試工具集合, 可以支持對BModel反匯編、結構可視化、單步執行仿真等功能，使用方法靈活。能夠快速定位BModel與原始模型推理結果不一致的問題，進而修復TPU-MLIR的編譯或模型出錯點。

下圖是TDB工具集的框架。

TDB主要是基于Python開發的，其核心功能模塊包括TPU架構相關的指令解析、指令運行、數據IO功能，以及通用的BModel反匯編框架及MLIR的索引機制。在此基礎上，形成了TDB調試、BModel_checker, BModel_dis, MLIR2graph等工具。TDB目前支持的處理器包括BM1684、BM1684X。

下表是TDB工具的具體功能

本文重點介紹tdb.py的使用方法和實現細節。

tdb.py的使用

tdb.py提供了一個和pdb、gdb界面類似的調試窗口，用于分析BModel運行，支持添加斷點，單步執行，查看內存數據（修改內存數據），數據比對。相關差異可參考下圖：

進入調試

usage:tdb.py[-h][--inputs[INPUTS]][--ref_data[REF_DATA...]][--plugins[PLUGINS]][--ddr_size[DDR_SIZE]][-v][context_dir]

TPUDebugger.

positionalarguments:
context_dirThepathofBModel.

options:
-h,--helpshowthishelpmessageandexit
--inputs[INPUTS]TheinputsdataoftheBModel.
--ref_data[REF_DATA...]
ThereferencedataoftheBModel.
--plugins[PLUGINS]Theextrapluginstobeadded.
--ddr_size[DDR_SIZE]
Theddr_sizeofcmodel.
-v,--verboseuseprogressbar

在context_dir直接運行tdb.py即可調試當前目錄下的compilation.bmodel文件；可通過--ref_data來傳入參考數據，示例如下：

tdb.py--ref_data../yolov5s_1o_bm1684x_f32_tpu_outputs.npz

調試命令

在進入TDB后，可以使用多個快捷命令來控制運行狀態。按下兩次tab或者鍵入 ? 獲取命令提示。

基本命令

插件系統

為了減少代碼的冗余程度，設計上TDB本體只負責對指令執行過程的基本控制，而額外通過插件系統對TDB的功能進行擴展。插件提供的功能包括：

• 在TDB執行指令的不同生命周期接收回調信息
• 對TDB本身的指令進行擴展

目前內置的“插件” 有 breakpoints、display、info、data-check 等，可以根據需求實現自己的TDB插件。

breakpoint

breakpoint插件用于實現斷點功能，在設計之初就考慮了可以通過多種形式添加斷點，包括指令名、指令地址、指令id、mlir的Operation名、value-id、location...等，同時可以根據需求靈活建立斷點。

目前支持的斷點類型包括：

display

display目前支持的較為簡陋，是通過對info函數的python調用封裝實現的：

display self.info("asm 5")

data-checker

默認在通過--ref_data傳入數據的情況下會直接開啟。也可以通過Bmodel_checker.py 使用

print

提供了內置的一些打印功能，主要聚焦于打印當前指令以及指令對應的數據，并會在TDB每一個stop時打印待執行的下一個atomic command

info

提供了內置的一些打印功能，主要聚焦于打印出不同格式的當前指令的上下文。

實現細節

文件結構

debugger首先提供了完整的指令解析和運行功能，這一部分的核心代碼位于 debugger/target_{產品型號/產品型號/common}。其中不同處理器在指令解析、cModel運行等方式的實現均有差異，這些差異分別在各自的文件夾中實現。而一部分相同的內容和對差異行為的抽象的聲明則在 python/debugger/target_common/ 目錄下提供。這部分內容比較復雜，在后面單獨介紹。

此外，debugger下還有一些其他文件，包括

• debugger/disassembler.py：提供對Bmodel 文件的基本解析
• debugger/atomic_dialect.py：基于disassembler.py，將 Bmodel的內容轉換為 mlir 的類型系統
• debugger/final_mlir.py：解析 `final.mlir`` 文件并建立索引供 TDB使用
• debugger/tdb_support.py：提供了基于cmd.Cmd的基本的TDB功能的實現，同時加載 bmodel、日志、斷點的基類、插件系統等。

各自的target_{device} 下提供的功能在后面介紹。而target_common包括

• context.py：提供了CModelContext 這一基類以及相關方法的聲明
• cmodel.py：提供了CModelRunner 和 Memory 兩個基類，提供了一些方法的聲明
• decoder.py：提供了 Decoder 類定義以及解析tiu dma指令方法的聲明
• op_support.py：提供了一些類型定義、Layout、MemoryType 等枚舉類型的聲明、一些公共方法、以及一些Operation 基類聲明

集成上下文環境

為了更方便的獲取不同target的相同功能（如指令解析或執行），每個target 需要繼承CModelContext并實現自己的TargetContext來主動暴露自己提供功能。每個TargetContext需要以類變量的方式定義：

• MemRef：描述了一塊內存區域的view（address、dtype、layout等）
• device：描述了該target的類型
• memmap：描述了處理器上的內存地址信息
• dma_sys、tiu_sys（部份處理器）：描述了停止指令的類型
• get_memory_type：根據輸入地址獲取地址類型（global、local、l2等 ）
• get_runner：獲取該target運行指令的Runner實例
• 其他，如local_layout_to_stride，
• merge_instruction：在每個subnet中，atomic指令滿足DAG，所以可以進行 topological sort（這一功能實際應該由 Decoder 提供），從而可以被順序執行

每個TDB實例在加載BModel后，會根據BModel的處理器來獲取到對應target的Context實例（是實例而不是類），從而能實現指令的解析和執行。

指令解析

每個target都需要繼承DecoderBase并實現自己的Decoder來提供各個target的指令解析功能，每個Decoder都需要實現以下接口：

• decode_tiu_cmd
• decode_tiu_cmds
• decode_dma_cmd
• decode_dma_cmds

BModel中，指令以CmdGroup（對多核實現，通過CoreCmdGroup）的形式存儲，在python/debugger/atomic_dialect.py中定義了decode_cmdgroup，可以看做是調用Decoder方法的入口

defdecode_cmdgroup(
context:CModelContext,cmd_group:CmdGroup,subnet_id:int,core_id=0
)->StaticCmdGroup:
context=context
decoder=context.decoder

tiu=decoder.decode_tiu_cmds(cmd_group.tiu_cmd,core_id=core_id)
dma=decoder.decode_dma_cmds(cmd_group.dma_cmd,core_id=core_id)

cmdgroup=StaticCmdGroup(tiu,dma,context.merge_instruction(tiu,dma))
#hackinjectionsubnet_id
forcmdincmdgroup.all:
cmd.subnet_id=subnet_id
returncmdgroup

指令運行

每個target都需要繼承MemoryBase和CModelRunner并實現自己的 Memory和TargetRunner來提供各個target的指令運行功能，其中：

• 每個Memory都需要實現set_data、get_data、clear_memory方法
• 每個TargetRunner都需要實現tiu_compute、dma_compute、init_memory、clear_memory、dynamic_compute 等方法

其中，Runner實例默認需要包含對應target的Memory實例。

插件系統

插件系統同時支持了指令執行回調和TDB功能擴展，相關的代碼位置包括：

• 插件基類：tdb_support.py:TdbPlugin
• 指令擴展基類：tdb_support.py:TdbPluginCmd
• 回調注冊功能實現：tdb_support.py:add_callback
• tdb 中實現相關邏輯：tdb_support.py:TdbCmdBackend.add_plugin
• tdb 中注冊生命周期：tdb.py中各個地方添加的 add_callback 裝飾器
• 各個 plugin 的具體實現：plugins/xxx.py

總結

BModel調試不是一件容易的事情，TDB提供了一種手段，可以看到BModel內部的推理過程并進行干預。本文介紹了TDB的使用方法和實現細節, 一方面讓大家熟悉BModel的調試方法，能夠更快地定位模型轉換過程中的問題并修復；另一方面，可以，并分析指令的格式和內容，增加開發的背景知識。