ieee802154_frame.h File Reference

IEEE 802.15.4 MAC frame related functions. More...

#include <zephyr/kernel.h>
#include <zephyr/net/ieee802154.h>
#include <zephyr/net/net_pkt.h>
#include <zephyr/toolchain.h>

Go to the source code of this file.

Data Structures
struct	ieee802154_fcf_seq
	Frame Control field and Sequence Number as in the MHR. More...
struct	ieee802154_address
	Short or extended address value in MAC addressing fields. More...
struct	ieee802154_address_field_comp
	Destination or Source Address field when PAN ID Compression omits the PAN ID. More...
struct	ieee802154_address_field_plain
	Destination or Source Address field with PAN ID and address. More...
struct	ieee802154_address_field
	Destination or Source Address field in either compressed or plain form. More...
struct	ieee802154_security_control_field
	Security Control field (first octet of the Auxiliary Security Header). More...
struct	ieee802154_key_identifier_field
	Key Identifier field of the Auxiliary Security Header. More...
struct	ieee802154_aux_security_hdr
	Auxiliary Security Header (ASH) following addressing fields when security is enabled. More...
struct	ieee802154_mhr
	Parsed view of the MAC Header (MHR) and Auxiliary Security Header pointers. More...
struct	ieee802154_gts_dir
	GTS Direction field in the beacon payload. More...
struct	ieee802154_gts
	One GTS descriptor in the GTS List field. More...
struct	ieee802154_gts_spec
	GTS Specification field of the beacon payload. More...
struct	ieee802154_pas_spec
	Pending Address Specification field of the beacon payload. More...
struct	ieee802154_beacon_sf
	Superframe Specification field of the beacon payload. More...
struct	ieee802154_beacon
	Fixed part of the Beacon Payload (Superframe Specification and GTS Specification). More...
struct	ieee802154_cmd_assoc_req
	Association Request command payload (Capability Information field). More...
struct	ieee802154_cmd_assoc_res
	Association Response command payload. More...
struct	ieee802154_cmd_disassoc_note
	Disassociation Notification command payload. More...
struct	ieee802154_cmd_coord_realign
	Coordinator Realignment command payload. More...
struct	ieee802154_gts_request
	GTS Request command payload. More...
struct	ieee802154_command
	Parsed MAC command frame payload. More...
struct	ieee802154_mpdu
	Parsed MAC Service Data Unit (MSDU) with MHR pointers and payload view. More...
struct	ieee802154_frame_params
	Parameters for building a MAC frame (addresses and PAN identifiers). More...

Macros
#define	IEEE802154_ACK_PKT_LENGTH   3
	Length in octets of an Immediate Acknowledgment (Imm-Ack) frame MPDU.
#define	IEEE802154_MIN_LENGTH   IEEE802154_ACK_PKT_LENGTH
	Minimum MAC frame NMPDU length supported here (same as IEEE802154_ACK_PKT_LENGTH).
#define	IEEE802154_FCF_SEQ_LENGTH   3
	Combined length in octets of the Frame Control and Sequence Number fields.
#define	IEEE802154_PAN_ID_LENGTH   2
	Length in octets of a PAN identifier in the MAC addressing fields.
#define	IEEE802154_BEACON_MIN_SIZE   4
	Minimum length in octets of the Beacon Payload field.
#define	IEEE802154_BEACON_SF_SIZE   2
	Length in octets of the Superframe Specification field.
#define	IEEE802154_BEACON_GTS_SPEC_SIZE   1
	Length in octets of the GTS Specification field.
#define	IEEE802154_BEACON_GTS_IF_MIN_SIZE   IEEE802154_BEACON_GTS_SPEC_SIZE
	Minimum length in octets of the GTS Fields when only the GTS Specification is present.
#define	IEEE802154_BEACON_PAS_SPEC_SIZE   1
	Length in octets of the Pending Address Specification field.
#define	IEEE802154_BEACON_PAS_IF_MIN_SIZE   IEEE802154_BEACON_PAS_SPEC_SIZE
	Minimum length in octets of the Pending Address Fields when only the specification is present.
#define	IEEE802154_BEACON_GTS_DIR_SIZE   1
	Length in octets of the GTS Direction field.
#define	IEEE802154_BEACON_GTS_SIZE   3
	Length in octets of one GTS descriptor in the GTS List field.
#define	IEEE802154_BEACON_GTS_RX   1
	GTS descriptor direction value for a receive-only GTS.
#define	IEEE802154_BEACON_GTS_TX   0
	GTS descriptor direction value for a transmit-only GTS.
#define	IEEE802154_SECURITY_LEVEL_ENC   IEEE802154_SECURITY_LEVEL_RESERVED
	Compare security levels against this to detect encryption modes.
#define	IEEE802154_AUTH_TAG_LENGTH_32   4
	Authentication tag length in octets for MIC-32 modes.
#define	IEEE802154_AUTH_TAG_LENGTH_64   8
	Authentication tag length in octets for MIC-64 modes.
#define	IEEE802154_AUTH_TAG_LENGTH_128   16
	Authentication tag length in octets for MIC-128 modes.
#define	IEEE802154_KEY_ID_FIELD_INDEX_LENGTH   1
	Length in octets of the Key Identifier field for Key Identifier Mode 1.
#define	IEEE802154_KEY_ID_FIELD_SRC_4_INDEX_LENGTH   5
	Length in octets of the Key Identifier field for Key Identifier Mode 2.
#define	IEEE802154_KEY_ID_FIELD_SRC_8_INDEX_LENGTH   9
	Length in octets of the Key Identifier field for Key Identifier Mode 3.
#define	IEEE802154_KEY_MAX_LEN   16
	Maximum key length in octets for MAC security operations in this API.
#define	IEEE802154_SECURITY_CF_LENGTH   1
	Length in octets of the Security Control field.
#define	IEEE802154_SECURITY_FRAME_COUNTER_LENGTH   4
	Length in octets of the Frame Counter field in the Auxiliary Security Header.
#define	IEEE802154_CMD_ASSOC_REQ_LENGTH   1
	Length in octets of the Association Request command payload (Capability Information).
#define	IEEE802154_CMD_ASSOC_RES_LENGTH   3
	Length in octets of the Association Response command payload.
#define	IEEE802154_CMD_DISASSOC_NOTE_LENGTH   1
	Length in octets of the Disassociation Notification command payload.
#define	IEEE802154_CMD_COORD_REALIGN_LENGTH   3
	Minimum length in octets of the Coordinator Realignment command payload covered here.
#define	IEEE802154_GTS_REQUEST_LENGTH   1
	Length in octets of the GTS Request command payload.
#define	IEEE802154_CMD_CFI_LENGTH   1
	Length in octets of the Command Frame Identifier field.

Enumerations
enum	ieee802154_frame_type {   IEEE802154_FRAME_TYPE_BEACON = 0x0 , IEEE802154_FRAME_TYPE_DATA = 0x1 , IEEE802154_FRAME_TYPE_ACK = 0x2 , IEEE802154_FRAME_TYPE_MAC_COMMAND = 0x3 ,   IEEE802154_FRAME_TYPE_RESERVED = 0x4 , IEEE802154_FRAME_TYPE_MULTIPURPOSE = 0x5 , IEEE802154_FRAME_TYPE_FRAK = 0x6 , IEEE802154_FRAME_TYPE_EXTENDED = 0x7 }
	Values of the Frame Type subfield in the Frame Control field. More...
enum	ieee802154_addressing_mode { IEEE802154_ADDR_MODE_NONE = 0x0 , IEEE802154_ADDR_MODE_RESERVED = 0x1 , IEEE802154_ADDR_MODE_SHORT = 0x2 , IEEE802154_ADDR_MODE_EXTENDED = 0x3 }
	Destination and Source Addressing Mode subfield values. More...
enum	ieee802154_version { IEEE802154_VERSION_802154_2003 = 0x0 , IEEE802154_VERSION_802154_2006 = 0x1 , IEEE802154_VERSION_802154 = 0x2 , IEEE802154_VERSION_RESERVED = 0x3 }
	Frame Version subfield values. More...
enum	ieee802154_security_level {   IEEE802154_SECURITY_LEVEL_NONE = 0x0 , IEEE802154_SECURITY_LEVEL_MIC_32 = 0x1 , IEEE802154_SECURITY_LEVEL_MIC_64 = 0x2 , IEEE802154_SECURITY_LEVEL_MIC_128 = 0x3 ,   IEEE802154_SECURITY_LEVEL_RESERVED = 0x4 , IEEE802154_SECURITY_LEVEL_ENC_MIC_32 = 0x5 , IEEE802154_SECURITY_LEVEL_ENC_MIC_64 = 0x6 , IEEE802154_SECURITY_LEVEL_ENC_MIC_128 = 0x7 }
	Security Level subfield values in the Security Control field. More...
enum	ieee802154_key_id_mode { IEEE802154_KEY_ID_MODE_IMPLICIT = 0x0 , IEEE802154_KEY_ID_MODE_INDEX = 0x1 , IEEE802154_KEY_ID_MODE_SRC_4_INDEX = 0x2 , IEEE802154_KEY_ID_MODE_SRC_8_INDEX = 0x3 }
	Key Identifier Mode subfield values. More...
enum	ieee802154_association_status_field {   IEEE802154_ASF_SUCCESSFUL = 0x00 , IEEE802154_ASF_PAN_AT_CAPACITY = 0x01 , IEEE802154_ASF_PAN_ACCESS_DENIED = 0x02 , IEEE802154_ASF_RESERVED = 0x03 ,   IEEE802154_ASF_RESERVED_PRIMITIVES = 0x80 }
	Association status values in the Association Response command. More...
enum	ieee802154_disassociation_reason_field {   IEEE802154_DRF_RESERVED_1 = 0x00 , IEEE802154_DRF_COORDINATOR_WISH = 0x01 , IEEE802154_DRF_DEVICE_WISH = 0x02 , IEEE802154_DRF_RESERVED_2 = 0x03 ,   IEEE802154_DRF_RESERVED_PRIMITIVES = 0x80 }
	Disassociation reason codes in the Disassociation Notification command. More...
enum	ieee802154_cfi {   IEEE802154_CFI_UNKNOWN = 0x00 , IEEE802154_CFI_ASSOCIATION_REQUEST = 0x01 , IEEE802154_CFI_ASSOCIATION_RESPONSE = 0x02 , IEEE802154_CFI_DISASSOCIATION_NOTIFICATION = 0x03 ,   IEEE802154_CFI_DATA_REQUEST = 0x04 , IEEE802154_CFI_PAN_ID_CONFLICT_NOTIFICATION = 0x05 , IEEE802154_CFI_ORPHAN_NOTIFICATION = 0x06 , IEEE802154_CFI_BEACON_REQUEST = 0x07 ,   IEEE802154_CFI_COORDINATOR_REALIGNEMENT = 0x08 , IEEE802154_CFI_GTS_REQUEST = 0x09 , IEEE802154_CFI_RESERVED = 0x0a }
	Command Frame Identifier (CFI) values for MAC commands. More...

Detailed Description

IEEE 802.15.4 MAC frame related functions.

This is not to be included by the application.

Note

All references to the standard in this file cite IEEE 802.15.4-2020.

All structs and attributes (e.g. PAN id, ext address and short address) in this file that directly represent parts of IEEE 802.15.4 frames are in LITTLE ENDIAN, see section 4, especially section 4.3.

Macro Definition Documentation

IEEE802154_ACK_PKT_LENGTH

#define IEEE802154_ACK_PKT_LENGTH   3

Length in octets of an Immediate Acknowledgment (Imm-Ack) frame MPDU.

Imm-Ack consists of the Frame Control field and the Sequence Number field only; see section 7.3.3 and Figure 7-17.

IEEE802154_AUTH_TAG_LENGTH_128

#define IEEE802154_AUTH_TAG_LENGTH_128   16

Authentication tag length in octets for MIC-128 modes.

Matches IEEE802154_SECURITY_LEVEL_MIC_128 and IEEE802154_SECURITY_LEVEL_ENC_MIC_128.

IEEE802154_AUTH_TAG_LENGTH_32

#define IEEE802154_AUTH_TAG_LENGTH_32   4

Authentication tag length in octets for MIC-32 modes.

Matches IEEE802154_SECURITY_LEVEL_MIC_32 and IEEE802154_SECURITY_LEVEL_ENC_MIC_32.

IEEE802154_AUTH_TAG_LENGTH_64

#define IEEE802154_AUTH_TAG_LENGTH_64   8

Authentication tag length in octets for MIC-64 modes.

Matches IEEE802154_SECURITY_LEVEL_MIC_64 and IEEE802154_SECURITY_LEVEL_ENC_MIC_64.

IEEE802154_BEACON_GTS_DIR_SIZE

#define IEEE802154_BEACON_GTS_DIR_SIZE   1

Length in octets of the GTS Direction field.

Present when the GTS Descriptor Count subfield is nonzero; see section 7.3.1.5 and Figure 7-10.

IEEE802154_BEACON_GTS_IF_MIN_SIZE

#define IEEE802154_BEACON_GTS_IF_MIN_SIZE   IEEE802154_BEACON_GTS_SPEC_SIZE

Minimum length in octets of the GTS Fields when only the GTS Specification is present.

Same as IEEE802154_BEACON_GTS_SPEC_SIZE when there are no GTS descriptors.

IEEE802154_BEACON_GTS_RX

#define IEEE802154_BEACON_GTS_RX   1

GTS descriptor direction value for a receive-only GTS.

See the Device Type subfield in Figure 7-11.

IEEE802154_BEACON_GTS_SIZE

#define IEEE802154_BEACON_GTS_SIZE   3

Length in octets of one GTS descriptor in the GTS List field.

Each descriptor is three octets; see section 7.3.1.5 and Figure 7-11.

IEEE802154_BEACON_GTS_SPEC_SIZE

#define IEEE802154_BEACON_GTS_SPEC_SIZE   1

Length in octets of the GTS Specification field.

See section 7.3.1.5 and Figure 7-9.

IEEE802154_BEACON_GTS_TX

#define IEEE802154_BEACON_GTS_TX   0

GTS descriptor direction value for a transmit-only GTS.

See the Device Type subfield in Figure 7-11.

IEEE802154_BEACON_MIN_SIZE

#define IEEE802154_BEACON_MIN_SIZE   4

Minimum length in octets of the Beacon Payload field.

Includes the Superframe Specification, GTS Specification, and Pending Address Specification fields at minimum; see section 7.3.1 and Figure 7-6.

IEEE802154_BEACON_PAS_IF_MIN_SIZE

#define IEEE802154_BEACON_PAS_IF_MIN_SIZE   IEEE802154_BEACON_PAS_SPEC_SIZE

Minimum length in octets of the Pending Address Fields when only the specification is present.

Same as IEEE802154_BEACON_PAS_SPEC_SIZE when there are no pending addresses listed.

IEEE802154_BEACON_PAS_SPEC_SIZE

#define IEEE802154_BEACON_PAS_SPEC_SIZE   1

Length in octets of the Pending Address Specification field.

See section 7.3.1.6 and Figure 7-12.

IEEE802154_BEACON_SF_SIZE

#define IEEE802154_BEACON_SF_SIZE   2

Length in octets of the Superframe Specification field.

See section 7.3.1.4 and Figure 7-7.

IEEE802154_CMD_ASSOC_REQ_LENGTH

#define IEEE802154_CMD_ASSOC_REQ_LENGTH   1

Length in octets of the Association Request command payload (Capability Information).

One octet; see section 7.5.2.

IEEE802154_CMD_ASSOC_RES_LENGTH

#define IEEE802154_CMD_ASSOC_RES_LENGTH   3

Length in octets of the Association Response command payload.

Three octets; see section 7.5.3.

IEEE802154_CMD_CFI_LENGTH

#define IEEE802154_CMD_CFI_LENGTH   1

Length in octets of the Command Frame Identifier field.

One octet; see section 7.5.1.

IEEE802154_CMD_COORD_REALIGN_LENGTH

#define IEEE802154_CMD_COORD_REALIGN_LENGTH   3

Minimum length in octets of the Coordinator Realignment command payload covered here.

First three octets of the payload; see section 7.5.10.

IEEE802154_CMD_DISASSOC_NOTE_LENGTH

#define IEEE802154_CMD_DISASSOC_NOTE_LENGTH   1

Length in octets of the Disassociation Notification command payload.

One octet; see section 7.5.4.

IEEE802154_FCF_SEQ_LENGTH

#define IEEE802154_FCF_SEQ_LENGTH   3

Combined length in octets of the Frame Control and Sequence Number fields.

These are the first three octets of the general MAC frame format; see Figure 7-2 and section 7.2.2.

IEEE802154_GTS_REQUEST_LENGTH

#define IEEE802154_GTS_REQUEST_LENGTH   1

Length in octets of the GTS Request command payload.

One octet; see section 7.5.11.

IEEE802154_KEY_ID_FIELD_INDEX_LENGTH

#define IEEE802154_KEY_ID_FIELD_INDEX_LENGTH   1

Length in octets of the Key Identifier field for Key Identifier Mode 1.

Key Index only; see Table 9-7.

IEEE802154_KEY_ID_FIELD_SRC_4_INDEX_LENGTH

#define IEEE802154_KEY_ID_FIELD_SRC_4_INDEX_LENGTH   5

Length in octets of the Key Identifier field for Key Identifier Mode 2.

Four-octet Key Source plus Key Index; see Table 9-7.

IEEE802154_KEY_ID_FIELD_SRC_8_INDEX_LENGTH

#define IEEE802154_KEY_ID_FIELD_SRC_8_INDEX_LENGTH   9

Length in octets of the Key Identifier field for Key Identifier Mode 3.

Eight-octet Key Source plus Key Index; see Table 9-7.

IEEE802154_KEY_MAX_LEN

#define IEEE802154_KEY_MAX_LEN   16

Maximum key length in octets for MAC security operations in this API.

Aligns with typical AES-128 key sizes; see section 9.4.

IEEE802154_MIN_LENGTH

#define IEEE802154_MIN_LENGTH   IEEE802154_ACK_PKT_LENGTH

Minimum MAC frame NMPDU length supported here (same as IEEE802154_ACK_PKT_LENGTH).

The shortest standardized MAC frame is the Imm-Ack; see section 7.3.3.

IEEE802154_PAN_ID_LENGTH

#define IEEE802154_PAN_ID_LENGTH   2

Length in octets of a PAN identifier in the MAC addressing fields.

The PAN ID is two octets; see section 7.2.2.8.

IEEE802154_SECURITY_CF_LENGTH

#define IEEE802154_SECURITY_CF_LENGTH   1

Length in octets of the Security Control field.

One octet; see section 9.4.2.

IEEE802154_SECURITY_FRAME_COUNTER_LENGTH

#define IEEE802154_SECURITY_FRAME_COUNTER_LENGTH   4

Length in octets of the Frame Counter field in the Auxiliary Security Header.

Four octets; see section 9.4.3.

IEEE802154_SECURITY_LEVEL_ENC

#define IEEE802154_SECURITY_LEVEL_ENC   IEEE802154_SECURITY_LEVEL_RESERVED

Compare security levels against this to detect encryption modes.

Security level values strictly above this constant use encryption (ENC MIC); see Table 9-6. Defined as the reserved codepoint IEEE802154_SECURITY_LEVEL_RESERVED.

Enumeration Type Documentation

ieee802154_addressing_mode

enum ieee802154_addressing_mode

Destination and Source Addressing Mode subfield values.

See section 7.2.2.9 and Table 7-3.

Enumerator
IEEE802154_ADDR_MODE_NONE	Addressing fields omitted (not present).
IEEE802154_ADDR_MODE_RESERVED	Reserved; shall not be used.
IEEE802154_ADDR_MODE_SHORT	Short address (16 bit).
IEEE802154_ADDR_MODE_EXTENDED	Extended address (64 bit).

ieee802154_association_status_field

enum ieee802154_association_status_field

Association status values in the Association Response command.

See section 7.5.3.

Enumerator
IEEE802154_ASF_SUCCESSFUL	Association successful.
IEEE802154_ASF_PAN_AT_CAPACITY	PAN at capacity.
IEEE802154_ASF_PAN_ACCESS_DENIED	PAN access denied.
IEEE802154_ASF_RESERVED	Reserved.
IEEE802154_ASF_RESERVED_PRIMITIVES	Reserved range for MAC primitives.

ieee802154_cfi

enum ieee802154_cfi

Command Frame Identifier (CFI) values for MAC commands.

See section 7.5.1.

Enumerator
IEEE802154_CFI_UNKNOWN	Unknown or unspecified command.
IEEE802154_CFI_ASSOCIATION_REQUEST	Association request.
IEEE802154_CFI_ASSOCIATION_RESPONSE	Association response.
IEEE802154_CFI_DISASSOCIATION_NOTIFICATION	Disassociation notification.
IEEE802154_CFI_DATA_REQUEST	Data request.
IEEE802154_CFI_PAN_ID_CONFLICT_NOTIFICATION	PAN ID conflict notification.
IEEE802154_CFI_ORPHAN_NOTIFICATION	Orphan notification.
IEEE802154_CFI_BEACON_REQUEST	Beacon request.
IEEE802154_CFI_COORDINATOR_REALIGNEMENT	Coordinator realignment.
IEEE802154_CFI_GTS_REQUEST	GTS request.
IEEE802154_CFI_RESERVED	Reserved.

ieee802154_disassociation_reason_field

enum ieee802154_disassociation_reason_field

Disassociation reason codes in the Disassociation Notification command.

See section 7.5.4.

Enumerator
IEEE802154_DRF_RESERVED_1	Reserved.
IEEE802154_DRF_COORDINATOR_WISH	Coordinator wishes device to leave.
IEEE802154_DRF_DEVICE_WISH	Device wishes to leave.
IEEE802154_DRF_RESERVED_2	Reserved.
IEEE802154_DRF_RESERVED_PRIMITIVES	Reserved range for MAC primitives.

ieee802154_frame_type

enum ieee802154_frame_type

Values of the Frame Type subfield in the Frame Control field.

See section 7.2.2.2 and Table 7-1.

Enumerator
IEEE802154_FRAME_TYPE_BEACON	Beacon frame.
IEEE802154_FRAME_TYPE_DATA	Data frame.
IEEE802154_FRAME_TYPE_ACK	Acknowledgment frame.
IEEE802154_FRAME_TYPE_MAC_COMMAND	MAC command frame.
IEEE802154_FRAME_TYPE_RESERVED	Reserved frame type.
IEEE802154_FRAME_TYPE_MULTIPURPOSE	Multipurpose frame.
IEEE802154_FRAME_TYPE_FRAK	FRak frame (fragment acknowledgment).
IEEE802154_FRAME_TYPE_EXTENDED	Extended frame type; use the Extended Frame Type field.

ieee802154_key_id_mode

enum ieee802154_key_id_mode

Key Identifier Mode subfield values.

See section 9.4.2.3 and Table 9-7.

Enumerator
IEEE802154_KEY_ID_MODE_IMPLICIT	Key is determined implicitly.
IEEE802154_KEY_ID_MODE_INDEX	Key Index only.
IEEE802154_KEY_ID_MODE_SRC_4_INDEX	4-octet Key Source and Key Index.
IEEE802154_KEY_ID_MODE_SRC_8_INDEX	8-octet Key Source and Key Index.

ieee802154_security_level

enum ieee802154_security_level

Security Level subfield values in the Security Control field.

See section 9.4.2.2 and Table 9-6.

Enumerator
IEEE802154_SECURITY_LEVEL_NONE	No security (no encryption, no authentication).
IEEE802154_SECURITY_LEVEL_MIC_32	MIC-32 authentication only.
IEEE802154_SECURITY_LEVEL_MIC_64	MIC-64 authentication only.
IEEE802154_SECURITY_LEVEL_MIC_128	MIC-128 authentication only.
IEEE802154_SECURITY_LEVEL_RESERVED	Reserved.
IEEE802154_SECURITY_LEVEL_ENC_MIC_32	Encryption with MIC-32.
IEEE802154_SECURITY_LEVEL_ENC_MIC_64	Encryption with MIC-64.
IEEE802154_SECURITY_LEVEL_ENC_MIC_128	Encryption with MIC-128.

ieee802154_version

enum ieee802154_version

Frame Version subfield values.

See section 7.2.2.10.

Enumerator
IEEE802154_VERSION_802154_2003	IEEE Std 802.15.4-2003.
IEEE802154_VERSION_802154_2006	IEEE Std 802.15.4-2006.
IEEE802154_VERSION_802154	IEEE Std 802.15.4 (2003 and 2006 excluded).
IEEE802154_VERSION_RESERVED	Reserved for future use.