Encoding and Decoding

The torii.lib.coding module provides building blocks for conversion between different encodings of binary numbers.

One-hot coding

class torii.lib.coding.Encoder(*args: Any, src_loc_at: int = 0, **kwargs: Any)

Encode one-hot to binary.

If one bit in i is asserted, n is low and o indicates the asserted bit. Otherwise, n is high and o is 0.

Parameters:

width (int) – Bit width of the input

Attributes:

  • i (Signal(width), in) – One-hot input.

  • o (Signal(range(width)), out) – Encoded natural binary.

  • n (Signal, out) – Invalid: either none or multiple input bits are asserted.

class torii.lib.coding.Decoder(*args: Any, src_loc_at: int = 0, **kwargs: Any)

Decode binary to one-hot.

If n is low, only the i-th bit in o is asserted. If n is high, o is 0.

Parameters:

width (int) – Bit width of the output.

Attributes:

  • i (Signal(range(width)), in) – Input binary.

  • o (Signal(width), out) – Decoded one-hot.

  • n (Signal, in) – Invalid, no output bits are to be asserted.

Priority coding

torii.lib.coding.PriorityEncoder

alias of Encoder

torii.lib.coding.PriorityDecoder

alias of Decoder

Gray coding

torii.lib.coding.GrayEncoder

alias of Encoder

torii.lib.coding.GrayDecoder

alias of Decoder

Consistent Overhead Byte Stuffing

This module implements some Consistent Overhead Byte Stuffing (COBS) encoders, primarily the RCOBSEncoder which is well adept at streaming.

class torii.lib.coding.cobs.RCOBSEncoder(*args: Any, src_loc_at: int = 0, **kwargs: Any)

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 for each byte:

  1. Increment the running total byte counter

  2. If the byte is 0x00 then write the value of the byte counter out and reset it to 0

  3. If it is not, then check to see if the running total counter is about to overflow

  4. If we are about to overflow, write out 0xFF and reset the counter

  5. Otherwise, write out the byte

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.

For decoding rCOBS encoded messages the decode_rcobs() method implements that functionality for any host-side applications.

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.

  • strobe (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.

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

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

torii.lib.coding.cobs.decode_rcobs(data: bytes | bytearray) → bytes

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.

Important

This is not a synthesize construct, it is simply a helper function to decode messages produced with the RCOBSEncoder on the host side. Or as a reference for implementation in other languages.

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.