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