ci(hal): Add HAL/LL-based test app for the TEE and APM peripherals

Author: laukik-hase

.gitlab/CODEOWNERS

@@ -125,6 +125,7 @@
 /components/freertos/                 @esp-idf-codeowners/system
 /components/hal/                      @esp-idf-codeowners/peripherals
 /components/hal/test_apps/crypto/     @esp-idf-codeowners/peripherals @esp-idf-codeowners/security
+/components/hal/test_apps/tee_apm/    @esp-idf-codeowners/peripherals @esp-idf-codeowners/security
 /components/heap/                     @esp-idf-codeowners/system
 /components/http_parser/              @esp-idf-codeowners/app-utilities
 /components/idf_test/                 @esp-idf-codeowners/peripherals @esp-idf-codeowners/system

components/esp_hw_support/port/esp32c5/cpu_region_protect.c

@@ -136,6 +136,7 @@ void esp_cpu_configure_region_protection(void)
     _Static_assert(SOC_CPU_SUBSYSTEM_LOW < SOC_CPU_SUBSYSTEM_HIGH, "Invalid CPU subsystem region");
 
     // 2. I/D-ROM
+#if CONFIG_ESP_SYSTEM_PMP_IDRAM_SPLIT && !BOOTLOADER_BUILD
     const uint32_t drom_start = (uint32_t) (ets_rom_layout_p->drom_start);
     if ((drom_start & (SOC_CPU_PMP_REGION_GRANULARITY - 1)) == 0) {
         // We can skip configuring the PMP entry for the [SOC_IROM_MASK_LOW - drom_start]
@@ -144,9 +145,11 @@ void esp_cpu_configure_region_protection(void)
         // the region as cacheable. Thus, we save on one PMP entry.
         PMP_ENTRY_SET(1, drom_start, NONE);
         PMP_ENTRY_SET(2, SOC_DROM_MASK_HIGH, PMP_TOR | R);
-    } else {
+    } else
+#endif
+    {
         PMP_ENTRY_SET(1, SOC_IROM_MASK_LOW, NONE);
-        PMP_ENTRY_SET(2, SOC_IROM_MASK_HIGH, PMP_TOR | RX);
+        PMP_ENTRY_SET(2, SOC_IROM_MASK_HIGH, PMP_TOR | CONDITIONAL_RX);
         _Static_assert(SOC_IROM_MASK_LOW < SOC_IROM_MASK_HIGH, "Invalid I/D-ROM region");
     }
 

components/esp_hw_support/port/esp32c61/cpu_region_protect.c

@@ -133,14 +133,17 @@ void esp_cpu_configure_region_protection(void)
     _Static_assert(SOC_CPU_SUBSYSTEM_LOW < SOC_CPU_SUBSYSTEM_HIGH, "Invalid CPU subsystem region");
 
     // 2. I/D-ROM
+#if CONFIG_ESP_SYSTEM_PMP_IDRAM_SPLIT && !BOOTLOADER_BUILD
     const uint32_t drom_start = (uint32_t) (ets_rom_layout_p->drom_start);
     if ((drom_start & (SOC_CPU_PMP_REGION_GRANULARITY - 1)) == 0) {
         PMP_ENTRY_SET(1, SOC_IROM_MASK_LOW, NONE);
         PMP_ENTRY_SET(2, drom_start, PMP_TOR | RX);
         PMP_ENTRY_SET(3, SOC_DROM_MASK_HIGH, PMP_TOR | RW);
-    } else {
+    } else
+#endif
+    {
         const uint32_t pmpaddr1 = PMPADDR_NAPOT(SOC_IROM_MASK_LOW, SOC_IROM_MASK_HIGH);
-        PMP_ENTRY_SET(1, pmpaddr1, PMP_NAPOT | RX);
+        PMP_ENTRY_SET(1, pmpaddr1, PMP_NAPOT | CONDITIONAL_RX);
         _Static_assert(SOC_IROM_MASK_LOW < SOC_IROM_MASK_HIGH, "Invalid I/D-ROM region");
     }
 

components/hal/.build-test-rules.yml

@@ -11,3 +11,7 @@ components/hal/test_apps/hal_i2c:
 components/hal/test_apps/hal_utils:
   enable:
     - if: IDF_TARGET == "linux"
+
+components/hal/test_apps/tee_apm:
+  disable:
+    - if: IDF_TARGET not in ["esp32c6", "esp32h2", "esp32c5", "esp32c61"]

components/hal/apm_hal.c

@@ -268,6 +268,8 @@ void apm_hal_set_region_end_addr(apm_ctrl_module_t ctrl_mod, uint32_t regn_num,
 
 void apm_hal_set_sec_mode_region_attr(apm_ctrl_module_t ctrl_mod, uint32_t regn_num, apm_security_mode_t mode, uint32_t regn_pms)
 {
+    HAL_ASSERT(mode != APM_SEC_MODE_TEE);
+
     switch (ctrl_mod) {
         case APM_CTRL_HP_APM:
             apm_ll_hp_apm_set_sec_mode_region_attr(regn_num, mode, regn_pms);

components/hal/test_apps/tee_apm/CMakeLists.txt

@@ -0,0 +1,15 @@
+#This is the project CMakeLists.txt file for the test subproject
+cmake_minimum_required(VERSION 3.16)
+
+# "Trim" the build. Include the minimal set of components, main, and anything it depends on.
+set(COMPONENTS main)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+
+project(test_tee_apm)
+
+include($ENV{IDF_PATH}/tools/ci/check_register_rw_half_word.cmake)
+message(STATUS "Checking tee/apm registers are not read-write by half-word")
+check_register_rw_half_word(SOC_MODULES "*tee"       # tee, lp_tee
+                                        "*apm *apm0" # hp_apm, lp_apm, cpu_apm, lp_apm0
+                            HAL_MODULES "apm")

components/hal/test_apps/tee_apm/README.md

@@ -0,0 +1,149 @@
+| Supported Targets | ESP32-C5 | ESP32-C6 | ESP32-C61 | ESP32-H2 |
+| ----------------- | -------- | -------- | --------- | -------- |
+
+# APM (Access Permission Management) Peripheral Test App
+
+This application validates region-based memory and peripheral access control via the APM (Access Permission Management) subsystem. It is primarily intended for bring-up and SoC-level functional testing.
+
+Tests exercise various master-to-region accesses under different security modes (`TEE`, `REE0`, `REE1`, `REE2`). Outcomes are validated against expected APM behavior and known SoC-specific quirks.
+
+---
+
+## Test Coverage
+
+### TEE mode default access behavior
+
+- **TEE Mode Default Access**
+
+Validates whether TEE mode has unrestricted access to regions not covered by APM entries. Confirms filtering issues on ESP32-C6 and ESP32-H2.
+
+### HP_CPU Access
+
+- **HP_CPU → CPU_PERI**
+- **HP_CPU → HP_PERI**
+- **HP_CPU → LP_PERI**
+- **HP_CPU → HP_MEM** (if `SOC_APM_CPU_APM_SUPPORTED`)
+- **HP_CPU → LP_MEM** (if `SOC_RTC_MEM_SUPPORTED`)
+
+Each scenario checks access permission enforcement for read-only and write-only settings across security modes.
+
+### GDMA Access
+
+- **GDMA → HP_MEM**
+- **GDMA → EXT_MEM** (if `CONFIG_SPIRAM`)
+
+Validates region-based restrictions across modes using DMA transfers.
+
+### LP_CPU Access (if `CONFIG_ULP_COPROC_ENABLED`)
+
+- **LP_CPU → LP_PERI**
+- **LP_CPU → LP_MEM**
+- **LP_CPU → HP_MEM**
+
+### PERI_APM Tests (if `SOC_APM_SUPPORT_TEE_PERI_ACCESS_CTRL`)
+
+- **HP_CPU → HP_PERI**
+- **HP_CPU → LP_PERI**
+- **LP_CPU → HP_PERI**
+- **LP_CPU → LP_PERI**
+
+Validates the per-peripheral access permissions for all security modes.
+
+---
+
+## Target Extension Guide
+
+To add support for a new SoC target, create a test configuration header at:
+
+```
+components/pms/priv_include/<target>/test_pms_params.h
+```
+
+This header must define:
+
+### 1. GDMA APM Master ID
+
+Defined based on GDMA version:
+
+```c
+#define TEST_GDMA_APM_MASTER_ID APM_MASTER_GDMA_GPSPI  // For SOC_AHB_GDMA_VERSION == 1
+```
+
+- `SOC_AHB_GDMA_VERSION == 1` → `GPSPI`
+- `SOC_AHB_GDMA_VERSION == 2` → `26` (e.g., `GDMA_DUMMY10`)
+
+Refer to `hal/apm_types.h` or the SoC TRM.
+
+### 2. APM Controller and Path Definitions
+
+Specify APM controller and access path for each initiator-target pair:
+
+```c
+#define HP_CPU_CPUPERI_APM_CTRL APM_CTRL_HP_APM
+#define HP_CPU_CPUPERI_APM_PATH APM_CTRL_ACCESS_PATH_M0
+#define TEST_HP_CPU_CPUPERI_REGN_NUM 4
+```
+
+Use the TRM to determine path-controller mappings.
+
+### 3. Peripheral Test Region Definitions
+
+Split the peripheral address space into testable regions:
+
+- Use `soc/reg_base.h` to get base addresses of peripherals.
+- Align non-contiguous region boundaries to 4 KB using:
+
+```c
+#define ALIGN_TO_NEXT_4KB(addr) (((addr) + 0x1000) & ~0xFFF)
+```
+
+#### CPU_PERI
+
+- Typically monitored by `HP_APM`.
+- Includes blocks like `TRACE`, `ASSIST_DEBUG`, `INTPRI`, `CACHE`.
+- `CPU_PERI` typically includes ~4 peripherals, and thus, 4 APM regions are sufficient for test coverage.
+
+#### LP_PERI
+
+- Monitored by `LP_APM`.
+- Covers domains like `PMU`, `LP_IO`, `LP_AON`.
+- For SoCs with `LP_CPU`, reserve the regions containing `PMU`, `LP_AON`, `LP_PERI`. These are reserved to allow test-case control and avoid undesired APM violations.
+
+```c
+#define TEST_LP_PERI_RESV_MASK BIT(0) | BIT(2) | BIT(6)
+```
+
+#### HP_PERI
+
+- Monitored by `HP_APM`.
+- Split into: `HP_PERI0`, `HP_PERI1`, and `HP_PERI2`.
+  Test APM regions should be proportionally allocated to these segments based on address space size.
+- Reserve the region containing `UART0`, since it is often used by the log console.
+- If `PERI_APM` is supported, reserve the regions with `TEE`, `LP_TEE`, `HP_APM`, `LP_APM`, `LP_APM0`, and `CPU_APM`, as these are inaccessible to the REE modes.
+
+```c
+#define TEST_HP_PERI_RESV_MASK BIT(0)
+```
+
+---
+
+## Building
+
+```bash
+idf.py set-target <TARGET>
+idf.py build
+```
+
+## Running the App
+
+```bash
+idf.py flash monitor
+```
+
+## Running Tests
+
+```bash
+pytest --target <TARGET>
+```
+
+---

components/hal/test_apps/tee_apm/components/pms/CMakeLists.txt

@@ -0,0 +1,25 @@
+cmake_minimum_required(VERSION 3.16)
+idf_build_get_property(target IDF_TARGET)
+
+set(srcs "src/test_tee_vectors.S"
+         "src/test_panic_handler.c"
+         "src/test_intr_utils.c"
+         "src/test_apm_utils.c"
+         "src/test_setup_utils.c"
+         "src/test_tee_sys_apm.c")
+if(CONFIG_SOC_APM_SUPPORT_TEE_PERI_ACCESS_CTRL)
+    list(APPEND srcs "src/test_tee_peri_apm.c")
+endif()
+
+idf_component_register(SRCS "${srcs}"
+                       INCLUDE_DIRS "include" "priv_include"
+                       PRIV_INCLUDE_DIRS "priv_include/${target}"
+                       REQUIRES ulp unity
+                       LDFRAGMENTS linker.lf)
+
+if(CONFIG_ULP_COPROC_ENABLED)
+    set(ulp_app_name ulp_lp_core_${COMPONENT_NAME})
+    set(ulp_rv_srcs "src/ulp/ulp_lp_core_main.c" "src/ulp/ulp_vectors.S")
+    set(ulp_exp_dep_srcs "src/test_tee_apm_pms.c")
+    ulp_embed_binary(${ulp_app_name} "${ulp_rv_srcs}" "${ulp_exp_dep_srcs}")
+endif()

components/hal/test_apps/tee_apm/components/pms/include/test_pms.h

@@ -0,0 +1,36 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/* Test-cases */
+void test_sys_apm_master_hp_cpu_slave_hp_peri(void);
+
+void test_sys_apm_master_hp_cpu_slave_cpu_peri(void);
+
+void test_sys_apm_master_gdma_slave_hpmem(void);
+
+void test_sys_apm_master_hp_cpu_slave_lpmem(void);
+
+void test_sys_apm_master_lp_cpu_slave_lp_peri(void);
+
+void test_sys_apm_master_hp_cpu_slave_lp_peri(void);
+
+void test_sys_apm_master_lp_cpu_slave_lpmem(void);
+
+void test_sys_apm_master_lp_cpu_slave_hpmem(void);
+
+void test_sys_apm_master_gdma_slave_extmem(void);
+
+void test_sys_apm_master_hp_cpu_slave_hpmem(void);
+
+void test_peri_apm_master_hp_cpu_slave_hp_peri(void);
+
+void test_peri_apm_master_hp_cpu_slave_lp_peri(void);
+
+void test_peri_apm_master_lp_cpu_slave_hp_peri(void);
+
+void test_peri_apm_master_lp_cpu_slave_lp_peri(void);
+
+void test_tee_mode_default_access(void);

components/hal/test_apps/tee_apm/components/pms/linker.lf

@@ -0,0 +1,5 @@
+[mapping:pms]
+archive: libpms.a
+entries:
+    test_intr_utils (noflash)
+    test_panic_handler (noflash)