36-wonderphi

Description

WonderPhi — Universal Permanent Driver for 142 AutoPhi ICs

WonderPhi is a complete, three-layer hardware/firmware/software driver system governing all 142 AutoPhi integrated-circuit designs across 14 IC categories. The driver is locked at version 1.0.0 permanently—enforced at compile time by _Static_assert and burned into silicon as Verilog localparam values. It shall never be updated, patched, or amended. Its constitutional law is the 10 Commandments, a set of immutable rules encoded in C #define constants, Verilog hardware parameters, and runtime enforcement logic at every layer of the stack. The package also includes a Python+ChromaDB RAG (Retrieval-Augmented Generation) application for querying the AutoPhi PCB-design knowledge base.

Author: Christopher G. Brown. Company: AutoPhi. Version: 1.0.0 (PERMANENT). Date: 2026-04-05.

The 10 Commandments — The Constitution

Every commandment is defined as a C #define constant in commandments.h and mirrored as a Verilog localparam in autophi_commandments.v . The commandment checksum is the XOR of all ten commandment codes, verified at boot and queryable at runtime. The total count is enforced by _Static_assert(AUTOPHI_NUM_COMMANDMENTS == 10) .

# Commandment Principle Key C Constants

I "I am the Lord thy God" This driver is the sole master controller. No other driver shall control AutoPhi ICs. #define COMMANDMENT_ONE_MASTER 0x00000001

II "Thou shalt have no other gods before me" No secondary or competing driver shall be loaded. Exclusive lock enforced. #define COMMANDMENT_NO_OTHER_DRIVERS 0x00000002

III "Thou shalt not take the name of the Lord in vain" Every command must be validated. Reject invalid/malformed requests. #define COMMANDMENT_VALID_COMMANDS_ONLY 0x00000003

IV "Remember the Sabbath day, to keep it holy" Mandatory low-power sleep cycles. The driver shall rest when idle. #define COMMANDMENT_POWER_REST 0x00000004

V "Honour thy father and thy mother" Full backwards compatibility with all 142 AutoPhi IC designs. #define COMMANDMENT_HONOUR_LEGACY 0x00000005

VI "Thou shalt not kill" Never corrupt, erase, or destroy data. All writes are atomic and CRC-32 verified. #define COMMANDMENT_NO_DESTROY 0x00000006

VII "Thou shalt not commit adultery" Strict protocol adherence. Never deviate from spec. #define COMMANDMENT_FAITHFUL_PROTOCOL 0x00000007

VIII "Thou shalt not steal" Never consume more resources than allocated. #define COMMANDMENT_NO_STEAL_RESOURCES 0x00000008

IX "Thou shalt not bear false witness" Status registers and health checks shall always report truthfully. #define COMMANDMENT_HONEST_STATUS 0x00000009

X "Thou shalt not covet" Fully self-contained. No external dependencies. No dynamic allocation. No floating point. #define COMMANDMENT_SELF_CONTAINED 0x0000000A

Enforcement: the commandment checksum is computed as the XOR of all ten codes ( AUTOPHI_COMMANDMENT_CHECKSUM ). At initialization, the firmware reads the hardware commandment register, compares it against the computed checksum, verifies the driver signature ( 0x4155544F ^ 0x50484921 ), and verifies the locked version. Any mismatch returns AUTOPHI_ERR_COMMANDMENT (-8) .

All 142 ICs — 14 Categories

The complete IC configuration table is defined in autophi_ic_table.h as a static array of 142 autophi_ic_desc_t descriptors. Each entry carries: IC ID (1–142), category code, supported-interface flags, preferred interface, register-map size, maximum clock frequency (MHz), base register address (32-bit), and a human-readable name string. Every IC supports all four bus interfaces (SPI, I2C, UART, Custom Bus) via the IC_SUPPORTS_ALL flag. The 14 category identifiers are defined as hex codes 0x01 through 0x0E .

Category Code IC Range Count Key Capability Preferred Bus Example IC Names

Quantum Computing Cores 0x01 1–20 20 4,096 qubits; qubit arrays, error correction, surface codes, quantum memory, control/readout, Josephson junctions, cryogenic interfaces, logical qubits Custom Bus AQCHS-QUBIT-ARRAY-0 through -3, AQCHS-ERROR-CORRECT-0/-1, AQCHS-SURFACE-CODE-0/-1, AQCHS-QUANTUM-MEMORY-0 through -3, AQCHS-CONTROL-READOUT-0/-1, AQCHS-JOSEPHSON-JNC-0/-1, AQCHS-CRYO-INTERFACE-0/-1, AQCHS-LOGICAL-QUBIT-0/-1

Photonic Interconnect 0x02 21–35 15 150 TB/s bandwidth; WDM multiplexers/demultiplexers, waveguide controllers, laser drivers, photodetectors, optical switches, power monitor Custom Bus PHOTON-WDM-MUX-0/-1, PHOTON-WDM-DEMUX-0/-1, PHOTON-WAVEGUIDE-CTRL-0 through -3, PHOTON-LASER-DRIVER-0/-1, PHOTON-PHOTODETECT-0/-1, PHOTON-OPTICAL-SWITCH-0/-1, PHOTON-POWER-MONITOR

Neuromorphic AI Engine 0x03 36–50 15 1,000,000+ neurons; spike arrays, synapse controllers, STDP learning, event routers, dendrite processors, axon drivers, homeostasis Custom Bus NEURO-SPIKE-ARRAY-0 through -3, NEURO-SYNAPSE-CTRL-0/-1, NEURO-STDP-LEARN-0/-1, NEURO-EVENT-ROUTER-0/-1, NEURO-DENDRITE-PROC-0/-1, NEURO-AXON-DRIVER-0/-1, NEURO-HOMEOSTASIS

AI Accelerator 0x04 51–70 20 32,768+ TOPS; matrix engines, 512-bit vector processors, transformer attention units, multimodal fusion, activation functions, weight memory, gradient engine, batch scheduler Custom Bus AI-MATRIX-ENGINE-0 through -3, AI-VECTOR-PROC-512B-0 through -3, AI-TRANSFORMER-ATTN-0 through -3, AI-MULTIMODAL-FUSE-0/-1, AI-ACTIVATION-FUNC-0/-1, AI-WEIGHT-MEMORY-0/-1, AI-GRADIENT-ENGINE, AI-BATCH-SCHEDULER

Memory Controllers 0x05 71–80 10 LPDDR5 + quantum memory interfaces; NVMe encrypted storage, cache coherence, ECC engine, DMA controller Custom Bus MEM-LPDDR5-CTRL-0/-1, MEM-QUANTUM-IFACE-0/-1, MEM-NVME-ENCRYPT-0/-1, MEM-CACHE-COHERENCE-0/-1, MEM-ECC-ENGINE, MEM-DMA-CONTROLLER

Power Management 0x06 81–90 10 Electromagnetic cooling integration; main/quantum/photonic/AI supply regulators, voltage/current monitors, thermal control, battery management, energy harvesting, sleep controller I2C PWR-MAIN-REGULATOR, PWR-QUANTUM-SUPPLY, PWR-PHOTONIC-SUPPLY, PWR-AI-SUPPLY, PWR-VOLTAGE-MONITOR, PWR-CURRENT-MONITOR, PWR-THERMAL-CTRL, PWR-BATTERY-MGMT, PWR-ENERGY-HARVEST, PWR-SLEEP-CONTROLLER

I/O Controllers 0x07 91–100 10 100 GbE MAC (dual), PCIe Gen5 controller, USB4 controller, optical expansion (dual), GPIO expanders, debug console, interrupt controller Mixed (Bus/SPI/UART) IO-100GBE-MAC-0/-1, IO-PCIE-GEN5-CTRL, IO-USB4-CTRL, IO-OPTICAL-EXPANSION-0/-1, IO-GPIO-EXPANDER-0/-1, IO-DEBUG-CONSOLE, IO-INTERRUPT-CTRL

Security / Crypto Engines 0x08 101–110 10 AES-256 (dual), quantum RNG, SHA3-512, RSA-4096, ECC P-384, key store, secure boot, tamper detection, firewall Custom Bus SEC-AES256-ENGINE-0/-1, SEC-QUANTUM-RNG, SEC-SHA3-512-ENGINE, SEC-RSA4096-ENGINE, SEC-ECC-P384-ENGINE, SEC-KEY-STORE, SEC-SECURE-BOOT, SEC-TAMPER-DETECT, SEC-FIREWALL

Sensor Interfaces 0x09 111–120 10 Temperature (dual), voltage rail, current rail, optical power, magnetic field, vibration, humidity, 24-bit ADC, 16-bit DAC I2C / SPI SENS-TEMPERATURE-0/-1, SENS-VOLTAGE-RAIL, SENS-CURRENT-RAIL, SENS-OPTICAL-POWER, SENS-MAGNETIC-FIELD, SENS-VIBRATION, SENS-HUMIDITY, SENS-ADC-24BIT, SENS-DAC-16BIT

Communication Controllers 0x0A 121–130 10 Quantum links (dual), quantum entanglement engine, classical bridge, mesh routers (dual), protocol engine, CRC/checksum, serial bridge, broadcast controller Custom Bus / UART COMM-QUANTUM-LINK-0/-1, COMM-QUANTUM-ENTANGLE, COMM-CLASSICAL-BRIDGE, COMM-MESH-ROUTER-0/-1, COMM-PROTOCOL-ENGINE, COMM-CRC-CHECKSUM, COMM-SERIAL-BRIDGE, COMM-BROADCAST-CTRL

DSP Cores 0x0B 131–138 8 FFT engines (dual), filter banks (dual), correlator, modulator, waveform generator, spectrum analyzer Custom Bus DSP-FFT-ENGINE-0/-1, DSP-FILTER-BANK-0/-1, DSP-CORRELATOR, DSP-MODULATOR, DSP-WAVEFORM-GEN, DSP-SPECTRUM-ANALYZER

Electromagnetic Cooling 0x0C 139–140 2 Magnetic propulsion/torque cooling (patents 1096, 1097, 1098); primary and secondary EM cooling systems with zero moving parts I2C COOL-EMAG-PRIMARY, COOL-EMAG-SECONDARY

LED Recycle-Powered 0x0D 141–142 2 Light trigger + recycle power (patents 3561, 2876, 1026); LED recycle controller and light trigger controller with digital optics SPI LED-RECYCLE-CTRL, LED-LIGHT-TRIGGER

Miscellaneous / Utility 0x0E (reserved) 0 Reserved category identifier for future utility ICs within the permanent driver's 142-IC address space — —

Ten synthesizable Verilog modules define the silicon-level driver, operating at a default 50 MHz system clock. All commandments are encoded as localparam values that are burned into the netlist and cannot be altered post-synthesis.

# Module Name File Function

1 autophi_commandments autophi_commandments.v Immutable hardware parameters module. Defines all 10 Commandments as Verilog localparam constants, interface identifiers ( IFACE_SPI=2'b00 , IFACE_I2C=2'b01 , IFACE_UART=2'b10 , IFACE_BUS=2'b11 ), the commandment checksum (XOR of all ten codes), power states, status codes, and the locked version (1.0.0).

2 autophi_spi_driver autophi_spi_driver.v Full-duplex SPI master/slave controller. Supports 8/16/32-bit transfers. Parameters: CLK_FREQ_HZ=50000000 , SPI_FREQ_HZ=1000000 (1 MHz), FIFO_DEPTH=256 . CPOL=0, CPHA=0 hardcoded per Commandment VII. Five-state FSM: IDLE, LOAD, TRANSFER, DONE, SLEEP. Includes IC ID validation (1–142) and automatic power-state transitions (Active/Idle/Sleep/Deep Sleep).

3 autophi_i2c_driver autophi_i2c_driver.v I2C master controller with 7-bit addressing, clock stretching support, and multi-master arbitration. Parameters: CLK_FREQ_HZ=50000000 , I2C_FREQ_HZ=400000 (400 kHz). 4-phase I2C clock generation. Ten-state FSM: IDLE, START, ADDR, ADDR_ACK, WRITE, WRITE_ACK, READ, READ_ACK, STOP, SLEEP. Open-drain SDA/SCL outputs with proper tristate control.

4 autophi_uart_driver autophi_uart_driver.v Full-duplex UART transceiver. Strict 8N1 format per Commandment VII. Parameters: CLK_FREQ_HZ=50000000 , BAUD_RATE=115200 , FIFO_DEPTH=256 . Separate TX and RX state machines (4 states each: IDLE, START, DATA, STOP). RX input synchronizer for metastability protection. Mid-bit sampling for start-bit validation.

5 autophi_bus_driver autophi_bus_driver.v Custom 32-bit parallel AutoPhi interconnect bus with handshake protocol and burst transfers (up to 16-beat bursts). Parameters: ADDR_WIDTH=32 , DATA_WIDTH=32 , BURST_MAX=16 . Eleven-state FSM: IDLE, REQUEST, ADDR_PH, WRITE_PH, READ_PH, BURST_WR, BURST_RD, DONE, ERROR, RELEASE, SLEEP. Bus arbitration via request/grant handshake. Tristate data bus.

6 autophi_universal_driver autophi_universal_driver.v Top-level module. Instantiates all four interface drivers (SPI, I2C, UART, Bus) and routes transactions via a 2-bit interface-select signal. Single entry point for all 142 ICs. Output multiplexing for cmd_ready , cmd_rdata , cmd_done , global_status , and global_power_state . Exports commandment_signature = 0x4155544F ^ 0x50484921 . Health-check logic verifies all four interface status registers report no errors.

7 autophi_watchdog autophi_watchdog.v Self-healing watchdog and fault-recovery module. Configurable watchdog timeout (default 100 ms) and heartbeat period (default 10 ms). Per-interface fault detection with heartbeat monitoring. Auto-reset after 5 consecutive faults ( MAX_CONSECUTIVE_FAULTS=5 ) with a 1 ms recovery hold. 8-bit per-interface fault counters that wrap safely at 255 per Commandment X. Four independent reset outputs ( spi_reset_n , i2c_reset_n , uart_reset_n , bus_reset_n ) plus a global watchdog_reset last-resort output. System health output as a 4-bit vector (one bit per interface).

8 autophi_aes256 autophi_aes256.v Lightweight AES-256 encryption engine for securing all bus communications. 256-bit key input, 128-bit block I/O. 14-round AES-256 with full S-Box lookup table (256 entries), ShiftRows, SubBytes, AddRoundKey, and RCON constants. Constant-time operation to prevent timing side-channels. Five-state FSM: IDLE, KEY_EXP, ROUND, FINAL, DONE. Fully self-contained per Commandment X (no external crypto IP).

9 autophi_debug_port autophi_debug_port.v Dedicated diagnostic port for field deployment. Read-only access to all internal registers. Features: transaction trace buffer (circular, last 64 entries), fault log (circular, last 32 entries), real-time performance counters (total transactions, total errors, uptime in seconds), commandment violation log, periodic status heartbeat (once per second). UART-based output at 115200 baud 8N1. Debug query interface with register map: 0x00 =Signature, 0x01 =Version, 0x02 =Uptime, 0x10 =Active interface, 0x11 =Active IC, 0x12 =Status, 0x13 =Power state, 0x20 =Interface health, 0x21 =System healthy, 0x30 =Transaction count, 0x31 =Error count, 0x40-0x43 =Per-interface fault counts, 0x50-0x51 =Last trace entry, 0xF0 =Commandment count (10), 0xFF =End marker ( 0xDEADC0DE ).

10 autophi_testbench autophi_testbench.v Comprehensive verification testbench. 20 test cases covering all 10 Commandments: driver signature verification, exclusive interface selection, invalid IC ID rejection (0 and 143), valid IC ID acceptance (1 and 142), power-state transitions, health check, SPI chip-select assertion, SPI transfer-in-progress, UART TX idle-high, AutoPhi Bus request/grant/ACK flow, interface switching across all four buses, reset/recovery behavior. 50 MHz clock (20 ns period), 5 ms simulation timeout. VCD waveform dump support.

Layer 2 — Firmware (Embedded C)

Thirteen C source files implement the firmware layer, running on the embedded processor. All memory is statically allocated per Commandment VIII and X. No dynamic allocation, no floating point, no external dependencies.

# File Function

1 autophi_fw_core.h Core firmware header. Defines the memory-mapped register map at base address 0x40000000 : AUTOPHI_REG_SIGNATURE (0x40000000), AUTOPHI_REG_VERSION (0x40000004), AUTOPHI_REG_STATUS (0x40000008), AUTOPHI_REG_CONTROL (0x4000000C), AUTOPHI_REG_IC_ID (0x40000010), AUTOPHI_REG_IFACE_SEL (0x40000014), AUTOPHI_REG_CMD_ADDR (0x40000018), AUTOPHI_REG_CMD_WDATA (0x4000001C), AUTOPHI_REG_CMD_RDATA (0x40000020), AUTOPHI_REG_CMD_CTRL (0x40000024), AUTOPHI_REG_POWER_STATE (0x40000028), AUTOPHI_REG_HEALTH (0x4000002C), AUTOPHI_REG_COMMANDMENTS (0x40000030), AUTOPHI_REG_CRC (0x40000034). Control bits: ENABLE, RESET, START_CMD, WRITE_MODE, HEALTH_CHECK. Status bits: READY, BUSY, ERROR, CMD_DONE, HEALTH_OK. TX/RX buffers: 4096 bytes each. Error codes: NONE(0) through NOT_INITIALIZED(-10). Declares core API: autophi_fw_init() , autophi_fw_health_check() , autophi_fw_verify_commandments() , autophi_fw_select_interface() , autophi_fw_get_status() , autophi_fw_enter_sleep() , autophi_fw_wake() , autophi_fw_read() , autophi_fw_write() .

2 autophi_fw_core.c Core firmware implementation. Boot sequence: verify sole master (Commandment I), write driver signature, set version, verify all 10 commandments, initialize SPI/I2C/UART/Bus interfaces, run health check, enable driver. Universal read/write dispatches to the active interface. Write path: compute CRC-32 before write, dispatch, then read-back and verify CRC match (Commandment VI). Static state: s_initialized , s_active_iface (default SPI), s_power_state , 4096-byte TX and RX buffers.

3 autophi_fw_spi.h SPI firmware header. SPI register map at base 0x40001000 : CTRL, STATUS, TXDATA, RXDATA, CLK_DIV, CS (offsets 0x00–0x14). Control bits: ENABLE, START, CPOL, CPHA. Status bits: READY, BUSY, DONE. Declares autophi_fw_spi_init() , autophi_fw_spi_read() , autophi_fw_spi_write() , autophi_fw_spi_transfer() .

4 autophi_fw_spi.c SPI firmware implementation. Byte-level SPI transfer routines with IC ID validation and CRC verification.

5 autophi_fw_i2c.h I2C firmware header. Declares autophi_fw_i2c_init() , autophi_fw_i2c_read() , autophi_fw_i2c_write() .

6 autophi_fw_i2c.c I2C firmware implementation. 7-bit address transactions with ACK/NACK handling.

7 autophi_fw_uart.h UART firmware header. Declares autophi_fw_uart_init() , autophi_fw_uart_send() , autophi_fw_uart_receive() .

8 autophi_fw_uart.c UART firmware implementation. 8N1 send/receive with bounded timeout loops.

9 autophi_fw_bus.h Custom Bus firmware header. Bus register map at base 0x40004000 : CTRL, STATUS, ADDR, WDATA, RDATA, BURST_LEN, IC_SELECT (offsets 0x00–0x18). Control bits: ENABLE, START, WRITE, READ, BURST. Status bits: READY, BUSY, DONE, ERROR. Declares autophi_fw_bus_init() , autophi_fw_bus_read() , autophi_fw_bus_write() , autophi_fw_bus_burst_read() , autophi_fw_bus_burst_write() .

10 autophi_fw_bus.c Custom Bus firmware implementation. Single and burst (up to 16-beat) transfers with 32-bit addressing.

11 autophi_ic_table.h IC configuration table. Static array of 142 autophi_ic_desc_t entries mapping every IC to its category, supported interfaces, preferred interface, register-map size, max clock (MHz), base address, and name. Lookup functions: autophi_ic_lookup() , autophi_ic_supports_iface() , autophi_ic_preferred_iface() , autophi_ic_base_addr() .

12 autophi_failover.h Interface failover engine. FAILOVER_MAX_RETRIES = 3 per interface before hop. FAILOVER_MAX_HOPS = 4 maximum chain depth. Default chain: BUS → SPI → I2C → UART. The autophi_failover_t struct tracks: primary interface, current interface, retry count, hop count, per-interface health (4-element array), and the 4-element failover chain. On failure, autophi_failover_next() retries the current interface up to 3 times, then marks it unhealthy, increments hop count, and finds the next healthy interface in the chain. Returns 0xFF on total failure. autophi_failover_init() builds the chain with the IC's preferred interface first, then remaining interfaces in default priority. autophi_failover_reset() restores all four interfaces to healthy.

13 autophi_regmap.h Register map reference for all 142 ICs. Common registers present on every IC at offset 0x0000–0x003F : IC_ID, IC_VERSION, IC_STATUS, IC_CONTROL, IC_IRQ_STATUS, IC_IRQ_ENABLE, IC_IRQ_CLEAR, IC_SIGNATURE (must read 0x4155544F ), IC_SCRATCH, IC_TEMPERATURE (0.1 C resolution), IC_VOLTAGE (mV), IC_CLOCK_FREQ (Hz), IC_UPTIME (seconds), IC_ERROR_COUNT, IC_RESET, IC_COMMANDMENT_CHK. Category-specific registers at 0x0040–0x0FFF for each IC family: Quantum (qubit count, fidelity, coherence time, gate control with Hadamard/Pauli-X/Y/Z/CNOT/Toffoli/Phase/T/SWAP/Measure), Photonic (channel count, bandwidth in Gbps, WDM wavelength in pm, laser power/temp/bias, BER, link status, modulation, optical switch matrix, latency in ps), Neuromorphic (neuron/synapse count, spike rate, membrane potential, threshold, STDP control, learning rate, event FIFO, power usage in uW), AI (TOPS, matrix dims, I/O/weight/output buffer addrs, precision INT4/INT8/FP16/BF16/FP32, activation ReLU/GELU/Sigmoid/Tanh/Softmax/SWiSH, attention heads, batch size, utilization %), Memory (capacity MB, bandwidth MB/s, latency ns, ECC status, DMA control), Power (output mV/mA, input mV, efficiency %, EM cooling field mT, EM torque, thermal status), Security (key slot, key size, algorithm AES-128/AES-256/SHA3-256/SHA3-512/RSA-2048/RSA-4096/ECC-P256/ECC-P384/Quantum-Safe, cipher mode ECB/CBC/GCM, IV, auth tag, RNG, tamper status, secure boot hash), EM Cooling (field strength mT, magnetic torque, cooling efficiency %, zone/target temp, zero-moving-parts, heat dissipated/power consumed in mW), LED Recycle (recycle efficiency %, energy stored/consumed in uJ, light intensity in lux, RGB color, light trigger control, laser wavelength nm, net power, cycle count, digital optics control). Register address helper: autophi_reg_addr(ic_id, reg_offset) computes the absolute address from the IC table base address plus the register offset.

Layer 3 — Host Software (C)

Seven C source files implement the host-side driver, providing the public API for applications communicating with all 142 AutoPhi ICs. The driver opens the device at /dev/autophi0 , verifies the commandment signature on open, and dispatches read/write operations through per-interface sub-drivers.

# File Function

1 autophi_ioctl.h IOCTL command definitions. Magic number: 'A' . Commands: GET_VERSION (0x01), GET_STATUS (0x02), HEALTH_CHECK (0x03), GET_SIGNATURE (0x04), SET_IFACE (0x10), GET_IFACE (0x11), SET_IC_ID (0x20), GET_IC_ID (0x21), ENTER_SLEEP (0x30), WAKE (0x31), GET_POWER (0x32), VERIFY_CMD (0x40), READ_REG (0x50), WRITE_REG (0x51). Includes portable _IO/_IOR/_IOW/_IOWR macro definitions.

2 autophi_drv_core.h Public API header. Device path: /dev/autophi0 . Opaque driver handle autophi_handle_t with file descriptor, active interface, active IC ID, power state, initialized flag. API functions: autophi_open() , autophi_close() , autophi_select_interface() , autophi_select_ic() , autophi_read() , autophi_write() , autophi_health_check() , autophi_get_status() , autophi_verify_commandments() , autophi_get_version() (always returns "1.0.0"), autophi_sleep() , autophi_wake() .

3 autophi_drv_core.c Core host driver implementation. Open: opens device, verifies driver signature ( 0x4155544F ^ 0x50484921 ), verifies all commandments via IOCTL, defaults to SPI/IC #1, runs health check. Close: enters sleep mode (Commandment IV), closes file descriptor. Read/write: validates handle, checks resource limits (max 4096 bytes), wakes if sleeping, dispatches to per-interface sub-driver. Write path: computes CRC-32 before sending, then read-back and CRC verify (Commandment VI). Platform abstraction layer with platform_open() , platform_close() , platform_ioctl() , platform_read() , platform_write() for portability across Linux, RTOS, and bare-metal.

4 autophi_drv_spi.c Host SPI sub-driver. Implements autophi_drv_spi_read() and autophi_drv_spi_write() via IOCTL dispatch to the firmware SPI layer.

5 autophi_drv_i2c.c Host I2C sub-driver. Implements autophi_drv_i2c_read() and autophi_drv_i2c_write() via IOCTL dispatch to the firmware I2C layer.

6 autophi_drv_uart.c Host UART sub-driver. Implements autophi_drv_uart_read() and autophi_drv_uart_write() via IOCTL dispatch to the firmware UART layer.

7 autophi_drv_bus.c Host Custom Bus sub-driver. Implements autophi_drv_bus_read() and autophi_drv_bus_write() via IOCTL dispatch to the firmware Custom Bus layer.

Four Bus Interfaces

Interface Select Code Protocol Details Key Parameters

SPI AUTOPHI_IFACE_SPI = 0x01 (hw: 2'b00 ) Full-duplex SPI master/slave. Mode 0 (CPOL=0, CPHA=0) hardcoded per Commandment VII. MSB-first shift. Chip-select active low. Default clock: 1 MHz from 50 MHz system clock. 8/16/32-bit transfer width. 256-deep FIFO. Clock divider: (CLK_FREQ / (2 * SPI_FREQ)) - 1 .

I2C AUTOPHI_IFACE_I2C = 0x02 (hw: 2'b01 ) I2C master with 7-bit addressing. Clock stretching support. Multi-master arbitration. Open-drain SDA/SCL. 4-phase clock generation. ACK/NACK detection per Commandment IX. 400 kHz standard speed ( AUTOPHI_I2C_SPEED_HZ = 400000 ). Prescaler: (CLK_FREQ / (4 * I2C_FREQ)) - 1 = 124 from 50 MHz. I2C prescale register: 16'd124 .

UART AUTOPHI_IFACE_UART = 0x03 (hw: 2'b10 ) Full-duplex UART transceiver. Strict 8N1: 8 data bits, no parity, 1 stop bit (Commandment VII). LSB-first. RX metastability protection (two-stage synchronizer). Mid-bit sampling for start-bit validation. Framing-error detection. 115,200 baud ( AUTOPHI_UART_BAUD = 115200 ). Baud divisor: CLK_FREQ / BAUD_RATE = 434 from 50 MHz. 256-deep FIFO.

Custom AutoPhi Bus AUTOPHI_IFACE_BUS = 0x04 (hw: 2'b11 ) 32-bit parallel bus with request/grant handshake protocol. Bus arbitration. Tristate bidirectional data bus. Burst transfers (1–16 beats). Separate address and data phases. ACK/error signaling from slave. 32-bit address width. 32-bit data width. Maximum burst length: 16 ( BURST_MAX=16 ). Address auto-increment by 4 bytes per burst beat. Firmware base: 0x40004000 .

Interface Failover Engine

Since the driver can never be patched, resilience is built in. The failover engine ( autophi_failover.h ) automatically switches interfaces when the primary fails.

• Retries per interface: 3 ( FAILOVER_MAX_RETRIES = 3 ). On each failure, the engine first retries the current interface up to 3 times before moving on.
• Maximum hops: 4 ( FAILOVER_MAX_HOPS = 4 ). After exhausting retries on one interface, the engine marks it unhealthy and hops to the next in the chain. After 4 hops, the engine returns 0xFF (total failure).
• Default chain: BUS → SPI → I2C → UART. Per-IC customization: autophi_failover_init(ic_id) builds the chain with the IC's preferred interface first, then remaining interfaces in default priority order, including only interfaces the IC supports.
• State tracking: primary interface, current interface, retry count, hop count (lifetime metric), per-interface health array (4 elements), and the 4-element failover chain.
• Recovery: autophi_failover_reset() restores all four interfaces to healthy status, used after watchdog recovery or manual reset.

AES-256 Encryption

The autophi_aes256 module provides hardware-level encryption for all bus communications. Since security patches will never come, the cryptography is built to be bulletproof from day one.

• Algorithm: AES-256 block cipher. 256-bit key. 128-bit block size. 14 rounds.
• S-Box: Full 256-entry constant lookup table, hardcoded in Verilog. No key-dependent table access—constant-time operation to eliminate timing side-channels.
• Operations: SubBytes (16-byte S-Box substitution), ShiftRows (row-wise circular shift in 4x4 column-major state matrix), AddRoundKey (128-bit XOR with round key).
• Round constants (RCON): 0x01, 0x02, 0x04, 0x08, 0x10, 0x20, 0x40 for rounds 0–6.
• GF(2^8) arithmetic: xtime function for Galois Field multiply-by-2 with irreducible polynomial 0x1b .
• Self-contained: No external IP. Commandment X compliant.

Self-Healing Watchdog

The autophi_watchdog module implements hardware-level self-healing. Because the driver can never be updated, it must heal itself.

• Watchdog timer: Configurable timeout, default 100 ms. Software must kick the watchdog periodically; expiry triggers a global reset pulse and auto-restarts the timer.
• Heartbeat monitoring: 10 ms check interval per interface. Edge-detection on heartbeat signals from SPI, I2C, UART, and Bus. Missing heartbeats or error status ( 2'b01 ) trigger fault detection.
• Per-interface auto-reset: After 5 consecutive faults ( MAX_CONSECUTIVE_FAULTS = 5 ), the module asserts the interface-specific reset line ( spi_reset_n , i2c_reset_n , uart_reset_n , or bus_reset_n ), holds it for 1 ms ( RECOVERY_CYCLES = CLK_FREQ_HZ / 1000 ), then releases it.
• Fault counters: 8-bit per-interface counters that wrap safely at 255 (Commandment X: no overflow). Exported as spi_fault_count , i2c_fault_count , uart_fault_count , bus_fault_count .
• Health output: 4-bit interface_health vector (one bit per interface, 1=healthy). system_healthy asserted only when all four bits are high.

Debug Port

The autophi_debug_port module is the primary diagnostic tool for field deployment, since the driver can never be updated.

• Output: UART-based, 115200 baud, 8N1. One-way (read-only).
• Transaction trace buffer: Circular buffer, 64 entries deep. Each entry: interface ID (8-bit) + IC ID (8-bit) + command (8-bit) + address (32-bit) + result (2-bit: 00=OK, 01=error, 10=timeout).
• Fault log: Circular buffer, 32 entries deep. Each entry: interface ID (8-bit) + fault code (8-bit).
• Performance counters: Total transactions (32-bit, wraps at 2^32), total errors (32-bit), uptime in seconds (32-bit, wraps at approximately 136 years).
• Periodic heartbeat: Once per second. Sends a compact status byte: [system_healthy|0|power_state[1:0]|global_status[1:0]|active_iface[1:0]] .
• Query registers: External probe can read 32-bit values by register address: 0x00 Signature ("AUTO"), 0x01 Version, 0x02 Uptime, 0x10–0x13 Current state (interface, IC, status, power), 0x20–0x21 Health, 0x30–0x31 Counters, 0x40–0x43 Per-interface fault counts, 0x50–0x51 Last trace entry, 0xF0 Commandment count, 0xFF End marker ( 0xDEADC0DE ). Unknown registers return 0xFFFFFFFF .

Canonical Register Map Structure

Every AutoPhi IC—all 142 of them—presents a common register block at offset 0x0000–0x003F with identical layout, followed by category-specific registers at 0x0040–0x0FFF .

Absolute register address for any IC and register: autophi_reg_addr(ic_id, reg_offset) = IC_base_address + reg_offset , where IC_base_address is looked up from the IC configuration table (e.g., IC 1 = 0x00000000 , IC 21 = 0x01000000 , IC 51 = 0x03000000 , IC 101 = 0x07000000 , IC 141 = 0x0C000000 ).

• autophi_u8 , autophi_u16 , autophi_u32 , autophi_i32 — unsigned/signed integer typedefs.
• autophi_transaction_t — Transaction structure: magic (must be 0xA5A5A5A5 ), interface_id, ic_id (1–142), command, reserved, address (32-bit), length, crc32.
• autophi_status_t — Status structure: status code, interface_id, ic_id, power_state, error_code, uptime_seconds.
• autophi_ic_desc_t — IC descriptor: ic_id, category, iface_flags, preferred_iface, reg_map_size, max_clock_mhz, base_reg_addr, name string.
• autophi_failover_t — Failover state: primary_iface, current_iface, retry_count, hop_count, iface_healthy[4], failover_chain[4].
• autophi_handle_t — Host driver handle: fd, active_iface, active_ic_id, power_state, initialized.

RAG Application (Python + ChromaDB)

The package includes a Retrieval-Augmented Generation application for querying the AutoPhi PCB-design knowledge base.

• Ingestion pipeline ( ingest.py ): Processes four source types: (1) PDF reference documents via pdfplumber , (2) structured Python knowledge modules ( rules.py , components.py , stackup.py , io_configs.py , netlist.py ), (3) Markdown knowledge base, (4) web URLs via requests + BeautifulSoup . Chunking: 800-character chunks with 120-character overlap. Deterministic chunk IDs via MD5 hash. Batch insertion in groups of 500.
• Vector store: ChromaDB persistent client. Collection: pcb_knowledge . Cosine similarity ( hnsw:space = cosine ).
• Query server ( app.py ): Flask application on port 5000. REST API: POST /api/search (query text, result count up to 30, optional source-type filter: pdf/python/markdown/web), GET /api/stats (chunk count). Each search hit returns: text, source file, source type, page/line number, and relevance score (1 minus cosine distance).
• Web UI: Dark-themed single-page interface. Search box with example queries (via aspect ratio, PCIe 5.0 trace width, VIPPO process, back drilling, solder mask, BGA fanout, annular ring, DFM vs DRC, crosstalk 3W rule, impedance stackup). Source-type radio filters. Expandable result cards with source badge, relevance percentage, and provenance.
• Dependencies: flask , chromadb , pdfplumber , requests , beautifulsoup4 .

Additional Deliverables

• commandments.h — The constitution. Top-level C header defining all 10 Commandments, version constants, interface identifiers, data types, CRC-32 function, and command validation.
• Makefile — Build system for the complete driver.
• example/autophi_example.c — Example application demonstrating the host API.
• LICENSE — Proprietary license. Covers US patent applications 17/687,656; 63/552,008; 29/839,062; 29/892,202; 17/454,808 and related continuations/divisionals/foreign counterparts.
• PCB asset: assets/autophi-pcb-6s.mp4 — PCB design visualization video.
• MANIFEST.json , CHANGELOG.md , CITATION.cff , README.md , PLAYBOOK.md — Project metadata, change history, citation reference, documentation, and playbook.

Hardware (Verilog) wonderphi-driver/hardware/ 10 autophi_commandments.v , autophi_spi_driver.v , autophi_i2c_driver.v , autophi_uart_driver.v , autophi_bus_driver.v , autophi_universal_driver.v , autophi_watchdog.v , autophi_aes256.v , autophi_debug_port.v , autophi_testbench.v

Firmware (C) wonderphi-driver/firmware/ 13 autophi_fw_core.h , autophi_fw_core.c , autophi_fw_spi.h , autophi_fw_spi.c , autophi_fw_i2c.h , autophi_fw_i2c.c , autophi_fw_uart.h , autophi_fw_uart.c , autophi_fw_bus.h , autophi_fw_bus.c , autophi_ic_table.h , autophi_failover.h , autophi_regmap.h

Host Software (C) wonderphi-driver/software/ 7 autophi_ioctl.h , autophi_drv_core.h , autophi_drv_core.c , autophi_drv_spi.c , autophi_drv_i2c.c , autophi_drv_uart.c , autophi_drv_bus.c

RAG Application (Python) / (project root) 2 app.py , ingest.py

How this is delivered

This package ships on a single Blu-ray disc, posted to the delivery address on your order. The archive on the disc is AES-256 encrypted; the passphrase is sent separately, by email, once the disc is despatched — so the disc alone is of no use to anyone who intercepts it.

Discs are despatched by tracked, signed-for post. Allow 5 business days for mastering and verification before despatch.

Photo