11/15/2026

PciConfigDump 工具使用說明 (User Guide & Technical Reference)

 本文件針對 PciConfigDumpFull.py 與 PciConfigDumpSingle.py 兩支基於 EfiPy2 框架開發的 PCI/PCIe 配置空間 (Configuration Space) 傾印與符號化解碼工具進行完整功能說明與操作指引。


一、 工具設計目的與核心特色

在 UEFI/BIOS 韌體開發、晶片驗證 (Silicon Bring-up) 與硬體除錯過程中,工程師經常需要檢核 PCI/PCIe 設備的配置空間暫存器。傳統 UEFI Shell 內建之 pci 指令或 dmem 工具多半僅提供基礎的 256 位元組 HexDump,或只能做非常有限的固定欄位解讀,對於 PCIe 4KB 延伸配置空間 (Extended Configuration Space) 以及動態 Capabilities 鏈結串列往往無法完整走訪與解析。

PciConfigDump 系列工具結合 EfiPy2 的 ACPI MCFG 解析器、動態結構建構引擎 (BuildPciHeader)、HexDump 與結構化解析 (DumpStruct),具備以下核心特色:

  1. ACPI MCFG / ECAM MMIO 直接實體映射:
    • 透過 ACPI MCFG 表格動態獲取各 Segment Group 的 Base Address。
    • 支援完整的 PCI Express 4KB 配置空間存取(突破 Legacy I/O Port 0xCF8/0xCFC 僅能存取 256 位元組之限制),且可無縫支援多 PCI Segment (多 Socket / 多 Domain) 架構。
  2. 動態能力鏈結串列走訪 (Dynamic Capability Walking):
    • 標準能力鏈 (Standard Capabilities):自 Offset 0x34 循序走訪並動態載入對應之 Ctypes 結構(如 PCIe Cap, MSI, MSI-X, Power Management, HotPlug, HyperTransport 等)。
    • PCIe 延伸能力鏈 (PCIe Extended Capabilities):若判定為 PCIe 設備,自動由 Offset 0x100 起走訪 4KB 延伸空間(如 AER, Virtual Channel, Serial Number, ACS, ARI, SR-IOV, LTR, L1 PM Substates 等)。
    • 自動孔洞填補 (Hole Alignment):鏈結間未使用的保留空間自動以 Reserved 位元組陣列填補,保證整體結構記憶體對齊與實體暫存器完全吻合。
  3. 雙重視角同步輸出 (Dual-View Output):
    • [1] Configuration Space HexDump:以 16 進位與 ASCII 字元對照方式呈現原始記憶體鏡像,並標註實體 MMIO 絕對位址。
    • [2] Configuration Space StructDump:以樹狀符號化階層展開所有暫存器與位元欄位 (Bitfields),清楚顯示各暫存器之數值、名稱與位元寬度。
  4. 靈活的工具定位與分工:
    • PciConfigDumpFull.py:全系統全自動掃描與批次傾印,適用於開機全域硬體存證、出廠檢驗與完整報表生成。
    • PciConfigDumpSingle.py:指定單一設備 (SBDF) 進行靶向精確傾印,具備命令列參數靈活覆蓋與強健之防呆機制,適用於針對性硬體除錯。

二、 工具規格比較表

項目PciConfigDumpFull.pyPciConfigDumpSingle.py
目標對象系統中所有存活的 PCI/PCIe 設備使用者指定之單一 PCI/PCIe 設備
輸入方式無需參數,自動枚舉支援命令列 positional target 或 -s/-b/-d/-f 選項
執行耗時依設備數量而定(約數秒,輸出規模龐大)極短(瞬時完成單一設備讀取與解碼)
輸出規模數萬行至數十萬行(建議重導向至檔案)數百行(適合終端直接檢視或重導向)
適用情境完整平台配置留存、全域 BAR/Cap 審查單一控制器調校、鏈路狀態除錯、AER 錯誤排查

三、 指令語法與參數說明

1. PciConfigDumpFull.py (全域傾印工具)

語法

python PciConfigDumpFull.py

說明

  • 執行時無須任何參數。
  • 腳本會透過 ScanPciDevices(AccessMode=PCI_ACCESS_MCFG) 自動搜尋系統中所有存活設備。
  • 對於每個找到的設備,自動匹配 MCFG 描述表中的 Segment 與 Bus 範圍,計算出 ECAM MMIO 位址並執行完整 HexDump 與 StructDump。
  • 強烈建議:因輸出資料極為豐富,請使用 UEFI Shell 重導向符號 > 將結果輸出至儲存裝置中的文字檔案(例如 fs0:\PciConfigDumpFull.txt)。

2. PciConfigDumpSingle.py (單一設備傾印工具)

語法

python PciConfigDumpSingle.py [target] [-s SEG] [-b BUS] [-d DEV] [-f FUNC]

參數規格表

參數名稱縮寫類型預設值說明
target(無)字串 (選填)None目標設備之 SBDF 格式字串(詳見下述格式說明)
--segment-s整數 (選填)0指定 PCI Segment Group Number (支援十進位或 0x 前綴十六進位)
--bus-b整數 (選填)None指定 PCI Bus Number (0 ~ 255)
--device-d整數 (選填)None指定 PCI Device Number (0 ~ 31)
--func-f整數 (選填)0指定 PCI Function Number (0 ~ 7)
--help-h旗標-顯示說明訊息並退出

Target 支援的 SBDF 格式

target 支援業界常見之多種表示法(大小寫不拘):

  1. 完整格式:[Seg:]Bus:Dev.Func
    • 範例:0000:00:02.0、00:02.0、0:2.0
  2. 冒號分隔格式:[Seg:]Bus:Dev:Func
    • 範例:0000:00:02:0、00:02:0
  3. 簡寫格式:Bus:Dev(Function 自動預設為 0,Segment 預設為 0)
    • 範例:00:02、0:2

Tip

參數覆蓋機制 (Override Rule):
若同時傳入 target 與獨立選項(如 -s、-b、-d、-f),獨立選項具有最高優先權,將覆蓋 target 中解析出的相應欄位。
例如:python PciConfigDumpSingle.py 00:02.0 -f 1 將會傾印 0000:00:02.1。

防呆與存在性檢測

  • 範圍檢查:Bus 超出 0255、Device 超出 031 或 Function 超出 0~7 時,會立即回報錯誤並退出。
  • ACPI MCFG 檢查:若系統未提供 MCFG 表,或指定的 Segment/Bus 不在 MCFG 覆蓋範圍內,會印出錯誤訊息並終止。
  • 設備存在性檢查:若目標暫存器之 Vendor ID 為 0xFFFF 或 0x0000,表示該插槽/BDF 無設備在線,工具會回報:
    Device 0000:00:1F.5 not present (Vendor ID = 0xFFFF)
    
    並安全退出,不會觸發非法存取例外。

四、 輸出格式與欄位解讀指南

每次傾印輸出均包含三大區塊:[標頭資訊 (Banner)]、[[1] HexDump] 與 [[2] StructDump]。

1. 標頭資訊 (Banner & MMIO Address)

====================================================================================================
0000:00:01.0 VGA compatible controller: VGA controller (3,0,0): Red Hat, Inc.: QXL paravirtual graphic card (1B36 0100 rev: 05)
Type: PCI (256B), MMIO: 0xE0008000 (Base: 0xE0000000, ECAM Offset: 0x00008000)
====================================================================================================
  • 第 1 行:設備基本身分資訊:
    • 0000:00:01.0:[Segment:Bus:Device.Function]。
    • VGA compatible controller: VGA controller (3,0,0):PCI Class Code 類別描述與代碼 (BaseClass, SubClass, ProgIf)。
    • Red Hat, Inc.: QXL paravirtual graphic card:由 Vendor ID (0x1B36) 與 Device ID (0x0100) 自動查詢 PCI-ID 資料庫還原之廠商與產品名稱。
    • rev: 05:Revision ID。
  • 第 2 行:
    • Type:標記該設備為傳統 PCI (256B) 或具備擴充空間的 PCIe (4KB)。
    • MMIO:該設備配置空間於系統實體記憶體空間之 ECAM 基底位址。
    • Base:ACPI MCFG 中該 Segment/Bus Range 所對應之 MMIO Base Address。
    • ECAM Offset:依據公式 (Bus << 20) | (Dev << 15) | (Func << 12) 所得之內部偏移量。

2. [1] Configuration Space HexDump

[1] Configuration Space HexDump:
            0  1  2  3  4  5  6  7   8  9  A  B  C  D  E  F  01234567 89ABCDEF
------------------------------------------------------------------------------
E0008000   36 1B 00 01 07 00 00 00  05 00 00 03 00 00 00 00  6....... ........
E0008010   00 00 00 84 00 00 00 80  00 40 88 89 61 F2 00 00  ........ .@..a...
E0008020   00 00 00 00 00 00 00 00  00 00 00 00 F4 1A 00 11  ........ ........
...
  • 最左側標記絕對實體 MMIO 記憶體位址。
  • 中間呈現 16 位元組 Hex 數值(Little-Endian 排列)。
  • 右側呈現可印 ASCII 字元。

3. [2] Configuration Space StructDump (符號化結構解碼)

本區塊為 PciConfigDump 的精髓所在。DumpStruct 會遞迴解開 ctypes 結構,將暫存器還原為清晰的階層圖。

(1) 基本標頭 (Hdr & Cfg)

  • Hdr (Type Independent Region, 0x00~0x0F):
    • 包含 VendorId、DeviceId、Command、Status、RevisionID、ClassCode、HeaderType 等。
  • Cfg (Header Type Specific Region, 0x10~0x3F):
    • Type 00 (Endpoint 裝置):展開 6 組 Base Address Registers (Bar0 ~ Bar5),自動透過 Union 解構出 Resource (Memory 或 I/O)、Type (32-bit 或 64-bit)、Prefetchable 與 BaseAddress。
    • Type 01 (PCI-to-PCI Bridge 橋接器):展開 Primary/Secondary/Subordinate Bus Numbers、I/O Base/Limit、Memory Base/Limit、Prefetchable Memory Base/Limit 等視窗範圍暫存器。
  Cfg                                                            Struct PCI_DEVICE_HEADER_TYPE_REGION
    Bar                                                            Struct EFIPY_PCI_BAR_REGION
      Bar0                                                           Union EFIPY_PCI_BAR32_MEM
        Bits                                                           Struct EFIPY_PCI_BAR32_MEM_BITS
          Resource                                               0x00000000 (1)
          Type                                                   0x00000000 (2)
          Prefetchable                                           0x00000000 (1)
          BaseAddress                                            0x08400000 (28)
        Uint32                                                         0x84000000

Note

欄位數值右側括號內的數字(例如 (28) 或 (1))代表該 Bitfield 所佔用的位元寬度 (Bit Width)。

(2) 標準能力鏈結 (Standard Capabilities)

若設備支援擴充能力,BuildPciHeader 會自動將各節點掛載於根層級,並以其結構名稱命名:

  • PCIe Capability (PCI_CAPABILITY_PCI_EXP):
    • Capability:版本、設備/連接埠類型 (PortType)、中斷訊息號碼。
    • DeviceCapability / DeviceControl / DeviceStatus:Max Payload Size (MPS)、Error Reporting 開關、FLR 支援等。
    • LinkCapability / LinkControl / LinkStatus:最大/目前鏈路速度 (LinkSpeed)、最大/目前鏈路寬度 (LinkWidth)、ASPM 狀態等。
  • MSI / MSI-X (PCI_CAPABILITY_MSI / MSI_X):訊息控制暫存器、32/64-bit 訊息位址、訊息資料與遮罩暫存器。
  • 電源管理 (PCI_CAPABILITY_PM):Power Management Capabilities (PMC)、Control/Status (PMCSR)。

(3) PCIe 延伸能力鏈結 (PCIe Extended Capabilities, 4KB 空間)

若為 PCIe 裝置,將進一步解析 0x100 以上之結構:

  • AER (PCI_EXPRESS_EXTENDED_AER):Uncorrectable Error Status/Mask/Severity、Correctable Error Status/Mask、Advanced Error Capabilities & Control、16-Byte Header Log、Root Error Status 等。
  • 虛擬通道 (PCI_EXPRESS_EXTENDED_CAPABILITIES_VIRTUAL_CHANNEL_CAPABILITY)。
  • 設備序號 (PCI_EXPRESS_EXTENDED_CAPABILITIES_SERIAL_NUMBER)。
  • SR-IOV (SR_IOV_CAPABILITY_REGISTER)。
  • ACS / ARI / L1 PM Substates。

五、 操作範例與使用情境

情境 1:全系統硬體存證 (Full System Snapshot)

在交付韌體或進行回報時,抓取全系統所有設備的配置空間快照:

# 在 UEFI Shell 下執行,並重新導向至硬碟或隨身碟
fs0:\> python PciConfigDumpFull.py > PciConfigDump_FullReport.txt

情境 2:指定 BDF 快速檢視單一設備

透過常見的 Bus:Dev.Func 格式傾印內建顯示卡或指定裝置:

# 傾印 00:01.0 (QEMU QXL 顯卡)
fs0:\> python PciConfigDumpSingle.py 00:01.0

# 傾印 00:1F.3 (音效控制器)
fs0:\> python PciConfigDumpSingle.py 00:1f.3

情境 3:十進位與十六進位獨立參數組合

當在指令檔中動態代入變數時,可使用獨立參數:

# 使用 16 進位指定 Bus 0, Device 0x1B, Function 0
fs0:\> python PciConfigDumpSingle.py -b 0x00 -d 0x1B -f 0

# 使用 10 進位指定 Bus 0, Device 27, Function 0
fs0:\> python PciConfigDumpSingle.py -b 0 -d 27 -f 0

情境 4:多 Segment 系統 (Multi-Socket Server) 傾印

在具備多個 PCI Domain/Segment 的伺服器平台上:

# 傾印 Segment 1, Bus 0x10, Device 0, Function 0
fs0:\> python PciConfigDumpSingle.py 0001:10:00.0

# 或使用 -s 參數覆蓋
fs0:\> python PciConfigDumpSingle.py 10:00.0 -s 1

情境 5:檢查不存在的設備

若嘗試存取未安裝或未上電的設備,工具會優雅提示而非閃退:

fs0:\> python PciConfigDumpSingle.py 00:09.0
Device 0000:00:09.0 not present (Vendor ID = 0xFFFF)

六、 配合 UEFI Shell NSH 批次檔自動化

可將常用的診斷指令包裝於 .nsh 批次檔中。

範例:DumpPciQuick.nsh

@echo off
echo ===================================================
echo [EfiPy2] Dumping Specific PCI Configuration Spaces
echo ===================================================

echo Dumping Root Complex / Host Bridge (00:00.0)...
python PciConfigDumpSingle.py 00:00.0 > HostBridge_00_00_0.txt

echo Dumping Primary Display Controller (00:01.0)...
python PciConfigDumpSingle.py 00:01.0 > Display_00_01_0.txt

echo Dumping Network Controller (00:02.0)...
python PciConfigDumpSingle.py 00:02.0 > Network_00_02_0.txt

echo All dumps completed.

七、 程式碼架構與底層模組相依性

兩支腳本均位於目錄 Efi\Apps\EfiPy2Sample\,其核心相依於 EfiPy2 之標準系統函式庫:

EfiPy2Sample/
  ├── PciConfigDumpFull.py            # 全域掃描與傾印主程式
  ├── PciConfigDumpSingle.py          # 單一裝置傾印主程式
  └── PciConfigDump.md                # 本說明文件
         │
         ├──> EfiPy2.Lib.Acpi.AcpiRetrieve      # ACPI Table (MCFG) 抽取模組
         ├──> EfiPy2.Lib.Acpi.AcpiMcfgParser    # ACPI MCFG 記憶體映射配置表解析器
         ├──> EfiPy2.Lib.PciScanLib             # PCI 設備枚舉與資訊格式化函式庫
         ├──> EfiPy2.Lib.PciConfigurationSpace  # 動態動態結構與 Capability 鏈結建構引擎 (BuildPciHeader)
         ├──> EfiPy2.Lib.HexDump                # 記憶體區塊 16 進位傾印工具
         └──> EfiPy2.Lib.StructDump             # ctypes 符號化階層解析輸出工具

關鍵函式呼叫剖析

  • ExtractTable(b'MCFG', 0):從 UEFI System Configuration Table 中搜尋 ACPI 2.0 / 1.0 表格,擷取簽章為 MCFG 之原始二進位資料。
  • AcpiMcfgParser(AcpiRaw):解碼 MCFG 內容,取得 BaseAddress 與對應之 PciSegmentGroupNumber、StartBusNumber、EndBusNumber。
  • BuildPciHeader(McfgDesc.BaseAddress, PciCfgOffset):
    1. 讀取實體 MMIO 偏移,判定 HeaderType(Type 00 Endpoint 或 Type 01 Bridge)。
    2. 依循 Offset 0x34 之 CapabilitiesPtr 依序解析 Standard Capabilities。
    3. 檢測是否存在 PCIe Capability(ID 0x10);若存在則進一步從 Offset 0x100 走訪 Extended Capabilities。
    4. 回傳 (PciObj, PciType, IsPcieDevice),其中 PciObj 映射實體位址,可直接供 HexDump 與 DumpStruct 輸出。