Every public symbol, grouped by task, one line each. The headers are the
reference: each entry’s Doxygen comment carries the full contract, and CI
fails if a public symbol lacks one or is missing from this page. Return codes
are collected at the end.
Header
Include when
crumbs.h
always — context, codec, dispatch, controller, scanners, raw I²C helpers
crumbs_message_helpers.h
building or reading payloads
crumbs_ops.h
defining a family: identity, payload codecs, controller-side wrappers
Header-declared length of a possibly padded read, for callers that decode raw reads themselves. -1 for NULL args, fewer than 4 bytes, data_len > 27, or a buffer shorter than its header declares. — crumbs.h
crumbs_crc8(data, len) → crumbs_crc8_t
CRC-8/SMBUS (poly 0x07, init 0). Returns 0 for NULL or empty input. — crumbs_crc.h
Payload helpers — crumbs_message_helpers.h
All static inline. Multi-byte integers are little-endian; floats are 4 native
bytes. Every add fails atomically with -1 when the payload would exceed 27
bytes; every read fails with -1 when offset + width > len.
Decode → type check → SET_REPLY intercept → on_message → matching handler. 0, -1, -2, or CRUMBS_RX_TYPE_MISMATCH. The HAL calls this from its receive callback.
Reply handler for the requested opcode, else on_request, else nothing (*out_len = 0, returns 0). -1 bad args, -2 encode failed. The HAL calls this from its request callback.
Encode and write one frame. -1NULL args, -2 wrong role, -3 encode failed, otherwise the HAL write’s return verbatim (0 = success; a HAL’s own negative codes can collide with those three).
crumbs_controller_read plus an identity check; CRUMBS_RX_REPLY_MISMATCH with out_msg still filled. expect_type_id == CRUMBS_TYPE_ID_ANY skips the type half; the opcode is always compared.
CRUMBS_RX_REPLY_MISMATCH
-7.
crumbs_device_t
ctx, addr, write_fn, read_fn, delay_fn, io: one bound target for the wrappers and raw helpers.
Whether dev has what a send (context + write) or a get (also read + delay) needs.
CRUMBS_DEFINE_FAMILY(PREFIX, type_id, OPS)
From an X(NAME, value) list: PREFIX_TYPE_ID and one enum constant per opcode. Fails the build if the type is not 0x01–0xFF, an opcode is above 0xFF or is 0xFE, or two opcodes share a value.
CRUMBS_DEFINE_PAYLOAD(name, wire_bytes, FIELDS)
From an X(type, name) list (u8 u16 u32 i8 i16 i32 float, wire order): name_t, name_wire_size, name_pack(msg, *v) (appends; -1 if it would exceed 27) and name_unpack(data, len, *v) (-1 if len < name_wire_size; longer accepted). Fails the build if the list does not sum to wire_bytes or wire_bytes exceeds 27. name_unpack is a parse_fn for CRUMBS_DEFINE_GET_OP.
CRUMBS_STATIC_ASSERT(cond, msg)
static_assert / _Static_assert, usable at file scope in C11 and C++11.
Defines family_send_name(dev, param): one SET with one parameter, usually a payload struct pointer and its _pack call. -1 for an unbound device or when pack_stmt returns non-zero, else the send code.
Read each address and count it if the bytes decode as a frame; non-strict (with ctx and write_fn given) also writes 00 00 00 00 to addresses whose read did not decode and retries — a peripheral dispatches that as an opcode-0x00 SET. Returns the count (stops at max_found), -1 bad args. timeout_us goes to every read. — crumbs.h
Register access with an arbitrary-width register address; a write with both parts is staged in a buffer of CRUMBS_I2C_DEV_MAX_WRITE (64 unless the library is built with another value).
major × 10000 + minor × 100 + patch, for #if comparisons and the version reply. — crumbs_version.h
Return codes
Range
Meaning
0
Success; scanners return a count ≥ 0, and a HAL read returns its byte count, so 0 there means nothing was read.
-1 … -6
Function-specific: -1 bad argument / wrong role / structural decode failure; -2 CRC (codec), wrong role (send), address select (Linux); -3 encode failed (send), read/write failed (Linux), read callback failed (helpers); -4 short read/write; -5 no repeated start; -6 too long for a buffer. The tables above give each function’s own set.