Commit 631f117e authored by Florian Grandel's avatar Florian Grandel Committed by Carles Cufi
Browse files

drivers: ieee802154: document endianness 



The IEEE 802.15.4 radio driver encodes attributes in:

* little endian for everything that is close to the protocol as
  IEEE 802.15.4 frames are little endian encoded.

* mixed big and little endian in its configuration where extended
  addresses are being represented. These inconsistencies are unfortunate
  but cannot be easily fixed in a backwards compatible way so will be
  left untouched in this change.

Endianness was almost nowhere documented which explains these
inconsistencies and led to several bugs where assignments of different
byte order are not converted (or sometimes converted, sometimes not).

This change documents intended endianness within the realm of the
IEEE 802.15.4 radio driver code. Conversion bugs are fixed in a separate
commit.

Signed-off-by: default avatarFlorian Grandel <jerico.dev@gmail.com>
parent 7ea6cc99

drivers/ieee802154/ieee802154_nrf5.c

+3 −2
Original line number Diff line number Diff line
@@ -940,9 +940,10 @@ static int nrf5_configure(const struct device *dev, 
		sys_put_le16(config->ack_ie.short_addr, short_addr_le);

		/**

		 * The extended address field passed to this function starts

		 * with the leftmost octet and ends with the rightmost octet.

		 * with the most significant octet and ends with the least

		 * significant octet (i.e. big endian byte order).

		 * The IEEE 802.15.4 transmission order mandates this order to be

		 * reversed in a transmitted frame.

		 * reversed (i.e. little endian byte order) in a transmitted frame.

		 *

		 * The nrf_802154_ack_data_set expects extended address in transmission

		 * order.

include/zephyr/net/ieee802154_radio.h

+20 −14
Original line number Diff line number Diff line
@@ -90,9 +90,9 @@ typedef void (*ieee802154_event_cb_t)(const struct device *dev, 
struct ieee802154_filter {

/** @cond ignore */

	union {

		uint8_t *ieee_addr;

		uint16_t short_addr;

		uint16_t pan_id;

		uint8_t *ieee_addr; /* in little endian */

		uint16_t short_addr; /* in CPU byte order */

		uint16_t pan_id; /* in CPU byte order */

	};

/* @endcond */

};
@@ -233,7 +233,7 @@ struct ieee802154_config { 


		/** ``IEEE802154_CONFIG_ACK_FPB`` */

		struct {

			uint8_t *addr;

			uint8_t *addr; /* in little endian for both, short and extended address */

			bool extended;

			bool enabled;

		} ack_fpb;
@@ -271,24 +271,30 @@ struct ieee802154_config { 
		} rx_slot;



		/** ``IEEE802154_CONFIG_CSL_PERIOD`` */

		uint32_t csl_period;

		uint32_t csl_period; /* in CPU byte order */



		/** ``IEEE802154_CONFIG_CSL_RX_TIME`` */

		uint32_t csl_rx_time;

		uint32_t csl_rx_time; /* in microseconds,

				       * based on ieee802154_radio_api.get_time()

				       */



		/** ``IEEE802154_CONFIG_ENH_ACK_HEADER_IE`` */

		struct {

			const uint8_t *data;

			const uint8_t *data; /* header IEs to be added to the Enh-Ack frame in

					      * little endian byte order

					      */

			uint16_t data_len;

			uint16_t short_addr;

			uint16_t short_addr; /* in CPU byte order */

			/**

			 * The extended address is expected to be passed starting

			 * with the leftmost octet and ending with the rightmost octet.

			 * with the most significant octet and ending with the

			 * least significant octet.

			 * A device with an extended address 01:23:45:67:89:ab:cd:ef

			 * should provide a pointer to array containing values in the

			 * same exact order.

			 * as written in the usual big-endian hex notation should

			 * provide a pointer to an array containing values in the

			 * exact same order.

			 */

			const uint8_t *ext_addr;

			const uint8_t *ext_addr; /* in big endian */

		} ack_ie;

	};

};
@@ -312,7 +318,7 @@ struct ieee802154_radio_api { 
	/** Clear Channel Assessment - Check channel's activity */

	int (*cca)(const struct device *dev);



	/** Set current channel */

	/** Set current channel, channel is in CPU byte order. */

	int (*set_channel)(const struct device *dev, uint16_t channel);



	/** Set/Unset filters (for IEEE802154_HW_FILTER ) */

CRA Git | Maintained and supported by SUSTech CRA and CCSE