Writing examples — naming & structure convention

Every program under examples/ follows this convention. It exists so a reader can tell, from the directory name alone, what feature the example demonstrates, which architecture it needs, and which board — while keeping examples as portable (and as un-suffixed) as possible.

One example, one feature

An example demonstrates exactly one feature, in the smallest self-contained way: instantiate → use → done. It is not a kitchen sink. If you find yourself showing two features, split into two examples.

  • No redundancy — if an existing example already covers the feature on a given target, don’t add a near-duplicate.

  • Minimal — only the code needed to show the feature and prove it worked (a print, an LED, a fault).

Directory naming

The directory name is the feature: examples/<feature>.

Add a suffix only when necessary, and only as much as necessary:

Form

When

Example

examples/<feature>

the feature/API is portable (the goal)

threads, trace, watchdog, isolation

examples/<feature>_<arch>

the feature or its API is architecture-specific, or the same feature needs a separate demo per architecture

fence_riscv, fence_tricore, unpriv_tricore

examples/<feature>_<arch>_<board>

the feature is board-specific and the arch alone doesn’t identify the board needed

fence_arm_v8m_frdm_mcxn947

Rules:

  • Portability first. An arch/board suffix is the down-prioritized exception. Prefer writing a portable example; only lock it to an arch/board when the feature genuinely cannot be “just a demo.”

  • <arch> = the family, disambiguated only when needed. Use the family (arm, riscv, tricore) when one demo covers it; add the sub-arch only to disambiguate multiple demos of the same feature (the three ARM supervisor-fence demos are fence_arm_v7a, fence_arm_v8a, fence_arm_v8r because the mechanism differs per profile; a single ARM-only demo is just hardfault).

  • No _demo suffix — it’s redundant inside examples/.

  • The Makefile’s PROJECT := must equal the directory name.

Worked examples

  • threads — bring up the kernel and spawn threads (portable).

  • trace — the trace ring API (portable).

  • watchdog — the watchdog API (portable).

  • fence_arm_v7a / fence_riscv / fence_tricore — the supervisor-fence API, one demo per mechanism.

  • unpriv_tricore, csa_reclaim_tricore — features currently demonstrated only on AURIX TriCore. When a portable version lands for other architectures, these remain the TriCore instances.

Structure & comment style

Keep the body a clear instantiate → use → done sequence. Step comments describe the step in plain words — do not number them:

/* Create the semaphore the producer will post. */
sem = tk_sem_create(0);

/* Spawn the worker on its own stack. */
tk_thread_create(worker, NULL, stack, sizeof stack, TK_PRIO_MIN + 1u);

Not /* 1. Create the semaphore */ — the numbering adds nothing and rots when steps change.

The file header comment should open with <dir>/main.c — <one line: what this demonstrates> and, where useful, a one-line build/run note (make BOARD=<board> flash).

Porting legacy examples

The pre-reshape tree (_legacy/examples/) holds ~90 more demos (peripherals, crypto, secure-boot, more boards). They are ported on demand, together with the API/HAL they exercise — not ahead of it — and each is renamed to this convention when it lands. See docs/readiness-1.0.0/dashboard.md for what is planned.