idf

# ESP-BIST IDF Sample

This sample demonstrates running ESP-BIST tests on the LP core (ULP coprocessor) within an ESP-IDF application, plus **Host Diagnostics**: the LP companion supervises a QM host OS agent on the HP core.

HP and LP cores communicate over the LP mailbox (`lp_core_mailbox_*`). On ESP32-C5/C6 this uses the software mailbox (shared memory + PMU interrupt). The HP agent sends `AGENT_READY`; the LP companion replies with post-boot and periodic runtime `LP_STATUS` bitmasks and (when enabled) Q&A `CHALLENGE` / `ANSWER` frames. Companion owns safe-state decisions (on failure it stops feeding the LP WDT).

This is deliberately the happy path only, so it works as a starting point for your own application. Fail-closed validation lives in [`tests/integration/hd_idf`](../../tests/integration/hd_idf).

## Supported SoCs

- ESP32-C5
- ESP32-C6
- ESP32-P4

## Prerequisites

- ESP-IDF v6.2 (`release/v6.2`)

The ULP sub-project uses ESP-IDF v6.2's native `LINKER_LAYOUT` parameter in `ulp_add_project()` (`${ESP_BIST_LP_LINKER_LAYOUT}`, resolved by `project_include.cmake` to `src/soc/<target>/ld/idf.ld`) to place the BIST safe-stack and mailbox state below `_bist_ram_test_start`. No patch to ESP-IDF is required.

## Using from the ESP Component Registry

To create a standalone project from this example via the ESP Component Registry:

```sh
. $IDF_PATH/export.sh
idf.py create-project-from-example "espressif/esp-bist==2.0.0-rc.1:idf"
cd idf
idf.py set-target <target_soc>
idf.py build
```

Or to add `espressif/esp-bist` to an existing ESP-IDF project:

```sh
idf.py add-dependency "espressif/esp-bist==2.0.0-rc.1"
```

## Build (In-Tree)

```sh
. $IDF_PATH/export.sh
cd samples/idf
idf.py set-target <target_soc>
idf.py build
```

## Flash and Monitor

```sh
idf.py -p PORT flash monitor
```

On success, the LP core runs the enabled BIST tests in a loop and prints results over LP UART.

## Configuration

```sh
idf.py menuconfig
```

Relevant options:

- **Component config > Ultra Low Power (ULP) Co-processor** — LP core enable and reserved memory size.
- **Component config > ESP-BIST** — enable individual BIST tests.
- **Component config > ESP-BIST > Host Diagnostics** — agent/companion, equal-rank audit options, and the challenge window and key.

## Validating fail-closed behaviour

Making the host misbehave — answering with the wrong key, or missing the
challenge window — belongs to
[`tests/integration/hd_idf`](../../tests/integration/hd_idf). Keeping it out of
here means a fail-closed build and a product build differ only in that test app;
nothing in `src/bist/` or in this sample has a test branch.

## BIST Tests Available on LP Core

| Test | Kconfig option |
|------|----------------|
| CPU registers | `CONFIG_ESP_BIST_CPU_REG_TEST` |
| CPU CSRs | `CONFIG_ESP_BIST_CPU_CSR_REG_TEST` |
| RAM (March A/X / Abraham) | `CONFIG_ESP_BIST_MEMORY_RAM_TEST` |
| Stack overflow | `CONFIG_ESP_BIST_STACK_TEST` |
| Flash CRC | `CONFIG_ESP_BIST_MEMORY_FLASH_TEST` |
| LP watchdog | `CONFIG_ESP_BIST_WDT_TIMEOUT_US` |

### RAM test notes

- **Post-boot:** March-X followed by `bist_ram_test_abraham_full()` (complete pair schedule).
- **Runtime:** March-A followed by `bist_ram_test_abraham()` (one partition pair per round).
- LP builds default `CONFIG_ESP_BIST_RAM_PARTITION_SIZE` to **64 words** in this sample to fit LP SRAM with Host Diagnostics.