Internal Implementation Details

The following are mostly internal implementation details, but end up in the user-facing API.

class torii_ila._bits.bits(value=0, length: int | None = None)

An immutable bit sequence, like bytes but for bits.

This bit sequence is ordered from LSB to MSB; this is the direction in which it is converted to and from iterators, and to and from bytes. Note, however, that it is converted to and from strings (which should be only used where a human-readable form is required) from MSB to LSB; this matches the way integer literals are written, as well as values in datasheets and other documentation.

class torii_ila._cobs.RCOBSEncoder

Reverse Consistent Overhead Byte Stuffing (rCOBS) encoder.

This is an implementation of the rCOBS algorithm. The source of the encoding algorithm was originally a Rust crate and can be found at: https://github.com/Dirbaio/rcobs

The algorithm is fairly simple, for each byte in a message, do the following:

  1. Increment running total byte counter

2. Check if byte is 0x00 3a. If it is, then write out the value of the byte counter and reset it 3b. If it is not, check to see if the running byte counter is about to overflow 4a. If it is, write out 0xFF and reset the byte counter 4b. If it is not, write out the byte itself.

This encoder is just a pure implementation of the encoding logic for a single byte, and as such has a collection of status and control signals to indicate to the outside world its status.

Attributes:

  • raw (Signal(8), in) – The raw byte to encode.

  • enc (Signal(8), out) – The rCOBS encoded byte. Not valid unless vld signal is high.

  • strb (Signal, in) – Strobe to signal to encode the byte in raw.

  • finish (Signal, in) – Flush the state of the encoder in preparation for next stream.

  • rdy (Signal, out) – Encoder ready signal, indicates when the encoder is ready for the next byte.

  • vld (Signal, out) – Value in enc is valid and can be latched.

torii_ila._cobs.decode_rcobs(data)

Decode an rCOBS encoded message.

The input data is expected to not contain any 0x00 framing information, it should be a single complete rCOBS message.

Parameters:

data (bytes | bytearray) – The rCOBS encoded message.

Returns:

The rCOBS decoded message.

Return type:

bytes

Raises:

ValueError – If the input dat contains a 0x00 byte -OR- the message is improperly encoded.