EtcPal  0.4.1
ETC Platform Abstraction Layer (EtcPal)
View other versions:
acn_pdu (ACN Protocol Family PDUs)

Overview

Parse or pack a PDU or PDU block as defined in ANSI E1.17 (ACN).

#include "etcpal/acn_pdu.h"

This module handles building and parsing the ACN PDU format as defined in ANSI E1.17, ACN Architecture document, § 2. EtcPal supports a few different ACN protocol family libraries, including sACN and RDMnet, so it's convenient to have this logic here.

Data Structures

struct  AcnPdu
 Holds state data used when parsing multiple PDUs in a PDU block. More...
 
struct  AcnPduConstraints
 Contains specific PDU info used by the generic helper acn_parse_pdu(). More...
 

Macros

#define ACN_PDU_LENGTH(pdu_buf)
 Get the length from the Length field of an ACN PDU. More...
 
#define ACN_PDU_PACK_NORMAL_LEN(pdu_buf, length)
 Fill in the Length field of an ACN PDU which has a length less than 4096. More...
 
#define ACN_PDU_PACK_EXT_LEN(pdu_buf, length)
 Fill in the Length field of an ACN PDU which has a length 4096 or greater. More...
 
#define ACN_PDU_INIT
 Default AcnPdu initializer values; must be used to intialize an AcnPdu when parsing the first PDU in a block. More...
 
#define ACN_INIT_PDU(pduptr)
 An alternative to ACN_PDU_INIT which can be used on an existing AcnPdu to re-initialize its values. More...
 

Typedefs

typedef struct AcnPdu AcnPdu
 Holds state data used when parsing multiple PDUs in a PDU block.
 
typedef struct AcnPduConstraints AcnPduConstraints
 Contains specific PDU info used by the generic helper acn_parse_pdu().
 

Functions

bool acn_parse_pdu (const uint8_t *buf, size_t buflen, const AcnPduConstraints *constraints, AcnPdu *pdu)
 Parse a generic ACN PDU. More...
 

Get the inheritance and length bits in an ACN PDU Flags & Length segment.

The first byte of each PDU contains a flags field which indicates the inheritance properties of that PDU.

For more information, see ANSI E1.17, ACN Architecture, § 2.4.

#define ACN_PDU_L_FLAG_SET(flags_byte)   ((bool)((flags_byte)&0x80u))
 Determine whether the L flag is set in an ACN PDU flags field. More...
 
#define ACN_PDU_V_FLAG_SET(flags_byte)   ((bool)((flags_byte)&0x40u))
 Determine whether the V flag is set in an ACN PDU flags field. More...
 
#define ACN_PDU_H_FLAG_SET(flags_byte)   ((bool)((flags_byte)&0x20u))
 Determine whether the H flag is set in an ACN PDU flags field. More...
 
#define ACN_PDU_D_FLAG_SET(flags_byte)   ((bool)((flags_byte)&0x10u))
 Determine whether the D flag is set in an ACN PDU flags field. More...
 

Set the inheritance and length bits in a PDU Flags & Length segment.

The first byte of each PDU contains a flags field which indicates the inheritance properties of that PDU.

For more information, see ANSI E1.17, ACN Architecture, § 2.4.

#define ACN_PDU_SET_L_FLAG(flags_byte)   (flags_byte |= 0x80u)
 Set the L flag in an ACN PDU flags field. More...
 
#define ACN_PDU_SET_V_FLAG(flags_byte)   (flags_byte |= 0x40u)
 Set the V flag in an ACN PDU flags field. More...
 
#define ACN_PDU_SET_H_FLAG(flags_byte)   (flags_byte |= 0x20u)
 Set the H flag in an ACN PDU flags field. More...
 
#define ACN_PDU_SET_D_FLAG(flags_byte)   (flags_byte |= 0x10u)
 Set the D flag in an ACN PDU flags field. More...
 

Macro Definition Documentation

◆ ACN_INIT_PDU

#define ACN_INIT_PDU (   pduptr)
Value:
do \
{ \
(pduptr)->pvector = NULL; \
(pduptr)->pheader = NULL; \
(pduptr)->pdata = NULL; \
(pduptr)->data_len = 0; \
(pduptr)->pnextpdu = NULL; \
} while (0)

An alternative to ACN_PDU_INIT which can be used on an existing AcnPdu to re-initialize its values.

Parameters
pduptrPointer to AcnPdu to initialize.

◆ ACN_PDU_D_FLAG_SET

#define ACN_PDU_D_FLAG_SET (   flags_byte)    ((bool)((flags_byte)&0x10u))

Determine whether the D flag is set in an ACN PDU flags field.

Parameters
flags_byteThe first byte of the PDU.
Returns
true (the D flag is set) or false (the D flag is not set).

◆ ACN_PDU_H_FLAG_SET

#define ACN_PDU_H_FLAG_SET (   flags_byte)    ((bool)((flags_byte)&0x20u))

Determine whether the H flag is set in an ACN PDU flags field.

Parameters
flags_byteThe first byte of the PDU.
Returns
true (the H flag is set) or false (the H flag is not set).

◆ ACN_PDU_INIT

#define ACN_PDU_INIT
Value:
{ \
NULL, NULL, NULL, 0, NULL \
}

Default AcnPdu initializer values; must be used to intialize an AcnPdu when parsing the first PDU in a block.

◆ ACN_PDU_L_FLAG_SET

#define ACN_PDU_L_FLAG_SET (   flags_byte)    ((bool)((flags_byte)&0x80u))

Determine whether the L flag is set in an ACN PDU flags field.

Parameters
flags_byteThe first byte of the PDU.
Returns
true (the L flag is set) or false (the L flags is not set).

◆ ACN_PDU_LENGTH

#define ACN_PDU_LENGTH (   pdu_buf)
Value:
((uint32_t)(ACN_PDU_L_FLAG_SET(pdu_buf[0]) \
? ((uint32_t)((pdu_buf[0] & 0x0fu) << 16) | (uint32_t)(pdu_buf[1] << 8) | (uint32_t)pdu_buf[2]) \
: ((uint32_t)((pdu_buf[0] & 0x0fu) << 8) | (uint32_t)pdu_buf[1])))
#define ACN_PDU_L_FLAG_SET(flags_byte)
Determine whether the L flag is set in an ACN PDU flags field.
Definition: acn_pdu.h:57

Get the length from the Length field of an ACN PDU.

Parameters
pdu_bufPointer to the start of the PDU buffer.
Returns
The length of the PDU.

◆ ACN_PDU_PACK_EXT_LEN

#define ACN_PDU_PACK_EXT_LEN (   pdu_buf,
  length 
)
Value:
do \
{ \
(pdu_buf)[0] = (uint8_t)(((pdu_buf)[0] & 0xf0) | (((length) >> 16) & 0x0fu)); \
(pdu_buf)[1] = (uint8_t)(((length) >> 8) & 0xffu); \
(pdu_buf)[2] = (uint8_t)(length)&0xffu; \
} while (0)

Fill in the Length field of an ACN PDU which has a length 4096 or greater.

The L flag of this PDU must be set to 1.

Parameters
pdu_bufPointer to the start of the PDU buffer.
lengthLength of this PDU.

◆ ACN_PDU_PACK_NORMAL_LEN

#define ACN_PDU_PACK_NORMAL_LEN (   pdu_buf,
  length 
)
Value:
do \
{ \
(pdu_buf)[0] = (uint8_t)(((pdu_buf)[0] & 0xf0) | (((length) >> 8) & 0x0fu)); \
(pdu_buf)[1] = (uint8_t)(length)&0xffu; \
} while (0)

Fill in the Length field of an ACN PDU which has a length less than 4096.

The L flag of this PDU must be set to 0.

Parameters
pdu_bufPointer to the start of the PDU buffer.
lengthLength of this PDU.

◆ ACN_PDU_SET_D_FLAG

#define ACN_PDU_SET_D_FLAG (   flags_byte)    (flags_byte |= 0x10u)

Set the D flag in an ACN PDU flags field.

Parameters
flags_byteThe first byte of the PDU.

◆ ACN_PDU_SET_H_FLAG

#define ACN_PDU_SET_H_FLAG (   flags_byte)    (flags_byte |= 0x20u)

Set the H flag in an ACN PDU flags field.

Parameters
flags_byteThe first byte of the PDU.

◆ ACN_PDU_SET_L_FLAG

#define ACN_PDU_SET_L_FLAG (   flags_byte)    (flags_byte |= 0x80u)

Set the L flag in an ACN PDU flags field.

Parameters
flags_byteThe first byte of the PDU.

◆ ACN_PDU_SET_V_FLAG

#define ACN_PDU_SET_V_FLAG (   flags_byte)    (flags_byte |= 0x40u)

Set the V flag in an ACN PDU flags field.

Parameters
flags_byteThe first byte of the PDU.

◆ ACN_PDU_V_FLAG_SET

#define ACN_PDU_V_FLAG_SET (   flags_byte)    ((bool)((flags_byte)&0x40u))

Determine whether the V flag is set in an ACN PDU flags field.

Parameters
flags_byteThe first byte of the PDU.
Returns
true (the V flag is set) or false (the V flag is not set).

Function Documentation

◆ acn_parse_pdu()

bool acn_parse_pdu ( const uint8_t *  buf,
size_t  buflen,
const AcnPduConstraints constraints,
AcnPdu pdu 
)

Parse a generic ACN PDU.

A function to parse a generic ACN PDU. The specific PDU info needed for parsing is contained in a struct AcnPduConstraints. Uses AcnPdu to maintain state across multiple PDUs in a block.

Parameters
[in]bufByte buffer containing a PDU.
[in]buflenSize in bytes of buf.
[in]constraintsSpecific information about the PDU being parsed
[in,out]pduPDU data from the last PDU in the block. The data is used and then replaced with data from this PDU.
Returns
true (PDU was parsed successfully) or false (parse error or no more PDUs in the block).