mac_common.h 24 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467
  1. /**
  2. * Copyright (c) 2016 - 2020 Nordic Semiconductor ASA and Luxoft Global Operations Gmbh.
  3. *
  4. * All Rights Reserved.
  5. *
  6. * Redistribution and use in source and binary forms, with or without modification,
  7. * are permitted provided that the following conditions are met:
  8. *
  9. *
  10. * 1. Redistributions of source code must retain the above copyright notice, this
  11. * list of conditions and the following disclaimer.
  12. *
  13. * 2. Redistributions in binary form, except as embedded into a Nordic
  14. * Semiconductor ASA integrated circuit in a product or a software update for
  15. * such product, must reproduce the above copyright notice, this list of
  16. * conditions and the following disclaimer in the documentation and/or other
  17. * materials provided with the distribution.
  18. *
  19. * 3. Neither the name of Nordic Semiconductor ASA nor the names of its
  20. * contributors may be used to endorse or promote products derived from this
  21. * software without specific prior written permission.
  22. *
  23. * 4. This software, with or without modification, must only be used with a
  24. * Nordic Semiconductor ASA integrated circuit.
  25. *
  26. * 5. Any software provided in binary form under this license must not be reverse
  27. * engineered, decompiled, modified and/or disassembled.
  28. *
  29. *
  30. * THIS SOFTWARE IS PROVIDED BY NORDIC SEMICONDUCTOR ASA "AS IS" AND ANY EXPRESS
  31. * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  32. * OF MERCHANTABILITY, NONINFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE ARE
  33. * DISCLAIMED. IN NO EVENT SHALL NORDIC SEMICONDUCTOR ASA OR CONTRIBUTORS BE
  34. * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  35. * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
  36. * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  37. * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  38. * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  39. * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  40. *
  41. */
  42. #ifndef MAC_COMMON_H_INCLUDED
  43. #define MAC_COMMON_H_INCLUDED
  44. #include <stdint.h>
  45. #include "phy_common.h"
  46. #if (CONFIG_SECURE == 1)
  47. #include "mac_security.h"
  48. #endif
  49. /** @file
  50. * Types and declarations common for different MLME transactions listed here.
  51. *
  52. * @defgroup mac_common MAC Common API
  53. * @ingroup mac_15_4
  54. * @{
  55. * @brief Module for declaring MAC Common API.
  56. * @details The Common MAC module contains declarations of commonly used MAC routines and necessary
  57. * macros and types.
  58. */
  59. /**@brief Maximum interval for acknowledgement frame to arrive in microseconds.
  60. *
  61. * macAckWaitDuration = aUnitBackoffPeriod(only for beacon enabled PAN) +
  62. * aTurnaroundTime +
  63. * phySHRDuration + ceil(6 * phySymbolsPerOctet) =
  64. * 20 + 12 + 10 + 6 * 2 =
  65. * 54 symbols / 62.5 ksymbols/s = 864 us (544 us for beacon disabled PAN)
  66. */
  67. #if (CONFIG_BEACON_ENABLED == 1)
  68. #define macAckWaitDuration 864
  69. #else
  70. #define macAckWaitDuration 544
  71. #endif
  72. /**@brief The maximum number of octets added by the MAC
  73. * sublayer to the MAC payload of a beacon frame.
  74. */
  75. #define aMaxBeaconOverhead 75
  76. /**@brief The number of symbols forming the basic time period
  77. * used by the CSMA-CA algorithm.
  78. */
  79. #define aUnitBackoffPeriod 20UL
  80. /**@brief The number of symbols forming a superframe slot
  81. * when the superframe order is equal to 0.
  82. */
  83. #define aBaseSlotDuration 60UL
  84. /**@brief The number of slots contained in any superframe. */
  85. #define aNumSuperframeSlots 16UL
  86. /**@brief The number of symbols forming a superframe when
  87. * the superframe order is equal to 0.
  88. */
  89. #define aBaseSuperframeDuration (aBaseSlotDuration * aNumSuperframeSlots)
  90. /**@brief The maximum size, in octets, of a beacon payload. */
  91. #define aMaxBeaconPayloadLength (aMaxPHYPacketSize - aMaxBeaconOverhead)
  92. /**@brief The maximum number of octets added by the MAC
  93. * sublayer to the PSDU without security.
  94. */
  95. #define aMaxMPDUUnsecuredOverhead 25
  96. /**@brief The maximum number of octets that can be transmitted in the MAC Payload
  97. * field of an unsecured MAC frame that will be guaranteed not to exceed aMaxPHYPacketSize.
  98. */
  99. #define aMaxMACSafePayloadSize (aMaxPHYPacketSize - aMaxMPDUUnsecuredOverhead)
  100. /**@brief The minimum number of octets added by the MAC sublayer to the PSDU.*/
  101. #define aMinMPDUOverhead 9
  102. /**@brief The maximum number of octets that can be transmitted in the MAC
  103. * Payload field.
  104. */
  105. #define aMaxMACPayloadSize (aMaxPHYPacketSize - aMinMPDUOverhead)
  106. /**@brief The maximum size of an MPDU, in octets, that can be followed by a SIFS period. */
  107. #define aMaxSIFSFrameSize 18
  108. /**@brief The minimum number of symbols forming the CAP.
  109. *
  110. * @details This ensures that MAC commands can still be transferred to devices
  111. * when GTSs are being used.
  112. */
  113. #define aMinCAPLength 440
  114. /**@brief The number of superframes in which a GTS descriptor exists
  115. * in the beacon frame of the PAN coordinator.
  116. */
  117. #define aGTSDescPersistenceTime 4
  118. /**@brief The number of consecutive lost beacons that will cause the MAC sublayer
  119. * of a receiving device to declare a loss of synchronization.
  120. */
  121. #define aMaxLostBeacons 4
  122. /**@brief Maximum number of battery life extension periods. */
  123. #define MAC_MIN_BATT_LIFE_EXT_PERIODS 6
  124. /**@brief Minimum number of battery life extension periods. */
  125. #define MAC_MAX_BATT_LIFE_EXT_PERIODS 41
  126. /**@brief Minimum value for macBeaconOrder parameter. */
  127. #define MAC_MIN_BEACON_ORDER 0
  128. /**@brief Maximum value for macBeaconOrder parameter. */
  129. #define MAC_MAX_BEACON_ORDER 15
  130. /**@brief Minimum value for macMaxCSMABackoffs parameter. */
  131. #define MAC_MIN_MAX_CSMA_BACKOFFS 0
  132. /**@brief Maximum value for macMaxCSMABackoffs parameter. */
  133. #define MAC_MAX_MAX_CSMA_BACKOFFS 5
  134. /**@brief Minimum value for macMinBE parameter. */
  135. #define MAC_MIN_MIN_BE 0
  136. /**@brief Minimum value for macMaxBE parameter. */
  137. #define MAC_MIN_MAX_BE 3
  138. /**@brief Maximum value for macMaxBE parameter. */
  139. #define MAC_MAX_MAX_BE 8
  140. /**@brief Minimum value for macSuperframeOrder parameter. */
  141. #define MAC_MIN_SUPERFRAME_ORDER 0
  142. /**@brief Maximum value for macSuperframeOrder parameter. */
  143. #define MAC_MAX_SUPERFRAME_ORDER 15
  144. /**@brief Minimum value for macMaxFrameRetries parameter. */
  145. #define MAC_MIN_MAX_FRAME_RETRIES 0
  146. /**@brief Maximum value for macMaxFrameRetries parameter. */
  147. #define MAC_MAX_MAX_FRAME_RETRIES 7
  148. /**@brief Minimum value for macResponseWaitTime parameter. */
  149. #define MAC_MIN_RESPONSE_WAIT_TIME 2
  150. /**@brief Maximum value for macResponseWaitTime parameter. */
  151. #define MAC_MAX_RESPONSE_WAIT_TIME 64
  152. /**@brief A handy macro for a never initialized short address. */
  153. #define MAC_SHORT_ADDRESS_NOT_SET 0xFFFF
  154. /**@brief A handy macro for a never initialized short address. */
  155. #define MAC_EXTENDED_ADDRESS_NOT_SET 0xFFFFFFFFFFFFFFFFULL
  156. /**@brief A value of MAC beacon order attribute which determines
  157. * a state with no periodic beacons.
  158. */
  159. #define MAC_NO_BEACONS 15
  160. /**@brief A handy macro for broadcast address. */
  161. #define MAC_BROADCAST_SHORT_ADDRESS 0xFFFF
  162. /**@brief A handy macro for unknown PAN ID. */
  163. #define MAC_BROADCAST_PANID 0xFFFF
  164. /**@brief Short address field value that is used when the device does not
  165. * support short addressing mode.
  166. */
  167. #define MAC_EXTENDED_ADDRESS_ONLY 0xFFFE
  168. /**@brief Final CAP slot field value in the beacon for non-beacon enabled PAN. */
  169. #define MAC_FINAL_CAP_SLOT_NBPAN 15
  170. /**@brief Total amount of slots available in beacon enabled PAN. */
  171. #define MAC_SLOT_AMOUNT 16
  172. /**@brief This is the value of auto request key index until it has been set. */
  173. #define MAC_SECURITY_KEY_INDEX_NOT_SET 0xFF
  174. /**@brief Length of short MAC address in bytes. */
  175. #define MAC_ADDR_SHORT_LEN 2
  176. /**@brief Length of extended MAC address in bytes. */
  177. #define MAC_ADDR_EXTENDED_LEN 8
  178. /**@brief Length of PAN ID field in bytes. */
  179. #define MAC_PAN_ID_LEN 2
  180. /**@brief MAC footer (FCS) size. */
  181. #define MAC_MFR_SIZE 2
  182. /**@brief Maximum auxiliary header length */
  183. #if (CONFIG_SECURE == 1)
  184. #define MAC_MAX_AUX_HEADER_SIZE 14
  185. #else
  186. #define MAC_MAX_AUX_HEADER_SIZE 0
  187. #endif
  188. /**@brief Maximum MAC header length */
  189. #define MAC_MAX_MHR_SIZE (PHY_MAX_HEADER_SIZE + \
  190. 2 /* Frame control */ + \
  191. 1 /* Data sequence number */ + \
  192. 2 * (sizeof(uint16_t) + (sizeof(uint64_t))) /* Two PAN IDs and extended addresses */ + \
  193. MAC_MAX_AUX_HEADER_SIZE)
  194. /**@brief Maximum MAC header length for beacon frame */
  195. #define MAC_MAX_BCN_MHR_SIZE (PHY_MAX_HEADER_SIZE + \
  196. 2 /* Frame control field */ + \
  197. 1 /* Beacon sequence number */ + \
  198. sizeof(uint16_t) /* PAN ID */ + \
  199. sizeof(uint64_t) /* Extended address */ + \
  200. MAC_MAX_AUX_HEADER_SIZE)
  201. /**@brief Memory which should be reserved for MAC fields */
  202. #if (CONFIG_SECURE == 1)
  203. #define MAC_MEMORY_RESERVE (MAC_MAX_MHR_SIZE + MAX_MIC_SIZE + MAC_MFR_SIZE)
  204. #else
  205. #define MAC_MEMORY_RESERVE (MAC_MAX_MHR_SIZE + MAC_MFR_SIZE)
  206. #endif
  207. /**@brief Offset of MAC payload in the frame buffer */
  208. #define MAC_MAX_MSDU_OFFSET MAC_MAX_MHR_SIZE
  209. /**@brief Possible MAC frame types. */
  210. typedef enum
  211. {
  212. MAC_BEACON, /**< Frame is a beacon. */
  213. MAC_DATA, /**< Frame is a data frame. */
  214. MAC_ACK, /**< Frame is a MAC ACKnowledgement. */
  215. MAC_COMMAND /**< Frame is a MAC command. */
  216. } mac_frame_type_t;
  217. /**@brief MAC ADDRESS. */
  218. typedef union
  219. {
  220. uint16_t short_address; /**< 16-bit short address. */
  221. uint64_t long_address; /**< 64-bit long address. */
  222. } mac_addr_t;
  223. /**@brief MAC ADDR MODE. */
  224. typedef enum
  225. {
  226. MAC_ADDR_NONE = 0, /**< NO address is used. */
  227. MAC_ADDR_SHORT = 2, /**< Short address is used. */
  228. MAC_ADDR_LONG = 3 /**< Long address is used. */
  229. } mac_addr_mode_t;
  230. typedef enum
  231. {
  232. MAC_FRAME_VERSION_2003, /**< IEEE 802.15.4-2003 compliant. */
  233. MAC_FRAME_VERSION_2006 /**< IEEE 802.15.4-2006 compliant. */
  234. } mac_frame_version_t;
  235. /**
  236. * @brief MAC status
  237. *
  238. * In accordance with IEEE Std 802.15.4-2006, section 7.1.17
  239. * excluding:
  240. * MAC_IS_NOT_AVAILABLE
  241. * This status is necessary for synchronous API.
  242. */
  243. typedef enum
  244. {
  245. MAC_SUCCESS = 0x00, /* 0 */ /**< Operation is successful. */
  246. MAC_COUNTER_ERROR = 0xDB, /* 219 */ /**< The frame counter purportedly applied
  247. by the originator of the received
  248. frame is invalid. */
  249. MAC_IMPROPER_KEY_TYPE = 0xDC, /* 220 */ /**< The key purportedly applied by the
  250. originator of the received frame is
  251. not allowed to be used with that
  252. frame type according to the key usage
  253. policy of the recipient. */
  254. MAC_IMPROPER_SECURITY_LEVEL = 0xDD, /* 221 */ /**< The security level purportedly applied
  255. by the originator of the received
  256. frame does not meet the minimum
  257. security level required/expected by
  258. the recipient for that frame type. */
  259. MAC_UNSUPPORTED_LEGACY = 0xDE, /* 222 */ /**< The received frame was purportedly
  260. secured using security based on IEEE
  261. Std 802.15.4-2003, and such security
  262. is not supported by this standard. */
  263. MAC_UNSUPPORTED_SECURITY = 0xDF, /* 223 */ /**< The security purportedly applied by
  264. the originator of the received frame
  265. is not supported. */
  266. MAC_BEACON_LOSS = 0xE0, /* 224 */ /**< The beacon was lost following a
  267. synchronization request. */
  268. MAC_CHANNEL_ACCESS_FAILURE = 0xE1, /* 225 */ /**< A transmission could not take place
  269. due to activity on the channel, i.e.
  270. the CSMA-CA mechanism has failed. */
  271. MAC_DENIED = 0xE2, /* 226 */ /**< The GTS request has been denied by
  272. the PAN coordinator. */
  273. MAC_DISABLE_TRX_FAILURE = 0xE3, /* 227 */ /**< The attempt to disable the
  274. transceiver has failed. */
  275. MAC_SECURITY_ERROR = 0xE4, /* 228 */ /**< Cryptographic processing of the
  276. received secured frame failed. */
  277. MAC_FRAME_TOO_LONG = 0xE5, /* 229 */ /**< Either a frame resulting from
  278. processing has a length that is
  279. greater than aMaxPHYPacketSize or
  280. a requested transaction is too large
  281. to fit in the CAP or GTS. */
  282. MAC_INVALID_GTS = 0xE6, /* 230 */ /**< The requested GTS transmission failed
  283. because the specified GTS either did
  284. not have a transmit GTS direction or
  285. was not defined. */
  286. MAC_INVALID_HANDLE = 0xE7, /* 231 */ /**< A request to purge an MSDU from the
  287. transaction queue was made using an
  288. MSDU handle that was not found in
  289. the transaction table. */
  290. MAC_INVALID_PARAMETER = 0xE8, /* 232 */ /**< A parameter in the primitive is
  291. either not supported or is out of
  292. the valid range. */
  293. MAC_NO_ACK = 0xE9, /* 233 */ /**< No acknowledgment was received after
  294. macMaxFrameRetries. */
  295. MAC_NO_BEACON = 0xEA, /* 234 */ /**< A scan operation failed to find any
  296. network beacons. */
  297. MAC_NO_DATA = 0xEB, /* 235 */ /**< No response data was available
  298. following a request. */
  299. MAC_NO_SHORT_ADDRESS = 0xEC, /* 236 */ /**< The operation failed because a 16-bit
  300. short address was not allocated. */
  301. MAC_OUT_OF_CAP = 0xED, /* 237 */ /**< A receiver enable request was
  302. unsuccessful because it could not be
  303. completed within the CAP.
  304. @note The enumeration description is
  305. not used in this standard, and it is
  306. included only to meet the backwards
  307. compatibility requirements for
  308. IEEE Std 802.15.4-2003. */
  309. MAC_PAN_ID_CONFLICT = 0xEE, /* 238 */ /**< A PAN identifier conflict has been
  310. detected and communicated to the PAN
  311. coordinator. */
  312. MAC_REALIGNMENT = 0xEF, /* 239 */ /**< A coordinator realignment command has
  313. been received. */
  314. MAC_TRANSACTION_EXPIRED = 0xF0, /* 240 */ /**< The transaction has expired and its
  315. information was discarded. */
  316. MAC_TRANSACTION_OVERFLOW = 0xF1, /* 241 */ /**< There is no capacity to store the
  317. transaction. */
  318. MAC_TX_ACTIVE = 0xF2, /* 242 */ /**< The transceiver was in the transmitter
  319. enabled state when the receiver was
  320. requested to be enabled.
  321. @note The enumeration description is
  322. not used in this standard, and it is
  323. included only to meet the backwards
  324. compatibility requirements for
  325. IEEE Std 802.15.4-2003. */
  326. MAC_UNAVAILABLE_KEY = 0xF3, /* 243 */ /**< The key purportedly used by the
  327. originator of the received frame is
  328. not available or, if available, the
  329. originating device is not known or is
  330. blacklisted with that particular
  331. key. */
  332. MAC_UNSUPPORTED_ATTRIBUTE = 0xF4, /* 244 */ /**< A SET/GET request was issued with the
  333. identifier of a PIB attribute that is
  334. not supported. */
  335. MAC_INVALID_ADDRESS = 0xF5, /* 245 */ /**< A request to send data was
  336. unsuccessful because neither the source
  337. address parameters nor the destination
  338. address parameters were present. */
  339. MAC_ON_TIME_TOO_LONG = 0xF6, /* 246 */ /**< A receiver enable request was
  340. unsuccessful because it specified a
  341. number of symbols that was longer than
  342. the beacon interval. */
  343. MAC_PAST_TIME = 0xF7, /* 247 */ /**< A receiver enable request was
  344. unsuccessful because it could not be
  345. completed within the current superframe
  346. and was not permitted to be deferred
  347. until the next superframe. */
  348. MAC_TRACKING_OFF = 0xF8, /* 248 */ /**< The device was instructed to start
  349. sending beacons based on the timing
  350. of the beacon transmissions of its
  351. coordinator, but the device is not
  352. currently tracking the beacon of its
  353. coordinator. */
  354. MAC_INVALID_INDEX = 0xF9, /* 249 */ /**< An attempt to write to a MAC PIB
  355. attribute that is in a table failed
  356. because the specified table index
  357. was out of range. */
  358. MAC_LIMIT_REACHED = 0xFA, /* 250 */ /**< A scan operation terminated
  359. prematurely because the number of
  360. PAN descriptors stored reached an
  361. implementation specified maximum. */
  362. MAC_READ_ONLY = 0xFB, /* 251 */ /**< A SET/GET request was issued with the
  363. identifier of an attribute that is
  364. read only. */
  365. MAC_SCAN_IN_PROGRESS = 0xFC, /* 252 */ /**< A request to perform a scan operation
  366. failed because the MLME was in the
  367. process of performing a previously
  368. initiated scan operation. */
  369. MAC_SUPERFRAME_OVERLAP = 0xFD, /* 253 */ /**< The device was instructed to start
  370. sending beacons based on the timing
  371. of the beacon transmissions of its
  372. coordinator, but the instructed start
  373. time overlapped the transmission time
  374. of the beacon of its coordinator. */
  375. /* Statuses out from standard. It is used for synchronous API */
  376. MAC_IS_NOT_AVAILABLE = 0xFF /* 255 */ /**< MAC is not available. */
  377. } mac_status_t;
  378. /**
  379. * @brief Payload descriptor.
  380. *
  381. * @details Not covered by the standard.
  382. * Contains information sufficient to allow the next higher layer to clean
  383. * the memory allocated for incoming frames.
  384. */
  385. typedef struct
  386. {
  387. /**
  388. * Pointer to the set of octets forming the frame payload being indicated by
  389. * the MAC sublayer entity.
  390. */
  391. uint8_t * p_payload;
  392. /**
  393. * Offset of the payload data relative to the beginning of the frame.
  394. * Equal to the MAC header.
  395. */
  396. uint8_t payload_offset;
  397. } mac_payload_descriptor_t;
  398. /** @brief Command frame IDs defined by the MAC sublayer that are listed
  399. * in Table 82 of the standard.
  400. */
  401. typedef enum
  402. {
  403. MAC_CMD_ASSOC_REQ = 0x01, /**< Association request.*/
  404. MAC_CMD_ASSOC_RESP = 0x02, /**< Association response.*/
  405. MAC_CMD_DISASSOC_NTF = 0x03, /**< Disassociation notification.*/
  406. MAC_CMD_DATA_REQ = 0x04, /**< Data request.*/
  407. MAC_CMD_PANID_CONFLICT_NTF = 0x05, /**< PAN ID conflict notification.*/
  408. MAC_CMD_ORPHAN_NTF = 0x06, /**< Orphan notification.*/
  409. MAC_CMD_BEACON_REQ = 0x07, /**< Beacon request.*/
  410. MAC_CMD_COORD_REALIGN = 0x08, /**< Coordinator realignment.*/
  411. MAC_CMD_GTS_REQ = 0x09 /**< GTS request.*/
  412. } mac_command_id_t;
  413. /** @} */
  414. #endif // MAC_COMMON_H_INCLUDED