Complete microtimer professional documentation

Author: Vanderhell

CONTRIBUTING.md

@@ -1,3 +1,17 @@
 # Contributing
-In scope: bug fixes, docs, tests. Out of scope: dynamic allocation, HW timer abstraction.
-By contributing, you agree to the MIT License.
+
+## Project Rules
+
+- Keep the public C API compatible with C99.
+- Preserve fixed-capacity, caller-owned storage semantics.
+- Do not add heap allocation, OS or RTOS dependencies, hidden locks, or generated code systems.
+- Keep access serialized per manager unless callers provide external synchronization.
+- Do not weaken runtime tests or remove compile-fail tests.
+- Do not create tags or releases unless explicitly requested.
+
+## Development Notes
+
+- Prefer CMake for package and consumer verification.
+- The checked-in `include/mtimer_config.h` is the source-tree default; build and install trees use a generated resolved configuration header.
+- Timer callbacks return `void`; error propagation must happen through caller-managed state.
+- `longjmp` out of a callback is unsupported and may leave the active-tick guard set.

README.md

@@ -1,97 +1,107 @@
-# microtimer
+# microtimer
 
 [![CI](https://github.com/Vanderhell/microtimer/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/Vanderhell/microtimer/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![C Standard](https://img.shields.io/badge/C-C99-blue.svg)](https://en.wikipedia.org/wiki/C99)
 
-Software timer manager for embedded systems.
+`microtimer` is a fixed-capacity software timer manager for C99 projects.
 
-C99 | Zero dependencies | Zero allocations | Oneshot + Periodic | Portable
+It targets serialized access to one manager from one execution context by default. It does not provide heap allocation, hidden locks, persistence, or general ISR/thread safety.
 
-## Why microtimer?
+## Support Scope
 
-Embedded main loops often contain repeated timing checks:
+- C99 and C11 consumers
+- C++ header consumption
+- GCC, Clang, and MSVC builds
+- Main-loop usage
+- ISR-owned usage with strict limits
+- External synchronization around shared access
+- ARM Cortex-M compile-only verification
+- CMake `find_package()` and `add_subdirectory()` consumers
+
+## Quick Start
 
 ```c
-if (now - last_blink > 500) { toggle_led(); last_blink = now; }
-if (now - last_send > 5000) { send_telemetry(); last_send = now; }
-if (now - last_check > 1000) { check_sensors(); last_check = now; }
-```
+#include "mtimer.h"
 
-`microtimer` replaces this with registered timers and a single tick path:
+static uint32_t app_clock_ms(void) { return platform_millis(); }
 
-```c
-mtimer_create(&tm, "blink",   500,  MTIMER_PERIODIC, on_blink, NULL);
-mtimer_create(&tm, "send",    5000, MTIMER_PERIODIC, on_send, NULL);
-mtimer_create(&tm, "timeout", 3000, MTIMER_ONESHOT,  on_timeout, NULL);
+static void blink_cb(uint8_t id, void *ctx)
+{
+    (void)id;
+    *(volatile int *)ctx = 1;
+}
 
-while (1) {
-    mtimer_tick(&tm);
+int main(void)
+{
+    mtimer_t tm;
+    volatile int blink_due = 0;
+    int timer_id;
+
+    if (mtimer_init(&tm, app_clock_ms) != MTIMER_OK) {
+        return 1;
+    }
+
+    timer_id = mtimer_create(&tm, "blink", 500u, MTIMER_PERIODIC, blink_cb, (void *)&blink_due);
+    if (timer_id < 0) {
+        return 1;
+    }
+
+    if (mtimer_start(&tm, (uint8_t)timer_id) != MTIMER_OK) {
+        return 1;
+    }
+
+    for (;;) {
+        int tick_rc = mtimer_tick(&tm);
+        if (tick_rc < 0) {
+            return 1;
+        }
+        if (blink_due) {
+            blink_due = 0;
+            toggle_led();
+        }
+    }
 }
 ```
 
-## Features
+## Key Contracts
 
-- Oneshot timers that auto-stop after firing.
-- Periodic timers with drift correction.
-- Pause/resume with remaining-time preservation.
-- Dynamic interval changes at runtime.
-- Slot reuse through destroy/create.
-- Named timer lookup for diagnostics and shell commands.
-- Per-timer and global fire counters.
+- Clock units are milliseconds on an unsigned 32-bit modulo counter.
+- Natural `uint32_t` wraparound is supported if the clock is not reset while timers are active.
+- `mtimer_tick()` fires each running timer at most once per successful call.
+- Missed periodic intervals are skipped without callback bursts; phase is retained when only one interval is due.
+- Timer names are optional and caller-owned. Non-`NULL` names must remain valid, immutable, and unique per manager.
+- Timer IDs are slot indexes. Destroying a timer invalidates its ID, and later creates may reuse that slot.
+- Same-manager mutation during callbacks returns `MTIMER_ERR_BUSY`.
 
-## Build and Test
+## Build
 
-Requirements:
-- C99 compiler (`gcc` or `clang`)
-- `make`
-
-Run tests:
+### CMake
 
 ```bash
-# clone microtest next to this repository root
-# expected path: ../microtest/include
-make -C tests
+cmake -S . -B build -DMICROTIMER_BUILD_TESTS=ON
+cmake --build build
+ctest --test-dir build --output-on-failure
 ```
 
-## Public API
-
-Key functions:
-- `mtimer_init`
-- `mtimer_create`, `mtimer_destroy`
-- `mtimer_start`, `mtimer_stop`, `mtimer_pause`, `mtimer_resume`
-- `mtimer_set_interval`
-- `mtimer_tick`
-- `mtimer_count`, `mtimer_find`, `mtimer_remaining`
-
-See [`include/mtimer.h`](include/mtimer.h) for full API details.
-
-## Repository Layout
+### Make
 
-- `include/mtimer.h` - public API
-- `src/mtimer.c` - implementation
-- `tests/test_all.c` - unit tests
-- `docs/DESIGN.md` - design rationale
-
-## Ecosystem
-
-- [microhealth](https://github.com/Vanderhell/microhealth)
-- [microwdt](https://github.com/Vanderhell/microwdt)
-- [microres](https://github.com/Vanderhell/microres)
-- [microsh](https://github.com/Vanderhell/microsh)
-
-## Configuration
-
-- `MTIMER_MAX_TIMERS` (default: `8`)
-
-## Contributing
-
-See [CONTRIBUTING.md](CONTRIBUTING.md).
+```bash
+make
+```
 
-## Changelog
+Caller-provided `CC`, `CPPFLAGS`, `CFLAGS`, and `LDFLAGS` are honored by the Makefiles.
 
-See [CHANGELOG.md](CHANGELOG.md).
+## Documentation
 
-## License
+- [API reference](docs/API_REFERENCE.md)
+- [Cookbook](docs/COOKBOOK.md)
+- [Design notes](docs/DESIGN.md)
+- [Issues and troubleshooting](docs/ISSUES.md)
+- [Porting guide](docs/PORTING_GUIDE.md)
+- [Verification status](docs/VERIFICATION.md)
+- [Contributing](CONTRIBUTING.md)
+- [Security reporting](SECURITY.md)
+- [Changelog](CHANGELOG.md)
 
-MIT - see [LICENSE](LICENSE).
+Releases are tag-driven through `.github/workflows/release.yml` and are only published from pushed `v*` tags.

SECURITY.md

@@ -0,0 +1,5 @@
+# Security Policy
+
+Report suspected vulnerabilities privately through the repository's security contact path or a private maintainer channel before public disclosure.
+
+This project has no built-in persistence, privilege boundaries, or sandboxing. Security-sensitive integrations must validate their own callback, clock, and synchronization assumptions.

docs/API_REFERENCE.md

@@ -0,0 +1,60 @@
+# API Reference
+
+## Initialization
+
+- `mtimer_init(mtimer_t *tm, mtimer_clock_fn clock)`
+  Initializes a manager using the caller-visible `sizeof(*tm)`.
+- `mtimer_init_sized(mtimer_t *tm, size_t tm_size, mtimer_clock_fn clock)`
+  Returns `MTIMER_ERR_ABI` when the caller and library disagree on manager size or resolved configuration.
+
+## Creation and Lifetime
+
+- `mtimer_create(...)`
+  Returns a non-negative slot index on success or a negative `mtimer_err_t` on failure.
+- `mtimer_destroy(mtimer_t *tm, uint8_t id)`
+  Invalidates the slot index immediately. Later creates may reuse the same slot.
+
+`name == NULL` creates an unnamed timer. Non-`NULL` names are caller-owned, must remain valid and immutable for the timer lifetime, and must be unique within the manager.
+
+## Control
+
+- `mtimer_start()`
+  Fully restarts a timer from the current clock value.
+- `mtimer_stop()`
+  Stops the timer and clears paused bookkeeping relevance.
+- `mtimer_pause()`
+  Valid only from `MTIMER_RUNNING`. Already-due timers store `remaining_ms == 0`.
+- `mtimer_resume()`
+  Valid only from `MTIMER_PAUSED`. Zero remaining time becomes eligible on the next tick.
+- `mtimer_set_interval()`
+  Rejects zero. Running timers restart from the current clock. Paused timers remain paused and adopt the full new interval as remaining time. Stopped timers keep the new interval and remain stopped.
+
+## Tick
+
+- `mtimer_tick(mtimer_t *tm)`
+  Returns the number of timers fired on success, or a negative `mtimer_err_t` such as `MTIMER_ERR_NULL`, `MTIMER_ERR_INVALID`, or `MTIMER_ERR_BUSY`.
+
+Each successful tick captures a single `now` value, processes timers in ascending slot order, and fires each timer at most once.
+
+## Queries
+
+- `mtimer_get_count()`
+- `mtimer_at()`
+- `mtimer_find()`
+- `mtimer_get_state()`
+- `mtimer_get_remaining()`
+- `mtimer_get_fire_count()`
+- `mtimer_get_total_fires()`
+- `mtimer_get_total_ticks()`
+
+All query functions report failure explicitly instead of returning values that could be mistaken for valid state.
+
+## Error Codes
+
+- `MTIMER_OK`
+- `MTIMER_ERR_NULL`
+- `MTIMER_ERR_FULL`
+- `MTIMER_ERR_NOT_FOUND`
+- `MTIMER_ERR_INVALID`
+- `MTIMER_ERR_BUSY`
+- `MTIMER_ERR_ABI`

docs/COOKBOOK.md

@@ -0,0 +1,113 @@
+# Cookbook
+
+## 1. Minimal initialization
+
+```c
+mtimer_t tm;
+if (mtimer_init(&tm, platform_millis) != MTIMER_OK) {
+    return;
+}
+```
+
+## 2. Complete quick start
+
+```c
+static volatile int timeout_due = 0;
+
+static void timeout_cb(uint8_t id, void *ctx)
+{
+    (void)id;
+    *(volatile int *)ctx = 1;
+}
+
+void app_loop(void)
+{
+    mtimer_t tm;
+    int timer_id;
+
+    if (mtimer_init(&tm, platform_millis) != MTIMER_OK) {
+        return;
+    }
+    timer_id = mtimer_create(&tm, "timeout", 3000u, MTIMER_ONESHOT, timeout_cb, (void *)&timeout_due);
+    if (timer_id < 0) {
+        return;
+    }
+    if (mtimer_start(&tm, (uint8_t)timer_id) != MTIMER_OK) {
+        return;
+    }
+    for (;;) {
+        int tick_rc = mtimer_tick(&tm);
+        if (tick_rc < 0) {
+            return;
+        }
+        if (timeout_due) {
+            timeout_due = 0;
+            handle_timeout();
+        }
+    }
+}
+```
+
+## 3. Oneshot timer
+
+Create with `MTIMER_ONESHOT`, then call `mtimer_start()`. It stops itself before the callback runs.
+
+## 4. Periodic timer
+
+Create with `MTIMER_PERIODIC`. Missed periods are skipped without callback bursts.
+
+## 5. Pause and resume
+
+Pause only from `MTIMER_RUNNING`, resume only from `MTIMER_PAUSED`. If a timer was already due when paused, resuming makes it eligible on the next tick.
+
+## 6. Change interval
+
+Running timers restart from the current clock. Paused timers keep the paused state and reset remaining time to the full new interval.
+
+## 7. Named timer lookup
+
+Use `mtimer_find(&tm, "name")`. Duplicate non-`NULL` names are rejected.
+
+## 8. Multiple managers
+
+Independent managers may be ticked independently because the active-tick guard is per manager.
+
+## 9. C++ consumer
+
+The public header is valid in C++ translation units. See `tests/consumers/cpp_consumer.cpp`.
+
+## 10. Installed CMake package consumer
+
+See `tests/find_package_consumer/` for a `find_package(microtimer CONFIG REQUIRED)` fixture that links `microtimer::microtimer`.
+
+## 11. add_subdirectory consumer
+
+See `tests/add_subdirectory_consumer/` for an `add_subdirectory()` fixture.
+
+## 12. Main-loop integration
+
+Use `mtimer_tick()` from one serialized loop or task that owns the manager.
+
+## 13. ISR-limited usage
+
+Only use from an ISR when the manager is ISR-owned or externally protected, the clock function is ISR-safe, and callbacks stay bounded and non-blocking.
+
+## 14. External locking
+
+Protect every API call with the same mutex or critical section when sharing one manager across execution contexts.
+
+## 15. Counter policy
+
+Per-timer and global counters use unsigned modulo wrap at `UINT32_MAX`.
+
+## 16. Clock wraparound
+
+Unsigned `uint32_t` wraparound is supported, but elapsed time longer than one complete counter cycle is not distinguishable.
+
+## 17. Context and name lifetime
+
+Callback context pointers and non-`NULL` timer names are caller-owned and must remain valid for the timer lifetime.
+
+## 18. Set-flag callback pattern
+
+Prefer callbacks that set flags or enqueue lightweight work, then act after `mtimer_tick()` returns.