---
title: "Kernel"
canonical_url: https://developer.repebble.com/pebbleos/docs/kernel/
last_updated: 2026-10-21
sdk_version: 4.33.1
---
# Kernel

Source: https://developer.repebble.com/pebbleos/docs/kernel/

`kernel/` owns every RTOS primitive the firmware uses. The public API lives in `include/pbl/kernel/` and is the only threading interface the rest of the tree may use. The implementation is PebbleOS’s own.

## Topics

- [Threads](https://developer.repebble.com/pebbleos/docs/kernel/threads.md)
- [Syscalls](https://developer.repebble.com/pebbleos/docs/kernel/syscalls.md)
- [Interrupts](https://developer.repebble.com/pebbleos/docs/kernel/interrupts.md)
- [Time and delays](https://developer.repebble.com/pebbleos/docs/kernel/time.md)
- [Boot](https://developer.repebble.com/pebbleos/docs/kernel/boot.md)
- [Idle](https://developer.repebble.com/pebbleos/docs/kernel/idle.md)
- [Memory](https://developer.repebble.com/pebbleos/docs/kernel/memory.md)
- [Fatal errors and assertions](https://developer.repebble.com/pebbleos/docs/kernel/fatal.md)
- [Compiler abstraction](https://developer.repebble.com/pebbleos/docs/kernel/compiler.md)
- [Kernel internals](https://developer.repebble.com/pebbleos/docs/kernel/internals.md)

## Layout

```
block-beta
  columns 2
  api["Public API · include/pbl/kernel/<br/>threads, mutexes, semaphores, queues, poll, IRQs"]:2
  core["Kernel · kernel/<br/>scheduler, objects, ticks"]:2
  arm["Cortex-M port · kernel/arch/arm/<br/>context switch, SVC, MPU, SysTick"] posix["Host port · kernel/arch/posix/<br/>native simulator, unit tests"]

  classDef app fill:#fa4a36,stroke:#fa4a36,color:#ffffff
  classDef system fill:#fd8a7c,stroke:#fd8a7c,color:#171717
  classDef base fill:#525252,stroke:#525252,color:#ffffff
  class api app
  class core system
  class arm,posix base
```

Next to the API, `include/pbl/kernel/` holds:

- `backend.h`: the private state each public object struct embeds;

- `compiler.h`: the [compiler abstraction](https://developer.repebble.com/pebbleos/docs/kernel/compiler.md);

- `section.h`: the placement of code and data in special sections.

## Objects

| 

Object

 | 

Struct

 | 

Static define

 |
| --- | --- | --- |
| 

Thread

 | 

`struct pbl_thread`

 | 

`PBL_THREAD_STACK_DEFINE` + `pbl_thread_create`

 |
| 

Mutex

 | 

`struct pbl_mutex`

 | 

`PBL_MUTEX_DEFINE`

 |
| 

Semaphore

 | 

`struct pbl_sem`

 | 

`PBL_SEM_DEFINE`

 |
| 

Message queue

 | 

`struct pbl_msgq`

 | 

`PBL_MSGQ_DEFINE`

 |
| 

Poll group

 | 

`struct pbl_poll_group`

 | 

`PBL_POLL_GROUP_DEFINE`

 |

Conventions:

- Every object is a caller-owned struct; there is no create/destroy pair that hands out heap handles. A `PBL_*_DEFINE` is a complete static initialiser, so a defined object is usable before the scheduler starts and needs no init call. `pbl_*_init()` exists for objects that live in dynamically allocated memory.

- Blocking calls take a `pbl_timeout_t` (`PBL_NO_WAIT`, `PBL_FOREVER`, `PBL_MSEC()`, `PBL_TICKS()`). The struct type stops ticks/ms mix-ups.

- Return `int`: 0 on success, `-EAGAIN` on timeout, `-EBUSY` for `PBL_NO_WAIT`.

- No `_from_isr` variants: `pbl_in_isr()` picks the path and any needed context switch is requested inside the call.

- Mutexes are recursive with owner and lock-site tracking. Non-recursive intent is expressed with `pbl_mutex_assert_held(m, false)`.

- Priorities: higher is more urgent, `PBL_PRIO_IDLE` .. `PBL_PRIO_MAX`.

- Returning from a thread entry function ends the thread.

## Configuration

`kernel/Kconfig` holds the tick rate, the number of priorities, the NVIC priority levels the kernel uses, the thread limit, the TLS slot count and the stack alignment the MPU guard needs.

`kernel/arch/arm/Kconfig` describes the CPU: each SoC selects its core (`CPU_CORTEX_M4`, `CPU_CORTEX_M33`, `CPU_STAR_MC1`) and features (`CPU_HAS_FPU`), the core selects its architecture (`ARMV7_M`, `ARMV8_M_MAINLINE`) and the architecture its traits (`CPU_CORTEX_M_HAS_SPLIM`). The compiler flags and the MPU backend are derived from these symbols. QEMU boards pick the emulated core with `SOC_QEMU_CORTEX_M4` or `SOC_QEMU_CORTEX_M33`.

## Modules

The [API reference](https://developer.repebble.com/pebbleos/apidoc/d9/d7c/group__kernel.html) documents every kernel module.

## MCU and SoC

CPU core helpers (`pbl/mcu/`) wrap the architecture’s interrupt, cache, FPU and MPU control; `pbl/soc/` holds what is specific to one SoC family.

The API reference documents both: [MCU](https://developer.repebble.com/pebbleos/apidoc/dd/dcb/group__mcu.html) and [SoC](https://developer.repebble.com/pebbleos/apidoc/dd/def/group__soc.html).

Generated from PebbleOS [3a7b71785](https://github.com/coredevices/pebbleos/commit/3a7b71785fd439666c4a8bc116f561140e8dec01). This page is maintained in the pebbleos repository: [docs/kernel/index.md](https://github.com/coredevices/pebbleos/blob/3a7b71785fd439666c4a8bc116f561140e8dec01/docs/kernel/index.md).