amos 73a5240295 Batches 21 and 18: add 74 calibrated tasks (40 Bos redo, 34 HWE code-gen)
Batch 21 (20261027-A-bos-redo-21) rebuilt 40 of the 53 rejected Bos-qiao
environments: hidden assertions that ran inside the candidate's process
now run in a trusted parent that reads observations from a low-UID
worker; gold bytes are unchanged. 9 were excluded for scope (ROS2,
oversize, security core), 3 are blocked because the source requires an
exec bit the platform does not freeze, 1 lacks requests/bs4 in trace6.

Batch 18 (20261026-C-hwe-codegen-18) adds its last 34 of 134 tasks; the
first 100 landed in 2f32624d.

Claude reviewed 74/74 USABLE against current digests, canonical
families, no ID or source overlap with main, plain public docs. Only the
new task directories are taken; the stale pre-batch-20 copies of
concur-release-capsule and resource-temp-link on the batch 21 branch and
both branches' progress notes stay as main has them. Difficulty is
unmeasured.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-02 10:23:12 +08:00

6.7 KiB

ADC scan software contract

This project models bytes and scan results in memory. It performs no device access. All rules in this document apply to the implementation. AdcFrame, AdcReading, AdcStatus and the function declarations in adc.h define the public C11 API. Adc is concrete object storage whose internal types and layout may be changed while preserving the public interfaces and observable behavior. Each Adc is independent, including two live objects with identical configurations. Callers supply valid, nonoverlapping pointers; object operations other than reset and the text interface receive initialized objects. Only the listed functions are public.

Frames

adc_encode(channel,out) accepts channels 0 through 7 and writes b0=1, b1=(8|channel)<<4, b2=0. Other channel integers return ADC_RANGE and leave out unchanged.

adc_decode(b0,b1,b2,out) accepts each byte from 0 through 255. It writes ((b1 & 3)<<8)|b2; b0 and the upper six bits of b1 do not contribute to the value. An out of range byte returns ADC_RANGE and leaves out unchanged.

Objects and results

adc_reset(adc) initializes or replaces the object with vref=3300000 microvolts, mask=255, rounds=1 and empty results. The object is inactive, next_channel=-1, completed_rounds=0 and frames=0.

adc_config(adc,vref,mask,rounds) accepts vref from 1 through 5000000, mask from 1 through 255, and rounds from 1 through 32. Invalid parameters return ADC_RANGE. Otherwise an active object returns ADC_BUSY. On success configuration is replaced and all results, frames and completed_rounds are cleared, leaving the object inactive with next_channel=-1.

adc_start(adc) returns ADC_BUSY if active. Otherwise it clears previous results, frames and completed_rounds, activates the scan and selects the lowest numbered channel whose bit is set in mask. Each round visits selected channels in increasing order; all rounds use the configured mask. Results belong to the most recent start or configuration, and partial results can be read before completion.

adc_tx(adc,out) returns ADC_IDLE if inactive and leaves out unchanged. Otherwise it writes the command frame for next_channel using adc_encode. Repeated calls do not advance or change the object.

adc_feed(adc,b0,b1,b2) validates all bytes as adc_decode does; invalid bytes return ADC_RANGE. If the bytes are valid but the object is inactive it returns ADC_IDLE. Success decodes one sample, appends it to the next channel, and advances to the next selected channel. After the last selected channel a round is completed; after the configured number of rounds the object becomes inactive and next_channel=-1. frames counts accepted samples since the last clearing operation, and completed_rounds counts fully accepted rounds. Further feed calls leave completed results intact.

adc_abort(adc) returns ADC_IDLE if inactive. Success stops an active scan, sets next_channel=-1, and retains partial results, frames and completed_rounds. A later start begins a new scan with empty results.

adc_read(adc,channel,out) accepts channel integers 0 through 7, returning ADC_RANGE otherwise. A channel with no accepted sample returns ADC_EMPTY. In either case out is unchanged. Success writes count, sum, minimum, maximum, last and microvolts for that channel. microvolts is floor(sumvref/(count1023)), evaluated with integer arithmetic without intermediate rounding; all other fields describe raw decoded samples. A channel need not be selected in the current mask to be queried.

adc_status(adc,out) writes vref, mask, rounds, active, next_channel, completed_rounds and frames. active is 0 or 1. It changes no object state and can be called repeatedly.

adc_clear(adc) returns ADC_BUSY while active. Otherwise it clears every reading, frames and completed_rounds, retains configuration, and sets next_channel=-1. Repeated clear calls succeed. Every unsuccessful API operation preserves the entire observable object and any output argument. ADC_OK=0, ADC_RANGE=1, ADC_BUSY=2, ADC_IDLE=3 and ADC_EMPTY=4. Other values are not API results. Successful codec and object operations returning int return ADC_OK; reset and status return void. The text interface returns its response count as described below.

Text interface

adc_run_cli(input,output,result) initializes result with adc_reset on every call and processes commands on that object. On return result retains the final state and readings for ordinary API access. It reads physical lines separated by LF; the last nonempty physical line is accepted without LF. Empty input produces no output. It handles at most 128 physical lines. If another physical line is encountered, it writes ERR LIMIT followed by LF and stops without executing that line. Its return value is the number of response lines written, including the LIMIT response. A final LF does not create an additional empty physical line.

Each ordinary line has at most 255 bytes before LF. Longer lines produce ERR SYNTAX and are consumed through LF or EOF as one physical line. NUL and bytes outside printable ASCII, space and tab produce ERR SYNTAX. Tokens are separated by space or tab; leading and trailing separators are allowed. Verb names are lowercase. Numeric tokens contain decimal digits, optionally preceded by minus, and represent a native signed 32-bit int. Leading zeroes and negative zero are accepted. Plus, missing digits, and values outside -2147483648 through 2147483647 produce ERR SYNTAX. Empty lines, unknown verbs, and a wrong number of arguments produce ERR SYNTAX. Syntax errors leave the local object unchanged.

The verbs are config VREF MASK ROUNDS, start, tx, feed B0 B1 B2, read CHANNEL, state, abort and clear. They call the corresponding API after all syntax checks. API failure writes ERR NAME followed by LF, where NAME is RANGE, BUSY, IDLE or EMPTY. The four mutating verbs config, start, feed, abort and the clearing verb clear write OK followed by LF on success.

Successful tx writes TX B0 B1 B2 followed by LF. Successful read writes READ COUNT SUM MINIMUM MAXIMUM LAST MICROVOLTS followed by LF. state writes STATE VREF MASK ROUNDS ACTIVE NEXT_CHANNEL COMPLETED_ROUNDS FRAMES followed by LF. Fields use canonical decimal integers separated by single spaces, with no trailing spaces. Each processed physical line writes one response. adc_run_cli writes only the specified bytes to the supplied output stream and emits no diagnostics; stdout bytes occur only when output is stdout. It writes nothing to stderr. It does not close either supplied FILE. Calls using separate streams in one process are independent.

The executable in main.c passes stdin/stdout and a result object to adc_run_cli and exits 0, including on erroneous input and LIMIT. It writes no other stdout bytes and no stderr bytes. Builds require C11 and the standard C library only.