ZMAC.h 16 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657
  1. /**************************************************************************************************
  2. Filename: ZMAC.h
  3. Revised: $Date: 2011-02-28 17:30:28 -0800 (Mon, 28 Feb 2011) $
  4. Revision: $Revision: 25231 $
  5. Description: This file contains the ZStack MAC Porting Layer.
  6. Copyright 2004-2011 Texas Instruments Incorporated. All rights reserved.
  7. IMPORTANT: Your use of this Software is limited to those specific rights
  8. granted under the terms of a software license agreement between the user
  9. who downloaded the software, his/her employer (which must be your employer)
  10. and Texas Instruments Incorporated (the "License"). You may not use this
  11. Software unless you agree to abide by the terms of the License. The License
  12. limits your use, and you acknowledge, that the Software may not be modified,
  13. copied or distributed unless embedded on a Texas Instruments microcontroller
  14. or used solely and exclusively in conjunction with a Texas Instruments radio
  15. frequency transceiver, which is integrated into your product. Other than for
  16. the foregoing purpose, you may not use, reproduce, copy, prepare derivative
  17. works of, modify, distribute, perform, display or sell this Software and/or
  18. its documentation for any purpose.
  19. YOU FURTHER ACKNOWLEDGE AND AGREE THAT THE SOFTWARE AND DOCUMENTATION ARE
  20. PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED,
  21. INCLUDING WITHOUT LIMITATION, ANY WARRANTY OF MERCHANTABILITY, TITLE,
  22. NON-INFRINGEMENT AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL
  23. TEXAS INSTRUMENTS OR ITS LICENSORS BE LIABLE OR OBLIGATED UNDER CONTRACT,
  24. NEGLIGENCE, STRICT LIABILITY, CONTRIBUTION, BREACH OF WARRANTY, OR OTHER
  25. LEGAL EQUITABLE THEORY ANY DIRECT OR INDIRECT DAMAGES OR EXPENSES
  26. INCLUDING BUT NOT LIMITED TO ANY INCIDENTAL, SPECIAL, INDIRECT, PUNITIVE
  27. OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, COST OF PROCUREMENT
  28. OF SUBSTITUTE GOODS, TECHNOLOGY, SERVICES, OR ANY CLAIMS BY THIRD PARTIES
  29. (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), OR OTHER SIMILAR COSTS.
  30. Should you have any questions regarding your right to use this Software,
  31. contact Texas Instruments Incorporated at www.TI.com.
  32. **************************************************************************************************/
  33. #ifndef ZMAC_H
  34. #define ZMAC_H
  35. #ifdef __cplusplus
  36. extern "C"
  37. {
  38. #endif
  39. /*********************************************************************
  40. * INCLUDES
  41. */
  42. #include "ZComDef.h"
  43. #include "zmac_internal.h"
  44. /*********************************************************************
  45. * MACROS
  46. */
  47. /* Maximum length of the beacon payload */
  48. #ifndef ZMAC_MAX_BEACON_PAYLOAD_LEN
  49. #define ZMAC_MAX_BEACON_PAYLOAD_LEN (7 + Z_EXTADDR_LEN)
  50. #endif
  51. /*********************************************************************
  52. * CONSTANTS
  53. */
  54. #if defined( MAC_API_H )
  55. #define ZMAC_CHAN_MASK ( \
  56. MAC_CHAN_11_MASK | \
  57. MAC_CHAN_12_MASK | \
  58. MAC_CHAN_13_MASK | \
  59. MAC_CHAN_14_MASK | \
  60. MAC_CHAN_15_MASK | \
  61. MAC_CHAN_16_MASK | \
  62. MAC_CHAN_17_MASK | \
  63. MAC_CHAN_18_MASK | \
  64. MAC_CHAN_19_MASK | \
  65. MAC_CHAN_20_MASK | \
  66. MAC_CHAN_21_MASK | \
  67. MAC_CHAN_22_MASK | \
  68. MAC_CHAN_23_MASK | \
  69. MAC_CHAN_24_MASK | \
  70. MAC_CHAN_25_MASK | \
  71. MAC_CHAN_26_MASK | \
  72. MAC_CHAN_27_MASK | \
  73. MAC_CHAN_28_MASK )
  74. #else
  75. #define ZMAC_CHAN_MASK 0x07FFF800
  76. #endif
  77. /* LQI adjustment parameters */
  78. #if !defined( LQI_CORR_MIN )
  79. #define LQI_CORR_MIN 50 /* Theoretical CORR lower limt */
  80. #endif
  81. #if !defined( LQI_CORR_MAX )
  82. #define LQI_CORR_MAX 110 /* Theoretical CORR upper limt */
  83. #endif
  84. /*********************************************************************
  85. * TYPEDEFS
  86. */
  87. /* ZMAC event header type */
  88. typedef struct
  89. {
  90. uint8 Event; /* ZMAC event */
  91. uint8 Status; /* ZMAC status */
  92. } ZMacEventHdr_t;
  93. /* Common security type */
  94. typedef struct
  95. {
  96. uint8 KeySource[ZMAC_KEY_SOURCE_MAX_LEN];
  97. uint8 SecurityLevel;
  98. uint8 KeyIdMode;
  99. uint8 KeyIndex;
  100. }ZMacSec_t;
  101. /* PAN descriptor type */
  102. typedef struct
  103. {
  104. zAddrType_t CoordAddress;
  105. uint16 CoordPANId;
  106. uint16 SuperframeSpec;
  107. uint8 LogicalChannel;
  108. uint8 ChannelPage;
  109. uint8 GTSPermit;
  110. uint8 LinkQuality;
  111. uint32 TimeStamp;
  112. uint8 SecurityFailure;
  113. ZMacSec_t Sec;
  114. } ZMacPanDesc_t;
  115. /* Communication status indication type */
  116. typedef struct
  117. {
  118. ZMacEventHdr_t hdr;
  119. zAddrType_t SrcAddress;
  120. zAddrType_t DstAddress;
  121. uint16 PANId;
  122. uint8 Reason;
  123. ZMacSec_t Sec;
  124. } ZMacCommStatusInd_t;
  125. /* SYNC */
  126. typedef struct
  127. {
  128. uint8 LogicalChannel; /* The logical channel to use */
  129. uint8 ChannelPage; /* The channel page to use */
  130. uint8 TrackBeacon; /* Set to TRUE to continue tracking beacons after synchronizing with the
  131. first beacon. Set to FALSE to only synchronize with the first beacon */
  132. }ZMacSyncReq_t;
  133. /* DATA TYPES */
  134. /* Data request parameters type */
  135. typedef struct
  136. {
  137. zAddrType_t DstAddr;
  138. uint16 DstPANId;
  139. uint8 SrcAddrMode;
  140. uint8 Handle;
  141. uint8 TxOptions;
  142. uint8 Channel;
  143. uint8 Power;
  144. ZMacSec_t Sec;
  145. uint8 msduLength;
  146. uint8 *msdu;
  147. } ZMacDataReq_t;
  148. /* Data confirm type */
  149. typedef struct
  150. {
  151. ZMacEventHdr_t hdr;
  152. uint8 msduHandle;
  153. ZMacDataReq_t *pDataReq;
  154. uint32 Timestamp;
  155. uint16 Timestamp2;
  156. uint8 retries;
  157. uint8 mpduLinkQuality;
  158. uint8 correlation;
  159. int8 rssi;
  160. } ZMacDataCnf_t;
  161. /* ASSOCIATION TYPES */
  162. /* Associate request type */
  163. typedef struct
  164. {
  165. uint8 LogicalChannel;
  166. uint8 ChannelPage;
  167. zAddrType_t CoordAddress;
  168. uint16 CoordPANId;
  169. uint8 CapabilityFlags;
  170. ZMacSec_t Sec;
  171. } ZMacAssociateReq_t;
  172. /* Associate response type */
  173. typedef struct
  174. {
  175. ZLongAddr_t DeviceAddress;
  176. uint16 AssocShortAddress;
  177. uint8 Status;
  178. ZMacSec_t Sec;
  179. } ZMacAssociateRsp_t;
  180. /* Associate indication parameters type */
  181. typedef struct
  182. {
  183. ZMacEventHdr_t hdr;
  184. ZLongAddr_t DeviceAddress;
  185. uint8 CapabilityFlags;
  186. ZMacSec_t Sec;
  187. } ZMacAssociateInd_t;
  188. /* Associate confim type */
  189. typedef struct
  190. {
  191. ZMacEventHdr_t hdr;
  192. uint16 AssocShortAddress;
  193. ZMacSec_t Sec;
  194. } ZMacAssociateCnf_t;
  195. /* Disassociate request type */
  196. typedef struct
  197. {
  198. zAddrType_t DeviceAddress;
  199. uint16 DevicePanId;
  200. uint8 DisassociateReason;
  201. uint8 TxIndirect;
  202. ZMacSec_t Sec;
  203. } ZMacDisassociateReq_t;
  204. /* Rx enable confirm type */
  205. typedef struct
  206. {
  207. ZMacEventHdr_t hdr;
  208. } ZMacRxEnableCnf_t;
  209. /* SCAN */
  210. /* Scan request type */
  211. typedef struct
  212. {
  213. uint32 ScanChannels;
  214. uint8 ScanType;
  215. uint8 ScanDuration;
  216. uint8 ChannelPage;
  217. uint8 MaxResults;
  218. ZMacSec_t Sec;
  219. union
  220. {
  221. uint8 *pEnergyDetect;
  222. ZMacPanDesc_t *pPanDescriptor;
  223. }Result;
  224. } ZMacScanReq_t;
  225. /* Scan confirm type */
  226. typedef struct
  227. {
  228. ZMacEventHdr_t hdr;
  229. uint8 ScanType;
  230. uint8 ChannelPage;
  231. uint32 UnscannedChannels;
  232. uint8 ResultListSize;
  233. union
  234. {
  235. uint8 *pEnergyDetect;
  236. ZMacPanDesc_t *pPanDescriptor;
  237. }Result;
  238. } ZMacScanCnf_t;
  239. /* START */
  240. /* Start request type */
  241. typedef struct
  242. {
  243. uint32 StartTime;
  244. uint16 PANID;
  245. uint8 LogicalChannel;
  246. uint8 ChannelPage;
  247. uint8 BeaconOrder;
  248. uint8 SuperframeOrder;
  249. uint8 PANCoordinator;
  250. uint8 BatteryLifeExt;
  251. uint8 CoordRealignment;
  252. ZMacSec_t RealignSec;
  253. ZMacSec_t BeaconSec;
  254. } ZMacStartReq_t;
  255. /* Start confirm type */
  256. typedef struct
  257. {
  258. ZMacEventHdr_t hdr;
  259. } ZMacStartCnf_t;
  260. /* POLL */
  261. /* Roll request type */
  262. typedef struct
  263. {
  264. zAddrType_t CoordAddress;
  265. uint16 CoordPanId;
  266. ZMacSec_t Sec;
  267. } ZMacPollReq_t;
  268. /* Poll confirm type */
  269. typedef struct
  270. {
  271. ZMacEventHdr_t hdr;
  272. } ZMacPollCnf_t;
  273. /* MAC_MLME_POLL_IND type */
  274. typedef struct
  275. {
  276. ZMacEventHdr_t hdr;
  277. uint16 srcShortAddr; /* Short address of the device sending the data request */
  278. uint16 srcPanId; /* Pan ID of the device sending the data request */
  279. } ZMacPollInd_t;
  280. /* ORPHAN */
  281. /* Orphan response type */
  282. typedef struct
  283. {
  284. ZLongAddr_t OrphanAddress;
  285. uint16 ShortAddress;
  286. uint8 AssociatedMember;
  287. ZMacSec_t Sec;
  288. } ZMacOrphanRsp_t;
  289. /* Orphan indication type */
  290. typedef struct
  291. {
  292. ZMacEventHdr_t hdr;
  293. ZLongAddr_t OrphanAddress;
  294. ZMacSec_t Sec;
  295. } ZMacOrphanInd_t;
  296. #if defined (MT_MAC_FUNC) || defined (MT_MAC_CB_FUNC)
  297. /* Sync loss indication type */
  298. typedef struct
  299. {
  300. ZMacEventHdr_t hdr;
  301. uint16 PANId;
  302. uint8 LogicalChannel;
  303. uint8 ChannelPage;
  304. ZMacSec_t Sec;
  305. } ZMacSyncLossInd_t;
  306. /* Data indication parameters type */
  307. typedef struct
  308. {
  309. ZMacEventHdr_t hdr;
  310. ZMacSec_t Sec;
  311. zAddrType_t SrcAddr;
  312. zAddrType_t DstAddr;
  313. uint32 Timestamp;
  314. uint16 Timestamp2;
  315. uint16 SrcPANId;
  316. uint16 DstPANId;
  317. uint8 mpduLinkQuality;
  318. uint8 Correlation;
  319. uint8 Rssi;
  320. uint8 Dsn;
  321. uint8 msduLength;
  322. uint8 *msdu;
  323. } ZMacDataInd_t;
  324. /* Disassociate indication type */
  325. typedef struct
  326. {
  327. ZMacEventHdr_t hdr;
  328. ZLongAddr_t DeviceAddress;
  329. uint8 DisassociateReason;
  330. ZMacSec_t Sec;
  331. } ZMacDisassociateInd_t;
  332. /* Disassociate confirm type */
  333. typedef struct
  334. {
  335. ZMacEventHdr_t hdr;
  336. zAddrType_t DeviceAddress;
  337. uint16 panID;
  338. } ZMacDisassociateCnf_t;
  339. /* Beacon notify indication type */
  340. typedef struct
  341. {
  342. ZMacEventHdr_t hdr;
  343. uint8 BSN;
  344. ZMacPanDesc_t *pPanDesc;
  345. uint8 PendAddrSpec;
  346. uint8 *AddrList;
  347. uint8 sduLength;
  348. uint8 *sdu;
  349. } ZMacBeaconNotifyInd_t;
  350. /* Purge confirm type */
  351. typedef struct
  352. {
  353. ZMacEventHdr_t hdr;
  354. uint8 msduHandle;
  355. } ZMacPurgeCnf_t;
  356. #endif
  357. typedef enum
  358. {
  359. TX_PWR_MINUS_22 = -22,
  360. TX_PWR_MINUS_21,
  361. TX_PWR_MINUS_20,
  362. TX_PWR_MINUS_19,
  363. TX_PWR_MINUS_18,
  364. TX_PWR_MINUS_17,
  365. TX_PWR_MINUS_16,
  366. TX_PWR_MINUS_15,
  367. TX_PWR_MINUS_14,
  368. TX_PWR_MINUS_13,
  369. TX_PWR_MINUS_12,
  370. TX_PWR_MINUS_11,
  371. TX_PWR_MINUS_10,
  372. TX_PWR_MINUS_9,
  373. TX_PWR_MINUS_8,
  374. TX_PWR_MINUS_7,
  375. TX_PWR_MINUS_6,
  376. TX_PWR_MINUS_5,
  377. TX_PWR_MINUS_4,
  378. TX_PWR_MINUS_3,
  379. TX_PWR_MINUS_2,
  380. TX_PWR_MINUS_1,
  381. TX_PWR_ZERO,
  382. TX_PWR_PLUS_1,
  383. TX_PWR_PLUS_2,
  384. TX_PWR_PLUS_3,
  385. TX_PWR_PLUS_4,
  386. TX_PWR_PLUS_5,
  387. TX_PWR_PLUS_6,
  388. TX_PWR_PLUS_7,
  389. TX_PWR_PLUS_8,
  390. TX_PWR_PLUS_9,
  391. TX_PWR_PLUS_10,
  392. TX_PWR_PLUS_11,
  393. TX_PWR_PLUS_12,
  394. TX_PWR_PLUS_13,
  395. TX_PWR_PLUS_14,
  396. TX_PWR_PLUS_15,
  397. TX_PWR_PLUS_16,
  398. TX_PWR_PLUS_17,
  399. TX_PWR_PLUS_18,
  400. TX_PWR_PLUS_19
  401. } ZMacTransmitPower_t; // The transmit power in units of -1 dBm.
  402. typedef struct
  403. {
  404. byte protocolID;
  405. byte stackProfile; // 4 bit in native
  406. byte protocolVersion; // 4 bit in native
  407. byte reserved; // 2 bit in native
  408. byte routerCapacity; // 1 bit in native
  409. byte deviceDepth; // 4 bit in native
  410. byte deviceCapacity; // 1 bit in native
  411. byte extendedPANID[Z_EXTADDR_LEN];
  412. byte txOffset[3];
  413. byte updateId;
  414. } beaconPayload_t;
  415. typedef uint8 (*applySecCB_t)( uint8 len, uint8 *msdu );
  416. typedef enum
  417. {
  418. LQI_ADJ_OFF = 0,
  419. LQI_ADJ_MODE1,
  420. LQI_ADJ_MODE2,
  421. LQI_ADJ_GET = 0xFF
  422. } ZMacLqiAdjust_t; // Mode settings for lqi adjustment
  423. /*********************************************************************
  424. * GLOBAL VARIABLES
  425. */
  426. #define NWK_CMD_ID_LEN sizeof( byte )
  427. /*********************************************************************
  428. * FUNCTIONS
  429. */
  430. /*
  431. * Initialize.
  432. */
  433. extern ZMacStatus_t ZMacInit( void );
  434. /*
  435. * Send a MAC Data Frame packet.
  436. */
  437. extern ZMacStatus_t ZMacDataReq( ZMacDataReq_t *param );
  438. /*
  439. * Send a MAC Data Frame packet and apply application security to the packet.
  440. */
  441. extern uint8 ZMacDataReqSec( ZMacDataReq_t *pData, applySecCB_t secCB );
  442. /*
  443. * Request an association with a coordinator.
  444. */
  445. extern ZMacStatus_t ZMacAssociateReq( ZMacAssociateReq_t *param );
  446. /*
  447. * Request to send an association response message.
  448. */
  449. extern ZMacStatus_t ZMacAssociateRsp( ZMacAssociateRsp_t *param );
  450. /*
  451. * Request to send a disassociate request message.
  452. */
  453. extern ZMacStatus_t ZMacDisassociateReq( ZMacDisassociateReq_t *param );
  454. /*
  455. * Gives the MAC extra processing time.
  456. * Returns false if its OK to sleep.
  457. */
  458. extern byte ZMacUpdate( void );
  459. /*
  460. * Read a MAC PIB attribute.
  461. */
  462. extern ZMacStatus_t ZMacGetReq( ZMacAttributes_t attr, byte *value );
  463. /*
  464. * This function allows the next higher layer to respond to
  465. * an orphan indication message.
  466. */
  467. extern ZMacStatus_t ZMacOrphanRsp( ZMacOrphanRsp_t *param );
  468. /*
  469. * This function is called to request MAC data request poll.
  470. */
  471. extern ZMacStatus_t ZMacPollReq( ZMacPollReq_t *param );
  472. /*
  473. * Reset the MAC.
  474. */
  475. extern ZMacStatus_t ZMacReset( byte SetDefaultPIB );
  476. /*
  477. * This function is called to perform a network scan.
  478. */
  479. extern ZMacStatus_t ZMacScanReq( ZMacScanReq_t *param );
  480. /*
  481. * Write a MAC PIB attribute.
  482. */
  483. extern ZMacStatus_t ZMacSetReq( ZMacAttributes_t attr, byte *value );
  484. #ifdef MAC_SECURITY
  485. /*
  486. * Read a MAC Security PIB attribute.
  487. */
  488. extern ZMacStatus_t ZMacSecurityGetReq( ZMacAttributes_t attr, byte *value );
  489. /*
  490. * Write a MAC Security PIB attribute.
  491. */
  492. extern ZMacStatus_t ZMacSecuritySetReq( ZMacAttributes_t attr, byte *value );
  493. #endif /* MAC_SECURITY */
  494. /*
  495. * This function is called to tell the MAC to transmit beacons
  496. * and become a coordinator.
  497. */
  498. extern ZMacStatus_t ZMacStartReq( ZMacStartReq_t *param );
  499. /*
  500. * This function is called to request a sync to the current
  501. * networks beacons.
  502. */
  503. extern ZMacStatus_t ZMacSyncReq( ZMacSyncReq_t *param );
  504. /*
  505. * This function requests to reset mac state machine and
  506. * transaction.
  507. */
  508. extern ZMacStatus_t ZMacCleanReq( void );
  509. /*
  510. * This function is called to request MAC to purge a message.
  511. */
  512. extern ZMacStatus_t ZMacPurgeReq( byte msduHandle );
  513. /*
  514. * This function is called to enable AUTOPEND and source address matching.
  515. */
  516. extern ZMacStatus_t ZMacSrcMatchEnable (uint8 addrType, uint8 numEntries);
  517. /*
  518. * This function is called to add a short or extended address to source address table.
  519. */
  520. extern ZMacStatus_t ZMacSrcMatchAddEntry (zAddrType_t *addr, uint16 panID);
  521. /*
  522. * This function is called to delete a short or extended address from source address table.
  523. */
  524. extern ZMacStatus_t ZMacSrcMatchDeleteEntry (zAddrType_t *addr, uint16 panID);
  525. /*
  526. * This funciton is called to enabled/disable acknowledging all packets with pending bit set
  527. */
  528. extern ZMacStatus_t ZMacSrcMatchAckAllPending (uint8 option);
  529. /*
  530. * This function is called to check if acknowledging all packets with pending bit set is enabled.
  531. */
  532. extern ZMacStatus_t ZMacSrcMatchCheckAllPending (void);
  533. /*
  534. * This function is called to request MAC to power on the radio hardware and wake up.
  535. */
  536. extern void ZMacPwrOnReq ( void );
  537. /*
  538. * This function returns the current power mode of the MAC.
  539. */
  540. extern uint8 ZMac_PwrMode(void);
  541. /*
  542. * This function is called to request MAC to set the transmit power level.
  543. */
  544. extern ZMacStatus_t ZMacSetTransmitPower( ZMacTransmitPower_t level );
  545. /*
  546. * This function is called to send out an empty msg
  547. */
  548. extern void ZMacSendNoData( uint16 DstAddr, uint16 DstPANId );
  549. /*
  550. * This callback function is called for every MAC message that is received
  551. * over-the-air or generated locally by MAC for the application.
  552. */
  553. extern uint8 (*pZMac_AppCallback)( uint8 *msgPtr );
  554. /*
  555. * This function returns true if the MAC state is idle.
  556. */
  557. extern uint8 ZMacStateIdle( void );
  558. /*
  559. * This function sets/returns LQI adjust mode.
  560. */
  561. extern ZMacLqiAdjust_t ZMacLqiAdjustMode( ZMacLqiAdjust_t mode );
  562. /*********************************************************************
  563. *********************************************************************/
  564. #ifdef __cplusplus
  565. }
  566. #endif
  567. #endif /* ZMAC_H */