深入學習和掌握TPU硬件架構(gòu)有困難？TDB助力你快速上手！

TDB介紹

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

下圖是TDB工具集的框架。

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

下表是TDB工具的具體功能

本文重點介紹tdb.py的使用方法和實現(xiàn)細節(jié)。

tdb.py的使用

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

進入調(diào)試

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即可調(diào)試當前目錄下的compilation.bmodel文件；可通過--ref_data來傳入?yún)⒖紨?shù)據(jù)，示例如下：

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

調(diào)試命令

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

基本命令

插件系統(tǒng)

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

• 在TDB執(zhí)行指令的不同生命周期接收回調(diào)信息
• 對TDB本身的指令進行擴展

目前內(nèi)置的“插件” 有 breakpoints、display、info、data-check 等，可以根據(jù)需求實現(xiàn)自己的TDB插件。

breakpoint

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

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

display

display目前支持的較為簡陋，是通過對info函數(shù)的python調(diào)用封裝實現(xiàn)的：

display self.info("asm 5")

data-checker

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

print

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

info

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

實現(xiàn)細節(jié)

文件結(jié)構(gòu)

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

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

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

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

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

集成上下文環(huán)境

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

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

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

指令解析

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

• decode_tiu_cmd
• decode_tiu_cmds
• decode_dma_cmd
• decode_dma_cmds

BModel中，指令以CmdGroup（對多核實現(xiàn)，通過CoreCmdGroup）的形式存儲，在python/debugger/atomic_dialect.py中定義了decode_cmdgroup，可以看做是調(diào)用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并實現(xiàn)自己的 Memory和TargetRunner來提供各個target的指令運行功能，其中：

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

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

插件系統(tǒng)

插件系統(tǒng)同時支持了指令執(zhí)行回調(diào)和TDB功能擴展，相關(guān)的代碼位置包括：

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

總結(jié)

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