Skip to content

API.md

Latest commit

 

History

History
73 lines (55 loc) · 2.75 KB

API.md

File metadata and controls

73 lines (55 loc) · 2.75 KB
Raw

API reference

Domain and errors

A valid domain has power-of-two count, index < count, and 1 <= offset_bits < log2(count). Checked map functions return GRAYGYRE_ERROR (UINT32_MAX) on invalid input. Config initialization and buffer functions return 0 on success and -1 on invalid input.

All operations are O(1) per mapped index. Generic/fixed mapping has no persistent state. Config mode uses a caller-owned graygyre_config (12 B on the validated host and ESP32-S3 ABIs). Hidden library persistent RAM is 0 B.

graygyre_map and graygyre_unmap

uint32_t graygyre_map(uint32_t index, uint32_t count, uint8_t offset_bits);
uint32_t graygyre_unmap(uint32_t index, uint32_t count, uint8_t offset_bits);

Checked generic mapping. unmap calls the same transform because GrayGyre is self-inverse. Example: graygyre_map(7, 256, 4).

Fixed cell variants

uint32_t graygyre8_map(uint32_t index, uint32_t count);
uint32_t graygyre16_map(uint32_t index, uint32_t count);
uint32_t graygyre32_map(uint32_t index, uint32_t count);

Checked maps for offset_bits 3, 4 and 5. The suffix is logical cell width in elements, not element type width. They return GRAYGYRE_ERROR on invalid input.

Configured hot path

int graygyre_config_init(graygyre_config *cfg, uint32_t count,
                         uint8_t offset_bits);
uint32_t graygyre_map_config(uint32_t index, const graygyre_config *cfg);

graygyre_config_init exhaustively validates the domain and derives masks. graygyre_map_config is the branchless, unchecked hot path: cfg must point to a successfully initialized object and index must be in its original domain. Violating those preconditions is outside the API contract. Use init once, map many. The config is immutable during mapping and may be shared read-only.

In-place buffers

int graygyre_u8_inplace(uint8_t *data, uint32_t count, uint8_t offset_bits);
int graygyre_u16_inplace(uint16_t *data, uint32_t count, uint8_t offset_bits);
int graygyre_u32_inplace(uint32_t *data, uint32_t count, uint8_t offset_bits);

Reorders the caller-owned buffer using one temporary element and pair swaps. Calling it twice restores the original order. It allocates no auxiliary buffer.

Out-of-place buffers

int graygyre_u8_out(uint8_t *dst, const uint8_t *src, uint32_t count,
                    uint8_t offset_bits);
int graygyre_u16_out(uint16_t *dst, const uint16_t *src, uint32_t count,
                     uint8_t offset_bits);
int graygyre_u32_out(uint32_t *dst, const uint32_t *src, uint32_t count,
                     uint8_t offset_bits);

Writes src[i] to dst[map(i)]. Source and destination must not overlap; equal pointers are rejected. Apply the same operation again with exchanged buffers to restore logical order.