Lee Kai Xuan / mbed-os

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.

Fork of mbed-os by erkin yucel

features/nanostack/FEATURE_NANOSTACK/sal-stack-nanostack/nanostack/platform/arm_hal_phy.h@0:f269e3021894, 2016-10-23 (annotated)

Committer:
elessair
Date:
Sun Oct 23 15:10:02 2016 +0000
Revision:
0:f269e3021894
Initial commit

Who changed what in which revision?

UserRevisionLine numberNew contents of line
elessair 0:f269e3021894 1 /*
elessair 0:f269e3021894 2 * Copyright (c) 2014-2015 ARM Limited. All rights reserved.
elessair 0:f269e3021894 3 *
elessair 0:f269e3021894 4 * SPDX-License-Identifier: LicenseRef-PBL
elessair 0:f269e3021894 5 *
elessair 0:f269e3021894 6 * Licensed under the Permissive Binary License, Version 1.0 (the "License"); you may not use this file except in compliance with the License.
elessair 0:f269e3021894 7 * You may obtain a copy of the License at
elessair 0:f269e3021894 8 *
elessair 0:f269e3021894 9 * https://www.mbed.com/licenses/PBL-1.0
elessair 0:f269e3021894 10 *
elessair 0:f269e3021894 11 * See the License for the specific language governing permissions and limitations under the License.
elessair 0:f269e3021894 12 *
elessair 0:f269e3021894 13 */
elessair 0:f269e3021894 14
elessair 0:f269e3021894 15 /**
elessair 0:f269e3021894 16 * \file arm_hal_phy.h
elessair 0:f269e3021894 17 * \brief PHY device driver API.
elessair 0:f269e3021894 18 */
elessair 0:f269e3021894 19
elessair 0:f269e3021894 20 #ifndef ARM_HAL_PHY_H_
elessair 0:f269e3021894 21 #define ARM_HAL_PHY_H_
elessair 0:f269e3021894 22
elessair 0:f269e3021894 23 #include "ns_types.h"
elessair 0:f269e3021894 24
elessair 0:f269e3021894 25 #ifdef __cplusplus
elessair 0:f269e3021894 26 extern "C" {
elessair 0:f269e3021894 27 #endif
elessair 0:f269e3021894 28
elessair 0:f269e3021894 29 /** Interface states */
elessair 0:f269e3021894 30 typedef enum {
elessair 0:f269e3021894 31 PHY_INTERFACE_RESET, /**< Reset PHY driver and set to idle. */
elessair 0:f269e3021894 32 PHY_INTERFACE_DOWN, /**< Disable PHY interface driver (RF radio disable). */
elessair 0:f269e3021894 33 PHY_INTERFACE_UP, /**< Enable PHY interface driver (RF radio receiver ON). */
elessair 0:f269e3021894 34 PHY_INTERFACE_RX_ENERGY_STATE, /**< Enable wireless interface ED scan mode. */
elessair 0:f269e3021894 35 PHY_INTERFACE_SNIFFER_STATE /**< Enable sniffer mode. */
elessair 0:f269e3021894 36 } phy_interface_state_e;
elessair 0:f269e3021894 37
elessair 0:f269e3021894 38 /** TX process return codes */
elessair 0:f269e3021894 39 typedef enum {
elessair 0:f269e3021894 40 PHY_LINK_TX_DONE, /**< TX process ready and ACK RX. */
elessair 0:f269e3021894 41 PHY_LINK_TX_DONE_PENDING, /**< TX process OK with ACK pending flag. */
elessair 0:f269e3021894 42 PHY_LINK_TX_SUCCESS, /**< MAC TX complete. MAC will a make decision to enter wait ACK or TX done state. */
elessair 0:f269e3021894 43 PHY_LINK_TX_FAIL, /**< Link TX process fail. */
elessair 0:f269e3021894 44 PHY_LINK_CCA_FAIL, /**< RF link CCA process fail. */
elessair 0:f269e3021894 45 } phy_link_tx_status_e;
elessair 0:f269e3021894 46
elessair 0:f269e3021894 47 /** Extension types */
elessair 0:f269e3021894 48 typedef enum {
elessair 0:f269e3021894 49 PHY_EXTENSION_CTRL_PENDING_BIT, /**< Control MAC pending bit for indirect data. */
elessair 0:f269e3021894 50 PHY_EXTENSION_READ_LAST_ACK_PENDING_STATUS, /**< Read status if the last ACK is still pending. */
elessair 0:f269e3021894 51 PHY_EXTENSION_SET_CHANNEL, /**< Net library channel set. */
elessair 0:f269e3021894 52 PHY_EXTENSION_READ_CHANNEL_ENERGY, /**< RF interface ED scan energy read. */
elessair 0:f269e3021894 53 PHY_EXTENSION_READ_LINK_STATUS, /**< Net library could read link status. */
elessair 0:f269e3021894 54 PHY_EXTENSION_CONVERT_SIGNAL_INFO, /**< Convert signal info. */
elessair 0:f269e3021894 55 } phy_extension_type_e;
elessair 0:f269e3021894 56
elessair 0:f269e3021894 57 /** Address types */
elessair 0:f269e3021894 58 typedef enum {
elessair 0:f269e3021894 59 PHY_MAC_48BIT, /**< IPv4/IPv6/BLE link layer address for Ethernet. This is optional. */
elessair 0:f269e3021894 60 PHY_MAC_64BIT, /**< RF/PLC link layer address. */
elessair 0:f269e3021894 61 PHY_MAC_16BIT, /**< RF interface short address. */
elessair 0:f269e3021894 62 PHY_MAC_PANID, /**< RF interface 16-Bit PAN-ID. */
elessair 0:f269e3021894 63 } phy_address_type_e;
elessair 0:f269e3021894 64
elessair 0:f269e3021894 65 /** PHY types */
elessair 0:f269e3021894 66 typedef enum phy_link_type_e {
elessair 0:f269e3021894 67 PHY_LINK_ETHERNET_TYPE, /**< Standard IEEE 802 Ethernet. */
elessair 0:f269e3021894 68 PHY_LINK_15_4_2_4GHZ_TYPE, /**< Standard 802.15.4 2.4GHz radio. */
elessair 0:f269e3021894 69 PHY_LINK_15_4_SUBGHZ_TYPE, /**< Standard 802.15.4 subGHz radio 868 /915MHz. */
elessair 0:f269e3021894 70 PHY_LINK_TUN, /**< Tunnel interface for Linux TUN, RF network driver over serial bus or just basic application to application data flow. */
elessair 0:f269e3021894 71 PHY_LINK_SLIP, /**< Generic SLIP driver which just forward SLIP payload */
elessair 0:f269e3021894 72 } phy_link_type_e;
elessair 0:f269e3021894 73
elessair 0:f269e3021894 74 /** Data layers */
elessair 0:f269e3021894 75 typedef enum data_protocol_e {
elessair 0:f269e3021894 76 LOCAL_SOCKET_DATA = 0, /**< 6LoWPAN library local socket data. */
elessair 0:f269e3021894 77 INTERFACE_DATA = 1, /**< 6LoWPAN library interface internal used protocol. */
elessair 0:f269e3021894 78 PHY_LAYER_PAYLOAD = 2, /**< PHY layer data selection or handler. */
elessair 0:f269e3021894 79 IPV6_DATAGRAM = 3, /**< IP layer data or TUN driver request data. */
elessair 0:f269e3021894 80 UNKNOWN_PROTOCOL = 4 /**< Non-supported protocol ID. */
elessair 0:f269e3021894 81 } data_protocol_e;
elessair 0:f269e3021894 82
elessair 0:f269e3021894 83 /** Requested data layer */
elessair 0:f269e3021894 84 typedef enum driver_data_request_e {
elessair 0:f269e3021894 85 PHY_LAYER_PAYLOAD_DATA_FLOW, /**< PHY layer data. */
elessair 0:f269e3021894 86 IPV6_DATAGRAMS_DATA_FLOW, /**< IP layer data or TUN driver request data. */
elessair 0:f269e3021894 87 } driver_data_request_e;
elessair 0:f269e3021894 88
elessair 0:f269e3021894 89 /** \brief Signal info types.
elessair 0:f269e3021894 90 *
elessair 0:f269e3021894 91 * Types of signal quality indication desired by various link protocols. Some are
elessair 0:f269e3021894 92 * really statistical, but a driver should ideally be able to create an estimate
elessair 0:f269e3021894 93 * based on its LQI/DBM numbers, for example to bootstrap a statistic calculation.
elessair 0:f269e3021894 94 */
elessair 0:f269e3021894 95 typedef enum phy_signal_info_type_e {
elessair 0:f269e3021894 96 PHY_SIGNAL_INFO_ETX, /**< Expected transmissions, unsigned 16-bit fixed-point ETX*128 [1..512], for example Zigbee IP + RFC 6719. */
elessair 0:f269e3021894 97 PHY_SIGNAL_INFO_IDR, /**< Inverse Delivery Ratio, unsigned 16-bit fixed-point IDR*32*256 [1..8], for example MLE draft 06. */
elessair 0:f269e3021894 98 PHY_SIGNAL_INFO_LINK_MARGIN, /**< Link margin, unsigned 16-bit fixed-point dB*256, [0..255], for example Thread routing draft. */
elessair 0:f269e3021894 99 } phy_signal_info_type_e;
elessair 0:f269e3021894 100
elessair 0:f269e3021894 101 /** Signal level info */
elessair 0:f269e3021894 102 typedef struct phy_signal_info_s {
elessair 0:f269e3021894 103 phy_signal_info_type_e type; /**< Signal info type desired. */
elessair 0:f269e3021894 104 uint8_t lqi; /**< Quality passed to arm_net_phy_rx. */
elessair 0:f269e3021894 105 int8_t dbm; /**< Strength passed to arm_net_phy_rx. */
elessair 0:f269e3021894 106 uint16_t result; /**< Resulting signal information. */
elessair 0:f269e3021894 107 } phy_signal_info_s;
elessair 0:f269e3021894 108
elessair 0:f269e3021894 109 /** PHY modulation scheme */
elessair 0:f269e3021894 110 typedef enum phy_modulation_e
elessair 0:f269e3021894 111 {
elessair 0:f269e3021894 112 M_OFDM, ///< QFDM
elessair 0:f269e3021894 113 M_OQPSK, ///< OQPSK
elessair 0:f269e3021894 114 M_BPSK, ///< BPSK
elessair 0:f269e3021894 115 M_GFSK, ///< GFSK
elessair 0:f269e3021894 116 M_UNDEFINED ///< UNDEFINED
elessair 0:f269e3021894 117 } phy_modulation_e;
elessair 0:f269e3021894 118
elessair 0:f269e3021894 119 /** Channel page numbers */
elessair 0:f269e3021894 120 typedef enum
elessair 0:f269e3021894 121 {
elessair 0:f269e3021894 122 CHANNEL_PAGE_0 = 0, ///< Page 0
elessair 0:f269e3021894 123 CHANNEL_PAGE_1 = 1, ///< Page 1
elessair 0:f269e3021894 124 CHANNEL_PAGE_2 = 2, ///< Page 2
elessair 0:f269e3021894 125 CHANNEL_PAGE_3 = 3, ///< Page 3
elessair 0:f269e3021894 126 CHANNEL_PAGE_4 = 4, ///< Page 4
elessair 0:f269e3021894 127 CHANNEL_PAGE_5 = 5, ///< Page 5
elessair 0:f269e3021894 128 CHANNEL_PAGE_6 = 6, ///< Page 6
elessair 0:f269e3021894 129 CHANNEL_PAGE_9 = 9, ///< Page 9
elessair 0:f269e3021894 130 CHANNEL_PAGE_10 = 10 ///< Page 10
elessair 0:f269e3021894 131 } channel_page_e;
elessair 0:f269e3021894 132
elessair 0:f269e3021894 133 /** Channel configuration */
elessair 0:f269e3021894 134 typedef struct phy_rf_channel_configuration_s
elessair 0:f269e3021894 135 {
elessair 0:f269e3021894 136 uint32_t channel_0_center_frequency; ///< Center frequency
elessair 0:f269e3021894 137 uint32_t channel_spacing; ///< Channel spacing
elessair 0:f269e3021894 138 uint32_t datarate; ///< Data rate
elessair 0:f269e3021894 139 uint16_t number_of_channels; ///< Number of channels
elessair 0:f269e3021894 140 phy_modulation_e modulation; ///< Modulation scheme
elessair 0:f269e3021894 141 } phy_rf_channel_configuration_s;
elessair 0:f269e3021894 142
elessair 0:f269e3021894 143 /** Channel page configuration */
elessair 0:f269e3021894 144 typedef struct phy_device_channel_page_s
elessair 0:f269e3021894 145 {
elessair 0:f269e3021894 146 channel_page_e channel_page; ///< Channel page
elessair 0:f269e3021894 147 const phy_rf_channel_configuration_s *rf_channel_configuration; ///< Pointer to channel configuration
elessair 0:f269e3021894 148 } phy_device_channel_page_s;
elessair 0:f269e3021894 149
elessair 0:f269e3021894 150 /** Virtual data request */
elessair 0:f269e3021894 151 typedef struct virtual_data_req_s {
elessair 0:f269e3021894 152 uint16_t parameter_length;
elessair 0:f269e3021894 153 uint8_t *parameters;
elessair 0:f269e3021894 154 uint16_t msduLength;
elessair 0:f269e3021894 155 const uint8_t *msdu;
elessair 0:f269e3021894 156 } virtual_data_req_t;
elessair 0:f269e3021894 157
elessair 0:f269e3021894 158 /**
elessair 0:f269e3021894 159 * @brief arm_net_phy_rx RX callback set by upper layer. Called when data is received
elessair 0:f269e3021894 160 * @param data_ptr Data received
elessair 0:f269e3021894 161 * @param data_len Length of the data received
elessair 0:f269e3021894 162 * @param link_quality Link quality
elessair 0:f269e3021894 163 * @param dbm Power ratio in decibels
elessair 0:f269e3021894 164 * @param driver_id ID of driver which received data
elessair 0:f269e3021894 165 * @return 0 if success, error otherwise
elessair 0:f269e3021894 166 */
elessair 0:f269e3021894 167 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);
elessair 0:f269e3021894 168
elessair 0:f269e3021894 169 /**
elessair 0:f269e3021894 170 * @brief arm_net_phy_tx_done TX done callback set by upper layer. Called when tx sent by upper layer has been handled
elessair 0:f269e3021894 171 * @param driver_id Id of the driver which handled TX request
elessair 0:f269e3021894 172 * @param tx_handle Handle of the TX
elessair 0:f269e3021894 173 * @param status Status code of the TX handling result
elessair 0:f269e3021894 174 * @param cca_retry Number of CCA retries done during handling
elessair 0:f269e3021894 175 * @param tx_retry Number of TX retries done during handling
elessair 0:f269e3021894 176 * @return 0 if success, error otherwise
elessair 0:f269e3021894 177 */
elessair 0:f269e3021894 178 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);
elessair 0:f269e3021894 179
elessair 0:f269e3021894 180 /**
elessair 0:f269e3021894 181 * @brief arm_net_virtual_rx RX callback set by user of serial MAC. Called when virtual RF has received data.
elessair 0:f269e3021894 182 * @param data_ptr Data received
elessair 0:f269e3021894 183 * @param data_len Length of the data received
elessair 0:f269e3021894 184 * @param driver_id ID of driver which received data
elessair 0:f269e3021894 185 * @return 0 if success, error otherwise
elessair 0:f269e3021894 186 */
elessair 0:f269e3021894 187 typedef int8_t arm_net_virtual_rx_fn(const uint8_t *data_ptr, uint16_t data_len,int8_t driver_id);
elessair 0:f269e3021894 188
elessair 0:f269e3021894 189 /**
elessair 0:f269e3021894 190 * @brief arm_net_virtual_tx TX callback set by serial MAC. Used to send data.
elessair 0:f269e3021894 191 * @param data_req Data to be sent
elessair 0:f269e3021894 192 * @param driver_id Id of the driver to be used.
elessair 0:f269e3021894 193 * @return 0 if success, error otherwise
elessair 0:f269e3021894 194 */
elessair 0:f269e3021894 195 typedef int8_t arm_net_virtual_tx_fn(const virtual_data_req_t *data_req,int8_t driver_id);
elessair 0:f269e3021894 196
elessair 0:f269e3021894 197 /** Device driver structure */
elessair 0:f269e3021894 198 typedef struct phy_device_driver_s
elessair 0:f269e3021894 199 {
elessair 0:f269e3021894 200 phy_link_type_e link_type; /**< Define driver types. */
elessair 0:f269e3021894 201 driver_data_request_e data_request_layer; /**< Define interface data OUT protocol. */
elessair 0:f269e3021894 202 uint8_t *PHY_MAC; /**< Pointer to 64-bit or 48-bit MAC address. */
elessair 0:f269e3021894 203 uint16_t phy_MTU; /**< Define MAX PHY layer MTU size. */
elessair 0:f269e3021894 204 char *driver_description; /**< Short driver platform description. Needs to end with zero. */
elessair 0:f269e3021894 205 uint8_t phy_tail_length; /**< Define PHY driver needed TAIL Length. */
elessair 0:f269e3021894 206 uint8_t phy_header_length; /**< Define PHY driver needed header length before PDU. */
elessair 0:f269e3021894 207 int8_t (*state_control)(phy_interface_state_e, uint8_t); /**< Function pointer for control PHY driver state. */
elessair 0:f269e3021894 208 int8_t (*tx)(uint8_t *, uint16_t, uint8_t, data_protocol_e); /**< Function pointer for PHY driver write operation. */
elessair 0:f269e3021894 209 int8_t (*address_write)(phy_address_type_e , uint8_t *); /**< Function pointer for PHY driver address write. */
elessair 0:f269e3021894 210 int8_t (*extension)(phy_extension_type_e, uint8_t *); /**< Function pointer for PHY driver extension control. */
elessair 0:f269e3021894 211 const phy_device_channel_page_s *phy_channel_pages; /**< Pointer to channel page list */
elessair 0:f269e3021894 212
elessair 0:f269e3021894 213 //Upper layer callbacks, set with arm_net_phy_register();
elessair 0:f269e3021894 214 arm_net_phy_rx_fn *phy_rx_cb; /**< PHY RX callback. Initialized by \ref arm_net_phy_register(). */
elessair 0:f269e3021894 215 arm_net_phy_tx_done_fn *phy_tx_done_cb; /**< Transmission done callback. Initialized by \ref arm_net_phy_register(). */
elessair 0:f269e3021894 216 //Virtual upper data rx
elessair 0:f269e3021894 217 arm_net_virtual_rx_fn *arm_net_virtual_rx_cb; /**< Virtual RX callback. Initialized by \ref arm_net_phy_register(). */
elessair 0:f269e3021894 218 arm_net_virtual_tx_fn *arm_net_virtual_tx_cb; /**< Virtual TX callback. Initialized by \ref arm_net_phy_register(). */
elessair 0:f269e3021894 219 uint16_t tunnel_type; /**< Tun driver type. */
elessair 0:f269e3021894 220 } phy_device_driver_s;
elessair 0:f269e3021894 221
elessair 0:f269e3021894 222
elessair 0:f269e3021894 223 /**
elessair 0:f269e3021894 224 * \brief This function registers the device driver to stack.
elessair 0:f269e3021894 225 *
elessair 0:f269e3021894 226 * \param phy_driver A pointer to device driver structure.
elessair 0:f269e3021894 227 *
elessair 0:f269e3021894 228 * \return >= 0 Device driver ID.
elessair 0:f269e3021894 229 * \return < 0 Means register fail.
elessair 0:f269e3021894 230 *
elessair 0:f269e3021894 231 */
elessair 0:f269e3021894 232 extern int8_t arm_net_phy_register(phy_device_driver_s *phy_driver);
elessair 0:f269e3021894 233
elessair 0:f269e3021894 234
elessair 0:f269e3021894 235 /**
elessair 0:f269e3021894 236 * \brief Set driver mac64 address.
elessair 0:f269e3021894 237 *
elessair 0:f269e3021894 238 * \param MAC A pointer to new mac64 address which is copied to old one.
elessair 0:f269e3021894 239 * \param id driver id
elessair 0:f269e3021894 240 *
elessair 0:f269e3021894 241 * \return >= 0 SET OK.
elessair 0:f269e3021894 242 * \return < 0 Means register fail.
elessair 0:f269e3021894 243 *
elessair 0:f269e3021894 244 */
elessair 0:f269e3021894 245 extern int8_t arm_net_phy_mac64_set(uint8_t *MAC, int8_t id);
elessair 0:f269e3021894 246
elessair 0:f269e3021894 247 /**
elessair 0:f269e3021894 248 * \brief Get driver mac64 address.
elessair 0:f269e3021894 249 *
elessair 0:f269e3021894 250 * \param id driver id
elessair 0:f269e3021894 251 *
elessair 0:f269e3021894 252 * \return > 0 Return pointer to MAC.
elessair 0:f269e3021894 253 * \return NULL.
elessair 0:f269e3021894 254 *
elessair 0:f269e3021894 255 */
elessair 0:f269e3021894 256 extern uint8_t *arm_net_phy_mac64_get(int8_t id);
elessair 0:f269e3021894 257
elessair 0:f269e3021894 258 /**
elessair 0:f269e3021894 259 * \brief Get driver link type.
elessair 0:f269e3021894 260 *
elessair 0:f269e3021894 261 * \param id driver id
elessair 0:f269e3021894 262 *
elessair 0:f269e3021894 263 * \return driver link type.
elessair 0:f269e3021894 264 *
elessair 0:f269e3021894 265 */
elessair 0:f269e3021894 266 extern int arm_net_phy_rf_type(int8_t id);
elessair 0:f269e3021894 267
elessair 0:f269e3021894 268 /**
elessair 0:f269e3021894 269 * \brief Get driver link type MTU size.
elessair 0:f269e3021894 270 *
elessair 0:f269e3021894 271 * \param id driver id
elessair 0:f269e3021894 272 *
elessair 0:f269e3021894 273 * \return size of MTU.
elessair 0:f269e3021894 274 *
elessair 0:f269e3021894 275 */
elessair 0:f269e3021894 276 extern uint16_t arm_net_phy_mtu_size(int8_t id);
elessair 0:f269e3021894 277
elessair 0:f269e3021894 278 /**
elessair 0:f269e3021894 279 * \brief Unregister the driver from storage.
elessair 0:f269e3021894 280 *
elessair 0:f269e3021894 281 * \param driver_id driver id
elessair 0:f269e3021894 282 *
elessair 0:f269e3021894 283 */
elessair 0:f269e3021894 284 extern void arm_net_phy_unregister(int8_t driver_id);
elessair 0:f269e3021894 285
elessair 0:f269e3021894 286 #ifdef __cplusplus
elessair 0:f269e3021894 287 }
elessair 0:f269e3021894 288 #endif
elessair 0:f269e3021894 289 #endif /* ARM_HAL_PHY_H_ */