callback 的建立與觸發#

• 使用 event_register_group_callback() 檢視設備樹表(Device Tree Table)的變更¹；

...
// main.c
status = event_register_group_callback(&EfiDtbTableGuid, &event, efi_dtb_changed);
if (EFI_ERROR(status)) return status;
return efi_dtb_changed();   // 立即執行一次

• 當 Bootloader 載入設備樹後，呼叫 efi_dtb_changed()，將這一變數傳遞給 dtb_enumerate_rprocs(dtb) 來解析裝置的設備樹，並處理 DTB 中標記爲「正常(status = "okay")」的遠端處理器。檢視設備樹中遠端處理器的 compatible 字串內容，匹配預先定義的 pil_type。爲了避免核心執行不穩定，qebspil 只會載入有 qcom,broken-reset 屬性的遠端處理器²；

...
status = dtb_enumerate_rprocs(dtb);
   if (status == EFI_NOT_FOUND)
   	return EFI_SUCCESS; /* No remoteprocs found */
   if (EFI_ERROR(status))
   	return status;
   ...

• 同時，在 efi_dtb_changed() 內部會註冊一個 Late EBS（ExitBootServices）事件 efi_late_ebs。這是 qebspil 的精妙之處，它使用 EDK2 的內部機制讓該 callback 在極晚的 TPL 級別執行，確保在 UEFI 轉交控制權給 Linux 核心的最後一刻，才真正執行 pil_finish_all() 來啟動遠端處理器。

// event.c + main.c
if (!ebs_event) {
   status = event_register_late_ebs_callback(&ebs_event, efi_late_ebs);
   // 使用 EDK2 內部 hack 將 TPL 調低，讓 callback 盡量晚執行
}

DTB 解析與 PIL 管理#

• 在 dtb_enumerate_rprocs() 中遍歷所有 remoteproc* 節點;
• 匹配 pil_type（包含 compatible、PAS ID、proxy GUID 等）;
• 支援多組件（DTB 擴充段 + 主要韌體），並限制全域最多可管理的遠端處理器裝置數量（目前 4 個）³;
• 從 DTB 取得 memory-region、firmware-name 等屬性。

// dtb.c 片段
ret = lkfdt_u32list_get(ctx->dtb, node, "memory-region", idx, &mem_phandle);
if (ret) return EFI_INVALID_PARAMETER;
// ... 取得 reserved-memory 資訊

fw_name = fdt_stringlist_get(ctx->dtb, node, "firmware-name", idx, NULL);
if (!fw_name) return EFI_INVALID_PARAMETER;
    ...

/* 枚舉裝置的遠端處理器 */

static EFI_STATUS dtb_enumerate_rproc(struct dtb_context *ctx, int node, struct pil *pil)
{
    for (enum pil_component c = 0; c < PIL_COMPONENTS; c++) {
        /* DTB 在 DTB 中排在後面，但在 enum 中排在前面 */
        int idx = PIL_COMPONENTS - c - 1;
        if (!pil_has_component(pil, c)) continue;
        status = dtb_load_pil_data(ctx, node, &pil->fw[c], idx);
        ...
    }
}

...

while ((node = fdt_next_node(dtb, node, NULL)) >= 0) {
    ...
    if (!name || strncmp(name, "remoteproc", sizeof("remoteproc") - 1))
        continue;
    if (!lkfdt_node_is_available(dtb, node))
        continue;
    if (!QEBSPIL_ALWAYS_START && !fdt_getprop(dtb, node, "qcom,broken-reset", NULL))
        continue;   // 預設只啟動標記 qcom,broken-reset 的 remoteproc
    ...
}

韌體載入與準備#

• 從 ESP 分割的 /firmware/ 目錄讀取韌體(根據 DTB 中 firmware-name 定義的韌體路徑和韌體名稱而定)；
• 載入 ELF 韌體(*_dtbs.elf)，利用 ELF 函式庫(elf.h)驗証 ELF header，Program headers，PT_LOAD 引數之類；
• 準備 metadata（從 ELF 的 PT_NULL segments 提取，用於 PAS 驗證）⁴；

...
EFI_STATUS fw_load_metadata(struct pil_fw *fw)
{
   const Elf32_Ehdr *ehdr = fw->elf_data;
   const Elf32_Phdr *phdr = fw->elf_data + ehdr->e_phoff;
   VOID *metadata = (VOID*)fw->metadata;
   UINT64 pos = 0;

   for (Elf32_Half i = 0; i < ehdr->e_phnum; i++, phdr++) {
   	if (phdr->p_type != PT_NULL || phdr->p_filesz == 0)     // 複製到預分配的 metadata 記憶體
   		continue;
   	if ((pos + phdr->p_filesz) > MAX_METADATA_SIZE)
   		return EFI_BUFFER_TOO_SMALL;

   	CopyMem(metadata + pos, fw->elf_data + phdr->p_offset, phdr->p_filesz);
   	pos += phdr->p_filesz;
   }

   if (pos == 0)
   	return EFI_NOT_FOUND;

   WriteBackInvalidateDataCacheRange(metadata, MAX_METADATA_SIZE);		// 透過 WriteBackInvalidateDataCacheRange() 確保資料完整寫入實體 RAM。
   return EFI_SUCCESS;
}
...

• fw_prepare()：分配 metadata 頁面與載入 ELF 資料。
• fw_load()：將 PT_LOAD segments 複製到目標記憶體位址，並處理 cache 維護。

與 TZ/SCM 互動#

• 在準備好韌體與記憶體後，透過 Qualcomm SCM（Secure Channel Manager）通訊協定（QCOM_SCM_PROTOCOL）向 TrustZone 核心發起安全系統呼叫（Syscall）⁵:

1. scm_pil_init()：初始化 PIL（Peripheral Image Loader），傳 PAS ID + metadata;

/* pil.c */
status = scm_pil_init(pil->type->id[c].full, fw->metadata);
   	if (EFI_ERROR(status)) {
   		Print(u"qebspil: Failed to init firmware for %a%a: %r (wrong firmware?)\n",
   		      pil->type->compatible, pil_component_names[c], status);
   		return status;
   	}

/* scm.c */        
EFI_STATUS scm_pil_init(UINT8 pas_id, EFI_PHYSICAL_ADDRESS metadata)
{
   UINT64 Parameters[SCM_MAX_NUM_PARAMETERS] = {
   	pas_id,
   	metadata,
   };
   UINT64 Results[SCM_MAX_NUM_RESULTS];

   return scm->ScmSipSysCall(scm, TZ_PIL_INIT_ID, TZ_PIL_INIT_ID_PARAM_ID, Parameters, Results);
}

2. scm_pil_mem_setup()：鎖定並設定該遠端處理器的專屬安全記憶體區域，限制非安全環境的非法存取;

/*scm.c*/
EFI_STATUS scm_pil_mem_setup(UINT8 pas_id, EFI_PHYSICAL_ADDRESS addr, UINTN size)
{
   UINT64 Parameters[SCM_MAX_NUM_PARAMETERS] = {
   	pas_id,     /* 指定 PAS ID，大小和在記憶體的地址 */
   	addr,
   	size,
   };
   UINT64 Results[SCM_MAX_NUM_RESULTS];

   return scm->ScmSipSysCall(scm, TZ_PIL_MEM_ID, TZ_PIL_MEM_ID_PARAM_ID, Parameters, Results);
}

/*pil.c*/
status = scm_pil_mem_setup(pil->type->id[c].full, fw->mem_addr, fw->mem_size);
   	if (EFI_ERROR(status)) {
   		Print(u"qebspil: Failed to setup memory area for %a%a: %r\n",
   		      pil->type->compatible, pil_component_names[c], status);
   		return status;
   	}
   }

3. scm_pil_start()：驗證並用完整韌體(full firmware)再啓動遠端處理器（TZ_PIL_AUTH_RESET_ID），如果因爲韌體或 DTB 原因無法完成啟動，程式會執行狀態回溯 (Rollback)：關閉剛才已成功載入的部分完整版韌體元件，避免系統處於載入一半的異常狀態（注意：此時並不會重新啟動精簡版韌體，遠端處理器將保持停止狀態）。

/*scm.c*/
EFI_STATUS scm_pil_start(UINT8 pas_id)
{
	UINT64 Parameters[SCM_MAX_NUM_PARAMETERS] = {
		pas_id,
	};
	UINT64 Results[SCM_MAX_NUM_RESULTS];

	return scm->ScmSipSysCall(scm, TZ_PIL_AUTH_RESET_ID, TZ_PIL_AUTH_RESET_ID_PARAM_ID, Parameters, Results);
}

/* pil.c */

/* Stop lite firmware in reverse order (full first, then DTB) */
	for (enum pil_component b = PIL_COMPONENTS; b > 0; b--) {
		if (!pil_has_component(pil, b - 1) || !pil->type->id[b - 1].lite)
			continue;

		/* Ignore return status since we don't know if lite was running */
		scm_pil_stop(pil->type->id[b - 1].lite);    // 因爲無法事先了解遠端處理器是否執行精簡版韌體，因此忽略返回的狀態變數
	}

	/* 錯誤處理 */

	for (enum pil_component c = 0; c < PIL_COMPONENTS; c++) {
		if (!pil_has_component(pil, c))
			continue;

		status = scm_pil_start(pil->type->id[c].full);
		if (EFI_ERROR(status)) {
			Print(u"qebspil: Failed to authenticate and start firmware for %a%a: %r\n",  /* 錯誤信息 */
			      pil->type->compatible, pil_component_names[c], status);

			/* Rollback：僅停止已成功啟動的 full firmware 元件 */
			for (enum pil_component b = c; b > 0; b--)
				if (pil_has_component(pil, b - 1))
					scm_pil_stop(pil->type->id[b - 1].full);

			return status;
		}
	}

• 使用 Proxy Vote Protocol（PIL_PROXY_PROTOCOL）進行資源投票，強迫啟動相關的 Power Domain（電源域）與時脈，確保硬體周邊處於可用狀態（在 pil_prepare() 階段執行）。啟動前會先嘗試停止精簡版韌體(lite firmware)（若存在），但失敗時不會自動回退到 lite 版本，而是保持停止狀態並 rollback full firmware，避免半載狀態。

與 Linux 配合#

qebspil 加載後，需要修補 Linux 核心的 qcom_q6v5_pas.c remoteproc 原始碼來添加遠端處理器 late attach / takeover 支援，修補後的 Linux 核心會自動接管預先啓動的遠端處理器。