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
mac_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 mac_api.h 00020 * \brief A API class to support different MACs from multiple vendors. 00021 * Vendor must implement a function which fills supported callback functions which Upper layer will use. 00022 */ 00023 00024 #ifndef MAC_API_H 00025 #define MAC_API_H 00026 00027 #include <inttypes.h> 00028 #include "mlme.h" 00029 #include "mac_mcps.h" 00030 00031 #ifdef __cplusplus 00032 extern "C" { 00033 #endif 00034 00035 struct channel_list_s; 00036 00037 typedef struct mac_api_s mac_api_t; 00038 00039 /** 00040 * Every MAC adapting to Upper layer must implement a function which creates mac_api_t pointer, e.g 'mac_api_t* create_mac_api();' 00041 * In the function external Mac needs to fill necessary function pointers so that Upper layer can use it. 00042 * For Nanostack to work, following (mlme/mcps) request functions are mandatory: 00043 * - mcps-data 00044 * - scan 00045 * - start 00046 * - poll 00047 * - get 00048 * - set 00049 * - reset 00050 * - (purge) 00051 * Also indication and confirm callbacks for above are needed plus 00052 * - beacon notify 00053 * - comm status 00054 * 00055 * \return mac_api_t Ownership of newly created object 00056 */ 00057 00058 /*! 00059 * \enum mlme_primitive 00060 * \brief Enum for MLME primitive types. 00061 */ 00062 typedef enum { 00063 MLME_ASSOCIATE, 00064 MLME_DISASSOCIATE, 00065 MLME_BEACON_NOTIFY, 00066 MLME_GET, 00067 MLME_GTS, 00068 MLME_ORPHAN, 00069 MLME_RESET, 00070 MLME_RX_ENABLE, 00071 MLME_SCAN, 00072 MLME_COMM_STATUS, 00073 MLME_SET, 00074 MLME_START, 00075 MLME_SYNC, 00076 MLME_SYNC_LOSS, 00077 MLME_POLL 00078 } mlme_primitive; 00079 00080 /** 00081 * \struct mac_description_storage_size_t 00082 * \brief Container for MAC storage sizes. 00083 */ 00084 typedef struct mac_description_storage_size_s { 00085 uint8_t device_decription_table_size; /**< MAC Device description list size */ 00086 uint8_t key_description_table_size; /**< MAC Key description list size */ 00087 uint8_t key_lookup_size; /**< Key description key lookup list size */ 00088 uint8_t key_usage_size; /**< Key description key usage list size */ 00089 } mac_description_storage_size_t; 00090 00091 /*! 00092 * \enum mac_extended_address_type 00093 * \brief Enum for MAC extended address types. 00094 */ 00095 typedef enum mac_extended_address_type { 00096 MAC_EXTENDED_READ_ONLY, /** EUID64 which is unique */ 00097 MAC_EXTENDED_DYNAMIC /** Configured MAC 64-bit address to RAM and Radio */ 00098 } mac_extended_address_type; 00099 //External MAC functions 00100 00101 /** 00102 * @brief mlme_associate_response 00103 * @param api API to handle the request 00104 * @param data MLME-ASSOCIATE.response specific values 00105 */ 00106 //typedef void mlme_associate_response(const mac_api_t* api, mlme_associate_resp_t *data); 00107 00108 //typedef void mlme_orphan_response(const mac_api_t* api, mlme_orphan_resp_t *data); 00109 00110 /** 00111 * @brief mlme_request 00112 * @param api API to handle the request 00113 * @param id The identifier of the MLME primitive 00114 * @param data Primitive specific data (\see mlme.h) 00115 */ 00116 typedef void mlme_request(const mac_api_t *api, mlme_primitive id, const void *data); 00117 00118 /** 00119 * @brief mcps_request MCPS_DATA request call 00120 * @param api API to handle the request 00121 * @param data MCPS-DATA.request specific values 00122 */ 00123 typedef void mcps_data_request(const mac_api_t *api, const mcps_data_req_t *data); 00124 00125 /** 00126 * @brief mcps_request MCPS_DATA with IE extions request call 00127 * @param api API to handle the request 00128 * @param data MCPS-DATA.request specific values 00129 * @param ie_ext Information element list to MCPS-DATA.request 00130 * @param asynch_channel_list Optional channel list to asynch data request. Give NULL when normal data request. 00131 * 00132 * Asynch data request is mac standard extension. asynch_channel_list include channel mask which channel message is requested to send. 00133 */ 00134 typedef void mcps_data_request_ext(const mac_api_t *api, const mcps_data_req_t *data, const mcps_data_req_ie_list_t *ie_ext, const struct channel_list_s *asynch_channel_list); 00135 00136 /** 00137 * @brief mcps_purge_request MCPS_PURGE request call 00138 * @param api API to handle the request 00139 * @param data MCPS-PURGE.request specific values 00140 * @return 0 in case of success, non-zero otherwise 00141 */ 00142 typedef uint8_t mcps_purge_request(const mac_api_t *api, const mcps_purge_t *data); 00143 00144 //Upper layer specific callback functions (will also be set by Upper layer after mac_api_t has been created and given to it) 00145 00146 /** 00147 * @brief mcps_data_confirm MCPS-DATA confirm is called as a response to MCPS-DATA request 00148 * @param api The API which handled the response 00149 * @param data MCPS-DATA.confirm specific values 00150 */ 00151 typedef void mcps_data_confirm(const mac_api_t *api, const mcps_data_conf_t *data); 00152 00153 /** 00154 * @brief mcps_data_confirm_ext MCPS-DATA confirm with Enhanced ACK payload is called as a response to MCPS-DATA request 00155 * @param api The API which handled the response 00156 * @param data MCPS-DATA.confirm specific values 00157 * @param conf_data Possible Confirmation Data 00158 */ 00159 typedef void mcps_data_confirm_ext(const mac_api_t *api, const mcps_data_conf_t *data, const mcps_data_conf_payload_t *conf_data); 00160 00161 /** 00162 * @brief mcps_data_indication MCPS-DATA indication is called when MAC layer has received data 00163 * @param api The API which handled the response 00164 * @param data MCPS-DATA.indication specific values 00165 */ 00166 typedef void mcps_data_indication(const mac_api_t *api, const mcps_data_ind_t *data); 00167 00168 /** 00169 * @brief mcps_data_indication MCPS-DATA indication is called when MAC layer has received data 00170 * @param api The API which handled the response 00171 * @param data MCPS-DATA.indication specific values 00172 * @param ie_ext Information element list 00173 */ 00174 typedef void mcps_data_indication_ext(const mac_api_t *api, const mcps_data_ind_t *data, const mcps_data_ie_list_t *ie_ext); 00175 00176 /** 00177 * @brief mcps_ack_data_req_ext Callback for request IE elements and payload to enhanced ACK 00178 * @param api The API which handled the response 00179 * @param data Pointer where MAC user set Payload and IE element pointers and length 00180 * @param rssi Signal strength for received packet 00181 * @param lqi Link quality to neighbor 00182 */ 00183 typedef void mcps_ack_data_req_ext(const mac_api_t *api, mcps_ack_data_payload_t *data, int8_t rssi, uint8_t lqi); 00184 00185 00186 /** 00187 * @brief mcps_purge_confirm MCPS-PURGE confirm is called as a response to MCPS-PURGE request 00188 * @param api The API which handled the request 00189 * @param data MCPS-PURGE.confirm specific values 00190 */ 00191 typedef void mcps_purge_confirm(const mac_api_t *api, mcps_purge_conf_t *data); 00192 00193 /** 00194 * @brief mlme_confirm One of the MLME primitive confirm callbacks 00195 * @param api API which handled the response 00196 * @param id The identifier of the MLME primitive 00197 * @param data Primitive specific data (\see mlme.h) 00198 */ 00199 typedef void mlme_confirm(const mac_api_t *api, mlme_primitive id, const void *data); 00200 00201 /** 00202 * @brief mlme_indication One of the 00203 * @param api API which handled the response 00204 * @param id The identifier of the MLME primitive 00205 * @param data Primitive specific data (\see mlme.h) 00206 */ 00207 typedef void mlme_indication(const mac_api_t *api, mlme_primitive id, const void *data); 00208 00209 /** 00210 * @brief Set extended address from MAC 00211 * @param api API to handle the request 00212 * @param mac64 pointer 00213 */ 00214 typedef int8_t mac_ext_mac64_address_set(const mac_api_t *api, const uint8_t *mac64); 00215 00216 /** 00217 * @brief Read extended address from MAC 00218 * @param api API to handle the request 00219 * @param mac64_buf Pointer where mac extended address can be written 00220 */ 00221 typedef int8_t mac_ext_mac64_address_get(const mac_api_t *api, mac_extended_address_type type, uint8_t *mac64_buf); 00222 00223 /** 00224 * @brief Read MAC security description storage sizes from MAC 00225 * @param api API to handle the request 00226 * @param buffer Pointer where supported sizes can be written 00227 */ 00228 typedef int8_t mac_storage_decription_sizes_get(const mac_api_t *api, mac_description_storage_size_t *buffer); 00229 00230 /** 00231 * @brief mac_api_initialize Initialises MAC layer into use, callbacks must be non-NULL. 00232 * @param api mac_api_t pointer, which is created by application. 00233 * @param data_conf_cb Upper layer function to handle MCPS confirmations 00234 * @param data_ind_cb Upper layer function to handle MCPS indications 00235 * @param mlme_conf_cb Upper layer function to handle MLME confirmations 00236 * @param mlme_ind_cb Upper layer function to handle MLME indications 00237 * @param parent_id Upper layer id, which is used in confirmation and indication callbacks 00238 * @return -1 if error, -2 if OOM, 0 otherwise 00239 */ 00240 typedef int8_t mac_api_initialize(mac_api_t *api, mcps_data_confirm *data_conf_cb, 00241 mcps_data_indication *data_ind_cb, mcps_purge_confirm *purge_conf_cb, mlme_confirm *mlme_conf_cb, 00242 mlme_indication *mlme_ind_cb, int8_t parent_id); 00243 00244 /** 00245 * @brief mac_api_enable_mcps_ext Initialises MAC 2015 extension for MCPS layer into use, callbacks must be non-NULL. 00246 * @param api mac_api_t pointer, which is created by application. 00247 * @param data_ind_cb Upper layer function to handle MCPS indications 00248 * @param data_cnf_cb Upper layer function to handle MCPS confirmation 00249 * @param ack_data_req_cb Upper layer function for set Enhanced ACK payload 00250 * @return -1 if error, -2 if OOM, 0 otherwise 00251 */ 00252 typedef int8_t mac_api_enable_mcps_ext(mac_api_t *api, 00253 mcps_data_indication_ext *data_ind_cb, 00254 mcps_data_confirm_ext *data_cnf_cb, 00255 mcps_ack_data_req_ext *ack_data_req_cb); 00256 00257 /** 00258 * \brief Struct mac_api_s defines functions for two-way communications between external MAC and Upper layer. 00259 * Application creates mac_api_t object by calling external MAC's creator function. 00260 * Then object is passed to Upper layer which then initializes it's own callback functions. 00261 * Then MAC is operated by Upper layer by calling MLME or MCPS primitive functions. 00262 */ 00263 struct mac_api_s { 00264 mac_api_initialize *mac_initialize; /**< MAC initialize function to use */ 00265 mac_api_enable_mcps_ext *mac_mcps_extension_enable; /**< MAC MCPS IE extension enable function, optional feature */ 00266 //External MAC callbacks 00267 mlme_request *mlme_req; /**< MAC MLME request function to use */ 00268 mcps_data_request *mcps_data_req; /**< MAC MCPS data request function to use */ 00269 mcps_data_request_ext *mcps_data_req_ext; /**< MAC MCPS data request with Information element extension function to use */ 00270 mcps_purge_request *mcps_purge_req; /**< MAC MCPS purge request function to use */ 00271 00272 //Upper layer callbacksMLME_ASSOCIATE 00273 mcps_data_confirm *data_conf_cb; /**< MAC MCPS data confirm callback function */ 00274 mcps_data_confirm_ext *data_conf_ext_cb; /**< MAC MCPS data confirm with payload callback function */ 00275 mcps_data_indication *data_ind_cb; /**< MAC MCPS data indication callback function */ 00276 mcps_data_indication_ext *data_ind_ext_cb; /**< MAC MCPS data indication with IE extension's callback function */ 00277 mcps_ack_data_req_ext *enhanced_ack_data_req_cb; /**< Enhanced ACK IE element and payload request from MAC user */ 00278 mcps_purge_confirm *purge_conf_cb; /**< MAC MCPS purge confirm callback function */ 00279 mlme_confirm *mlme_conf_cb; /**< MAC MLME confirm callback function */ 00280 mlme_indication *mlme_ind_cb; /**< MAC MLME indication callback function */ 00281 mac_ext_mac64_address_set *mac64_set; /**< MAC extension function to set mac64 address */ 00282 mac_ext_mac64_address_get *mac64_get; /**< MAC extension function to get mac64 address */ 00283 mac_storage_decription_sizes_get *mac_storage_sizes_get; /**< Getter function to query data storage sizes from MAC */ 00284 00285 int8_t parent_id; /**< Upper layer id */ 00286 uint16_t phyMTU; /**< Maximum Transmission Unit(MTU) used by MAC*/ 00287 }; 00288 00289 /** 00290 * \struct mac_statistics_t 00291 * \brief MAC statistics structure. 00292 */ 00293 typedef struct mac_statistics_s { 00294 uint16_t mac_tx_queue_size; /**< MAC TX queue current size. */ 00295 uint16_t mac_tx_queue_peak; /**< MAC TX queue peak size. */ 00296 uint32_t mac_rx_count; /**< MAC RX packet count. */ 00297 uint32_t mac_tx_count; /**< MAC TX packet count. */ 00298 uint32_t mac_bc_rx_count; /**< MAC broadcast RX packet count. */ 00299 uint32_t mac_bc_tx_count; /**< MAC broadcast TX packet count. */ 00300 uint32_t mac_beacon_rx_count; /**< MAC Beacon RX packet count. */ 00301 uint32_t mac_beacon_tx_count; /**< MAC Beacon TX packet count. */ 00302 uint32_t mac_rx_drop_count; /**< MAC RX packet drop count. */ 00303 uint32_t mac_tx_bytes; /**< MAC TX bytes count. */ 00304 uint32_t mac_rx_bytes; /**< MAC RX bytes count. */ 00305 uint32_t mac_tx_failed_count; /**< MAC TX failed count. */ 00306 uint32_t mac_retry_count; /**< MAC TX retry count. */ 00307 uint32_t mac_cca_attempts_count; /**< MAC CCA attempts count. */ 00308 uint32_t mac_failed_cca_count; /**< MAC failed CCA count. */ 00309 } mac_statistics_t; 00310 00311 #ifdef __cplusplus 00312 } 00313 #endif 00314 00315 #endif // MAC_API_H
Generated on Tue Jul 12 2022 13:54:31 by
