#include "mip_packet.h"
#include "mip_offsets.h"
#include "definitions/descriptors.h"
#include <string.h>
#include <assert.h>

Include dependency graph for mip_packet.c:

Functions
void	mip_packet_from_buffer (mip_packet packet, uint8_t buffer, size_t length)
	Initializes a MIP packet from an existing buffer. More...

void	mip_packet_create (mip_packet packet, uint8_t buffer, size_t buffer_size, uint8_t descriptor_set)
	Create a brand-new MIP packet in the given buffer. More...

uint8_t	mip_packet_descriptor_set (const mip_packet *packet)
	Returns the MIP descriptor set for this packet. More...

uint8_t	mip_packet_payload_length (const mip_packet *packet)
	Returns the length of the payload (MIP fields). More...

packet_length	mip_packet_total_length (const mip_packet *packet)
	Returns the total length of the packet, in bytes. More...

uint8_t *	mip_packet_buffer (mip_packet *packet)
	Returns a writable pointer to the data buffer. More...

const uint8_t *	mip_packet_pointer (const mip_packet *packet)
	Returns a pointer to the data buffer containing the packet. More...

const uint8_t *	mip_packet_payload (const mip_packet *packet)
	Returns a pointer to the packet's payload (the first field). More...

uint16_t	mip_packet_checksum_value (const mip_packet *packet)
	Returns the value of the checksum as written in the packet. More...

uint16_t	mip_packet_compute_checksum (const mip_packet *packet)
	Computes the checksum of the MIP packet. More...

bool	mip_packet_is_sane (const mip_packet *packet)
	Returns true if the packet buffer is not NULL and is at least the minimum size (MIP_PACKET_LENGTH_MIN). More...

bool	mip_packet_is_valid (const mip_packet *packet)
	Returns true if the packet is valid. More...

bool	mip_packet_is_empty (const mip_packet *packet)
	Returns true if the mip packet contains no payload. More...

packet_length	mip_packet_buffer_size (const mip_packet *packet)
	Returns the size of the buffer backing the MIP packet. More...

remaining_count	mip_packet_remaining_space (const mip_packet *packet)
	Returns the remaining space available for more payload data. More...

bool	mip_packet_is_data (const mip_packet *packet)
	Returns true if the packet is from a data descriptor set. More...

bool	mip_packet_add_field (mip_packet packet, uint8_t field_descriptor, const uint8_t payload, uint8_t payload_length)
	Adds a pre-constructed MIP field to the packet. More...

remaining_count	mip_packet_alloc_field (mip_packet packet, uint8_t field_descriptor, uint8_t payload_length, uint8_t *const payload_ptr_out)
	Allocate a MIP field within the packet and return the payload pointer. More...

remaining_count	mip_packet_realloc_last_field (mip_packet packet, uint8_t payload_ptr, uint8_t new_payload_length)
	Changes the size of the last field in the packet. More...

remaining_count	mip_packet_cancel_last_field (mip_packet packet, uint8_t payload_ptr)
	Removes the last field from the packet after having allocated it. More...

void	mip_packet_finalize (mip_packet *packet)
	Prepares the packet for transmission by adding the checksum. More...

void	mip_packet_reset (mip_packet *packet, uint8_t descriptor_set)
	Reinitialize the packet with the given descriptor set. More...

Function Documentation

◆ mip_packet_add_field()

bool mip_packet_add_field	(	mip_packet *	packet,
		uint8_t	field_descriptor,
		const uint8_t *	payload,
		uint8_t	payload_length
	)

Adds a pre-constructed MIP field to the packet.

                                            +--------------------+
                                            |  Payload Bytes     |
                              Len  Desc     +--------------------+
                               |    |        | copy
 Packet Buffer                 V    V        V
---------------+------------+-   -+-    -+--                  -+-
 ...   Header  |   Field    | Len | Desc |  Payload            |
---------------+------------+-----+------+---------------------+----------
                            |                                  |
                    End of last field   --------------->  End of new field

Parameters

packet
field_descriptor	The MIP field descriptor (e.g. command or data descriptor).
payload	A pointer to the field payload data (without the header). Can be NULL if payload_length is 0.
payload_length	The length of the payload data. Must be less than or equal to MIP_FIELD_PAYLOAD_LENGTH_MAX. Does not include the header.

Returns: true if the field was added, or false if there was not enough space.

◆ mip_packet_alloc_field()

remaining_count mip_packet_alloc_field	(	mip_packet *	packet,
		uint8_t	field_descriptor,
		uint8_t	payload_length,
		uint8_t **const	payload_ptr_out
	)

Allocate a MIP field within the packet and return the payload pointer.

                              Len   Desc  .---> Payload ptr out
                               |     |    |
 Packet Buffer                 V     V    |
---------------+------------+-   -+-    -+---------------------+----------
 ...   Header  |   Field    | Len | Desc | (unwritten payload) |
---------------+------------+-----+------+---------------------+----------
                            |                                  |
                    End of last field   --------------->  End of new field

Parameters

packet
field_descriptor	The MIP field descriptor (e.g. command or data descriptor).
payload_length	The requested length of the field payload (not including the header). If the size is not known ahead of time, pass 0 and inspect the return value to see how much payload data can be written. Then call mip_packet_realloc_field() with the used size and same payload pointer.
payload_ptr_out	A pointer to a pointer to the field payload. This will receive the payload pointer into which data should be written.

Returns: The amount of space remaining after allocating this field. If this is negative, the field could not be allocated and the payload must not be written.

◆ mip_packet_buffer()

uint8_t* mip_packet_buffer ( mip_packet * packet )

Returns a writable pointer to the data buffer.

◆ mip_packet_buffer_size()

packet_length mip_packet_buffer_size ( const mip_packet * packet )

Returns the size of the buffer backing the MIP packet.

Note: This is the BUFFER SIZE and not the packet length.

◆ mip_packet_cancel_last_field()

remaining_count mip_packet_cancel_last_field	(	mip_packet *	packet,
		uint8_t *	payload_ptr
	)

Removes the last field from the packet after having allocated it.

Use only after allocating a field with mip_packet_alloc_field to cancel it. E.g. if it turns out that there isn't enough buffer space to write the payload.

Parameters

packet
payload_ptr	Pointer to the field payload. This must be the same value returned from alloc_field and must point to the last field.

Returns: The remaining space in the packet after removing the field.

◆ mip_packet_checksum_value()

uint16_t mip_packet_checksum_value ( const mip_packet * packet )

Returns the value of the checksum as written in the packet.

This function does not compute the checksum. To do so, use mip_packet_compute_checksum().

◆ mip_packet_compute_checksum()

uint16_t mip_packet_compute_checksum ( const mip_packet * packet )

Computes the checksum of the MIP packet.

Returns: The computed checksum value.

◆ mip_packet_create()

void mip_packet_create	(	mip_packet *	packet,
		uint8_t *	buffer,
		size_t	buffer_size,
		uint8_t	descriptor_set
	)

Create a brand-new MIP packet in the given buffer.

Use this along with the packet building functions to create MIP packets.

Parameters

packet
buffer	This is where the packet bytes will be stored. Must be at least MIP_PACKET_LENGTH_MIN bytes in size.
buffer_size	The size of buffer, in bytes.
descriptor_set	The MIP descriptor set for the packet.

◆ mip_packet_descriptor_set()

uint8_t mip_packet_descriptor_set ( const mip_packet * packet )

Returns the MIP descriptor set for this packet.

◆ mip_packet_finalize()

void mip_packet_finalize ( mip_packet * packet )

Prepares the packet for transmission by adding the checksum.

This does not increase the total packet length since the checksum is always implicitly included.

                                                         Checksum
                                                           VVVV
---------------+------------+------------+-----//-----+--        --+----
 ...   Header  |   Field    |   Field    |     ...    |  (empty)   |
---------------+------------+------------+-----//-----+------------+----
                                                      |            |
                                           End of last field       |
                                                              Total Length

◆ mip_packet_from_buffer()

void mip_packet_from_buffer	(	mip_packet *	packet,
		uint8_t *	buffer,
		size_t	length
	)

Initializes a MIP packet from an existing buffer.

Use this when receiving or parsing MIP packets.

The data in the buffer should be a valid or suspected MIP packet.

Parameters

packet
buffer	The data buffer containing the bytes for a MIP packet. Must be at least MIP_PACKET_LENGTH_MIN bytes in size.
length	The length of the data pointed to by buffer.

Note: The data does not need to be a valid MIP packet, for instance to use the mip_packet_is_sane() or mip_packet_is_valid() functions. However, if it is NOT a valid MIP packet, the result of calling any accessor function is unpredictable. In particular, if length is less than MIP_PACKET_LENGTH_MIN bytes, calling the accessor functions is undefined behavior.

◆ mip_packet_is_data()

bool mip_packet_is_data ( const mip_packet * packet )

Returns true if the packet is from a data descriptor set.

See also: is_data_descriptor_set

Returns: true if the packet contains data.; false if it contains commands or replies.

◆ mip_packet_is_empty()

bool mip_packet_is_empty ( const mip_packet * packet )

Returns true if the mip packet contains no payload.

Parameters

packet

Returns: true if the packet has a payload length of 0.

◆ mip_packet_is_sane()

bool mip_packet_is_sane ( const mip_packet * packet )

Returns true if the packet buffer is not NULL and is at least the minimum size (MIP_PACKET_LENGTH_MIN).

If the packet is not 'sane', then none of the mip_packet_* functions may be used to access it (to do so is undefined behavior). This should never occur in normal circumstances.

◆ mip_packet_is_valid()

bool mip_packet_is_valid ( const mip_packet * packet )

Returns true if the packet is valid.

A packet is valid if:

mip_packet_is_sane() returns true,
The descriptor set is not 0x00, and
The checksum is valid.

◆ mip_packet_payload()

const uint8_t* mip_packet_payload ( const mip_packet * packet )

Returns a pointer to the packet's payload (the first field).

◆ mip_packet_payload_length()

uint8_t mip_packet_payload_length ( const mip_packet * packet )

Returns the length of the payload (MIP fields).

◆ mip_packet_pointer()

const uint8_t* mip_packet_pointer ( const mip_packet * packet )

Returns a pointer to the data buffer containing the packet.

◆ mip_packet_realloc_last_field()

remaining_count mip_packet_realloc_last_field	(	mip_packet *	packet,
		uint8_t *	payload_ptr,
		uint8_t	new_payload_length
	)

Changes the size of the last field in the packet.

Use this in conjunction with mip_packet_alloc_field() when the size of the field is not known in advance. Pass a payload size of 0 to alloc_field and check that the returned available space is sufficient, then write the payload and call this function with the actual space used.

Parameters

packet
payload_ptr	Pointer to the field payload. This must be the same value returned from alloc_field and must point to the last field.
new_payload_length	Length of payload written. Generally it is an error for this to exceed the actual amount of space available in the packet. In this case, the packet is left with just the empty field and the return value will be negative.

Returns: The space remaining in the packet after changing the field size. This will be negative if the new length did not fit.

◆ mip_packet_remaining_space()

remaining_count mip_packet_remaining_space ( const mip_packet * packet )

Returns the remaining space available for more payload data.

This is equal to the buffer size less the total packet length.

◆ mip_packet_reset()

void mip_packet_reset	(	mip_packet *	packet,
		uint8_t	descriptor_set
	)

Reinitialize the packet with the given descriptor set.

This clears out all of the fields but keeps the same buffer.

Parameters

packet
descriptor_set	New descriptor set.

◆ mip_packet_total_length()

packet_length mip_packet_total_length ( const mip_packet * packet )

Returns the total length of the packet, in bytes.

Returns: The length of the packet. Always at least MIP_PACKET_LENGTH_MIN.

Functions

Function Documentation

◆ mip_packet_add_field()

◆ mip_packet_alloc_field()

◆ mip_packet_buffer()

◆ mip_packet_buffer_size()

◆ mip_packet_cancel_last_field()

◆ mip_packet_checksum_value()

◆ mip_packet_compute_checksum()

◆ mip_packet_create()

◆ mip_packet_descriptor_set()

◆ mip_packet_finalize()

◆ mip_packet_from_buffer()

◆ mip_packet_is_data()

◆ mip_packet_is_empty()

◆ mip_packet_is_sane()

◆ mip_packet_is_valid()

◆ mip_packet_payload()

◆ mip_packet_payload_length()

◆ mip_packet_pointer()

◆ mip_packet_realloc_last_field()

◆ mip_packet_remaining_space()

◆ mip_packet_reset()

◆ mip_packet_total_length()