Requirements Traceability Matrix

sc_cobs_max_encoded(n) shall return an upper bound on the encoded length of any n-byte payload.

sc_cobs_max_encoded returns 1 for n == 0, else n + (n-1)/254 + 1.

sc_cobs_encode shall produce output containing no 0x00 byte, and shall return 0 if an argument is NULL or the output would not fit.

sc_cobs_encode returns 0 when in or out is NULL or sc_cobs_max_encoded(in_len) > out_cap.

Encode consumes the input one byte at a time.

On a 0x00 input byte, the current code is written and a new block started.

A non-zero input byte is copied to the output and the code incremented.

When the code reaches 0xFF (254 data bytes) and more input remains, the block is closed with 0xFF.

After the input is consumed, the pending code is written into its reserved slot.

sc_cobs_decode shall be the exact inverse of sc_cobs_encode for every payload: decode(encode(p)) == p.

Encode consumes the input one byte at a time.

Decode reads a code byte, then that many minus one data bytes, repeating.

code - 1 data bytes are copied verbatim from input to output.

Unless the code was 0xFF or the input is exhausted, a single 0x00 is appended between blocks.

sc_cobs_decode shall return 0 for malformed input (a 0x00 where a code byte is expected, or a block length that runs past the end) or when the output would not fit.

sc_cobs_decode returns 0 when in or out is NULL.

Decode reads a code byte, then that many minus one data bytes, repeating.

A code byte of 0x00, or a span that exceeds the remaining input or output, sets the failure flag.

Decode returns the decoded length on success, 0 on any failure.

Each function shall compute its named standard CRC with the conventional parameters, matching the published check value for the message "123456789".

Each function iterates over len message bytes, folding each into the register; a zero-length message runs the loop zero times.

For every byte, the register is advanced by exactly eight single-bit steps.

For the non-reflected CRCs, a step XORs the polynomial when the top register bit is set, otherwise it only shifts left.

sc_crc8_smbus returns the register unmodified (init 0x00, poly 0x07, no final XOR).

sc_crc16_ccitt_false returns the register unmodified (init 0xFFFF, poly 0x1021).

sc_crc32 uses the reflected algorithm: a step XORs 0xEDB88320 when the low register bit is set, otherwise it only shifts right.

sc_crc32 applies the final XOR with 0xFFFFFFFF before returning.

Any single-bit change anywhere in the message shall change the returned CRC.

For every byte, the register is advanced by exactly eight single-bit steps.

For the non-reflected CRCs, a step XORs the polynomial when the top register bit is set, otherwise it only shifts left.

sc_crc32 uses the reflected algorithm: a step XORs 0xEDB88320 when the low register bit is set, otherwise it only shifts right.

A zero-length message shall return the CRC's defined initial/framed value.

Each function iterates over len message bytes, folding each into the register; a zero-length message runs the loop zero times.

sc_crc8_smbus returns the register unmodified (init 0x00, poly 0x07, no final XOR).

sc_crc16_ccitt_false returns the register unmodified (init 0xFFFF, poly 0x1021).

sc_crc32 applies the final XOR with 0xFFFFFFFF before returning.

A NULL data pointer shall be treated as a zero-length message regardless of the length argument.

A NULL data pointer forces len to 0 before the loop.

sc_debounce_config_valid shall reject a NULL config or a threshold of 0.

sc_debounce_config_valid returns SC_ERR_NULL for NULL cfg.

Returns SC_ERR_PARAM when threshold == 0.

Returns SC_OK otherwise.

sc_debounce_init shall set the output to a given value and clear the run counter; a NULL state shall be rejected. sc_debounce_update shall return false for a NULL config or state without modifying the state.

sc_debounce_init sets output to 0/1 from initial and counter to 0.

A NULL cfg or state returns false without touching the state.

sc_debounce_init returns SC_ERR_NULL for NULL state.

The output shall follow the raw input only after the raw input has disagreed with the current output for threshold consecutive updates.

When the raw sample differs, counter is incremented.

When counter reaches threshold, output takes the raw value and counter is reset.

A disagreement run shorter than threshold shall not change the output, and the run counter shall reset on the first agreeing sample.

When the raw sample equals output, counter is set to 0.

Conversion between whole numbers and Q16.16 shall be exact within the representable range and saturate outside it; Q16.16 → int shall truncate toward zero.

sc_q16_from_int returns SC_Q16_MAX when value > 32767.

Returns SC_Q16_MIN when value < -32768.

Otherwise returns value * SC_Q16_ONE.

sc_q16_to_int returns q / SC_Q16_ONE (truncates toward zero).

Add and subtract shall return the exact result when it fits and saturate at SC_Q16_MAX / SC_Q16_MIN otherwise.

sc_q16_add is sc_sat_add_i32.

sc_q16_sub is sc_sat_sub_i32.

Multiply shall round to nearest (ties away from zero) and saturate on overflow.

Multiply adds a half-LSB bias before the shift when the 64-bit product is ≥ 0.

Multiply subtracts a half-LSB bias when the product is < 0 (ties away from zero).

Multiply divides the biased product by 2^16 and clamps the result.

clamp_i64 returns SC_Q16_MAX when the 64-bit value exceeds it.

clamp_i64 returns SC_Q16_MIN when the value is below it.

clamp_i64 returns the value cast to sc_q16_t otherwise.

Divide shall saturate on overflow; division by zero shall return SC_Q16_MAX when the dividend is ≥ 0 and SC_Q16_MIN otherwise.

sc_q16_div returns SC_Q16_MAX (dividend ≥ 0) or SC_Q16_MIN (dividend < 0) when the divisor is 0.

Otherwise divide computes (a << 16) / b in 64-bit and clamps.

clamp_i64 returns SC_Q16_MAX when the 64-bit value exceeds it.

clamp_i64 returns SC_Q16_MIN when the value is below it.

clamp_i64 returns the value cast to sc_q16_t otherwise.

Absolute value shall saturate: |SC_Q16_MIN| returns SC_Q16_MAX.

sc_q16_abs returns SC_Q16_MAX when q == SC_Q16_MIN.

Returns -q when q < 0.

Returns q when q >= 0.

Clamp shall constrain a value to [lo, hi], returning lo when lo > hi.

sc_q16_clamp returns lo when lo > hi.

sc_q16_clamp returns lo when q < lo.

Returns hi when q > hi.

Returns q when it is already within [lo, hi].

After initialisation the output shall be CLEARED (false).

sc_hysteresis_init sets state->asserted to false.

sc_hysteresis_init returns SC_ERR_NULL when state is NULL, else SC_OK.

sc_hysteresis_output returns false when state is NULL.

sc_hysteresis_output returns state->asserted otherwise.

The output shall ASSERT (true) when the input rises to or above high_threshold while the output is currently cleared.

sc_hysteresis_update sets asserted true when asserted is false and input >= cfg->high_threshold.

sc_hysteresis_update returns false without dereferencing either pointer if cfg or state is NULL.

sc_hysteresis_update returns the post-update value of state->asserted.

The output shall CLEAR when the input falls to or below low_threshold while the output is currently asserted.

sc_hysteresis_update sets asserted false when asserted is true and input <= cfg->low_threshold.

sc_hysteresis_update returns false without dereferencing either pointer if cfg or state is NULL.

sc_hysteresis_update returns the post-update value of state->asserted.

While the input is strictly between the two thresholds the output shall hold its previous value.

When neither edge condition holds, sc_hysteresis_update leaves asserted unchanged.

Across any sequence of inputs the output shall change at most once per update and only in the direction the input crossing implies.

sc_hysteresis_update sets asserted true when asserted is false and input >= cfg->high_threshold.

sc_hysteresis_update sets asserted false when asserted is true and input <= cfg->low_threshold.

When neither edge condition holds, sc_hysteresis_update leaves asserted unchanged.

A configuration with high_threshold == low_threshold shall behave as a plain comparator (no dead band).

Otherwise sc_hysteresis_config_valid returns SC_OK.

A configuration with high_threshold < low_threshold shall be reported invalid by sc_hysteresis_config_valid.

sc_hysteresis_config_valid returns SC_ERR_NULL when cfg is NULL.

sc_hysteresis_config_valid returns SC_ERR_PARAM when cfg->high_threshold < cfg->low_threshold.

Otherwise sc_hysteresis_config_valid returns SC_OK.

An input at or below the first breakpoint shall return the first table value; an input at or above the last breakpoint shall return the last value; a NULL table shall evaluate to 0.

sc_lut_eval returns y[0] when x <= x[0].

Returns y[n-1] when the segment search reaches the last point.

A NULL lut returns 0.

An input strictly between two breakpoints shall return the linear interpolation of the bracketing segment.

The search advances until x < x[i+1], selecting segment i.

step = y[i+1] - y[i] and span = x[i+1] - x[i] are computed in 64-bit.

offset = step * (x - x[i]) / span.

The result is sc_sat_add_i32(y[i], offset).

sc_lut_valid shall reject a NULL table or array, fewer than two points, or breakpoints that are not strictly increasing.

sc_lut_valid returns SC_ERR_NULL when lut, x, or y is NULL.

Returns SC_ERR_PARAM when n < 2.

Returns SC_ERR_PARAM when any x[i+1] <= x[i].

sc_median_config_valid shall accept a length that is odd and in 1..SC_MEDIAN_MAX_WINDOW, and shall reject a NULL config, an even length, a length of 0, or a length greater than SC_MEDIAN_MAX_WINDOW.

sc_median_config_valid returns SC_ERR_NULL for a NULL cfg.

Returns SC_ERR_PARAM when length exceeds SC_MEDIAN_MAX_WINDOW.

Returns SC_ERR_PARAM when length is even (which includes 0).

Returns SC_OK for an odd length within range.

sc_median_init shall place the filter in a known empty state and reject a NULL state. sc_median_update shall return 0 for a NULL config or state without modifying the state.

sc_median_init clears every history slot to 0 and sets count and head to 0.

sc_median_init returns SC_ERR_NULL for a NULL state, SC_OK otherwise.

sc_median_update returns 0 and does not touch the state when cfg or state is NULL.

sc_median_update shall maintain a sliding window of the most recent length samples, overwriting the oldest sample once the window is full.

sc_median_update writes the new sample to history[head] and advances head modulo length.

count increases by one per update until it reaches length, then holds.

sc_median_update shall return the median of the samples currently held in the window. Before the window has filled, it shall return the median of the samples seen so far.

sc_median_update copies the count live samples into a scratch buffer and sorts them ascending with an insertion sort.

sc_median_update returns the scratch element at index count / 2.

sc_pid_config_valid shall reject a NULL config, out_min > out_max, or a derivative-filter coefficient outside [0, SC_Q16_ONE).

sc_pid_config_valid returns SC_ERR_NULL for NULL cfg.

Returns SC_ERR_PARAM when out_min > out_max.

Returns SC_ERR_PARAM when d_filter < 0 or d_filter >= SC_Q16_ONE.

Returns SC_OK otherwise.

sc_pid_init shall preload the integrator with the given initial output and seed the measurement history; a NULL state shall be rejected. sc_pid_update shall return 0 for a NULL config or state and not modify the state.

sc_pid_update returns 0 without touching the state when cfg or state is NULL.

sc_pid_init returns SC_ERR_NULL for NULL state.

sc_pid_init sets integrator = initial_output, prev_measurement = initial_measurement, prev_derivative = 0.

The proportional term shall be kp × (setpoint − measurement).

error = setpoint − measurement (saturating).

p_term = kp × error.

The derivative term shall be computed from the change in *measurement*, not error, so a setpoint step alone produces no derivative contribution.

d_raw = kd × −(measurement − prev_measurement).

The derivative term shall be passed through a first-order low-pass with coefficient d_filter.

d_term = d_filter × prev_derivative + (1 − d_filter) × d_raw.

The integrator shall accumulate ki × error each cycle, subject to anti-windup.

i_new = integrator + ki × error.

While the unclamped output is above out_max (or below out_min), the integrator shall be updated only if the update moves the output toward the band; otherwise it shall be held.

When out_raw > out_max: return out_max; commit i_new only if i_new <= integrator.

When out_raw < out_min: return out_min; commit i_new only if i_new >= integrator.

The returned output shall always lie within [out_min, out_max], and a stable closed loop shall converge onto its setpoint.

out_raw = p_term + i_new + d_term.

When out_raw > out_max: return out_max; commit i_new only if i_new <= integrator.

When out_raw < out_min: return out_min; commit i_new only if i_new >= integrator.

Otherwise return out_raw and commit i_new.

sc_ringbuf_init shall bind the buffer to caller storage of a stated capacity and leave it empty; it shall reject a NULL buffer, NULL storage, or zero capacity.

sc_ringbuf_init stores storage, capacity, and zeroes head, tail, count.

sc_ringbuf_is_empty returns count == 0.

Every mutating entry point returns SC_ERR_NULL when a required pointer (rb, storage, out) is NULL.

sc_ringbuf_init returns SC_ERR_PARAM when capacity == 0.

The query helpers treat a NULL rb as empty / not-full / count 0.

Bytes shall be returned by sc_ringbuf_pop in the order they were supplied to sc_ringbuf_push (first-in, first-out).

sc_ringbuf_count returns count.

sc_ringbuf_push writes value at head; sc_ringbuf_pop reads from tail into *out.

The buffer shall reuse storage cyclically: after capacity pushes the write position wraps to the start, and likewise for reads.

After advancing, head / tail wrap to 0 when they reach capacity; count is incremented on push and decremented on pop.

sc_ringbuf_push shall return SC_ERR_FULL and make no change when the buffer already holds capacity bytes.

sc_ringbuf_is_full returns count == capacity.

sc_ringbuf_push returns SC_ERR_FULL without writing when count == capacity.

sc_ringbuf_pop shall return SC_ERR_EMPTY and leave the output argument unchanged when the buffer holds no bytes.

sc_ringbuf_is_empty returns count == 0.

sc_ringbuf_pop returns SC_ERR_EMPTY without touching *out when count == 0.

Every mutating entry point returns SC_ERR_NULL when a required pointer (rb, storage, out) is NULL.

sc_ringbuf_reset shall discard all buffered bytes while keeping the storage binding usable.

sc_ringbuf_reset zeroes head, tail, count and returns SC_OK.

A commanded change larger than the configured limit shall be applied as at most max_step_up per update when rising, or max_step_down per update when falling.

delta is sc_sat_sub_i32(target, state->output).

delta is limited to max_step_up when it exceeds it.

delta is limited to -max_step_down when it is below it.

A commanded change within the configured limits shall be applied in full on that update.

delta within [-max_step_down, max_step_up] is left unchanged.

sc_ratelimit_init sets state->output to initial and returns SC_OK.

Given a fixed reachable target, the output shall converge onto it exactly within a finite number of updates and then hold.

state->output is updated to the clamped value and returned.

sc_ratelimit_output returns state->output otherwise.

The returned output shall always lie in [out_min, out_max], regardless of the starting value or target.

The new output is raised to out_min if below it.

The new output is lowered to out_max if above it.

A new output already within [out_min, out_max] is left unchanged.

No input value shall cause the output to wrap; internal arithmetic shall saturate at the 32-bit limits.

delta is sc_sat_sub_i32(target, state->output).

The new output is sc_sat_add_i32(state->output, delta).

If state is NULL the function shall return 0; if state is non-NULL but cfg is NULL it shall return the current output unchanged.

NULL state returns 0; NULL cfg with non-NULL state returns state->output.

sc_ratelimit_init returns SC_ERR_NULL for NULL state.

sc_ratelimit_output returns 0 for NULL state.

sc_ratelimit_config_valid shall reject a negative step or out_min > out_max.

sc_ratelimit_config_valid returns SC_ERR_NULL for NULL cfg.

Returns SC_ERR_PARAM when max_step_up < 0 or max_step_down < 0.

Returns SC_ERR_PARAM when out_min > out_max.

Returns SC_OK otherwise.

When the exact mathematical result of the operation is within [INT32_MIN, INT32_MAX], the function shall return that result.

Otherwise sc_sat_add_i32 returns a + b.

Otherwise sc_sat_sub_i32 returns a - b.

When the exact result exceeds INT32_MAX the function shall return INT32_MAX; when it is below INT32_MIN it shall return INT32_MIN. The function shall never evaluate a signed expression that overflows.

sc_sat_add_i32 returns INT32_MAX when b > 0 and a > INT32_MAX - b.

sc_sat_add_i32 returns INT32_MIN when b < 0 and a < INT32_MIN - b.

sc_sat_sub_i32 returns INT32_MAX when b < 0 and a > INT32_MAX + b.

sc_sat_sub_i32 returns INT32_MIN when b > 0 and a < INT32_MIN + b.

sc_sched_config_valid shall reject a NULL config, a NULL slot table, zero slots, a NULL task pointer, a period of 0, or a phase not less than its period.

sc_sched_config_valid returns SC_ERR_NULL for a NULL cfg, a NULL slots, or a NULL slot run.

Returns SC_ERR_PARAM when n == 0.

Returns SC_ERR_PARAM when a slot has period == 0 or phase >= period.

sc_sched_init shall set the tick counter to 0; a NULL state shall be rejected. sc_sched_tick shall return 0 and not advance the tick for a NULL config or state.

sc_sched_init sets state->tick to 0.

A NULL cfg or state returns 0 without running or advancing.

sc_sched_init returns SC_ERR_NULL for a NULL state.

On each sc_sched_tick, every slot for which tick % period == phase shall be run once, in table order, and the tick counter shall then advance by one. The return value shall be the number of tasks run.

sc_sched_tick iterates the slots 0 .. n-1 in order.

A slot is run when (tick % period) == phase.

After running the due slots, state->tick is incremented and the run count returned.

sc_sm_config_valid shall reject a NULL config, a NULL transition table, or a table of zero rows.

sc_sm_config_valid returns SC_ERR_NULL when cfg or cfg->table is NULL.

Returns SC_ERR_PARAM when n == 0.

Returns SC_OK otherwise.

sc_sm_init shall set the machine to cfg->initial; sc_sm_state shall report the current state id, or 0xFFFF for a NULL state. NULL arguments to either shall be rejected / handled.

sc_sm_init sets state->state to cfg->initial.

sc_sm_init returns SC_ERR_NULL when state or cfg is NULL.

sc_sm_state returns 0xFFFF for a NULL state.

sc_sm_state returns state->state otherwise.

On an event, sc_sm_dispatch shall use the first table row whose from equals the current state and whose event equals the delivered event: it shall run that row's action (if non-NULL), move to the row's to state, and return true.

sc_sm_dispatch scans rows 0 .. n-1 in order.

On a match with a non-NULL action, the action is called with ctx.

On a match, state->state becomes t->to, fired is set, and the scan stops.

If no row matches, the state shall not change, no action shall run, and sc_sm_dispatch shall return false. NULL arguments shall return false.

sc_sm_dispatch scans rows 0 .. n-1 in order.

A NULL cfg or state returns false without scanning.

sc_vote_config_valid shall accept a count in 2..SC_VOTE_MAX_INPUTS, an agree in 1..count, and a non-negative tolerance, and shall reject a NULL config, a count outside that range, an agree of 0 or greater than count, or a negative tolerance.

sc_vote_config_valid returns SC_ERR_NULL for a NULL cfg.

Returns SC_ERR_PARAM when count is below 2 or above SC_VOTE_MAX_INPUTS.

Returns SC_ERR_PARAM when agree is 0 or greater than count.

Returns SC_ERR_PARAM when tolerance is negative.

Returns SC_OK when cfg is non-NULL and count, agree and tolerance are all in range.

sc_vote_evaluate shall return SC_ERR_NULL if any of cfg, inputs, or out is NULL, and SC_ERR_PARAM if n is not equal to cfg->count, in either case without producing a result.

sc_vote_evaluate returns SC_ERR_NULL if cfg, inputs or out is NULL.

sc_vote_evaluate returns SC_ERR_PARAM if n is not equal to cfg->count.

sc_vote_evaluate shall compute, for each channel, the number of channels whose reading is within tolerance of it, select the channel with the largest such count (earliest channel on a tie) as the winner, and set out->value to the winner's reading and out->agreeing to the winner's count. The within-tolerance test shall not overflow for any int32_t readings.

For each channel i, computes its cluster size as the number of channels j (0 <= j < n) for which within(inputs[i], inputs[j], tolerance) holds.

within(a, b, tol) forms a - b widened to 64-bit, negates it when negative, and returns whether the magnitude does not exceed tol; the widening admits no intermediate overflow.

Keeps winner as the channel with the greatest cluster size seen so far, leaving it unchanged when a later channel only ties.

Sets out->value to inputs[winner] and out->agreeing to sizes[winner].

sc_vote_evaluate shall set out->verdict to SC_VOTE_OK when out->agreeing is at least cfg->agree, and to SC_VOTE_NO_CONSENSUS otherwise, and shall return SC_OK once a result has been written for either verdict.

Sets out->verdict to SC_VOTE_OK when out->agreeing >= cfg->agree, otherwise SC_VOTE_NO_CONSENSUS.

Returns SC_OK once out has been fully populated.

sc_vote_evaluate shall set bit i of out->dissenting when channel i's reading is not within tolerance of out->value, and clear every other bit.

Sets bit i of out->dissenting when within(inputs[i], out->value, tolerance) is false, and leaves every other bit clear.

sc_watchdog_config_valid shall return SC_ERR_NULL for a NULL config, SC_ERR_PARAM for a timeout of 0, and SC_OK otherwise.

sc_watchdog_config_valid returns SC_ERR_NULL for a NULL cfg.

Returns SC_ERR_PARAM when cfg->timeout is 0.

Returns SC_OK when cfg is non-NULL and timeout is non-zero.

sc_watchdog_init shall set the elapsed count to 0 and the tripped flag to false, and shall return SC_ERR_NULL for a NULL state.

sc_watchdog_init returns SC_ERR_NULL for a NULL state.

sc_watchdog_init sets elapsed to 0 and tripped to false.

sc_watchdog_kick shall set the elapsed count to 0 for a non-NULL state and do nothing for a NULL state. It shall not clear the tripped flag.

sc_watchdog_kick returns without effect when state is NULL.

sc_watchdog_kick sets elapsed to 0 for a non-NULL state, leaving tripped unchanged.

sc_watchdog_tick shall return SC_WATCHDOG_TRIPPED without modifying the state when either cfg or state is NULL.

sc_watchdog_tick returns SC_WATCHDOG_TRIPPED without modifying the state when cfg or state is NULL.

When neither argument is NULL, sc_watchdog_tick shall increment the elapsed count by one while it is below cfg->timeout and leave it at cfg->timeout once reached, shall set the tripped flag when the elapsed count reaches cfg->timeout, and shall return SC_WATCHDOG_TRIPPED if the tripped flag is set or SC_WATCHDOG_OK otherwise. The increment shall not overflow.

When elapsed < timeout, sc_watchdog_tick increments elapsed by one (widened to unsigned for the sum so the uint16_t store cannot overflow); otherwise it leaves elapsed at timeout.

After the increment, sc_watchdog_tick sets tripped when elapsed >= timeout; no path in sc_watchdog_tick or sc_watchdog_kick clears it.

sc_watchdog_tick returns SC_WATCHDOG_TRIPPED when tripped is set, otherwise SC_WATCHDOG_OK.

Once set, the tripped flag shall remain set until sc_watchdog_init is called; neither a kick nor an in-deadline tick shall clear it. sc_watchdog_expired shall return true exactly while the flag is set for a non-NULL state, and false for a NULL state.

After the increment, sc_watchdog_tick sets tripped when elapsed >= timeout; no path in sc_watchdog_tick or sc_watchdog_kick clears it.

sc_watchdog_expired returns true only when state is non-NULL and state->tripped is set.