Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
Dependents: TYBLE16_simple_data_logger TYBLE16_MP3_Air
fhss_api.h
00001 /* 00002 * Copyright (c) 2016-2018, Arm Limited and affiliates. 00003 * SPDX-License-Identifier: Apache-2.0 00004 * 00005 * Licensed under the Apache License, Version 2.0 (the "License"); 00006 * you may not use this file except in compliance with the License. 00007 * You may obtain a copy of the License at 00008 * 00009 * http://www.apache.org/licenses/LICENSE-2.0 00010 * 00011 * Unless required by applicable law or agreed to in writing, software 00012 * distributed under the License is distributed on an "AS IS" BASIS, 00013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00014 * See the License for the specific language governing permissions and 00015 * limitations under the License. 00016 */ 00017 00018 /** 00019 * \file fhss_api.h 00020 * \brief 00021 */ 00022 00023 #ifndef FHSS_API_H 00024 #define FHSS_API_H 00025 00026 00027 #ifdef __cplusplus 00028 extern "C" { 00029 #endif 00030 00031 typedef struct fhss_api fhss_api_t; 00032 typedef struct fhss_callback fhss_callback_t; 00033 00034 /** 00035 * @brief FHSS frame types. 00036 */ 00037 #define FHSS_SYNCH_FRAME 0 /**< FHSS synchronization frame */ 00038 #define FHSS_SYNCH_REQUEST_FRAME 1 /**< FHSS synchronization request frame */ 00039 #define FHSS_DATA_FRAME 2 /**< FHSS data frame */ 00040 00041 /** 00042 * @brief FHSS synchronization info length. 00043 */ 00044 #define FHSS_SYNCH_INFO_LENGTH 21 00045 00046 /** 00047 * @brief FHSS states. 00048 */ 00049 typedef enum { 00050 FHSS_UNSYNCHRONIZED, 00051 FHSS_SYNCHRONIZED, 00052 } fhss_states; 00053 00054 /** 00055 * @brief FHSS is broadcast channel. Checks if current channel is broadcast channel. 00056 * @param api FHSS instance. 00057 * @return false if unicast channel, true if broadcast channel. 00058 */ 00059 typedef bool fhss_is_broadcast_channel(const fhss_api_t *api); 00060 00061 /** 00062 * @brief FHSS queue check. Checks if broadcast queue must be used instead of unicast queue. 00063 * @param api FHSS instance. 00064 * @param is_broadcast_addr Destination address type of packet (true if broadcast address). 00065 * @param frame_type Frame type of packet (Frames types are defined by FHSS api). 00066 * @return false if unicast queue, true if broadcast queue. 00067 */ 00068 typedef bool fhss_use_broadcast_queue(const fhss_api_t *api, bool is_broadcast_addr, int frame_type); 00069 00070 /** 00071 * @brief FHSS TX handle. Set destination channel and write synchronization info. 00072 * @param api FHSS instance. 00073 * @param is_broadcast_addr Destination address type of packet (true if broadcast address). 00074 * @param destination_address Destination MAC address. 00075 * @param frame_type Frame type of packet (Frames types are defined by FHSS api). 00076 * @param frame_length MSDU length of the frame. 00077 * @param phy_header_length PHY header length. 00078 * @param phy_tail_length PHY tail length. 00079 * @param tx_time TX time. 00080 * @return 0 Success. 00081 * @return -1 Transmission of the packet is currently not allowed, try again. 00082 * @return -2 Invalid api. 00083 * @return -3 Broadcast packet on Unicast channel (not allowed), push packet back to queue. 00084 */ 00085 typedef int fhss_tx_handle(const fhss_api_t *api, bool is_broadcast_addr, uint8_t *destination_address, int frame_type, uint16_t frame_length, uint8_t phy_header_length, uint8_t phy_tail_length, uint32_t tx_time); 00086 00087 /** 00088 * @brief Check TX permission. 00089 * @param api FHSS instance. 00090 * @param is_broadcast_addr Destination address type of packet (true if broadcast address). 00091 * @param handle Handle of the data request. 00092 * @param frame_type Frame type of packet (Frames types are defined by FHSS api). 00093 * @param frame_length MSDU length of the frame. 00094 * @param phy_header_length PHY header length. 00095 * @param phy_tail_length PHY tail length. 00096 * @return false if transmission is denied, true if transmission is allowed. 00097 */ 00098 typedef bool fhss_check_tx_conditions(const fhss_api_t *api, bool is_broadcast_addr, uint8_t handle, int frame_type, uint16_t frame_length, uint8_t phy_header_length, uint8_t phy_tail_length); 00099 00100 /** 00101 * @brief Notification of received FHSS synch or synch request frame. 00102 * @param api FHSS instance. 00103 * @param pan_id Source PAN id of the received frame (FHSS_SYNCH_FRAME only). 00104 * @param source_address Source address of the received frame (FHSS_SYNCH_FRAME only). 00105 * @param timestamp Timestamp of reception (FHSS_SYNCH_FRAME only). 00106 * @param synch_info Pointer to synchronization info (FHSS_SYNCH_FRAME only). 00107 * @param frame_type Frame type of packet (Frames types are defined by FHSS api). 00108 */ 00109 typedef void fhss_receive_frame(const fhss_api_t *api, uint16_t pan_id, uint8_t *source_address, uint32_t timestamp, uint8_t *synch_info, int frame_type); 00110 00111 /** 00112 * @brief Data TX done callback. 00113 * @param api FHSS instance. 00114 * @param waiting_ack MAC is waiting Acknowledgement for this frame. 00115 * @param tx_completed TX completed (Ack received or no more retries left (if unicast frame)). 00116 * @param handle Handle of the data request. 00117 */ 00118 typedef void fhss_data_tx_done(const fhss_api_t *api, bool waiting_ack, bool tx_completed, uint8_t handle); 00119 00120 /** 00121 * @brief Data TX or CCA failed callback. 00122 * @param api FHSS instance. 00123 * @param handle Handle of the data request. 00124 * @param frame_type Frame type of packet (Frames types are defined by FHSS api). 00125 * @return true if frame has to be queued for retransmission, false otherwise. 00126 */ 00127 typedef bool fhss_data_tx_fail(const fhss_api_t *api, uint8_t handle, int frame_type); 00128 00129 /** 00130 * @brief Change synchronization state. 00131 * @param api FHSS instance. 00132 * @param fhss_state FHSS state (FHSS states are defined by FHSS api). 00133 * @param pan_id PAN id of the network FHSS synchronizes with. 00134 * @return -1 when failed, otherwise current MAC channel. 00135 */ 00136 typedef int16_t fhss_synch_state_set(const fhss_api_t *api, fhss_states fhss_state, uint16_t pan_id); 00137 00138 /** 00139 * @brief Read timestamp. 00140 * @param api FHSS instance. 00141 * @return Timestamp to be written in received frame. 00142 */ 00143 typedef uint32_t fhss_read_timestamp(const fhss_api_t *api); 00144 00145 /** 00146 * @brief Get additional retransmission period. FHSS uses different retry periods depending on destination or channel availability. 00147 * @param api FHSS instance. 00148 * @param destination_address Destination MAC address. 00149 * @param phy_mtu PHY MTU size. 00150 * @return Retransmission period in microsecond which should be added to normal backoff period. 00151 */ 00152 typedef uint32_t fhss_get_retry_period(const fhss_api_t *api, uint8_t *destination_address, uint16_t phy_mtu); 00153 00154 /** 00155 * @brief Write synchronization info to given pointer. 00156 * @param api FHSS instance. 00157 * @param ptr Pointer to data. Start of written data for Synch frame. Start of IE header for Data frame. 00158 * @param length Length of IE header. Ignored when Synch frame. 00159 * @param frame_type Frame type of packet (Frames types are defined by FHSS api). 00160 * @param tx_time TX time must be referenced to the first symbol following the SFD of the transmitted frame. 00161 * @return -1 on fail, write length otherwise. 00162 */ 00163 typedef int16_t fhss_write_synch_info(const fhss_api_t *api, uint8_t *ptr, uint8_t length, int frame_type, uint32_t tx_time); 00164 00165 /** 00166 * @brief Initialize MAC functions. 00167 * @param api FHSS instance. 00168 * @param callbacks MAC functions to be called from FHSS. 00169 * @return 0 Success. 00170 * @return -1 Invalid parameters. 00171 */ 00172 typedef int fhss_init_callbacks(const fhss_api_t *api, fhss_callback_t *callbacks); 00173 00174 /** 00175 * \brief Struct fhss_api defines interface between software MAC and FHSS. 00176 * Application creates fhss_api_s object by calling FHSS creator function. 00177 * Then object is passed to software MAC which then initialises it's own callback functions. 00178 */ 00179 struct fhss_api { 00180 fhss_is_broadcast_channel *is_broadcast_channel; /**< FHSS is broadcast channel. */ 00181 fhss_use_broadcast_queue *use_broadcast_queue; /**< FHSS queue check. */ 00182 fhss_tx_handle *tx_handle; /**< FHSS TX handle. */ 00183 fhss_check_tx_conditions *check_tx_conditions; /**< Check TX permission. */ 00184 fhss_receive_frame *receive_frame; /**< Notification of received FHSS synch or synch request frame. */ 00185 fhss_data_tx_done *data_tx_done; /**< Data TX done callback. */ 00186 fhss_data_tx_fail *data_tx_fail; /**< Data TX or CCA failed callback. */ 00187 fhss_synch_state_set *synch_state_set; /**< Change synchronization state. */ 00188 fhss_read_timestamp *read_timestamp; /**< Read timestamp. */ 00189 fhss_get_retry_period *get_retry_period; /**< Get retransmission period. */ 00190 fhss_write_synch_info *write_synch_info; /**< Write synchronization info to TX frame*/ 00191 fhss_init_callbacks *init_callbacks; /**< Initialize MAC functions. */ 00192 }; 00193 00194 /** 00195 * @brief Read MAC TX queue size. 00196 * @param fhss_api FHSS instance. 00197 * @param broadcast_queue Queue type to be read (true if broadcast queue). 00198 * @return Queue size (number of frames queued). 00199 */ 00200 typedef uint16_t mac_read_tx_queue_size(const fhss_api_t *fhss_api, bool broadcast_queue); 00201 00202 /** 00203 * @brief Read MAC address. 00204 * @param fhss_api FHSS instance. 00205 * @param mac_address MAC address pointer. 00206 * @return 0 Success. 00207 * @return -1 Invalid parameters. 00208 */ 00209 typedef int mac_read_mac_address(const fhss_api_t *fhss_api, uint8_t *mac_address); 00210 00211 /** 00212 * @brief Read PHY datarate. 00213 * @param fhss_api FHSS instance. 00214 * @return PHY datarate. 00215 */ 00216 typedef uint32_t mac_read_datarate(const fhss_api_t *fhss_api); 00217 00218 /** 00219 * @brief Read 32-bit timestamp. 00220 * @param fhss_api FHSS instance. 00221 * @return Timestamp. 00222 */ 00223 typedef uint32_t mac_read_timestamp(const fhss_api_t *fhss_api); 00224 00225 /** 00226 * @brief Change channel. 00227 * @param fhss_api FHSS instance. 00228 * @param channel_number Channel number. 00229 * @return 0 Success. 00230 * @return -1 Invalid parameters. 00231 */ 00232 typedef int mac_change_channel(const fhss_api_t *fhss_api, uint8_t channel_number); 00233 00234 /** 00235 * @brief Send FHSS frame. 00236 * @param fhss_api FHSS instance. 00237 * @param frame_type Frame type of packet (Frames types are defined by FHSS api). 00238 * @return 0 Success. 00239 * @return -1 Invalid parameters. 00240 */ 00241 typedef int mac_send_fhss_frame(const fhss_api_t *fhss_api, int frame_type); 00242 00243 /** 00244 * @brief Send notification when FHSS synchronization is lost. 00245 * @param fhss_api FHSS instance. 00246 * @return 0 Success. 00247 * @return -1 Invalid parameters. 00248 */ 00249 typedef int mac_synch_lost_notification(const fhss_api_t *fhss_api); 00250 00251 /** 00252 * @brief Poll TX queue. 00253 * @param fhss_api FHSS instance. 00254 * @return 0 Success. 00255 * @return -1 Invalid parameters. 00256 */ 00257 typedef int mac_tx_poll(const fhss_api_t *fhss_api); 00258 00259 /** 00260 * @brief Broadcast channel notification from FHSS. 00261 * @param fhss_api FHSS instance. 00262 * @param broadcast_time Remaining broadcast time. 00263 * @return 0 Success. 00264 * @return -1 Invalid parameters. 00265 */ 00266 typedef int mac_broadcast_notify(const fhss_api_t *fhss_api, uint32_t broadcast_time); 00267 00268 /** 00269 * @brief Read coordinator MAC address. 00270 * @param fhss_api FHSS instance. 00271 * @param mac_address MAC address pointer. 00272 * @return 0 Success. 00273 * @return -1 Invalid parameters. 00274 */ 00275 typedef int mac_read_coordinator_mac_address(const fhss_api_t *fhss_api, uint8_t *mac_address); 00276 00277 /** 00278 * @brief Read synchronization info for a specific peer. 00279 * @param fhss_api FHSS instance. 00280 * @param info_ptr Pointer to info data. 00281 * @param mac_address MAC address pointer. 00282 * @param info_type Type of the read info (UTT-IE, BT-IE, US-IE, BS-IE). 00283 * @param rx_timestamp Time of reception of the element. 00284 * @return >=0 Length of the info. 00285 * @return -1 Fail. 00286 */ 00287 typedef int mac_read_synch_info(const fhss_api_t *fhss_api, uint8_t *info_ptr, uint8_t *mac_address, int info_type, uint32_t rx_timestamp); 00288 00289 /** 00290 * \brief Struct fhss_callback defines functions that software MAC needs to implement. 00291 * Function pointers are passed to FHSS using fhss_init_callbacks function. 00292 */ 00293 struct fhss_callback { 00294 mac_read_tx_queue_size *read_tx_queue_size; /**< Read MAC TX queue size. */ 00295 mac_read_mac_address *read_mac_address; /**< Read MAC address. */ 00296 mac_read_datarate *read_datarate; /**< Read PHY datarate. */ 00297 mac_read_timestamp *read_timestamp; /**< Read timestamp. */ 00298 mac_change_channel *change_channel; /**< Change channel. */ 00299 mac_send_fhss_frame *send_fhss_frame; /**< Send FHSS frame. */ 00300 mac_synch_lost_notification *synch_lost_notification; /**< Send notification when FHSS synchronization is lost. */ 00301 mac_tx_poll *tx_poll; /**< Poll TX queue. */ 00302 mac_broadcast_notify *broadcast_notify; /**< Broadcast channel notification from FHSS. */ 00303 mac_read_coordinator_mac_address *read_coord_mac_address; /**< Read coordinator MAC address. */ 00304 mac_read_synch_info *read_synch_info; /**< Read information element for a specific MAC address. */ 00305 }; 00306 00307 #ifdef __cplusplus 00308 } 00309 #endif 00310 00311 #endif // FHSS_API_H
Generated on Tue Jul 12 2022 13:54:21 by
