RTOS migrations

​

Prepare the migration

• The source RTOS version, vendor SDK or fork, toolchain, and build configuration.
• The destination RTOS release, board target, required drivers, and middleware dependencies.
• The build, test, flash, and observation commands, including the connected board and its probe or port.
• Application interfaces, timing tolerances, RAM, flash, and power budgets, and any behavior changes you accept.

​

Capture the source behavior

Build the current firmware and run its existing tests. On the confirmed board,
capture startup and a representative workload using the project's observation
setup. Record task periods, response latency, queue overflow behavior, and
memory and power usage where measurable. Save the firmware artifact,
configuration, test inputs, and results as the migration baseline. Mark
missing measurements.

​

Review the porting plan

• Tasks, priorities, stacks, timers, synchronization, and shared-resource ownership.
• Blocking calls, timeouts, interrupt context, and scheduling assumptions.
• Startup, allocation, drivers, power management, and build configuration.
• Affected files, implementation order, checks for each stage, and unresolved dependencies.

​

Example: FreeRTOS to Zephyr

Plan a FreeRTOS-to-Zephyr migration on the current board. Preserve the sensor
driver's application-facing API, the 10 ms sampling period, sample ordering,
and UART packet format. Use the recorded jitter and memory limits. Inspect
FreeRTOSConfig.h, task creation, queues, notifications, timers, ISR calls,
and SDK dependencies. Check the chosen Zephyr release's board and driver
support. Propose stages with affected files and pass conditions before editing.

​

Establish the Zephyr application

Trace the existing sensor bus and UART initialization against the board
schematic and peripheral limits. Propose the devicetree overlay, pinctrl,
Kconfig, and runtime changes needed for Zephyr. Account for existing board
and SoC defaults. Identify conflicting HAL initialization and unresolved
pin, clock, or driver assumptions before implementing the configuration.

​

Review the behavior behind each API

• Tasks and priorities. Move task entry points to Zephyr threads and map their relative urgency explicitly. FreeRTOS uses larger numbers for higher priority. Zephyr uses smaller numbers, with negative values for cooperative threads and nonnegative values for preemptible threads. Include system threads in the priority review, and check time slicing and startup order. See FreeRTOS task scheduling and Zephyr threads.
• Stacks and allocation. Upstream FreeRTOS xTaskCreate takes a stack depth in StackType_t elements, often called words; ESP-IDF uses bytes. Zephyr’s K_THREAD_DEFINE takes bytes. Use Zephyr’s stack-definition or stack-allocation APIs, then measure stack usage again under load. Check heap use, static allocation, and allocation-failure behavior too. See FreeRTOS task creation and Zephyr thread APIs.
• Queues and synchronization. A fixed-size sample queue may fit k_msgq. Check item size, copy versus pointer ownership, capacity, return values, and full-queue behavior. Review mutex priority inheritance and notification or event-bit semantics separately before choosing replacements. See Zephyr message queues.
• Periods and timeouts. Preserve the acquisition task’s periodic deadline and overrun policy. Replacing a delay-until loop with a relative sleep after each iteration’s work can introduce drift. Convert tick-based waits deliberately, and check rounding, no-wait, and indefinite-wait behavior against the chosen API. See Zephyr kernel timing.
• Timers and interrupt handlers. FreeRTOS software timer callbacks run in a timer service task and must not block. Zephyr timer expiry functions run in interrupt context. Defer work that needs thread context to a suitable worker or thread. Audit every FromISR call and critical section for the destination’s context rules. Zephyr treats kernel API use from zero-latency interrupts as undefined behavior. See FreeRTOS software timers, Zephyr timers, and interrupt handling.
• Deferred work. A shared workqueue can delay processing behind other work. Submitting a work item that is already queued doesn’t queue a second event. If every sample matters, keep samples in a queue or buffer and verify the consumer’s latency. See Zephyr workqueues.
• Drivers and middleware. Decide which existing code can stay behind the application interface and which should move to Zephyr drivers or subsystems. Check who owns interrupts, clocks, DMA, and the system tick before keeping vendor HAL initialization.

​

Port one complete data path

Implement the reviewed acquisition-to-queue-to-UART path in the Zephyr build.
Preserve sample ownership, ordering, and overflow reporting. Run focused tests
for conversion and packet encoding, then build the selected board target.
Report the result and remaining dependencies before porting other services.

​

Verify the migrated firmware

Run the same sensor workload and capture duration as the FreeRTOS baseline.
Compare startup order, sampling period and jitter, sample loss, UART packet
format, and RAM, flash, and power usage against the agreed limits. Exercise
queue saturation, sensor timeout recovery, and watchdog recovery from stalled
work. Report each check as passed, failed, or unverified, with its evidence.

• Save repeatable bench checks as hardware scripts. See Automated testing for host and target checks.
• Switch to Debug mode for faults or hangs.
• Choose the instrument for the requirement: a logic analyzer for bus transactions, an oscilloscope for signal quality, or a power analyzer for current consumption.