Struct Decoder 

pub struct Decoder<'d, U> { /* private fields */ }

A decoder for individual packets and/or payloads

Use this decoder to decode encap::Packets or smi::Packets.

A decoder is created via a Builder. From the supplied data, packets of different formats may be decoded using the corresponding fns such as decode_encap_packet or decode_smi_packet. After assessing whether a packet is relevant or not, its Payload may be decoded. Multiple packets from different harts may be sequentially decoded by a single decoder instance.

If a packet could not be decoded due to insufficient data, the decoder will report this by emitting an Error::InsufficientData error. Alternatively, the number of bytes left in the input can be queried via the fn bytes_left.

Example

The follwing example demonstrates decoding of trace data in chunks with one decoder per input, including the recovery from attempting to decode an incomplete packet. We do not need to clone the Builder since it happens to be Copy in this case.

use riscv_etrace::packet;

let builder = packet::builder().with_params(&parameters);
let mut decoder = builder.decoder(trace_data);
loop {
    let packet = match decoder.decode_encap_packet() {
        Ok(packet) => packet,
        Err(packet::Error::InsufficientData(_)) => break,
        Err(e) => panic!("{e:?}"),
    };
    // ...
}
let mut decoder = builder.decoder(trace_data_next);
loop {
    let packet = match decoder.decode_encap_packet() {
        Ok(packet) => packet,
        Err(packet::Error::InsufficientData(_)) => break,
        Err(e) => panic!("{e:?}"),
    };
    // ...
}

Implementations

impl<'d, U> Decoder<'d, U>

pub fn bytes_left(&self) -> usize

Retrieve the number of bytes left in this decoder’s data

If the decoder is currently not at a byte boundary, the number returned includes the partially decoded byte.

pub fn byte_pos(&self) -> usize

Retrieve the current byte position

Returns the zero-based position of the byte which is currently decoded. If the current bit position is on a byte boundary, the position of the byte after the boundary is returned.

Example

use riscv_etrace::packet;

let mut decoder = packet::builder().decoder(trace_data);
assert_eq!(decoder.byte_pos(), 0);

pub fn reset(&mut self, data: &'d [u8])

Reset the inner data to the given byte slice

pub fn decode<T: Decode<'d, U>>(&mut self) -> Result<T, Error>

Decode a single item

Decodes a single item, consuming the associated data from the input and sign-extending the input if neccessary. Depending on the item’s type and Decode implementation, the decoder may be left at a bit boundary following the item after successful operation. A failure may leave the decoder in an unspecified state.

pub fn decode_encap_packet(&mut self) -> Result<Packet<Self>, Error>

where U: Clone,

Decode a single encap::Packet

Decodes a single encap::Packet, consuming the associated data from the input. After successful operation, the decoder is left at the byte boundary following the packet, ready to decode the next one. A failure may leave the decoder in an unspecified state.

pub fn decode_smi_packet(&mut self) -> Result<Packet<Self>, Error>

where U: Clone,

Decode a single smi::Packet consisting of header and payload

Decodes a single smi::Packet, consuming the associated data from the input. After successful operation, the decoder is left at the byte boundary following the packet, ready to decode the next one. A failure may leave the decoder in an unspecified state.

pub fn decode_esp32_packet(&mut self) -> Result<Packet<Self>, Error>

where U: Clone,

pub fn decode_payload( &mut self, ) -> Result<InstructionTrace<U::IOptions, U::DOptions>, Error>

where U: Unit,

Decode a single, stand-alone InstructionTrace payload

Decodes a single InstructionTrace payload, consuming the associated data from the input and sign-extending the input if neccessary. After successful operation, the decoder is left at the bit boundary following the payload. A failure may leave the decoder in an unspecified state.

pub fn unit(&self) -> &U

Retrieve this decoder’s Unit

pub fn remaining_data(&self) -> &'d [u8]

Retrieve the remaining inner data, including the current byte

If the current bit position is at a byte buondary, e.g. after successful decoding of a packet, the returned buffer contains only undecoded data.

pub fn split_off_to(&mut self, pos: usize) -> Result<Self, Error>

where U: Clone,

Split off a sub-decoder covering the data to the given position

On success, the inner data will be reset to the portion of the original data starting at and including byte pos past the current byte position. A decoder with the original bit position covering the first half of the buffer will be returned.

Trait Implementations

impl<'d, U: Clone> Clone for Decoder<'d, U>

fn clone(&self) -> Decoder<'d, U>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.