# TraxProbe OS / RTOS Porting Layer

This directory contains the OS/RTOS integration layer for TraxProbe, organized into a common (platform-independent) module and per-OS/RTOS ports.

## Directory Structure

```
os/
├── common/
│   ├── trax_rtos_tables.h       — RTOS entity registry + trax_os_* query API declarations
│   └── trax_rtos_tables.c       — RTOS RAM table + free-list implementation
│
├── FreeRTOS/
│   ├── trax_rtos_port.h         — FreeRTOS trace hook macro definitions
│   ├── trax_freertos_task.c     — FreeRTOS Ctrl Task (xTaskCreateStatic)
│   ├── trax_freertos_heap.c     — Heap query API (xPortGetFreeHeapSize, …)
│   ├── trax_freertos_memory.c   — Stack high-water polling (uxTaskGet…)
│   ├── trax_freertos_meta.c     — Port-supplied META for kernel-owned ISRs
│   └── README.md                — FreeRTOS integration guide
│
└── BareMetal/
    ├── trax_baremetal_memory.c  — Stack monitor stub (no-op, single stack)
    └── README.md                — BareMetal integration guide
```

## Architecture

### Common Layer (`common/`)

The common layer provides platform-independent task and object table management:

- **Static RAM tables** with O(1) free-list allocation/deallocation
- **No RTOS headers** — portable across any RTOS or bare-metal environment
- Uses `TRAX_CFG_RTOS_TASK_NAME_MAX` (default 16) instead of RTOS-specific name length constants

Each RTOS port calls the common table API from its trace hook macros.

### OS / RTOS Ports

Each port provides:
1. **Trace hook macros** that map RTOS kernel events to TraxProbe frames
2. **A ctrl task** (or polling instructions) for draining the ring buffer

## How to Add a New RTOS Port

1. Create a new directory under `os/` (e.g., `os/Zephyr/`)
2. Create a port header named `trax_rtos_port.h` in that directory that:
   - `#include "../common/trax_rtos_tables.h"`
   - Defines trace hook macros that call the common table API
   - Uses include guard `TRAX_<RTOS>_PORT_H_` (e.g. `TRAX_ZEPHYR_PORT_H_`)
3. Add the new RTOS constant to `include/trax_tid.h` (e.g. `TRAX_RTOS_ZEPHYR`)
4. Add a `#elif` branch to `include/trax_rtos_port.h` (the dispatcher) for the new constant
5. Create a ctrl task source file using the RTOS's native task/thread API
6. Add a `README.md` with integration instructions

## Configuration

In `App/Config/trax_config.h`:

```c
#define TRAX_CFG_RTOS_TYPE             TRAX_RTOS_FREERTOS  // or TRAX_RTOS_NONE
#define TRAX_CFG_RTOS_TASK_NAME_MAX    configMAX_TASK_NAME_LEN  // optional, default 16
```
