arm_hal_phy.h

00001 /*
00002  * Copyright (c) 2014-2015 ARM Limited. All rights reserved.
00003  *
00004  * SPDX-License-Identifier: LicenseRef-PBL
00005  *
00006  * Licensed under the Permissive Binary License, Version 1.0 (the "License"); you may not use this file except in compliance with the License.
00007  * You may obtain a copy of the License at
00008  *
00009  * https://www.mbed.com/licenses/PBL-1.0
00010  *
00011  * See the License for the specific language governing permissions and limitations under the License.
00012  *
00013  */
00014 
00015 /**
00016  * \file arm_hal_phy.h
00017  * \brief PHY device driver API.
00018  */
00019 
00020 #ifndef ARM_HAL_PHY_H_
00021 #define ARM_HAL_PHY_H_
00022 
00023 #include "ns_types.h"
00024 
00025 #ifdef __cplusplus
00026 extern "C" {
00027 #endif
00028 
00029 /** Interface states */
00030 typedef enum {
00031     PHY_INTERFACE_RESET,            /**< Reset PHY driver and set to idle. */
00032     PHY_INTERFACE_DOWN,             /**< Disable PHY interface driver (RF radio disable). */
00033     PHY_INTERFACE_UP,               /**< Enable PHY interface driver (RF radio receiver ON). */
00034     PHY_INTERFACE_RX_ENERGY_STATE,  /**< Enable wireless interface ED scan mode. */
00035     PHY_INTERFACE_SNIFFER_STATE     /**< Enable sniffer mode. */
00036 } phy_interface_state_e;
00037 
00038 /** TX process return codes */
00039 typedef enum {
00040     PHY_LINK_TX_DONE,           /**< TX process ready and ACK RX. */
00041     PHY_LINK_TX_DONE_PENDING,   /**< TX process OK with ACK pending flag. */
00042     PHY_LINK_TX_SUCCESS,        /**< MAC TX complete. MAC will a make decision to enter wait ACK or TX done state. */
00043     PHY_LINK_TX_FAIL,           /**< Link TX process fail. */
00044     PHY_LINK_CCA_FAIL,          /**< RF link CCA process fail. */
00045 } phy_link_tx_status_e;
00046 
00047 /** Extension types */
00048 typedef enum {
00049     PHY_EXTENSION_CTRL_PENDING_BIT, /**< Control MAC pending bit for indirect data. */
00050     PHY_EXTENSION_READ_LAST_ACK_PENDING_STATUS, /**< Read status if the last ACK is still pending. */
00051     PHY_EXTENSION_SET_CHANNEL,  /**< Net library channel set. */
00052     PHY_EXTENSION_READ_CHANNEL_ENERGY, /**< RF interface ED scan energy read. */
00053     PHY_EXTENSION_READ_LINK_STATUS, /**< Net library could read link status. */
00054     PHY_EXTENSION_CONVERT_SIGNAL_INFO, /**< Convert signal info. */
00055 } phy_extension_type_e;
00056 
00057 /** Address types */
00058 typedef enum {
00059     PHY_MAC_48BIT, /**< IPv4/IPv6/BLE link layer address for Ethernet. This is optional. */
00060     PHY_MAC_64BIT, /**< RF/PLC link layer address. */
00061     PHY_MAC_16BIT, /**< RF interface short address. */
00062     PHY_MAC_PANID, /**< RF interface 16-Bit PAN-ID. */
00063 } phy_address_type_e;
00064 
00065 /** PHY types */
00066 typedef enum phy_link_type_e {
00067     PHY_LINK_ETHERNET_TYPE,         /**< Standard IEEE 802 Ethernet. */
00068     PHY_LINK_15_4_2_4GHZ_TYPE,      /**< Standard 802.15.4 2.4GHz radio. */
00069     PHY_LINK_15_4_SUBGHZ_TYPE,      /**< Standard 802.15.4 subGHz radio 868 /915MHz. */
00070     PHY_LINK_TUN,                   /**< Tunnel interface for Linux TUN, RF network driver over serial bus or just basic application to application data flow. */
00071     PHY_LINK_SLIP,                  /**< Generic SLIP driver which just forward SLIP payload */
00072 } phy_link_type_e;
00073 
00074 /** Data layers */
00075 typedef enum data_protocol_e {
00076     LOCAL_SOCKET_DATA = 0,          /**< 6LoWPAN library local socket data. */
00077     INTERFACE_DATA = 1,             /**< 6LoWPAN library interface internal used protocol. */
00078     PHY_LAYER_PAYLOAD = 2,          /**< PHY layer data selection or handler. */
00079     IPV6_DATAGRAM = 3,              /**< IP layer data or TUN driver request data. */
00080     UNKNOWN_PROTOCOL = 4            /**< Non-supported protocol ID. */
00081 } data_protocol_e;
00082 
00083 /** Requested data layer */
00084 typedef enum driver_data_request_e {
00085     PHY_LAYER_PAYLOAD_DATA_FLOW,    /**< PHY layer data. */
00086     IPV6_DATAGRAMS_DATA_FLOW,       /**< IP layer data or TUN driver request data. */
00087 } driver_data_request_e;
00088 
00089 /** \brief Signal info types.
00090  *
00091  * Types of signal quality indication desired by various link protocols. Some are
00092  * really statistical, but a driver should ideally be able to create an estimate
00093  * based on its LQI/DBM numbers, for example to bootstrap a statistic calculation.
00094  */
00095 typedef enum phy_signal_info_type_e {
00096     PHY_SIGNAL_INFO_ETX,            /**< Expected transmissions, unsigned 16-bit fixed-point ETX*128 [1..512], for example Zigbee IP + RFC 6719. */
00097     PHY_SIGNAL_INFO_IDR,            /**< Inverse Delivery Ratio, unsigned 16-bit fixed-point IDR*32*256 [1..8], for example MLE draft 06. */
00098     PHY_SIGNAL_INFO_LINK_MARGIN,    /**< Link margin, unsigned 16-bit fixed-point dB*256, [0..255], for example Thread routing draft. */
00099 } phy_signal_info_type_e;
00100 
00101 /** Signal level info */
00102 typedef struct phy_signal_info_s {
00103     phy_signal_info_type_e type;    /**< Signal info type desired. */
00104     uint8_t lqi;                    /**< Quality passed to arm_net_phy_rx. */
00105     int8_t dbm;                     /**< Strength passed to arm_net_phy_rx. */
00106     uint16_t result;                /**< Resulting signal information. */
00107 } phy_signal_info_s;
00108 
00109 /** PHY modulation scheme */
00110 typedef enum phy_modulation_e
00111 {
00112     M_OFDM,     ///< QFDM
00113     M_OQPSK,    ///< OQPSK
00114     M_BPSK,     ///< BPSK
00115     M_GFSK,     ///< GFSK
00116     M_UNDEFINED ///< UNDEFINED
00117 } phy_modulation_e;
00118 
00119 /** Channel page numbers */
00120 typedef enum
00121 {
00122     CHANNEL_PAGE_0 = 0,     ///< Page 0
00123     CHANNEL_PAGE_1 = 1,     ///< Page 1
00124     CHANNEL_PAGE_2 = 2,     ///< Page 2
00125     CHANNEL_PAGE_3 = 3,     ///< Page 3
00126     CHANNEL_PAGE_4 = 4,     ///< Page 4
00127     CHANNEL_PAGE_5 = 5,     ///< Page 5
00128     CHANNEL_PAGE_6 = 6,     ///< Page 6
00129     CHANNEL_PAGE_9 = 9,     ///< Page 9
00130     CHANNEL_PAGE_10 = 10    ///< Page 10
00131 } channel_page_e;
00132 
00133 /** Channel configuration */
00134 typedef struct phy_rf_channel_configuration_s
00135 {
00136     uint32_t channel_0_center_frequency;    ///< Center frequency
00137     uint32_t channel_spacing;               ///< Channel spacing
00138     uint32_t datarate;                      ///< Data rate
00139     uint16_t number_of_channels;            ///< Number of channels
00140     phy_modulation_e modulation;            ///< Modulation scheme
00141 } phy_rf_channel_configuration_s;
00142 
00143 /** Channel page configuration */
00144 typedef struct phy_device_channel_page_s
00145 {
00146     channel_page_e channel_page;            ///< Channel page
00147     const phy_rf_channel_configuration_s *rf_channel_configuration; ///< Pointer to channel configuration
00148 } phy_device_channel_page_s;
00149 
00150 /** Virtual data request */
00151 typedef struct virtual_data_req_s {
00152     uint16_t parameter_length;
00153     uint8_t *parameters;
00154     uint16_t msduLength;
00155     const uint8_t *msdu;
00156 } virtual_data_req_t;
00157 
00158 /**
00159  * @brief arm_net_phy_rx RX callback set by upper layer. Called when data is received
00160  * @param data_ptr Data received
00161  * @param data_len Length of the data received
00162  * @param link_quality Link quality
00163  * @param dbm Power ratio in decibels
00164  * @param driver_id ID of driver which received data
00165  * @return 0 if success, error otherwise
00166  */
00167 typedef int8_t arm_net_phy_rx_fn(const uint8_t *data_ptr, uint16_t data_len, uint8_t link_quality, int8_t dbm, int8_t driver_id);
00168 
00169 /**
00170  * @brief arm_net_phy_tx_done TX done callback set by upper layer. Called when tx sent by upper layer has been handled
00171  * @param driver_id Id of the driver which handled TX request
00172  * @param tx_handle Handle of the TX
00173  * @param status Status code of the TX handling result
00174  * @param cca_retry Number of CCA retries done during handling
00175  * @param tx_retry Number of TX retries done during handling
00176  * @return 0 if success, error otherwise
00177  */
00178 typedef int8_t arm_net_phy_tx_done_fn(int8_t driver_id, uint8_t tx_handle, phy_link_tx_status_e status, uint8_t cca_retry, uint8_t tx_retry);
00179 
00180 /**
00181  * @brief arm_net_virtual_rx RX callback set by user of serial MAC. Called when virtual RF has received data.
00182  * @param data_ptr Data received
00183  * @param data_len Length of the data received
00184  * @param driver_id ID of driver which received data
00185  * @return 0 if success, error otherwise
00186  */
00187 typedef int8_t arm_net_virtual_rx_fn(const uint8_t *data_ptr, uint16_t data_len,int8_t driver_id);
00188 
00189 /**
00190  * @brief arm_net_virtual_tx TX callback set by serial MAC. Used to send data.
00191  * @param data_req Data to be sent
00192  * @param driver_id Id of the driver to be used.
00193  * @return 0 if success, error otherwise
00194  */
00195 typedef int8_t arm_net_virtual_tx_fn(const virtual_data_req_t *data_req,int8_t driver_id);
00196 
00197 /** Device driver structure */
00198 typedef struct phy_device_driver_s
00199 {
00200     phy_link_type_e link_type;                                      /**< Define driver types. */
00201     driver_data_request_e data_request_layer;                       /**< Define interface data OUT protocol. */
00202     uint8_t *PHY_MAC;                                               /**< Pointer to 64-bit or 48-bit MAC address. */
00203     uint16_t phy_MTU;                                               /**< Define MAX PHY layer MTU size. */
00204     char *driver_description;                                       /**< Short driver platform description. Needs to end with zero. */
00205     uint8_t phy_tail_length;                                        /**< Define PHY driver needed TAIL Length. */
00206     uint8_t phy_header_length;                                      /**< Define PHY driver needed header length before PDU. */
00207     int8_t (*state_control)(phy_interface_state_e, uint8_t);        /**< Function pointer for control PHY driver state. */
00208     int8_t (*tx)(uint8_t *, uint16_t, uint8_t, data_protocol_e);    /**< Function pointer for PHY driver write operation. */
00209     int8_t (*address_write)(phy_address_type_e , uint8_t *);        /**< Function pointer for PHY driver address write. */
00210     int8_t (*extension)(phy_extension_type_e, uint8_t *);           /**< Function pointer for PHY driver extension control. */
00211     const phy_device_channel_page_s *phy_channel_pages;             /**< Pointer to channel page list */
00212 
00213     //Upper layer callbacks, set with arm_net_phy_register();
00214     arm_net_phy_rx_fn *phy_rx_cb;                                   /**< PHY RX callback. Initialized by \ref arm_net_phy_register(). */
00215     arm_net_phy_tx_done_fn *phy_tx_done_cb;                         /**< Transmission done callback. Initialized by \ref arm_net_phy_register(). */
00216     //Virtual upper data rx
00217     arm_net_virtual_rx_fn *arm_net_virtual_rx_cb;                   /**< Virtual RX callback. Initialized by \ref arm_net_phy_register(). */
00218     arm_net_virtual_tx_fn *arm_net_virtual_tx_cb;                   /**< Virtual TX callback. Initialized by \ref arm_net_phy_register(). */
00219     uint16_t tunnel_type; /**< Tun driver type. */
00220 } phy_device_driver_s;
00221 
00222 
00223 /**
00224  * \brief This function registers the device driver to stack.
00225  *
00226  * \param phy_driver A pointer to device driver structure.
00227  *
00228  * \return >= 0 Device driver ID.
00229  * \return < 0 Means register fail.
00230  *
00231  */
00232 extern int8_t arm_net_phy_register(phy_device_driver_s *phy_driver);
00233 
00234 
00235 /**
00236  * \brief Set driver mac64 address.
00237  *
00238  * \param MAC A pointer to new mac64 address which is copied to old one.
00239  * \param  id driver id
00240  *
00241  * \return >= 0 SET OK.
00242  * \return < 0 Means register fail.
00243  *
00244  */
00245 extern int8_t arm_net_phy_mac64_set(uint8_t *MAC, int8_t id);
00246 
00247 /**
00248  * \brief Get driver mac64 address.
00249  *
00250  * \param  id driver id
00251  *
00252  * \return > 0 Return pointer to MAC.
00253  * \return NULL.
00254  *
00255  */
00256 extern uint8_t *arm_net_phy_mac64_get(int8_t id);
00257 
00258 /**
00259  * \brief Get driver link type.
00260  *
00261  * \param  id driver id
00262  *
00263  * \return driver link type.
00264  *
00265  */
00266 extern int arm_net_phy_rf_type(int8_t id);
00267 
00268 /**
00269  * \brief Get driver link type MTU size.
00270  *
00271  * \param  id driver id
00272  *
00273  * \return size of MTU.
00274  *
00275  */
00276 extern uint16_t arm_net_phy_mtu_size(int8_t id);
00277 
00278 /**
00279  * \brief Unregister the driver from storage.
00280  *
00281  * \param driver_id driver id
00282  *
00283  */
00284 extern void arm_net_phy_unregister(int8_t driver_id);
00285 
00286 #ifdef __cplusplus
00287 }
00288 #endif
00289 #endif /* ARM_HAL_PHY_H_ */