1 /* 2 * Copyright (c) 2016, The OpenThread Authors. 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions are met: 7 * 1. Redistributions of source code must retain the above copyright 8 * notice, this list of conditions and the following disclaimer. 9 * 2. Redistributions in binary form must reproduce the above copyright 10 * notice, this list of conditions and the following disclaimer in the 11 * documentation and/or other materials provided with the distribution. 12 * 3. Neither the name of the copyright holder nor the 13 * names of its contributors may be used to endorse or promote products 14 * derived from this software without specific prior written permission. 15 * 16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 17 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 20 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 21 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 22 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 23 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 26 * POSSIBILITY OF SUCH DAMAGE. 27 */ 28 29 /** 30 * @file 31 * @brief 32 * This file defines the raw OpenThread IEEE 802.15.4 Link Layer API. 33 */ 34 35 #ifndef OPENTHREAD_LINK_RAW_H_ 36 #define OPENTHREAD_LINK_RAW_H_ 37 38 #include <openthread/platform/radio.h> 39 40 #ifdef __cplusplus 41 extern "C" { 42 #endif 43 44 /** 45 * @addtogroup api-link-raw 46 * 47 * @brief 48 * This module includes functions that control the raw link-layer configuration. 49 * 50 * @{ 51 * 52 */ 53 54 /** 55 * Pointer on receipt of a IEEE 802.15.4 frame. 56 * 57 * @param[in] aInstance A pointer to an OpenThread instance. 58 * @param[in] aFrame A pointer to the received frame or NULL if the receive operation was aborted. 59 * @param[in] aError OT_ERROR_NONE when successfully received a frame. 60 * OT_ERROR_ABORT when reception was aborted and a frame was not received. 61 * 62 */ 63 typedef void (*otLinkRawReceiveDone)(otInstance *aInstance, otRadioFrame *aFrame, otError aError); 64 65 /** 66 * Enables/disables the raw link-layer. 67 * 68 * @param[in] aInstance A pointer to an OpenThread instance. 69 * @param[in] aCallback A pointer to a function called on receipt of a IEEE 802.15.4 frame. NULL to disable the 70 * raw-link layer. 71 * 72 * @retval OT_ERROR_FAILED The radio could not be enabled/disabled. 73 * @retval OT_ERROR_INVALID_STATE If the OpenThread IPv6 interface is already enabled. 74 * @retval OT_ERROR_NONE If the enable state was successfully set. 75 * 76 */ 77 otError otLinkRawSetReceiveDone(otInstance *aInstance, otLinkRawReceiveDone aCallback); 78 79 /** 80 * Indicates whether or not the raw link-layer is enabled. 81 * 82 * @param[in] aInstance A pointer to an OpenThread instance. 83 * 84 * @retval true The raw link-layer is enabled. 85 * @retval false The raw link-layer is disabled. 86 * 87 */ 88 bool otLinkRawIsEnabled(otInstance *aInstance); 89 90 /** 91 * Gets the status of promiscuous mode. 92 * 93 * @param[in] aInstance A pointer to an OpenThread instance. 94 * 95 * @retval true Promiscuous mode is enabled. 96 * @retval false Promiscuous mode is disabled. 97 * 98 */ 99 bool otLinkRawGetPromiscuous(otInstance *aInstance); 100 101 /** 102 * Enables or disables promiscuous mode. 103 * 104 * @param[in] aInstance A pointer to an OpenThread instance. 105 * @param[in] aEnable A value to enable or disable promiscuous mode. 106 * 107 * @retval OT_ERROR_NONE If successful. 108 * @retval OT_ERROR_INVALID_STATE If the raw link-layer isn't enabled. 109 * 110 */ 111 otError otLinkRawSetPromiscuous(otInstance *aInstance, bool aEnable); 112 113 /** 114 * Set the Short Address for address filtering. 115 * 116 * @param[in] aInstance A pointer to an OpenThread instance. 117 * @param[in] aShortAddress The IEEE 802.15.4 Short Address. 118 * 119 * @retval OT_ERROR_NONE If successful. 120 * @retval OT_ERROR_INVALID_STATE If the raw link-layer isn't enabled. 121 * 122 */ 123 otError otLinkRawSetShortAddress(otInstance *aInstance, uint16_t aShortAddress); 124 125 /** 126 * Transition the radio from Receive to Sleep. 127 * Turn off the radio. 128 * 129 * @param[in] aInstance A pointer to an OpenThread instance. 130 * 131 * @retval OT_ERROR_NONE Successfully transitioned to Sleep. 132 * @retval OT_ERROR_BUSY The radio was transmitting 133 * @retval OT_ERROR_INVALID_STATE The radio was disabled 134 * 135 */ 136 otError otLinkRawSleep(otInstance *aInstance); 137 138 /** 139 * Transitioning the radio from Sleep to Receive. 140 * Turn on the radio. 141 * 142 * @param[in] aInstance A pointer to an OpenThread instance. 143 * 144 * @retval OT_ERROR_NONE Successfully transitioned to Receive. 145 * @retval OT_ERROR_INVALID_STATE The radio was disabled or transmitting. 146 * 147 */ 148 otError otLinkRawReceive(otInstance *aInstance); 149 150 /** 151 * The radio transitions from Transmit to Receive. 152 * Returns a pointer to the transmit buffer. 153 * 154 * The caller forms the IEEE 802.15.4 frame in this buffer then calls otLinkRawTransmit() 155 * to request transmission. 156 * 157 * @param[in] aInstance A pointer to an OpenThread instance. 158 * 159 * @returns A pointer to the transmit buffer or NULL if the raw link-layer isn't enabled. 160 * 161 */ 162 otRadioFrame *otLinkRawGetTransmitBuffer(otInstance *aInstance); 163 164 /** 165 * Pointer on receipt of a IEEE 802.15.4 frame. 166 * 167 * @param[in] aInstance A pointer to an OpenThread instance. 168 * @param[in] aFrame A pointer to the frame that was transmitted. 169 * @param[in] aAckFrame A pointer to the ACK frame. 170 * @param[in] aError OT_ERROR_NONE when the frame was transmitted. 171 * OT_ERROR_NO_ACK when the frame was transmitted but no ACK was received 172 * OT_ERROR_CHANNEL_ACCESS_FAILURE when the transmission could not take place 173 due to activity on the channel. 174 * OT_ERROR_ABORT when transmission was aborted for other reasons. 175 * 176 */ 177 typedef void (*otLinkRawTransmitDone)(otInstance *aInstance, 178 otRadioFrame *aFrame, 179 otRadioFrame *aAckFrame, 180 otError aError); 181 182 /** 183 * Begins the transmit sequence on the radio. 184 * 185 * The caller must form the IEEE 802.15.4 frame in the buffer provided by otLinkRawGetTransmitBuffer() before 186 * requesting transmission. The channel and transmit power are also included in the otRadioFrame structure. 187 * 188 * The transmit sequence consists of: 189 * 1. Transitioning the radio to Transmit from Receive. 190 * 2. Transmits the PSDU on the given channel and at the given transmit power. 191 * 192 * @param[in] aInstance A pointer to an OpenThread instance. 193 * @param[in] aCallback A pointer to a function called on completion of the transmission. 194 * 195 * @retval OT_ERROR_NONE Successfully transitioned to Transmit. 196 * @retval OT_ERROR_INVALID_STATE The radio was not in the Receive state. 197 * 198 */ 199 otError otLinkRawTransmit(otInstance *aInstance, otLinkRawTransmitDone aCallback); 200 201 /** 202 * Get the most recent RSSI measurement. 203 * 204 * @param[in] aInstance A pointer to an OpenThread instance. 205 * 206 * @returns The RSSI in dBm when it is valid. 127 when RSSI is invalid. 207 * 208 */ 209 int8_t otLinkRawGetRssi(otInstance *aInstance); 210 211 /** 212 * Get the radio capabilities. 213 * 214 * @param[in] aInstance A pointer to an OpenThread instance. 215 * 216 * @returns The radio capability bit vector. The stack enables or disables some functions based on this value. 217 * 218 */ 219 otRadioCaps otLinkRawGetCaps(otInstance *aInstance); 220 221 /** 222 * Pointer on receipt of a IEEE 802.15.4 frame. 223 * 224 * @param[in] aInstance A pointer to an OpenThread instance. 225 * @param[in] aEnergyScanMaxRssi The maximum RSSI encountered on the scanned channel. 226 * 227 */ 228 typedef void (*otLinkRawEnergyScanDone)(otInstance *aInstance, int8_t aEnergyScanMaxRssi); 229 230 /** 231 * Begins the energy scan sequence on the radio. 232 * 233 * @param[in] aInstance A pointer to an OpenThread instance. 234 * @param[in] aScanChannel The channel to perform the energy scan on. 235 * @param[in] aScanDuration The duration, in milliseconds, for the channel to be scanned. 236 * @param[in] aCallback A pointer to a function called on completion of a scanned channel. 237 * 238 * @retval OT_ERROR_NONE Successfully started scanning the channel. 239 * @retval OT_ERROR_BUSY The radio is performing energy scanning. 240 * @retval OT_ERROR_NOT_IMPLEMENTED The radio doesn't support energy scanning. 241 * @retval OT_ERROR_INVALID_STATE If the raw link-layer isn't enabled. 242 * 243 */ 244 otError otLinkRawEnergyScan(otInstance *aInstance, 245 uint8_t aScanChannel, 246 uint16_t aScanDuration, 247 otLinkRawEnergyScanDone aCallback); 248 249 /** 250 * Enable/Disable source match for frame pending. 251 * 252 * @param[in] aInstance A pointer to an OpenThread instance. 253 * @param[in] aEnable Enable/disable source match for frame pending. 254 * 255 * @retval OT_ERROR_NONE If successful. 256 * @retval OT_ERROR_INVALID_STATE If the raw link-layer isn't enabled. 257 * 258 */ 259 otError otLinkRawSrcMatchEnable(otInstance *aInstance, bool aEnable); 260 261 /** 262 * Adding short address to the source match table. 263 * 264 * @param[in] aInstance A pointer to an OpenThread instance. 265 * @param[in] aShortAddress The short address to be added. 266 * 267 * @retval OT_ERROR_NONE Successfully added short address to the source match table. 268 * @retval OT_ERROR_NO_BUFS No available entry in the source match table. 269 * @retval OT_ERROR_INVALID_STATE If the raw link-layer isn't enabled. 270 * 271 */ 272 otError otLinkRawSrcMatchAddShortEntry(otInstance *aInstance, uint16_t aShortAddress); 273 274 /** 275 * Adding extended address to the source match table. 276 * 277 * @param[in] aInstance A pointer to an OpenThread instance. 278 * @param[in] aExtAddress The extended address to be added. 279 * 280 * @retval OT_ERROR_NONE Successfully added extended address to the source match table. 281 * @retval OT_ERROR_NO_BUFS No available entry in the source match table. 282 * @retval OT_ERROR_INVALID_STATE If the raw link-layer isn't enabled. 283 * 284 */ 285 otError otLinkRawSrcMatchAddExtEntry(otInstance *aInstance, const otExtAddress *aExtAddress); 286 287 /** 288 * Removing short address to the source match table. 289 * 290 * @param[in] aInstance A pointer to an OpenThread instance. 291 * @param[in] aShortAddress The short address to be removed. 292 * 293 * @retval OT_ERROR_NONE Successfully removed short address from the source match table. 294 * @retval OT_ERROR_NO_ADDRESS The short address is not in source match table. 295 * @retval OT_ERROR_INVALID_STATE If the raw link-layer isn't enabled. 296 * 297 */ 298 otError otLinkRawSrcMatchClearShortEntry(otInstance *aInstance, uint16_t aShortAddress); 299 300 /** 301 * Removing extended address to the source match table of the radio. 302 * 303 * @param[in] aInstance A pointer to an OpenThread instance. 304 * @param[in] aExtAddress The extended address to be removed. 305 * 306 * @retval OT_ERROR_NONE Successfully removed the extended address from the source match table. 307 * @retval OT_ERROR_NO_ADDRESS The extended address is not in source match table. 308 * @retval OT_ERROR_INVALID_STATE If the raw link-layer isn't enabled. 309 * 310 */ 311 otError otLinkRawSrcMatchClearExtEntry(otInstance *aInstance, const otExtAddress *aExtAddress); 312 313 /** 314 * Removing all the short addresses from the source match table. 315 * 316 * @param[in] aInstance A pointer to an OpenThread instance. 317 * 318 * @retval OT_ERROR_NONE If successful. 319 * @retval OT_ERROR_INVALID_STATE If the raw link-layer isn't enabled. 320 * 321 */ 322 otError otLinkRawSrcMatchClearShortEntries(otInstance *aInstance); 323 324 /** 325 * Removing all the extended addresses from the source match table. 326 * 327 * @param[in] aInstance A pointer to an OpenThread instance. 328 * 329 * @retval OT_ERROR_NONE If successful. 330 * @retval OT_ERROR_INVALID_STATE If the raw link-layer isn't enabled. 331 * 332 */ 333 otError otLinkRawSrcMatchClearExtEntries(otInstance *aInstance); 334 335 /** 336 * Update MAC keys and key index. 337 * 338 * @param[in] aInstance A pointer to an OpenThread instance. 339 * @param[in] aKeyIdMode The key ID mode. 340 * @param[in] aKeyId The key index. 341 * @param[in] aPrevKey The previous MAC key. 342 * @param[in] aCurrKey The current MAC key. 343 * @param[in] aNextKey The next MAC key. 344 * 345 * @retval OT_ERROR_NONE If successful. 346 * @retval OT_ERROR_INVALID_STATE If the raw link-layer isn't enabled. 347 * 348 */ 349 otError otLinkRawSetMacKey(otInstance *aInstance, 350 uint8_t aKeyIdMode, 351 uint8_t aKeyId, 352 const otMacKey *aPrevKey, 353 const otMacKey *aCurrKey, 354 const otMacKey *aNextKey); 355 356 /** 357 * Sets the current MAC frame counter value. 358 * 359 * Always sets the MAC counter to the new given value @p aMacFrameCounter independent of the current 360 * value. 361 * 362 * @param[in] aInstance A pointer to an OpenThread instance. 363 * @param[in] aMacFrameCounter The MAC frame counter value. 364 * 365 * @retval OT_ERROR_NONE If successful. 366 * @retval OT_ERROR_INVALID_STATE If the raw link-layer isn't enabled. 367 * 368 */ 369 otError otLinkRawSetMacFrameCounter(otInstance *aInstance, uint32_t aMacFrameCounter); 370 371 /** 372 * Sets the current MAC frame counter value only if the new value is larger than the current one. 373 * 374 * @param[in] aInstance A pointer to an OpenThread instance. 375 * @param[in] aMacFrameCounter The MAC frame counter value. 376 * 377 * @retval OT_ERROR_NONE If successful. 378 * @retval OT_ERROR_INVALID_STATE If the raw link-layer isn't enabled. 379 * 380 */ 381 otError otLinkRawSetMacFrameCounterIfLarger(otInstance *aInstance, uint32_t aMacFrameCounter); 382 383 /** 384 * Get current platform time (64bits width) of the radio chip. 385 * 386 * @param[in] aInstance A pointer to an OpenThread instance. 387 * 388 * @returns The current radio time in microseconds. 389 * 390 */ 391 uint64_t otLinkRawGetRadioTime(otInstance *aInstance); 392 393 /** 394 * @} 395 * 396 */ 397 398 #ifdef __cplusplus 399 } // extern "C" 400 #endif 401 402 #endif // OPENTHREAD_LINK_RAW_H_ 403
