Module chip_protocol 

The chips’ byte protocol on the UART, defined once.

The whole-program engine talks to its host over one byte channel: it takes the program image, streams a record for every Show as the program runs, sends a request and waits for the reply when the program reaches the outside world (a host call), and ends with a result frame. Every byte value in that exchange is defined here and nowhere else. The engine model, the renderer and the host bridge use these constants, and scripts/logos-chip.py reads the same table as JSON from the chip_host example (table_json).

record	direction	bytes
program image	host → chip	the config memories and the params, then IMAGE_GO
show	chip → host	REC_SHOW, a value
call	chip → host	REC_CALL, the HostCall code, the argument count, that many values
reply	host → chip	REC_REPLY, a value
result frame	chip → host	FRAME_SYNC, result [63:0], cycles [31:0], one end byte

A program that pre-loads its heap sends IMAGE_HEAP and the pre-load between the params and IMAGE_GO. A value is its tag, then 8 bytes most significant first, except a Text: a 4-byte length, most significant first, and that many UTF-8 bytes. The end byte of the result frame is FRAME_END for a finished run, FRAME_END_CALL_STACK when the call stack overflowed and FRAME_END_HEAP when the heap did. Neither overflow’s result bytes are an answer.

Structs

ResultFrame

The result frame that closes a run.

Enums

ChipValue

A value as the protocol carries it.

FrameError

Why bytes are not a record.

HostCall

The program’s operations that reach the outside world through the host. The host services each with the one relay client (logicaffeine_system::relay); the chip never frames the relay protocol itself.

Record

One record of the exchange.

Constants

FRAME_END

The result frame of a run that finished.

FRAME_END_CALL_STACK

The result frame of a run whose call stack overflowed the engine’s frame stack.

FRAME_END_HEAP

The result frame of a run whose heap overflowed the engine’s heap.

FRAME_SYNC

The first byte of the result frame.

IMAGE_GO

The program image is complete; the engine starts the run.

IMAGE_HEAP

The program image’s heap pre-load segment follows.

REC_CALL

A host call’s request.

REC_REPLY

The host’s reply to a host call.

REC_SHOW

A Show record.

TAGS

Every value tag, in code order.

TAG_BOOL

A Bool, carried as 0 or 1.

TAG_FLOAT

A Real: its IEEE-754 bit pattern, rendered with the language’s fmt_f64.

TAG_INT

A signed 64-bit Int.

TAG_TEXT

A Text. On the engine, the shown value is a heap pointer to a char-list [len, byte0..]; on the wire, the length and the bytes.

TAG_WORD32

A Word32, rendered unsigned.

Functions

fill_verilog

Fill a Verilog template’s protocol bytes from this table: __V_<NAME>__ becomes the byte as a Verilog literal (8'hA7), __X_<NAME>__ the hex a comment quotes (0xA7). Panics if a placeholder names no protocol byte.

table_json

The whole table as JSON, for a host that is not Rust: scripts/logos-chip.py reads it from chip_host --table rather than restating a byte of it.