{"id":50856110,"url":"https://github.com/project-chip/poski","last_synced_at":"2026-06-14T18:38:40.532Z","repository":{"id":357254843,"uuid":"460946801","full_name":"project-chip/poski","owner":"project-chip","description":"OS Abstraction Layer","archived":false,"fork":false,"pushed_at":"2026-06-06T23:46:24.000Z","size":125,"stargazers_count":2,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-06-14T18:38:26.271Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/project-chip.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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":"2022-02-18T17:33:42.000Z","updated_at":"2026-06-06T23:46:28.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/project-chip/poski","commit_stats":null,"previous_names":["project-chip/poski","project-chip/osal"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/project-chip/poski","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/project-chip%2Fposki","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/project-chip%2Fposki/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/project-chip%2Fposki/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/project-chip%2Fposki/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/project-chip","download_url":"https://codeload.github.com/project-chip/poski/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/project-chip%2Fposki/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34333806,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-14T02:00:07.365Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":[],"created_at":"2026-06-14T18:38:39.708Z","updated_at":"2026-06-14T18:38:40.527Z","avatar_url":"https://github.com/project-chip.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CHIP Operating System Abstraction Layer (OSAL)\n\nPOSKI (Portable Operating System Kernel Interface) is an OSAL used within Project CHIP.\nPOSKI acts as a 'POSIX for embedded,' providing a thin abstraction layer that ensures \nseamless application portability across different RTOS targets.\n\nBy bridging kernels like FreeRTOS, Zephyr, and POSIX, POSKI empowers a single codebase\nto traverse the entire lifecycle: host-based simulation, bring-up testing, and the\nfinal production environment.\nThis ensures long-term portability, future-proofing applications against RTOS shifts \nwhile ending platform fragmentation.\n\nThe name POSKI is used to diambiguate the CHIP OSAL from external OSAL used by\nother projects or vendor SDKs.\n\n## Introduction\n\nThe CHIP OSAL is designed to provide a thin adaptation layer for portability of\nthe example applications and common portions of the DeviceLayer to a range of\nReal Time Operating Systems (RTOS). The intent is to leverage native OS\nprimitives as much as possible while providing a unified interface surface for\nthose primitives to the rest of the CHIP system, and to deliver common OS\nfunctionality suitable for deeply embedded environments.\n\nCHIP OSAL provides abstractions for:\n\n-   [tasks](#Task) (aka threads)\n-   [mutex](#Mutex)\n-   [semaphores](#Semaphore)\n-   [queues](#Queue)\n-   [timers](#Timer)\n-   [time](#Time)\n\nCHIP OSAL currently supports the above abstractions for the following OS\ntargets:\n\n-   POSIX (linux) - Linux and other standard POSIX systems\n-   POSIX (apple) - Apple and other Mach kernel systems using dispatch\n\nImplementations for the following targets are planned:\n\n-   FreeRTOS\n-   Zephyr\n\n### Motivation\n\nProject CHIP has explicit goals to provide a unifying, interoperable, versatile,\nlow overhead, and robust connected home solution with explicit focus on\ntime-to-market. These goals require the platform layer design to be highly\nscalable, allowing disparate and diverse platforms to be integrated with high\nvelocity. To support rapid integration of new platforms in a scalable and\nmaintainable way requires:\n\n-   Maximum reuse of code, verification, and testing\n-   Minimum code fragmentation, forking, and conditional compilation\n-   Adaptable and thin pathway to optimized native APIs\n\nDevice platforms tend to be highly unique on the first order, but also pivot on\nthree major areas of common functionality. These areas of commonality define a\nthree dimensional matrix of possible device configurations where a shared point\non any one axis can allow code reuse across otherwise disparate platorms:\n\n-   Device (board)\n\n    -   Platforms that share a specific choice of chip combinations and wiring\n        at the PCB level can share a common DeviceLayer port.\n    -   The DeviceLayer provides the minimum interface required to interface\n        CHIP to all the HW-specific details of a device such as BLE, WiFi,\n        storage.\n    -   Target examples are silicon vendor development boards or final product\n        PCBs.\n    -   A DeviceLayer is able to own all decisions about a device and impose\n        hard assumptions on the particular combination of board + os + hw.\n    -   A DeviceLayer is free to use an abstraction of the underlying OS or HW\n        layers to provide better portability between different RTOS environments\n        or across a family of SoCs.\n\n-   Operating System (os)\n\n    -   Platforms that share a common OS or RTOS can share a common OSAL port.\n    -   Target examples are FreeRTOS, Zephyr, Linux, Mac, ...\n    -   A given app or device layer port codebase may want to be retargetted\n        from one OS to another. This could happen during an upgrade cycle for\n        instance, or a new product may want to use a particular device layer\n        port that CHIP provides, but port it to the RTOS they typically use.\n\n-   Hardware (hw / chip)\n    -   Platforms that share a common chipset, SoC, or silicon can share a\n        common Hardware Abstraction Layer (HAL) from the vendor SDK.\n    -   By leveraging a HAL, the same application can be retargetted to\n        different chipsets across a family of similar SoCs.\n\nThe primary motivation of the CHIP OSAL is to enable code sharing and reuse in\nthe example applications and DeviceLayer. Rather than have a separate example\napp each combination of hw + os + board, the CHIP OSAL allows an example app to\nbe written in a common way and be retargeted for different OS/RTOS such as\nFreeRTOS, Zephyr, Linux, etc. The CHIP OSAL is intended to help make the system\nmore scalable as the matrix of combinations of hw + os + app increases over\ntime.\n\n### Context\n\nThere is a long history of OSAL layers. Why does CHIP need its own?\n\nWhile it is true the CHIP OSAL is \"Yet Another OSAL\", it is one that was\ndesigned to meet the specific requirements for Project CHIP. Other OSAL projects\nwere considered, some with common contributors to CHIP OSAL, but each had gaps\nrelative the requirements for Project CHIP:\n\n-   [nler](https://github.com/nestlabs/nler) - Nest Labs Embedded Runtime\n\n    -   Uses event queues with event pointer semantics whereas CHIP uses message\n        queues with copy semantics.\n    -   Has an inconsistant API namespace. All CHIP OSAL functions predictably\n        begin with `chip_os`.\n    -   Was designed to enforce a particular embedded programming philosophy.\n        Semaphores are notably missing for example.\n    -   Imposes its own centralized timer system rather than providing a thin\n        pass-through to native OS timers.\n    -   Centralized timer system relies on nler event queues, which are\n        antithetical to the CHIP messsage queue paradigm.\n\n-   [npl](https://github.com/apache/mynewt-nimble/tree/master/porting/npl) -\n    MyNewt NimBLE Platform Layer\n    -   Uses event queues with event pointer semantics whereas CHIP uses message\n        queues with copy semantics.\n    -   Is embedded within a larger BLE stack project and as such isn't easily\n        composable as a submodule.\n    -   Uses a consistent, but domain specic API namespace: `ble_npl`\n\n---\n\n## Reference\n\n### Task\n\nA task is an independent context of code execution that runs without any\ndependency on other concurrent tasks within the system. Only one task runs at\nany given time. The scheduler starts and stops tasks as necessary to manage\nresources according to the priorities and policies of the system. A task has no\nknowledge of the underlying scheduler activity and can be swapped in and out,\nbut will always run with a consistent execution context and stack.\n\n### Mutex\n\nA mutex provides a locking mechanism for enforcing mutual exclusion and\nprotection of shared resources between independent paths of execution such as\ndifferent tasks or interrupts.\n\n### Semaphore\n\nA semaphore is a synchronization primitive which provides a means to block one\ntask until it is released by a signal from another task or interrupt.\n\n### Queue\n\nA queue is a basic primitive for intertask communication. A queue can be used to\nsend messages from a task or interrupt producer to a consumer task using copy\nsemantics.\n\n### Timer\n\nA timer triggers a callback function after a given amount of time has passed.\n\n### Time\n\nA collection of utility functions for getting current system time and converting\nbetween milliseconds and CPU ticks is provided.\n\n## Porting guide\n\nThe CHIP OSAL module is structured as follows:\n\n| File / Folder           | Contents                                                            |\n| ----------------------- | ------------------------------------------------------------------- |\n| src/include/chip/osal.h | Public header with complete CHIP OSAL API                           |\n| src/osal/include        | Common headers and utilitied that can be shared by ports            |\n| src/osal/tests          | Implements portable tests of CHIP OSAL APIs                         |\n| src/osal/\u003cport\u003e         | Implements OSAL API for a given platform \u003cport\u003e                     |\n| \u003cport\u003e/chip/os_port.h   | Maps OSAL types to platform-specific definitions for a given \u003cport\u003e |\n\n### Layout Details\n\n```\n.\n├── src/osal              - Top level of CHIP OSAL submodule\n├── include\n│   └── Ring.h            - A portable ring buffer class for common use\n├── README.md             - This document\n└── tests\n    ├── Makefile.am       - Primary automake file\n    ├── Makefile.mk       - Developer utility make file for running the tests\n    ├── test_os_mutex.c   - Test of chip_os_mutex\n    ├── test_os_queue.c   - Test of chip_os_queue\n    ├── test_os_sem.c     - Test of chip_os_sem\n    ├── test_os_task.c    - Test of chip_os_task\n    ├── test_os_timer.c   - Test of chip_os_timer\n    ├── test_ring.cpp     - Test of Ring.h\n    └── test_util.h       - Common test utilities\n```\n\n#### POSIX Port Layout\n\nThe POSIX port includes both Linux and Apple implementations.\n\nLinux uses the standard POSIX APIs for all functionality.\n\nApple uses POSIX pthreads but also Grand Central dispatch for the timer and\nsemaphore implementations.\n\n| OS    | Task    | Mutex | Sem      | Timer    | Time  | Queue          |\n| ----- | ------- | ----- | -------- | -------- | ----- | -------------- |\n| Linux | pthread | posix | posix    | posix    | posix | pthread + ring |\n| MacOS | pthread | posix | dispatch | dispatch | mach  | pthread + ring |\n\n```\n├── src/osal               - Top level of CHIP OSAL submodule\n├── posix\n│   ├── chip\n│   │   ├── os_port.h      - Primary port-specific header to hook into public src/include/chip/osal.h\n│   │   ├── os_time.h      - Types related to time and timers\n│   │   └── os_types.h     - All other CHIP OSAL types\n│   ├── os_mutex.c         - Implementation of chip_os_mutex\n│   ├── os_queue.cc        - Implementation of chip_os_queue\n│   ├── os_sem.c           - Implementation of chip_os_sem\n│   ├── os_task.c          - Implementation of chip_os_task\n│   ├── os_time.c          - Implementation of chip_os_time\n│   ├── os_timer.c         - Implementation of chip_os_timer\n│   ├── os_utils.c         - Shared code for the posix port, most notably error mapping.\n│   ├── os_utils.h         - Shared header for the posix port, most notably nlassert code utility macros.\n│   └── RingPthread.h      - Thread-safe version of Ring using posix mutex and cond\n```\n\n\n## Quick Start\n\n### Prerequisites\n\n- Make\n- Bazel\n- GTest\n\n\n#### Linux\n\nFor standard prerequisites (Make, Ccache, Bazel):\n```bash\nsudo apt install make ccache bazel\n```\n\n#### Mac\n\n```\nbrew install make ccache bazel gtest\n```\n\n### Build\n\n#### Make\n\nTo build only the **POSIX/Linux** library target (`libosal.a`) and tests:\n```bash\n$ make\n```\n\nTo build the **FreeRTOS** static library target (`libosal_freertos.a`) and firmware hex binaries (requires Nordic SDK):\n```bash\n# Export the path to Nordic SDK\n$ export NRF5_SDK_ROOT=/path/to/nRF5_SDK_17.1.0_ddde560\n\n# Compile FreeRTOS library and hex targets\n$ PLATFORM=nrf52840 make\n```\n\n#### Bazel\n\nBy default, `bazel build //:all` will attempt to build targets for all supported platforms, including Zephyr (which will fail if you don't have the Zephyr SDK installed).\n\nTo build only the **POSIX/Linux** library target:\n```bash\n$ bazel build //:osal\n```\n\nTo build only the **FreeRTOS** library target (`osal_freertos` / `freertos` alias):\n```bash\n# Builds osal_freertos.\n$ bazel build //:freertos\n```\n\nTo build the POSIX/Linux test binaries:\n```bash\n$ bazel build //:test //:gtest\n```\n\n### Test\n\n#### Make\n\nTo run the standard tests:\n```bash\n$ make test\n```\n\nTo run the Google Test (gtest) suite (which automatically downloads and builds gtest locally):\n```bash\n$ make gtest\n```\n\n#### Bazel\n\nTo run the standard tests:\n```bash\n$ bazel test //:test\n```\n\nTo run the Google Test (gtest) suite:\n```bash\n$ bazel test //:gtest\n```\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fproject-chip%2Fposki","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fproject-chip%2Fposki","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fproject-chip%2Fposki/lists"}