From acb30dc56d75a1f6119d6af4c9a0446dfa48b41b Mon Sep 17 00:00:00 2001
From: Henrik Stickann <4376396-Mithradir@users.noreply.gitlab.com>
Date: Sun, 10 Apr 2022 16:31:32 +0200
Subject: [PATCH] Update README

---
 README.md | 79 ++++++++++++++++++++++++++++++++++++++-----------------
 1 file changed, 55 insertions(+), 24 deletions(-)

diff --git a/README.md b/README.md
index c91d40f..0052a7e 100644
--- a/README.md
+++ b/README.md
@@ -1,40 +1,71 @@
 # CMSIS OS2
 
-Library using cmsis_os2.h functionality for RTOS projects.
+Library using CMSIS-RTOS2 functionality for RTOS projects.
 
-Modules are enabled via defines set in `sta/config.hpp` which must be provided by the application.
+Modules are enabled via defines set in `<sta/config.hpp>` header which must be provided by the application.
 
 
-## System events
+# Interface implementations
+
+The library provides implementations for the following interfaces using CMSIS-RTOS2 functionality:
+* `Mutex`
+* `Signal`
+
+
+# Modules
+
+## System Event
+
+Provides an interface for common system events. 
+
+Configuration:
+* `#define STA_OS2_SYSTEM_EVENT_ENABLE`: Enable module
+* `#define STA_OS2_SYSTEM_EVENT_HANDLE <var_name>`: Override variable name of flag handle (default: systemEventHandle)
 
-Enable: `STA_SYSTEM_EVENT_ENABLE`
 
 Requirements:
-* EventFlag: `systemEvent`
+* RTOS: event flag
 
 
 ## Watchdog
 
-Watchdog task gets woken periodically (every `STA_WATCHDOG_TIMER_PERIOD` ticks) or via `sta::nofityWatchdog(uint32_t)` calls
-and calls `sta::watchdogEventHandler(void *, uint32_t)`. Applications *must* implement `sta::watchdogEventHandler(void *, uint32_t)`.
-
-
-Enable: `STA_WATCHDOG_ENABLE`
-
-Requirements:
-* Task: `watchdog`
-* Timer: `heartbeat`
+The watchdog task waits for signals sent either from the heartbeat timer or manually via `sta::notifyWatchdog`
+and forwards the event flags to the `sta::watchdogEventHandler` function implemented by the application.
 
 Configuration:
-* Heartbeat timer period: `STA_WATCHDOG_TIMER_PERIOD` (defaults to `1000`).
-
-
-## Startup task
-
-Startup task calls `sta::startupTaskExtras(void *)`, starts the watchdog timer if enabled and terminates the thread.
-`sta::startupTaskExtras(void *)` may be overridden by the application.
-
-Enable: `STA_STARTUP_TASK_ENABLE`
+* `#define STA_OS2_WATCHDOG_ENABLE`: Enable module
+* `#define STA_OS2_WATCHDOG_TIMER_PERIOD <period_ticks>`: Set period in ticks of heartbeat timer (default: 1000)
+* `#define STA_OS2_WATCHDOG_TIMER_HANDLE <var_name>`: Override variable name of heartbeat timer handle (default: heartbeatHandle)
+* `#define STA_OS2_WATCHDOG_TIMER_CALLBACK <func_name>`: Override name of heartbeat timer callback function (default: heartbeatCallback)
+* `#define STA_OS2_WATCHDOG_HANDLE <var_name>`: Override variable name of watchdog task handle (default: watchdogHandle)
+* `#define STA_OS2_WATCHDOG_ENTRY_FUNCTION <func_name>`: Override name of watchdog task entry function (default: watchdogTask)
 
 Requirements:
-* Task: `startupTask` (alternative: call manually in freertos.c default task)
+* Uses the `System Event` module
+* RTOS: timer + task
+
+
+## Startup
+
+The entry function for the startup task must be called manually from the default task.
+
+It provides all setup required by the enabled system tasks. If additional initialization is required by the
+application the function `void sta::startupExtras(void *)` declared in `<sta/os2/startup.hpp>` can be implemented.
+
+Configuration:
+* `#define STA_OS2_STARTUP_ENABLE`: Enable module
+* `#define STA_OS2_STARTUP_ENTRY_FUNCTION <func_name>`: Override name of startup task entry function (default: startupTask)
+
+Requirements:
+* Uses the `System Event` module
+* RTOS: task
+
+
+## Easy Config
+
+Simplify configuration of modules. Intended for use in `<sta/config.hpp>`.
+
+Configuration:
+* `#define STA_OS2_SYSTEM_TASKS_ENABLE`: Enable all modules required for system tasks
+* `#define STA_OS2_WATCHDOG_TIMER_NAME <name>`: Override handle and callback name for watchdog timer
+* `#define STA_OS2_WATCHDOG_NAME <name>`: Override handle and entry function name for watchdog task