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 {
00051     FHSS_UNSYNCHRONIZED,
00052     FHSS_SYNCHRONIZED,
00053 } fhss_states;
00054 
00055 /**
00056  * @brief FHSS is broadcast channel. Checks if current channel is broadcast channel.
00057  * @param api FHSS instance.
00058  * @return false if unicast channel, true if broadcast channel.
00059  */
00060 typedef bool fhss_is_broadcast_channel(const fhss_api_t *api);
00061 
00062 /**
00063  * @brief FHSS queue check. Checks if broadcast queue must be used instead of unicast queue.
00064  * @param api FHSS instance.
00065  * @param is_broadcast_addr Destination address type of packet (true if broadcast address).
00066  * @param frame_type Frame type of packet (Frames types are defined by FHSS api).
00067  * @return false if unicast queue, true if broadcast queue.
00068  */
00069 typedef bool fhss_use_broadcast_queue(const fhss_api_t *api, bool is_broadcast_addr, int frame_type);
00070 
00071 /**
00072  * @brief FHSS TX handle. Set destination channel and write synchronization info.
00073  * @param api FHSS instance.
00074  * @param is_broadcast_addr Destination address type of packet (true if broadcast address).
00075  * @param destination_address Destination MAC address.
00076  * @param frame_type Frame type of packet (Frames types are defined by FHSS api).
00077  * @param frame_length MSDU length of the frame.
00078  * @param phy_header_length PHY header length.
00079  * @param phy_tail_length PHY tail length.
00080  * @param tx_time TX time.
00081  * @return  0 Success.
00082  * @return -1 Transmission of the packet is currently not allowed, try again.
00083  * @return -2 Invalid api.
00084  * @return -3 Broadcast packet on Unicast channel (not allowed), push packet back to queue.
00085  */
00086 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);
00087 
00088 /**
00089  * @brief Check TX permission.
00090  * @param api FHSS instance.
00091  * @param is_broadcast_addr Destination address type of packet (true if broadcast address).
00092  * @param handle Handle of the data request.
00093  * @param frame_type Frame type of packet (Frames types are defined by FHSS api).
00094  * @param frame_length MSDU length of the frame.
00095  * @param phy_header_length PHY header length.
00096  * @param phy_tail_length PHY tail length.
00097  * @return false if transmission is denied, true if transmission is allowed.
00098  */
00099 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);
00100 
00101 /**
00102  * @brief Notification of received FHSS synch or synch request frame.
00103  * @param api FHSS instance.
00104  * @param pan_id Source PAN id of the received frame (FHSS_SYNCH_FRAME only).
00105  * @param source_address Source address of the received frame (FHSS_SYNCH_FRAME only).
00106  * @param timestamp Timestamp of reception (FHSS_SYNCH_FRAME only).
00107  * @param synch_info Pointer to synchronization info (FHSS_SYNCH_FRAME only).
00108  * @param frame_type Frame type of packet (Frames types are defined by FHSS api).
00109  */
00110 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);
00111 
00112 /**
00113  * @brief Data TX done callback.
00114  * @param api FHSS instance.
00115  * @param waiting_ack MAC is waiting Acknowledgement for this frame.
00116  * @param tx_completed TX completed (Ack received or no more retries left (if unicast frame)).
00117  * @param handle Handle of the data request.
00118  */
00119 typedef void fhss_data_tx_done(const fhss_api_t *api, bool waiting_ack, bool tx_completed, uint8_t handle);
00120 
00121 /**
00122  * @brief Data TX or CCA failed callback.
00123  * @param api FHSS instance.
00124  * @param handle Handle of the data request.
00125  * @param frame_type Frame type of packet (Frames types are defined by FHSS api).
00126  * @return true if frame has to be queued for retransmission, false otherwise.
00127  */
00128 typedef bool fhss_data_tx_fail(const fhss_api_t *api, uint8_t handle, int frame_type);
00129 
00130 /**
00131  * @brief Change synchronization state.
00132  * @param api FHSS instance.
00133  * @param fhss_state FHSS state (FHSS states are defined by FHSS api).
00134  * @param pan_id PAN id of the network FHSS synchronizes with.
00135  */
00136 typedef void 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 retransmission period. FHSS uses different retry periods for different destinations.
00147  * @param api FHSS instance.
00148  * @param destination_address Destination MAC address.
00149  * @param phy_mtu PHY MTU size.
00150  * @return Retransmission period.
00151  */
00152 typedef uint16_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 Change channel.
00220  * @param fhss_api FHSS instance.
00221  * @param channel_number Channel number.
00222  * @return  0 Success.
00223  * @return -1 Invalid parameters.
00224  */
00225 typedef int mac_change_channel(const fhss_api_t *fhss_api, uint8_t channel_number);
00226 
00227 /**
00228  * @brief Send FHSS frame.
00229  * @param fhss_api FHSS instance.
00230  * @param frame_type Frame type of packet (Frames types are defined by FHSS api).
00231  * @return  0 Success.
00232  * @return -1 Invalid parameters.
00233  */
00234 typedef int mac_send_fhss_frame(const fhss_api_t *fhss_api, int frame_type);
00235 
00236 /**
00237  * @brief Send notification when FHSS synchronization is lost.
00238  * @param fhss_api FHSS instance.
00239  * @return  0 Success.
00240  * @return -1 Invalid parameters.
00241  */
00242 typedef int mac_synch_lost_notification(const fhss_api_t *fhss_api);
00243 
00244 /**
00245  * @brief Poll TX queue.
00246  * @param fhss_api FHSS instance.
00247  * @return  0 Success.
00248  * @return -1 Invalid parameters.
00249  */
00250 typedef int mac_tx_poll(const fhss_api_t *fhss_api);
00251 
00252 /**
00253  * @brief Broadcast channel notification from FHSS.
00254  * @param fhss_api FHSS instance.
00255  * @param broadcast_time Remaining broadcast time.
00256  * @return  0 Success.
00257  * @return -1 Invalid parameters.
00258  */
00259 typedef int mac_broadcast_notify(const fhss_api_t *fhss_api, uint32_t broadcast_time);
00260 
00261 /**
00262  * @brief Read coordinator MAC address.
00263  * @param fhss_api FHSS instance.
00264  * @param mac_address MAC address pointer.
00265  * @return  0 Success.
00266  * @return -1 Invalid parameters.
00267  */
00268 typedef int mac_read_coordinator_mac_address(const fhss_api_t *fhss_api, uint8_t *mac_address);
00269 
00270 /**
00271  * @brief Read synchronization info for a specific peer.
00272  * @param fhss_api FHSS instance.
00273  * @param info_ptr Pointer to info data.
00274  * @param mac_address MAC address pointer.
00275  * @param info_type Type of the read info (UTT-IE, BT-IE, US-IE, BS-IE).
00276  * @param rx_timestamp Time of reception of the element.
00277  * @return  >=0 Length of the info.
00278  * @return -1 Fail.
00279  */
00280 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);
00281 
00282 /**
00283  * \brief Struct fhss_callback defines functions that software MAC needs to implement.
00284  * Function pointers are passed to FHSS using fhss_init_callbacks function.
00285  */
00286 struct fhss_callback {
00287     mac_read_tx_queue_size *read_tx_queue_size;                 /**< Read MAC TX queue size. */
00288     mac_read_mac_address *read_mac_address;                     /**< Read MAC address. */
00289     mac_read_datarate *read_datarate;                           /**< Read PHY datarate. */
00290     mac_change_channel *change_channel;                         /**< Change channel. */
00291     mac_send_fhss_frame *send_fhss_frame;                       /**< Send FHSS frame. */
00292     mac_synch_lost_notification *synch_lost_notification;       /**< Send notification when FHSS synchronization is lost. */
00293     mac_tx_poll *tx_poll;                                       /**< Poll TX queue. */
00294     mac_broadcast_notify *broadcast_notify;                     /**< Broadcast channel notification from FHSS. */
00295     mac_read_coordinator_mac_address *read_coord_mac_address;   /**< Read coordinator MAC address. */
00296     mac_read_synch_info *read_synch_info;                       /**< Read information element for a specific MAC address. */
00297 };
00298 
00299 #ifdef __cplusplus
00300 }
00301 #endif
00302 
00303 #endif // FHSS_API_H