From the 101 lk/man/pth code-gen sources: 63 tasks (C11 36, C++17 27, 11 canonical families), 38 skipped for scope or duplication. Each task has at least one independent contract-edge defect, boundary types rotate, and public docs state trap clauses as plain contract prose. Claude reviewed 63/63 USABLE against current digests. Difficulty is unmeasured. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
11 KiB
Library and observation contract
C01. dma.h defines the public C11 ABI. Unsigned fields have the C unsigned range and addresses/lengths have the uint64_t range. Calls use live, nonoverlapping objects and valid input byte spans; no thread safety or timing behavior is required. All required pointer arguments must be non-NULL. Invalid arguments return -22 without output writes or callbacks. Read-only inputs must never be changed. Unless explicitly described otherwise, failed operations leave outputs and state unchanged.
C02. Error constants are 0=OK, -5=IO, -11=AGAIN, -22=INVALID, -28=NOSPACE, -34=RANGE, -95=UNSUPPORTED. A backend setter returns one of 0, -11, -95. The supplied backend is deterministic and callbacks cannot fail during restore. dma_error_name(error) returns the listed name for each constant and UNKNOWN for any other int.
C03. dma_mask(bits,out) accepts bits 1..64, writes the low bits bits set to 1, and returns 0. Invalid widths or NULL output return -22. At 64 the mask is UINT64_MAX.
C04. dma_fits(bits,address,length) returns -22 for an invalid width; otherwise it returns 1 iff address <= mask and either length is zero or the entire inclusive interval [address,address+length-1] fits the mask without arithmetic overflow. It returns 0 otherwise. A zero-length interval still requires an in-range starting address.
C05. dma_window(bits,address,length,alignment,boundary,last) first validates width 1..64, last non-NULL, positive length, power-of-two alignment 1..4096, boundary either zero or a power of two <=2^32, and address divisible by alignment. Any such violation is -22, taking priority over range errors. It then returns -34 if the interval does not fit the mask or, for nonzero boundary, address/boundary != last/boundary. Success writes inclusive last=address+length-1 and returns 0. Error leaves last unchanged.
C06. A backend holds opaque context plus streaming(context,bits), coherent(context,bits), restore(context,old_streaming,old_coherent) callbacks. Context itself may be NULL. dma_device_bind(device,backend,streaming_bits,coherent_bits) validates all three callback pointers and widths 0..64, stores a copy of the backend and the initial pair, marks bound=1, and returns 0. It calls no callbacks. Width 0 means disabled and is legal only for an initial/restored value. The caller makes backend physical state agree with the initial pair; rebinding is allowed and replaces the old backend without invoking it.
C07. A valid device has bound exactly 1, all callbacks present and both stored widths in 0..64. dma_device_state(device,s,c) validates the device and both output pointers, then writes the current stored widths and returns 0. Invalid/unbound devices return -22. dma_device_pair(device,bits) validates the device and bits 1..64 before any side effect.
C08. Every pair attempt invokes streaming first. On streaming success it invokes coherent. It never invokes coherent after a streaming failure. Both success commits both stored widths=bits and returns 0; even an already equal pair still invokes both setters. On either failure it invokes restore exactly once with the pair at entry, retains the stored pair, and returns the failing setter's error. No other callback is permitted. This applies even when the failing setter made no change. The physical and stored pair must agree after each attempt.
C09. dma_policy has widths[8], count and retries. dma_policy_validate(policy) returns 0 iff count is 1..8, the first count widths are 1..64 in strictly decreasing order, and retries is 0..8; otherwise -22. Tail widths beyond count are ignored. It never writes the policy.
C10. dma_policy_limit(policy,out) validates policy and out, writes count*(retries+1), returns 0. dma_policy_contains(policy,bits) validates policy and queried bits 1..64, then returns 1 if bits is in the first count entries, 0 if absent, -22 on invalid input. Limit's output is unchanged on error.
C11. dma_negotiate(device,policy,result) validates all arguments before any callbacks or result writes. It visits exactly the explicit widths in order: no inserted widths, no sorting or deduplication. For each candidate it attempts a pair once plus at most retries additional attempts. Only -11 is retried at the same width. -95 immediately moves to the next candidate. A final -11 after exhausting that width also moves to the next candidate. Never restart the budget on a coherent failure; a retry starts again with streaming.
C12. First successful pair ends negotiation and returns 0, with result status=0, bits=the chosen width, selected_index=its zero-based policy index, attempts=number of pair attempts actually started across all candidates, last_error=0. All candidates failing returns -5, with result status=-5, bits=0, selected_index=-1, attempts=actual total, last_error=last failing setter result (-11 or -95). The entry pair is preserved when all candidates fail. Result on any valid negotiation is fully replaced. Failure consumption in the backend remains consumed; restore only restores widths. The same device and backend may be reused by later pair/negotiate calls.
C13. dma_policy_parse(text,length,out) parses an explicit ASCII span of length 1..256. NUL and bytes >127 are invalid, and the span need not have a terminator. The grammar is exactly two fields in either order, separated by one semicolon: widths = D[,D...] ; retries = D. Spaces, tabs, CR and LF may surround keys, =, numbers, commas, semicolon and the entire span. No whitespace may occur inside a key or decimal number. D is one or more decimal digits, including leading zeros; no signs or other numeric syntax. Both keys are mandatory and case-sensitive; duplicates, unknown keys, empty fields, trailing semicolon or trailing junk are invalid. The resulting policy must satisfy C09. All parse errors return -22 and preserve the entire output policy and input bytes. Success returns 0, replaces count/retries/first count widths, and zeroes all unused widths.
C14. dma_result_json(result,buffer,capacity) accepts only result shapes described here: success has status=0, bits 1..64, selected_index 0..7, attempts 1..72, last_error=0; failure has status=-5, bits=0, selected_index=-1, attempts 1..72, last_error any negative int. Other shapes return -22. buffer must be non-NULL, even at capacity zero. Success writes a UTF-8 JSON object with exactly integer fields status,bits,selected_index,attempts,last_error and a NUL terminator, returns the byte count before NUL, and does not write beyond it. Field order and JSON whitespace may vary. If capacity cannot hold that representation and NUL, return -28 without any buffer changes. Capacities 0 or 1 cannot hold a valid object; capacity 256 can hold every valid result. Other capacities may be judged against the chosen representation. All error returns preserve the full buffer.
C15. The fixed simulator stores streaming and coherent caps 0..64, physical widths, and a transient budget per channel and width. Setters reject widths outside 1..64 with -22; then widths above that channel's cap with -95 without consuming transient budget; then consume one available transient failure and return -11; otherwise update that physical width and return 0. Its ledger records every setter as [channel,width,0,status], channel 0 streaming or 1 coherent. Restore unconditionally installs the two saved widths and records [2,old_streaming,old_coherent,0]. Budgets are not restored. Ledger length is counted by actual callbacks, independently of result.attempts.
C16. The console has two independent slots, initially unbound with zero stored/physical widths. Commands use ASCII decimal tokens and line separators; all uint64_t values fit that range. Slot is 0 or 1, channel is 0 or 1, F's width is 1..64, failures is 0..9, J's capacity is 0..256. These command envelope restrictions are guaranteed. Bad library parameters (invalid widths/count/retries etc.) are deliberately supported and return the errors above. It emits one JSON array per record and exits 0 on complete valid records, regardless of library return values. JSON numbers must have integer type; booleans are not integers. stderr has no format or encoding restrictions.
C17. I slot stream_cap coherent_cap stream_initial coherent_initial replaces that simulator with zero budgets/ledger and calls bind. P slot bits clears ledger then calls pair. N slot nonce count retries w0 w1 w2 w3 w4 w5 w6 w7 clears ledger and calls negotiate with a result whose five fields initially equal nonce (nonce <=2^31-1). I/P output is [return,stored_s,stored_c,physical_s,physical_c,ledger,ledger_count]; N prepends return and all five result fields, then the same stored/physical/ledger fields. Initial widths supplied to I are 0..64, and caps need not admit them: restoring an old configuration always works. Q slot nonce calls state with both outputs initially nonce and emits [return,streaming_output,coherent_output]. F slot channel width failures overwrites only that transient budget and emits [0]. F does not call library functions.
C18. L nonce query_bits count retries w0...w7 emits [validate_return,limit_return,limit_output,contains_return]; limit_output starts at nonce. X nonce hex parses the bytes represented by hex (- means empty). Its policy count,retries and all eight widths initially equal nonce; output is [return,count,retries,w0,...,w7,before_hash,after_hash]. Hash is FNV-1a 64 with offset 14695981039346656037 and prime 1099511628211, reduced modulo 2^64. X supports spans up to 1024 bytes to observe over-limit rejection.
C19. M bits nonce64 emits [mask_return,mask_output], output initially nonce64. T bits address length emits [fits_return]. W bits address length alignment boundary nonce64 emits [window_return,last_output], last initially nonce64. J status bits selected_index attempts last_error capacity starts 512 bytes at 0x5a and emits [json_return,hex_of_all_512_buffer_bytes]. E signed_error emits [error_name]. V emits the raw return/output list from the public console's NULL, missing-callback, unbound-device and invalid-initial-width calls; invalid calls follow C01/C06/C07 and leave the initialized outputs unchanged. Its final valid bind uses a NULL backend context (with no callback invocation), then reports the replacement state, context/bound flags and callback counts before/after. See console.c for their order; it contains no expectations.
C20. Build and grading compile the supplied observation console and simulator together with the six collected files using gcc -std=c11 -O2 -Wall -Wextra -pedantic. No download or nonstandard library is available. Builds must succeed and the process must complete its input within 15 seconds; compile timeout is 25 seconds. Only observed semantic behavior is judged, no specific source patch or algorithm. Inputs may combine library calls across both instances and reuse their state.