osd_packet class

Representation of a single packet in the debug interconnect.

Accessor functions encapsulate reading and writing fields inside the packet.

Usage

#include <osd/osd.h>
#include <osd/packet.h>

Public Interface

libosd-packet::osd_packet_type

Packet types

Values:

0
1
2
3
libosd-packet::osd_packet_type_reg_subtype

Values of the TYPE_SUB field in if TYPE == OSD_PACKET_TYPE_REG

Values:

0b0000
0b0001
0b0010
0b0011
0b1000
0b1001
0b1010
0b1011
0b1100
0b0100
0b0101
0b0110
0b0111
0b1110
0b1111
libosd-packet::osd_packet_type_event_subtype

Values of the TYPE_SUB field in if TYPE == OSD_PACKET_TYPE_EVENT

Values:

0
1
5
osd_result osd_packet_new(struct osd_packet ** packet, size_t size_data_words)

Allocate memory for a packet with given data size and zero all data fields

The osd_packet.size field is set to the allocated size.

Return
OSD_OK if successful, any other value indicates an error
See
osd_packet_new_from_zframe()
See
osd_packet_realloc()
See
osd_packet_free()
Parameters
  • [out] packet: the packet to be allocated
  • [in] size_data_words: number of uint16_t words in the packet, including the header words.

osd_result osd_packet_realloc(struct osd_packet ** packet_p, size_t data_size_words_new)

Reallocate memory for a packet to increase or decrease its size

Return
OSD_OK if successful, any other value indicates an error
See
osd_packet_new()
See
osd_packet_free()
Parameters
  • packet_p: A pointer to an existing packet, which will be reallocated. The resulting pointer will potentially differ from the the passed pointer!
  • [in] size_data_words: number of uint16_t words in the packet, including the header words. May be larger or smaller than the size of the existing packet.

osd_result osd_packet_new_from_zframe(struct osd_packet ** packet, const zframe_t * frame)

Create a new packet from a zframe

See
osd_packet_new()

void osd_packet_free(struct osd_packet ** packet)

Free the memory associated with the packet and NULL the object

osd_result osd_packet_combine(struct osd_packet ** first_p, const struct osd_packet * second)

Append the payload of the second packet into the first packet

The header data of the second packet is ignored.

Return
OSD_OK if successful, any other value indicates an error
Parameters
  • first_p: a pointer to an existing packet, which will be reallocated the resulting pointer will be different than the the passed pointer!
  • second: the packet of which the payload is appended to first

unsigned int osd_packet_get_dest(const struct osd_packet * packet)

Extract the DEST field out of a packet

unsigned int osd_packet_get_src(const struct osd_packet * packet)

Extract the SRC field out of a packet

unsigned int osd_packet_get_type(const struct osd_packet * packet)

Extract the TYPE field out of a packet

unsigned int osd_packet_get_type_sub(const struct osd_packet * packet)

Extract the TYPE_SUB field out of a packet

osd_result osd_packet_set_type_sub(struct osd_packet * packet, const unsigned int type_sub)

Set the TYPE_SUB field in a packet

osd_result osd_packet_set_header(struct osd_packet * packet, const unsigned int dest, const unsigned int src, const enum osd_packet_type type, const unsigned int type_sub)

Populate the header of a osd_packet

Return
OSD_OK on success, any other value indicates an error
Parameters
  • packet:
  • dest: packet destination
  • src: packet source
  • type: packet type
  • type_sub: packet subtype

size_t osd_packet_sizeof(const struct osd_packet * packet)

Size in bytes of a packet

unsigned int osd_packet_sizeconv_payload2data(unsigned int payload_words)

Get the number of data words required for the given payload words

Data words are the number of 16 bit words in a DI packet, including the DI header. Payload words are the number of 16 bit words in a DI packet excluding the header.

unsigned int osd_packet_sizeconv_data2payload(unsigned int data_words)

Get the number of paylaod words required for the given data words

Data words are the number of 16 bit words in a DI packet, including the DI header. Payload words are the number of 16 bit words in a DI packet excluding the header.

void osd_packet_log(const struct osd_packet * packet, struct osd_log_ctx * log_ctx, const char * msg)

Log a debug message with the packet in human-readable form

Use the msg parameter to prefix the dumped packet in the log entry with, for example, the type of packet being logged. This is preferrable over writing two log entries to keep the information together.

Parameters
  • packet: packet to log
  • log_ctx: the log context to write to
  • msg: message to be prepended to the dumped packet

void osd_packet_dump(const struct osd_packet * packet, FILE * fd)

Dump a packet in human-readable (debugging) form to a file stream

See
osd_packet_to_string()
Parameters
  • packet: packet to dump
  • fd: stream to dump packet to. You can use stdout and stderr here.

void osd_packet_to_string(const struct osd_packet * packet, char ** str)

Dump the packet to a string (for human consumption)

The string representation of a packet is for debugging purposes only and may change at any time, do not rely on it for automated parsing.

See
osd_packet_dump()

bool osd_packet_fwrite(const struct osd_packet * packet, FILE * fd)

Write a packet from a file descriptor

In its current implementation this function memory-dumps osd_packet structs to a file, without any encoding. This has some consequences:

  • The resulting file is in native endianness, i.e. not portable between little and big endian machines.
  • No file header is present, or any for of file magic number to identify the file type.
  • No file integrity checks, such as checksums.

Return
bool operation successful?
See
osd_packet_fread()
Parameters
  • packet: the packet to write
  • fd: the open file descriptor to write to

struct osd_packet* osd_packet_fread(FILE * fd)

Read a packet from an open file descriptor

See the discussion in osd_packet_fwrite() for known limitations.

Return
the read packet, or NULL if reading failed
See
osd_packet_fwrite()
Parameters
  • fd: an open file descriptor to read from

bool osd_packet_equal(const struct osd_packet * p1, const struct osd_packet * p2)

Check if two packets are equal

DP_HEADER_TYPE_SHIFT
DP_HEADER_TYPE_MASK
DP_HEADER_TYPE_SUB_SHIFT
DP_HEADER_TYPE_SUB_MASK
DP_HEADER_SRC_SHIFT
DP_HEADER_SRC_MASK
DP_HEADER_DEST_SHIFT
DP_HEADER_DEST_MASK
struct osd_packet
#include <packet.h>

A packet in the Open SoC Debug system