元件結構化設定參考資料

本頁提供結構化設定的行為和實作詳細資訊。如需使用結構化設定的指南,請參閱:

生命週期

系統會在建立元件時解析設定值。

解析度優先順序

「元件設定」能根據元件執行個體執行時針對的結構定義調整其行為,這表示最可靠的設定值應該是對元件執行個體結構定義最有知識的編碼值。

元件管理服務會解析每個設定欄位的值,並優先依照以下順序排列各個來源:

  1. 來自開發人員覆寫服務 (WIP) 的值
  2. 來自元件父項的值
  3. 來自元件專屬套件的值

負責工程版本的元件開發人員可以瞭解系統上執行的所有內容,這將覆寫最具公信力的覆寫項目。父項可以瞭解自身提供給子項的背景資訊。最後,由於元件專屬套件中的值只能對元件包裝方式進行編碼,因此所有其他資訊必須從外部來源提供。

產生的用戶端程式庫

元件作者應使用 configc 工具產生的用戶端程式庫來存取設定值。這些程式庫會透過元件執行器提供的 API (例如 ELF 執行元件的程序) 使用已解析的 VMO,確認檢查碼正確無誤,並將剖析的設定值傳回呼叫端。

用戶端程式庫會傳回含有設定的本機非靜態值,讓使用者可選擇以引數形式將值向下傳遞,或明確將設定值明確放在可供全域存取的位置。

由於元件管理員只會在元件具備有效的設定值時啟動元件,因此呼叫端看不見用戶端程式庫,如果無法擷取或剖析設定值,就會導致元件執行個體停止運作。

設定檔值檔案

如果元件解析器會傳回包含 config 結構定義的元件資訊清單,也必須傳回設定檔。

設定值檔案是 fuchsia.component.decl/ConfigValuesData 類型的「保存的 FIDL 訊息」

如果經過編譯的元件資訊清單,這些資訊清單通常會以 meta/*.cm 的形式儲存在套件中,而設定值檔案通常是以 meta/*.cvf 的形式儲存在套件中。

已解決的 VMO

元件管理員從元件解析器和任何執行階段覆寫值組合中解析出元件的設定值後,就會將設定編碼至 VMO,並提供給 fuchsia.component.runner/ComponentStartInfo.encoded_config 中的執行元件。

VMO 的前 2 個位元組應解讀為無正負號的 16 位元小端整數,表示包含設定檢查碼的後續位元組數。使用總和檢查碼後,剩餘的位元組是頂層結構的永久 FIDL 訊息,與產生的用戶端程式庫使用的版面配置相符。結構體的欄位會按照相同順序,與元件編譯資訊清單的設定欄位相符。

檢查碼驗證

為防範意外設定錯誤,防止封裝設定的元件發生意外錯誤,cmc 會在編譯 CML 時計算元件的 config 結構定義雜湊,並在編譯的資訊清單 (*.cm) 中將該雜湊用於總和檢查碼。設定值檔案產生的用戶端程式庫已解析的 VMO 中也包含這個總和檢查碼。

在建構和元件建立期間,系統會驗證已編譯資訊清單的檢查碼,確保與設定值檔案中的總和檢查碼相符。接著,元件管理員會在啟動元件時,將總和檢查碼放在已解析的 VMO 中。產生的用戶端程式庫在剖析實際設定值之前,會在執行階段檢查已解析的 VMO 中的值是否相符。