API 參考：其他結構

本頁內容與 PDK 內的 docs\NEXUS_TUI_PLUGIN_API_REFERENCE.md 相同（依章節分頁，連結已改成站內連結）。

5.1 NxGpioCaps

NxGpioCaps 是單一後端的 GPIO 能力宣告，經 NxHostApi::GpioGetCaps 取得。報的是硬體能力，不是這塊板子的接線——「這支腳接了 reset」是 Plugin 自己的知識，經 on_config_load／on_config_save 持久化，不在本結構裡。本結構為跨 DLL 邊界的 out 參數，size_of_struct 由呼叫端填寫。

NxGpioCaps::size_of_struct

型別：NxDword

意義：由呼叫端填 sizeof(NxGpioCaps)，供降級判定使用。

合法值／哨兵：填 (NxDword)sizeof(NxGpioCaps)。

何時填：呼叫 NxHostApi::GpioGetCaps 之前，memset 之後立即填。

NxGpioCaps::gpio_pin_mask

型別：NxDword

意義：bit N ＝ 1 表示 pin N 可宣告為 NX_PIN_FUNC_GPIO_IN／NX_PIN_FUNC_GPIO_OUT。

合法值／哨兵：由 Core 依連線後端的實際能力填入，Plugin 只讀。

何時填：Core 於 NxHostApi::GpioGetCaps 呼叫成功時填入。

NxGpioCaps::int_pin_mask

型別：NxDword

意義：bit N ＝ 1 表示 pin N 支援 NX_PIN_FUNC_INT（中斷偵測）。

合法值／哨兵：由 Core 依連線後端的實際能力填入，Plugin 只讀。

何時填：同上。

NxGpioCaps::reserved

型別：reserved0／reserved1／reserved2／reserved3：各為 NxByte（結構結尾，四個各自獨立的保留位元組——NxBool 是 int，4 位元組，夾在 NxByte 之間會產生編譯器決定的 padding，故以四個具名 NxByte 補齊而非單一陣列）。

意義：保留給日後 ADC／DAC 相關能力在結尾追加使用。

合法值／哨兵：一律填 0。

何時填：memset 整個結構即可；Core 不讀取這些欄位的內容。

5.2 NxLogSpan

NxLogSpan 是單一 Log 訊息內的一段語意著色區間，經 NxHostApi::LogWriteStyled 的 spans 陣列傳入；spans／span_count 為 NULL／0 時語意等同純文字 Log。同一段文字只能屬於一個 span——「既粗體又閃爍」在同一個 span 用 style 位元組合表達，不能疊兩個 span。本結構恆為 12 位元組、全定寬欄位、自然對齊，不使用 #pragma pack。

NxLogSpan::start

型別：NxWord

意義：本 span 在 msg 內的 0-based 起始位元組位移，單位是位元組，不是字元——msg 必須為純 ASCII。位移基準是 Plugin 自己這份還沒有前綴的 msg，Core 會在存入前自動把每個 span 往後位移前綴長度，Plugin 不要自己預留前綴寬度。

合法值／哨兵：0 ~ msg 長度；多個 span 的 start 須嚴格遞增且彼此不重疊，否則 NxHostApi::LogWriteStyled 回 ERR_INVALID_PARAM，整筆不寫入。

何時填：呼叫 NxHostApi::LogWriteStyled 前，依要著色的字串片段位移填入。

NxLogSpan::len

型別：NxWord

意義：本 span 涵蓋的位元組數。

合法值／哨兵：0 表示本 span 未使用（陣列填充位）；陣列中混入 len == 0 的元素（不論位置）與整筆訊息一起被拒絕，不做部分寫入或靜默修正。

何時填：同上，實際要著色的位元組數。

NxLogSpan::fg

型別：NxByte

意義：前景語意色（NX_COLOR_*）；NX_COLOR_DEFAULT ＝沿用該列等級色。

合法值／哨兵：NX_COLOR_* 值域內的合法值。使用 Core 保留值（OK／WARN／ERROR／INFO／CHANGED／DISABLED／BG_* 等）或 >= NX_COLOR_COUNT 時：不拒絕整筆，改記為安全值（NX_COLOR_ACCENT）並記一次 WARN。

何時填：呼叫 NxHostApi::LogWriteStyled 前填入。

NxLogSpan::bg

型別：NxByte

意義：背景語意色（NX_COLOR_*）；NX_COLOR_DEFAULT ＝沿用面板底色。

合法值／哨兵：規則同 NxLogSpan::fg；使用保留值時改記為 NX_COLOR_DEFAULT 並記一次 WARN。

何時填：同上。

NxLogSpan::style

型別：NxByte

意義：NX_LOG_STYLE_* 位元組合；未定義位元一律被 Core 遮掉（& 0x0F）。

合法值／哨兵：

何時填：呼叫 NxHostApi::LogWriteStyled 前，依需要的樣式組合這些位元。

NxLogSpan::fg_alt

型別：NxByte

意義：NX_LOG_STYLE_BLINK 相位 1 的前景色；NX_COLOR_DEFAULT ＝與 bg 相同（視覺上文字在相位 1 消失）。

合法值／哨兵：NX_COLOR_* 值域內的合法值；未設定 NX_LOG_STYLE_BLINK 時本欄位不影響呈現。

何時填：設定 NX_LOG_STYLE_BLINK 且需要指定相位 1 前景色時填；不需要時留 NX_COLOR_DEFAULT（0）。

NxLogSpan::bg_alt

型別：NxByte

意義：NX_LOG_STYLE_BLINK 相位 1 的背景色；NX_COLOR_DEFAULT ＝沿用 bg（相位交替只影響前景）。

合法值／哨兵：NX_COLOR_* 值域內的合法值。

何時填：同 NxLogSpan::fg_alt。

NxLogSpan::reserved

型別：reserved0：NxByte [3]（結構結尾）。

意義：保留欄位，維持本結構恆為 12 位元組、自然對齊、無 padding 的既有不變式。

合法值／哨兵：一律填 0。

何時填：memset 整個結構即可；Core 不讀取這個欄位的內容。

5.3 NxCommandDef

NxCommandDef 是一筆 Plugin 自訂指令的定義，經 IcPlugin::commands 陣列宣告；指令表由 Plugin 擁有且必須是靜態生命期，Core 只讀不釋放。headless 掛載沒有 Widget 面板也沒有 Canvas，自訂指令是它唯一的互動手段。

NxCommandDef::name

型別：const char *

意義：指令名稱（不含參數）。

合法值／哨兵：靜態字串；與內建指令同名（含別名與簡碼）時內建優先：本筆自訂指令照常註冊但永遠叫不到，Host 在 Plugin 載入時記一筆 WARN（例：run 是內建的 run <script.lua>，Plugin 不得再用）。

何時填：宣告 commands[] 靜態表時。

NxCommandDef::help

型別：const char *

意義：一行說明。Host 的 help 輸出在內建指令之後以「Plugin commands」區塊列出每筆自訂指令的名稱與這一行（內建指令撞名者不列）。

合法值／哨兵：靜態字串；可為 NULL（視為空字串）。過長者在 Host 端截斷（約 95 字元）。

何時填：同上。

NxCommandDef::usage

型別：const char *

意義：用法字串（例如 "dump <bank>"）。handler 回傳非 ERR_OK 時，Host 會記一則 INFO Log usage: <字串> 當提示；help 輸出的「Plugin commands」區塊也以它顯示引數。

合法值／哨兵：靜態字串；可為 NULL 或空字串（不記提示、不顯示引數列）。過長者在 Host 端截斷。

何時填：同上。

NxCommandDef::handler

型別：NxCommandFn（函式指標，簽章 NxLong (NX_CALL *)(NxPluginCtx ctx, int argc, const char *const *argv)）

意義：指令的處理函式。在該 mount 所綁定後端的 I2C Worker Thread 上呼叫（sdk/nexus_plugin_api.h 對 NxCommandFn 的 @warning；並非全域唯一一條，見 PLUGIN_GUIDE 第 4 章），且已包在 SEH 保護邊界內——本 handler 內部發生的例外不會波及主程式，但不會以「這次指令呼叫失敗」的形式回到呼叫端：崩潰會把整個掛載標記為故障（Tab 標題顯示故障後綴，自此不再被呼叫任何 callback），而派發函式本身連同它回填的回傳值一律回報 ERR_OK——崩潰不會產生「對應這個錯誤的訊息」，使用者看到的是一筆通用的 ERROR（「plugin ‘<name>’ faulted in command; taken offline」）。argv 僅在本次呼叫期間有效，argv[0] 為指令名本身。handler 正常返回（未崩潰）且回傳非 ERR_OK 時，Host 記的同樣是一筆通用的「job 失敗」訊息（op／addr／offset／len 格式，對指令類 Job 而言後三者恆為 0，不是針對該錯誤量身打造的說明）。

合法值／哨兵：不得為 NULL；為 NULL 時本筆指令視同不存在（呼叫時回 ERR_NOT_FOUND）。

何時填：宣告 commands[] 靜態表時。

5.4 NxRegSemantic

NxRegSemantic 是一筆暫存器語意描述（選用），經 IcPlugin::reg_semantics 陣列宣告。標頭文件描述的設計意圖是供 UI 呈現「這個位址是什麼」，但如 IcPlugin::reg_semantics 一節所述，目前沒有任何程式碼讀取這份表，宣告它不會在畫面上產生任何可觀察效果；以下各欄位節描述的是本結構本身的資料形狀，供日後接上消費端時使用。

NxRegSemantic::bank

型別：NxByte

意義：所屬 Bank。

合法值／哨兵：0～0xFF。

何時填：宣告 reg_semantics[] 靜態表時。

NxRegSemantic::offset

型別：NxByte

意義：暫存器位移。

合法值／哨兵：0～0xFF。

何時填：同上。

NxRegSemantic::bit_shift

型別：NxByte

意義：欄位的最低位元位置。

合法值／哨兵：0～7；整個位元組時填 0。

何時填：同上。

NxRegSemantic::bit_width

型別：NxByte

意義：欄位寬度（位元數）。

合法值／哨兵：1～8；整個位元組時填 8。

何時填：同上。

NxRegSemantic::name

型別：const char *

意義：欄位名稱（NUL 結尾的靜態字串）。

合法值／哨兵：靜態儲存期字串，不得為 NULL（本欄位是本筆語意描述存在的理由）。

何時填：同上。

NxRegSemantic::description

型別：const char *

意義：補充說明。

合法值／哨兵：靜態儲存期字串；不需要時填 NULL。

何時填：同上。