ethernet_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 /** \file ethernet_mac_api.h
00019  * \brief Ethernet MAC API
00020  */
00021 
00022 #ifndef ETHERNET_MAC_API_H
00023 #define ETHERNET_MAC_API_H
00024 
00025 #include <inttypes.h>
00026 #include "platform/arm_hal_phy.h"
00027 
00028 #ifdef __cplusplus
00029 extern "C" {
00030 #endif
00031 
00032 #define ETHERTYPE_IPV4              0x0800  /**< ethernet type for IPv4 */
00033 #define ETHERTYPE_ARP               0x0806  /**< ethernet type for ARP */
00034 #define ETHERTYPE_802_1Q_TAG        0x8100  /**< ethernet type for 802_1Q */
00035 #define ETHERTYPE_IPV6              0x86dd  /**< ethernet type for IPv6 */
00036 
00037 typedef struct eth_mac_api_s eth_mac_api_t;
00038 
00039 /**
00040   * \brief Struct eth_data_conf_s defines arguments for data confirm message
00041   */
00042 typedef struct eth_data_conf_s {
00043     uint8_t msduHandle;         /**< Handle associated with MSDU */
00044     uint8_t status;             /**< Status of the last transaction */
00045 } eth_data_conf_t;
00046 
00047 /**
00048   * \brief Struct eth_data_req_s defines arguments for data request message
00049   */
00050 typedef struct eth_data_req_s {
00051     uint16_t msduLength;        /**< Service data unit length */
00052     uint8_t *msdu;              /**< Service data unit */
00053     uint8_t *srcAddress;        /**< Source address */
00054     uint8_t *dstAddress;        /**< Destination address */
00055     uint16_t etehernet_type;    /**< Ethernet type */
00056     uint8_t msduHandle;         /**< Handle associated with MSDU */
00057 } eth_data_req_t;
00058 
00059 /**
00060   * \brief Struct eth_data_ind_s defines arguments for data indication message
00061   */
00062 typedef struct eth_data_ind_s {
00063     uint16_t msduLength;        /**< Service data unit length */
00064     uint8_t *msdu;              /**< Service data unit */
00065     uint8_t srcAddress[6];      /**< Source address */
00066     uint8_t dstAddress[6];      /**< Destination address */
00067     uint16_t etehernet_type;    /**< Ethernet type */
00068     uint8_t link_quality;       /**< Link quality */
00069     int8_t dbm;                 /**< measured dBm */
00070 } eth_data_ind_t;
00071 
00072 /**
00073  * @brief Creates ethernet MAC API instance which will use driver given
00074  * @param driver_id Ethernet driver id. Must be valid
00075  * @return New MAC instance if successful, NULL otherwise
00076  */
00077 extern eth_mac_api_t *ethernet_mac_create(int8_t driver_id);
00078 
00079 /**
00080  * @brief Destroy ethernet MAC API instance
00081  * Call this only for freeing all allocated memory and when mac is total unused
00082  *
00083  * @param mac_api Removed mac class pointer
00084  * @return -1 Unknow MAC
00085  * @return 0 Mac class is removed
00086  */
00087 extern int8_t ethernet_mac_destroy(eth_mac_api_t *mac_api);
00088 
00089 /**
00090  * @brief data_request data request call
00091  * @param api API to handle the request
00092  * @param data Data containing request parameters
00093  */
00094 typedef void eth_mac_data_request(const eth_mac_api_t *api, const eth_data_req_t *data);
00095 
00096 /**
00097  * @brief data_confirm confirm is called as a response to data_request
00098  * @param api The API which handled the request
00099  * @param data Data containing confirm parameters
00100  */
00101 typedef void eth_mac_data_confirm(const eth_mac_api_t *api, const eth_data_conf_t *data);
00102 
00103 /**
00104  * @brief data_indication Data indication is called when MAC layer has received data
00105  * @param api The API which handled the response
00106  * @param data Data containing indication parameters
00107  */
00108 typedef void eth_mac_data_indication(const eth_mac_api_t *api, const eth_data_ind_t *data);
00109 
00110 /**
00111  * @brief Set 48 bit address from MAC
00112  * @param api API to handle the request
00113  * @param mac48 Pointer having mac address to be set
00114  * @return 0 if successful, -1 otherwise
00115  */
00116 typedef int8_t eth_mac_mac48_address_set(const eth_mac_api_t *api, const uint8_t *mac48);
00117 
00118 /**
00119  * @brief Read 48 bit address from MAC
00120  * @param api API to handle the request
00121  * @param mac48_buf Pointer where mac address can be written
00122  * @return 0 if successful, -1 otherwise
00123  */
00124 typedef int8_t eth_mac_mac48_address_get(const eth_mac_api_t *api, uint8_t *mac48_buf);
00125 
00126 /**
00127  * @brief Set 64 bit interface identifier from IID64
00128  * @param api API to handle the request
00129  * @param iid64 Pointer having iid64 to be set
00130  * @return 0 if successful, -1 otherwise
00131  */
00132 typedef int8_t eth_mac_iid64_address_set(const eth_mac_api_t *api, const uint8_t *iid64);
00133 
00134 /**
00135  * @brief Read 64 bit interface identifier
00136  * @param api API to handle the request
00137  * @param iid64_buf Pointer where IID64 can be written
00138  * @return 0 if successful, -1 otherwise
00139  */
00140 typedef int8_t eth_mac_iid64_address_get(const eth_mac_api_t *api, uint8_t *iid64_buf);
00141 
00142 /**
00143  * @brief Upper layer will call this function, when MAC is taken into use
00144  * @param api API to initialize
00145  * @param conf_cb Callback for confirm type of messages
00146  * @param ind_cb Callback for indication type of messages
00147  * @param parent_id Upper layer identifier
00148  * @return 0 if success; -1 if api is NULL or not found
00149  */
00150 typedef int8_t eth_mac_api_initialize(eth_mac_api_t *api, eth_mac_data_confirm *conf_cb,
00151                                       eth_mac_data_indication *ind_cb, uint8_t parent_id);
00152 
00153 /**
00154   * \brief Struct eth_mac_api_s defines functions for two-way communications between ethernet MAC and Upper layer.
00155   */
00156 struct eth_mac_api_s {
00157     eth_mac_api_initialize      *mac_initialize;                /**< Callback function for MAC initialization */
00158 
00159     eth_mac_data_request        *data_req;                      /**< Callback function for data request */
00160     eth_mac_data_confirm        *data_conf_cb;                  /**< Callback function for data confirmation */
00161     eth_mac_data_indication     *data_ind_cb;                   /**< Callback function for data indication */
00162 
00163     eth_mac_mac48_address_set   *mac48_set;                     /**< Setter for MAC address */
00164     eth_mac_mac48_address_get   *mac48_get;                     /**< Getter for MAC address */
00165 
00166     eth_mac_iid64_address_set   *iid64_set;                     /**< Setter for IID64 */
00167     eth_mac_iid64_address_get   *iid64_get;                     /**< Getter for IID64 */
00168 
00169     uint8_t                     parent_id;                      /**< Upper layer ID */
00170     bool                        address_resolution_needed;      /**< Normal ethernet should set this true for tunnel or false for slip */
00171 };
00172 
00173 #ifdef __cplusplus
00174 }
00175 #endif
00176 
00177 #endif // ETHERNET_MAC_API_H
00178