CleverOS Documentation

Internal State And Function Reference

This page turns the appendix on global variables and related functions into a public-facing guide. The function explanations are based on the reviewed CleverOS source behavior in OS.h, os.c, and inline.c.

Browse Functions Repository Docs

Source Reconciliation

The appendix is a useful cross-reference, but a few names are from older code or were renamed in the current source.

Appendix name	Current source status
`lowPowerModeOS()`	No standalone function in the reviewed source. Low power is implemented through schedulerOS(), idleTaskOS(), minDelayTickOS(), and the lowPowerTimerOS callback.
`qTxIntFloatOS() / qRxIntFloatOS()`	The current public names are qTxValueOS() and qRxValueOS().
`leakMemoryNoAllOS() / lackMemoryNoAllOS()`	The current public names are leakAllOS() and lackAllOS().
`margeAddressOS(), dangerAddressOS(), getMemoryNoOS()`	Older memory-manager helpers; not present in the reviewed current source.
`divisorOS()`	Declared in OS.h, but no implementation was found in the reviewed os.c.

Global State By Subsystem

CleverOS is intentionally compact, so global arrays are central to scheduling, events, stack safety, queues, memory, and low-power behavior.

Subsystem	Important state	Purpose
Kernel	`CurrentPriorityOS, ReadyTableOS[], WaitTickOS[], PriorityOwnEventOS[]`	Track the running task, runnable tasks, delayed tasks, and tasks that have acquired events.
Context Switch	`CurrentTaskOS, NextTaskOS, TaskSpPointerOS[], TaskStackOS[]`	Provide the stack addresses used by PendSV_Handler().
Stack Safety	`ResidueOS[], DeltaResidueOS[], MaxDeltaOS[], SafeLevelOS[], DangerStackOS[]`	Measure remaining stack padding and mark unsafe tasks.
Events	`EventNumberTaskOS[], ReceiveMessageOS[], MutexOwnerOS[], PublicFlagOS[]`	Hold semaphore, mail, mutex, and flag wait state.
Memory	`PoolOS[], FreeBulkNoOS[], StartBulkNoOS[], LeakNoOS[], LackNoOS[]`	Implement the fixed memory pool and allocation diagnostics.
Queues	`QBodyOS[], QTxRxOS[], qRetrieveOS[][], FlagTxRxOS`	Store queue entries and non-blocking value-transfer progress.
Timing And Low Power	`SystemTickOS, TaskExecuteClockOS[], TaskLoadOS[], MinDelayTickOS, PowerOnOS`	Track task execution time, task load, and skipped ticks during low-power idle.

Public API Functions

These are the functions a firmware developer is most likely to use directly from OS.h.

Function	Brief explanation
`startOS()`	Validates configuration, stores callbacks, initializes SysTick, events, stacks, PSP, and starts the selected task.
`schedulerOS()`	Selects the next task, isolates dangerous-stack tasks, updates task/load state, handles low-power entry, and triggers PendSV.
`queryReadyTableOS()`	Returns the ready-table address so firmware can inspect runnable task bits.
`nonBlockingCallbackOS()`	Runs a short callback with interrupts disabled and returns its status.
`deleteSelfOS()`	Removes the current task from normal scheduling by delaying it indefinitely.
`errorPendSizeOS()`	Returns the pending-event table error flag.
`ramToPaddingOS()`	Converts a RAM budget into stack padding words after CPU register frames are reserved.
`paddingToRamOS()`	Converts stack padding words back into required RAM bytes.
`autoPackItemsOS()`	Reports the auto-assigned padding per task when PaddingOS[] was not manually configured.
`minimumStackOS()`	Scans stack fill markers and reports each task's consumed padding plus optional minimum RAM.
`autoMinimumStackOS()`	Estimates an optimized stack RAM size from the smallest remaining auto padding.
`queryResidueStackOS()`	Updates and returns the current task's remaining untouched stack padding.
`queryDangerTaskOS()`	Reports whether the current task is marked as stack-dangerous.
`checkStackSafetyOS()`	Applies a selected stack-safety level after enough runs and marks the task dangerous if needed.
`querySafeLevelOS()`	Returns the current task's observed safety level after enough scheduler samples.
`delayTickOS()`	Blocks the current task for a tick count or indefinitely for a negative tick value.
`delayTimeOS()`	Converts time fields into ticks, rounds milliseconds, and blocks the current task.
`delayUntilEqualOS()`	Blocks until two watched integer addresses hold equal values.
`delayUntilTrueOS()`	Blocks until a watched integer address becomes non-zero.
`postSemOS()`	Posts a semaphore number and wakes matching pending tasks.
`pendSemOS()`	Waits for one semaphore from a terminated number array, returning ready number, timeout, or array error.
`postMailOS()`	Stores a message pointer and wakes tasks waiting for that mail number.
`readMailOS()`	Reads a mail pointer and optionally clears the mail slot.
`pendMailOS()`	Waits for mail and returns the message pointer, optionally reporting the ready mail number.
`postMutexOS()`	Releases the current task's mutex and grants it to the highest-priority waiter.
`pendMutexOS()`	Acquires one mutex or waits until it becomes available.
`postFlagOS()`	Sets or clears public flag bits and wakes tasks whose private masks match.
`pendFlagOS()`	Waits for flag numbers using match-all or match-any bit semantics.
`queryPublicFlagOS()`	Returns a public flag word.
`checkPublicFlagBitOS()`	Returns whether one public flag bit is set.
`getMemoryOS()`	Allocates from the fixed pool under an allocation number and reports repeated allocation as a leak.
`getMemoryWithPutOS()`	Frees an allocation number first, then allocates new memory for it.
`putMemoryOS()`	Frees memory associated with an allocation number.
`mallocOS()`	Allocates from the same fixed pool without a persistent allocation number.
`freeOS()`	Frees a pool allocation by raw address.
`queryFreeBulkNoOS()`	Copies the free-bulk bitmap into a caller buffer and returns the true bulk count.
`leakMemoryNoOS()`	Returns and clears the first allocation number that attempted to allocate twice.
`lackMemoryNoOS()`	Returns and clears the first allocation number that failed from lack of pool space.
`leakAllOS()`	Returns cumulative leak counts for all allocation numbers.
`lackAllOS()`	Returns cumulative allocation-failure counts for all allocation numbers.
`postQOS()`	Pushes a pointer-sized message into a queue and wakes matching queue waiters.
`pendQOS()`	Waits for any queue in a terminated array, reads queued entries, and returns the retrieval buffer.
`qReadyNumberOS()`	Maps a retrieval buffer pointer back to its queue number.
`queryRemainItemsOS()`	Returns remaining capacity for a queue.
`qTxValueOS()`	Starts non-blocking transfer of an integer or scaled-float array into a queue.
`qRxValueOS()`	Starts non-blocking receive of integer or scaled-float queue values into caller storage.
`packetLengthOS()`	Returns the configured value-transfer length for a queue.
`qTxRealtimeOS()`	Thin real-time send wrapper around postQOS().
`qRxRealtimePendOS()`	Waits indefinitely for one queue item and returns the first retrieved message.
`relativeTaskLoadOS()`	Calculates task execution share from scheduler run counts, excluding idle.
`idleTaskLoadOS()`	Calculates idle percentage from accumulated execution clocks.
`matchRegisterOS()`	Returns the tick count skipped when low-power idle was entered.

Internal Function Groups

These functions explain how the kernel uses the global state behind the public API.

Startup

initializeSysTickOS, setHandlerPriorityOS, initializeTaskOS, initializeEventOS, assignPaddingSpOS, checkStartErrorOS

Scheduling

setTableOS, clearTableOS, checkSetBitOS, currentExecuteClockOS, highestEventPriorityOS, resumeTaskOS, pauseTaskOS, SysTick_Handler

Pend Logic

currentPriorityMapEventIndexOS, IsStartPendOS, justifyNumberArrayOS, readReadyNumberOS, pendCodeOS

Stack Internals

currentResidueOS, dangerSafeOS, checkSafeLevelOS

Memory Internals

memoryAddressOS, findFreeMemoryOS, memoryOS

Queue Internals

readQOS, findItemNumberOS, writeQOS, qTxOS, qRxOS, nonBlockingValueTransferOS

Low Power And Port

minDelayTickOS, idleTaskOS, findLeastBitOS, interruptNumberOS, setPSPOS, setCONTROLOS, PendSV_Handler