phy_common.h 9.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240
  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 PHY_COMMON_H_INCLUDED
  43. #define PHY_COMMON_H_INCLUDED
  44. /** @file
  45. * This file contains declarations of commonly used PHY routines and necessary macros/types.
  46. *
  47. * @defgroup phy_common PHY Common API
  48. * @ingroup phy_15_4
  49. * @{
  50. * @brief Module to declare Common PHY API
  51. * @details The Common PHY module contains declarations of commonly used PHY routines and necessary macros/types.
  52. */
  53. /**@brief The maximum PSDU size (in octets) the PHY shall be able to receive (aMaxPHYPacketSize).
  54. *
  55. * @details See Table 22 - PHY constants.
  56. */
  57. #define PHY_MAX_PACKET_SIZE 127
  58. /**@brief The maximum PHR size (in octets).
  59. *
  60. * @details See 6.3 PPDU format.
  61. */
  62. #define PHY_MAX_HEADER_SIZE 1
  63. /**@brief Maximum PPDU size */
  64. #define PHY_MAX_PPDU_SIZE (PHY_MAX_HEADER_SIZE + PHY_MAX_PACKET_SIZE)
  65. /**@brief Position of PHY header related to income PPDU start pointer.*/
  66. #define PHY_HEADER_POS (-1)
  67. /**@brief Size of PHY header in bytes.*/
  68. #define PHY_HEADER_SIZE 1
  69. /**@brief Maximum channel number.*/
  70. #define PHY_MAX_CHANNEL_NUM 0x1Au
  71. /**@brief Minimum channel number.*/
  72. #define PHY_MIN_CHANNEL_NUM 0x0Bu
  73. // for 2400 MHz O-QPSK 1 octet = 2 symbols 1 symbol = 32bits chip
  74. #define aMaxPHYPacketSize PHY_MAX_PACKET_SIZE // in octets
  75. #define aTurnaroundTime 12 // in symbols
  76. #define aTurnaroundTimeUs 192 // in us
  77. // Read only parameters
  78. #define PHY_CURRENT_PAGE 0x0u
  79. #define PHY_CHANNEL_SUPPORTED 0x07FFF800ul
  80. #define PHY_SHR_DURATION 10u
  81. #define PHY_MAX_FRAME_DURATION (PHY_SHR_DURATION + (int)((aMaxPHYPacketSize + 1) * PHY_SYMBOLS_PER_OCTET))
  82. #define PHY_SYMBOLS_PER_OCTET 2u
  83. // CCA values
  84. #define PHY_TRX_CCA_MODE0 0
  85. #define PHY_TRX_CCA_MODE1 1
  86. #define PHY_TRX_CCA_MODE2 2
  87. #define PHY_TRX_CCA_MODE3 3
  88. /** @brief Minimum value that can be used to set radio transmit power. Equals
  89. * to -32 dBm.
  90. *
  91. * This is a combination of digits which includes:
  92. * 2 MSBs represent the tolerance on the transmit power
  93. * 6 LSBs which may be written to, represent a signed integer in twos-complement format,
  94. * corresponding to the nominal transmit power of the device in decibels relative to 1 mW.
  95. * All combinations less than 0xBF are valid.
  96. */
  97. #define PHY_MIN_TX_POWER 0x20
  98. /** @brief Internal parameter of the PHY layer.
  99. *
  100. * @details Position of the sign bit inside transmit power attribute.*/
  101. #define PHY_TRANSMIT_POWER_SIGN_BIT_POS 5
  102. /** @brief Internal parameter of the PHY layer.
  103. *
  104. * @details This mask hides transmit power from transmit power attribute value,
  105. * but leaves precision bitfield.
  106. */
  107. #define PHY_TRANSMIT_POWER_MASK 0xC0
  108. /** @brief Internal parameter of the PHY layer.
  109. *
  110. * @details This mask hides precision bitfield from transmit power attribute value,
  111. * leaving transmit power unchanged.
  112. */
  113. #define PHY_TRANSMIT_POWER_MASK_INV 0x3F
  114. // Possible transmit power
  115. #define DBM_11 ( 11 & PHY_TRANSMIT_POWER_MASK_INV)
  116. #define DBM_10 ( 10 & PHY_TRANSMIT_POWER_MASK_INV)
  117. #define DBM_9 ( 9 & PHY_TRANSMIT_POWER_MASK_INV)
  118. #define DBM_8 ( 8 & PHY_TRANSMIT_POWER_MASK_INV)
  119. #define DBM_7 ( 7 & PHY_TRANSMIT_POWER_MASK_INV)
  120. #define DBM_6 ( 6 & PHY_TRANSMIT_POWER_MASK_INV)
  121. #define DBM_5 ( 5 & PHY_TRANSMIT_POWER_MASK_INV)
  122. #define DBM_4 ( 4 & PHY_TRANSMIT_POWER_MASK_INV)
  123. #define DBM_3 ( 3 & PHY_TRANSMIT_POWER_MASK_INV)
  124. #define DBM_2 ( 2 & PHY_TRANSMIT_POWER_MASK_INV)
  125. #define DBM_1 ( 1 & PHY_TRANSMIT_POWER_MASK_INV)
  126. #define DBM_0 ( 0 & PHY_TRANSMIT_POWER_MASK_INV)
  127. #define DBM_MIN_1 (( -1) & PHY_TRANSMIT_POWER_MASK_INV)
  128. #define DBM_MIN_2 (( -2) & PHY_TRANSMIT_POWER_MASK_INV)
  129. #define DBM_MIN_3 (( -3) & PHY_TRANSMIT_POWER_MASK_INV)
  130. #define DBM_MIN_4 (( -4) & PHY_TRANSMIT_POWER_MASK_INV)
  131. #define DBM_MIN_5 (( -5) & PHY_TRANSMIT_POWER_MASK_INV)
  132. #define DBM_MIN_6 (( -6) & PHY_TRANSMIT_POWER_MASK_INV)
  133. #define DBM_MIN_7 (( -7) & PHY_TRANSMIT_POWER_MASK_INV)
  134. #define DBM_MIN_8 (( -8) & PHY_TRANSMIT_POWER_MASK_INV)
  135. #define DBM_MIN_9 (( -9) & PHY_TRANSMIT_POWER_MASK_INV)
  136. #define DBM_MIN_10 ((-10) & PHY_TRANSMIT_POWER_MASK_INV)
  137. #define DBM_MIN_11 ((-11) & PHY_TRANSMIT_POWER_MASK_INV)
  138. #define DBM_MIN_12 ((-12) & PHY_TRANSMIT_POWER_MASK_INV)
  139. #define DBM_MIN_13 ((-13) & PHY_TRANSMIT_POWER_MASK_INV)
  140. #define DBM_MIN_14 ((-14) & PHY_TRANSMIT_POWER_MASK_INV)
  141. #define DBM_MIN_15 ((-15) & PHY_TRANSMIT_POWER_MASK_INV)
  142. #define DBM_MIN_16 ((-16) & PHY_TRANSMIT_POWER_MASK_INV)
  143. #define DBM_MIN_17 ((-17) & PHY_TRANSMIT_POWER_MASK_INV)
  144. #define DBM_MIN_18 ((-18) & PHY_TRANSMIT_POWER_MASK_INV)
  145. #define DBM_MIN_19 ((-19) & PHY_TRANSMIT_POWER_MASK_INV)
  146. #define DBM_MIN_20 ((-20) & PHY_TRANSMIT_POWER_MASK_INV)
  147. #define DBM_MIN_21 ((-21) & PHY_TRANSMIT_POWER_MASK_INV)
  148. #define DBM_MIN_22 ((-22) & PHY_TRANSMIT_POWER_MASK_INV)
  149. #define DBM_MIN_23 ((-23) & PHY_TRANSMIT_POWER_MASK_INV)
  150. #define DBM_MIN_24 ((-24) & PHY_TRANSMIT_POWER_MASK_INV)
  151. #define DBM_MIN_25 ((-25) & PHY_TRANSMIT_POWER_MASK_INV)
  152. #define DBM_MIN_26 ((-26) & PHY_TRANSMIT_POWER_MASK_INV)
  153. #define DBM_MIN_27 ((-27) & PHY_TRANSMIT_POWER_MASK_INV)
  154. /**@brief Common PHY enumerations description used in various PHY primitives.
  155. *
  156. * @details See Table 18-PHY enumerations description for detailed info on the statuses up to PHY_READ_ONLY.
  157. * The statuses with higher numbers are implementation specific and used for synchronous API only.
  158. */
  159. typedef enum
  160. {
  161. /** The CCA attempt has detected a busy channel. */
  162. PHY_BUSY = 0x00,
  163. /** The transceiver is asked to change its state while receiving. */
  164. PHY_BUSY_RX = 0x01,
  165. /** The transceiver is asked to change its state while transmitting. */
  166. PHY_BUSY_TX = 0x02,
  167. /** The transceiver is to be switched off immediately. */
  168. PHY_FORCE_TRX_OFF = 0x03,
  169. /** The CCA attempt has detected an idle channel. */
  170. PHY_IDLE = 0x04,
  171. /** A SET/GET request was issued with a parameter in the primitive that is
  172. out of the valid range. */
  173. PHY_INVALID_PARAMETER = 0x05,
  174. /** The transceiver is in or is to be configured into the receiver enabled state. */
  175. PHY_RX_ON = 0x06,
  176. /** A SET/GET, an ED operation, or a transceiver state change was successful. */
  177. PHY_SUCCESS = 0x07,
  178. /** The transceiver is in or is to be configured into the transceiver disabled state. */
  179. PHY_TRX_OFF = 0x08,
  180. /** The transceiver is in or is to be configured into the transmitter enabled state. */
  181. PHY_TX_ON = 0x09,
  182. /** A SET/GET request was issued with the identifier of an attribute that is not supported. */
  183. PHY_UNSUPPORTED_ATTRIBUTE = 0x0A,
  184. /** A SET/GET request was issued with the identifier of an attribute that is read-only.*/
  185. PHY_READ_ONLY = 0x0B,
  186. /* Statuses out of the standard. They are used for synchronous API */
  187. /** Transceiver is forced to change it's state to PHY_TX_ON (potential packet drop). */
  188. PHY_FORCE_TX_ON = 0xFC,
  189. /** Data cannot be sent due to failed CCA results.*/
  190. PHY_CHANNEL_ACCESS_FAILURE = 0xFD,
  191. /** Data had been sent but ACK frame hasn't been received.*/
  192. PHY_NO_ACK = 0xFE,
  193. /** PHY is not available for synchronous access */
  194. PHY_IS_NOT_AVAILABLE = 0xFF
  195. } phy_enum_t;
  196. /**@brief PHY status type.*/
  197. typedef phy_enum_t phy_status_t;
  198. /** @} */
  199. #endif // PHY_COMMON_H_INCLUDED