{"id":23189077,"url":"https://github.com/kubasejdak-org/osal","last_synced_at":"2026-05-05T23:32:39.517Z","repository":{"id":248432604,"uuid":"828646692","full_name":"kubasejdak-org/osal","owner":"kubasejdak-org","description":"Operating System Abstraction Layer for C/C++","archived":false,"fork":false,"pushed_at":"2026-05-02T11:56:40.000Z","size":3654,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-02T12:23:10.320Z","etag":null,"topics":["arm","baremetal","c","cpp","embedded","freertos","linux","osal"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kubasejdak-org.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-07-14T19:11:41.000Z","updated_at":"2026-05-02T11:50:19.000Z","dependencies_parsed_at":"2024-07-14T21:53:32.449Z","dependency_job_id":null,"html_url":"https://github.com/kubasejdak-org/osal","commit_stats":null,"previous_names":["kubasejdak-org/osal"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/kubasejdak-org/osal","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubasejdak-org%2Fosal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubasejdak-org%2Fosal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubasejdak-org%2Fosal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubasejdak-org%2Fosal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kubasejdak-org","download_url":"https://codeload.github.com/kubasejdak-org/osal/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubasejdak-org%2Fosal/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32672635,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-05T11:29:49.557Z","status":"ssl_error","status_checked_at":"2026-05-05T11:29:48.587Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["arm","baremetal","c","cpp","embedded","freertos","linux","osal"],"created_at":"2024-12-18T11:17:11.922Z","updated_at":"2026-05-05T23:32:39.512Z","avatar_url":"https://github.com/kubasejdak-org.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# osal\n\nOS abstraction layer providing unified C and C++ APIs for common OS and RTOS primitives. Architecture is organized\naround a portable C layer with an optional C++ wrapper for RAII and object-oriented use.\n\nMain features:\n\n- **dual-layer API**: thin C API (`osal::c`) for direct use, and C++ RAII wrappers (`osal::cpp`) built on top of it,\n- **ISR-safe variants**: dedicated `*Isr()` operations for mutex and semaphore use from interrupt context,\n- **threads**: create, join, yield, and prioritize with a 5-level priority system,\n- **synchronization**: mutexes (recursive and non-recursive), semaphores, and scoped locks — all with optional timeouts,\n- **time and sleep**: timestamp functions, time unit conversions, and `std::chrono`-based sleep.\n\n## Supported Platforms\n\n| `OSAL_PLATFORM` | Backend details                     |\n| --------------- | ----------------------------------- |\n| `linux`         | Linux backend using POSIX API       |\n| `freertos`      | FreeRTOS backend using FreeRTOS API |\n\nBackend selection is controlled at build time with `OSAL_PLATFORM`. The architecture is designed to accommodate\nadditional backends over time.\n\n\u003e [!IMPORTANT]\n\u003e\n\u003e `osal` requires target project to use CMake.\n\n## Architecture\n\n### Components\n\n- **`osal`** — C API layer and platform backends. Exposes primitives for:\n    - threads,\n    - mutexes,\n    - semaphores,\n    - sleep,\n    - time/timestamp utilities.\n\n- **`cpp`** — C++ wrapper layer built on top of the C API. Adds RAII and object-oriented abstractions.\n\nThe diagram below illustrates the layering. The C++ API is a thin wrapper over the C API. The C API delegates all\nplatform-specific work to the selected backend:\n\n```mermaid\n---\n  config:\n    class:\n      hideEmptyMembersBox: true\n---\n\nclassDiagram\n    class Thread\n    class OsalThread\n    class ThreadImpl\n\n    class LinuxThreadImpl[\"POSIX API\"]\n    class FreeRTOSThreadImpl[\"FreeRTOS API\"]\n\n    Thread *-- OsalThread\n    OsalThread *-- ThreadImpl\n    ThreadImpl ..\u003e LinuxThreadImpl : Linux\n    ThreadImpl ..\u003e FreeRTOSThreadImpl : FreeRTOS\n\n    note for Thread \"C++\"\n    note for OsalThread \"C\"\n```\n\n### Technologies\n\n- **Language**: C++23, C17\n- **Build System**: CMake (minimum version 3.28)\n- **Package Manager**: Conan (test dependencies only)\n- **Static Analysis**: clang-format, clang-tidy\n- **CI/CD**: GitHub Actions\n\n### Repository Structure\n\n`osal` follows the standard `kubasejdak-org` repository layout for C++ libraries:\n\n```bash\nosal/\n├── cmake/                              # CMake build system\n│   ├── compilation-flags.cmake         # Internal compilation flags\n│   ├── components.cmake                # Helper component loader (FetchContent helper)\n│   ├── modules/                        # CMake Find*.cmake modules for dependencies\n│   └── presets/                        # Internal preset helpers\n├── lib/                                # Core components\n│   ├── osal/                           # C API (osal::c) and platform backends\n│   │   ├── common/                     # Platform-independent implementation (osal::common)\n│   │   ├── linux/                      # Linux backend (pthread)\n│   │   └── freertos/                   # FreeRTOS backend\n│   └── cpp/                            # C++ wrapper API (osal::cpp)\n├── tests/                              # Test suite (Catch2)\n├── tools/                              # Development tools and scripts\n├── .devcontainer/                      # Dev container configuration\n├── .github/workflows/                  # GitHub Actions workflows\n└── CMakePresets.json                   # Development CMake presets\n```\n\n## Usage\n\n### CMake Integration\n\nCreate a `Findosal.cmake` module (typically in cmake/modules directory):\n\n```cmake\ninclude(FetchContent)\nFetchContent_Declare(osal\n    GIT_REPOSITORY  https://github.com/kubasejdak-org/osal.git\n    GIT_TAG         \u003ccommit-sha|branch|tag\u003e\n)\n\nFetchContent_MakeAvailable(osal)\ninclude(${osal_SOURCE_DIR}/cmake/components.cmake)\n```\n\n\u003e [!NOTE]\n\u003e\n\u003e `GIT_TAG` accepts any ref recognized by CMake FetchContent: a full commit SHA, a branch name, or a tag.\n\nThen add the module directory to the CMake search path and request the library:\n\n```cmake\nlist(APPEND CMAKE_MODULE_PATH \"${CMAKE_CURRENT_SOURCE_DIR}/cmake/modules\")\n\nfind_package(osal)\n```\n\n### Configuration\n\nControl platform selection via CMake variables (typically in `CMakePresets.json`):\n\n| Variable        | Purpose                             | Values              |\n| --------------- | ----------------------------------- | ------------------- |\n| `OSAL_PLATFORM` | Selects the platform backend to use | `linux`, `freertos` |\n\nSet it in your preset or pass it directly:\n\n```bash\ncmake -DOSAL_PLATFORM=linux --preset linux-native-gcc-debug . -B out/build/linux-native-gcc-debug\n```\n\n\u003e [!IMPORTANT]\n\u003e\n\u003e `OSAL_PLATFORM` must be defined before `osal::c` is built. The build will fail with an explicit error if it is\n\u003e missing.\n\n### Linking\n\nLink against `osal::cpp` for the C++ API (pulls in `osal::c` transitively) or against `osal::c` directly when C++\nwrappers are not needed:\n\n```cmake\ntarget_link_libraries(my-app\n    PRIVATE\n        osal::cpp   # C++ RAII API, osal::c is linked transitively\n)\n```\n\n```cmake\ntarget_link_libraries(my-c-app\n    PRIVATE\n        osal::c     # C API only\n)\n```\n\n### API Overview\n\n`osal::cpp` is an optional convenience layer built on top of `osal::c`. Projects that prefer the plain C interface can\nlink `osal::c` directly.\n\n#### Threads\n\n**C++**:\n\n```cpp\n#include \u003cosal/Thread.hpp\u003e\n\nosal::NormalPrioThread\u003c\u003e worker(\"worker-thread\", [] {\n    // thread body\n});\n\nworker.join();\n```\n\n**C**:\n\n```c\n#include \u003cosal/Thread.h\u003e\n\nstatic void worker(void* arg)\n{\n    // thread body\n}\n\nstruct OsalThread thread;\nstruct OsalThreadConfig config = {Normal, cOsalThreadDefaultStackSize, NULL};\n\nosalThreadCreateEx(\u0026thread, config, worker, NULL, \"worker-thread\");\nosalThreadJoin(\u0026thread);\nosalThreadDestroy(\u0026thread);\n```\n\n#### Mutexes and scoped locks\n\n**C++: RAII with `ScopedLock`**\n\n```cpp\n#include \u003cosal/Mutex.hpp\u003e\n#include \u003cosal/ScopedLock.hpp\u003e\n\nosal::Mutex mutex;\n\n{\n    osal::ScopedLock lock(mutex);\n    if (!lock)\n        return; // failed to acquire\n\n    // critical section\n}   // mutex unlocked automatically on scope exit\n```\n\n**C (manual lock/unlock)**:\n\n```c\n#include \u003cosal/Mutex.h\u003e\n\nstruct OsalMutex mutex;\n\nosalMutexCreate(\u0026mutex, cOsalMutexDefaultType);\nosalMutexLock(\u0026mutex);\n\n// critical section\n\nosalMutexUnlock(\u0026mutex);\nosalMutexDestroy(\u0026mutex);\n```\n\n#### Semaphores\n\n**C++**:\n\n```cpp\n#include \u003cosal/Semaphore.hpp\u003e\n\nosal::Semaphore sem(0);\n\nsem.signal();   // producer\nsem.wait();     // consumer (blocks until signalled)\n```\n\n**C**:\n\n```c\n#include \u003cosal/Semaphore.h\u003e\n\nstruct OsalSemaphore sem;\n\nosalSemaphoreCreate(\u0026sem, 0);\nosalSemaphoreSignal(\u0026sem); // producer\nosalSemaphoreWait(\u0026sem);   // consumer (blocks until signalled)\nosalSemaphoreDestroy(\u0026sem);\n```\n\n#### Sleep\n\n**C++**:\n\n```cpp\n#include \u003cosal/sleep.hpp\u003e\nusing namespace std::chrono_literals;\n\nosal::sleep(100ms);\n```\n\n**C**:\n\n```c\n#include \u003cosal/sleep.h\u003e\n\nosalSleepMs(100);\n```\n\n## Development\n\n\u003e [!NOTE]\n\u003e\n\u003e This section is relevant when working on `osal` itself in standalone mode. The presets defined here can also serve as\n\u003e a reference for dependent projects.\n\n### Commands\n\n- **Configure**: `cmake --preset \u003cpreset-name\u003e . -B out/build/\u003cpreset-name\u003e`\n- **Build**: `cmake --build out/build/\u003cpreset-name\u003e --parallel`\n- **Run tests**: `cd out/build/\u003cpreset-name\u003e/bin; ./osal-tests`\n- **Reformat code**: `tools/check-clang-format.sh`\n- **Run linter**: `cd out/build/\u003cpreset-name\u003e; ../../../tools/check-clang-tidy.sh`\n    - Must be launched with a clang preset (usually inside the clang dev container)\n\n### Available CMake Presets\n\n- **Native Linux**:\n    - **System dependencies**: `linux-native-{gcc,clang}-{debug,release}`\n    - **Conan dependencies**: `linux-native-conan-{gcc,clang}-{debug,release}`\n- **Cross-compilation**:\n    - **Generic ARM64**: `linux-arm64-conan-{gcc,clang}-{debug,release}`\n    - **Yocto (via SDK)**: `yocto-sdk-{gcc,clang}-{debug,release}`\n    - **FreeRTOS ARMv7 Cortex-M4**: `freertos-armv7-m4-conan-gcc-{debug,release}`\n- **Sanitizers**: `*-{asan,lsan,tsan,ubsan}` variants (Linux native and Conan presets)\n\n\u003e [!NOTE]\n\u003e\n\u003e For local development use the `linux-native-conan-gcc-debug` preset.\n\n### Code Quality\n\n- **Zero Warning Policy**: All warnings treated as errors (`-Wall -Wextra -Wpedantic -Werror`)\n- **No Exceptions**: C++ code is built with `-fno-exceptions`; errors are reported via `std::error_code`\n- **Code Formatting**: clang-format with project-specific style (120-character line length)\n- **Static Analysis**: clang-tidy configuration enforced in CI\n- **Sanitizers**: Address, leak, thread, and undefined behavior sanitizer presets available\n\n### Important Notes\n\n1. **Component structure**: `osal::c` and `osal::cpp` are separate CMake components in `lib/osal/` and `lib/cpp/`\n   respectively. Public headers live under `include/osal/` within each component directory. Platform-specific internal\n   headers (`ThreadImpl.h`, `MutexImpl.h`, `SemaphoreImpl.h`) are in `lib/osal/\u003cplatform\u003e/include/internal/` and are\n   never included by consumers.\n\n2. **Adding a new platform backend**: Create `lib/osal/\u003cplatform\u003e/` with the same structure as `linux/` or `freertos/`.\n   Implement every function declared in `lib/osal/include/osal/` and provide the three `*Impl.h` headers in\n   `\u003cplatform\u003e/include/internal/`. Pass the new directory name as `OSAL_PLATFORM` to activate it.\n\n3. **Testing**: Tests live in `tests/` and use Catch2 3.13.0 (fetched via Conan). Use a Conan preset to run them. The\n   test binary is named `osal-tests`; on non-UNIX targets an `.bin` image is generated from it instead.\n\n4. **Dependencies**: Conan is used only for test dependencies (Catch2). The runtime library has no external package\n   requirements beyond what the selected backend needs — `pthread` for `linux`, the FreeRTOS kernel for `freertos`.\n\n5. **Error handling**: Every operation returns `std::error_code`. The `OsalError` enum is mapped to an\n   `std::error_category` via `osal::ErrorCategory` (see `lib/cpp/include/osal/Error.hpp`). Exceptions are explicitly\n   disabled at compile time via `-fno-exceptions`.\n\n6. **ISR safety**: Functions suffixed with `Isr()` (e.g. `osalMutexUnlockIsr()`, `osal::Semaphore::signalIsr()`) must\n   only be called from interrupt context. The standard variants must not be called from ISR. Mixing the two is undefined\n   behavior.\n\n7. **Thread priority aliases**: `osal::Thread\u003cPriority, StackSize\u003e` has five convenience aliases defined in\n   `lib/cpp/include/osal/Thread.hpp`: `LowestPrioThread`, `LowPrioThread`, `NormalPrioThread`, `HighPrioThread`, and\n   `HighestPrioThread`. Prefer these over explicitly spelling out the template parameters.\n\n8. **Code style**: Formatting is enforced by `.clang-format` (120-character lines, project-specific brace and spacing\n   rules). Run `tools/check-clang-format.sh` locally before submitting changes. Static analysis is enforced via\n   `.clang-tidy`; run the linter with a clang preset to surface issues before CI.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkubasejdak-org%2Fosal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkubasejdak-org%2Fosal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkubasejdak-org%2Fosal/lists"}