tan-cli 0.7.0__py3-none-any.whl

tan/templates/vendored/iot/E1M-AEN801/testcase.yaml

@@ -0,0 +1,68 @@
+# SPDX-License-Identifier: Apache-2.0
+
+sample:
+  name: mqtt-telemetry
+  description: |
+    Publish a sensor reading over MQTT/TLS via the portable
+    <alp/iot.h> Wi-Fi + MQTT surface.  AEN-only: the transport is
+    the CC3501E Wi-Fi6+BLE bridge on the E1M-AEN801.  On native_sim
+    there is no radio, so alp_wifi_open()/alp_mqtt_open() return
+    NULL (NOT_READY) and the app prints the telemetry framing it
+    would publish, then exits on the done marker.
+
+tests:
+  alp_sdk.example.mqtt_telemetry.native_sim:
+    extra_args: EXTRA_CONF_FILE=generated/alp.conf
+    platform_allow:
+      - native_sim
+      - native_sim/native/64
+    integration_platforms:
+      - native_sim/native/64
+    tags:
+      - alp-sdk
+      - example
+      - iot
+      - mqtt
+      - aen
+    harness: console
+    harness_config:
+        type: one_line
+        regex:
+          - "\\[mqtt\\] done"
+    # No native_sim.conf any more: it existed only to turn mbedtls off
+    # around the ssl_misc.h break, which is fixed at its root (#2173), so
+    # this scenario now builds the same TLS-enabled config the SoM does.
+    # native_sim's only entropy driver is FAKE_ENTROPY_NATIVE_SIM, whose own
+    # Kconfig help says it "does not generate real entropy", so the weak-RNG
+    # refusal in zephyr/CMakeLists.txt applies here too (#2192). A simulator
+    # run is exactly what the opt-in exists for. It lives on the SCENARIO,
+    # not in the app's prj.conf, so a copy scaffolded by `tan init
+    # --from-example` and built for real hardware still refuses.
+    extra_configs:
+      - CONFIG_ALP_SDK_ALLOW_TEST_ENTROPY=y
+
+  # Issue #2173: the AEN build had no scenario at all, so the one target
+  # this app is actually written for -- the CC3501E bridge on an
+  # E1M-AEN801 -- was never compiled in CI, and it had stopped compiling
+  # (the mbedtls PSA floor, fixed in zephyr/Kconfig.alp-libraries).
+  # build_only: there is no radio on a CI runner, so this asserts the
+  # image links for the SoM its board.yaml names, nothing more.
+  alp_sdk.example.mqtt_telemetry.aen:
+    extra_args: EXTRA_CONF_FILE=generated/alp.conf
+    platform_allow:
+      - alp_e1m_aen801_m55_hp/ae822fa0e5597ls0/rtss_hp
+      - alp_e1m_aen803_m55_hp/ae822fa0e5597ls0/rtss_hp
+    tags:
+      - alp-sdk
+      - example
+      - iot
+      - mqtt
+      - aen
+    build_only: true
+    # No weak-RNG opt-in: every AEN board seeds its CSPRNG from the Secure
+    # Enclave TRNG by default (#2192), so this configures on real entropy.
+    harness: console
+    harness_config:
+        type: one_line
+        regex:
+          - "\\[mqtt\\] done"

tan/templates/vendored/minimal/E1M-AEN801/CMakeLists.txt

@@ -0,0 +1,8 @@
+# SPDX-License-Identifier: Apache-2.0
+
+cmake_minimum_required(VERSION 3.20)
+
+find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
+project(hello_world LANGUAGES C)
+
+target_sources(app PRIVATE src/main.c)

tan/templates/vendored/minimal/E1M-AEN801/README.md

@@ -0,0 +1,108 @@
+# hello-world
+
+The canonical "first program" for the Alp SDK.  No peripherals,
+no chips, no board-specific wiring -- just a periodic `printf`
+loop so you can confirm the toolchain, flash flow, and log
+console are wired correctly before chasing harder bugs.
+
+If `[hello] tick 0` doesn't appear, the suspect list is short:
+
+1.  **Toolchain** -- the build output completes cleanly but the
+    image you flashed doesn't match the SoM (cross-compiled for
+    the wrong core; mismatched Zephyr board target).
+2.  **Flash flow** -- the image flashed but boot vector / SAU /
+    secure-state config doesn't allow it to start.
+3.  **Console wiring** -- the app is running but your terminal is
+    on the wrong UART, wrong baud rate, or wrong USB enumeration.
+
+Pin down which one BEFORE moving on to alp-sdk's
+[`examples/peripheral-io/gpio-button-led`](https://github.com/alplabai/alp-sdk/tree/v0.17.0/examples/peripheral-io/gpio-button-led)
+or
+[`examples/peripheral-io/i2c-scanner`](https://github.com/alplabai/alp-sdk/tree/v0.17.0/examples/peripheral-io/i2c-scanner)
+-- neither is part of this scaffolded project.
+
+## What this shows
+
+* The minimal `board.yaml` v2 shape: `schema_version`, `som.sku`,
+  `board.name`, one `cores.<id>` with an empty `peripherals: []`.
+* That `prj.conf` stays empty -- all CONFIG_* selection comes from
+  the loader-generated `alp.conf`.
+* The Zephyr boot -> `main()` -> printf path with no peripheral
+  initialisation in between.
+
+## Build
+
+```bash
+# Standalone, native_sim (host binary; no hardware needed):
+# writes ./generated/alp.conf, which west reads below (#866)
+tan generate --target zephyr-conf --core m55_hp --sdk-root "$ALP_SDK_ROOT" --output generated/alp.conf
+west build -b native_sim/native/64 . \
+    -- -DEXTRA_CONF_FILE=generated/alp.conf -DEXTRA_ZEPHYR_MODULES=$ALP_SDK_ROOT
+west build -t run
+
+# On real silicon, point -b at the SoM's Zephyr board target.
+# Example for E1M-AEN801:
+west build -b alp_e1m_aen801_m55_hp/ae822fa0e5597ls0/rtss_hp . -- -DEXTRA_CONF_FILE=generated/alp.conf
+west flash
+```
+
+## Where the output lands
+
+| SoM family   | Console route                                            |
+|--------------|----------------------------------------------------------|
+| E1M-AEN      | Alif first USART -> FTDI USB-UART on E1M-EVK (115200 8N1) |
+| E1M-V2N      | Renesas SCIF -> FTDI USB-UART on E1M-X-EVK (115200 8N1)   |
+| E1M-V2N-M1   | Same as V2N                                              |
+| native_sim   | Host binary stdout                                       |
+
+Open the serial port in your terminal of choice (115200 8N1).
+The recommended cross-platform tool is `tio` -- one binary, one
+syntax on Linux, macOS, and Windows:
+
+```
+tio -b 115200 <your-serial-device>
+```
+
+Per-OS device naming (and the alternative terminals each OS
+prefers) is documented in
+[`docs/cross-platform-setup.md`](https://github.com/alplabai/alp-sdk/blob/v0.17.0/docs/cross-platform-setup.md)
+section 7.7.
+
+<!-- cross-platform-lint:ignore -->
+Quick reference: Linux uses `/dev/ttyUSB*` or `/dev/ttyACM*`;
+macOS uses `/dev/cu.usbserial-*` or `/dev/cu.usbmodem*`; Windows
+uses `COM<N>` (visible in Device Manager under "Ports (COM &
+LPT)").
+<!-- cross-platform-lint:resume -->
+
+## Expected output
+
+```
+[hello] Alp SDK hello-world starting
+[hello] tick 0
+[hello] tick 1
+[hello] tick 2
+[hello] tick 3
+[hello] tick 4
+[hello] done
+```
+
+## Customising
+
+* **Loop forever.**  Swap the bounded `for` loop in `src/main.c`
+  for the commented-out `TICKS_ON_REAL_SILICON` block.
+* **Faster heartbeat.**  Drop `HELLO_TICK_PERIOD_MS` from `1000`
+  to `100` (10 Hz) or `10` (100 Hz).  At <= 1 ms you'll start to
+  see scheduler overhead.
+* **Different log macro.**  Swap `printf` for `printk` (always
+  ISR-safe) or Zephyr's `LOG_INF` (compile-time-filtered,
+  requires `CONFIG_LOG=y` in `prj.conf`).
+
+## Reference
+
+- [`docs/firmware-quickstart.md`](https://github.com/alplabai/alp-sdk/blob/v0.17.0/docs/firmware-quickstart.md)
+  -- single-OS bring-up walk-through.
+- [`docs/cross-platform-setup.md`](https://github.com/alplabai/alp-sdk/blob/v0.17.0/docs/cross-platform-setup.md)
+  -- Windows/macOS/Linux toolchain + serial-port notes.
+- [`docs/troubleshooting.md`](https://github.com/alplabai/alp-sdk/blob/v0.17.0/docs/troubleshooting.md)
+  -- common boot/flash/console failures + fixes.

tan/templates/vendored/minimal/E1M-AEN801/board.yaml

@@ -0,0 +1,32 @@
+# board.yaml -- per-app project configuration for the
+# hello-world example.
+#
+# The simplest possible Alp SDK app: no peripherals, no chips, no
+# board-specific wiring.  Just the boot path + a periodic printf
+# loop so customers can confirm their toolchain + flash flow + log
+# console are wired correctly before chasing harder bugs.
+#
+# Customer workflow: `tan init --from-example peripheral-io/hello-world`, change `som.sku` to
+# your MPN, edit the `preset:` (or use an inline board) if you're on a non-EVK board,
+# and `tan build`, which plans alp.conf from this file; twister and a bare
+# west build read the pre-generated generated/alp.conf instead
+# (`tan generate --target zephyr-conf`, see README.md).
+som:
+  sku: E1M-AEN801
+
+preset: e1m-evk
+supported_boards:
+  - e1m-evk
+  - e1m-x-evk
+cores:
+  m55_hp:
+    app: ./src
+    # No peripherals -- this example exercises only the boot path
+    # and printf, both of which are part of the Zephyr baseline and
+    # need no explicit Kconfig.  When the loader sees an empty
+    # peripherals: list it still emits the SoC + board configs
+    # the SoM topology requires, so the app boots normally.
+    peripherals: []
+
+diagnostics:
+  log_level: info

tan/templates/vendored/minimal/E1M-AEN801/prj.conf

@@ -0,0 +1,8 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Intentionally empty.  Every CONFIG_* this app needs is derived
+# from board.yaml by `tan build` and layered in via
+# EXTRA_CONF_FILE (see README.md: `tan generate --target zephyr-conf`).  Add app-specific tuning
+# knobs (e.g. CONFIG_HEAP_MEM_POOL_SIZE=N) here only when they
+# are NOT feature-selection -- everything declarative belongs in
+# board.yaml.

tan/templates/vendored/minimal/E1M-AEN801/src/main.c

@@ -0,0 +1,111 @@
+/*
+ * Copyright 2026 Alp Lab AB
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * hello-world -- the canonical "first program" for the Alp SDK.
+ *
+ * No peripherals, no chips, no board-specific wiring.  Just the
+ * boot path + a periodic printf loop so customers can confirm
+ * their toolchain + flash flow + log console are wired correctly
+ * before chasing harder bugs.
+ *
+ * What success looks like:
+ *
+ *   [hello] Alp SDK hello-world starting
+ *   [hello] tick 0
+ *   [hello] tick 1
+ *   ...
+ *   [hello] tick 4
+ *   [hello] done
+ *
+ * Where the output lands depends on the SoM:
+ *
+ *   * E1M-AEN (Alif Ensemble) -- the SoC's first USART, surfaced
+ *     on the EVK board as the FTDI USB-UART (open at 115200 8N1).
+ *   * E1M-V2N / V2N-M1        -- the Renesas SCIF console; same FTDI
+ *     bridge on the E1M-X-EVK at 115200 8N1.
+ *   * native_sim host build   -- stdout of the host binary.
+ *
+ * The SDK doesn't ship its own alp_log API yet (planned post-1.0);
+ * use printf or Zephyr's LOG_* macros directly.  This example uses
+ * printf for clarity -- it lands on whatever Zephyr has picked as
+ * its console (CONFIG_LOG_BACKEND_UART under the hood).
+ */
+
+#include <stdio.h>
+
+#include <alp/cap.h>
+#include <alp/peripheral.h>
+#include <alp/soc_caps.h>
+
+/* Capped tick count keeps the native_sim run inside twister's
+ * timeout.  Real on-silicon firmware would loop forever instead --
+ * see TICKS_ON_REAL_SILICON below.  We expose the cap as a macro
+ * so customers see exactly what to change. */
+#define HELLO_TICKS 5u
+
+/* The wait between ticks.  alp_delay_ms yields the CPU to other
+ * threads + the power-management subsystem during the wait on
+ * scheduler-backed targets; on baremetal it falls through to a
+ * calibrated busy-loop (there's no scheduler to yield to). */
+#define HELLO_TICK_PERIOD_MS 1000u
+
+int main(void)
+{
+	/* Bring up the SDK runtime before anything else -- thin today,
+	 * but future backends rely on it (see <alp/peripheral.h>). */
+	(void)alp_init();
+
+	/* The first line a bring-up engineer wants to see -- it
+     * confirms the boot path made it to main() AND the printf
+     * console is decoded correctly.  If THIS line is missing,
+     * the toolchain / flash flow / console-cable is the suspect,
+     * not the SDK. */
+	printf("[hello] Alp SDK hello-world starting\n");
+
+	/* Periodic loop -- prints a monotonically-increasing tick every
+     * HELLO_TICK_PERIOD_MS so the customer can see the app is alive
+     * (not just printed once + crashed).  Capped at HELLO_TICKS so
+     * twister's console-harness one_line regex can latch the `done`
+     * marker; real firmware would loop forever. */
+	for (uint32_t tick = 0; tick < HELLO_TICKS; tick++) {
+		printf("[hello] tick %u\n", tick);
+		alp_delay_ms(HELLO_TICK_PERIOD_MS);
+	}
+
+	/* TICKS_ON_REAL_SILICON: in production firmware you'd swap the
+     * bounded for-loop above for:
+     *
+     *     for (uint32_t tick = 0; ; tick++) {
+     *         printf("[hello] tick %u\n", tick);
+     *         alp_delay_ms(HELLO_TICK_PERIOD_MS);
+     *     }
+     *
+     * Returning from main() on Zephyr is technically legal but the
+     * kernel idles afterwards -- nothing keeps the heartbeat going. */
+
+	/* Capability-API teaching block.
+     *
+     * `ALP_HAS()` is a compile-time constant expression.  Use it for
+     * #if / static_assert -- the unused branch disappears entirely
+     * from the binary, so this is zero-cost on parts that lack the
+     * feature. */
+#if ALP_HAS(HELIUM_MVE)
+	printf("[hello] this build targets a Helium-capable SoC\n");
+#else
+	printf("[hello] no Helium MVE on this SoC -- scalar path\n");
+#endif
+
+	/* `alp_has()` is the runtime equivalent.  Useful when the same
+     * binary may run on different SoCs (rare on Zephyr, common in
+     * board-bringup tooling) or when the branch only matters for
+     * logging rather than codegen. */
+	if (alp_has(ALP_CAP_ID_HW_I2C)) {
+		printf("[hello] HW I2C available (could probe sensors here)\n");
+	} else {
+		printf("[hello] no HW I2C on this SoC\n");
+	}
+
+	printf("[hello] done\n");
+	return 0;
+}

tan/templates/vendored/minimal/E1M-AEN801/testcase.yaml

@@ -0,0 +1,49 @@
+# SPDX-License-Identifier: Apache-2.0
+
+sample:
+  name: hello-world
+  description: |
+    Minimal "first program" example.  Prints a periodic heartbeat
+    so customers can verify their toolchain + flash flow + log
+    console before tackling peripheral wiring.  Builds on both
+    EVKs: no board-specific macros required.
+
+tests:
+  alp_sdk.example.hello_world.e1m_x_evk:
+    extra_args: EXTRA_CONF_FILE=generated/alp.conf
+    platform_allow:
+      - native_sim
+      - native_sim/native/64
+    integration_platforms:
+      - native_sim/native/64
+    extra_configs:
+      - 'CONFIG_COMPILER_OPT="-DALP_BOARD_E1M_X_EVK"'
+    tags:
+      - alp-sdk
+      - example
+      - hello-world
+      - v2n
+    harness: console
+    harness_config:
+        type: one_line
+        regex:
+          - "\\[hello\\] done"
+  alp_sdk.example.hello_world.e1m_evk:
+    extra_args: EXTRA_CONF_FILE=generated/alp.conf
+    platform_allow:
+      - native_sim
+      - native_sim/native/64
+    integration_platforms:
+      - native_sim/native/64
+    extra_configs:
+      - 'CONFIG_COMPILER_OPT="-DALP_BOARD_E1M_EVK"'
+    tags:
+      - alp-sdk
+      - example
+      - hello-world
+      - aen
+    harness: console
+    harness_config:
+        type: one_line
+        regex:
+          - "\\[hello\\] done"

tan/templates/vendored/minimal/E1M-V2N101/CMakeLists.txt

@@ -0,0 +1,8 @@
+# SPDX-License-Identifier: Apache-2.0
+
+cmake_minimum_required(VERSION 3.20)
+
+find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
+project(hello_world LANGUAGES C)
+
+target_sources(app PRIVATE src/main.c)

tan/templates/vendored/minimal/E1M-V2N101/README.md

@@ -0,0 +1,108 @@
+# hello-world
+
+The canonical "first program" for the Alp SDK.  No peripherals,
+no chips, no board-specific wiring -- just a periodic `printf`
+loop so you can confirm the toolchain, flash flow, and log
+console are wired correctly before chasing harder bugs.
+
+If `[hello] tick 0` doesn't appear, the suspect list is short:
+
+1.  **Toolchain** -- the build output completes cleanly but the
+    image you flashed doesn't match the SoM (cross-compiled for
+    the wrong core; mismatched Zephyr board target).
+2.  **Flash flow** -- the image flashed but boot vector / SAU /
+    secure-state config doesn't allow it to start.
+3.  **Console wiring** -- the app is running but your terminal is
+    on the wrong UART, wrong baud rate, or wrong USB enumeration.
+
+Pin down which one BEFORE moving on to alp-sdk's
+[`examples/peripheral-io/gpio-button-led`](https://github.com/alplabai/alp-sdk/tree/v0.17.0/examples/peripheral-io/gpio-button-led)
+or
+[`examples/peripheral-io/i2c-scanner`](https://github.com/alplabai/alp-sdk/tree/v0.17.0/examples/peripheral-io/i2c-scanner)
+-- neither is part of this scaffolded project.
+
+## What this shows
+
+* The minimal `board.yaml` v2 shape: `schema_version`, `som.sku`,
+  `board.name`, one `cores.<id>` with an empty `peripherals: []`.
+* That `prj.conf` stays empty -- all CONFIG_* selection comes from
+  the loader-generated `alp.conf`.
+* The Zephyr boot -> `main()` -> printf path with no peripheral
+  initialisation in between.
+
+## Build
+
+```bash
+# Standalone, native_sim (host binary; no hardware needed):
+# writes ./generated/alp.conf, which west reads below (#866)
+tan generate --target zephyr-conf --core m33_sm --sdk-root "$ALP_SDK_ROOT" --output generated/alp.conf
+west build -b native_sim/native/64 . \
+    -- -DEXTRA_CONF_FILE=generated/alp.conf -DEXTRA_ZEPHYR_MODULES=$ALP_SDK_ROOT
+west build -t run
+
+# On real silicon, point -b at the SoM's Zephyr board target.
+# Example for E1M-V2N101:
+west build -b alp_e1m_v2n101_m33_sm/r9a09g056n48gbg/cm33 . -- -DEXTRA_CONF_FILE=generated/alp.conf
+west flash --host <board-ip>
+```
+
+## Where the output lands
+
+| SoM family   | Console route                                            |
+|--------------|----------------------------------------------------------|
+| E1M-AEN      | Alif first USART -> FTDI USB-UART on E1M-EVK (115200 8N1) |
+| E1M-V2N      | Renesas SCIF -> FTDI USB-UART on E1M-X-EVK (115200 8N1)   |
+| E1M-V2N-M1   | Same as V2N                                              |
+| native_sim   | Host binary stdout                                       |
+
+Open the serial port in your terminal of choice (115200 8N1).
+The recommended cross-platform tool is `tio` -- one binary, one
+syntax on Linux, macOS, and Windows:
+
+```
+tio -b 115200 <your-serial-device>
+```
+
+Per-OS device naming (and the alternative terminals each OS
+prefers) is documented in
+[`docs/cross-platform-setup.md`](https://github.com/alplabai/alp-sdk/blob/v0.17.0/docs/cross-platform-setup.md)
+section 7.7.
+
+<!-- cross-platform-lint:ignore -->
+Quick reference: Linux uses `/dev/ttyUSB*` or `/dev/ttyACM*`;
+macOS uses `/dev/cu.usbserial-*` or `/dev/cu.usbmodem*`; Windows
+uses `COM<N>` (visible in Device Manager under "Ports (COM &
+LPT)").
+<!-- cross-platform-lint:resume -->
+
+## Expected output
+
+```
+[hello] Alp SDK hello-world starting
+[hello] tick 0
+[hello] tick 1
+[hello] tick 2
+[hello] tick 3
+[hello] tick 4
+[hello] done
+```
+
+## Customising
+
+* **Loop forever.**  Swap the bounded `for` loop in `src/main.c`
+  for the commented-out `TICKS_ON_REAL_SILICON` block.
+* **Faster heartbeat.**  Drop `HELLO_TICK_PERIOD_MS` from `1000`
+  to `100` (10 Hz) or `10` (100 Hz).  At <= 1 ms you'll start to
+  see scheduler overhead.
+* **Different log macro.**  Swap `printf` for `printk` (always
+  ISR-safe) or Zephyr's `LOG_INF` (compile-time-filtered,
+  requires `CONFIG_LOG=y` in `prj.conf`).
+
+## Reference
+
+- [`docs/firmware-quickstart.md`](https://github.com/alplabai/alp-sdk/blob/v0.17.0/docs/firmware-quickstart.md)
+  -- single-OS bring-up walk-through.
+- [`docs/cross-platform-setup.md`](https://github.com/alplabai/alp-sdk/blob/v0.17.0/docs/cross-platform-setup.md)
+  -- Windows/macOS/Linux toolchain + serial-port notes.
+- [`docs/troubleshooting.md`](https://github.com/alplabai/alp-sdk/blob/v0.17.0/docs/troubleshooting.md)
+  -- common boot/flash/console failures + fixes.

tan/templates/vendored/minimal/E1M-V2N101/board.yaml

@@ -0,0 +1,32 @@
+# board.yaml -- per-app project configuration for the
+# hello-world example.
+#
+# The simplest possible Alp SDK app: no peripherals, no chips, no
+# board-specific wiring.  Just the boot path + a periodic printf
+# loop so customers can confirm their toolchain + flash flow + log
+# console are wired correctly before chasing harder bugs.
+#
+# Customer workflow: `tan init --from-example peripheral-io/hello-world`, change `som.sku` to
+# your MPN, edit the `preset:` (or use an inline board) if you're on a non-EVK board,
+# and `tan build`, which plans alp.conf from this file; twister and a bare
+# west build read the pre-generated generated/alp.conf instead
+# (`tan generate --target zephyr-conf`, see README.md).
+som:
+  sku: E1M-V2N101
+
+preset: e1m-x-evk
+supported_boards:
+  - e1m-evk
+  - e1m-x-evk
+cores:
+  m33_sm:
+    app: ./src
+    # No peripherals -- this example exercises only the boot path
+    # and printf, both of which are part of the Zephyr baseline and
+    # need no explicit Kconfig.  When the loader sees an empty
+    # peripherals: list it still emits the SoC + board configs
+    # the SoM topology requires, so the app boots normally.
+    peripherals: []
+
+diagnostics:
+  log_level: info

tan/templates/vendored/minimal/E1M-V2N101/prj.conf

@@ -0,0 +1,8 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Intentionally empty.  Every CONFIG_* this app needs is derived
+# from board.yaml by `tan build` and layered in via
+# EXTRA_CONF_FILE (see README.md: `tan generate --target zephyr-conf`).  Add app-specific tuning
+# knobs (e.g. CONFIG_HEAP_MEM_POOL_SIZE=N) here only when they
+# are NOT feature-selection -- everything declarative belongs in
+# board.yaml.

tan/templates/vendored/minimal/E1M-V2N101/src/main.c

@@ -0,0 +1,111 @@
+/*
+ * Copyright 2026 Alp Lab AB
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * hello-world -- the canonical "first program" for the Alp SDK.
+ *
+ * No peripherals, no chips, no board-specific wiring.  Just the
+ * boot path + a periodic printf loop so customers can confirm
+ * their toolchain + flash flow + log console are wired correctly
+ * before chasing harder bugs.
+ *
+ * What success looks like:
+ *
+ *   [hello] Alp SDK hello-world starting
+ *   [hello] tick 0
+ *   [hello] tick 1
+ *   ...
+ *   [hello] tick 4
+ *   [hello] done
+ *
+ * Where the output lands depends on the SoM:
+ *
+ *   * E1M-AEN (Alif Ensemble) -- the SoC's first USART, surfaced
+ *     on the EVK board as the FTDI USB-UART (open at 115200 8N1).
+ *   * E1M-V2N / V2N-M1        -- the Renesas SCIF console; same FTDI
+ *     bridge on the E1M-X-EVK at 115200 8N1.
+ *   * native_sim host build   -- stdout of the host binary.
+ *
+ * The SDK doesn't ship its own alp_log API yet (planned post-1.0);
+ * use printf or Zephyr's LOG_* macros directly.  This example uses
+ * printf for clarity -- it lands on whatever Zephyr has picked as
+ * its console (CONFIG_LOG_BACKEND_UART under the hood).
+ */
+
+#include <stdio.h>
+
+#include <alp/cap.h>
+#include <alp/peripheral.h>
+#include <alp/soc_caps.h>
+
+/* Capped tick count keeps the native_sim run inside twister's
+ * timeout.  Real on-silicon firmware would loop forever instead --
+ * see TICKS_ON_REAL_SILICON below.  We expose the cap as a macro
+ * so customers see exactly what to change. */
+#define HELLO_TICKS 5u
+
+/* The wait between ticks.  alp_delay_ms yields the CPU to other
+ * threads + the power-management subsystem during the wait on
+ * scheduler-backed targets; on baremetal it falls through to a
+ * calibrated busy-loop (there's no scheduler to yield to). */
+#define HELLO_TICK_PERIOD_MS 1000u
+
+int main(void)
+{
+	/* Bring up the SDK runtime before anything else -- thin today,
+	 * but future backends rely on it (see <alp/peripheral.h>). */
+	(void)alp_init();
+
+	/* The first line a bring-up engineer wants to see -- it
+     * confirms the boot path made it to main() AND the printf
+     * console is decoded correctly.  If THIS line is missing,
+     * the toolchain / flash flow / console-cable is the suspect,
+     * not the SDK. */
+	printf("[hello] Alp SDK hello-world starting\n");
+
+	/* Periodic loop -- prints a monotonically-increasing tick every
+     * HELLO_TICK_PERIOD_MS so the customer can see the app is alive
+     * (not just printed once + crashed).  Capped at HELLO_TICKS so
+     * twister's console-harness one_line regex can latch the `done`
+     * marker; real firmware would loop forever. */
+	for (uint32_t tick = 0; tick < HELLO_TICKS; tick++) {
+		printf("[hello] tick %u\n", tick);
+		alp_delay_ms(HELLO_TICK_PERIOD_MS);
+	}
+
+	/* TICKS_ON_REAL_SILICON: in production firmware you'd swap the
+     * bounded for-loop above for:
+     *
+     *     for (uint32_t tick = 0; ; tick++) {
+     *         printf("[hello] tick %u\n", tick);
+     *         alp_delay_ms(HELLO_TICK_PERIOD_MS);
+     *     }
+     *
+     * Returning from main() on Zephyr is technically legal but the
+     * kernel idles afterwards -- nothing keeps the heartbeat going. */
+
+	/* Capability-API teaching block.
+     *
+     * `ALP_HAS()` is a compile-time constant expression.  Use it for
+     * #if / static_assert -- the unused branch disappears entirely
+     * from the binary, so this is zero-cost on parts that lack the
+     * feature. */
+#if ALP_HAS(HELIUM_MVE)
+	printf("[hello] this build targets a Helium-capable SoC\n");
+#else
+	printf("[hello] no Helium MVE on this SoC -- scalar path\n");
+#endif
+
+	/* `alp_has()` is the runtime equivalent.  Useful when the same
+     * binary may run on different SoCs (rare on Zephyr, common in
+     * board-bringup tooling) or when the branch only matters for
+     * logging rather than codegen. */
+	if (alp_has(ALP_CAP_ID_HW_I2C)) {
+		printf("[hello] HW I2C available (could probe sensors here)\n");
+	} else {
+		printf("[hello] no HW I2C on this SoC\n");
+	}
+
+	printf("[hello] done\n");
+	return 0;
+}