Refactor

CMakeLists.txt

@@ -38,6 +38,19 @@ include("${CMAKE_CURRENT_SOURCE_DIR}/osal_config.cmake")
 
 set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -Wall -Wextra -Werror=implicit-function-declaration")
 
+# Extra warnings for the library sources only (verified clean on gcc and
+# clang). Not applied to tests/examples since cmocka/test code is outside
+# our control for some of these (e.g. -Wpedantic on generated test macros).
+set(DMOSAL_EXTRA_WARNING_FLAGS
+  -Wshadow
+  -Wconversion
+  -Wpedantic
+  -Wcast-align
+  -Wpointer-arith
+  -Wstrict-prototypes
+  -Wmissing-prototypes
+)
+
 # Sanitizers / coverage — one flag string shared between compile and link.
 set(_dm_extra "")
 if(DMOSAL_ENABLE_ASAN)
@@ -104,6 +117,7 @@ else()
   add_library(dmosal STATIC ${osal_SRC})
 endif()
 target_link_libraries(dmosal ${CMAKE_THREAD_LIBS_INIT} rt)
+target_compile_options(dmosal PRIVATE ${DMOSAL_EXTRA_WARNING_FLAGS})
 set_target_properties(dmosal PROPERTIES
   VERSION ${DMOSAL_VERSION} SOVERSION ${DMOSAL_MAJOR_VERSION})
 
@@ -222,11 +236,18 @@ add_subdirectory(examples EXCLUDE_FROM_ALL)
 # doc
 ##############################################################################
 add_custom_target(doc)
-find_package(Doxygen)
+find_package(Doxygen OPTIONAL_COMPONENTS dot)
 if(NOT DOXYGEN_FOUND)
   message(WARNING "Doxygen is not found!")
 else()
-  configure_file(doxygen.cfg.in ${PROJECT_BINARY_DIR}/Doxyfile @ONLY)
+  if(DOXYGEN_DOT_FOUND)
+    set(DMOSAL_DOXYGEN_HAVE_DOT YES)
+  else()
+    set(DMOSAL_DOXYGEN_HAVE_DOT NO)
+  endif()
+  set(DMOSAL_INCLUDE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/include/dmosal")
+  set(DMOSAL_DOCS_PATH "${CMAKE_CURRENT_SOURCE_DIR}/docs")
+  configure_file(docs/doxygen.cfg.in ${PROJECT_BINARY_DIR}/Doxyfile @ONLY)
   add_custom_target(doxygen-doc
     COMMAND ${DOXYGEN_EXECUTABLE} ${PROJECT_BINARY_DIR}/Doxyfile
     SOURCES ${PROJECT_BINARY_DIR}/Doxyfile)

README.md

@@ -1,4 +1,4 @@
-# OSAL - OS Abstraction Layer for Embedded Systems
+# dmosal — OS Abstraction Layer
 
 [![CI](https://github.com/drymon/osal/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/drymon/osal/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/gh/drymon/osal/branch/main/graph/badge.svg)](https://codecov.io/gh/drymon/osal)
@@ -7,7 +7,13 @@
 
 A small, portable embedded C abstraction layer providing deterministic/bounded
 resource management and consistent concurrency, timing, and communication
-semantics across POSIX and RTOS platforms. Licensed BSD-2-Clause.
+semantics across POSIX and RTOS platforms.
+
+Everything (tasks, mutexes, semaphores, queues, timers, ...) is allocated
+statically up front through a central resource manager, so there's no malloc
+on the hot path and the worst-case memory usage is known ahead of time. A
+POSIX/Linux backend is included; other targets can be added behind the same
+API without breaking existing callers.
 
 ```
    +-------------------------------+
@@ -27,42 +33,56 @@ semantics across POSIX and RTOS platforms. Licensed BSD-2-Clause.
    +-------------------------------+
 ```
 
-## Build & test
+## Getting started
+
+You'll need `cmake`, `libcmocka-dev`, and `doxygen`:
+
+```
+sudo apt install cmake libcmocka-dev doxygen
+```
+
+Then build the library, run the tests, and check out the examples:
+
+```
+just check          # configure + build + run tests
+just build           # build the examples target
+```
 
-Requires `cmake`, `libcmocka-dev`, `doxygen` (`sudo apt install cmake
-libcmocka-dev doxygen` on Ubuntu/Debian).
+If you'd rather not install a toolchain locally, there's a pinned
+[`Dockerfile`](Dockerfile):
 
 ```
-$ just check          # configure + build + run tests
+docker build -t dmosal-dev .
+docker run --rm -v "$PWD":/workspace -w /workspace dmosal-dev just check
 ```
 
-No [`just`](https://github.com/casey/just)? See the [`justfile`](justfile)
-for the equivalent raw `cmake`/`ctest` commands, or use the pinned
-[`Dockerfile`](Dockerfile) for a reproducible toolchain
-(`docker build -t dmosal-dev . && docker run --rm -v "$PWD":/workspace -w
-/workspace dmosal-dev just check`).
+Don't have [`just`](https://github.com/casey/just) installed? Check the
+[`justfile`](justfile) — every recipe there is just a couple of plain
+`cmake`/`ctest` commands you can run directly.
 
-Other recipes: `just check-valgrind`, `just check-asan`, `just check-tsan`,
-`just check-coverage`, `just doc`, `just format`, `just tidy` — run `just
---list` for the full set.
+There are a few more recipes worth knowing about: `just check-valgrind`,
+`just check-asan`, `just check-tsan`, `just check-coverage`, `just doc`,
+`just format`, `just tidy`. Run `just --list` to see everything.
 
-Resource limits (max tasks, queues, etc.) are configured at CMake time; see
-[osal_config.cmake](osal_config.cmake).
+Resource limits (how many tasks, queues, etc. you get) are set at CMake
+configure time — see [osal_config.cmake](osal_config.cmake).
 
 ## Examples
 
-See [examples/](examples/) for sample programs. Build with `just build`
+Sample programs live in [examples/](examples/). Build them with `just build`
 (CMake target `examples`).
 
 ## Documentation
 
-- API reference (Doxygen): `just doc`, output in `build/doc/html/`.
-- Design/behavioral docs: [docs/](docs/README.md) (architecture, API spec,
-  resource lifetime, thread-safety, porting guide).
+- API reference (Doxygen): run `just doc`, output ends up in
+  `build/doc/html/`.
+- Design docs: [docs/](docs/README.md) — architecture, API spec, resource
+  lifetime, thread-safety, porting guide.
 
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md).
+Bug reports, patches, ideas — all welcome. See [CONTRIBUTING.md](CONTRIBUTING.md)
+for how to build, test, and keep the style consistent.
 
 ## License
 

docs/doxygen.cfg.in

@@ -5,7 +5,7 @@
 #---------------------------------------------------------------------------
 DOXYFILE_ENCODING      = UTF-8
 PROJECT_NAME           = "OS Abstract Layer"
-PROJECT_NUMBER         =
+PROJECT_NUMBER         = @DMOSAL_VERSION@
 PROJECT_BRIEF          = "OS Abstract Layer Library API Guide"
 PROJECT_LOGO           =
 OUTPUT_DIRECTORY       = @PROJECT_BINARY_DIR@/doc
@@ -95,13 +95,13 @@ WARNINGS               = YES
 WARN_IF_UNDOCUMENTED   = YES
 WARN_IF_DOC_ERROR      = YES
 WARN_NO_PARAMDOC       = NO
-WARN_AS_ERROR          = NO
+WARN_AS_ERROR          = YES
 WARN_FORMAT            = "$file:$line: $text"
 WARN_LOGFILE           =
 #---------------------------------------------------------------------------
 # Configuration options related to the input files
 #---------------------------------------------------------------------------
-INPUT                  = @DMOSAL_INCLUDE_PATH@
+INPUT                  = @DMOSAL_INCLUDE_PATH@ @DMOSAL_DOCS_PATH@/mainpage.dox
 INPUT_ENCODING         = UTF-8
 FILE_PATTERNS          =
 RECURSIVE              = NO
@@ -134,7 +134,6 @@ VERBATIM_HEADERS       = YES
 # Configuration options related to the alphabetical class index
 #---------------------------------------------------------------------------
 ALPHABETICAL_INDEX     = YES
-COLS_IN_ALPHA_INDEX    = 5
 IGNORE_PREFIX          =
 #---------------------------------------------------------------------------
 # Configuration options related to the HTML output
@@ -150,7 +149,6 @@ HTML_EXTRA_FILES       =
 HTML_COLORSTYLE_HUE    = 220
 HTML_COLORSTYLE_SAT    = 100
 HTML_COLORSTYLE_GAMMA  = 80
-HTML_TIMESTAMP         = NO
 HTML_DYNAMIC_SECTIONS  = NO
 HTML_INDEX_NUM_ENTRIES = 100
 GENERATE_DOCSET        = NO
@@ -176,12 +174,11 @@ QHG_LOCATION           =
 GENERATE_ECLIPSEHELP   = NO
 ECLIPSE_DOC_ID         = org.doxygen.Project
 DISABLE_INDEX          = NO
-GENERATE_TREEVIEW      = NO
+GENERATE_TREEVIEW      = YES
 ENUM_VALUES_PER_LINE   = 4
 TREEVIEW_WIDTH         = 250
 EXT_LINKS_IN_WINDOW    = NO
 FORMULA_FONTSIZE       = 10
-FORMULA_TRANSPARENT    = YES
 USE_MATHJAX            = NO
 MATHJAX_FORMAT         = HTML-CSS
 MATHJAX_RELPATH        = http://cdn.mathjax.org/mathjax/latest
@@ -212,9 +209,7 @@ PDF_HYPERLINKS         = YES
 USE_PDFLATEX           = YES
 LATEX_BATCHMODE        = NO
 LATEX_HIDE_INDICES     = NO
-LATEX_SOURCE_CODE      = NO
 LATEX_BIB_STYLE        = plain
-LATEX_TIMESTAMP        = NO
 #---------------------------------------------------------------------------
 # Configuration options related to the RTF output
 #---------------------------------------------------------------------------
@@ -224,7 +219,6 @@ COMPACT_RTF            = NO
 RTF_HYPERLINKS         = NO
 RTF_STYLESHEET_FILE    =
 RTF_EXTENSIONS_FILE    =
-RTF_SOURCE_CODE        = NO
 #---------------------------------------------------------------------------
 # Configuration options related to the man page output
 #---------------------------------------------------------------------------
@@ -244,7 +238,6 @@ XML_PROGRAMLISTING     = YES
 #---------------------------------------------------------------------------
 GENERATE_DOCBOOK       = NO
 DOCBOOK_OUTPUT         = docbook
-DOCBOOK_PROGRAMLISTING = NO
 #---------------------------------------------------------------------------
 # Configuration options for the AutoGen Definitions output
 #---------------------------------------------------------------------------
@@ -279,13 +272,10 @@ EXTERNAL_PAGES         = YES
 #---------------------------------------------------------------------------
 # Configuration options related to the dot tool
 #---------------------------------------------------------------------------
-CLASS_DIAGRAMS         = YES
 DIA_PATH               =
 HIDE_UNDOC_RELATIONS   = YES
-HAVE_DOT               = YES
+HAVE_DOT               = @DMOSAL_DOXYGEN_HAVE_DOT@
 DOT_NUM_THREADS        = 0
-DOT_FONTNAME           = Helvetica
-DOT_FONTSIZE           = 10
 DOT_FONTPATH           =
 CLASS_GRAPH            = YES
 COLLABORATION_GRAPH    = YES
@@ -303,14 +293,13 @@ DOT_IMAGE_FORMAT       = png
 INTERACTIVE_SVG        = NO
 DOT_PATH               =
 DOTFILE_DIRS           =
-MSCFILE_DIRS           = doxywizard
+MSCFILE_DIRS           =
 DIAFILE_DIRS           =
 PLANTUML_JAR_PATH      =
 PLANTUML_CFG_FILE      =
 PLANTUML_INCLUDE_PATH  =
 DOT_GRAPH_MAX_NODES    = 50
 MAX_DOT_GRAPH_DEPTH    = 0
-DOT_TRANSPARENT        = NO
 DOT_MULTI_TARGETS      = NO
 GENERATE_LEGEND        = YES
 DOT_CLEANUP            = YES

docs/mainpage.dox

@@ -0,0 +1,21 @@
+/**
+ * @mainpage dmosal
+ *
+ * A small, portable embedded C abstraction layer providing deterministic/bounded
+ * resource management and consistent concurrency, timing, and communication
+ * semantics across POSIX and RTOS platforms.
+ *
+ * This page indexes the API reference below. For narrative documentation, see
+ * the Markdown docs in `docs/` (also linked from the project README):
+ *
+ * - architecture.md — layered design, subsystem overview, resource-manager
+ *   pattern, callback threading model, backend model.
+ * - thread-safety.md — per-API table classifying every public call as
+ *   thread-safe, single-owner, or init-thread-only.
+ * - lifetime.md — init/deinit ordering, resource ownership, when it is
+ *   safe to use/release a resource.
+ * - api-spec.md — behavioral specification per subsystem: functions,
+ *   states, error codes, invariants.
+ * - porting.md — how to add a new backend (e.g. an RTOS or bare-metal
+ *   target).
+ */