GrayGyre is a tiny C data-placement primitive that spreads locally adjacent indices across logical cells/pages using a self-inverse Gray-code shear.
It is deterministic, allocation-free, table-free, integer-only and has no hidden state. The configured map is branchless. GrayGyre is not encryption, cryptography, a hash, wear leveling, error correction or a full-cycle scheduler.
#include "graygyre.h"
graygyre_config cfg;
graygyre_config_init(&cfg, 256, 4); /* 16-element logical cells */
uint32_t physical = graygyre_map_config(logical, &cfg);
uint32_t original = graygyre_map_config(physical, &cfg);The second call restores logical because the transform is an involution.
The transform keeps the local offset and XORs its Gray code into the cell bits. This can help deterministic record placement, page/bank spreading, DMA descriptor placement and burst interleaving without tables or allocation.
- ESP32-S3 at 240 MHz, physical
-O2measurement: configured map approximately 10 cycles/index (median of five runs). - Configured kernel is branchless.
- Tested ESP32-S3
-OsELF: configured map symbol 42 B. - Hidden persistent library RAM: 0 B. Config mode uses a 12 B caller-owned object on the tested ABI.
Performance and code-size values come from different optimization profiles. See benchmarks for method and full tables.
graygyre_map() is the checked generic API. graygyre8_map(),
graygyre16_map() and graygyre32_map() select 8-, 16- and 32-element logical
cells; the number is not a C data-type width. For hot loops, initialize a
graygyre_config once and call graygyre_map_config() many times.
offset_bits is always explicit: 3 means width 8, 4 means width 16, and 5 means
width 32. GrayGyre never tunes it silently.
Because every permutation cycle has length one or two, in-place APIs swap only
pairs where i < map(i). No visited bitmap is required. u8, u16 and u32
out-of-place APIs are also provided.
cmake -S . -B build
cmake --build build
ctest --test-dir buildOr use make test and make examples.
| Target | Status |
|---|---|
| ESP32-S3 | physical performance validated |
| Cortex-M0+ | compile/static validated |
| Cortex-M4 | compile/static validated |
| Cortex-M33 | compile/static validated |
| RV32I | compile/static validated |
| RV32IM | compile/static validated |
The domain size must be a power of two. The mapping contains fixed points and is not a full-cycle traversal. See limitations.
GrayGyre is available under the MIT License.