Axiom One primitives

GrayGyre

Adjacent logical indices can cluster in the same page, bank or logical cell even when a small deterministic spread would improve placement.

An allocation-free, table-free C primitive maps indices with a self-inverse Gray-code shear, spreading local neighbours across configured logical cells while retaining an exact inverse through the same mapping call.

DevelopmentMITC99
GitHubQuick Start
Last verified
2026-08-28
Platform scope
Portable C99; caller-owned state and no dynamic allocation

What it solves

Adjacent logical indices can cluster in the same page, bank or logical cell even when a small deterministic spread would improve placement.

How it works

1Logical index→2Gray-code shear→3logical cell + local offset→4physical index

Use it when

Spread deterministic record placement across logical pages or banks
Place DMA descriptors or burst-interleaved data without lookup tables
Map an index repeatedly in a hot loop after one configuration step
Permute an array in place without a visited bitmap

Quick Start

#include "graygyre.h"

graygyre_config cfg;
graygyre_config_init(&cfg, 256u, 4u);
uint32_t physical = graygyre_map_config(logical, &cfg);
uint32_t original = graygyre_map_config(physical, &cfg);
/* original == logical: the transform is self-inverse. */

Engineering evidence

  • Configured mapping is branchless, integer-only and has no hidden state
  • ESP32-S3 hardware measurements and a tested configured-map size are documented separately from optimisation-profile caveats
  • Cortex-M0+/M4/M33 and RV32I/RV32IM are documented as compile/static-validated targets

Known limits

  • Not encryption, cryptography, hashing, wear levelling, error correction or a full-cycle scheduler
  • The domain size must be a power of two
  • The mapping contains fixed points; it is a placement permutation, not a traversal order