本文件針對 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),具備以下核心特色:
- ACPI MCFG / ECAM MMIO 直接實體映射:
- 透過 ACPI MCFG 表格動態獲取各 Segment Group 的 Base Address。
- 支援完整的 PCI Express 4KB 配置空間存取(突破 Legacy I/O Port 0xCF8/0xCFC 僅能存取 256 位元組之限制),且可無縫支援多 PCI Segment (多 Socket / 多 Domain) 架構。
- 動態能力鏈結串列走訪 (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位元組陣列填補,保證整體結構記憶體對齊與實體暫存器完全吻合。
- 標準能力鏈 (Standard Capabilities):自 Offset
- 雙重視角同步輸出 (Dual-View Output):
- [1] Configuration Space HexDump:以 16 進位與 ASCII 字元對照方式呈現原始記憶體鏡像,並標註實體 MMIO 絕對位址。
- [2] Configuration Space StructDump:以樹狀符號化階層展開所有暫存器與位元欄位 (Bitfields),清楚顯示各暫存器之數值、名稱與位元寬度。
- 靈活的工具定位與分工:
PciConfigDumpFull.py:全系統全自動掃描與批次傾印,適用於開機全域硬體存證、出廠檢驗與完整報表生成。PciConfigDumpSingle.py:指定單一設備 (SBDF) 進行靶向精確傾印,具備命令列參數靈活覆蓋與強健之防呆機制,適用於針對性硬體除錯。
二、 工具規格比較表
| 項目 | PciConfigDumpFull.py | PciConfigDumpSingle.py |
|---|---|---|
| 目標對象 | 系統中所有存活的 PCI/PCIe 設備 | 使用者指定之單一 PCI/PCIe 設備 |
| 輸入方式 | 無需參數,自動枚舉 | 支援命令列 positional target 或 -s/-b/-d/-f 選項 |
| 執行耗時 | 依設備數量而定(約數秒,輸出規模龐大) | 極短(瞬時完成單一設備讀取與解碼) |
| 輸出規模 | 數萬行至數十萬行(建議重導向至檔案) | 數百行(適合終端直接檢視或重導向) |
| 適用情境 | 完整平台配置留存、全域 BAR/Cap 審查 | 單一控制器調校、鏈路狀態除錯、AER 錯誤排查 |
python PciConfigDumpFull.py- 執行時無須任何參數。
- 腳本會透過
ScanPciDevices(AccessMode=PCI_ACCESS_MCFG)自動搜尋系統中所有存活設備。 - 對於每個找到的設備,自動匹配 MCFG 描述表中的 Segment 與 Bus 範圍,計算出 ECAM MMIO 位址並執行完整 HexDump 與 StructDump。
- 強烈建議:因輸出資料極為豐富,請使用 UEFI Shell 重導向符號
>將結果輸出至儲存裝置中的文字檔案(例如fs0:\PciConfigDumpFull.txt)。
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 支援業界常見之多種表示法(大小寫不拘):
- 完整格式:
[Seg:]Bus:Dev.Func- 範例:
0000:00:02.0、00:02.0、0:2.0
- 範例:
- 冒號分隔格式:
[Seg:]Bus:Dev:Func- 範例:
0000:00:02:0、00:02:0
- 範例:
- 簡寫格式:
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 超出 0
255、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]。
====================================================================================================
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)所得之內部偏移量。
[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 字元。
本區塊為 PciConfigDump 的精髓所在。DumpStruct 會遞迴解開 ctypes 結構,將暫存器還原為清晰的階層圖。
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 等視窗範圍暫存器。
- Type 00 (Endpoint 裝置):展開 6 組 Base Address Registers (
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)。
若設備支援擴充能力,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)。
若為 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。
在交付韌體或進行回報時,抓取全系統所有設備的配置空間快照:
# 在 UEFI Shell 下執行,並重新導向至硬碟或隨身碟
fs0:\> python PciConfigDumpFull.py > PciConfigDump_FullReport.txt透過常見的 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當在指令檔中動態代入變數時,可使用獨立參數:
# 使用 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在具備多個 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若嘗試存取未安裝或未上電的設備,工具會優雅提示而非閃退:
fs0:\> python PciConfigDumpSingle.py 00:09.0
Device 0000:00:09.0 not present (Vendor ID = 0xFFFF)可將常用的診斷指令包裝於 .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):- 讀取實體 MMIO 偏移,判定 HeaderType(Type 00 Endpoint 或 Type 01 Bridge)。
- 依循 Offset 0x34 之
CapabilitiesPtr依序解析 Standard Capabilities。 - 檢測是否存在 PCIe Capability(ID
0x10);若存在則進一步從 Offset 0x100 走訪 Extended Capabilities。 - 回傳
(PciObj, PciType, IsPcieDevice),其中PciObj映射實體位址,可直接供HexDump與DumpStruct輸出。