1 /* 2 * Copyright (c) 2017, Nordic Semiconductor ASA 3 * All rights reserved. 4 * 5 * SPDX-License-Identifier: BSD-3-Clause 6 * 7 * Redistribution and use in source and binary forms, with or without 8 * modification, are permitted provided that the following conditions are met: 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 must reproduce the above copyright 14 * notice, this list of conditions and the following disclaimer in the 15 * documentation and/or other materials provided with the distribution. 16 * 17 * 3. Neither the name of Nordic Semiconductor ASA nor the names of its 18 * contributors may be used to endorse or promote products derived from this 19 * software without specific prior written permission. 20 * 21 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 22 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 23 * IMPLIED WARRANTIES OF MERCHANTABILITY, AND FITNESS FOR A PARTICULAR PURPOSE 24 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 25 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 26 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 27 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 28 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 29 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 30 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 31 * POSSIBILITY OF SUCH DAMAGE. 32 * 33 */ 34 35 #ifndef NRF_802154_COMMON_UTILS_H__ 36 #define NRF_802154_COMMON_UTILS_H__ 37 38 #include <stdint.h> 39 #include "nrf_802154_config.h" 40 41 /** 42 * @defgroup nrf_802154_data Functions to calculate data given by the driver 43 * @{ 44 */ 45 46 /** 47 * @brief Converts energy level received during the energy detection procedure to IEEE Std. 802.15.4-2015 compliant value. 48 * 49 * @param ed_dbm Energy level in dBm 50 * 51 * @return uint8_t Energy level in units compliant to IEEE Std. 802.15.4-2015 chapter 10.2.5. 52 */ 53 uint8_t nrf_802154_energy_level_from_dbm_calculate(int8_t ed_dbm); 54 55 /** 56 * @brief Converts a given dBm level to a CCA energy detection threshold value. 57 * 58 * @param[in] dbm Energy level in dBm used to calculate the CCAEDTHRES value. 59 * 60 * @return Energy level value corresponding to the given dBm level that is to be written to 61 * the CCACTRL register. 62 */ 63 uint8_t nrf_802154_ccaedthres_from_dbm_calculate(int8_t dbm); 64 65 /** 66 * @brief Calculates the timestamp of the first symbol of the preamble in a received frame. 67 * 68 * @deprecated This function is deprecated. Use @ref nrf_802154_timestamp_end_to_phr_convert 69 * instead and adjust the code that calls this function to rely on the timestamp of the first symbol 70 * of the PHR, not the timestamp of the first symbol of the frame. 71 * 72 * @param[in] end_timestamp Timestamp of the end of the last symbol in the frame, 73 * in microseconds. 74 * @param[in] psdu_length Number of bytes in the frame PSDU. 75 * 76 * @return Timestamp of the beginning of the first preamble symbol of a given frame, 77 * in microseconds. 78 */ 79 uint64_t nrf_802154_first_symbol_timestamp_get(uint64_t end_timestamp, uint8_t psdu_length); 80 81 /** 82 * @brief Calculates the timestamp of the MAC Header in a received frame. 83 * 84 * @deprecated This function is deprecated. Use @ref nrf_802154_timestamp_end_to_phr_convert 85 * instead and adjust the code that calls this function to rely on the timestamp of the first symbol 86 * of the PHR, not the MAC Header timestamp. 87 * 88 * @param[in] end_timestamp Timestamp of the end of the last symbol in the frame, 89 * in microseconds. 90 * @param[in] psdu_length Number of bytes in the frame PSDU. 91 * 92 * @return Timestamp of the MHR of a given frame, in microseconds. 93 */ 94 uint64_t nrf_802154_mhr_timestamp_get(uint64_t end_timestamp, uint8_t psdu_length); 95 96 /** 97 * @brief Converts the timestamp of the frame's end to the timestamp of the start of its PHR. 98 * 99 * This function calculates the time when the first symbol of the PHR is at the local antenna. Note 100 * that this time is equivalent to: the end of the frame's SFD and RMARKER as defined in' 101 * IEEE 802.15.4-2020, Section 6.9.1. 102 * 103 * @param[in] end_timestamp Timestamp of the end of the last symbol in the frame, 104 * in microseconds. 105 * @param[in] psdu_length Number of bytes in the frame PSDU. 106 * 107 * @return Timestamp of the start of the PHR of a given frame, in microseconds. 108 */ 109 uint64_t nrf_802154_timestamp_end_to_phr_convert(uint64_t end_timestamp, uint8_t psdu_length); 110 111 /** 112 * @brief Converts the timestamp of the frame's PHR to the timestamp of the start of its SHR. 113 * 114 * This function converts the time when the first symbol of the frame's PHR is at the local antenna 115 * to the timestamp of the start of the frame's SHR. 116 * 117 * @param[in] phr_timestamp Timestamp of the frame's PHR. 118 * 119 * @return Timestamp of the start of the SHR of a given frame, in microseconds. 120 */ 121 uint64_t nrf_802154_timestamp_phr_to_shr_convert(uint64_t phr_timestamp); 122 123 /** 124 * @brief Converts the timestamp of the frame's PHR to the timestamp of the start of its MHR. 125 * 126 * This function converts the time when the first symbol of the frame's PHR is at the local antenna 127 * to the timestamp of the start of the frame's MHR. 128 * 129 * @param[in] phr_timestamp Timestamp of the frame's PHR. 130 * 131 * @return Timestamp of the start of the MHR of a given frame, in microseconds. 132 */ 133 uint64_t nrf_802154_timestamp_phr_to_mhr_convert(uint64_t phr_timestamp); 134 135 /** 136 * @} 137 */ 138 139 #endif // NRF_802154_COMMON_UTILS_H__ 140
