Line data Source code
1 1 : /*
2 : * Copyright (c) 2016 Intel Corporation.
3 : * Copyright (c) 2022 Florian Grandel.
4 : *
5 : * SPDX-License-Identifier: Apache-2.0
6 : */
7 :
8 : /**
9 : * @file
10 : * @brief Packet data common to all IEEE 802.15.4 L2 layers
11 : *
12 : * All references to the spec refer to IEEE 802.15.4-2020.
13 : */
14 :
15 : #ifndef ZEPHYR_INCLUDE_NET_IEEE802154_PKT_H_
16 : #define ZEPHYR_INCLUDE_NET_IEEE802154_PKT_H_
17 :
18 : #include <string.h>
19 :
20 : #include <zephyr/types.h>
21 :
22 : #ifdef __cplusplus
23 : extern "C" {
24 : #endif
25 :
26 : /** @cond ignore */
27 :
28 : #ifndef NET_PKT_HAS_CONTROL_BLOCK
29 : #define NET_PKT_HAS_CONTROL_BLOCK
30 : #endif
31 :
32 : /* See section 6.16.2.8 - Received Signal Strength Indicator (RSSI) */
33 : #define IEEE802154_MAC_RSSI_MIN 0U /* corresponds to -174 dBm */
34 : #define IEEE802154_MAC_RSSI_MAX 254U /* corresponds to 80 dBm */
35 : #define IEEE802154_MAC_RSSI_UNDEFINED 255U /* used by us to indicate an undefined RSSI value */
36 :
37 : #define IEEE802154_MAC_RSSI_DBM_MIN -174 /* in dBm */
38 : #define IEEE802154_MAC_RSSI_DBM_MAX 80 /* in dBm */
39 : #define IEEE802154_MAC_RSSI_DBM_UNDEFINED INT16_MIN /* represents an undefined RSSI value */
40 :
41 : struct net_pkt_cb_ieee802154 {
42 : #if defined(CONFIG_NET_L2_OPENTHREAD)
43 : uint32_t ack_fc; /* Frame counter set in the ACK */
44 : uint8_t ack_keyid; /* Key index set in the ACK */
45 : #endif
46 : union {
47 : /* RX packets */
48 : struct {
49 : uint8_t lqi; /* Link Quality Indicator */
50 : /* See section 6.16.2.8 - Received Signal Strength Indicator (RSSI)
51 : * "RSSI is represented as one octet of integer [...]; therefore,
52 : * the minimum and maximum values are 0 (–174 dBm) and 254 (80 dBm),
53 : * respectively. 255 is reserved." (MAC PIB attribute macRssi, see
54 : * section 8.4.3.10, table 8-108)
55 : *
56 : * TX packets will show zero for this value. Drivers may set the
57 : * field to the reserved value 255 (0xff) to indicate that an RSSI
58 : * value is not available for this packet.
59 : */
60 : uint8_t rssi;
61 : };
62 : struct {
63 : #if defined(CONFIG_IEEE802154_SELECTIVE_TXCHANNEL)
64 : /* The channel used for timed transmissions.
65 : *
66 : * Please refer to `ieee802154_radio_api::tx` documentation for
67 : * details.
68 : */
69 : uint8_t txchannel;
70 : #endif /* CONFIG_IEEE802154_SELECTIVE_TXCHANNEL */
71 : };
72 : };
73 :
74 : /* Flags */
75 : uint8_t ack_fpb : 1; /* Frame Pending Bit was set in the ACK */
76 : uint8_t frame_secured : 1; /* Frame is authenticated and
77 : * encrypted according to its
78 : * Auxiliary Security Header
79 : */
80 : uint8_t mac_hdr_rdy : 1; /* Indicates if frame's MAC header
81 : * is ready to be transmitted or if
82 : * it requires further modifications,
83 : * e.g. Frame Counter injection.
84 : */
85 : #if defined(CONFIG_NET_L2_OPENTHREAD)
86 : uint8_t ack_seb : 1; /* Security Enabled Bit was set in the ACK */
87 : #endif
88 : };
89 :
90 : struct net_pkt;
91 : static inline void *net_pkt_cb(struct net_pkt *pkt);
92 :
93 : static inline struct net_pkt_cb_ieee802154 *net_pkt_cb_ieee802154(struct net_pkt *pkt)
94 : {
95 : return (struct net_pkt_cb_ieee802154 *)net_pkt_cb(pkt);
96 : };
97 :
98 : static inline uint8_t net_pkt_ieee802154_lqi(struct net_pkt *pkt)
99 : {
100 : return net_pkt_cb_ieee802154(pkt)->lqi;
101 : }
102 :
103 : static inline void net_pkt_set_ieee802154_lqi(struct net_pkt *pkt, uint8_t lqi)
104 : {
105 : net_pkt_cb_ieee802154(pkt)->lqi = lqi;
106 : }
107 :
108 : /**
109 : * @brief Get the unsigned RSSI value as defined in section 6.16.2.8,
110 : * Received Signal Strength Indicator (RSSI)
111 : *
112 : * @param pkt Pointer to the packet.
113 : *
114 : * @returns RSSI represented as unsigned byte value, ranging from
115 : * 0 (–174 dBm) to 254 (80 dBm).
116 : * The special value 255 (IEEE802154_MAC_RSSI_UNDEFINED)
117 : * indicates that an RSSI value is not available for this
118 : * packet. Will return zero for packets on the TX path.
119 : */
120 : static inline uint8_t net_pkt_ieee802154_rssi(struct net_pkt *pkt)
121 : {
122 : return net_pkt_cb_ieee802154(pkt)->rssi;
123 : }
124 :
125 : /**
126 : * @brief Set the unsigned RSSI value as defined in section 6.16.2.8,
127 : * Received Signal Strength Indicator (RSSI).
128 : *
129 : * @param pkt Pointer to the packet that was received with the given
130 : * RSSI.
131 : * @param rssi RSSI represented as unsigned byte value, ranging from
132 : * 0 (–174 dBm) to 254 (80 dBm).
133 : * The special value 255 (IEEE802154_MAC_RSSI_UNDEFINED)
134 : * indicates that an RSSI value is not available for this
135 : * packet.
136 : */
137 : static inline void net_pkt_set_ieee802154_rssi(struct net_pkt *pkt, uint8_t rssi)
138 : {
139 : net_pkt_cb_ieee802154(pkt)->rssi = rssi;
140 : }
141 :
142 : /**
143 : * @brief Get a signed RSSI value measured in dBm.
144 : *
145 : * @param pkt Pointer to the packet.
146 : *
147 : * @returns RSSI represented in dBm. Returns the special value
148 : * IEEE802154_MAC_RSSI_DBM_UNDEFINED if an RSSI value
149 : * is not available for this packet. Packets on the TX
150 : * path will always show -174 dBm (which corresponds to
151 : * an internal value of unsigned zero).
152 : */
153 : static inline int16_t net_pkt_ieee802154_rssi_dbm(struct net_pkt *pkt)
154 : {
155 : int16_t rssi = net_pkt_cb_ieee802154(pkt)->rssi;
156 : return rssi == IEEE802154_MAC_RSSI_UNDEFINED ? IEEE802154_MAC_RSSI_DBM_UNDEFINED
157 : : rssi + IEEE802154_MAC_RSSI_DBM_MIN;
158 : }
159 :
160 : /**
161 : * @brief Set the RSSI value as a signed integer measured in dBm.
162 : *
163 : * @param pkt Pointer to the packet that was received with the given
164 : * RSSI.
165 : * @param rssi represented in dBm. Set to the special value
166 : * IEEE802154_MAC_RSSI_DBM_UNDEFINED if an RSSI value is
167 : * not available for this packet. Values above 80 dBm will
168 : * be mapped to 80 dBm, values below -174 dBm will be mapped
169 : * to -174 dBm.
170 : */
171 : static inline void net_pkt_set_ieee802154_rssi_dbm(struct net_pkt *pkt, int16_t rssi)
172 : {
173 : if (likely(rssi >= IEEE802154_MAC_RSSI_DBM_MIN && rssi <= IEEE802154_MAC_RSSI_DBM_MAX)) {
174 : int16_t unsigned_rssi = rssi - IEEE802154_MAC_RSSI_DBM_MIN;
175 :
176 : net_pkt_cb_ieee802154(pkt)->rssi = unsigned_rssi;
177 : return;
178 : } else if (rssi == IEEE802154_MAC_RSSI_DBM_UNDEFINED) {
179 : net_pkt_cb_ieee802154(pkt)->rssi = IEEE802154_MAC_RSSI_UNDEFINED;
180 : return;
181 : } else if (rssi < IEEE802154_MAC_RSSI_DBM_MIN) {
182 : net_pkt_cb_ieee802154(pkt)->rssi = IEEE802154_MAC_RSSI_MIN;
183 : return;
184 : } else if (rssi > IEEE802154_MAC_RSSI_DBM_MAX) {
185 : net_pkt_cb_ieee802154(pkt)->rssi = IEEE802154_MAC_RSSI_MAX;
186 : return;
187 : }
188 :
189 : CODE_UNREACHABLE;
190 : }
191 :
192 : #if defined(CONFIG_IEEE802154_SELECTIVE_TXCHANNEL)
193 : static inline uint8_t net_pkt_ieee802154_txchannel(struct net_pkt *pkt)
194 : {
195 : return net_pkt_cb_ieee802154(pkt)->txchannel;
196 : }
197 :
198 : static inline void net_pkt_set_ieee802154_txchannel(struct net_pkt *pkt, uint8_t channel)
199 : {
200 : net_pkt_cb_ieee802154(pkt)->txchannel = channel;
201 : }
202 : #endif /* CONFIG_IEEE802154_SELECTIVE_TXCHANNEL */
203 :
204 : static inline bool net_pkt_ieee802154_ack_fpb(struct net_pkt *pkt)
205 : {
206 : return net_pkt_cb_ieee802154(pkt)->ack_fpb;
207 : }
208 :
209 : static inline void net_pkt_set_ieee802154_ack_fpb(struct net_pkt *pkt, bool fpb)
210 : {
211 : net_pkt_cb_ieee802154(pkt)->ack_fpb = fpb;
212 : }
213 :
214 : static inline bool net_pkt_ieee802154_frame_secured(struct net_pkt *pkt)
215 : {
216 : return net_pkt_cb_ieee802154(pkt)->frame_secured;
217 : }
218 :
219 : static inline void net_pkt_set_ieee802154_frame_secured(struct net_pkt *pkt, bool secured)
220 : {
221 : net_pkt_cb_ieee802154(pkt)->frame_secured = secured;
222 : }
223 :
224 : static inline bool net_pkt_ieee802154_mac_hdr_rdy(struct net_pkt *pkt)
225 : {
226 : return net_pkt_cb_ieee802154(pkt)->mac_hdr_rdy;
227 : }
228 :
229 : static inline void net_pkt_set_ieee802154_mac_hdr_rdy(struct net_pkt *pkt, bool rdy)
230 : {
231 : net_pkt_cb_ieee802154(pkt)->mac_hdr_rdy = rdy;
232 : }
233 :
234 : #if defined(CONFIG_NET_L2_OPENTHREAD)
235 : static inline uint32_t net_pkt_ieee802154_ack_fc(struct net_pkt *pkt)
236 : {
237 : return net_pkt_cb_ieee802154(pkt)->ack_fc;
238 : }
239 :
240 : static inline void net_pkt_set_ieee802154_ack_fc(struct net_pkt *pkt, uint32_t fc)
241 : {
242 : net_pkt_cb_ieee802154(pkt)->ack_fc = fc;
243 : }
244 :
245 : static inline uint8_t net_pkt_ieee802154_ack_keyid(struct net_pkt *pkt)
246 : {
247 : return net_pkt_cb_ieee802154(pkt)->ack_keyid;
248 : }
249 :
250 : static inline void net_pkt_set_ieee802154_ack_keyid(struct net_pkt *pkt, uint8_t keyid)
251 : {
252 : net_pkt_cb_ieee802154(pkt)->ack_keyid = keyid;
253 : }
254 :
255 : static inline bool net_pkt_ieee802154_ack_seb(struct net_pkt *pkt)
256 : {
257 : return net_pkt_cb_ieee802154(pkt)->ack_seb;
258 : }
259 :
260 : static inline void net_pkt_set_ieee802154_ack_seb(struct net_pkt *pkt, bool seb)
261 : {
262 : net_pkt_cb_ieee802154(pkt)->ack_seb = seb;
263 : }
264 : #endif /* CONFIG_NET_L2_OPENTHREAD */
265 :
266 : /** @endcond */
267 :
268 : #ifdef __cplusplus
269 : }
270 : #endif
271 :
272 : #endif /* ZEPHYR_INCLUDE_NET_IEEE802154_PKT_H_ */
|
