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.
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 */ 00141 typedef void mcps_purge_request(const mac_api_t* api, const mcps_purge_t *data); 00142 00143 //Upper layer specific callback functions (will also be set by Upper layer after mac_api_t has been created and given to it) 00144 00145 /** 00146 * @brief mcps_data_confirm MCPS-DATA confirm is called as a response to MCPS-DATA request 00147 * @param api The API which handled the response 00148 * @param data MCPS-DATA.confirm specific values 00149 */ 00150 typedef void mcps_data_confirm(const mac_api_t* api, const mcps_data_conf_t *data); 00151 00152 /** 00153 * @brief mcps_data_confirm_ext MCPS-DATA confirm with Enhanced ACK payload is called as a response to MCPS-DATA request 00154 * @param api The API which handled the response 00155 * @param data MCPS-DATA.confirm specific values 00156 * @param conf_data Possible Confirmation Data 00157 */ 00158 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); 00159 00160 /** 00161 * @brief mcps_data_indication MCPS-DATA indication is called when MAC layer has received data 00162 * @param api The API which handled the response 00163 * @param data MCPS-DATA.indication specific values 00164 */ 00165 typedef void mcps_data_indication(const mac_api_t* api, const mcps_data_ind_t *data); 00166 00167 /** 00168 * @brief mcps_data_indication MCPS-DATA indication is called when MAC layer has received data 00169 * @param api The API which handled the response 00170 * @param data MCPS-DATA.indication specific values 00171 * @param ie_ext Information element list 00172 */ 00173 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); 00174 00175 /** 00176 * @brief mcps_ack_data_req_ext Callback for request IE elements and payload to enhanced ACK 00177 * @param api The API which handled the response 00178 * @param data Pointer where MAC user set Payload and IE element pointers and length 00179 * @param rssi Signal strength for received packet 00180 * @param lqi Link quality to neighbor 00181 */ 00182 typedef void mcps_ack_data_req_ext(const mac_api_t* api, mcps_ack_data_payload_t *data, int8_t rssi, uint8_t lqi); 00183 00184 00185 /** 00186 * @brief mcps_purge_confirm MCPS-PURGE confirm is called as a response to MCPS-PURGE request 00187 * @param api The API which handled the request 00188 * @param data MCPS-PURGE.confirm specific values 00189 */ 00190 typedef void mcps_purge_confirm( const mac_api_t* api, mcps_purge_conf_t *data ); 00191 00192 /** 00193 * @brief mlme_confirm One of the MLME primitive confirm callbacks 00194 * @param api API which handled the response 00195 * @param id The identifier of the MLME primitive 00196 * @param data Primitive specific data (\see mlme.h) 00197 */ 00198 typedef void mlme_confirm(const mac_api_t* api, mlme_primitive id, const void *data); 00199 00200 /** 00201 * @brief mlme_indication One of the 00202 * @param api API which handled the response 00203 * @param id The identifier of the MLME primitive 00204 * @param data Primitive specific data (\see mlme.h) 00205 */ 00206 typedef void mlme_indication(const mac_api_t* api, mlme_primitive id, const void *data); 00207 00208 /** 00209 * @brief Set extended address from MAC 00210 * @param api API to handle the request 00211 * @param mac64 pointer 00212 */ 00213 typedef int8_t mac_ext_mac64_address_set(const mac_api_t* api, const uint8_t *mac64); 00214 00215 /** 00216 * @brief Read extended address from MAC 00217 * @param api API to handle the request 00218 * @param mac64_buf Pointer where mac extended address can be written 00219 */ 00220 typedef int8_t mac_ext_mac64_address_get(const mac_api_t* api, mac_extended_address_type type, uint8_t *mac64_buf); 00221 00222 /** 00223 * @brief Read MAC security description storage sizes from MAC 00224 * @param api API to handle the request 00225 * @param buffer Pointer where supported sizes can be written 00226 */ 00227 typedef int8_t mac_storage_decription_sizes_get(const mac_api_t* api, mac_description_storage_size_t *buffer); 00228 00229 /** 00230 * @brief mac_api_initialize Initialises MAC layer into use, callbacks must be non-NULL. 00231 * @param api mac_api_t pointer, which is created by application. 00232 * @param data_conf_cb Upper layer function to handle MCPS confirmations 00233 * @param data_ind_cb Upper layer function to handle MCPS indications 00234 * @param mlme_conf_cb Upper layer function to handle MLME confirmations 00235 * @param mlme_ind_cb Upper layer function to handle MLME indications 00236 * @param parent_id Upper layer id, which is used in confirmation and indication callbacks 00237 * @return -1 if error, -2 if OOM, 0 otherwise 00238 */ 00239 typedef int8_t mac_api_initialize(mac_api_t *api, mcps_data_confirm *data_conf_cb, 00240 mcps_data_indication *data_ind_cb, mcps_purge_confirm *purge_conf_cb, mlme_confirm *mlme_conf_cb, 00241 mlme_indication *mlme_ind_cb, int8_t parent_id); 00242 00243 /** 00244 * @brief mac_api_enable_mcps_ext Initialises MAC 2015 extension for MCPS layer into use, callbacks must be non-NULL. 00245 * @param api mac_api_t pointer, which is created by application. 00246 * @param data_ind_cb Upper layer function to handle MCPS indications 00247 * @param data_cnf_cb Upper layer function to handle MCPS confirmation 00248 * @param ack_data_req_cb Upper layer function for set Enhanced ACK payload 00249 * @return -1 if error, -2 if OOM, 0 otherwise 00250 */ 00251 typedef int8_t mac_api_enable_mcps_ext(mac_api_t *api, 00252 mcps_data_indication_ext *data_ind_cb, 00253 mcps_data_confirm_ext *data_cnf_cb, 00254 mcps_ack_data_req_ext *ack_data_req_cb); 00255 00256 /** 00257 * \brief Struct mac_api_s defines functions for two-way communications between external MAC and Upper layer. 00258 * Application creates mac_api_t object by calling external MAC's creator function. 00259 * Then object is passed to Upper layer which then initializes it's own callback functions. 00260 * Then MAC is operated by Upper layer by calling MLME or MCPS primitive functions. 00261 */ 00262 struct mac_api_s { 00263 mac_api_initialize *mac_initialize; /**< MAC initialize function to use */ 00264 mac_api_enable_mcps_ext *mac_mcps_extension_enable; /**< MAC MCPS IE extension enable function, optional feature */ 00265 //External MAC callbacks 00266 mlme_request *mlme_req; /**< MAC MLME request function to use */ 00267 mcps_data_request *mcps_data_req; /**< MAC MCPS data request function to use */ 00268 mcps_data_request_ext *mcps_data_req_ext; /**< MAC MCPS data request with Information element extension function to use */ 00269 mcps_purge_request *mcps_purge_req; /**< MAC MCPS purge request function to use */ 00270 00271 //Upper layer callbacksMLME_ASSOCIATE 00272 mcps_data_confirm *data_conf_cb; /**< MAC MCPS data confirm callback function */ 00273 mcps_data_confirm_ext *data_conf_ext_cb; /**< MAC MCPS data confirm with payload callback function */ 00274 mcps_data_indication *data_ind_cb; /**< MAC MCPS data indication callback function */ 00275 mcps_data_indication_ext *data_ind_ext_cb; /**< MAC MCPS data indication with IE extension's callback function */ 00276 mcps_ack_data_req_ext *enhanced_ack_data_req_cb; /**< Enhanced ACK IE element and payload request from MAC user */ 00277 mcps_purge_confirm *purge_conf_cb; /**< MAC MCPS purge confirm callback function */ 00278 mlme_confirm *mlme_conf_cb; /**< MAC MLME confirm callback function */ 00279 mlme_indication *mlme_ind_cb; /**< MAC MLME indication callback function */ 00280 mac_ext_mac64_address_set *mac64_set; /**< MAC extension function to set mac64 address */ 00281 mac_ext_mac64_address_get *mac64_get; /**< MAC extension function to get mac64 address */ 00282 mac_storage_decription_sizes_get *mac_storage_sizes_get; /**< Getter function to query data storage sizes from MAC */ 00283 00284 int8_t parent_id; /**< Upper layer id */ 00285 uint16_t phyMTU; /**< Maximum Transmission Unit(MTU) used by MAC*/ 00286 }; 00287 00288 /** 00289 * \struct mac_statistics_t 00290 * \brief MAC statistics structure. 00291 */ 00292 typedef struct mac_statistics_s { 00293 uint16_t mac_tx_queue_size; /**< MAC TX queue current size. */ 00294 uint16_t mac_tx_queue_peak; /**< MAC TX queue peak size. */ 00295 uint32_t mac_rx_count; /**< MAC RX packet count. */ 00296 uint32_t mac_tx_count; /**< MAC TX packet count. */ 00297 uint32_t mac_bc_rx_count; /**< MAC broadcast RX packet count. */ 00298 uint32_t mac_bc_tx_count; /**< MAC broadcast TX packet count. */ 00299 uint32_t mac_beacon_rx_count; /**< MAC Beacon RX packet count. */ 00300 uint32_t mac_beacon_tx_count; /**< MAC Beacon TX packet count. */ 00301 uint32_t mac_rx_drop_count; /**< MAC RX packet drop count. */ 00302 uint32_t mac_tx_bytes; /**< MAC TX bytes count. */ 00303 uint32_t mac_rx_bytes; /**< MAC RX bytes count. */ 00304 uint32_t mac_tx_failed_count; /**< MAC TX failed count. */ 00305 uint32_t mac_retry_count; /**< MAC TX retry count. */ 00306 uint32_t mac_cca_attempts_count; /**< MAC CCA attempts count. */ 00307 uint32_t mac_failed_cca_count; /**< MAC failed CCA count. */ 00308 } mac_statistics_t; 00309 00310 #ifdef __cplusplus 00311 } 00312 #endif 00313 00314 #endif // MAC_API_H
Generated on Tue Aug 9 2022 00:37:12 by
