Boreas:: Zephyr-style kernel APIs and a device model

[_swoz_]

Sharing an open-source project we've been using in our ESP-IDF work: Boreas, a thin compatibility layer that lets you write IDF projects using Zephyr RTOS API conventions; a more uniform, structured surface on top of ESP-IDF/FreeRTOS.

What you get:

- Kernel primitives: k_sem, k_work, k_timer, k_thread, k_msgq, k_event, slist/dlist, ring buffer, and the timeout model
- A device model: device_t + *_dt_spec helpers for I2C/SPI/GPIO/UART that separate hardware description from application logic. Changing a pin or supporting a different board revision becomes a config change. Proper DTS is not here, so configs live in code. In other projects we've made adc, i2s, temp_sensor devices and more
- System services: per-module log levels, thread analyzer, subsystem watchdog, retry/backoff
- A shell with excellent command-registration ergonomics

It's not an OS port and it sits on top of the ESP-IDF you already use. The components are independent, so you can pull in just the piece you want (on one project we grabbed only zshell).

Tested on ESP-IDF v5.4/v5.5, both on the linux target (no hardware needed) and on-device on the ESP32-S3 and -C5. Apache-2.0; kernel API surface derived from Zephyr (also Apache-2.0).

Notable here is the "why not just use Zephyr". The short answer is business reasons. Not all teams want the on-ramp for Zephyr, IDF ecosystem requires it, new silicon, or more.

Repo + runnable examples: https://github.com/intercreate/boreas
Release notes (v0.1.0): https://github.com/intercreate/boreas/r ... tag/v0.1.0

Feedback very welcome!

[MicroController]

Just at a glance:

- For k_mutex you may want to use a "recursive" mutex (xSemaphoreCreateRecursiveMutex()) instead of implementing it yourself on top of a non-recursive one.

- k_thread: vTaskSuspend() has an inherent race condition and should not be used; xTaskNotifyWait() is a better and safe alternative to use.

- atomics: You should prefer using C's standard atomics (<stdatomic.h>)

- k_sem: How about just wrapping a FreeRTOS semaphore instead of rolling your own implementation?

[_swoz_]

Thanks for the feedback! Much appreciated

- I misread the docs on the Recursive Mutex - that's a better solution
- looking more into this. In practice I never ran into this issue but for completeness I will do the right thing here.
- atomics: under the hood they are stdatomics, but the API/ABI for Zephyr modules is where these atomics come into play
- k_sem: another compatibility spec for Zephyr modules; FreeRTOS model has a misalignment here. I'll either test the heck out of this approach or find a way to use FreeRTOS semaphore but limit Zephyr compatibility loudly.

[MicroController]

- atomics: under the hood they are stdatomics

I think you got that one backwards. "__atomic_store_n()", for example, is (likely) "under gcc's hood" of the standard C "atomic_store_explicit()".

- looking more into this.

The problem is, if, for whatever (scheduling/priority) reason, the vTaskResume() happens before the target task gets to executing its vTaskSuspend(), the "resume" is simply lost, the task enters the "suspended" state, and never gets out of it again. Notifications are "sticky", i.e. they stay pending until the task consumes them.

- k_sem: another compatibility spec for Zephyr modules; FreeRTOS model has a misalignment here.

Yeah, looks like there's no way to emulate "k_sem_reset()" via FreeRTOS APIs. Apart from that, they seem compatible.