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:

// 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_err_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 — 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.
• Instance IDs (ALP_E1M_I2C0, ALP_E1M_PWM3, …) come from <alp/e1m_pinout.h> and are portable across every E1M-conformant SoM.
• alp_err_t is an integer; ALP_OK == 0. Failure codes are documented per-call but use a small common set (see Architecture).
• 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>.

Headers

Peripherals

Header	Page	What it provides
<alp/peripheral.h>	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	(experimental) Register-file I²C target helper over the target-mode surface
<alp/i3c.h>	I3C	I3C controller class; experimental. Open proven on Alif Ensemble E8; live transfer unproven.
<alp/pwm.h>	PWM	PWM channels
<alp/adc.h>	ADC	Analog-to-digital sampling, streaming, filters
<alp/dac.h>	DAC	Digital-to-analog output (millivolt domain)
<alp/counter.h>	Counter	Counters + quadrature encoder
<alp/i2s.h>	I²S	I²S / SAI audio bus
<alp/can.h>	CAN	CAN / CAN-FD
<alp/rtc.h>	RTC	Real-time clock
<alp/wdt.h>	WDT	Watchdog timer
<alp/usb.h>	USB	USB 2.0 / 3.0

Audio / camera / display

Header	Page	What it provides
<alp/audio.h>	Audio	PDM in + I²S out, Alp-default DSP chain
<alp/camera.h>	Camera	MIPI CSI / parallel camera, ISP
<alp/display.h>	Display	Display subsystem (raw)
<alp/gpu2d.h>	GPU2D	(experimental) Portable 2D blit / fill / blend; D/AVE 2D on AEN, CPU fallback elsewhere
<alp/jpeg.h>	JPEG	(experimental) JPEG encoder; Alif E8 Hantro VC9000E hardware backend, portable software baseline elsewhere.
<alp/gui.h>	GUI	LVGL re-export with Alp defaults

Inference

Header	Page	What it provides
<alp/inference.h>	Inference	NPU dispatcher (Ethos-U / DRP-AI / DEEPX / CPU)
<alp/model.h>	Model packaging	(experimental) Read-side parser for the portable .alpmodel package — alp_model_parse()
<alp/dsp.h>	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	(experimental) Madgwick IMU orientation filter — libraries: [madgwick_ahrs]
<alp/pid.h>	PID	(experimental) PID control loop with clamping + anti-windup — libraries: [pid]
<alp/tmu.h>	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	Wi-Fi station + MQTT
<alp/ble.h>	BLE	BLE 5.4 peripheral + central
<alp/security.h>	Security	MbedTLS PSA Crypto (hash / AEAD / TRNG)

System

Header	Page	What it provides
<alp/rpc.h>	RPC	Framed RPC over OpenAMP/RPMsg (heterogeneous IPC)
<alp/mproc.h>	Mproc	Raw mailbox / shared mem / hwsem primitives
<alp/hw_info.h>	HW Info	EEPROM manifest + BOARD_ID ADC
<alp/power.h>	Power	System power modes
<alp/storage.h>	Storage	Block storage, optional inline AES
<alp/update_log.h>	Update Log	Tamper-evident firmware-update audit log (experimental)
<alp/version.h>	Version & ABI	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	(experimental) alp_has() / ALP_HAS() / alp_cap_name() — SoC-level capability queries. Umbrella include for the whole capability surface.
<alp/cap_instance.h>	Capabilities	(experimental) alp_capabilities_has() + the per-instance descriptor each alp_<class>_capabilities() returns.
<alp/backend.h>	Backend Registry	(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 page.
<alp/e1m_pinout.h>	E1M-spec instance IDs + portability bounds (ALP_E1M_<CLASS>_COUNT). See Pinout.
<alp/e1m_x_pinout.h>	E1M-X instance IDs + bounds. See 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.
<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.
<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>	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/...> — 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-stability.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 — which backend, which OS, which SoM
• 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/. Build locally with doxygen Doxyfile.

Where next

• <alp/peripheral.h> — the most-used header (GPIO / I²C / SPI / UART)
• Chip catalogue
• Examples