Boreas 0.1.0

Zephyr-compatible kernel APIs and device model for ESP-IDF.

Boreas brings Zephyr RTOS API conventions to ESP-IDF projects running on
FreeRTOS — a thin, tested abstraction layer, not a port. Named for the Greek
god of the north wind, a sibling to Zephyr (west wind).

This is the first tagged release. It closes out the 2026-06 hardening series and
sets the baseline API surface that downstream projects pin to.

What's included

Component	Surface
zkernel	k_timer, k_work / k_work_delayable / work queues, k_sem, k_mutex, k_msgq, k_event, k_thread, sys_slist, sys_dlist, ring_buf, timeout API (K_MSEC/K_NO_WAIT/K_FOREVER), SYS_INIT framework
zdevice	device_t, DEVICE_DEFINE, and *_dt_spec bus helpers for I2C, SPI, GPIO, and UART
zsys	per-module log levels, thread analyzer, subsystem watchdog, retry/backoff
zshell	SHELL_CMD_REGISTER command registration

Public headers live under the boreas/ prefix (boreas/zephyr/kernel.h,
boreas/zephyr/init.h, boreas/zephyr/sys/util.h, … plus the device-model
headers boreas/device_model.h, boreas/i2c_dt.h, boreas/gpio_dt.h, …).

Release highlights

The 2026-06 hardening series made the blocking primitives match upstream Zephyr
semantics under stress:

• k_sem and k_event are notification-backed (#41, #42) — no FreeRTOS
  control block. K_SEM_DEFINE / K_EVENT_DEFINE are true compile-time
  initializers usable from any constructor (pre-scheduler safe). When a take/wait
  returns, the kernel holds no references into the caller's struct.
• k_work cancel + return codes match upstream (#37, #38) — upstream-parity
  return codes, K_WORK_CANCELING enforced, self-rescheduling delayables stop
  reliably with one k_work_cancel_delayable_sync().
• k_thread lifecycle honors the caller-owned-memory contract (#18) — a
  returning entry function terminates the thread; k_thread_join reclaims it and
  no longer false-joins suspended threads.
• k_timer status_sync no longer blocks the timer dispatch (#49); ISR-context
  k_timer dispatch alignment (#12).
• ring_buf added with index-wrap / peek-across-wrap coverage (#50).
• ISR-safe helpers are IRAM-resident (#54, closes #53) — z_sem_pop_waiter
  and the rest of the K_ISR_SAFE call surface now live in .iram0.text, so
  k_sem_give / k_work_submit from an ESP_INTR_FLAG_IRAM interrupt during a
  flash-cache-disabled window no longer cache-fault. A build-time guard
  (tools/check_iram_symbols.sh) asserts the placement on the target ELF.
• Stress + regression suites for the timeout-vs-give and post-wakes-all races
  (#39, #48). Tests run on ESP-IDF's linux target (no hardware) and on-device
  (ESP32-S3).

Behavior & compatibility notes

Semantics that differ from a naive FreeRTOS wrapper — relevant if you're pinning
to this tag or upgrading from tracking main:

• k_work_submit* success is no longer 0. Upstream-parity codes: 0 =
  no-op (already queued), 1 = queued, 2 = was running and queued again,
  negative = error. < 0 checks are unaffected; == 0 success checks must change.
• k_work_cancel polarity is inverted — it returns remaining busy state
  (nonzero = still busy). k_work_cancel_sync now returns bool was-pending.
• Task-notification index 1 is reserved for zkernel blocking primitives —
  don't use it in application code. Requires
  CONFIG_FREERTOS_TASK_NOTIFICATION_ARRAY_ENTRIES >= 2 (supplied via
  sdkconfig.boreas).
• Do not abort a thread blocked in k_sem_take — upstream unpends aborted
  threads; Boreas cannot (see the @note on k_sem_take).

Full migration checklist is in CHANGELOG.md.

Requirements

• ESP-IDF (uses freertos, esp_timer, log, driver); tested on v5.4 and v5.5
• sdkconfig.boreas added to your SDKCONFIG_DEFAULTS (a compile-time error
  names it if missing)
• Targets: ESP32-S3 (on-device) and the ESP-IDF linux target (tests)

Getting started

git submodule add https://github.com/intercreate/boreas.git components/boreas

# Top-level CMakeLists.txt, before project.cmake
set(EXTRA_COMPONENT_DIRS components/boreas/components)
set(SDKCONFIG_DEFAULTS "sdkconfig.defaults;components/boreas/sdkconfig.boreas")

Then rm -rf build sdkconfig && idf.py set-target <target>, and add the Boreas
components you use to your component's REQUIRES. See the
README for the full walkthrough and each component's README.md.

Maturity & scope

Early-stage (0.1.0) but exercised: Boreas ships with linux- and device-target
test suites that run on every change. It implements a curated subset of the
Zephyr API surface — not the full RTOS, kernel scheduler, or devicetree. Scope
grows as real projects need it.

License & attribution

Apache 2.0, © 2026 Intercreate. Kernel API surface derived from
Zephyr RTOS (Apache 2.0).