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_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 tofirst
-
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 destinationsrc
: packet sourcetype
: packet typetype_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 loglog_ctx
: the log context to write tomsg
: 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 dumpfd
: 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.
-
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 writefd
: 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