Copyright (c) 2026 Muhammad Anisur Rahman. All rights reserved. See COPYRIGHT.
TUWA is a small preemptive real-time operating system. A portable C kernel - scheduler, memory manager, timers and a full set of inter-task communication primitives - runs over a thin per-CPU layer and a per-board support package.
It boots on four cores today, and on every one of them it schedules preemptively, mounts a FAT12 filesystem on a RAM disk, loads a relocatable binary module from that filesystem and runs it, and gives you a shell to browse and load by hand.
| File | Covers |
|---|---|
docs/01-overview.md | Architecture, supported targets, what a build prints |
docs/02-build-guide.md | Build and run instructions per target core |
docs/03-porting-guide.md | Bringing TUWA to a new CPU |
docs/04-bsp-guide.md | Bringing TUWA to a new board |
docs/05-api-reference.md | The API by subsystem, with examples |
docs/06-modules.md | Run-time modules: ELF, PE and picfmt2 |
docs/api-index.md | GENERATED - the 150 public declarations |
Read 01-overview.md first. It is short, and it says plainly what is proven and what is not.
bash tools/make-package.sh [outdir]It regenerates the API index from the headers, copies the shippable files, and then scans the result and refuses to produce a package that names kernel internals or mentions a port that is not part of this release. The check exists because the risk is not copying the wrong file, it is a shipped file quietly acquiring content that should not be in it.
tools/public-api.list is the allowlist that decides what counts as public. Anything a header declares that is not on it is treated as internal, which is the safe direction to fail in.
include/ in this package is the complete compile surface for an application:
| Header | Holds |
|---|---|
tuwa_api.h | The 150 public prototypes. GENERATED from the allowlist |
tuwa_types.h | The types the API exposes - four of them opaque |
tuwa_bsp.h | The kernel-to-board contract |
modload.h, ksymtab.h, picfmt2.h | Run-time modules |
The kernel's own header is not here. It still exists and the kernel still builds against it; it is simply not part of the release, which is the point of the split.
public-api-test.c is what makes that claim checkable. It includes only these headers and uses a slice of the API, and every port compiles it on every build. If a private type ever leaks into a public prototype, the build fails and names it. Without that, "the public headers stand alone" is an assertion that quietly stops being true.
Four types are opaque - FILE_DESCRIPTOR, TUWA_DEVICE, MAIL_BUFFER, DEVICE_IO. You receive a pointer and hand it back; the layouts stay private. If you find yourself needing a field out of one, that is a missing accessor rather than a reason to reach for a private header - say so and it can be added.
It is not a binary distribution. The headers are split and checked, but the kernel still ships as source rather than as a prebuilt library, and there is no licence text - COPYRIGHT records authorship and grants nothing.
internal/UNCLASSIFIED.md lists the 831 declarations that stayed private, by header. It is the record of what the split decided, does not ship, and make-package.sh fails if it ever leaks into a package.
Two further gaps stand between this and a binary release:
Both prerequisites from the distribution plan are now done: the public/private header split, and tuwa_bsp.h pinning the kernel-to-board contract. What remains for a binary release is building the kernel as a library and choosing licence terms.
None of that blocks using these documents to build TUWA, port it, or write a BSP. It blocks handing the tree to a third party as a product.