diff --git a/nrf_802154/common/include/nrf_802154_const.h b/nrf_802154/common/include/nrf_802154_const.h index 39ca432480..a20f9c1e35 100644 --- a/nrf_802154/common/include/nrf_802154_const.h +++ b/nrf_802154/common/include/nrf_802154_const.h @@ -40,196 +40,196 @@ #ifndef NRF_802154_CONST_H_ #define NRF_802154_CONST_H_ -#define RAW_LENGTH_OFFSET 0 ///< Byte containing the frame length in a raw frame. -#define RAW_PAYLOAD_OFFSET 1 ///< Offset of the frame payload in a raw frame - -#define ACK_HEADER_WITH_PENDING 0x12 ///< The first byte of an ACK frame containing a pending bit. -#define ACK_HEADER_WITHOUT_PENDING 0x02 ///< The first byte of an ACK frame without a pending bit. - -#define ACK_REQUEST_OFFSET 1 ///< Byte containing the ACK request bit (+1 for the frame length byte). -#define ACK_REQUEST_BIT (1 << 5) ///< ACK request bit. - -#define ASN_IN_NONCE_BIT 0x40 ///< Bit containing the ASN in Nonce field. - -#define DEST_ADDR_TYPE_OFFSET 2 ///< Byte containing the destination address type (+1 for the frame length byte). -#define DEST_ADDR_TYPE_MASK 0x0c ///< Mask of bits containing the destination address type. -#define DEST_ADDR_TYPE_EXTENDED 0x0c ///< Bits containing the extended destination address type. -#define DEST_ADDR_TYPE_NONE 0x00 ///< Bits containing a not-present destination address type. -#define DEST_ADDR_TYPE_SHORT 0x08 ///< Bits containing the short destination address type. -#define DEST_ADDR_OFFSET 6 ///< Offset of the destination address in the Data frame (+1 for the frame length byte). - -#define DSN_OFFSET 3 ///< Byte containing the DSN value (+1 for the frame length byte). -#define DSN_SUPPRESS_OFFSET 2 ///< Byte containing the DSN suppression field. -#define DSN_SUPPRESS_BIT 0x01 ///< Bits containing the DSN suppression field. - -#define FRAME_COUNTER_SUPPRESS_BIT 0x20 ///< Bit containing the Frame Counter Suppression field. - -#define FRAME_PENDING_OFFSET 1 ///< Byte containing a pending bit (+1 for the frame length byte). -#define FRAME_PENDING_BIT (1 << 4) ///< Pending bit. - -#define FRAME_TYPE_OFFSET 1 ///< Byte containing the frame type bits (+1 for the frame length byte). -#define FRAME_TYPE_MASK 0x07 ///< Mask of bits containing the frame type. -#define FRAME_TYPE_ACK 0x02 ///< Bits containing the ACK frame type. -#define FRAME_TYPE_BEACON 0x00 ///< Bits containing the Beacon frame type. -#define FRAME_TYPE_COMMAND 0x03 ///< Bits containing the Command frame type. -#define FRAME_TYPE_DATA 0x01 ///< Bits containing the Data frame type. -#define FRAME_TYPE_EXTENDED 0x07 ///< Bits containing the Extended frame type. -#define FRAME_TYPE_FRAGMENT 0x06 ///< Bits containing the Fragment or the Frak frame type. -#define FRAME_TYPE_MULTIPURPOSE 0x05 ///< Bits containing the Multipurpose frame type. - -#define FRAME_VERSION_OFFSET 2 ///< Byte containing the frame version bits (+1 for the frame length byte). -#define FRAME_VERSION_MASK 0x30 ///< Mask of bits containing the frame version. -#define FRAME_VERSION_0 0x00 ///< Bits containing the frame version 0b00. -#define FRAME_VERSION_1 0x10 ///< Bits containing the frame version 0b01. -#define FRAME_VERSION_2 0x20 ///< Bits containing the frame version 0b10. -#define FRAME_VERSION_3 0x30 ///< Bits containing the frame version 0b11. - -#define IE_HEADER_LENGTH_MASK 0x3f ///< Mask of bits containing the length of an IE header content. -#define IE_PRESENT_OFFSET 2 ///< Byte containing the IE Present bit. -#define IE_PRESENT_BIT 0x02 ///< Bits containing the IE Present field. - -#define KEY_ID_MODE_0 0 ///< Value of the 0x00 Key Identifier Mode. -#define KEY_ID_MODE_1 1 ///< Value of the 0x01 Key Identifier Mode. -#define KEY_ID_MODE_2 2 ///< Value of the 0x10 Key Identifier Mode. -#define KEY_ID_MODE_3 3 ///< Value of the 0x11 Key Identifier Mode. - -#define KEY_ID_MODE_MASK 0x18 ///< Mask of bits containing Key Identifier Mode in the Security Control field. -#define KEY_ID_MODE_BIT_OFFSET 3 ///< Number of bits the Key Identifier Mode is offset in the Security Control field. -#define KEY_ID_MODE_0_MASK 0 ///< Bits containing the 0x00 Key Identifier Mode. -#define KEY_ID_MODE_1_MASK 0x08 ///< Bits containing the 0x01 Key Identifier Mode. -#define KEY_ID_MODE_2_MASK 0x10 ///< Bits containing the 0x10 Key Identifier Mode. -#define KEY_ID_MODE_3_MASK 0x18 ///< Bits containing the 0x11 Key Identifier Mode. - -#define KEY_SRC_KEY_ID_MODE_0_SIZE 0 ///< Size of the Key Source field when Key Identifier Mode equals 0. -#define KEY_SRC_KEY_ID_MODE_1_SIZE 0 ///< Size of the Key Source field when Key Identifier Mode equals 1. -#define KEY_SRC_KEY_ID_MODE_2_SIZE 4 ///< Size of the Key Source field when Key Identifier Mode equals 2. -#define KEY_SRC_KEY_ID_MODE_3_SIZE 8 ///< Size of the Key Source field when Key Identifier Mode equals 3. - -#define KEY_IDX_SIZE 1 ///< Size of the Key Index field - -#define MAC_CMD_COMMAND_ID_SIZE 1 ///< Size of the MAC Command ID field. -#define MAC_CMD_ASSOC_REQ 0x01 ///< Command frame identifier for MAC Association request. -#define MAC_CMD_ASSOC_RESP 0x02 ///< Command frame identifier for MAC Association response. -#define MAC_CMD_DISASSOC_NOTIFY 0x03 ///< Command frame identifier for MAC Disaccociation notification. -#define MAC_CMD_DATA_REQ 0x04 ///< Command frame identifier for MAC Data Requests. -#define MAC_CMD_PANID_CONFLICT 0x05 ///< Command frame identifier for MAC PAN ID conflict notification. -#define MAC_CMD_ORPHAN_NOTIFY 0x06 ///< Command frame identifier for MAC Orphan notification. -#define MAC_CMD_BEACON_REQ 0x07 ///< Command frame identifier for MAC Beacon. -#define MAC_CMD_COORD_REALIGN 0x08 ///< Command frame identifier for MAC Coordinator realignment. -#define MAC_CMD_GTS_REQUEST 0x09 ///< Command frame identifier for MAC GTS request. - -#define PAN_ID_COMPR_OFFSET 1 ///< Byte containing the PAN ID compression bit (+1 for the frame length byte). -#define PAN_ID_COMPR_MASK 0x40 ///< PAN ID compression bit. - -#define PAN_ID_OFFSET 4 ///< Offset of PAN ID in the Data frame (+1 for the frame length byte). - -#define PHR_OFFSET 0 ///< Offset of the PHY header in a frame. -#define PHR_LENGTH_MASK 0x7f ///< Mask of the PHR length field - -#define PSDU_OFFSET 1 ///< Offset of the PHY payload. - -#define SECURITY_ENABLED_OFFSET 1 ///< Byte containing the Security Enabled bit. -#define SECURITY_ENABLED_BIT 0x08 ///< Bits containing the Security Enabled field. -#define SECURITY_LEVEL_MASK 0x07 ///< Mask of bits containing the Security level field. -#define SECURITY_LEVEL_NONE 0x00 ///< Bits indicating a frame with no security attributes (0b000). -#define SECURITY_LEVEL_MIC_32 0x01 ///< Bits containing the 32-bit Message Integrity Code (0b001). -#define SECURITY_LEVEL_MIC_64 0x02 ///< Bits containing the 64-bit Message Integrity Code (0b010). -#define SECURITY_LEVEL_MIC_128 0x03 ///< Bits containing the 128-bit Message Integrity Code (0b011). -#define SECURITY_LEVEL_ENC_MIC_32 0x05 ///< Bits containing the 32-bit Encrypted Message Integrity Code (0b101). -#define SECURITY_LEVEL_ENC_MIC_64 0x06 ///< Bits containing the 64-bit Encrypted Message Integrity Code (0b110). -#define SECURITY_LEVEL_ENC_MIC_128 0x07 ///< Bits containing the 128-bit Encrypted Message Integrity Code (0b111). -#define SECURITY_LEVEL_MIC_LEVEL_MASK 0x03 ///< Mask of bits encoding the Message Integrity Code length. - -#define SRC_ADDR_TYPE_EXTENDED 0xc0 ///< Bits containing the extended source address type. -#define SRC_ADDR_TYPE_NONE 0x00 ///< Bits containing a not-present source address type. -#define SRC_ADDR_TYPE_MASK 0xc0 ///< Mask of bits containing the source address type. -#define SRC_ADDR_TYPE_OFFSET 2 ///< Byte containing the source address type (+1 for the frame length byte). -#define SRC_ADDR_TYPE_SHORT 0x80 ///< Bits containing the short source address type. - -#define SRC_ADDR_OFFSET_SHORT_DST 8 ///< Offset of the source address in the Data frame if the destination address is short. -#define SRC_ADDR_OFFSET_EXTENDED_DST 14 ///< Offset of the source address in the Data frame if the destination address is extended. - -#define DSN_SIZE 1 ///< Size of the Sequence Number field. -#define FCF_SIZE 2 ///< Size of the FCF field. -#define FCS_SIZE 2 ///< Size of the FCS field. -#define FRAME_COUNTER_SIZE 4 ///< Size of the Frame Counter field. -#define IE_HEADER_SIZE 2 ///< Size of the obligatory IE Header field elements. -#define IMM_ACK_LENGTH 5 ///< Length of the ACK frame. -#define KEY_ID_MODE_1_SIZE 1 ///< Size of the 0x01 Key Identifier Mode field. -#define KEY_ID_MODE_2_SIZE 5 ///< Size of the 0x10 Key Identifier Mode field. -#define KEY_ID_MODE_3_SIZE 9 ///< Size of the 0x11 Key Identifier Mode field. -#define MAX_PACKET_SIZE 127 ///< Maximum size of the radio packet. -#define MIC_32_SIZE 4 ///< Size of MIC with the MIC-32 and ENC-MIC-32 security attributes. -#define MIC_64_SIZE 8 ///< Size of MIC with the MIC-64 and ENC-MIC-64 security attributes. -#define MIC_128_SIZE 16 ///< Size of MIC with the MIC-128 and ENC-MIC-128 security attributes. -#define PAN_ID_SIZE 2 ///< Size of the PAN ID. -#define PHR_SIZE 1 ///< Size of the PHR field. -#define SECURITY_CONTROL_SIZE 1 ///< Size of the Security Control field. - -#define AES_CCM_KEY_SIZE 16 ///< Size of AES CCM Key. - -#define EXTENDED_ADDRESS_SIZE 8 ///< Size of the Extended Mac Address. -#define SHORT_ADDRESS_SIZE 2 ///< Size of the Short Mac Address. - -#define TURNAROUND_TIME 192UL ///< RX-to-TX or TX-to-RX turnaround time (aTurnaroundTime), in microseconds (us). -#define CCA_TIME 128UL ///< Time required to perform CCA detection (aCcaTime), in microseconds (us). -#define ACK_IFS TURNAROUND_TIME ///< Ack Inter Frame Spacing [us] - delay between last symbol of received frame and first symbol of transmitted Ack -#define UNIT_BACKOFF_PERIOD (TURNAROUND_TIME + CCA_TIME) ///< Number of symbols in the basic time period used by CSMA-CA algorithm (aUnitBackoffPeriod), in (us). - -#define PHY_US_PER_SYMBOL 16 ///< Duration of a single symbol in microseconds (us). -#define PHY_SYMBOLS_PER_OCTET 2 ///< Number of symbols in a single byte (octet). -#define PHY_SHR_SYMBOLS 10 ///< Number of symbols in the Synchronization Header (SHR). - -#define PHY_MIN_RECEIVER_SENSITIVITY -85 ///< Lowest receiver sensitivity level in dBm according to 802.15.4-2020 specification, chapter 12.3.4 - -#define ED_RESULT_MAX 0xff ///< Maximal ED result. - -#define BROADCAST_ADDRESS ((uint8_t[SHORT_ADDRESS_SIZE]) {0xff, 0xff}) ///< Broadcast short address. - -#define MIN_SIFS_PERIOD_US 192 ///< Minimum Short IFS period default value in us. -#define MIN_LIFS_PERIOD_US 640 ///< Minimum Long IFS period default value in us. -#define MAX_SIFS_FRAME_SIZE 18 ///< Maximum frame length which can be followed by the Short Interframe Space. - -#define NRF_802154_RESERVED_CSMACA_ID (UINT32_MAX - 2) ///< Delayed timeslot identifier reserved for CSMA/CA procedure. -#define NRF_802154_RESERVED_DTX_ID (UINT32_MAX - 3) ///< Delayed timeslot identifier reserved for delayed transmissions. - -#define IE_VENDOR_ID 0x00 ///< Vendor-specific IE identifier -#define IE_VENDOR_SIZE_MIN 3 ///< Vendor-specific IE minimum length -#define IE_VENDOR_OUI_OFFSET 0 ///< Vendor-specific IE OUI offset - -#define IE_VENDOR_THREAD_SUBTYPE_OFFSET 3 ///< Thread Vendor-specific IE subtype offset -#define IE_VENDOR_THREAD_DATA_OFFSET 4 ///< Thread Vendor-specific IE DATA offset -#define IE_VENDOR_THREAD_OUI 0xeab89b ///< Thread Vendor-specific IE OUI -#define IE_VENDOR_THREAD_SIZE_MIN 4 ///< Thread Vendor-specific IE minimum length - -#define IE_VENDOR_THREAD_ACK_PROBING_ID 0x00 ///< Thread Vendor-specific ACK Probing IE subtype ID -#define IE_VENDOR_THREAD_ACK_SIZE_MIN 5 ///< Thread Vendor-specific ACK Probing IE minimum size -#define IE_VENDOR_THREAD_ACK_SIZE_MAX 6 ///< Thread Vendor-specific ACK Probing IE maximum size -#define IE_VENDOR_THREAD_RSSI_TOKEN 0x01 ///< Thread Vendor-specific ACK Probing IE RSSI value placeholder -#define IE_VENDOR_THREAD_MARGIN_TOKEN 0x02 ///< Thread Vendor-specific ACK Probing IE Link margin value placeholder -#define IE_VENDOR_THREAD_LQI_TOKEN 0x03 ///< Thread Vendor-specific ACK Probing IE LQI value placeholder -#define IE_VENDOR_THREAD_RSSI_FLOOR -130 ///< Thread Vendor-specific ACK Probing RSSI floor value used for scaling -#define IE_VENDOR_THREAD_MARGIN_FLOOR 0 ///< Thread Vendor-specific ACK Probing margin floor value used for scaling -#define IE_VENDOR_THREAD_RSSI_CEIL 0 ///< Thread Vendor-specific ACK Probing RSSI ceil value used for scaling -#define IE_VENDOR_THREAD_MARGIN_CEIL 130 ///< Thread Vendor-specific ACK Probing margin ceil value used for scaling -#define IE_VENDOR_THREAD_CST_ID 0x02 ///< Thread Vendor-specific CST IE subtype ID -#define IE_VENDOR_THREAD_CST_SIZE 8 ///< Thread Vendor-specific CST IE size -#define IE_CSL_SYMBOLS_PER_UNIT 10 ///< Number of symbols per phase/period unit -#define IE_CSL_PERIOD_MAX 0xffff ///< Maximum CSL IE phase/period value -#define IE_CSL_SIZE_MIN 4 ///< Minimal size of the CSL IE -#define IE_CSL_ID 0x1a ///< CSL IE identifier - -#define IE_HT1 0x7e ///< Information Element Header Termination type 1 -#define IE_HT2 0x7f ///< Information Element Header Termination type 2 -#define IE_LENGTH_MASK 0x7f ///< Information element length mask -#define IE_LENGTH_OFFSET 0x00 ///< Information element length offset -#define IE_ID_OFFSET_0 0x00 ///< Offset of the octet containing the first part of the IE identifier. -#define IE_ID_OFFSET_1 0x01 ///< Offset of the octed containing the second part of the IE identifier. -#define IE_DATA_OFFSET 0x02 ///< Information element data offset -#define IE_HEADER_ELEMENT_ID_OFFSET 0x07 ///< Bit offset of Element ID field in a Header IE header. - -#define ENH_ACK_MAX_SIZE MAX_PACKET_SIZE ///< Maximum length of the Enh-ACK frame. -#define ACK_MAX_SIZE ENH_ACK_MAX_SIZE ///< Maximum length of the ACK frame. +#define RAW_LENGTH_OFFSET 0 /**< Byte containing the frame length in a raw frame. */ +#define RAW_PAYLOAD_OFFSET 1 /**< Offset of the frame payload in a raw frame */ + +#define ACK_HEADER_WITH_PENDING 0x12 /**< The first byte of an ACK frame containing a pending bit. */ +#define ACK_HEADER_WITHOUT_PENDING 0x02 /**< The first byte of an ACK frame without a pending bit. */ + +#define ACK_REQUEST_OFFSET 1 /**< Byte containing the ACK request bit (+1 for the frame length byte). */ +#define ACK_REQUEST_BIT (1 << 5) /**< ACK request bit. */ + +#define ASN_IN_NONCE_BIT 0x40 /**< Bit containing the ASN in Nonce field. */ + +#define DEST_ADDR_TYPE_OFFSET 2 /**< Byte containing the destination address type (+1 for the frame length byte). */ +#define DEST_ADDR_TYPE_MASK 0x0c /**< Mask of bits containing the destination address type. */ +#define DEST_ADDR_TYPE_EXTENDED 0x0c /**< Bits containing the extended destination address type. */ +#define DEST_ADDR_TYPE_NONE 0x00 /**< Bits containing a not-present destination address type. */ +#define DEST_ADDR_TYPE_SHORT 0x08 /**< Bits containing the short destination address type. */ +#define DEST_ADDR_OFFSET 6 /**< Offset of the destination address in the Data frame (+1 for the frame length byte). */ + +#define DSN_OFFSET 3 /**< Byte containing the DSN value (+1 for the frame length byte). */ +#define DSN_SUPPRESS_OFFSET 2 /**< Byte containing the DSN suppression field. */ +#define DSN_SUPPRESS_BIT 0x01 /**< Bits containing the DSN suppression field. */ + +#define FRAME_COUNTER_SUPPRESS_BIT 0x20 /**< Bit containing the Frame Counter Suppression field. */ + +#define FRAME_PENDING_OFFSET 1 /**< Byte containing a pending bit (+1 for the frame length byte). */ +#define FRAME_PENDING_BIT (1 << 4) /**< Pending bit. */ + +#define FRAME_TYPE_OFFSET 1 /**< Byte containing the frame type bits (+1 for the frame length byte). */ +#define FRAME_TYPE_MASK 0x07 /**< Mask of bits containing the frame type. */ +#define FRAME_TYPE_ACK 0x02 /**< Bits containing the ACK frame type. */ +#define FRAME_TYPE_BEACON 0x00 /**< Bits containing the Beacon frame type. */ +#define FRAME_TYPE_COMMAND 0x03 /**< Bits containing the Command frame type. */ +#define FRAME_TYPE_DATA 0x01 /**< Bits containing the Data frame type. */ +#define FRAME_TYPE_EXTENDED 0x07 /**< Bits containing the Extended frame type. */ +#define FRAME_TYPE_FRAGMENT 0x06 /**< Bits containing the Fragment or the Frak frame type. */ +#define FRAME_TYPE_MULTIPURPOSE 0x05 /**< Bits containing the Multipurpose frame type. */ + +#define FRAME_VERSION_OFFSET 2 /**< Byte containing the frame version bits (+1 for the frame length byte). */ +#define FRAME_VERSION_MASK 0x30 /**< Mask of bits containing the frame version. */ +#define FRAME_VERSION_0 0x00 /**< Bits containing the frame version 0b00. */ +#define FRAME_VERSION_1 0x10 /**< Bits containing the frame version 0b01. */ +#define FRAME_VERSION_2 0x20 /**< Bits containing the frame version 0b10. */ +#define FRAME_VERSION_3 0x30 /**< Bits containing the frame version 0b11. */ + +#define IE_HEADER_LENGTH_MASK 0x3f /**< Mask of bits containing the length of an IE header content. */ +#define IE_PRESENT_OFFSET 2 /**< Byte containing the IE Present bit. */ +#define IE_PRESENT_BIT 0x02 /**< Bits containing the IE Present field. */ + +#define KEY_ID_MODE_0 0 /**< Value of the 0x00 Key Identifier Mode. */ +#define KEY_ID_MODE_1 1 /**< Value of the 0x01 Key Identifier Mode. */ +#define KEY_ID_MODE_2 2 /**< Value of the 0x10 Key Identifier Mode. */ +#define KEY_ID_MODE_3 3 /**< Value of the 0x11 Key Identifier Mode. */ + +#define KEY_ID_MODE_MASK 0x18 /**< Mask of bits containing Key Identifier Mode in the Security Control field. */ +#define KEY_ID_MODE_BIT_OFFSET 3 /**< Number of bits the Key Identifier Mode is offset in the Security Control field. */ +#define KEY_ID_MODE_0_MASK 0 /**< Bits containing the 0x00 Key Identifier Mode. */ +#define KEY_ID_MODE_1_MASK 0x08 /**< Bits containing the 0x01 Key Identifier Mode. */ +#define KEY_ID_MODE_2_MASK 0x10 /**< Bits containing the 0x10 Key Identifier Mode. */ +#define KEY_ID_MODE_3_MASK 0x18 /**< Bits containing the 0x11 Key Identifier Mode. */ + +#define KEY_SRC_KEY_ID_MODE_0_SIZE 0 /**< Size of the Key Source field when Key Identifier Mode equals 0. */ +#define KEY_SRC_KEY_ID_MODE_1_SIZE 0 /**< Size of the Key Source field when Key Identifier Mode equals 1. */ +#define KEY_SRC_KEY_ID_MODE_2_SIZE 4 /**< Size of the Key Source field when Key Identifier Mode equals 2. */ +#define KEY_SRC_KEY_ID_MODE_3_SIZE 8 /**< Size of the Key Source field when Key Identifier Mode equals 3. */ + +#define KEY_IDX_SIZE 1 /**< Size of the Key Index field. */ + +#define MAC_CMD_COMMAND_ID_SIZE 1 /**< Size of the MAC Command ID field. */ +#define MAC_CMD_ASSOC_REQ 0x01 /**< Command frame identifier for MAC Association request. */ +#define MAC_CMD_ASSOC_RESP 0x02 /**< Command frame identifier for MAC Association response. */ +#define MAC_CMD_DISASSOC_NOTIFY 0x03 /**< Command frame identifier for MAC Disassociation notification. */ +#define MAC_CMD_DATA_REQ 0x04 /**< Command frame identifier for MAC Data request. */ +#define MAC_CMD_PANID_CONFLICT 0x05 /**< Command frame identifier for MAC PAN ID conflict notification. */ +#define MAC_CMD_ORPHAN_NOTIFY 0x06 /**< Command frame identifier for MAC Orphan notification. */ +#define MAC_CMD_BEACON_REQ 0x07 /**< Command frame identifier for MAC Beacon. */ +#define MAC_CMD_COORD_REALIGN 0x08 /**< Command frame identifier for MAC Coordinator realignment. */ +#define MAC_CMD_GTS_REQUEST 0x09 /**< Command frame identifier for MAC GTS request. */ + +#define PAN_ID_COMPR_OFFSET 1 /**< Byte containing the PAN ID compression bit (+1 for the frame length byte). */ +#define PAN_ID_COMPR_MASK 0x40 /**< PAN ID compression bit. */ + +#define PAN_ID_OFFSET 4 /**< Offset of PAN ID in the Data frame (+1 for the frame length byte). */ + +#define PHR_OFFSET 0 /**< Offset of the PHY header in a frame. */ +#define PHR_LENGTH_MASK 0x7f /**< Mask of the PHR length field. */ + +#define PSDU_OFFSET 1 /**< Offset of the PHY payload. */ + +#define SECURITY_ENABLED_OFFSET 1 /**< Byte containing the Security Enabled bit. */ +#define SECURITY_ENABLED_BIT 0x08 /**< Bits containing the Security Enabled field. */ +#define SECURITY_LEVEL_MASK 0x07 /**< Mask of bits containing the Security level field. */ +#define SECURITY_LEVEL_NONE 0x00 /**< Bits indicating a frame with no security attributes (0b000). */ +#define SECURITY_LEVEL_MIC_32 0x01 /**< Bits containing the 32-bit Message Integrity Code (0b001). */ +#define SECURITY_LEVEL_MIC_64 0x02 /**< Bits containing the 64-bit Message Integrity Code (0b010). */ +#define SECURITY_LEVEL_MIC_128 0x03 /**< Bits containing the 128-bit Message Integrity Code (0b011). */ +#define SECURITY_LEVEL_ENC_MIC_32 0x05 /**< Bits containing the 32-bit Encrypted Message Integrity Code (0b101). */ +#define SECURITY_LEVEL_ENC_MIC_64 0x06 /**< Bits containing the 64-bit Encrypted Message Integrity Code (0b110). */ +#define SECURITY_LEVEL_ENC_MIC_128 0x07 /**< Bits containing the 128-bit Encrypted Message Integrity Code (0b111). */ +#define SECURITY_LEVEL_MIC_LEVEL_MASK 0x03 /**< Mask of bits encoding the Message Integrity Code length. */ + +#define SRC_ADDR_TYPE_EXTENDED 0xc0 /**< Bits containing the extended source address type. */ +#define SRC_ADDR_TYPE_NONE 0x00 /**< Bits containing a not-present source address type. */ +#define SRC_ADDR_TYPE_MASK 0xc0 /**< Mask of bits containing the source address type. */ +#define SRC_ADDR_TYPE_OFFSET 2 /**< Byte containing the source address type (+1 for the frame length byte). */ +#define SRC_ADDR_TYPE_SHORT 0x80 /**< Bits containing the short source address type. */ + +#define SRC_ADDR_OFFSET_SHORT_DST 8 /**< Offset of the source address in the Data frame if the destination address is short. */ +#define SRC_ADDR_OFFSET_EXTENDED_DST 14 /**< Offset of the source address in the Data frame if the destination address is extended. */ + +#define DSN_SIZE 1 /**< Size of the Sequence Number field. */ +#define FCF_SIZE 2 /**< Size of the FCF field. */ +#define FCS_SIZE 2 /**< Size of the FCS field. */ +#define FRAME_COUNTER_SIZE 4 /**< Size of the Frame Counter field. */ +#define IE_HEADER_SIZE 2 /**< Size of the obligatory IE Header field elements. */ +#define IMM_ACK_LENGTH 5 /**< Length of the ACK frame. */ +#define KEY_ID_MODE_1_SIZE 1 /**< Size of the 0x01 Key Identifier Mode field. */ +#define KEY_ID_MODE_2_SIZE 5 /**< Size of the 0x10 Key Identifier Mode field. */ +#define KEY_ID_MODE_3_SIZE 9 /**< Size of the 0x11 Key Identifier Mode field. */ +#define MAX_PACKET_SIZE 127 /**< Maximum size of the radio packet. */ +#define MIC_32_SIZE 4 /**< Size of MIC with the MIC-32 and ENC-MIC-32 security attributes. */ +#define MIC_64_SIZE 8 /**< Size of MIC with the MIC-64 and ENC-MIC-64 security attributes. */ +#define MIC_128_SIZE 16 /**< Size of MIC with the MIC-128 and ENC-MIC-128 security attributes. */ +#define PAN_ID_SIZE 2 /**< Size of the PAN ID. */ +#define PHR_SIZE 1 /**< Size of the PHR field. */ +#define SECURITY_CONTROL_SIZE 1 /**< Size of the Security Control field. */ + +#define AES_CCM_KEY_SIZE 16 /**< Size of AES CCM Key. */ + +#define EXTENDED_ADDRESS_SIZE 8 /**< Size of the Extended Mac Address. */ +#define SHORT_ADDRESS_SIZE 2 /**< Size of the Short Mac Address. */ + +#define TURNAROUND_TIME 192UL /**< RX-to-TX or TX-to-RX turnaround time (aTurnaroundTime), in microseconds (us). */ +#define CCA_TIME 128UL /**< Time required to perform CCA detection (aCcaTime), in microseconds (us). */ +#define ACK_IFS TURNAROUND_TIME /**< ACK Inter Frame Spacing [us] - delay between last symbol of received frame and first symbol of transmitted ACK. */ +#define UNIT_BACKOFF_PERIOD (TURNAROUND_TIME + CCA_TIME) /**< Number of symbols in the basic time period used by CSMA-CA algorithm (aUnitBackoffPeriod), in (us). */ + +#define PHY_US_PER_SYMBOL 16 /**< Duration of a single symbol in microseconds (us). */ +#define PHY_SYMBOLS_PER_OCTET 2 /**< Number of symbols in a single byte (octet). */ +#define PHY_SHR_SYMBOLS 10 /**< Number of symbols in the Synchronization Header (SHR). */ + +#define PHY_MIN_RECEIVER_SENSITIVITY -85 /**< Lowest receiver sensitivity level in dBm according to 802.15.4-2020 specification, chapter 12.3.4 */ + +#define ED_RESULT_MAX 0xff /**< Maximal ED result. */ + +#define BROADCAST_ADDRESS ((uint8_t[SHORT_ADDRESS_SIZE]) {0xff, 0xff}) /**< Broadcast short address. */ + +#define MIN_SIFS_PERIOD_US 192 /**< Minimum Short IFS period default value in us. */ +#define MIN_LIFS_PERIOD_US 640 /**< Minimum Long IFS period default value in us. */ +#define MAX_SIFS_FRAME_SIZE 18 /**< Maximum frame length which can be followed by the Short Interframe Space. */ + +#define NRF_802154_RESERVED_CSMACA_ID (UINT32_MAX - 2) /**< Delayed timeslot identifier reserved for CSMA/CA procedure. */ +#define NRF_802154_RESERVED_DTX_ID (UINT32_MAX - 3) /**< Delayed timeslot identifier reserved for delayed transmissions. */ + +#define IE_VENDOR_ID 0x00 /**< Vendor-specific IE identifier. */ +#define IE_VENDOR_SIZE_MIN 3 /**< Vendor-specific IE minimum length. */ +#define IE_VENDOR_OUI_OFFSET 0 /**< Vendor-specific IE OUI offset. */ + +#define IE_VENDOR_THREAD_SUBTYPE_OFFSET 3 /**< Thread Vendor-specific IE subtype offset. */ +#define IE_VENDOR_THREAD_DATA_OFFSET 4 /**< Thread Vendor-specific IE DATA offset. */ +#define IE_VENDOR_THREAD_OUI 0xeab89b /**< Thread Vendor-specific IE OUI. */ +#define IE_VENDOR_THREAD_SIZE_MIN 4 /**< Thread Vendor-specific IE minimum length. */ + +#define IE_VENDOR_THREAD_ACK_PROBING_ID 0x00 /**< Thread Vendor-specific ACK Probing IE subtype ID. */ +#define IE_VENDOR_THREAD_ACK_SIZE_MIN 5 /**< Thread Vendor-specific ACK Probing IE minimum size. */ +#define IE_VENDOR_THREAD_ACK_SIZE_MAX 6 /**< Thread Vendor-specific ACK Probing IE maximum size. */ +#define IE_VENDOR_THREAD_RSSI_TOKEN 0x01 /**< Thread Vendor-specific ACK Probing IE RSSI value placeholder. */ +#define IE_VENDOR_THREAD_MARGIN_TOKEN 0x02 /**< Thread Vendor-specific ACK Probing IE Link margin value placeholder. */ +#define IE_VENDOR_THREAD_LQI_TOKEN 0x03 /**< Thread Vendor-specific ACK Probing IE LQI value placeholder. */ +#define IE_VENDOR_THREAD_RSSI_FLOOR -130 /**< Thread Vendor-specific ACK Probing RSSI floor value used for scaling. */ +#define IE_VENDOR_THREAD_MARGIN_FLOOR 0 /**< Thread Vendor-specific ACK Probing margin floor value used for scaling. */ +#define IE_VENDOR_THREAD_RSSI_CEIL 0 /**< Thread Vendor-specific ACK Probing RSSI ceil value used for scaling. */ +#define IE_VENDOR_THREAD_MARGIN_CEIL 130 /**< Thread Vendor-specific ACK Probing margin ceil value used for scaling. */ +#define IE_VENDOR_THREAD_CST_ID 0x02 /**< Thread Vendor-specific CST IE subtype ID. */ +#define IE_VENDOR_THREAD_CST_SIZE 8 /**< Thread Vendor-specific CST IE size. */ +#define IE_CSL_SYMBOLS_PER_UNIT 10 /**< Number of symbols per phase/period unit. */ +#define IE_CSL_PERIOD_MAX 0xffff /**< Maximum CSL IE phase/period value. */ +#define IE_CSL_SIZE_MIN 4 /**< Minimal size of the CSL IE. */ +#define IE_CSL_ID 0x1a /**< CSL IE identifier. */ + +#define IE_HT1 0x7e /**< Information Element Header Termination type 1. */ +#define IE_HT2 0x7f /**< Information Element Header Termination type 2. */ +#define IE_LENGTH_MASK 0x7f /**< Information element length mask. */ +#define IE_LENGTH_OFFSET 0x00 /**< Information element length offset. */ +#define IE_ID_OFFSET_0 0x00 /**< Offset of the octet containing the first part of the IE identifier. */ +#define IE_ID_OFFSET_1 0x01 /**< Offset of the octet containing the second part of the IE identifier. */ +#define IE_DATA_OFFSET 0x02 /**< Information element data offset. */ +#define IE_HEADER_ELEMENT_ID_OFFSET 0x07 /**< Bit offset of Element ID field in a Header IE header. */ + +#define ENH_ACK_MAX_SIZE MAX_PACKET_SIZE /**< Maximum length of the Enh-ACK frame. */ +#define ACK_MAX_SIZE ENH_ACK_MAX_SIZE /**< Maximum length of the ACK frame. */ typedef enum { @@ -242,4 +242,4 @@ typedef enum REQ_ORIG_IFS, } req_originator_t; -#endif // NRF_802154_CONST_H_ +#endif /* NRF_802154_CONST_H_ */ diff --git a/nrf_802154/common/include/nrf_802154_types.h b/nrf_802154/common/include/nrf_802154_types.h index c37093fb4c..5764c8b578 100644 --- a/nrf_802154/common/include/nrf_802154_types.h +++ b/nrf_802154/common/include/nrf_802154_types.h @@ -35,25 +35,31 @@ #ifndef NRF_802154_TYPES_H__ #define NRF_802154_TYPES_H__ -#include -#include -#include - /** * Avoid including nrfx dependencies in a build only containing * serialization commands */ -#if !NRF_802154_SERIALIZATION_HOST - #include "hal/nrf_radio.h" -#else +#if !NRF_802154_SERIALIZATION_HOST || defined(DOXYGEN) +#include "hal/nrf_radio.h" +#endif /* !NRF_802154_SERIALIZATION_HOST */ +#include + +#include +#include + +#if NRF_802154_SERIALIZATION_HOST || defined(DOXYGEN) + typedef uint8_t nrf_radio_cca_mode_t; -/** @brief RADIO Clear Channel Assessment modes. */ +/** + * @brief RADIO Clear Channel Assessment modes. + */ #define NRF_RADIO_CCA_MODE_ED 0x00 #define NRF_RADIO_CCA_MODE_CARRIER 0x01 #define NRF_RADIO_CCA_MODE_CARRIER_AND_ED 0x02 #define NRF_RADIO_CCA_MODE_CARRIER_OR_ED 0x03 -#endif + +#endif /* NRF_802154_SERIALIZATION_HOST */ /** * @defgroup nrf_802154_types Type definitions used in the 802.15.4 driver @@ -67,85 +73,85 @@ typedef uint8_t nrf_radio_cca_mode_t; */ typedef uint8_t nrf_802154_state_t; -#define NRF_802154_STATE_INVALID 0x01 // !< Radio in an invalid state. -#define NRF_802154_STATE_SLEEP 0x02 // !< Radio in the sleep state. -#define NRF_802154_STATE_RECEIVE 0x03 // !< Radio in the receive state. -#define NRF_802154_STATE_TRANSMIT 0x04 // !< Radio in the transmit state. -#define NRF_802154_STATE_ENERGY_DETECTION 0x05 // !< Radio in the energy detection state. -#define NRF_802154_STATE_CCA 0x06 // !< Radio in the CCA state. -#define NRF_802154_STATE_CONTINUOUS_CARRIER 0x07 // !< Radio in the continuous carrier state. -#define NRF_802154_STATE_MODULATED_CARRIER 0x08 // !< Radio in the modulated carrier state. +#define NRF_802154_STATE_INVALID 0x01 /**< Radio in an invalid state. */ +#define NRF_802154_STATE_SLEEP 0x02 /**< Radio in the sleep state. */ +#define NRF_802154_STATE_RECEIVE 0x03 /**< Radio in the receive state. */ +#define NRF_802154_STATE_TRANSMIT 0x04 /**< Radio in the transmit state. */ +#define NRF_802154_STATE_ENERGY_DETECTION 0x05 /**< Radio in the energy detection state. */ +#define NRF_802154_STATE_CCA 0x06 /**< Radio in the CCA state. */ +#define NRF_802154_STATE_CONTINUOUS_CARRIER 0x07 /**< Radio in the continuous carrier state. */ +#define NRF_802154_STATE_MODULATED_CARRIER 0x08 /**< Radio in the modulated carrier state. */ /** * @brief Errors reported during the frame transmission. */ typedef uint8_t nrf_802154_tx_error_t; -#define NRF_802154_TX_ERROR_NONE 0x00 // !< There is no transmit error. -#define NRF_802154_TX_ERROR_BUSY_CHANNEL 0x01 // !< CCA reported busy channel before the transmission. -#define NRF_802154_TX_ERROR_INVALID_ACK 0x02 // !< Received ACK frame is other than expected. -#define NRF_802154_TX_ERROR_NO_MEM 0x03 // !< No receive buffer is available to receive an ACK. -#define NRF_802154_TX_ERROR_TIMESLOT_ENDED 0x04 // !< Radio timeslot ended during the transmission procedure. -#define NRF_802154_TX_ERROR_NO_ACK 0x05 // !< ACK frame was not received during the timeout period. -#define NRF_802154_TX_ERROR_ABORTED 0x06 // !< Procedure was aborted by another operation. -#define NRF_802154_TX_ERROR_TIMESLOT_DENIED 0x07 // !< Transmission did not start due to a denied timeslot request. -#define NRF_802154_TX_ERROR_KEY_ID_INVALID 0x08 // !< Transmission did not start due to invalid key ID in frame's security header. -#define NRF_802154_TX_ERROR_FRAME_COUNTER_ERROR 0x09 // !< Transmission did not start due a frame counter error. -#define NRF_802154_TX_ERROR_TIMESTAMP_ENCODING_ERROR 0x0A // !< Timestamp could not been encoded in the transmission process. -#define NRF_802154_TX_ERROR_INVALID_REQUEST 0x0B // !< The frame or transmit metadata is invalid. +#define NRF_802154_TX_ERROR_NONE 0x00 /**< There is no transmit error. */ +#define NRF_802154_TX_ERROR_BUSY_CHANNEL 0x01 /**< CCA reported busy channel before the transmission. */ +#define NRF_802154_TX_ERROR_INVALID_ACK 0x02 /**< Received ACK frame is other than expected. */ +#define NRF_802154_TX_ERROR_NO_MEM 0x03 /**< No receive buffer is available to receive an ACK. */ +#define NRF_802154_TX_ERROR_TIMESLOT_ENDED 0x04 /**< Radio timeslot ended during the transmission procedure. */ +#define NRF_802154_TX_ERROR_NO_ACK 0x05 /**< ACK frame was not received during the timeout period. */ +#define NRF_802154_TX_ERROR_ABORTED 0x06 /**< Procedure was aborted by another operation. */ +#define NRF_802154_TX_ERROR_TIMESLOT_DENIED 0x07 /**< Transmission did not start due to a denied timeslot request. */ +#define NRF_802154_TX_ERROR_KEY_ID_INVALID 0x08 /**< Transmission did not start due to invalid key ID in frame's security header. */ +#define NRF_802154_TX_ERROR_FRAME_COUNTER_ERROR 0x09 /**< Transmission did not start due a frame counter error. */ +#define NRF_802154_TX_ERROR_TIMESTAMP_ENCODING_ERROR 0x0A /**< Timestamp could not be encoded in the transmission process. */ +#define NRF_802154_TX_ERROR_INVALID_REQUEST 0x0B /**< The frame or transmit metadata is invalid. */ /** * @brief Possible errors during the frame reception. */ typedef uint8_t nrf_802154_rx_error_t; -#define NRF_802154_RX_ERROR_NONE 0x00 // !< There is no receive error. -#define NRF_802154_RX_ERROR_INVALID_FRAME 0x01 // !< Received a malformed frame. -#define NRF_802154_RX_ERROR_INVALID_FCS 0x02 // !< Received a frame with an invalid checksum. -#define NRF_802154_RX_ERROR_INVALID_DEST_ADDR 0x03 // !< Received a frame with a mismatched destination address. -#define NRF_802154_RX_ERROR_RUNTIME 0x04 // !< Runtime error occurred (for example, CPU was held for too long). -#define NRF_802154_RX_ERROR_TIMESLOT_ENDED 0x05 // !< Radio timeslot ended during the frame reception. -#define NRF_802154_RX_ERROR_ABORTED 0x06 // !< Procedure was aborted by another operation. -#define NRF_802154_RX_ERROR_DELAYED_TIMESLOT_DENIED 0x07 // !< Delayed reception request was rejected due to a denied timeslot request. -#define NRF_802154_RX_ERROR_DELAYED_TIMEOUT 0x08 // !< Delayed reception timeslot ended. -#define NRF_802154_RX_ERROR_INVALID_LENGTH 0x09 // !< Received a frame with invalid length. -#define NRF_802154_RX_ERROR_DELAYED_ABORTED 0x0A // !< Delayed operation in the ongoing state was aborted by other request. -#define NRF_802154_RX_ERROR_NO_BUFFER 0x0B // !< Reception suppressed because there was no free buffer available. +#define NRF_802154_RX_ERROR_NONE 0x00 /**< There is no receive error. */ +#define NRF_802154_RX_ERROR_INVALID_FRAME 0x01 /**< Received a malformed frame. */ +#define NRF_802154_RX_ERROR_INVALID_FCS 0x02 /**< Received a frame with an invalid checksum. */ +#define NRF_802154_RX_ERROR_INVALID_DEST_ADDR 0x03 /**< Received a frame with a mismatched destination address. */ +#define NRF_802154_RX_ERROR_RUNTIME 0x04 /**< Runtime error occurred (for example, CPU was held for too long). */ +#define NRF_802154_RX_ERROR_TIMESLOT_ENDED 0x05 /**< Radio timeslot ended during the frame reception. */ +#define NRF_802154_RX_ERROR_ABORTED 0x06 /**< Procedure was aborted by another operation. */ +#define NRF_802154_RX_ERROR_DELAYED_TIMESLOT_DENIED 0x07 /**< Delayed reception request was rejected due to a denied timeslot request. */ +#define NRF_802154_RX_ERROR_DELAYED_TIMEOUT 0x08 /**< Delayed reception timeslot ended. */ +#define NRF_802154_RX_ERROR_INVALID_LENGTH 0x09 /**< Received a frame with invalid length. */ +#define NRF_802154_RX_ERROR_DELAYED_ABORTED 0x0A /**< Delayed operation in the ongoing state was aborted by other request. */ +#define NRF_802154_RX_ERROR_NO_BUFFER 0x0B /**< Reception suppressed because there was no free buffer available. */ /** * @brief Possible errors during the energy detection. */ typedef uint8_t nrf_802154_ed_error_t; -#define NRF_802154_ED_ERROR_ABORTED 0x01 // !< Procedure was aborted by another operation. +#define NRF_802154_ED_ERROR_ABORTED 0x01 /**< Procedure was aborted by another operation. */ /** * @brief Possible errors during the CCA procedure. */ typedef uint8_t nrf_802154_cca_error_t; -#define NRF_802154_CCA_ERROR_ABORTED 0x01 // !< Procedure was aborted by another operation. +#define NRF_802154_CCA_ERROR_ABORTED 0x01 /**< Procedure was aborted by another operation. */ /** * @brief Possible errors during sleep procedure call. */ typedef uint8_t nrf_802154_sleep_error_t; -#define NRF_802154_SLEEP_ERROR_NONE 0x00 // !< There is no error. -#define NRF_802154_SLEEP_ERROR_BUSY 0x01 // !< The driver cannot enter the sleep state due to the ongoing operation. +#define NRF_802154_SLEEP_ERROR_NONE 0x00 /**< There is no error. */ +#define NRF_802154_SLEEP_ERROR_BUSY 0x01 /**< The driver cannot enter the sleep state due to the ongoing operation. */ /** * @brief Possible errors during key handling. */ typedef uint8_t nrf_802154_security_error_t; -#define NRF_802154_SECURITY_ERROR_NONE 0x00 // !< There is no error. -#define NRF_802154_SECURITY_ERROR_STORAGE_FULL 0x01 // !< The key storage is full - removal of stored keys is needed. -#define NRF_802154_SECURITY_ERROR_KEY_NOT_FOUND 0x02 // !< The provided key was not found inside the storage. -#define NRF_802154_SECURITY_ERROR_ALREADY_PRESENT 0x03 // !< The storage already has the key of the same ID. -#define NRF_802154_SECURITY_ERROR_TYPE_NOT_SUPPORTED 0x04 // !< The provided key type is not supported. -#define NRF_802154_SECURITY_ERROR_MODE_NOT_SUPPORTED 0x05 // !< The provided key id mode is not supported. -#define NRF_802154_SECURITY_ERROR_FRAME_COUNTER_OVERFLOW 0x06 // !< The associated frame counter overflowed. +#define NRF_802154_SECURITY_ERROR_NONE 0x00 /**< There is no error. */ +#define NRF_802154_SECURITY_ERROR_STORAGE_FULL 0x01 /**< The key storage is full - removal of stored keys is needed. */ +#define NRF_802154_SECURITY_ERROR_KEY_NOT_FOUND 0x02 /**< The provided key was not found inside the storage. */ +#define NRF_802154_SECURITY_ERROR_ALREADY_PRESENT 0x03 /**< The storage already has the key of the same ID. */ +#define NRF_802154_SECURITY_ERROR_TYPE_NOT_SUPPORTED 0x04 /**< The provided key type is not supported. */ +#define NRF_802154_SECURITY_ERROR_MODE_NOT_SUPPORTED 0x05 /**< The provided key id mode is not supported. */ +#define NRF_802154_SECURITY_ERROR_FRAME_COUNTER_OVERFLOW 0x06 /**< The associated frame counter overflowed. */ /** * @brief Termination level selected for a particular request. @@ -155,18 +161,18 @@ typedef uint8_t nrf_802154_security_error_t; */ typedef uint8_t nrf_802154_term_t; -#define NRF_802154_TERM_NONE 0x00 // !< Request is skipped if another operation is ongoing. -#define NRF_802154_TERM_802154 0x01 // !< Request terminates the ongoing 802.15.4 operation. +#define NRF_802154_TERM_NONE 0x00 /**< Request is skipped if another operation is ongoing. */ +#define NRF_802154_TERM_802154 0x01 /**< Request terminates the ongoing 802.15.4 operation. */ /** * @brief Structure for configuring CCA. */ typedef struct { - nrf_radio_cca_mode_t mode; // !< CCA mode. - int8_t ed_threshold; // !< Busy threshold of the CCA energy. Not used in @ref NRF_RADIO_CCA_MODE_CARRIER. The threshold is absolute value in dBm. - uint8_t corr_threshold; // !< Busy threshold of the CCA correlator. Not used in @ref NRF_RADIO_CCA_MODE_ED. - uint8_t corr_limit; // !< Limit of occurrences above the busy threshold of the CCA correlator. Not used in @ref NRF_RADIO_CCA_MODE_ED. + nrf_radio_cca_mode_t mode; /**< CCA mode. */ + int8_t ed_threshold; /**< Busy threshold of the CCA energy. Not used in @ref NRF_RADIO_CCA_MODE_CARRIER. The threshold is absolute value in dBm. */ + uint8_t corr_threshold; /**< Busy threshold of the CCA correlator. Not used in @ref NRF_RADIO_CCA_MODE_ED. */ + uint8_t corr_limit; /**< Limit of occurrences above the busy threshold of the CCA correlator. Not used in @ref NRF_RADIO_CCA_MODE_ED. */ } nrf_802154_cca_cfg_t; /** @@ -174,8 +180,8 @@ typedef struct */ typedef uint8_t nrf_802154_ack_data_t; -#define NRF_802154_ACK_DATA_PENDING_BIT 0x00 // !< Frame Pending bit should be set in the Ack. -#define NRF_802154_ACK_DATA_IE 0x01 // !< Header Information Element should be set in the Ack. +#define NRF_802154_ACK_DATA_PENDING_BIT 0x00 /**< Frame Pending bit should be set in the Ack. */ +#define NRF_802154_ACK_DATA_IE 0x01 /**< Header Information Element should be set in the Ack. */ /** * @brief Methods of source address matching. @@ -190,9 +196,9 @@ typedef uint8_t nrf_802154_ack_data_t; */ typedef uint8_t nrf_802154_src_addr_match_t; -#define NRF_802154_SRC_ADDR_MATCH_THREAD 0x00 // !< Implementation for the Thread protocol. -#define NRF_802154_SRC_ADDR_MATCH_ZIGBEE 0x01 // !< Implementation for the Zigbee protocol. -#define NRF_802154_SRC_ADDR_MATCH_ALWAYS_1 0x02 // !< Standard compliant implementation. +#define NRF_802154_SRC_ADDR_MATCH_THREAD 0x00 /**< Implementation for the Thread protocol. */ +#define NRF_802154_SRC_ADDR_MATCH_ZIGBEE 0x01 /**< Implementation for the Zigbee protocol. */ +#define NRF_802154_SRC_ADDR_MATCH_ALWAYS_1 0x02 /**< Standard compliant implementation. */ /** * @brief RSSI measurement results. @@ -209,9 +215,9 @@ typedef uint8_t nrf_802154_src_addr_match_t; */ typedef uint8_t nrf_802154_test_mode_csmaca_backoff_t; -#define NRF_802154_TEST_MODE_CSMACA_BACKOFF_RANDOM 0x00 // !< The CSMA/CA uses random number of backoff periods (IEEE Std. 802.15.4 compliant) -#define NRF_802154_TEST_MODE_CSMACA_BACKOFF_ALWAYS_MAX 0x01 // !< The CSMA/CA uses always maximum backoff periods (Test mode, non-compliant to IEEE Std. 802.15.4) -#define NRF_802154_TEST_MODE_CSMACA_BACKOFF_ALWAYS_MIN 0x02 // !< The CSMA/CA uses always minimum backoff periods (Test mode, non-compliant to IEEE Std. 802.15.4) +#define NRF_802154_TEST_MODE_CSMACA_BACKOFF_RANDOM 0x00 /**< The CSMA/CA uses random number of backoff periods (IEEE Std. 802.15.4 compliant) */ +#define NRF_802154_TEST_MODE_CSMACA_BACKOFF_ALWAYS_MAX 0x01 /**< The CSMA/CA uses always maximum backoff periods (Test mode, non-compliant to IEEE Std. 802.15.4) */ +#define NRF_802154_TEST_MODE_CSMACA_BACKOFF_ALWAYS_MIN 0x02 /**< The CSMA/CA uses always minimum backoff periods (Test mode, non-compliant to IEEE Std. 802.15.4) */ /** * @brief Mode of triggering receive request to Coex arbiter. @@ -223,9 +229,9 @@ typedef uint8_t nrf_802154_test_mode_csmaca_backoff_t; */ typedef uint8_t nrf_802154_coex_rx_request_mode_t; -#define NRF_802154_COEX_RX_REQUEST_MODE_ENERGY_DETECTION 0x01 // !< Coex requests to arbiter in receive mode upon energy detected. -#define NRF_802154_COEX_RX_REQUEST_MODE_PREAMBLE 0x02 // !< Coex requests to arbiter in receive mode upon preamble reception. -#define NRF_802154_COEX_RX_REQUEST_MODE_DESTINED 0x03 // !< Coex requests to arbiter in receive mode upon detection that frame is addressed to this device. +#define NRF_802154_COEX_RX_REQUEST_MODE_ENERGY_DETECTION 0x01 /**< Coex requests to arbiter in receive mode upon energy detected. */ +#define NRF_802154_COEX_RX_REQUEST_MODE_PREAMBLE 0x02 /**< Coex requests to arbiter in receive mode upon preamble reception. */ +#define NRF_802154_COEX_RX_REQUEST_MODE_DESTINED 0x03 /**< Coex requests to arbiter in receive mode upon detection that frame is addressed to this device. */ /** * @brief Mode of triggering transmit request to Coex arbiter. @@ -238,10 +244,10 @@ typedef uint8_t nrf_802154_coex_rx_request_mode_t; */ typedef uint8_t nrf_802154_coex_tx_request_mode_t; -#define NRF_802154_COEX_TX_REQUEST_MODE_FRAME_READY 0x01 // !< Coex requests to arbiter in transmit mode when the frame is ready to be transmitted. -#define NRF_802154_COEX_TX_REQUEST_MODE_CCA_START 0x02 // !< Coex requests to arbiter in transmit mode before CCA is started. -#define NRF_802154_COEX_TX_REQUEST_MODE_CCA_DONE 0x03 // !< Coex requests to arbiter in transmit mode after CCA is finished. -#define NRF_802154_COEX_TX_REQUEST_MODE_ON_CCA_TOGGLE 0x04 // !< Coex requests to arbiter in transmit mode before CCA is started and releases the request if CCA reports busy channel. +#define NRF_802154_COEX_TX_REQUEST_MODE_FRAME_READY 0x01 /**< Coex requests to arbiter in transmit mode when the frame is ready to be transmitted. */ +#define NRF_802154_COEX_TX_REQUEST_MODE_CCA_START 0x02 /**< Coex requests to arbiter in transmit mode before CCA is started. */ +#define NRF_802154_COEX_TX_REQUEST_MODE_CCA_DONE 0x03 /**< Coex requests to arbiter in transmit mode after CCA is finished. */ +#define NRF_802154_COEX_TX_REQUEST_MODE_ON_CCA_TOGGLE 0x04 /**< Coex requests to arbiter in transmit mode before CCA is started and releases the request if CCA reports busy channel. */ /** * @brief Mode of handling Interframe spacing. @@ -253,9 +259,9 @@ typedef uint8_t nrf_802154_coex_tx_request_mode_t; */ typedef uint8_t nrf_802154_ifs_mode_t; -#define NRF_802154_IFS_MODE_DISABLED 0x00 // !< Interframe spacing is never inserted. -#define NRF_802154_IFS_MODE_MATCHING_ADDRESSES 0x01 // !< Interframe spacing is inserted only on matching addresses. -#define NRF_802154_IFS_MODE_ALWAYS 0x02 // !< Interframe spacing is always inserted. +#define NRF_802154_IFS_MODE_DISABLED 0x00 /**< Interframe spacing is never inserted. */ +#define NRF_802154_IFS_MODE_MATCHING_ADDRESSES 0x01 /**< Interframe spacing is inserted only on matching addresses. */ +#define NRF_802154_IFS_MODE_ALWAYS 0x02 /**< Interframe spacing is always inserted. */ /** * @brief Capabilities of nrf 802.15.4 radio driver @@ -273,14 +279,14 @@ typedef uint8_t nrf_802154_ifs_mode_t; */ typedef uint32_t nrf_802154_capabilities_t; -#define NRF_802154_CAPABILITY_CSMA (1UL << 0UL) // !< CSMA-CA supported -#define NRF_802154_CAPABILITY_DELAYED_TX (1UL << 1UL) // !< TX at specified time supported -#define NRF_802154_CAPABILITY_DELAYED_RX (1UL << 2UL) // !< RX at specified time supported -#define NRF_802154_CAPABILITY_ACK_TIMEOUT (1UL << 3UL) // !< ACK timeout supported -#define NRF_802154_CAPABILITY_ANT_DIVERSITY (1UL << 4UL) // !< Antenna diversity supported -#define NRF_802154_CAPABILITY_IFS (1UL << 5UL) // !< Inter-frame spacing supported -#define NRF_802154_CAPABILITY_TIMESTAMP (1UL << 6UL) // !< Frame timestamping supported -#define NRF_802154_CAPABILITY_SECURITY (1UL << 7UL) // !< Frame security supported +#define NRF_802154_CAPABILITY_CSMA (1UL << 0UL) /**< CSMA-CA supported. */ +#define NRF_802154_CAPABILITY_DELAYED_TX (1UL << 1UL) /**< TX at specified time supported. */ +#define NRF_802154_CAPABILITY_DELAYED_RX (1UL << 2UL) /**< RX at specified time supported. */ +#define NRF_802154_CAPABILITY_ACK_TIMEOUT (1UL << 3UL) /**< ACK timeout supported. */ +#define NRF_802154_CAPABILITY_ANT_DIVERSITY (1UL << 4UL) /**< Antenna diversity supported. */ +#define NRF_802154_CAPABILITY_IFS (1UL << 5UL) /**< Inter-frame spacing supported. */ +#define NRF_802154_CAPABILITY_TIMESTAMP (1UL << 6UL) /**< Frame timestamping supported. */ +#define NRF_802154_CAPABILITY_SECURITY (1UL << 7UL) /**< Frame security supported. */ /** * @brief Types of keys which can be used with the nRF 802.15.4 Radio Driver. @@ -291,7 +297,7 @@ typedef uint32_t nrf_802154_capabilities_t; */ typedef uint32_t nrf_802154_key_type_t; -#define NRF_802154_KEY_CLEARTEXT 0x00 // !< Key stored in clear text. +#define NRF_802154_KEY_CLEARTEXT 0x00 /**< Key stored in clear text. */ /** * @brief Type of structure holding statistic counters. @@ -300,22 +306,14 @@ typedef uint32_t nrf_802154_key_type_t; */ typedef struct { - /**@brief Number of failed CCA attempts. */ - uint32_t cca_failed_attempts; - /**@brief Number of frames received with correct CRC and with filtering passing. */ - uint32_t received_frames; - /**@brief Number of times energy was detected in receive mode.*/ - uint32_t received_energy_events; - /**@brief Number of times a preamble was received in receive mode. */ - uint32_t received_preambles; - /**@brief Number of coex requests issued to coex arbiter. */ - uint32_t coex_requests; - /**@brief Number of coex requests issued to coex arbiter that have been granted. */ - uint32_t coex_granted_requests; - /**@brief Number of coex requests issued to coex arbiter that have been denied. */ - uint32_t coex_denied_requests; - /**@brief Number of coex grant activations that have been not requested. */ - uint32_t coex_unsolicited_grants; + uint32_t cca_failed_attempts; /**< Number of failed CCA attempts. */ + uint32_t received_frames; /**< Number of frames received with correct CRC and with filtering passing. */ + uint32_t received_energy_events; /**< Number of times energy was detected in receive mode. */ + uint32_t received_preambles; /**< Number of times a preamble was received in receive mode. */ + uint32_t coex_requests; /**< Number of coex requests issued to coex arbiter. */ + uint32_t coex_granted_requests; /**< Number of coex requests issued to coex arbiter that have been granted. */ + uint32_t coex_denied_requests; /**< Number of coex requests issued to coex arbiter that have been denied. */ + uint32_t coex_unsolicited_grants; /**< Number of coex grant activations that have been not requested. */ } nrf_802154_stat_counters_t; /** @@ -323,18 +321,12 @@ typedef struct */ typedef struct { - /**@brief Time stamp of last CSMA/CA procedure started. */ - uint64_t last_csmaca_start_timestamp; - /**@brief Time stamp of last CCA start attempt. */ - uint64_t last_cca_start_timestamp; - /**@brief Time stamp of last CCA attempt finished with CCA IDLE (channel was free to transmit). */ - uint64_t last_cca_idle_timestamp; - /**@brief Time stamp when last bit of transmitted frame was sent on the air. */ - uint64_t last_tx_end_timestamp; - /**@brief Time stamp when last bit of acknowledge frame was received */ - uint64_t last_ack_end_timestamp; - /**@brief Time stamp when last bit of received frame was received. */ - uint64_t last_rx_end_timestamp; + uint64_t last_csmaca_start_timestamp; /**< Time stamp of last CSMA/CA procedure started. */ + uint64_t last_cca_start_timestamp; /**< Time stamp of last CCA start attempt. */ + uint64_t last_cca_idle_timestamp; /**< Time stamp of last CCA attempt finished with CCA IDLE (channel was free to transmit). */ + uint64_t last_tx_end_timestamp; /**< Time stamp when last bit of transmitted frame was sent on the air. */ + uint64_t last_ack_end_timestamp; /**< Time stamp when last bit of acknowledge frame was received */ + uint64_t last_rx_end_timestamp; /**< Time stamp when last bit of received frame was received. */ } nrf_802154_stat_timestamps_t; /** @@ -342,11 +334,8 @@ typedef struct */ typedef struct { - /**@brief Statistic counters */ - nrf_802154_stat_counters_t counters; - - /**@brief Time stamps of events */ - nrf_802154_stat_timestamps_t timestamps; + nrf_802154_stat_counters_t counters; /**< Statistic counters */ + nrf_802154_stat_timestamps_t timestamps; /**< Time stamps of events */ } nrf_802154_stats_t; /** @@ -359,8 +348,8 @@ typedef uint8_t nrf_802154_key_id_mode_t; */ typedef struct { - nrf_802154_key_id_mode_t mode; // !< Key Id Mode (0..3) - uint8_t * p_key_id; // !< Pointer to the Key Id field + nrf_802154_key_id_mode_t mode; /**< Key Id Mode (0..3) */ + uint8_t * p_key_id; /**< Pointer to the Key Id field */ } nrf_802154_key_id_t; /** @@ -370,12 +359,12 @@ typedef struct { union { - uint8_t * p_cleartext_key; // !< Pointer to the cleartext representation of the key. - } value; // !< Union holding different representations of the key. - nrf_802154_key_id_t id; // !< Key Id of the key. - nrf_802154_key_type_t type; // !< @ref nrf_802154_key_type_t type of the key used. - uint32_t frame_counter; // !< Frame counter to use in case @ref use_global_frame_counter is set to false. - bool use_global_frame_counter; // !< Whether to use the global frame counter instead of the one defined in this structure. + uint8_t * p_cleartext_key; /**< Pointer to the cleartext representation of the key. */ + } value; /**< Union holding different representations of the key. */ + nrf_802154_key_id_t id; /**< Key Id of the key. */ + nrf_802154_key_type_t type; /**< @ref nrf_802154_key_type_t type of the key used. */ + uint32_t frame_counter; /**< Frame counter to use in case @ref use_global_frame_counter is set to false. */ + bool use_global_frame_counter; /**< Whether to use the global frame counter instead of the one defined in this structure. */ } nrf_802154_key_t; /** @@ -397,8 +386,8 @@ typedef struct */ typedef struct { - bool is_secured; // !< If the frame to be transmitted is already secured (in the sense of IEEE 802.15.4 security operations). - bool dynamic_data_is_set; // !< If dynamic data of the frame frame to be transmitted is set. + bool is_secured; /**< If the frame to be transmitted is already secured (in the sense of IEEE 802.15.4 security operations). */ + bool dynamic_data_is_set; /**< If dynamic data of the frame frame to be transmitted is set. */ } nrf_802154_transmitted_frame_props_t; /** @@ -410,8 +399,8 @@ typedef struct */ typedef struct { - bool use_metadata_value; // !< Set to true if the value in @p power should be used as the TX power in dBm - int8_t power; // !< Transmission power in dBm + bool use_metadata_value; /**< Set to true if the value in @p power should be used as the TX power in dBm. */ + int8_t power; /**< Transmission power in dBm. */ } nrf_802154_tx_power_metadata_t; /** @@ -422,8 +411,8 @@ typedef struct */ typedef struct { - bool use_metadata_value; // !< Set to true if the value in @p channel should be used as the TX channel - uint8_t channel; // !< Transmission channel + bool use_metadata_value; /**< Set to true if the value in @p channel should be used as the TX channel. */ + uint8_t channel; /**< Transmission channel. */ } nrf_802154_tx_channel_metadata_t; /** @@ -440,11 +429,11 @@ typedef struct */ typedef struct { - nrf_802154_transmitted_frame_props_t frame_props; // !< Properties of the frame to be transmitted. - bool cca; // !< If the driver is to perform a CCA procedure before transmission. - nrf_802154_tx_power_metadata_t tx_power; // !< Information about the TX power to be used. - nrf_802154_tx_channel_metadata_t tx_channel; // !< Information about the TX channel to be used. - bool tx_timestamp_encode; // !< True if the transmit timestamp shall be encoded in the payload. + nrf_802154_transmitted_frame_props_t frame_props; /**< Properties of the frame to be transmitted. */ + bool cca; /**< If the driver is to perform a CCA procedure before transmission. */ + nrf_802154_tx_power_metadata_t tx_power; /**< Information about the TX power to be used. */ + nrf_802154_tx_channel_metadata_t tx_channel; /**< Information about the TX channel to be used. */ + bool tx_timestamp_encode; /**< True if the transmit timestamp shall be encoded in the payload. */ } nrf_802154_transmit_metadata_t; /** @@ -452,12 +441,12 @@ typedef struct */ typedef struct { - nrf_802154_transmitted_frame_props_t frame_props; // !< Properties of the frame to be transmitted. - bool cca; // !< If the driver is to perform a CCA procedure before transmission. - uint8_t channel; // !< Radio channel on which the frame is to be transmitted. - nrf_802154_tx_power_metadata_t tx_power; // !< Information about the TX power to be used. - uint8_t extra_cca_attempts; // !< Maximum number of additional CCA attempts that can be performed if the first attempt returns busy channel. Ignored if @ref cca equals @c false. - bool tx_timestamp_encode; // !< True if the transmit timestamp shall be encoded in the payload. + nrf_802154_transmitted_frame_props_t frame_props; /**< Properties of the frame to be transmitted. */ + bool cca; /**< If the driver is to perform a CCA procedure before transmission. */ + uint8_t channel; /**< Radio channel on which the frame is to be transmitted. */ + nrf_802154_tx_power_metadata_t tx_power; /**< Information about the TX power to be used. */ + uint8_t extra_cca_attempts; /**< Maximum number of additional CCA attempts that can be performed if the first attempt returns busy channel. Ignored if @ref cca equals @c false. */ + bool tx_timestamp_encode; /**< True if the transmit timestamp shall be encoded in the payload. */ } nrf_802154_transmit_at_metadata_t; /** @@ -465,10 +454,10 @@ typedef struct */ typedef struct { - nrf_802154_transmitted_frame_props_t frame_props; // !< Properties of the frame to be transmitted. - nrf_802154_tx_power_metadata_t tx_power; // !< Information about the TX power to be used. - nrf_802154_tx_channel_metadata_t tx_channel; // !< Information about the TX channel to be used. - bool tx_timestamp_encode; // !< True if the transmit timestamp shall be encoded in the payload. + nrf_802154_transmitted_frame_props_t frame_props; /**< Properties of the frame to be transmitted. */ + nrf_802154_tx_power_metadata_t tx_power; /**< Information about the TX power to be used. */ + nrf_802154_tx_channel_metadata_t tx_channel; /**< Information about the TX channel to be used. */ + bool tx_timestamp_encode; /**< True if the transmit timestamp shall be encoded in the payload. */ } nrf_802154_transmit_csma_ca_metadata_t; /** @@ -476,22 +465,22 @@ typedef struct */ typedef struct { - nrf_802154_transmitted_frame_props_t frame_props; // !< Properties of the returned frame. + nrf_802154_transmitted_frame_props_t frame_props; /**< Properties of the returned frame. */ union { struct { - uint8_t * p_ack; // !< A pointer to a buffer that contains PHR and PSDU of the received ACK. The first byte - // in the buffer is the length of the frame (PHR). The following bytes contain the ACK frame itself (PSDU). The length byte - // (PHR) includes FCS. FCS is already verified by the hardware and may be modified by the hardware. - // If ACK was not requested or requested but not received, @ref p_ack is set to NULL. - uint8_t length; // !< Length of the received ACK payload or 0 if @ref p_ack is NULL. - int8_t power; // !< RSSI of the received frame or 0 if @ref p_ack is NULL. - uint8_t lqi; // !< LQI of the received frame or 0 if @ref p_ack is NULL. - uint64_t time; // !< Timestamp taken when the last symbol of ACK is received. If @ref p_ack is NULL, this field is set to 0, but is considered invalid. - } transmitted; // !< Result values for a successful frame transmission. - } data; // !< Result values that are valid only for successful operations. + uint8_t * p_ack; /**< A pointer to a buffer that contains PHR and PSDU of the received ACK. The first byte + * in the buffer is the length of the frame (PHR). The following bytes contain the ACK frame itself (PSDU). The length byte + * (PHR) includes FCS. FCS is already verified by the hardware and may be modified by the hardware. + * If ACK was not requested or requested but not received, @ref p_ack is set to NULL. */ + uint8_t length; /**< Length of the received ACK payload or 0 if @ref p_ack is NULL. */ + int8_t power; /**< RSSI of the received frame or 0 if @ref p_ack is NULL. */ + uint8_t lqi; /**< LQI of the received frame or 0 if @ref p_ack is NULL. */ + uint64_t time; /**< Timestamp taken when the last symbol of ACK is received. If @ref p_ack is NULL, this field is set to 0, but is considered invalid. */ + } transmitted; /**< Result values for a successful frame transmission. */ + } data; /**< Result values that are valid only for successful operations. */ } nrf_802154_transmit_done_metadata_t; /** @@ -499,11 +488,11 @@ typedef struct */ typedef struct { - int8_t ed_dbm; // !< Maximum detected ED in dBm. + int8_t ed_dbm; /**< Maximum detected ED in dBm. */ } nrf_802154_energy_detected_t; /** *@} **/ -#endif // NRF_802154_TYPES_H__ +#endif /* NRF_802154_TYPES_H__ */ diff --git a/nrf_802154/driver/src/mac_features/ack_generator/nrf_802154_ack_data.c b/nrf_802154/driver/src/mac_features/ack_generator/nrf_802154_ack_data.c index 02fadd8132..d4b397098a 100644 --- a/nrf_802154/driver/src/mac_features/ack_generator/nrf_802154_ack_data.c +++ b/nrf_802154/driver/src/mac_features/ack_generator/nrf_802154_ack_data.c @@ -48,52 +48,52 @@ #include "nrf_802154_config.h" #include "nrf_802154_const.h" -/// Maximum number of Short Addresses of nodes for which there is ACK data to set. +/** Maximum number of Short Addresses of nodes for which there is ACK data to set. */ #define NUM_SHORT_ADDRESSES NRF_802154_PENDING_SHORT_ADDRESSES -/// Maximum number of Extended Addresses of nodes for which there is ACK data to set. +/** Maximum number of Extended Addresses of nodes for which there is ACK data to set. */ #define NUM_EXTENDED_ADDRESSES NRF_802154_PENDING_EXTENDED_ADDRESSES -/// Structure representing pending bit setting variables. +/** Structure representing pending bit setting variables. */ typedef struct { - bool enabled; /// If setting pending bit is enabled. - uint8_t short_addr[NUM_SHORT_ADDRESSES][SHORT_ADDRESS_SIZE]; /// Array of short addresses of nodes for which there is pending data in the buffer. - uint8_t extended_addr[NUM_EXTENDED_ADDRESSES][EXTENDED_ADDRESS_SIZE]; /// Array of extended addresses of nodes for which there is pending data in the buffer. - uint32_t num_of_short_addr; /// Current number of short addresses of nodes for which there is pending data in the buffer. - uint32_t num_of_ext_addr; /// Current number of extended addresses of nodes for which there is pending data in the buffer. + bool enabled; /**< If setting pending bit is enabled. */ + uint8_t short_addr[NUM_SHORT_ADDRESSES][SHORT_ADDRESS_SIZE]; /**< Array of short addresses of nodes for which there is pending data in the buffer. */ + uint8_t extended_addr[NUM_EXTENDED_ADDRESSES][EXTENDED_ADDRESS_SIZE]; /**< Array of extended addresses of nodes for which there is pending data in the buffer. */ + uint32_t num_of_short_addr; /**< Current number of short addresses of nodes for which there is pending data in the buffer. */ + uint32_t num_of_ext_addr; /**< Current number of extended addresses of nodes for which there is pending data in the buffer. */ } pending_bit_arrays_t; -// Structure representing a single IE record. +/* Structure representing a single IE record. */ typedef struct { - uint8_t p_data[NRF_802154_MAX_ACK_IE_SIZE]; /// Pointer to IE data buffer. - uint8_t len; /// Length of the buffer. + uint8_t p_data[NRF_802154_MAX_ACK_IE_SIZE]; /**< Pointer to IE data buffer. */ + uint8_t len; /**< Length of the buffer. */ } ie_data_t; -// Structure representing IE records sent in an ACK message to a given short address. +/* Structure representing IE records sent in an ACK message to a given short address. */ typedef struct { - uint8_t addr[SHORT_ADDRESS_SIZE]; /// Short address of peer node. - ie_data_t ie_data; /// Pointer to IE records. + uint8_t addr[SHORT_ADDRESS_SIZE]; /**< Short address of peer node. */ + ie_data_t ie_data; /**< Pointer to IE records. */ } ack_short_ie_data_t; -// Structure representing IE records sent in an ACK message to a given extended address. +/* Structure representing IE records sent in an ACK message to a given extended address. */ typedef struct { - uint8_t addr[EXTENDED_ADDRESS_SIZE]; /// Extended address of peer node. - ie_data_t ie_data; /// Pointer to IE records. + uint8_t addr[EXTENDED_ADDRESS_SIZE]; /**< Extended address of peer node. */ + ie_data_t ie_data; /**< Pointer to IE records. */ } ack_ext_ie_data_t; -// Structure representing IE data setting variables. +/* Structure representing IE data setting variables. */ typedef struct { - ack_short_ie_data_t short_data[NUM_SHORT_ADDRESSES]; /// Array of short addresses and IE records sent to these addresses. - ack_ext_ie_data_t ext_data[NUM_EXTENDED_ADDRESSES]; /// Array of extended addresses and IE records sent to these addresses. - uint32_t num_of_short_data; /// Current number of short addresses stored in @p short_data. - uint32_t num_of_ext_data; /// Current number of extended addresses stored in @p ext_data. + ack_short_ie_data_t short_data[NUM_SHORT_ADDRESSES]; /**< Array of short addresses and IE records sent to these addresses. */ + ack_ext_ie_data_t ext_data[NUM_EXTENDED_ADDRESSES]; /**< Array of extended addresses and IE records sent to these addresses. */ + uint32_t num_of_short_data; /**< Current number of short addresses stored in @p short_data. */ + uint32_t num_of_ext_data; /**< Current number of extended addresses stored in @p ext_data. */ } ie_arrays_t; -// TODO: Combine below arrays to perform binary search only once per Ack generation. +/* TODO: Combine below arrays to perform binary search only once per ACK generation. */ static pending_bit_arrays_t m_pending_bit; static ie_arrays_t m_ie; static nrf_802154_src_addr_match_t m_src_matching_method; @@ -117,7 +117,7 @@ static int8_t extended_addr_compare(const uint8_t * p_first_addr, const uint8_t uint32_t first_addr; uint32_t second_addr; - // Compare extended address in two steps to prevent unaligned access error. + /* Compare extended address in two steps to prevent unaligned access error. */ for (uint32_t i = 0; i < EXTENDED_ADDRESS_SIZE / sizeof(uint32_t); i++) { first_addr = *(const uint32_t *)(p_first_addr + (i * sizeof(uint32_t))); @@ -230,7 +230,7 @@ static bool addr_binary_search(const uint8_t * p_addr, break; } - // The actual algorithm + /* The actual algorithm */ int32_t low = 0; uint32_t midpoint = 0; int32_t high = addr_array_len; @@ -270,7 +270,8 @@ static bool addr_binary_search(const uint8_t * p_addr, * last iteration, midpoint is equal to 1 and low and high are equal to 0. Midpoint is then set * to 0 and with last case being utilized, low is set to 1. However, midpoint equal to 0 is * incorrect, as in the last iteration first element of the array proves to be less than the - * element to be added to the array. With the below code, midpoint is then shifted to 1. */ + * element to be added to the array. With the below code, midpoint is then shifted to 1. + */ if ((uint32_t)low == midpoint + 1) { midpoint++; @@ -339,7 +340,7 @@ static bool addr_match_thread(const nrf_802154_frame_t * p_frame_data) bool extended = nrf_802154_frame_src_addr_is_extended(p_frame_data); const uint8_t * p_src_addr = nrf_802154_frame_src_addr_get(p_frame_data); - // The pending bit is set by default. + /* The pending bit is set by default. */ if (!m_pending_bit.enabled || (NULL == p_src_addr)) { return true; @@ -364,25 +365,25 @@ static bool addr_match_zigbee(const nrf_802154_frame_t * p_frame_data) const uint8_t * p_src_addr; bool ret = false; - // If ack data generator module is disabled do not perform check, return true by default. + /* If ack data generator module is disabled do not perform check, return true by default. */ if (!m_pending_bit.enabled) { return true; } - // Check the frame type. + /* Check the frame type. */ p_src_addr = nrf_802154_frame_src_addr_get(p_frame_data); src_addr_type = nrf_802154_frame_src_addr_type_get(p_frame_data); p_cmd = nrf_802154_frame_mac_command_id_get(p_frame_data); - // Check frame type and command type. + /* Check frame type and command type. */ if ((p_cmd != NULL) && (*p_cmd == MAC_CMD_DATA_REQ)) { - // Check addressing type - in long case address, pb should always be 1. + /* Check addressing type - in long case address, pb should always be 1. */ if (src_addr_type == SRC_ADDR_TYPE_SHORT) { - // Return true if address is not found on the m_pending_bits list. + /* Return true if address is not found on the m_pending_bits list. */ ret = !addr_index_find(p_src_addr, &location, NRF_802154_ACK_DATA_PENDING_BIT, @@ -494,7 +495,8 @@ static bool addr_add(const uint8_t * p_addr, if (data_type == NRF_802154_ACK_DATA_IE) { /* The content of ie_data_t in the structure indexed by location - * is uninitialized (can have old content). Let's initialize it. */ + * is uninitialized (can have old content). Let's initialize it. + */ ie_data_t * p_ie_data = extended ? &(((ack_ext_ie_data_t *)p_entry_at_location)->ie_data) : &(((ack_short_ie_data_t *)p_entry_at_location)->ie_data); @@ -619,7 +621,6 @@ static bool ie_data_set(uint32_t location, bool extended, const uint8_t * p_data } /* Append IE data with the new IE. */ - if (ie_data->len + data_len > NRF_802154_MAX_ACK_IE_SIZE) { /* No space to fit it the new IE. */ diff --git a/nrf_802154/driver/src/mac_features/ack_generator/nrf_802154_ack_data.h b/nrf_802154/driver/src/mac_features/ack_generator/nrf_802154_ack_data.h index c26baa5144..f20d3ecb8b 100644 --- a/nrf_802154/driver/src/mac_features/ack_generator/nrf_802154_ack_data.h +++ b/nrf_802154/driver/src/mac_features/ack_generator/nrf_802154_ack_data.h @@ -48,7 +48,7 @@ #include "mac_features/nrf_802154_frame.h" /** - * @brief Initializes the ACK data generator module. + * @brief Initialize the ACK data generator module. */ void nrf_802154_ack_data_init(void); @@ -60,7 +60,7 @@ void nrf_802154_ack_data_init(void); void nrf_802154_ack_data_enable(bool enabled); /** - * @brief Adds an address to the ACK data list. + * @brief Add an address to the ACK data list. * * ACK frames sent in response to frames with the source address matching any address from the ACK data list * will have the appropriate data set. If the source address does not match any of the addresses in the @@ -82,7 +82,7 @@ bool nrf_802154_ack_data_for_addr_set(const uint8_t * p_addr, uint8_t data_len); /** - * @brief Removes an address from the ACK data list. + * @brief Remove an address from the ACK data list. * * ACK frames sent in response to frames with the source address matching any address from * the ACK data list will have the appropriate data set. If the source address does not match @@ -100,7 +100,7 @@ bool nrf_802154_ack_data_for_addr_clear(const uint8_t * p_addr, nrf_802154_ack_data_t data_type); /** - * @brief Removes all addresses of a given length from the ACK data list. + * @brief Remove all addresses of a given length from the ACK data list. * * @param[in] extended Indication if all extended addresses or all short addresses are * to be removed from the list. @@ -122,7 +122,7 @@ void nrf_802154_ack_data_reset(bool extended, nrf_802154_ack_data_t data_type); void nrf_802154_ack_data_src_addr_matching_method_set(nrf_802154_src_addr_match_t match_method); /** - * @brief Checks if a pending bit is to be set in the ACK frame sent in response to a given frame. + * @brief Check if a pending bit is to be set in the ACK frame sent in response to a given frame. * * @param[in] p_frame_data Pointer to the frame parser data for which the ACK frame is being prepared. * @@ -133,7 +133,7 @@ bool nrf_802154_ack_data_pending_bit_should_be_set( const nrf_802154_frame_t * p_frame_data); /** - * @brief Gets the IE data stored in the list for the source address of the provided frame. + * @brief Get the IE data stored in the list for the source address of the provided frame. * * @param[in] p_src_addr Pointer to the source address to search for in the list. * @param[in] src_addr_ext If the source address is extended. @@ -145,4 +145,4 @@ const uint8_t * nrf_802154_ack_data_ie_get(const uint8_t * p_src_addr, bool src_addr_ext, uint8_t * p_ie_length); -#endif // NRF_802154_ACK_DATA_H +#endif /* NRF_802154_ACK_DATA_H */ diff --git a/nrf_802154/driver/src/mac_features/ack_generator/nrf_802154_ack_generator.c b/nrf_802154/driver/src/mac_features/ack_generator/nrf_802154_ack_generator.c index b1a2216525..fc390fdfbe 100644 --- a/nrf_802154/driver/src/mac_features/ack_generator/nrf_802154_ack_generator.c +++ b/nrf_802154/driver/src/mac_features/ack_generator/nrf_802154_ack_generator.c @@ -72,21 +72,21 @@ static frame_version_t frame_version_is_2015_or_above( void nrf_802154_ack_generator_init(void) { - // Both generators are initialized to enable sending both Imm-Acks and Enh-Acks. + /* Both generators are initialized to enable sending both Imm-Acks and Enh-Acks. */ nrf_802154_imm_ack_generator_init(); nrf_802154_enh_ack_generator_init(); } void nrf_802154_ack_generator_reset(void) { - // Both generators are reset to enable sending both Imm-Ack and Enh-Ack. + /* Both generators are reset to enable sending both Imm-Ack and Enh-Ack. */ nrf_802154_imm_ack_generator_reset(); nrf_802154_enh_ack_generator_reset(); } uint8_t * nrf_802154_ack_generator_create(const nrf_802154_frame_t * p_frame_data) { - // This function should not be called if ACK is not requested. + /* This function should not be called if ACK is not requested. */ NRF_802154_ASSERT(nrf_802154_frame_ar_bit_is_set(p_frame_data)); switch (frame_version_is_2015_or_above(p_frame_data)) diff --git a/nrf_802154/driver/src/mac_features/ack_generator/nrf_802154_ack_generator.h b/nrf_802154/driver/src/mac_features/ack_generator/nrf_802154_ack_generator.h index 4c38971599..b4e6a1f144 100644 --- a/nrf_802154/driver/src/mac_features/ack_generator/nrf_802154_ack_generator.h +++ b/nrf_802154/driver/src/mac_features/ack_generator/nrf_802154_ack_generator.h @@ -44,17 +44,21 @@ #include "mac_features/nrf_802154_frame.h" -/** Initializes the ACK generator module. */ +/** + * @brief Initialize the ACK generator module. + */ void nrf_802154_ack_generator_init(void); -/** @brief Resets the ACK generator module. +/** + * @brief Reset the ACK generator module. * * @note This function should be called for every received frame to be acknowledged before * @ref nrf_802154_ack_generator_create is called for that frame. */ void nrf_802154_ack_generator_reset(void); -/** @brief Creates an ACK in response to the provided frame and inserts it into a radio buffer. +/** + * @brief Create an ACK in response to the provided frame and insert it into a radio buffer. * * @note Only those contents of the frame being acknowledged marked by @p p_frame_data as valid * are used for ACK generation. If any data necessary to generate an ACK is missing or marked as @@ -68,7 +72,6 @@ void nrf_802154_ack_generator_reset(void); * @returns Either pointer to a constant buffer that contains PHR and PSDU * of the created ACK frame, or NULL when the response cannot be created. */ -uint8_t * nrf_802154_ack_generator_create( - const nrf_802154_frame_t * p_frame_data); +uint8_t * nrf_802154_ack_generator_create(const nrf_802154_frame_t * p_frame_data); -#endif // NRF_802154_ACK_GENERATOR_H +#endif /* NRF_802154_ACK_GENERATOR_H */ diff --git a/nrf_802154/driver/src/mac_features/ack_generator/nrf_802154_enh_ack_generator.c b/nrf_802154/driver/src/mac_features/ack_generator/nrf_802154_enh_ack_generator.c index 551487fb94..7d7386930a 100644 --- a/nrf_802154/driver/src/mac_features/ack_generator/nrf_802154_enh_ack_generator.c +++ b/nrf_802154/driver/src/mac_features/ack_generator/nrf_802154_enh_ack_generator.c @@ -186,8 +186,9 @@ static uint8_t frame_control_set(const nrf_802154_frame_t * p_frame_data, if (level >= PARSE_LEVEL_FULL) { - // As some frame pending bit setting algorithms depend on MAC payload, - // the entire frame must be known to set this field. + /* As some frame pending bit setting algorithms depend on MAC payload, + * the entire frame must be known to set this field. + */ fcf_frame_pending_set(p_frame_data); } @@ -211,7 +212,7 @@ static uint8_t destination_set(const nrf_802154_frame_t * p_frame_data, uint8_t src_addr_size = nrf_802154_frame_src_addr_size_get(p_frame_data); - // Fill the Ack destination PAN ID field. + /* Fill the Ack destination PAN ID field. */ if (p_ack_dst_panid != NULL) { const uint8_t * p_dst_panid; @@ -233,7 +234,7 @@ static uint8_t destination_set(const nrf_802154_frame_t * p_frame_data, bytes_written += PAN_ID_SIZE; } - // Fill the Ack destination address field. + /* Fill the Ack destination address field. */ if ((p_ack_dst_addr != NULL) && (p_frame_src_addr != NULL)) { NRF_802154_ASSERT(nrf_802154_frame_dst_addr_is_extended(p_ack_data) == @@ -248,7 +249,7 @@ static uint8_t destination_set(const nrf_802154_frame_t * p_frame_data, static void source_set(void) { - // Intentionally empty: source address type is None. + /* Intentionally empty: source address type is None. */ } /*************************************************************************************************** @@ -307,7 +308,7 @@ static bool frame_counter_set(nrf_802154_frame_t * p_ack_data, if (p_frame_counter == NULL) { - // The frame counter is suppressed + /* The frame counter is suppressed */ *p_bytes_written = 0; return true; } @@ -322,7 +323,7 @@ static bool frame_counter_set(nrf_802154_frame_t * p_ack_data, return false; } - // Set the frame counter value in security header of the ACK frame + /* Set the frame counter value in security header of the ACK frame */ host_32_to_little(new_fc_value, p_frame_counter); *p_bytes_written = FRAME_COUNTER_SIZE; @@ -350,11 +351,11 @@ static bool security_header_set(const nrf_802154_frame_t * p_frame_data, return true; } - // All the bits in the security control byte can be copied. + /* All the bits in the security control byte can be copied. */ *ack_sec_ctrl = *frame_sec_ctrl; bytes_written += SECURITY_CONTROL_SIZE; - // Security control field is now ready. The parsing of the frame can advance. + /* Security control field is now ready. The parsing of the frame can advance. */ result = nrf_802154_frame_parser_valid_data_extend(p_ack_data, ack_sec_ctrl_offset + PHR_SIZE, PARSE_LEVEL_SEC_CTRL_OFFSETS); @@ -363,10 +364,11 @@ static bool security_header_set(const nrf_802154_frame_t * p_frame_data, if (nrf_802154_frame_sec_ctrl_sec_lvl_get(p_frame_data) == SECURITY_LEVEL_NONE) { - // The security level value is zero, therefore no auxiliary security header processing - // is performed according to 802.15.4 specification. This also applies to the frame counter, - // the value of which is left as it is in the message to which the ACK responds. - // The entire auxiliary security header content is simply copied to ACK. + /* The security level value is zero, therefore no auxiliary security header processing + * is performed according to 802.15.4 specification. This also applies to the frame counter, + * the value of which is left as it is in the message to which the ACK responds. + * The entire auxiliary security header content is simply copied to ACK. + */ uint8_t sec_hdr_size = security_header_size(p_frame_data) - SECURITY_CONTROL_SIZE; memcpy(ack_sec_ctrl + SECURITY_CONTROL_SIZE, @@ -411,8 +413,10 @@ static void ie_header_set(const uint8_t * p_ie_data, memcpy(p_ack_ie, p_ie_data, ie_data_len); #if NRF_802154_IE_WRITER_ENABLED + nrf_802154_ie_writer_prepare(p_ack_ie, p_ack_ie + ie_data_len); -#endif + +#endif /* NRF_802154_IE_WRITER_ENABLED */ } /*************************************************************************************************** @@ -422,6 +426,7 @@ static void ie_header_set(const uint8_t * p_ie_data, static bool encryption_prepare(const nrf_802154_frame_t * p_ack_data) { #if NRF_802154_ENCRYPTION_ENABLED + if (nrf_802154_frame_security_enabled_bit_is_set(p_ack_data) == false) { return true; @@ -433,9 +438,12 @@ static bool encryption_prepare(const nrf_802154_frame_t * p_ack_data) } return nrf_802154_encrypt_ack_prepare(p_ack_data); -#else // NRF_802154_ENCRYPTION_ENABLED + +#else /* NRF_802154_ENCRYPTION_ENABLED */ + return true; -#endif // NRF_802154_ENCRYPTION_ENABLED + +#endif /* NRF_802154_ENCRYPTION_ENABLED */ } /*************************************************************************************************** @@ -444,8 +452,9 @@ static bool encryption_prepare(const nrf_802154_frame_t * p_ack_data) static void fcf_process(const nrf_802154_frame_t * p_frame_data) { - // Set Frame Control field bits. - // Some of them might require correction when higher parse level is available + /* Set Frame Control field bits. + * Some of them might require correction when higher parse level is available. + */ m_ack[PHR_OFFSET] += frame_control_set(p_frame_data, false); bool result = nrf_802154_frame_parser_valid_data_extend(&m_ack_data, @@ -458,22 +467,21 @@ static void fcf_process(const nrf_802154_frame_t * p_frame_data) static void addr_end_process(const nrf_802154_frame_t * p_frame_data) { - // Set valid sequence number in ACK frame. + /* Set valid sequence number in ACK frame. */ m_ack[PHR_OFFSET] += sequence_number_set(p_frame_data); - // Set destination address and PAN ID. + /* Set destination address and PAN ID. */ m_ack[PHR_OFFSET] += destination_set(p_frame_data, &m_ack_data); - // Set source address and PAN ID. + /* Set source address and PAN ID. */ source_set(); - // Having the frame's source address, presence of IEs can be determined. - // coverity[unchecked_value] + /* Having the frame's source address, presence of IEs can be determined. */ mp_ie_data = nrf_802154_ack_data_ie_get( nrf_802154_frame_src_addr_get(p_frame_data), nrf_802154_frame_src_addr_is_extended(p_frame_data), &m_ie_data_len); - // Update the IE present bit in Frame Control field knowing if IEs should be present. + /* Update the IE present bit in Frame Control field knowing if IEs should be present. */ fcf_ie_present_set(mp_ie_data != NULL); bool result = nrf_802154_frame_parser_valid_data_extend(&m_ack_data, @@ -507,11 +515,11 @@ static bool aux_sec_hdr_process(const nrf_802154_frame_t * p_frame_data) static void ie_process(const nrf_802154_frame_t * p_frame_data) { - // Set IE header. + /* Set IE header. */ ie_header_set(mp_ie_data, m_ie_data_len, &m_ack_data); m_ack[PHR_OFFSET] += m_ie_data_len; - // Add space for the FCS field. + /* Add space for the FCS field. */ m_ack[PHR_OFFSET] += FCS_SIZE; bool result = nrf_802154_frame_parser_valid_data_extend(&m_ack_data, @@ -555,7 +563,7 @@ static uint8_t * ack_process( { if (!aux_sec_hdr_process(p_frame_data)) { - // Failure to set auxiliary security header, the ACK cannot be created. Exit immediately + /* Failure to set auxiliary security header, the ACK cannot be created. Exit immediately. */ *p_processing_done = true; return NULL; } @@ -565,19 +573,20 @@ static uint8_t * ack_process( if (frame_parse_level == PARSE_LEVEL_FULL) { - // With the entire frame validated update the Frame Pending bit in Frame Control field + /* With the entire frame validated update the Frame Pending bit in Frame Control field. */ fcf_frame_pending_set(p_frame_data); if (encryption_process()) { - // Success. Processing completed + /* Success. Processing completed. */ *p_processing_done = true; return m_ack; } else { - // Failure to prepare encryption even though it's required, the ACK cannot be created. - // Exit immediately + /* Failure to prepare encryption even though it's required, the ACK cannot be created. + * Exit immediately. + */ *p_processing_done = true; return NULL; } @@ -592,24 +601,29 @@ static uint8_t * ack_process( void nrf_802154_enh_ack_generator_init(void) { - // Intentionally empty. + /* Intentionally empty. */ } void nrf_802154_enh_ack_generator_reset(void) { #if NRF_802154_IE_WRITER_ENABLED - // The IE writer module can be in the IE_WRITER_PREPARE state if - // the previous transmission failed at an early stage. - // Reset it, to avoid data corruption in case this ACK - // does not contain information elements. Otherwise, the - // IE writer would commit data in nrf_802154_ie_writer_tx_ack_started_hook - // regardless if writing of IE elements is needed or not. + + /* The IE writer module can be in the IE_WRITER_PREPARE state if + * the previous transmission failed at an early stage. + * Reset it, to avoid data corruption in case this ACK + * does not contain information elements. Otherwise, the + * IE writer would commit data in nrf_802154_ie_writer_tx_ack_started_hook + * regardless if writing of IE elements is needed or not. + */ nrf_802154_ie_writer_reset(); -#endif + +#endif /* NRF_802154_IE_WRITER_ENABLED */ #if NRF_802154_ENCRYPTION_ENABLED + nrf_802154_encrypt_ack_reset(); -#endif + +#endif /* NRF_802154_ENCRYPTION_ENABLED */ memset(m_ack, 0U, sizeof(m_ack)); (void)nrf_802154_frame_parser_data_init(m_ack, 0U, PARSE_LEVEL_NONE, &m_ack_data); diff --git a/nrf_802154/driver/src/mac_features/ack_generator/nrf_802154_enh_ack_generator.h b/nrf_802154/driver/src/mac_features/ack_generator/nrf_802154_enh_ack_generator.h index ddd136e8fb..913e924c57 100644 --- a/nrf_802154/driver/src/mac_features/ack_generator/nrf_802154_enh_ack_generator.h +++ b/nrf_802154/driver/src/mac_features/ack_generator/nrf_802154_enh_ack_generator.h @@ -45,17 +45,21 @@ #include #include -/** Initializes the Enhanced ACK generator module. */ +/** + * @brief Initialize the Enhanced ACK generator module. + */ void nrf_802154_enh_ack_generator_init(void); -/** @brief Resets the Enhanced ACK generator module. +/** + * @brief Reset the Enhanced ACK generator module. * * @note This function should be called for every received frame to be acknowledged before * @ref nrf_802154_enh_ack_generator_create is called for that frame. */ void nrf_802154_enh_ack_generator_reset(void); -/** @brief Creates an Enhanced ACK in response to the provided frame. +/** + * @brief Create an Enhanced ACK in response to the provided frame. * * @note Only those contents of the frame being acknowledged marked by @p p_frame_data as valid * are used for ACK generation. If any data necessary to generate an ACK is missing or marked as @@ -70,7 +74,6 @@ void nrf_802154_enh_ack_generator_reset(void); * of the created Enhanced ACK frame, or NULL when the response cannot be * created. */ -uint8_t * nrf_802154_enh_ack_generator_create( - const nrf_802154_frame_t * p_frame_data); +uint8_t * nrf_802154_enh_ack_generator_create(const nrf_802154_frame_t * p_frame_data); -#endif // NRF_802154_ENH_ACK_GENERATOR_H +#endif /* NRF_802154_ENH_ACK_GENERATOR_H */ diff --git a/nrf_802154/driver/src/mac_features/ack_generator/nrf_802154_imm_ack_generator.c b/nrf_802154/driver/src/mac_features/ack_generator/nrf_802154_imm_ack_generator.c index 7e112c3f2f..df1f2b12f4 100644 --- a/nrf_802154/driver/src/mac_features/ack_generator/nrf_802154_imm_ack_generator.c +++ b/nrf_802154/driver/src/mac_features/ack_generator/nrf_802154_imm_ack_generator.c @@ -61,24 +61,27 @@ void nrf_802154_imm_ack_generator_init(void) void nrf_802154_imm_ack_generator_reset(void) { - // Intentionally empty + /* Intentionally empty */ } uint8_t * nrf_802154_imm_ack_generator_create( const nrf_802154_frame_t * p_frame_data) { #if NRF_802154_IE_WRITER_ENABLED - // The IE writer module can be in the IE_WRITER_PREPARE state if - // the previous transmission failed at an early stage. - // Reset it, to avoid data corruption in when this ACK is transmitted. - // Otherwise, the IE writer would commit data in nrf_802154_ie_writer_tx_ack_started_hook - // regardless if writing of IE elements is needed or not. + + /* The IE writer module can be in the IE_WRITER_PREPARE state if + * the previous transmission failed at an early stage. + * Reset it, to avoid data corruption when this ACK is transmitted. + * Otherwise, the IE writer would commit data in nrf_802154_ie_writer_tx_ack_started_hook + * regardless of whether writing of IE elements is needed or not. + */ nrf_802154_ie_writer_reset(); - #endif + + #endif /* NRF_802154_IE_WRITER_ENABLED */ if (nrf_802154_frame_parse_level_get(p_frame_data) < PARSE_LEVEL_FULL) { - // The entire frame being acknowledged is necessary to correctly generate Ack + /* The entire frame being acknowledged is necessary to correctly generate Ack */ return NULL; } @@ -89,10 +92,10 @@ uint8_t * nrf_802154_imm_ack_generator_create( return NULL; } - // Set valid sequence number in ACK frame. + /* Set valid sequence number in ACK frame. */ m_ack_data[DSN_OFFSET] = *frame_dsn; - // Set pending bit in ACK frame. + /* Set pending bit in ACK frame. */ if (nrf_802154_ack_data_pending_bit_should_be_set(p_frame_data)) { m_ack_data[FRAME_PENDING_OFFSET] = ACK_HEADER_WITH_PENDING; diff --git a/nrf_802154/driver/src/mac_features/ack_generator/nrf_802154_imm_ack_generator.h b/nrf_802154/driver/src/mac_features/ack_generator/nrf_802154_imm_ack_generator.h index fa8b28b585..71b86cf7a8 100644 --- a/nrf_802154/driver/src/mac_features/ack_generator/nrf_802154_imm_ack_generator.h +++ b/nrf_802154/driver/src/mac_features/ack_generator/nrf_802154_imm_ack_generator.h @@ -46,17 +46,21 @@ #include "mac_features/nrf_802154_frame.h" -/** Initializes the Immediate ACK generator module. */ +/** + * @brief Initialize the Immediate ACK generator module. + */ void nrf_802154_imm_ack_generator_init(void); -/** @brief Resets the Immediate ACK generator module. +/** + * @brief Reset the Immediate ACK generator module. * * @note This function should be called for every received frame to be acknowledged before * @ref nrf_802154_imm_ack_generator_create is called for that frame. */ void nrf_802154_imm_ack_generator_reset(void); -/** @brief Creates an Immediate ACK in response to the provided frame. +/** + * @brief Create an Immediate ACK in response to the provided frame. * * @note Only those contents of the frame being acknowledged marked by @p p_frame_data as valid * are used for ACK generation. If any data necessary to generate an ACK is missing or marked as @@ -71,7 +75,6 @@ void nrf_802154_imm_ack_generator_reset(void); * of the created Immediate ACK frame, or NULL when the response cannot be * created. */ -uint8_t * nrf_802154_imm_ack_generator_create( - const nrf_802154_frame_t * p_frame_data); +uint8_t * nrf_802154_imm_ack_generator_create(const nrf_802154_frame_t * p_frame_data); -#endif // NRF_802154_IMM_ACK_GENERATOR_H +#endif /* NRF_802154_IMM_ACK_GENERATOR_H */ diff --git a/nrf_802154/driver/src/nrf_802154_core.c b/nrf_802154/driver/src/nrf_802154_core.c index 9ef246a120..e0a4b88913 100644 --- a/nrf_802154/driver/src/nrf_802154_core.c +++ b/nrf_802154/driver/src/nrf_802154_core.c @@ -91,18 +91,15 @@ #include "NRF_AES_ECB.h" #endif -/// Delay before first check of received frame: 24 bits is PHY header and MAC Frame Control field. -#define BCC_INIT (3 * 8) +#define BCC_INIT (3 * 8) /**< Delay before first check of received frame: 24 bits is PHY header and MAC Frame Control field. */ -/// Duration of single iteration of Energy Detection procedure -#define ED_ITER_DURATION 128U -/// Overhead of hardware preparation for ED procedure (aTurnaroundTime) [number of iterations] -#define ED_ITERS_OVERHEAD 2U +#define ED_ITER_DURATION 128U /**< Duration of single iteration of Energy Detection procedure. */ +#define ED_ITERS_OVERHEAD 2U /**< Overhead of hardware preparation for ED procedure (aTurnaroundTime) [number of iterations]. */ -#define MAX_CRIT_SECT_TIME 60 ///< Maximal time that the driver spends in single critical section. +#define MAX_CRIT_SECT_TIME 60U /**< Maximal time that the driver spends in single critical section. */ -#define LQI_VALUE_FACTOR ED_RSSISCALE ///< Factor needed to calculate LQI value based on data from RADIO peripheral -#define LQI_MAX 0xff ///< Maximal LQI value +#define LQI_VALUE_FACTOR ED_RSSISCALE /**< Factor needed to calculate LQI value based on data from RADIO peripheral. */ +#define LQI_MAX 0xff /**< Maximal LQI value. */ /** Get LQI of given received packet. If CRC is calculated by hardware LQI is included instead of CRC * in the frame. Length is stored in byte with index 0; CRC is 2 last bytes. @@ -114,38 +111,39 @@ */ #define PRESTARTED_TIMER_TIMEOUT_US (160U) -static rx_buffer_t * mp_current_rx_buffer; /// Pointer to currently used receive buffer. -static uint8_t * mp_ack; ///< Pointer to Ack frame buffer. -static uint32_t m_ed_time_left; ///< Remaining time of the current energy detection procedure [us]. -static int8_t m_ed_result; ///< Result of the current energy detection procedure. -static uint8_t m_last_lqi; ///< LQI of the last received non-ACK frame, corrected for the temperature. -static int8_t m_last_rssi; ///< RSSI of the last received non-ACK frame, corrected for the temperature. -static uint8_t m_no_rx_buffer_notified; ///< Set when NRF_802154_RX_ERROR_NO_BUFFER has been notified. +static rx_buffer_t * mp_current_rx_buffer; /**< Pointer to currently used receive buffer. */ +static uint8_t * mp_ack; /**< Pointer to Ack frame buffer. */ +static uint32_t m_ed_time_left; /**< Remaining time of the current energy detection procedure [us]. */ +static int8_t m_ed_result; /**< Result of the current energy detection procedure. */ +static uint8_t m_last_lqi; /**< LQI of the last received non-ACK frame, corrected for the temperature. */ +static int8_t m_last_rssi; /**< RSSI of the last received non-ACK frame, corrected for the temperature. */ +static uint8_t m_no_rx_buffer_notified; /**< Set when NRF_802154_RX_ERROR_NO_BUFFER has been notified. */ -static nrf_802154_frame_t m_current_rx_frame_data; ///< RX frame parser data. +static nrf_802154_frame_t m_current_rx_frame_data; /**< RX frame parser data. */ static nrf_802154_transmit_params_t m_tx; -static volatile radio_state_t m_state; ///< State of the radio driver. +static volatile radio_state_t m_state; /**< State of the radio driver. */ typedef struct { - bool frame_filtered : 1; ///< If frame being received passed filtering operation. - bool frame_parsed : 1; ///< If frame being received has been parsed - bool rx_timeslot_requested : 1; ///< If timeslot for the frame being received is already requested. - bool tx_with_cca : 1; ///< If currently transmitted frame is transmitted with cca. - bool tx_diminished_prio : 1; ///< If priority of the current transmission should be diminished. + bool frame_filtered : 1; /**< If frame being received passed filtering operation. */ + bool frame_parsed : 1; /**< If frame being received has been parsed. */ + bool rx_timeslot_requested : 1; /**< If timeslot for the frame being received is already requested. */ + bool tx_with_cca : 1; /**< If currently transmitted frame is transmitted with cca. */ + bool tx_diminished_prio : 1; /**< If priority of the current transmission should be diminished. */ #if defined(CONFIG_SOC_SERIES_BSIM_NRFXX) - bool tx_started_notify : 1; ///< If higher layer should be notified that transmission started. -#endif + bool tx_started_notify : 1; /**< If higher layer should be notified that transmission started. */ + +#endif /* CONFIG_SOC_SERIES_BSIM_NRFXX */ } nrf_802154_flags_t; -static nrf_802154_flags_t m_flags; ///< Flags used to store the current driver state. +static nrf_802154_flags_t m_flags; /**< Flags used to store the current driver state. */ -static volatile bool m_rsch_timeslot_is_granted; ///< State of the RSCH timeslot. -static volatile rsch_prio_t m_rsch_priority = RSCH_PRIO_IDLE; ///< Last notified RSCH priority. +static volatile bool m_rsch_timeslot_is_granted; /**< State of the RSCH timeslot. */ +static volatile rsch_prio_t m_rsch_priority = RSCH_PRIO_IDLE; /**< Last notified RSCH priority. */ /** @brief Value of argument @c notifications_mask to @ref nrf_802154_trx_receive_frame */ static nrf_802154_trx_receive_notifications_t m_trx_receive_frame_notifications_mask; @@ -175,7 +173,8 @@ static void request_preconditions_for_state(radio_state_t state) nrf_802154_rsch_crit_sect_prio_request(min_required_rsch_prio(state)); } -/** Set driver state. +/** + * @brief Set driver state. * * @param[in] state Driver state to set. */ @@ -190,7 +189,8 @@ static void state_set(radio_state_t state) request_preconditions_for_state(state); } -/** Specifies what ramp up trigger mode to use when handling RX or TX operation request. +/** + * @brief Specify the ramp up trigger mode to use when handling RX or TX operation request. * * It is assumed that the DELAYED_TRX module always requests HW mode both RX and TX, * while in all other cases SW mode is required. @@ -203,7 +203,9 @@ static nrf_802154_trx_ramp_up_trigger_mode_t ramp_up_mode_choose(req_originator_ TRX_RAMP_UP_HW_TRIGGER : TRX_RAMP_UP_SW_TRIGGER; } -/** Clear RX frame data. */ +/** + * @brief Clear RX frame data. + */ static void rx_data_clear(void) { (void)nrf_802154_frame_parser_data_init(mp_current_rx_buffer->data, @@ -215,7 +217,9 @@ static void rx_data_clear(void) mp_ack = NULL; } -/** Clear flags describing frame being received. */ +/** + * @brief Clear flags describing frame being received. + */ static void rx_flags_clear(void) { m_flags.frame_filtered = false; @@ -223,17 +227,21 @@ static void rx_flags_clear(void) m_flags.frame_parsed = false; } -/** Wait for the RSSI measurement. */ +/** + * @brief Wait for the RSSI measurement. + */ static void rssi_measurement_wait(void) { while (!nrf_802154_trx_rssi_sample_is_available()) { - // Intentionally empty: This function is called from a critical section. - // WFE would not be waken up by a RADIO event. + /* Intentionally empty: This function is called from a critical section. + * WFE would not be waken up by a RADIO event. + */ } } -/** Get the result of the last RSSI measurement. +/** + * @brief Get the result of the last RSSI measurement. * * @returns Result of the last RSSI measurement in dBm. */ @@ -242,7 +250,8 @@ static int8_t rssi_last_measurement_get(void) return nrf_802154_trx_rssi_last_sample_get(); } -/** Get LQI of a received frame. +/** + * @brief Get LQI of a received frame. * * @param[in] p_data Pointer to buffer containing PHR and PSDU of received frame * @@ -263,7 +272,8 @@ static uint8_t lqi_get(const uint8_t * p_data) return (uint8_t)lqi; } -#if (NRF_802154_FRAME_TIMESTAMP_ENABLED) +#if NRF_802154_FRAME_TIMESTAMP_ENABLED + /** * @brief Get timestamp made by timer coordinator. * @@ -288,20 +298,27 @@ static uint64_t timer_coord_timestamp_get(void) } else { - // Return timestamp without correction + /* Return timestamp without correction */ } return timestamp; } -#endif +#endif /* NRF_802154_FRAME_TIMESTAMP_ENABLED */ +/** + * @brief Notify MAC layer that a frame was received. + * + * @param[in] p_data Pointer to the received frame. + */ static void received_frame_notify(uint8_t * p_data) { nrf_802154_notify_received(p_data, m_last_rssi, m_last_lqi); } -/** Allow nesting critical sections and notify MAC layer that a frame was received. */ +/** + * @brief Allow nesting critical sections and notify MAC layer that a frame was received. + */ static void received_frame_notify_and_nesting_allow(uint8_t * p_data) { nrf_802154_critical_section_nesting_allow(); @@ -311,32 +328,44 @@ static void received_frame_notify_and_nesting_allow(uint8_t * p_data) nrf_802154_critical_section_nesting_deny(); } -/** Notify MAC layer that receive procedure failed. */ +/** + * @brief Notify MAC layer that receive procedure failed. + * + * @param[in] error Error code. + */ static void receive_failed_notify(nrf_802154_rx_error_t error) { nrf_802154_critical_section_nesting_allow(); - // Don't care about the result - if the notification cannot be performed - // no impact on the device's operation is expected + /* Don't care about the result - if the notification cannot be performed + * no impact on the device's operation is expected + */ (void)nrf_802154_notify_receive_failed(error, m_rx_window_id, true); nrf_802154_critical_section_nesting_deny(); } -/** Notify MAC layer that transmission of ACK frame has started. */ +/** + * @brief Notify MAC layer that transmission of ACK frame has started. + */ static void transmit_ack_started_notify() { #if !defined(CONFIG_SOC_SERIES_BSIM_NRFXX) + nrf_802154_core_hooks_tx_ack_started(mp_ack); -#else - /** - * Otherwise this was already called immediately after setting up the transmission. - */ -#endif + +#else /* CONFIG_SOC_SERIES_BSIM_NRFXX */ + + /* Otherwise this was already called immediately after setting up the transmission. */ + +#endif /* CONFIG_SOC_SERIES_BSIM_NRFXX */ + nrf_802154_tx_ack_started(mp_ack); } -/** Notify that reception of a frame has started. */ +/** + * @brief Notify that reception of a frame has started. + */ static void receive_started_notify(void) { nrf_802154_core_hooks_rx_started(&m_current_rx_frame_data); @@ -394,7 +423,9 @@ static void tx_client_transmitted_notify(nrf_802154_frame_t nrf_802154_log_function_exit(NRF_802154_LOG_VERBOSITY_LOW); } -/** Notify MAC layer that transmission of requested frame has started. */ +/** + * @brief Notify MAC layer that transmission of requested frame has started. + */ static void transmit_started_notify(void) { nrf_802154_log_function_enter(NRF_802154_LOG_VERBOSITY_LOW); @@ -411,7 +442,13 @@ static void transmit_started_notify(void) nrf_802154_log_function_exit(NRF_802154_LOG_VERBOSITY_LOW); } -/** Notify MAC layer that a frame was transmitted. */ +/** + * @brief Notify MAC layer that a frame was transmitted. + * + * @param[in] p_ack Pointer to the ACK frame. + * @param[in] power Power of the transmitted frame. + * @param[in] lqi LQI of the transmitted frame. + */ static void transmitted_frame_notify(uint8_t * p_ack, int8_t power, uint8_t lqi) { nrf_802154_log_function_enter(NRF_802154_LOG_VERBOSITY_LOW); @@ -432,7 +469,7 @@ static void transmitted_frame_notify(uint8_t * p_ack, int8_t power, uint8_t lqi) metadata.data.transmitted.time = nrf_802154_stat_timestamp_read_last_ack_end_timestamp(); } - // Update the transmitted frame contents and update frame status flags + /* Update the transmitted frame contents and update frame status flags */ nrf_802154_tx_work_buffer_original_frame_update(m_tx.frame.p_frame, &metadata.frame_props); @@ -447,7 +484,12 @@ static void transmitted_frame_notify(uint8_t * p_ack, int8_t power, uint8_t lqi) nrf_802154_log_function_exit(NRF_802154_LOG_VERBOSITY_LOW); } -/** Notify MAC layer that transmission procedure failed. */ +/** + * @brief Notify MAC layer that transmission procedure failed. + * + * @param[in] error Error code. + * @param[in] p_meta Pointer to the transmission done metadata. + */ static void transmit_failed_notify(nrf_802154_tx_error_t error, const nrf_802154_transmit_done_metadata_t * p_meta) { @@ -459,7 +501,12 @@ static void transmit_failed_notify(nrf_802154_tx_error_t e nrf_802154_log_function_exit(NRF_802154_LOG_VERBOSITY_LOW); } -/** Allow nesting critical sections and notify MAC layer that transmission procedure failed. */ +/** + * @brief Allow nesting critical sections and notify MAC layer that transmission procedure failed. + * + * @param[in] error Error code. + * @param[in] p_meta Pointer to the transmission done metadata. + */ static void transmit_failed_notify_and_nesting_allow( nrf_802154_tx_error_t error, const nrf_802154_transmit_done_metadata_t * p_meta) @@ -471,7 +518,11 @@ static void transmit_failed_notify_and_nesting_allow( nrf_802154_critical_section_nesting_deny(); } -/** Notify MAC layer that energy detection procedure ended. */ +/** + * @brief Notify MAC layer that energy detection procedure ended. + * + * @param[in] p_result Pointer to the energy detection result. + */ static void energy_detected_notify(const nrf_802154_energy_detected_t * p_result) { nrf_802154_critical_section_nesting_allow(); @@ -481,7 +532,11 @@ static void energy_detected_notify(const nrf_802154_energy_detected_t * p_result nrf_802154_critical_section_nesting_deny(); } -/** Notify MAC layer that CCA procedure ended. */ +/** + * @brief Notify MAC layer that CCA procedure ended. + * + * @param[in] result Result of the CCA procedure. + */ static void cca_notify(bool result) { nrf_802154_critical_section_nesting_allow(); @@ -491,7 +546,8 @@ static void cca_notify(bool result) nrf_802154_critical_section_nesting_deny(); } -/** Check if timeslot is currently granted. +/** + * @brief Check if timeslot is currently granted. * * @retval true The timeslot is granted. * @retval false The timeslot is not granted. @@ -511,7 +567,8 @@ static bool antenna_diversity_is_enabled(void) * @section RX buffer management **************************************************************************************************/ -/** Set currently used rx buffer to given address. +/** + * @brief Set currently used rx buffer to given address. * * @param[in] p_rx_buffer Pointer to receive buffer that should be used now. */ @@ -520,7 +577,8 @@ static void rx_buffer_in_use_set(rx_buffer_t * p_rx_buffer) mp_current_rx_buffer = p_rx_buffer; } -/** Check if currently there is available rx buffer. +/** + * @brief Check if currently there is available rx buffer. * * @retval true There is available rx buffer. * @retval false Currently there is no available rx buffer. @@ -530,7 +588,8 @@ static bool rx_buffer_is_available(void) return (mp_current_rx_buffer != NULL) && (mp_current_rx_buffer->free); } -/** Get pointer to available rx buffer. +/** + * @brief Get pointer to available rx buffer. * * @returns Pointer to available rx buffer or NULL if rx buffer is not available. */ @@ -543,7 +602,8 @@ static uint8_t * rx_buffer_get(void) * @section ACK transmission management **************************************************************************************************/ -/** Check if ACK is requested in the given frame to be transmitted. +/** + * @brief Check if ACK is requested in the given frame to be transmitted. * * @param[in] p_frame Pointer to a TX frame to check. * @@ -554,13 +614,13 @@ static bool tx_frame_ack_is_requested(const nrf_802154_frame_t * p_frame) { if (nrf_802154_frame_parse_level_get(p_frame) < PARSE_LEVEL_FCF_OFFSETS) { - // The frame is badly formatted. + /* The frame is badly formatted. */ return false; } if (nrf_802154_frame_type_get(p_frame) == FRAME_TYPE_MULTIPURPOSE) { - // Multipurpose frame parsing is not implemented, so assume AR is not set. + /* Multipurpose frame parsing is not implemented, so assume AR is not set. */ return false; } @@ -571,7 +631,8 @@ static bool tx_frame_ack_is_requested(const nrf_802154_frame_t * p_frame) * @section Energy detection management **************************************************************************************************/ -/** Setup next iteration of energy detection procedure. +/** + * @brief Set up the next iteration of energy detection procedure. * * Energy detection procedure is performed in iterations to make sure it is performed for requested * time regardless radio arbitration. @@ -638,9 +699,12 @@ static rsch_prio_t min_required_rsch_prio(radio_state_t state) case RADIO_STATE_TX: case RADIO_STATE_TX_ACK: #if NRF_802154_CARRIER_FUNCTIONS_ENABLED + case RADIO_STATE_CONTINUOUS_CARRIER: case RADIO_STATE_MODULATED_CARRIER: -#endif // NRF_802154_CARRIER_FUNCTIONS_ENABLED + +#endif /* NRF_802154_CARRIER_FUNCTIONS_ENABLED */ + return RSCH_PRIO_TX; case RADIO_STATE_CCA_TX: @@ -694,13 +758,16 @@ static int_fast8_t action_needed(rsch_prio_t old_prio, rsch_prio_t new_prio, rad return result; } -/** Check if time remaining in the timeslot is long enough to process whole critical section. */ +/** + * @brief Check if time remaining in the timeslot is long enough to process whole critical section. + */ static bool remaining_timeslot_time_is_enough_for_crit_sect(void) { return nrf_802154_rsch_timeslot_us_left_get() >= MAX_CRIT_SECT_TIME; } -/** Check if critical section can be processed at the moment. +/** + * @brief Check if critical section can be processed at the moment. * * @note This function returns valid result only inside critical section. * @@ -712,7 +779,9 @@ static bool critical_section_can_be_processed_now(void) return !timeslot_is_granted() || remaining_timeslot_time_is_enough_for_crit_sect(); } -/** Enter critical section and verify if there is enough time to complete operations within. */ +/** + * @brief Enter critical section and verify if there is enough time to complete operations within. + */ static bool critical_section_enter_and_verify_timeslot_length(void) { bool result = nrf_802154_critical_section_enter(); @@ -738,9 +807,11 @@ static bool can_terminate_current_operation(radio_state_t state, case RADIO_STATE_SLEEP: case RADIO_STATE_FALLING_ASLEEP: #if NRF_802154_CARRIER_FUNCTIONS_ENABLED + case RADIO_STATE_CONTINUOUS_CARRIER: case RADIO_STATE_MODULATED_CARRIER: -#endif // NRF_802154_CARRIER_FUNCTIONS_ENABLED + +#endif /* NRF_802154_CARRIER_FUNCTIONS_ENABLED */ result = true; break; @@ -770,17 +841,21 @@ static void operation_terminated_notify(radio_state_t state, bool receiving_psdu { case RADIO_STATE_SLEEP: case RADIO_STATE_FALLING_ASLEEP: + #if NRF_802154_CARRIER_FUNCTIONS_ENABLED + case RADIO_STATE_CONTINUOUS_CARRIER: case RADIO_STATE_MODULATED_CARRIER: -#endif // NRF_802154_CARRIER_FUNCTIONS_ENABLED + +#endif /* NRF_802154_CARRIER_FUNCTIONS_ENABLED */ break; case RADIO_STATE_RX: if (receiving_psdu_now) { - // Don't care about the result - if the notification cannot be performed - // no impact on the device's operation is expected + /* Don't care about the result - if the notification cannot be performed + * no impact on the device's operation is expected. + */ (void)nrf_802154_notify_receive_failed(NRF_802154_RX_ERROR_ABORTED, m_rx_window_id, true); @@ -828,7 +903,8 @@ static void operation_terminated_notify(radio_state_t state, bool receiving_psdu } } -/** Terminate ongoing operation. +/** + * @brief Terminate ongoing operation. * * This function is called when MAC layer requests transition to another operation. * @@ -871,7 +947,8 @@ static bool current_operation_terminate(nrf_802154_term_t term_lvl, if (m_state == RADIO_STATE_RX) { /* When in rx mode, nrf_802154_trx_receive_frame_prestarted handler might - * have already been called. We need to stop counting timeout. */ + * have already been called. We need to stop counting timeout. + */ m_rx_prestarted_trig_count = 0; (void)nrf_802154_sl_timer_remove(&m_rx_prestarted_timer); @@ -881,7 +958,8 @@ static bool current_operation_terminate(nrf_802154_term_t term_lvl, /* We might have boosted preconditions (to support coex) above level * normally requested for current state by request_preconditions_for_state(m_state). * When current operation is terminated we request preconditions back - * thus ceasing to request to coex. */ + * thus ceasing to request to coex. + */ request_preconditions_for_state(m_state); } @@ -901,12 +979,14 @@ static bool current_operation_terminate(nrf_802154_term_t term_lvl, return result; } -/** Initialize Falling Asleep operation. */ +/** + * @brief Initialize Falling Asleep operation. + */ static void falling_asleep_init(void) { if (nrf_802154_trx_go_idle()) { - // There will be nrf_802154_trx_in_idle call, where we will continue processing + /* There will be nrf_802154_trx_in_idle call, where we will continue processing */ } else { @@ -914,7 +994,9 @@ static void falling_asleep_init(void) } } -/**@brief Makes value to be passed to @ref nrf_802154_trx_receive_frame as @c notifications_mask parameter */ +/** + * @brief Make value to be passed to @ref nrf_802154_trx_receive_frame as @c notifications_mask parameter + */ static nrf_802154_trx_receive_notifications_t make_trx_frame_receive_notification_mask(void) { nrf_802154_trx_receive_notifications_t result = TRX_RECEIVE_NOTIFICATION_NONE; @@ -932,13 +1014,15 @@ static nrf_802154_trx_receive_notifications_t make_trx_frame_receive_notificatio { case NRF_802154_COEX_RX_REQUEST_MODE_DESTINED: /* Coex requesting handled through nrf_802154_trx_receive_frame_bcmatched handler. - * No additional notifications required. */ + * No additional notifications required. + */ break; case NRF_802154_COEX_RX_REQUEST_MODE_ENERGY_DETECTION: result |= TRX_RECEIVE_NOTIFICATION_PRESTARTED | TRX_RECEIVE_NOTIFICATION_STARTED; - // Note: TRX_RECEIVE_NOTIFICATION_STARTED is required for stopping counting timeout for - // activity triggered by nrf_802154_trx_receive_frame_prestarted. + /* Note: TRX_RECEIVE_NOTIFICATION_STARTED is required for stopping counting timeout for + * activity triggered by nrf_802154_trx_receive_frame_prestarted. + */ break; case NRF_802154_COEX_RX_REQUEST_MODE_PREAMBLE: @@ -953,10 +1037,11 @@ static nrf_802154_trx_receive_notifications_t make_trx_frame_receive_notificatio return result; } -/**@brief Makes value to be passed to @ref nrf_802154_trx_transmit_frame as @c notifications_mask parameter +/** + * @brief Make value to be passed to @ref nrf_802154_trx_transmit_frame as @c notifications_mask parameter * - * @param[in] cca Pass true, if cca operation it to be performed before transmit. - * Pass false otherwise. + * @param[in] cca Pass true, if cca operation is to be performed before transmit, + * pass false otherwise. */ static nrf_802154_trx_transmit_notifications_t make_trx_frame_transmit_notification_mask(bool cca) { @@ -1005,7 +1090,7 @@ static void rx_init_free_buffer_find_and_update(bool free_buffer) { if (!free_buffer) { - // If no buffer was available, then find a new one. + /* If no buffer was available, then find a new one. */ rx_buffer_in_use_set(nrf_802154_rx_buffer_free_find()); uint8_t * rx_buffer = rx_buffer_get(); @@ -1020,7 +1105,7 @@ static void rx_init_free_buffer_find_and_update(bool free_buffer) } /** - * @brief Initializes RX operation + * @brief Initialize RX operation. * * @param[in] ru_tr_mode Desired trigger mode for radio ramp up. * @param[out] p_abort_shall_follow It is set to `true` when initialization fails and the trx @@ -1045,11 +1130,11 @@ static void rx_init(nrf_802154_trx_ramp_up_trigger_mode_t ru_tr_mode, bool * p_a return; } - // Find available RX buffer + /* Find available RX buffer */ free_buffer = rx_buffer_is_available(); rx_init_free_buffer_find_and_update(free_buffer); - // Clear receive flags and data + /* Clear receive flags and data */ rx_flags_clear(); rx_data_clear(); @@ -1081,13 +1166,22 @@ static void rx_init(nrf_802154_trx_ramp_up_trigger_mode_t ru_tr_mode, bool * p_a } } -#if (NRF_802154_FRAME_TIMESTAMP_ENABLED) - // Configure the timer coordinator to get a timestamp of the CRCOK event. +#if NRF_802154_FRAME_TIMESTAMP_ENABLED + + /* Configure the timer coordinator to get a timestamp of the CRCOK event. */ nrf_802154_timer_coord_timestamp_prepare(nrf_802154_trx_radio_crcok_event_handle_get()); -#endif + +#endif /* NRF_802154_FRAME_TIMESTAMP_ENABLED */ } -/** Initialize TX operation. */ +/** + * @brief Initialize TX operation. + * + * @param[in] rampup_trigg_mode Trigger mode for radio ramp up. + * + * @retval true TX operation initialized successfully. + * @retval false TX operation initialization failed. + */ static bool tx_init(nrf_802154_trx_ramp_up_trigger_mode_t rampup_trigg_mode) { uint8_t cca_attempts = m_tx.cca ? (1 + m_tx.extra_cca_attempts) : 0; @@ -1113,20 +1207,23 @@ static bool tx_init(nrf_802154_trx_ramp_up_trigger_mode_t rampup_trigg_mode) return false; } -#if (NRF_802154_FRAME_TIMESTAMP_ENABLED) +#if NRF_802154_FRAME_TIMESTAMP_ENABLED + if (cca) { - // Configure the timer coordinator to get a time stamp of the READY event. - // Note: This event triggers CCASTART, so the time stamp of READY event - // is the time stamp when CCA started. + /* Configure the timer coordinator to get a time stamp of the READY event. + * Note: This event triggers CCASTART, so the time stamp of READY event + * is the time stamp when CCA started. + */ nrf_802154_timer_coord_timestamp_prepare(nrf_802154_trx_radio_ready_event_handle_get()); } else { - // Configure the timer coordinator to get a time stamp of the PHYEND event. + /* Configure the timer coordinator to get a time stamp of the PHYEND event. */ nrf_802154_timer_coord_timestamp_prepare(nrf_802154_trx_radio_phyend_event_handle_get()); } -#endif + +#endif /* NRF_802154_FRAME_TIMESTAMP_ENABLED */ nrf_802154_trx_channel_set(m_tx.channel); m_flags.tx_with_cca = cca; @@ -1135,7 +1232,9 @@ static bool tx_init(nrf_802154_trx_ramp_up_trigger_mode_t rampup_trigg_mode) cca_attempts, &m_tx.tx_power, m_trx_transmit_frame_notifications_mask); + #if defined(CONFIG_SOC_SERIES_BSIM_NRFXX) + /** * In simulation the frame contents are latched when the first bit of the preamble is * "transmitted" by the simulated radio. Any modifications performed after that (for example in @@ -1155,7 +1254,7 @@ static bool tx_init(nrf_802154_trx_ramp_up_trigger_mode_t rampup_trigg_mode) if (cca) { - // Assume that the first CCA succeeds + /* Assume that the first CCA succeeds */ adjustments.tx_started.time_to_radio_address_us += RX_RAMP_UP_TIME + CCA_TIME + RX_TX_TURNAROUND_TIME; } @@ -1175,7 +1274,8 @@ static bool tx_init(nrf_802154_trx_ramp_up_trigger_mode_t rampup_trigg_mode) nrf_802154_bsim_utils_core_hooks_adjustments_t zeroes = {0}; nrf_802154_bsim_utils_core_hooks_adjustments_set(&zeroes); -#endif + +#endif /* CONFIG_SOC_SERIES_BSIM_NRFXX */ if (rampup_trigg_mode == TRX_RAMP_UP_HW_TRIGGER) { @@ -1195,7 +1295,9 @@ static bool tx_init(nrf_802154_trx_ramp_up_trigger_mode_t rampup_trigg_mode) return true; } -/** Initialize ED operation */ +/** + * @brief Initialize ED operation. + */ static void ed_init(void) { if (!timeslot_is_granted()) @@ -1210,20 +1312,23 @@ static void ed_init(void) uint32_t trx_ed_count = 0U; - // Notify antenna diversity about energy detection request. Antenna diversity state - // will be updated, and m_ed_time_left reduced accordingly. + /* Notify antenna diversity about energy detection request. Antenna diversity state + * will be updated, and m_ed_time_left reduced accordingly. + */ nrf_802154_sl_ant_div_energy_detection_requested_notify(&m_ed_time_left); if (!ed_iter_setup(&m_ed_time_left, &trx_ed_count)) { - // Just wait for next timeslot if there is not enough time in this one. + /* Just wait for next timeslot if there is not enough time in this one. */ return; } nrf_802154_trx_energy_detection(trx_ed_count); } -/** Initialize CCA operation. */ +/** + * @brief Initialize CCA operation. + */ static void cca_init(void) { if (!timeslot_is_granted()) @@ -1246,7 +1351,9 @@ static void cca_init(void) #if NRF_802154_CARRIER_FUNCTIONS_ENABLED -/** Initialize Continuous Carrier operation. */ +/** + * @brief Initialize Continuous Carrier operation. + */ static void continuous_carrier_init(void) { if (!timeslot_is_granted()) @@ -1265,7 +1372,9 @@ static void continuous_carrier_init(void) nrf_802154_trx_continuous_carrier(&split_power); } -/** Initialize Modulated Carrier operation. */ +/** + * @brief Initialize Modulated Carrier operation. + */ static void modulated_carrier_init(const uint8_t * p_data) { if (!timeslot_is_granted()) @@ -1285,9 +1394,11 @@ static void modulated_carrier_init(const uint8_t * p_data) nrf_802154_trx_modulated_carrier(p_data, &split_power); } -#endif // NRF_802154_CARRIER_FUNCTIONS_ENABLED +#endif /* NRF_802154_CARRIER_FUNCTIONS_ENABLED */ -/** Switches to idle state: rx or sleep depending on RxOnWhenIdle mode */ +/** + * @brief Switch to idle state: rx or sleep depending on RxOnWhenIdle mode. + */ static void switch_to_idle(void) { if (!nrf_802154_pib_rx_on_when_idle_get()) @@ -1389,12 +1500,16 @@ static void on_timeslot_ended(void) case RADIO_STATE_ED: case RADIO_STATE_CCA: + #if NRF_802154_CARRIER_FUNCTIONS_ENABLED + case RADIO_STATE_CONTINUOUS_CARRIER: case RADIO_STATE_MODULATED_CARRIER: -#endif // NRF_802154_CARRIER_FUNCTIONS_ENABLED + +#endif /* NRF_802154_CARRIER_FUNCTIONS_ENABLED */ + case RADIO_STATE_SLEEP: - // Intentionally empty. + /* Intentionally empty. */ break; default: @@ -1427,7 +1542,7 @@ static void on_preconditions_denied(radio_state_t state) switch (state) { case RADIO_STATE_FALLING_ASLEEP: - // There should be on_timeslot_ended event + /* There should be on_timeslot_ended event */ break; case RADIO_STATE_RX: @@ -1453,12 +1568,16 @@ static void on_preconditions_denied(radio_state_t state) case RADIO_STATE_ED: case RADIO_STATE_CCA: + #if NRF_802154_CARRIER_FUNCTIONS_ENABLED + case RADIO_STATE_CONTINUOUS_CARRIER: case RADIO_STATE_MODULATED_CARRIER: -#endif // NRF_802154_CARRIER_FUNCTIONS_ENABLED + +#endif /* NRF_802154_CARRIER_FUNCTIONS_ENABLED */ + case RADIO_STATE_SLEEP: - // Intentionally empty. + /* Intentionally empty. */ break; default: @@ -1479,7 +1598,7 @@ static void on_preconditions_approved(radio_state_t state) switch (state) { case RADIO_STATE_SLEEP: - // Intentionally empty. Appropriate action will be performed on state change. + /* Intentionally empty. Appropriate action will be performed on state change. */ break; case RADIO_STATE_RX: @@ -1503,6 +1622,7 @@ static void on_preconditions_approved(radio_state_t state) break; #if NRF_802154_CARRIER_FUNCTIONS_ENABLED + case RADIO_STATE_CONTINUOUS_CARRIER: continuous_carrier_init(); break; @@ -1510,7 +1630,8 @@ static void on_preconditions_approved(radio_state_t state) case RADIO_STATE_MODULATED_CARRIER: modulated_carrier_init(m_tx.frame.p_frame); break; -#endif // NRF_802154_CARRIER_FUNCTIONS_ENABLED + +#endif /* NRF_802154_CARRIER_FUNCTIONS_ENABLED */ default: NRF_802154_ASSERT(false); @@ -1530,13 +1651,15 @@ static void on_timeslot_started(void) nrf_802154_timer_coord_start(); #if defined(CONFIG_SOC_SERIES_BSIM_NRFXX) + /** * In simulation no time passes while the CPU is executing code and the radio ramp-up is shorter * than the time needed by the ECB peripheral to encrypt the longest possible 802.15.4 frame. * Speed up the ECB to guarantee that encryption completes before transmission starts. */ nrf_aes_ecb_cheat_set_t_ecb(1); -#endif + +#endif /* CONFIG_SOC_SERIES_BSIM_NRFXX */ nrf_802154_log_function_exit(NRF_802154_LOG_VERBOSITY_LOW); } @@ -1544,11 +1667,12 @@ static void on_timeslot_started(void) static bool preconditions_approved_should_be_ignored(rsch_prio_t previously_approved_prio, rsch_prio_t currently_approved_prio) { - // Approved preconditions should only be ignored only all the following conditions are met: - // * all preconditions apart from Coex had already been approved; - // * the call is a result of Coex becoming approved at the highest priority; - // * currently performed operation is transmission with CCA; - // * Coex for transmission is requested after CCA reports idle channel + /* Approved preconditions should only be ignored if all the following conditions are met: + * * all preconditions apart from Coex had already been approved; + * * the call is a result of Coex becoming approved at the highest priority; + * * currently performed operation is transmission with CCA; + * * Coex for transmission is requested after CCA reports idle channel + */ bool only_coex_was_unapproved = (previously_approved_prio == RSCH_PRIO_RX); bool all_preconditions_are_approved = (currently_approved_prio == RSCH_PRIO_MAX); bool current_state_is_cca_tx = (m_state == RADIO_STATE_CCA_TX); @@ -1569,26 +1693,27 @@ void nrf_802154_rsch_crit_sect_prio_changed(rsch_prio_t prio) if ((old_prio == RSCH_PRIO_IDLE) && (prio != RSCH_PRIO_IDLE)) { - // We have just got a timeslot. + /* We have just got a timeslot. */ on_timeslot_started(); } else if ((old_prio != RSCH_PRIO_IDLE) && (prio == RSCH_PRIO_IDLE)) { - // We are giving back timeslot. + /* We are giving back timeslot. */ on_timeslot_ended(); return; } else if (prio == RSCH_PRIO_IDLE) { - // It might happen that even though IDLE has already been notified, this function is called - // again as a result of preemptions caused by unexpected timeslot change (e.g. the application - // requested transition to sleep while out of timeslot and RAAL notified timeslot start - // in the middle of that sleep request). The following block makes RAAL finish its processing. + /* It might happen that even though IDLE has already been notified, this function is called + * again as a result of preemptions caused by unexpected timeslot change (e.g. the application + * requested transition to sleep while out of timeslot and RAAL notified timeslot start + * in the middle of that sleep request). The following block makes RAAL finish its processing. + */ nrf_802154_rsch_continuous_ended(); } else { - // Intentionally empty + /* Intentionally empty */ } int_fast8_t transition = action_needed(old_prio, prio, m_state); @@ -1601,10 +1726,11 @@ void nrf_802154_rsch_crit_sect_prio_changed(rsch_prio_t prio) { on_preconditions_denied(m_state); - // After denying preconditions, TRX is disabled. However, it is possible that the existing - // preconditions are enough for the new state (entered due to denied preconditions) and TRX - // could be enabled for the new state. If this is the case, on_preconditions_approved() is - // called to fully switch to the new state. + /* After denying preconditions, TRX is disabled. However, it is possible that the existing + * preconditions are enough for the new state (entered due to denied preconditions) and TRX + * could be enabled for the new state. If this is the case, on_preconditions_approved() is + * called to fully switch to the new state. + */ radio_state_t new_state = m_state; if (is_state_allowed_for_prio(prio, new_state)) @@ -1727,14 +1853,14 @@ void nrf_802154_trx_receive_frame_prestarted(void) if (!antenna_diversity_is_enabled()) { - // Only assert if notifications mask would not allow for calling this function. + /* Only assert if notifications mask would not allow for calling this function. */ NRF_802154_ASSERT((m_trx_receive_frame_notifications_mask & TRX_RECEIVE_NOTIFICATION_PRESTARTED) != 0U); } else { - // Antenna diversity uses this function for detecting possible preamble on air. + /* Antenna diversity uses this function for detecting possible preamble on air. */ } NRF_802154_ASSERT(m_state == RADIO_STATE_RX); @@ -1745,15 +1871,15 @@ void nrf_802154_trx_receive_frame_prestarted(void) nrf_802154_sl_ant_div_rx_preamble_detected_notify(); - // Antenna diversity module should be notified if framestart doesn't come. + /* Antenna diversity module should be notified if framestart doesn't come. */ bool rx_timeout_should_be_started = antenna_diversity_is_enabled(); if (nrf_802154_pib_coex_rx_request_mode_get() == NRF_802154_COEX_RX_REQUEST_MODE_ENERGY_DETECTION) { - // Request boosted preconditions for receive + /* Request boosted preconditions for receive */ nrf_802154_rsch_crit_sect_prio_request(RSCH_PRIO_RX); - // Boosted preconditions should be reverted if the framestart doesn't come. + /* Boosted preconditions should be reverted if the framestart doesn't come. */ rx_timeout_should_be_started = true; } @@ -1795,8 +1921,10 @@ void nrf_802154_trx_receive_frame_started(void) (m_trx_receive_frame_notifications_mask & TRX_RECEIVE_NOTIFICATION_STARTED) != 0U); #if (NRF_802154_STATS_COUNT_RECEIVED_PREAMBLES) + nrf_802154_stat_counter_increment_received_preambles(); -#endif + +#endif /* NRF_802154_STATS_COUNT_RECEIVED_PREAMBLES */ switch (nrf_802154_pib_coex_rx_request_mode_get()) { @@ -1816,8 +1944,9 @@ void nrf_802154_trx_receive_frame_started(void) if (antenna_diversity_is_enabled()) { - // If antenna diversity is enabled, rx_prestarted_timer would be started even - // in different coex rx request modes than NRF_802154_COEX_RX_REQUEST_MODE_ENERGY_DETECTION + /* If antenna diversity is enabled, rx_prestarted_timer would be started even + * in different coex rx request modes than NRF_802154_COEX_RX_REQUEST_MODE_ENERGY_DETECTION + */ m_rx_prestarted_trig_count = 0; (void)nrf_802154_sl_timer_remove(&m_rx_prestarted_timer); nrf_802154_sl_ant_div_rx_frame_started_notify(); @@ -1965,16 +2094,18 @@ uint8_t nrf_802154_trx_receive_frame_bcmatched(uint8_t bcc) } else { - // Disable receiver and wait for a new timeslot. + /* Disable receiver and wait for a new timeslot. */ nrf_802154_trx_abort(); - // We should not leave trx in temporary state, let's receive then. - // We avoid hard reset of radio during TX ACK phase due to timeslot end, - // which could result in spurious RF emission. + /* We should not leave trx in temporary state, let's receive then. */ + /* We avoid hard reset of radio during TX ACK phase due to timeslot end, + * which could result in spurious RF emission. + */ rx_init(TRX_RAMP_UP_SW_TRIGGER, NULL); - // Don't care about the result - if the notification cannot be performed - // no impact on the device's operation is expected + /* Don't care about the result - if the notification cannot be performed + * no impact on the device's operation is expected + */ (void)nrf_802154_notify_receive_failed(NRF_802154_RX_ERROR_TIMESLOT_ENDED, m_rx_window_id, true); @@ -2012,7 +2143,7 @@ void nrf_802154_trx_receive_frame_crcerror(void) rx_flags_clear(); rx_data_clear(); - // We don't change receive buffer, receive will go to the same that was already used + /* We don't change receive buffer, receive will go to the same that was already used */ request_preconditions_for_state(m_state); nrf_802154_fal_tx_power_split_t split_power = {0}; @@ -2025,8 +2156,10 @@ void nrf_802154_trx_receive_frame_crcerror(void) &split_power); #if NRF_802154_NOTIFY_CRCERROR + receive_failed_notify(NRF_802154_RX_ERROR_INVALID_FCS); -#endif // NRF_802154_NOTIFY_CRCERROR + +#endif /* NRF_802154_NOTIFY_CRCERROR */ nrf_802154_log_function_exit(NRF_802154_LOG_VERBOSITY_LOW); } @@ -2049,7 +2182,7 @@ void nrf_802154_trx_receive_frame_received(void) uint8_t * p_received_data = mp_current_rx_buffer->data; nrf_802154_rx_error_t filter_result = NRF_802154_RX_ERROR_RUNTIME; - // Latch RSSI and LQI values before sending ACK + /* Latch RSSI and LQI values before sending ACK */ m_last_rssi = rssi_last_measurement_get(); m_last_lqi = lqi_get(p_received_data); @@ -2118,8 +2251,9 @@ void nrf_802154_trx_receive_frame_received(void) { if (nrf_802154_trx_transmit_ack(nrf_802154_tx_work_buffer_get(mp_ack), ACK_IFS)) { - // Intentionally empty: transmitting ack, because we can + /* Intentionally empty: transmitting ack, because we can. */ #if defined(CONFIG_SOC_SERIES_BSIM_NRFXX) + /** * In simulation the frame contents are latched when the first bit of the * preamble is "transmitted" by the simulated radio. Any modifications performed @@ -2145,7 +2279,9 @@ void nrf_802154_trx_receive_frame_received(void) nrf_802154_bsim_utils_core_hooks_adjustments_t zeroes = {0}; nrf_802154_bsim_utils_core_hooks_adjustments_set(&zeroes); -#endif /* defined(CONFIG_SOC_SERIES_BSIM_NRFXX) */ + +#endif /* CONFIG_SOC_SERIES_BSIM_NRFXX */ + } else { @@ -2174,11 +2310,11 @@ void nrf_802154_trx_receive_frame_received(void) else { request_preconditions_for_state(m_state); - // Filter out received ACK frame if promiscuous mode is disabled. + /* Filter out received ACK frame if promiscuous mode is disabled. */ if (((p_received_data[FRAME_TYPE_OFFSET] & FRAME_TYPE_MASK) != FRAME_TYPE_ACK) || nrf_802154_pib_promiscuous_get()) { - // Current buffer will be passed to the application + /* Current buffer will be passed to the application. */ mp_current_rx_buffer->free = false; switch_to_idle(); @@ -2187,16 +2323,17 @@ void nrf_802154_trx_receive_frame_received(void) } else { - // Receive to the same buffer + /* Receive to the same buffer. */ rx_init(TRX_RAMP_UP_SW_TRIGGER, NULL); } } } else { - // CRC is OK, but filtering operation did not end - it is invalid frame with valid CRC - // or problem due to software latency (i.e. handled BCMATCH, CRCERROR, CRCOK from two - // consecutively received frames). + /* CRC is OK, but filtering operation did not end - it is invalid frame with valid CRC + * or problem due to software latency (i.e. handled BCMATCH, CRCERROR, CRCOK from two + * consecutively received frames). + */ request_preconditions_for_state(m_state); rx_init(TRX_RAMP_UP_SW_TRIGGER, NULL); @@ -2279,7 +2416,7 @@ void nrf_802154_trx_transmit_ack_transmitted(void) uint8_t * p_received_data = mp_current_rx_buffer->data; - // Current buffer used for receive operation will be passed to the application + /* Current buffer used for receive operation will be passed to the application. */ mp_current_rx_buffer->free = false; switch_to_idle(); @@ -2293,17 +2430,18 @@ void nrf_802154_trx_transmit_frame_transmitted(void) { nrf_802154_log_function_enter(NRF_802154_LOG_VERBOSITY_LOW); -#if (NRF_802154_FRAME_TIMESTAMP_ENABLED) +#if NRF_802154_FRAME_TIMESTAMP_ENABLED + uint64_t ts = timer_coord_timestamp_get(); - // ts holds now timestamp of the PHYEND event + /* ts holds now timestamp of the PHYEND event. */ nrf_802154_stat_timestamp_write_last_tx_end_timestamp(ts); if (m_flags.tx_with_cca) { m_flags.tx_diminished_prio = false; - // We calculate the timestamp when ccaidle must happened. + /* We calculate the timestamp when ccaidle must happened. */ ts -= nrf_802154_frame_duration_get(m_tx.frame.p_frame[0], true, true) + RX_TX_TURNAROUND_TIME; @@ -2311,7 +2449,7 @@ void nrf_802154_trx_transmit_frame_transmitted(void) nrf_802154_stat_timestamp_write_last_cca_idle_timestamp(ts); } -#endif +#endif /* NRF_802154_FRAME_TIMESTAMP_ENABLED */ if (tx_frame_ack_is_requested(&m_tx.frame)) { @@ -2321,10 +2459,12 @@ void nrf_802154_trx_transmit_frame_transmitted(void) nrf_802154_trx_receive_buffer_set(rx_buffer_get()); -#if (NRF_802154_FRAME_TIMESTAMP_ENABLED) - // Configure the timer coordinator to get a timestamp of the CRCOK event. +#if NRF_802154_FRAME_TIMESTAMP_ENABLED + + /* Configure the timer coordinator to get a timestamp of the CRCOK event. */ nrf_802154_timer_coord_timestamp_prepare(nrf_802154_trx_radio_crcok_event_handle_get()); -#endif + +#endif /* NRF_802154_FRAME_TIMESTAMP_ENABLED */ nrf_802154_trx_receive_ack(); @@ -2343,15 +2483,15 @@ void nrf_802154_trx_transmit_frame_transmitted(void) static bool ack_match_check_version_not_2(const nrf_802154_frame_t * p_tx_frame, const nrf_802154_frame_t * p_ack_frame) { - // Frame Version != 2 + /* Frame Version != 2 */ - // Check: Phy length + /* Check: Phy length */ if (nrf_802154_frame_length_get(p_ack_frame) != IMM_ACK_LENGTH) { return false; } - // Check if Frame version is 0 or 1. + /* Check if Frame version is 0 or 1. */ switch (nrf_802154_frame_version_get(p_ack_frame)) { case FRAME_VERSION_0: @@ -2362,7 +2502,7 @@ static bool ack_match_check_version_not_2(const nrf_802154_frame_t * p_tx_frame, return false; } - // Check: Sequence number match + /* Check: Sequence number match */ if (p_ack_frame->p_frame[DSN_OFFSET] != p_tx_frame->p_frame[DSN_OFFSET]) { return false; @@ -2384,10 +2524,10 @@ static bool ack_match_check_version_2(const nrf_802154_frame_t * p_tx_frame, return false; } - // Transmitted frame was Version 2 - // For frame version 2 sequence number bit may be suppressed and its check fails. - // Verify ACK frame using its destination address. - + /* Transmitted frame was Version 2. + * For frame version 2 sequence number bit may be suppressed and its check fails. + * Verify ACK frame using its destination address. + */ const uint8_t * p_tx_src_addr = nrf_802154_frame_src_addr_get(p_tx_frame); const uint8_t * p_ack_dst_addr = nrf_802154_frame_dst_addr_get(p_ack_frame); uint8_t tx_src_addr_size = nrf_802154_frame_src_addr_size_get(p_tx_frame); @@ -2400,7 +2540,7 @@ static bool ack_match_check_version_2(const nrf_802154_frame_t * p_tx_frame, p_ack_dst_addr, tx_src_addr_size))) { - // Mismatch + /* Mismatch */ return false; } @@ -2415,13 +2555,14 @@ static bool ack_match_check(const nrf_802154_frame_t * p_tx_frame, return false; } - // Check: Frame Control Field -> Frame type + /* Check: Frame Control Field -> Frame type */ if (nrf_802154_frame_type_get(p_ack_frame) != FRAME_TYPE_ACK) { - return false; // This is not an ACK frame + /* This is not an ACK frame */ + return false; } - // Check: Frame Control Field -> Frame version + /* Check: Frame Control Field -> Frame version */ if (nrf_802154_frame_version_get(p_tx_frame) == FRAME_VERSION_2) { return ack_match_check_version_2(p_tx_frame, p_ack_frame); @@ -2434,7 +2575,7 @@ static void on_bad_ack(void) { nrf_802154_log_function_enter(NRF_802154_LOG_VERBOSITY_LOW); - // We received either a frame with incorrect CRC or not an ACK frame or not matching ACK + /* We received either a frame with incorrect CRC or not an ACK frame or not matching ACK. */ switch_to_idle(); nrf_802154_transmit_done_metadata_t metadata = {}; @@ -2449,7 +2590,7 @@ void nrf_802154_trx_receive_ack_received(void) { nrf_802154_log_function_enter(NRF_802154_LOG_VERBOSITY_LOW); - // CRC of received frame is correct + /* CRC of received frame is correct. */ uint8_t * p_ack_data = mp_current_rx_buffer->data; bool result = nrf_802154_frame_parser_data_init(p_ack_data, @@ -2469,7 +2610,7 @@ void nrf_802154_trx_receive_ack_received(void) mp_current_rx_buffer->free = false; - // Detect Frame Pending field set to one on Ack frame received after a Data Request Command + /* Detect Frame Pending field set to one on Ack frame received after a Data Request Command. */ bool should_receive = false; if (nrf_802154_frame_type_get(&m_tx.frame) == FRAME_TYPE_COMMAND) @@ -2493,9 +2634,9 @@ void nrf_802154_trx_receive_ack_received(void) switch_to_idle(); } - transmitted_frame_notify(p_ack_buffer->data, // phr + psdu - rssi_last_measurement_get(), // rssi - lqi_get(p_ack_buffer->data)); // lqi; + transmitted_frame_notify(p_ack_buffer->data, /* phr + psdu */ + rssi_last_measurement_get(), /* rssi */ + lqi_get(p_ack_buffer->data)); /* lqi */ } else { @@ -2518,8 +2659,9 @@ void nrf_802154_trx_standalone_cca_finished(bool channel_was_idle) void nrf_802154_trx_transmit_frame_ccastarted(void) { - // This handler provided by trx is never called because parameter notifications_mask - // of the nrf_802154_trx_transmit_frame does not contain TRX_TRANSMIT_NOTIFICATION_CCASTARTED. + /* This handler provided by trx is never called because parameter notifications_mask + * of the nrf_802154_trx_transmit_frame does not contain TRX_TRANSMIT_NOTIFICATION_CCASTARTED. + */ NRF_802154_ASSERT(false); } @@ -2530,15 +2672,17 @@ void nrf_802154_trx_transmit_frame_ccaidle(void) NRF_802154_ASSERT(m_state == RADIO_STATE_CCA_TX); NRF_802154_ASSERT(m_trx_transmit_frame_notifications_mask & TRX_TRANSMIT_NOTIFICATION_CCAIDLE); -#if (NRF_802154_FRAME_TIMESTAMP_ENABLED) +#if NRF_802154_FRAME_TIMESTAMP_ENABLED + uint64_t ts = timer_coord_timestamp_get(); - // Configure the timer coordinator to get a timestamp of the PHYEND event. + /* Configure the timer coordinator to get a timestamp of the PHYEND event. */ nrf_802154_timer_coord_timestamp_prepare(nrf_802154_trx_radio_phyend_event_handle_get()); - // Update stat timestamp of CCASTART event + /* Update stat timestamp of CCASTART event. */ nrf_802154_stat_timestamp_write_last_cca_start_timestamp(ts); -#endif + +#endif /* NRF_802154_FRAME_TIMESTAMP_ENABLED */ if (m_coex_tx_request_mode == NRF_802154_COEX_TX_REQUEST_MODE_CCA_DONE) { @@ -2582,7 +2726,8 @@ void nrf_802154_trx_energy_detection_finished(int8_t ed_sample_dbm) else { /* There is too little time in current timeslot, just wait for timeslot end. - * Operation will be resumed in next timeslot */ + * Operation will be resumed in next timeslot. + */ } } else if (nrf_802154_sl_ant_div_energy_detection_finished_notify()) @@ -2652,7 +2797,7 @@ static bool core_sleep(nrf_802154_term_t term_lvl, req_originator_t req_orig, bo if (result) { - // The order of calls in the following blocks is inverted to avoid RAAL races. + /* The order of calls in the following blocks is inverted to avoid RAAL races. */ if (timeslot_is_granted()) { state_set(RADIO_STATE_FALLING_ASLEEP); @@ -2741,8 +2886,9 @@ static bool core_receive(nrf_802154_term_t term_lvl, { nrf_802154_trx_abort(); - // HW triggering failed, fallback is SW trigger. - // (fallback immunizes against the rare case of spurious lptimer firing) + /* HW triggering failed, fallback is SW trigger. + * (fallback immunizes against the rare case of spurious lptimer firing) + */ rx_init(TRX_RAMP_UP_SW_TRIGGER, NULL); } } @@ -2837,7 +2983,6 @@ nrf_802154_tx_error_t nrf_802154_core_transmit(nrf_802154_term_t te state_set(p_params->cca ? RADIO_STATE_CCA_TX : RADIO_STATE_TX); m_tx = *p_params; - // coverity[check_return] result = tx_init(ramp_up_mode_choose(req_orig)); if (p_params->immediate && !result) @@ -3018,7 +3163,7 @@ bool nrf_802154_core_modulated_carrier(nrf_802154_term_t term_lvl, return result; } -#endif // NRF_802154_CARRIER_FUNCTIONS_ENABLED +#endif /* NRF_802154_CARRIER_FUNCTIONS_ENABLED */ bool nrf_802154_core_notify_buffer_free(uint8_t * p_data) { @@ -3069,6 +3214,7 @@ bool nrf_802154_core_channel_update(req_originator_t req_orig) break; #if NRF_802154_CARRIER_FUNCTIONS_ENABLED + case RADIO_STATE_CONTINUOUS_CARRIER: if (timeslot_is_granted()) { @@ -3083,9 +3229,10 @@ bool nrf_802154_core_channel_update(req_originator_t req_orig) } break; -#endif // NRF_802154_CARRIER_FUNCTIONS_ENABLED +#endif /* NRF_802154_CARRIER_FUNCTIONS_ENABLED */ + default: - // Don't perform any additional action in any other state. + /* Don't perform any additional action in any other state. */ break; } @@ -3158,7 +3305,7 @@ bool nrf_802154_core_last_rssi_measurement_get(int8_t * p_rssi) if (rssi_started && in_crit_sect && timeslot_is_granted()) { - // Checking if a timeslot is granted is valid only in a critical section + /* Checking if a timeslot is granted is valid only in a critical section */ rssi_started = nrf_802154_trx_rssi_measure_is_started(); if (rssi_started) { @@ -3213,13 +3360,14 @@ int8_t nrf_802154_sl_ant_div_rssi_measure_get(void) { int8_t result = NRF_802154_RSSI_INVALID; - // This function is supposed to be called after detecting frame prestarted event, but before - // detecting valid frame address. This means that we're currently in critical section, but the - // timeslot is not yet extended due to detecting valid frame. To avoid invalid timeslot extension - // due to blocking rssi measurements, antenna check can be aborted here if timeslot is about to end. - // Antenna switching takes 200 ns (250 ns with safety margin), while rssi measurement - 250, - // which gives total time of 750 ns. - // 750 ns is less than safety margin, so timeslot us left different than 0 is sufficient. + /* This function is supposed to be called after detecting frame prestarted event, but before + * detecting valid frame address. This means that we're currently in critical section, but the + * timeslot is not yet extended due to detecting valid frame. To avoid invalid timeslot extension + * due to blocking rssi measurements, antenna check can be aborted here if timeslot is about to end. + * Antenna switching takes 200 ns (250 ns with safety margin), while rssi measurement - 250, + * which gives total time of 750 ns. + * 750 ns is less than safety margin, so timeslot us left different than 0 is sufficient. + */ if (!nrf_802154_rsch_timeslot_us_left_get()) { return result; @@ -3231,8 +3379,9 @@ int8_t nrf_802154_sl_ant_div_rssi_measure_get(void) { while (!nrf_802154_trx_rssi_sample_is_available()) { - // Intentionally empty: This function is called from a critical section. - // WFE would not be waken up by a RADIO event. + /* Intentionally empty: This function is called from a critical section. + * WFE would not be waken up by a RADIO event. + */ } uint8_t rssi_sample = nrf_802154_trx_rssi_last_sample_get(); diff --git a/nrf_802154/driver/src/nrf_802154_core.h b/nrf_802154/driver/src/nrf_802154_core.h index 1778e3eb7a..6289279f5f 100644 --- a/nrf_802154/driver/src/nrf_802154_core.h +++ b/nrf_802154/driver/src/nrf_802154_core.h @@ -57,47 +57,49 @@ extern "C" { */ typedef enum { - // Sleep - RADIO_STATE_SLEEP, ///< Low power mode (disabled) - the only state in which all radio preconditions are not requested. - RADIO_STATE_FALLING_ASLEEP, ///< Before entering the sleep state, all radio preconditions are requested. + /* Sleep */ + RADIO_STATE_SLEEP, /**< Low power mode (disabled) - the only state in which all radio preconditions are not requested. */ + RADIO_STATE_FALLING_ASLEEP, /**< Before entering the sleep state, all radio preconditions are requested. */ - // Receive - RADIO_STATE_RX, ///< The receiver is enabled and it is receiving frames. - RADIO_STATE_TX_ACK, ///< The frame is received and the ACK is being transmitted. + /* Receive */ + RADIO_STATE_RX, /**< The receiver is enabled and it is receiving frames. */ + RADIO_STATE_TX_ACK, /**< The frame is received and the ACK is being transmitted. */ - // Transmit - RADIO_STATE_CCA_TX, ///< Performing CCA followed by the frame transmission. - RADIO_STATE_TX, ///< Transmitting data frame (or beacon). - RADIO_STATE_RX_ACK, ///< Receiving ACK after the transmitted frame. + /* Transmit */ + RADIO_STATE_CCA_TX, /**< Performing CCA followed by the frame transmission. */ + RADIO_STATE_TX, /**< Transmitting data frame (or beacon). */ + RADIO_STATE_RX_ACK, /**< Receiving ACK after the transmitted frame. */ - // Energy Detection - RADIO_STATE_ED, ///< Performing the energy detection procedure. + /* Energy Detection */ + RADIO_STATE_ED, /**< Performing the energy detection procedure. */ - // CCA - RADIO_STATE_CCA, ///< Performing the CCA procedure. + /* CCA */ + RADIO_STATE_CCA, /**< Performing the CCA procedure. */ #if NRF_802154_CARRIER_FUNCTIONS_ENABLED - // Continuous carrier - RADIO_STATE_CONTINUOUS_CARRIER, ///< Emitting the continuous carrier wave. - // Modulated carrier - RADIO_STATE_MODULATED_CARRIER ///< Emitting the modulated carrier signal. -#endif // NRF_802154_CARRIER_FUNCTIONS_ENABLED + /* Continuous carrier */ + RADIO_STATE_CONTINUOUS_CARRIER, /**< Emitting the continuous carrier wave. */ + + /* Modulated carrier */ + RADIO_STATE_MODULATED_CARRIER /**< Emitting the modulated carrier signal. */ + +#endif /* NRF_802154_CARRIER_FUNCTIONS_ENABLED */ } radio_state_t; /** - * @brief Initializes the 802.15.4 driver core. + * @brief Initialize the 802.15.4 driver core. */ void nrf_802154_core_init(void); /** - * @brief Deinitializes the 802.15.4 driver core. + * @brief Deinitialize the 802.15.4 driver core. */ void nrf_802154_core_deinit(void); /** - * @brief Gets the current state of the nRF 802.15.4 driver. + * @brief Get the current state of the nRF 802.15.4 driver. * * @returns Current state of the 802.15.4 driver. */ @@ -108,7 +110,7 @@ radio_state_t nrf_802154_core_state_get(void); **************************************************************************************************/ /** - * @brief Requests the transition to the @ref RADIO_STATE_SLEEP state. + * @brief Request the transition to the @ref RADIO_STATE_SLEEP state. * * @param[in] term_lvl Termination level of this request. Selects procedures to abort. * @@ -120,7 +122,7 @@ bool nrf_802154_core_sleep(nrf_802154_term_t term_lvl); #if NRF_802154_CSMA_CA_CANCEL_ENABLED || defined(__DOXYGEN__) /** - * @brief Requests the transition to the @ref RADIO_STATE_SLEEP state with the CSMA-CA procedure + * @brief Request the transition to the @ref RADIO_STATE_SLEEP state with the CSMA-CA procedure * cancelled. * * The function puts the driver into the sleep state and cancels the CSMA-CA backoff procedure in @@ -136,7 +138,7 @@ bool nrf_802154_core_sleep_with_cancel_csma_ca(nrf_802154_term_t term_lvl); #endif /* NRF_802154_CSMA_CA_CANCEL_ENABLED */ /** - * @brief Requests the transition to the @ref RADIO_STATE_RX state. + * @brief Request the transition to the @ref RADIO_STATE_RX state. * * @param[in] term_lvl Termination level of this request. Selects procedures to abort. * @param[in] req_orig Module that originates this request. @@ -154,7 +156,7 @@ bool nrf_802154_core_receive(nrf_802154_term_t term_lvl, uint32_t id); /** - * @brief Requests the transition to the @ref RADIO_STATE_TX state. + * @brief Request the transition to the @ref RADIO_STATE_TX state. * * @param[in] term_lvl Termination level of this request. Selects procedures to abort. * @param[in] req_orig Module that originates this request. @@ -169,7 +171,7 @@ nrf_802154_tx_error_t nrf_802154_core_transmit(nrf_802154_term_t te nrf_802154_transmit_params_t * p_params); /** - * @brief Requests end of waiting for an ACK by the core. + * @brief Request end of waiting for an ACK by the core. * * @param[in] p_param Pointer to the notification parameters; * @@ -179,7 +181,7 @@ nrf_802154_tx_error_t nrf_802154_core_transmit(nrf_802154_term_t te bool nrf_802154_core_ack_timeout_handle(const nrf_802154_ack_timeout_handle_params_t * p_param); /** - * @brief Requests the transition to the @ref RADIO_STATE_ED state. + * @brief Request the transition to the @ref RADIO_STATE_ED state. * * When the energy detection procedure is finished, the driver transitions * to the @ref RADIO_STATE_RX state. @@ -194,7 +196,7 @@ bool nrf_802154_core_ack_timeout_handle(const nrf_802154_ack_timeout_handle_para bool nrf_802154_core_energy_detection(nrf_802154_term_t term_lvl, uint32_t time_us); /** - * @brief Requests the transition to the @ref RADIO_STATE_CCA state. + * @brief Request the transition to the @ref RADIO_STATE_CCA state. * * When the CCA procedure is finished, the driver transitions to the @ref RADIO_STATE_RX state. * @@ -208,7 +210,7 @@ bool nrf_802154_core_cca(nrf_802154_term_t term_lvl); #if NRF_802154_CARRIER_FUNCTIONS_ENABLED /** - * @brief Requests the transition to the @ref RADIO_STATE_CONTINUOUS_CARRIER state. + * @brief Request the transition to the @ref RADIO_STATE_CONTINUOUS_CARRIER state. * * @param[in] term_lvl Termination level of this request. Selects procedures to abort. * @@ -219,7 +221,7 @@ bool nrf_802154_core_cca(nrf_802154_term_t term_lvl); bool nrf_802154_core_continuous_carrier(nrf_802154_term_t term_lvl); /** - * @brief Requests the transition to the @ref RADIO_STATE_MODULATED_CARRIER state. + * @brief Request the transition to the @ref RADIO_STATE_MODULATED_CARRIER state. * * @param[in] term_lvl Termination level of this request. Selects procedures to abort. * @param[in] p_data Data buffer to modulate the carrier with. @@ -231,14 +233,14 @@ bool nrf_802154_core_continuous_carrier(nrf_802154_term_t term_lvl); bool nrf_802154_core_modulated_carrier(nrf_802154_term_t term_lvl, const uint8_t * p_data); -#endif // NRF_802154_CARRIER_FUNCTIONS_ENABLED +#endif /* NRF_802154_CARRIER_FUNCTIONS_ENABLED */ /*************************************************************************************************** * @section State machine notifications **************************************************************************************************/ /** - * @brief Notifies the core module that a higher layer freed a frame buffer. + * @brief Notify the core module that a higher layer freed a frame buffer. * * When there are no free buffers available, the core does not start the receiver. * If the core receives this notification, it changes the internal state to make sure @@ -249,7 +251,7 @@ bool nrf_802154_core_modulated_carrier(nrf_802154_term_t term_lvl, bool nrf_802154_core_notify_buffer_free(uint8_t * p_data); /** - * @brief Notifies the core module that the next higher layer requested the change of the channel. + * @brief Notify the core module that the next higher layer requested the change of the channel. * * The core is expected to update the frequency register of the peripheral and, if it is * in the @c RADIO_STATE_RX, in the @c RADIO_STATE_CONTINUOUS_CARRIER @@ -261,25 +263,25 @@ bool nrf_802154_core_notify_buffer_free(uint8_t * p_data); bool nrf_802154_core_channel_update(req_originator_t req_orig); /** - * @brief Notifies the core module that the next higher layer requested the change + * @brief Notify the core module that the next higher layer requested the change * of the CCA configuration. */ bool nrf_802154_core_cca_cfg_update(void); /** - * @brief Notifies the core module that the next higher layer requested the RSSI measurement. + * @brief Notify the core module that the next higher layer requested the RSSI measurement. */ bool nrf_802154_core_rssi_measure(void); /** - * @brief Gets the last RSSI measurement. + * @brief Get the last RSSI measurement. * * @param[out] p_rssi RSSI measurement value in dBm. */ bool nrf_802154_core_last_rssi_measurement_get(int8_t * p_rssi); /** - * Get RSSI of the last received non-ACK frame. + * @brief Get RSSI of the last received non-ACK frame. * * Returns 0 if no frame was received yet. * @@ -288,7 +290,7 @@ bool nrf_802154_core_last_rssi_measurement_get(int8_t * p_rssi); int8_t nrf_802154_core_last_frame_rssi_get(void); /** - * Get LQI of the last received non-ACK frame. + * @brief Get LQI of the last received non-ACK frame. * * Returns 0 if no frame was received yet. * @@ -297,16 +299,18 @@ int8_t nrf_802154_core_last_frame_rssi_get(void); uint8_t nrf_802154_core_last_frame_lqi_get(void); /** - * @brief Notifies the core module that the next higher layer requested the change of the antenna. + * @brief Notify the core module that the next higher layer requested the change of the antenna. */ bool nrf_802154_core_antenna_update(void); #if !NRF_802154_INTERNAL_IRQ_HANDLING + /** - * @brief Notifies the core module that there is a pending IRQ to be handled. + * @brief Notify the core module that there is a pending IRQ to be handled. */ void nrf_802154_core_irq_handler(void); -#endif // !NRF_802154_INTERNAL_IRQ_HANDLING + +#endif /* !NRF_802154_INTERNAL_IRQ_HANDLING */ #ifdef __cplusplus }