arm_hal_phy.h

00001 /*
00002  * Copyright (c) 2014-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 arm_hal_phy.h
00020  * \brief PHY device driver API.
00021  */
00022 
00023 #ifndef ARM_HAL_PHY_H_
00024 #define ARM_HAL_PHY_H_
00025 
00026 #include "ns_types.h"
00027 
00028 #ifdef __cplusplus
00029 extern "C" {
00030 #endif
00031 
00032 /** PHY_LINK_CCA_PREPARE status definitions */
00033 #define PHY_TX_NOT_ALLOWED  -1      /**< TX not allowed. Do not continue to CCA process. */
00034 #define PHY_TX_ALLOWED      0       /**< TX allowed. Continue to CCA process. */
00035 #define PHY_RESTART_CSMA    1       /**< Restart CSMA-CA timer. CSMA-CA period must be calculated using given backoff time (PHY_EXTENSION_SET_CSMA_PARAMETERS) */
00036 
00037 /** Interface states */
00038 typedef enum {
00039     PHY_INTERFACE_RESET,            /**< Reset PHY driver and set to idle. */
00040     PHY_INTERFACE_DOWN,             /**< Disable PHY interface driver (RF radio disable). */
00041     PHY_INTERFACE_UP,               /**< Enable PHY interface driver (RF radio receiver ON). */
00042     PHY_INTERFACE_RX_ENERGY_STATE,  /**< Enable wireless interface ED scan mode. */
00043     PHY_INTERFACE_SNIFFER_STATE     /**< Enable sniffer mode. */
00044 } phy_interface_state_e;
00045 
00046 /** TX process return codes */
00047 typedef enum {
00048     PHY_LINK_TX_DONE,           /**< TX process ready and ACK RX. */
00049     PHY_LINK_TX_DONE_PENDING,   /**< TX process OK with ACK pending flag. */
00050     PHY_LINK_TX_SUCCESS,        /**< MAC TX complete. MAC will a make decision to enter wait ACK or TX done state. */
00051     PHY_LINK_TX_FAIL,           /**< Link TX process fail. */
00052     PHY_LINK_CCA_FAIL,          /**< RF link CCA process fail. */
00053     PHY_LINK_CCA_OK,            /**< RF link CCA process ok. */
00054     PHY_LINK_CCA_PREPARE,       /**< Prepare for CCA after CSMA-CA: changes to CCA channel and gives permission to TX. See PHY_LINK_CCA_PREPARE status definitions for return values */
00055 } phy_link_tx_status_e;
00056 
00057 /** MAC filtering modes. Set corresponding bit to 1 (1 << MAC_FRAME_VERSION_X) in PHY_EXTENSION_FILTERING_SUPPORT request when PHY can handle the filtering of this frame type.
00058  *  NOTE: Currently MAC supports filtering and Acking only 802.15.4-2015 frames. Any other frame version must be filtered and Acked by PHY with either HW or SW solution. */
00059 typedef enum {
00060     MAC_FRAME_VERSION_2 = 2          /**< 802.15.4-2015 */
00061 } phy_link_filters_e;
00062 
00063 /** Extension types */
00064 typedef enum {
00065     PHY_EXTENSION_CTRL_PENDING_BIT, /**< Control MAC pending bit for indirect data. */
00066     PHY_EXTENSION_READ_LAST_ACK_PENDING_STATUS, /**< Read status if the last ACK is still pending. */
00067     PHY_EXTENSION_SET_CHANNEL,  /**< Net library channel set. */
00068     PHY_EXTENSION_READ_CHANNEL_ENERGY, /**< RF interface ED scan energy read. */
00069     PHY_EXTENSION_READ_LINK_STATUS, /**< Net library could read link status. */
00070     PHY_EXTENSION_CONVERT_SIGNAL_INFO, /**< Convert signal info. */
00071     PHY_EXTENSION_ACCEPT_ANY_BEACON, /**< Set boolean true or false for accept beacon from other Pan-ID than configured. Default value should be false */
00072     PHY_EXTENSION_SET_TX_TIME,  /**< Net library sets transmission time based on global time stamp. Max. 65ms from setting to TX. If TX time is set to zero, it should be ignored.*/
00073     PHY_EXTENSION_READ_RX_TIME, /**< Read the time of last reception based on global micro seconds time stamp. */
00074     PHY_EXTENSION_READ_TX_FINNISH_TIME, /**< Read the time of last finished TX micro seconds based on global time stamp. */
00075     PHY_EXTENSION_DYNAMIC_RF_SUPPORTED, /**< Read status for support Radio driver support for set TX time, CCA and Timestamp read. Also PHY_LINK_CCA_PREPARE tx status must be supported also*/
00076     PHY_EXTENSION_GET_TIMESTAMP, /**<  Read 32-bit constant monotonic time stamp in us */
00077     PHY_EXTENSION_SET_CSMA_PARAMETERS, /**< CSMA parameter's are given by phy_csma_params_t structure remember type cast uint8_t pointer to structure type*/
00078     PHY_EXTENSION_GET_SYMBOLS_PER_SECOND, /**<  Read Symbols per seconds which will help to convert symbol time to real time  */
00079     PHY_EXTENSION_SET_RF_CONFIGURATION,  /**<  Set RF configuration using phy_rf_channel_configuration_s structure */
00080     PHY_EXTENSION_FILTERING_SUPPORT, /**<  Return filtering modes that can be supported by the PHY driver. See phy_link_filters_e */
00081     PHY_EXTENSION_SET_TX_POWER, /**<  Set TX output power which is given as percentage of maximum. 0 is the lowest possible TX power and 100 is the highest possible TX power */
00082     PHY_EXTENSION_SET_CCA_THRESHOLD /**<  Set CCA threshold which is given as percentage of maximum threshold. 0 is the lowest(strictest) possible threshold and 100 is the highest possible threshold */
00083 } phy_extension_type_e;
00084 
00085 /** Address types */
00086 typedef enum {
00087     PHY_MAC_48BIT, /**< IPv4/IPv6/BLE link layer address for Ethernet. This is optional. */
00088     PHY_MAC_64BIT, /**< RF/PLC link layer address. */
00089     PHY_MAC_16BIT, /**< RF interface short address. */
00090     PHY_MAC_PANID, /**< RF interface 16-Bit PAN-ID. */
00091 } phy_address_type_e;
00092 
00093 /** PHY types */
00094 typedef enum phy_link_type_e {
00095     PHY_LINK_ETHERNET_TYPE,         /**< Standard IEEE 802 Ethernet. */
00096     PHY_LINK_15_4_2_4GHZ_TYPE,      /**< Standard 802.15.4 2.4GHz radio. */
00097     PHY_LINK_15_4_SUBGHZ_TYPE,      /**< Standard 802.15.4 subGHz radio 868 /915MHz. */
00098     PHY_LINK_TUN,                   /**< Tunnel interface for Linux TUN, RF network driver over serial bus or just basic application to application data flow. */
00099     PHY_LINK_SLIP,                  /**< Generic SLIP driver which just forward SLIP payload */
00100     PHY_LINK_PPP,                   /**< PPP */
00101 } phy_link_type_e;
00102 
00103 /** Data layers */
00104 typedef enum data_protocol_e {
00105     LOCAL_SOCKET_DATA = 0,          /**< 6LoWPAN library local socket data. */
00106     INTERFACE_DATA = 1,             /**< 6LoWPAN library interface internal used protocol. */
00107     PHY_LAYER_PAYLOAD = 2,          /**< PHY layer data selection or handler. */
00108     IPV6_DATAGRAM = 3,              /**< IP layer data or TUN driver request data. */
00109     UNKNOWN_PROTOCOL = 4            /**< Non-supported protocol ID. */
00110 } data_protocol_e;
00111 
00112 /** Requested data layer */
00113 typedef enum driver_data_request_e {
00114     PHY_LAYER_PAYLOAD_DATA_FLOW,    /**< PHY layer data. */
00115     IPV6_DATAGRAMS_DATA_FLOW,       /**< IP layer data or TUN driver request data. */
00116 } driver_data_request_e;
00117 
00118 /** \brief Signal info types.
00119  *
00120  * Types of signal quality indication desired by various link protocols. Some are
00121  * really statistical, but a driver should ideally be able to create an estimate
00122  * based on its LQI/DBM numbers, for example to bootstrap a statistic calculation.
00123  */
00124 typedef enum phy_signal_info_type_e {
00125     PHY_SIGNAL_INFO_ETX,            /**< Expected transmissions, unsigned 16-bit fixed-point ETX*128 [1..512], for example Zigbee IP + RFC 6719. */
00126     PHY_SIGNAL_INFO_IDR,            /**< Inverse Delivery Ratio, unsigned 16-bit fixed-point IDR*32*256 [1..8], for example MLE draft 06. */
00127     PHY_SIGNAL_INFO_LINK_MARGIN,    /**< Link margin, unsigned 16-bit fixed-point dB*256, [0..255], for example Thread routing draft. */
00128 } phy_signal_info_type_e;
00129 
00130 /** Signal level info */
00131 typedef struct phy_signal_info_s {
00132     phy_signal_info_type_e type;    /**< Signal info type desired. */
00133     uint8_t lqi;                    /**< Quality passed to arm_net_phy_rx. */
00134     int8_t dbm;                     /**< Strength passed to arm_net_phy_rx. */
00135     uint16_t result;                /**< Resulting signal information. */
00136 } phy_signal_info_s;
00137 
00138 /** CSMA-CA parameters */
00139 typedef struct phy_csma_params {
00140     uint32_t backoff_time;           /**< CSMA Backoff us time before start CCA & TX. 0 should disable current backoff*/
00141     bool cca_enabled;                /**< True will affect CCA check false start TX direct after backoff */
00142 } phy_csma_params_t;
00143 
00144 /** PHY modulation scheme */
00145 typedef enum phy_modulation_e {
00146     M_OFDM,     ///< QFDM
00147     M_OQPSK,    ///< OQPSK
00148     M_BPSK,     ///< BPSK
00149     M_GFSK,     ///< GFSK
00150     M_2FSK,     ///< 2FSK
00151     M_UNDEFINED ///< UNDEFINED
00152 } phy_modulation_e;
00153 
00154 /** Channel page numbers */
00155 typedef enum {
00156     CHANNEL_PAGE_0 = 0,     ///< Page 0
00157     CHANNEL_PAGE_1 = 1,     ///< Page 1
00158     CHANNEL_PAGE_2 = 2,     ///< Page 2
00159     CHANNEL_PAGE_3 = 3,     ///< Page 3
00160     CHANNEL_PAGE_4 = 4,     ///< Page 4
00161     CHANNEL_PAGE_5 = 5,     ///< Page 5
00162     CHANNEL_PAGE_6 = 6,     ///< Page 6
00163     CHANNEL_PAGE_9 = 9,     ///< Page 9
00164     CHANNEL_PAGE_10 = 10    ///< Page 10
00165 } channel_page_e;
00166 
00167 /** Modulation index */
00168 typedef enum {
00169     MODULATION_INDEX_0_5 = 0,   ///< Modulation index 0.5
00170     MODULATION_INDEX_1_0 = 1,   ///< Modulation index 1.0
00171     MODULATION_INDEX_UNDEFINED  ///< Modulation index undefined
00172 } phy_modulation_index_e;
00173 
00174 /** Channel configuration */
00175 typedef struct phy_rf_channel_configuration_s {
00176     uint32_t channel_0_center_frequency;        ///< Center frequency
00177     uint32_t channel_spacing;                   ///< Channel spacing
00178     uint32_t datarate;                          ///< Data rate
00179     uint16_t number_of_channels;                ///< Number of channels
00180     phy_modulation_e modulation;                ///< Modulation scheme
00181     phy_modulation_index_e modulation_index;    ///< Modulation index
00182 } phy_rf_channel_configuration_s;
00183 
00184 /** Channel page configuration */
00185 typedef struct phy_device_channel_page_s {
00186     channel_page_e channel_page;            ///< Channel page
00187     const phy_rf_channel_configuration_s *rf_channel_configuration; ///< Pointer to channel configuration
00188 } phy_device_channel_page_s;
00189 
00190 /** PHY statistics */
00191 typedef struct phy_rf_statistics_s {
00192     uint32_t crc_fails;        ///< CRC failures
00193     uint32_t tx_timeouts;      ///< transmission timeouts
00194     uint32_t rx_timeouts;      ///< reception timeouts
00195 } phy_rf_statistics_s;
00196 
00197 /** Virtual data request */
00198 typedef struct virtual_data_req_s {
00199     uint16_t parameter_length;      /**< Length of user specified header. Can be zero. */
00200     uint8_t *parameters;            /**< Pointer to user specified header. Optional */
00201     uint16_t msduLength;            /**< MSDU Length */
00202     const uint8_t *msdu;            /**< MSDU */
00203 } virtual_data_req_t;
00204 
00205 /**
00206  * @brief arm_net_phy_rx RX callback set by upper layer. Called when data is received
00207  * @param data_ptr Data received
00208  * @param data_len Length of the data received
00209  * @param link_quality Link quality
00210  * @param dbm Power ratio in decibels
00211  * @param driver_id ID of driver which received data
00212  * @return 0 if success, error otherwise
00213  */
00214 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);
00215 
00216 /**
00217  * @brief arm_net_phy_tx_done TX done callback set by upper layer. Called when tx sent by upper layer has been handled
00218  * @param driver_id Id of the driver which handled TX request
00219  * @param tx_handle Handle of the TX
00220  * @param status Status code of the TX handling result
00221  * @param cca_retry Number of CCA retries done during handling
00222  * @param tx_retry Number of TX retries done during handling
00223  * @return 0 if success, error otherwise
00224  */
00225 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);
00226 
00227 /**
00228  * @brief arm_net_virtual_rx RX callback set by user of serial MAC. Called when virtual RF has received data.
00229  * @param data_ptr Data received
00230  * @param data_len Length of the data received
00231  * @param driver_id ID of driver which received data
00232  * @return 0 if success, error otherwise
00233  */
00234 typedef int8_t arm_net_virtual_rx_fn(const uint8_t *data_ptr, uint16_t data_len, int8_t driver_id);
00235 
00236 /**
00237  * @brief arm_net_virtual_tx TX callback set by serial MAC. Used to send data.
00238  * @param data_req Data to be sent
00239  * @param driver_id Id of the driver to be used.
00240  * @return 0 if success, error otherwise
00241  */
00242 typedef int8_t arm_net_virtual_tx_fn(const virtual_data_req_t *data_req, int8_t driver_id);
00243 
00244 /**
00245  * @brief arm_net_virtual_config Configuration receive callback set by upper layer. Used to receive internal configuration parameters.
00246  * @param driver_id Id of the driver to be used.
00247  * @param data Pointer to received configuration data.
00248  * @param length Length of the configuration data.
00249  * @return 0 if success, error otherwise
00250  */
00251 typedef int8_t arm_net_virtual_config_rx_fn(int8_t driver_id, const uint8_t *data, uint16_t length);
00252 
00253 /**
00254  * @brief arm_net_virtual_config Configuration send callback set by upper layer. Used to send internal configuration parameters.
00255  * @param driver_id Id of the driver to be used.
00256  * @param data Pointer to sent configuration data.
00257  * @param length Length of the configuration data.
00258  * @return 0 if success, error otherwise
00259  */
00260 typedef int8_t arm_net_virtual_config_tx_fn(int8_t driver_id, const uint8_t *data, uint16_t length);
00261 
00262 /**
00263  * @brief arm_net_virtual_confirmation Confirmation receive callback set by upper layer. Used to receive MLME confirmation data.
00264  * @param driver_id Id of the driver to be used.
00265  * @param data Pointer to received confirmation data.
00266  * @param length Length of the confirmation data.
00267  * @return 0 if success, error otherwise
00268  */
00269 typedef int8_t arm_net_virtual_confirmation_rx_fn(int8_t driver_id, const uint8_t *data, uint16_t length);
00270 
00271 /** Device driver structure */
00272 typedef struct phy_device_driver_s {
00273     phy_link_type_e link_type;                                      /**< Define driver types. */
00274     driver_data_request_e data_request_layer;                       /**< Define interface data OUT protocol. */
00275     uint8_t *PHY_MAC;                                               /**< Pointer to 64-bit or 48-bit MAC address. */
00276     uint16_t phy_MTU;                                               /**< Define MAX PHY layer MTU size. */
00277     char *driver_description;                                       /**< Short driver platform description. Needs to end with zero. */
00278     uint8_t phy_tail_length;                                        /**< Define PHY driver needed TAIL Length. */
00279     uint8_t phy_header_length;                                      /**< Define PHY driver needed header length before PDU. */
00280     int8_t (*state_control)(phy_interface_state_e, uint8_t);        /**< Function pointer for control PHY driver state. */
00281     int8_t (*tx)(uint8_t *, uint16_t, uint8_t, data_protocol_e);    /**< Function pointer for PHY driver write operation. */
00282     int8_t (*address_write)(phy_address_type_e, uint8_t *);         /**< Function pointer for PHY driver address write. */
00283     int8_t (*extension)(phy_extension_type_e, uint8_t *);           /**< Function pointer for PHY driver extension control. */
00284     const phy_device_channel_page_s *phy_channel_pages;             /**< Pointer to channel page list */
00285 
00286     //Upper layer callbacks, set with arm_net_phy_register();
00287     arm_net_phy_rx_fn *phy_rx_cb;                                   /**< PHY RX callback. Initialized by \ref arm_net_phy_register(). */
00288     arm_net_phy_tx_done_fn *phy_tx_done_cb;                         /**< Transmission done callback. Initialized by \ref arm_net_phy_register(). */
00289     //Virtual upper data rx
00290     arm_net_virtual_rx_fn *arm_net_virtual_rx_cb;                   /**< Virtual RX callback. Initialized by \ref arm_net_phy_register(). */
00291     arm_net_virtual_tx_fn *arm_net_virtual_tx_cb;                   /**< Virtual TX callback. Initialized by \ref arm_net_phy_register(). */
00292     arm_net_virtual_config_rx_fn *virtual_config_rx_cb;             /**< Virtual config receive callback. Initialized by \ref arm_net_phy_register(). */
00293     arm_net_virtual_config_tx_fn *virtual_config_tx_cb;             /**< Virtual config send callback. Initialized by \ref arm_net_phy_register(). */
00294     arm_net_virtual_confirmation_rx_fn *virtual_confirmation_rx_cb; /**< Virtual confirmation receive callback. Initialized by \ref arm_net_phy_register(). */
00295     uint16_t tunnel_type; /**< Tun driver type. */
00296     phy_rf_statistics_s *phy_rf_statistics;                         /**< PHY statistics. */
00297 } phy_device_driver_s;
00298 
00299 
00300 /**
00301  * \brief This function registers the device driver to stack.
00302  *
00303  * \param phy_driver A pointer to device driver structure.
00304  *
00305  * \return >= 0 Device driver ID.
00306  * \return < 0 Means register fail.
00307  *
00308  */
00309 extern int8_t arm_net_phy_register(phy_device_driver_s *phy_driver);
00310 
00311 
00312 /**
00313  * \brief Set driver mac64 address.
00314  *
00315  * \param MAC A pointer to new mac64 address which is copied to old one.
00316  * \param  id driver id
00317  *
00318  * \return >= 0 SET OK.
00319  * \return < 0 Means register fail.
00320  *
00321  */
00322 extern int8_t arm_net_phy_mac64_set(uint8_t *MAC, int8_t id);
00323 
00324 /**
00325  * \brief Get driver mac64 address.
00326  *
00327  * \param  id driver id
00328  *
00329  * \return > 0 Return pointer to MAC.
00330  * \return NULL.
00331  *
00332  */
00333 extern uint8_t *arm_net_phy_mac64_get(int8_t id);
00334 
00335 /**
00336  * \brief Get driver link type.
00337  *
00338  * \param  id driver id
00339  *
00340  * \return driver link type.
00341  *
00342  */
00343 extern int arm_net_phy_rf_type(int8_t id);
00344 
00345 /**
00346  * \brief Get driver link type MTU size.
00347  *
00348  * \param  id driver id
00349  *
00350  * \return size of MTU.
00351  *
00352  */
00353 extern uint16_t arm_net_phy_mtu_size(int8_t id);
00354 
00355 /**
00356  * \brief Unregister the driver from storage.
00357  *
00358  * \param driver_id driver id
00359  *
00360  */
00361 extern void arm_net_phy_unregister(int8_t driver_id);
00362 
00363 #ifdef __cplusplus
00364 }
00365 #endif
00366 #endif /* ARM_HAL_PHY_H_ */