---
title: "API Overview"
description: "The Alp SDK's public surface lives under include/alp/. Every header is C99-compatible and Doxygen-documented; this page summarises what each one provides."
source: https://docs.alplab.ai/sdk/api/overview
---

# API Reference

The Alp SDK's public surface lives under `include/alp/`. Every header is C99-compatible and Doxygen-documented; this page summarises what each one provides.

## Conventions

All public APIs follow the same shape:

```c
// Open a peripheral
alp_<class>_t *handle = alp_<class>_open(&(alp_<class>_config_t){ ... });
if (handle == NULL) {
    int err = alp_last_error();   // ALP_ERR_NOSUPPORT, OUT_OF_RANGE, ...
}

// Operate
alp_status_t rc = alp_<class>_<op>(handle, ...);

// Close
alp_<class>_close(handle);
```

- **Handles** are opaque pointers returned by `_open()`. `NULL` indicates failure.
- **`alp_last_error()`** is a thread-local diagnostic. Read it whenever `_open()` returns `NULL` or `*_op` returns an error. Concurrent `open()` calls on different threads don't clobber each other's diagnostic; a successful `open()` clears that thread's slot, and every thread's initial state is `ALP_OK`.
- **`ALP_*_CONFIG_DEFAULT(id)`** (v0.10) default-initialises a config struct from its identity field, so callers set only what they change. See [the shared contract](https://docs.alplab.ai/sdk/api/peripheral#default-initialiser-macros) — including the C++ compound-literal caveat — and each class's page for its defaults.
- **`alp_status_name()` / `alp_status_description()`** (v0.10) turn any `alp_status_t` into a symbolic name or a human-readable string for logs. Both are generated from the enum itself and never return `NULL`. See [Status-code strings](https://docs.alplab.ai/sdk/api/peripheral#status-code-strings).
- **Instance IDs** (`ALP_E1M_I2C0`, `ALP_E1M_PWM3`, …) come from `<alp/e1m_pinout.h>` and are portable across every E1M-conformant SoM.
- **`alp_status_t`** is the status enum every operation returns; `ALP_OK == 0`. Failure codes are documented per-call but use a small common set (see [Architecture](https://docs.alplab.ai/sdk/architecture#error-model)).
- **SDK lifecycle** (v0.9): call `alp_init()` once at startup before the first `_open()`, and `alp_deinit()` at teardown. Both are `[ABI-EXPERIMENTAL]`, idempotent, and thin today — but portable code must not skip them. See [`<alp/peripheral.h>`](https://docs.alplab.ai/sdk/api/peripheral#sdk-lifecycle).

## Headers

### Peripherals

| Header                                                  | Page                              | What it provides                                  |
|---------------------------------------------------------|-----------------------------------|---------------------------------------------------|
| `<alp/peripheral.h>`                                    | [Peripheral](https://docs.alplab.ai/sdk/api/peripheral) | I²C, SPI, GPIO, UART — the four core bus classes; v0.9 adds I²C/SPI **target (slave) mode** |
| `<alp/i2c_regfile.h>`                                   | [I²C Register File](https://docs.alplab.ai/sdk/api/i2c-regfile) | (experimental) Register-file I²C target helper over the target-mode surface |
| `<alp/i3c.h>`                                           | [I3C](https://docs.alplab.ai/sdk/api/i3c)               | I3C controller class; experimental. Open proven on Alif Ensemble E8; live transfer unproven. |
| `<alp/pwm.h>`                                           | [PWM](https://docs.alplab.ai/sdk/api/pwm)               | PWM channels                                      |
| `<alp/adc.h>`                                           | [ADC](https://docs.alplab.ai/sdk/api/adc)               | Analog-to-digital sampling, streaming, filters    |
| `<alp/dac.h>`                                           | [DAC](https://docs.alplab.ai/sdk/api/dac)               | Digital-to-analog output (millivolt domain)       |
| `<alp/counter.h>`                                       | [Counter](https://docs.alplab.ai/sdk/api/counter)       | Counters + quadrature encoder                     |
| `<alp/i2s.h>`                                           | [I²S](https://docs.alplab.ai/sdk/api/i2s)               | I²S / SAI audio bus                               |
| `<alp/can.h>`                                           | [CAN](https://docs.alplab.ai/sdk/api/can)               | CAN / CAN-FD                                      |
| `<alp/rtc.h>`                                           | [RTC](https://docs.alplab.ai/sdk/api/rtc)               | Real-time clock                                   |
| `<alp/wdt.h>`                                           | [WDT](https://docs.alplab.ai/sdk/api/wdt)               | Watchdog timer                                    |
| `<alp/usb.h>`                                           | [USB](https://docs.alplab.ai/sdk/api/usb)               | USB 2.0 / 3.0                                     |

### Audio / camera / display

| Header              | Page                              | What it provides                                  |
|---------------------|-----------------------------------|---------------------------------------------------|
| `<alp/audio.h>`     | [Audio](https://docs.alplab.ai/sdk/api/audio)           | PDM in + I²S out, Alp-default DSP chain           |
| `<alp/camera.h>`    | [Camera](https://docs.alplab.ai/sdk/api/camera)         | Camera capture: Zephyr video / ISP-Pico on AEN, V4L2 on Linux (v0.17.0) |
| `<alp/display.h>`   | [Display](https://docs.alplab.ai/sdk/api/display)       | Display subsystem (raw)                           |
| `<alp/gpu2d.h>`     | [GPU2D](https://docs.alplab.ai/sdk/api/gpu2d)           | (experimental) Portable 2D blit / fill / blend; D/AVE 2D on AEN, CPU fallback elsewhere |
| `<alp/jpeg.h>`      | [JPEG](https://docs.alplab.ai/sdk/api/jpeg)             | (experimental) JPEG encoder; Alif E8 Hantro VC9000E hardware backend, portable software baseline elsewhere. |
| `<alp/gui.h>`       | [GUI](https://docs.alplab.ai/sdk/api/gui)               | LVGL re-export with Alp defaults                  |

### Inference

| Header              | Page                              | What it provides                                  |
|---------------------|-----------------------------------|---------------------------------------------------|
| `<alp/inference.h>` | [Inference](https://docs.alplab.ai/sdk/api/inference)   | NPU dispatcher (Ethos-U / DRP-AI / DEEPX / CPU)   |
| `<alp/model.h>`     | [Model packaging](https://docs.alplab.ai/sdk/model-packaging) | (experimental) Read-side parser for the portable `.alpmodel` package — `alp_model_parse()` |
| `<alp/dsp.h>`       | [DSP](https://docs.alplab.ai/sdk/api/dsp)               | FIR/IIR/window/FFT chains over CMSIS-DSP, summary stats, RBJ biquad designer |

### Math, control & sensor fusion

| Header              | Page                              | What it provides                                  |
|---------------------|-----------------------------------|---------------------------------------------------|
| `<alp/ahrs.h>`      | [AHRS](https://docs.alplab.ai/sdk/api/ahrs)             | (experimental) Madgwick IMU orientation filter — `libraries: [madgwick-ahrs]` |
| `<alp/pid.h>`       | [PID](https://docs.alplab.ai/sdk/api/pid)               | (experimental) PID control loop with clamping + anti-windup — `libraries: [pid]` |
| `<alp/tmu.h>`       | [TMU](https://docs.alplab.ai/sdk/api/tmu)               | (experimental) 12 stateless transcendental primitives; GD32 CORDIC offload on V2N, libm elsewhere |

`<alp/ahrs.h>` and `<alp/pid.h>` are opt-in `board.yaml` libraries, caller-owned (no pool, no handle), and pure portable C. `<alp/tmu.h>` is always available and dispatches through the backend registry.

### Connectivity & security

| Header              | Page                              | What it provides                                  |
|---------------------|-----------------------------------|---------------------------------------------------|
| `<alp/iot.h>`       | [IoT](https://docs.alplab.ai/sdk/api/iot)               | Wi-Fi station + MQTT                              |
| `<alp/ble.h>`       | [BLE](https://docs.alplab.ai/sdk/api/ble)               | BLE 5.4 peripheral + central                      |
| `<alp/security.h>`  | [Security](https://docs.alplab.ai/sdk/api/security)     | MbedTLS PSA Crypto (hash / AEAD / TRNG)           |

### System

| Header              | Page                              | What it provides                                  |
|---------------------|-----------------------------------|---------------------------------------------------|
| `<alp/rpc.h>`       | [RPC](https://docs.alplab.ai/sdk/api/rpc)               | Framed RPC over OpenAMP/RPMsg (heterogeneous IPC) |
| `<alp/mproc.h>`     | [Mproc](https://docs.alplab.ai/sdk/api/mproc)           | Raw mailbox / shared mem / hwsem primitives       |
| `<alp/hw_info.h>`   | [HW Info](https://docs.alplab.ai/sdk/api/hw-info)       | EEPROM manifest + BOARD_ID ADC, Secure Data Page mirror |
| `<alp/temperature.h>` | [Temperature](https://docs.alplab.ai/sdk/api/temperature) | (experimental, v0.17.0) On-module ambient sensor and SoC die temperature, in milli-°C |
| `<alp/power.h>`     | [Power](https://docs.alplab.ai/sdk/api/power)           | System power modes incl. STOP, RAM retention, SoM power domains, boot wake record |
| `<alp/storage.h>`   | [Storage](https://docs.alplab.ai/sdk/api/storage)       | Block storage; inline-AES surface + Alif SecAES key provisioning |
| `<alp/update_log.h>`| [Update Log](https://docs.alplab.ai/sdk/api/update-log) | Tamper-evident firmware-update audit log (experimental) |
| `<alp/version.h>`   | [Version & ABI](https://docs.alplab.ai/sdk/api/version) | SDK version macros + per-class ABI-tier feature-test (`ALP_VERSION_AT_LEAST`, `ALP_ABI_STATUS_*`, `alp_version_string()`) |

### Capability / portability

| Header                  | Page                                    | What it provides                                  |
|-------------------------|-----------------------------------------|---------------------------------------------------|
| `<alp/cap.h>`           | [Capabilities](https://docs.alplab.ai/sdk/api/capabilities)   | (experimental) `alp_has()` / `ALP_HAS()` / `alp_cap_name()` — SoC-level capability queries. Umbrella include for the whole capability surface. |
| `<alp/cap_instance.h>`  | [Capabilities](https://docs.alplab.ai/sdk/api/capabilities#instance-level-what-can-this-handle-do) | (experimental) `alp_capabilities_has()` + the per-instance descriptor each `alp_<class>_capabilities()` returns. |
| `<alp/backend.h>`       | [Backend Registry](https://docs.alplab.ai/sdk/api/backend)    | (experimental) `alp_backend_count/select/select_next` — the registration + selection mechanism under every `alp_<class>_open()`. |

These headers carry **no functions** — macros and constants only:

| Header                  | What it provides                                                |
|-------------------------|------------------------------------------------------------------|
| `<alp/soc_caps.h>`      | (generated) Active-SoC capability constants (`ALP_SOC_REF_STR`, `ALP_SOC_ADC_MAX_RESOLUTION_BITS`, …) used by `*_open()`. Documented on the [Capabilities](https://docs.alplab.ai/sdk/api/capabilities#alpsoc_capsh--the-generated-constants) page. |
| `<alp/e1m_pinout.h>`    | E1M-spec instance IDs + portability bounds (`ALP_E1M_<CLASS>_COUNT`). See [Pinout](https://docs.alplab.ai/hardware/pinout). |
| `<alp/e1m_x_pinout.h>`  | E1M-X instance IDs + bounds. See [Pinout](https://docs.alplab.ai/hardware/pinout). |
| `<alp/board.h>`         | Board-agnostic facade for cross-EVK examples: includes the active board's generated routes header (selected by the `ALP_BOARD_<SLUG>` define the build emits from the `board.yaml` preset) so an example can open pins via portable `BOARD_*` aliases. Form-factor-specific examples should include the specific routes header instead. See [board.yaml](https://docs.alplab.ai/sdk/board-yaml). |
| `<alp/console.h>`       | No portable symbols today — the `alp` shell command group (board / gpio / i2c / adc / pwm / mem / clk / companion) **self-registers** on any console-enabled build. Deliberately chip-neutral; companion attach lives behind `<alp/ext/<companion>/console.h>`. See [Console](https://docs.alplab.ai/sdk/tools/console). |
| `<alp/boards/<board>.h>`   | Board-feature names (e.g. EVK pin map; one header per board preset). |

### Generated headers

| Header                  | What it provides                                                |
|-------------------------|------------------------------------------------------------------|
| `<alp/system_ipc.h>`    | Endpoint IDs, addresses, mailbox channel macros — emitted from `board.yaml`'s `ipc:` block. Both halves of a heterogeneous project `#include` it. |
| `"alp_hw_info_build.h"` | Generated under `build/generated/`; include with quotes. `ALP_HW_BUILD_*` macros baked from `board.yaml`'s `som:` block + top-level board declaration (inline or `preset:`). |

### Chip drivers

50+ drivers under [`<alp/chips/...>`](https://docs.alplab.ai/sdk/chips) — opt-in via `board.yaml`'s `chips:` array. Each driver follows the same shape: `<chip>_init(&ctx, bus, ...)` → per-feature getters / setters. Driver names use the chip's natural manufacturer name (`lsm6dso_*`, `ssd1306_*`, `gd32g553_*`); the `alp_` prefix is reserved for SDK-level abstractions.

## ABI stability

Every public header is annotated `[ABI-STABLE]` or `[ABI-EXPERIMENTAL]` at the file-level Doxygen block. The SDK ships an ABI snapshot + a `pr-abi-snapshot.yml` CI job that blocks merges which change the binary surface without an explicit bump. Stable headers carry that contract until the next major bump; experimental headers (e.g. `<alp/gpu2d.h>`, the wave-2 `<alp/dsp.h>` chain types, `<alp/power.h>`'s mode setter) reserve the right to evolve pre-v1.0.

Pin your SDK to a specific commit if you depend on an experimental surface. See [`docs/abi/README.md`](https://github.com/alplabai/alp-sdk/blob/main/docs/abi/README.md) for the policy.

## Per-row implementation status

Some headers are surface-only on certain (OS × SoM) combinations — the call returns `NULL` + `ALP_ERR_NOSUPPORT`. The authoritative per-row status lives in the SDK repo:

- [`docs/os-support-matrix.md`](https://github.com/alplabai/alp-sdk/blob/main/docs/os-support-matrix.md) — which backend, which OS, which SoM
- [`docs/test-plan.md`](https://github.com/alplabai/alp-sdk/blob/main/docs/test-plan.md) — HW-verified (✅) vs code-merged-pending (🟡) vs not-started (⏳)

## Doxygen

The full Doxygen-rendered reference is available in the SDK repo at [`docs/doxygen/`](https://github.com/alplabai/alp-sdk/tree/main/docs/doxygen). Build locally with `doxygen Doxyfile`.

## Where next

- [`<alp/peripheral.h>`](https://docs.alplab.ai/sdk/api/peripheral) — the most-used header (GPIO / I²C / SPI / UART)
- [Chip catalogue](https://docs.alplab.ai/sdk/chips)
- [Examples](https://docs.alplab.ai/sdk/examples/overview)
