begriffs open source - cmsis/blob - CMSIS/Driver/Include/Driver_WiFi.h

   1 /*
   2  * Copyright (c) 2019-2022 Arm Limited. All rights reserved.
   3  *
   4  * SPDX-License-Identifier: Apache-2.0
   5  *
   6  * Licensed under the Apache License, Version 2.0 (the License); you may
   7  * not use this file except in compliance with the License.
   8  * You may obtain a copy of the License at
   9  *
  10  * www.apache.org/licenses/LICENSE-2.0
  11  *
  12  * Unless required by applicable law or agreed to in writing, software
  13  * distributed under the License is distributed on an AS IS BASIS, WITHOUT
  14  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15  * See the License for the specific language governing permissions and
  16  * limitations under the License.
  17  *
  18  * $Date:        30. March 2022
  19  * $Revision:    V1.1
  20  *
  21  * Project:      WiFi (Wireless Fidelity Interface) Driver definitions
  22  */
  23
  24 /* History:
  25  *  Version 1.1
  26  *    Extended Socket Receive/RecvFrom/Send/SendTo (support for polling)
  27  *  Version 1.0
  28  *    Initial release
  29  */
  30
  31 #ifndef DRIVER_WIFI_H_
  32 #define DRIVER_WIFI_H_
  33
  34 #ifdef  __cplusplus
  35 extern "C"
  36 {
  37 #endif
  38
  39 #include "Driver_Common.h"
  40
  41 #define ARM_WIFI_API_VERSION ARM_DRIVER_VERSION_MAJOR_MINOR(1,1)  /* API version */
  42
  43
  44 #define _ARM_Driver_WiFi_(n)      Driver_WiFi##n
  45 #define  ARM_Driver_WiFi_(n) _ARM_Driver_WiFi_(n)
  46
  47
  48 /****** WiFi SetOption/GetOption Function Option Codes *****/
  49 #define ARM_WIFI_BSSID                      1U          ///< Station/AP Set/Get BSSID of AP to connect or of AP;        data = &bssid,    len =  6, uint8_t[6]
  50 #define ARM_WIFI_TX_POWER                   2U          ///< Station/AP Set/Get transmit power;                         data = &power,    len =  4, uint32_t: 0 .. 20 [dBm]
  51 #define ARM_WIFI_LP_TIMER                   3U          ///< Station    Set/Get low-power deep-sleep time;              data = &time,     len =  4, uint32_t [seconds]: 0 = disable (default)
  52 #define ARM_WIFI_DTIM                       4U          ///< Station/AP Set/Get DTIM interval;                          data = &dtim,     len =  4, uint32_t [beacons]
  53 #define ARM_WIFI_BEACON                     5U          ///<         AP Set/Get beacon interval;                        data = &interval, len =  4, uint32_t [ms]
  54 #define ARM_WIFI_MAC                        6U          ///< Station/AP Set/Get MAC;                                    data = &mac,      len =  6, uint8_t[6]
  55 #define ARM_WIFI_IP                         7U          ///< Station/AP Set/Get IPv4 static/assigned address;           data = &ip,       len =  4, uint8_t[4]
  56 #define ARM_WIFI_IP_SUBNET_MASK             8U          ///< Station/AP Set/Get IPv4 subnet mask;                       data = &mask,     len =  4, uint8_t[4]
  57 #define ARM_WIFI_IP_GATEWAY                 9U          ///< Station/AP Set/Get IPv4 gateway address;                   data = &ip,       len =  4, uint8_t[4]
  58 #define ARM_WIFI_IP_DNS1                    10U         ///< Station/AP Set/Get IPv4 primary   DNS address;             data = &ip,       len =  4, uint8_t[4]
  59 #define ARM_WIFI_IP_DNS2                    11U         ///< Station/AP Set/Get IPv4 secondary DNS address;             data = &ip,       len =  4, uint8_t[4]
  60 #define ARM_WIFI_IP_DHCP                    12U         ///< Station/AP Set/Get IPv4 DHCP client/server enable/disable; data = &dhcp,     len =  4, uint32_t: 0 = disable, non-zero = enable (default)
  61 #define ARM_WIFI_IP_DHCP_POOL_BEGIN         13U         ///<         AP Set/Get IPv4 DHCP pool begin address;           data = &ip,       len =  4, uint8_t[4]
  62 #define ARM_WIFI_IP_DHCP_POOL_END           14U         ///<         AP Set/Get IPv4 DHCP pool end address;             data = &ip,       len =  4, uint8_t[4]
  63 #define ARM_WIFI_IP_DHCP_LEASE_TIME         15U         ///<         AP Set/Get IPv4 DHCP lease time;                   data = &time,     len =  4, uint32_t [seconds]
  64 #define ARM_WIFI_IP6_GLOBAL                 16U         ///< Station/AP Set/Get IPv6 global address;                    data = &ip6,      len = 16, uint8_t[16]
  65 #define ARM_WIFI_IP6_LINK_LOCAL             17U         ///< Station/AP Set/Get IPv6 link local address;                data = &ip6,      len = 16, uint8_t[16]
  66 #define ARM_WIFI_IP6_SUBNET_PREFIX_LEN      18U         ///< Station/AP Set/Get IPv6 subnet prefix length;              data = &len,      len =  4, uint32_t: 1 .. 127
  67 #define ARM_WIFI_IP6_GATEWAY                19U         ///< Station/AP Set/Get IPv6 gateway address;                   data = &ip6,      len = 16, uint8_t[16]
  68 #define ARM_WIFI_IP6_DNS1                   20U         ///< Station/AP Set/Get IPv6 primary   DNS address;             data = &ip6,      len = 16, uint8_t[16]
  69 #define ARM_WIFI_IP6_DNS2                   21U         ///< Station/AP Set/Get IPv6 secondary DNS address;             data = &ip6,      len = 16, uint8_t[16]
  70 #define ARM_WIFI_IP6_DHCP_MODE              22U         ///< Station/AP Set/Get IPv6 DHCPv6 client mode;                data = &mode,     len =  4, uint32_t: ARM_WIFI_IP6_DHCP_xxx (default Off)
  71
  72 /****** WiFi Security Type *****/
  73 #define ARM_WIFI_SECURITY_OPEN              0U          ///< Open
  74 #define ARM_WIFI_SECURITY_WEP               1U          ///< Wired Equivalent Privacy (WEP) with Pre-Sheared Key (PSK)
  75 #define ARM_WIFI_SECURITY_WPA               2U          ///< WiFi Protected Access (WPA) with PSK
  76 #define ARM_WIFI_SECURITY_WPA2              3U          ///< WiFi Protected Access II (WPA2) with PSK
  77 #define ARM_WIFI_SECURITY_UNKNOWN           255U        ///< Unknown
  78
  79 /****** WiFi Protected Setup (WPS) Method *****/
  80 #define ARM_WIFI_WPS_METHOD_NONE            0U          ///< Not used
  81 #define ARM_WIFI_WPS_METHOD_PBC             1U          ///< Push Button Configuration
  82 #define ARM_WIFI_WPS_METHOD_PIN             2U          ///< PIN
  83
  84 /****** WiFi IPv6 Dynamic Host Configuration Protocol (DHCP) Mode *****/
  85 #define ARM_WIFI_IP6_DHCP_OFF               0U          ///< Static Host Configuration (default)
  86 #define ARM_WIFI_IP6_DHCP_STATELESS         1U          ///< Dynamic Host Configuration stateless DHCPv6
  87 #define ARM_WIFI_IP6_DHCP_STATEFULL         2U          ///< Dynamic Host Configuration statefull DHCPv6
  88
  89 /****** WiFi Event *****/
  90 #define ARM_WIFI_EVENT_AP_CONNECT          (1UL << 0)   ///< Access Point: Station has connected;           arg = &mac, mac (uint8_t[6])
  91 #define ARM_WIFI_EVENT_AP_DISCONNECT       (1UL << 1)   ///< Access Point: Station has disconnected;        arg = &mac, mac (uint8_t[6])
  92 #define ARM_WIFI_EVENT_ETH_RX_FRAME        (1UL << 4)   ///< Ethernet Frame Received (in bypass mode only); arg = interface (0 = Station, 1 = Access Point)
  93
  94
  95 /**
  96 \brief WiFi Configuration
  97 */
  98 typedef struct ARM_WIFI_CONFIG_s {
  99   const char   *ssid;                                   ///< Pointer to Service Set Identifier (SSID) null-terminated string
 100   const char   *pass;                                   ///< Pointer to Password null-terminated string
 101         uint8_t security;                               ///< Security type (ARM_WIFI_SECURITY_xxx)
 102         uint8_t ch;                                     ///< WiFi Channel (0 = auto, otherwise = exact channel)
 103         uint8_t reserved;                               ///< Reserved
 104         uint8_t wps_method;                             ///< WiFi Protected Setup (WPS) method (ARM_WIFI_WPS_METHOD_xxx)
 105   const char   *wps_pin;                                ///< Pointer to WiFi Protected Setup (WPS) PIN null-terminated string
 106 } ARM_WIFI_CONFIG_t;
 107
 108 /**
 109 \brief WiFi Scan Information
 110 */
 111 typedef struct ARM_WIFI_SCAN_INFO_s {
 112   char    ssid[32+1];                                   ///< Service Set Identifier (SSID) null-terminated string
 113   uint8_t bssid[6];                                     ///< Basic Service Set Identifier (BSSID)
 114   uint8_t security;                                     ///< Security type (ARM_WIFI_SECURITY_xxx)
 115   uint8_t ch;                                           ///< WiFi Channel
 116   uint8_t rssi;                                         ///< Received Signal Strength Indicator
 117 } ARM_WIFI_SCAN_INFO_t;
 118
 119 /**
 120 \brief WiFi Network Information
 121 */
 122 typedef struct ARM_WIFI_NET_INFO_s {
 123   char    ssid[32+1];                                   ///< Service Set Identifier (SSID) null-terminated string
 124   char    pass[64+1];                                   ///< Password null-terminated string
 125   uint8_t security;                                     ///< Security type (ARM_WIFI_SECURITY_xxx)
 126   uint8_t ch;                                           ///< WiFi Channel
 127   uint8_t rssi;                                         ///< Received Signal Strength Indicator
 128 } ARM_WIFI_NET_INFO_t;
 129
 130 /****** Socket Address Family definitions *****/
 131 #define ARM_SOCKET_AF_INET                  1           ///< IPv4
 132 #define ARM_SOCKET_AF_INET6                 2           ///< IPv6
 133
 134 /****** Socket Type definitions *****/
 135 #define ARM_SOCKET_SOCK_STREAM              1           ///< Stream socket
 136 #define ARM_SOCKET_SOCK_DGRAM               2           ///< Datagram socket
 137
 138 /****** Socket Protocol definitions *****/
 139 #define ARM_SOCKET_IPPROTO_TCP              1           ///< TCP
 140 #define ARM_SOCKET_IPPROTO_UDP              2           ///< UDP
 141
 142 /****** Socket Option definitions *****/
 143 #define ARM_SOCKET_IO_FIONBIO               1           ///< Non-blocking I/O (Set only, default = 0); opt_val = &nbio, opt_len = sizeof(nbio), nbio (integer): 0=blocking, non-blocking otherwise
 144 #define ARM_SOCKET_SO_RCVTIMEO              2           ///< Receive timeout in ms (default = 0); opt_val = &timeout, opt_len = sizeof(timeout)
 145 #define ARM_SOCKET_SO_SNDTIMEO              3           ///< Send timeout in ms (default = 0); opt_val = &timeout, opt_len = sizeof(timeout)
 146 #define ARM_SOCKET_SO_KEEPALIVE             4           ///< Keep-alive messages (default = 0); opt_val = &keepalive, opt_len = sizeof(keepalive), keepalive (integer): 0=disabled, enabled otherwise
 147 #define ARM_SOCKET_SO_TYPE                  5           ///< Socket Type (Get only); opt_val = &socket_type, opt_len = sizeof(socket_type), socket_type (integer): ARM_SOCKET_SOCK_xxx
 148
 149 /****** Socket Function return codes *****/
 150 #define ARM_SOCKET_ERROR                   (-1)         ///< Unspecified error
 151 #define ARM_SOCKET_ESOCK                   (-2)         ///< Invalid socket
 152 #define ARM_SOCKET_EINVAL                  (-3)         ///< Invalid argument
 153 #define ARM_SOCKET_ENOTSUP                 (-4)         ///< Operation not supported
 154 #define ARM_SOCKET_ENOMEM                  (-5)         ///< Not enough memory
 155 #define ARM_SOCKET_EAGAIN                  (-6)         ///< Operation would block or timed out
 156 #define ARM_SOCKET_EINPROGRESS             (-7)         ///< Operation in progress
 157 #define ARM_SOCKET_ETIMEDOUT               (-8)         ///< Operation timed out
 158 #define ARM_SOCKET_EISCONN                 (-9)         ///< Socket is connected
 159 #define ARM_SOCKET_ENOTCONN                (-10)        ///< Socket is not connected
 160 #define ARM_SOCKET_ECONNREFUSED            (-11)        ///< Connection rejected by the peer
 161 #define ARM_SOCKET_ECONNRESET              (-12)        ///< Connection reset by the peer
 162 #define ARM_SOCKET_ECONNABORTED            (-13)        ///< Connection aborted locally
 163 #define ARM_SOCKET_EALREADY                (-14)        ///< Connection already in progress
 164 #define ARM_SOCKET_EADDRINUSE              (-15)        ///< Address in use
 165 #define ARM_SOCKET_EHOSTNOTFOUND           (-16)        ///< Host not found
 166
 167
 168 // Function documentation
 169 /**
 170   \fn            ARM_DRIVER_VERSION ARM_WIFI_GetVersion (void)
 171   \brief         Get driver version.
 172   \return        \ref ARM_DRIVER_VERSION
 173 */
 174 /**
 175   \fn            ARM_WIFI_CAPABILITIES ARM_WIFI_GetCapabilities (void)
 176   \brief         Get driver capabilities.
 177   \return        \ref ARM_WIFI_CAPABILITIES
 178 */
 179 /**
 180   \fn            int32_t ARM_WIFI_Initialize (ARM_WIFI_SignalEvent_t cb_event)
 181   \brief         Initialize WiFi Module.
 182   \param[in]     cb_event Pointer to \ref ARM_WIFI_SignalEvent_t
 183   \return        execution status
 184                    - \ref ARM_DRIVER_OK                : Operation successful
 185                    - \ref ARM_DRIVER_ERROR             : Operation failed
 186 */
 187 /**
 188   \fn            int32_t ARM_WIFI_Uninitialize (void)
 189   \brief         De-initialize WiFi Module.
 190   \return        execution status
 191                    - \ref ARM_DRIVER_OK                : Operation successful
 192                    - \ref ARM_DRIVER_ERROR             : Operation failed
 193 */
 194 /**
 195   \fn            int32_t ARM_WIFI_PowerControl (ARM_POWER_STATE state)
 196   \brief         Control WiFi Module Power.
 197   \param[in]     state     Power state
 198                    - \ref ARM_POWER_OFF                : Power off: no operation possible
 199                    - \ref ARM_POWER_LOW                : Low-power mode: sleep or deep-sleep depending on \ref ARM_WIFI_LP_TIMER option set
 200                    - \ref ARM_POWER_FULL               : Power on: full operation at maximum performance
 201   \return        execution status
 202                    - \ref ARM_DRIVER_OK                : Operation successful
 203                    - \ref ARM_DRIVER_ERROR             : Operation failed
 204                    - \ref ARM_DRIVER_ERROR_UNSUPPORTED : Operation not supported
 205                    - \ref ARM_DRIVER_ERROR_PARAMETER   : Parameter error (invalid state)
 206 */
 207 /**
 208   \fn            int32_t ARM_WIFI_GetModuleInfo (char *module_info, uint32_t max_len)
 209   \brief         Get Module information.
 210   \param[out]    module_info Pointer to character buffer were info string will be returned
 211   \param[in]     max_len     Maximum length of string to return (including null terminator)
 212   \return        execution status
 213                    - \ref ARM_DRIVER_OK                : Operation successful
 214                    - \ref ARM_DRIVER_ERROR             : Operation failed
 215                    - \ref ARM_DRIVER_ERROR_UNSUPPORTED : Operation not supported
 216                    - \ref ARM_DRIVER_ERROR_PARAMETER   : Parameter error (NULL module_info pointer or max_len equals to 0)
 217 */
 218 /**
 219   \fn            int32_t ARM_WIFI_SetOption (uint32_t interface, uint32_t option, const void *data, uint32_t len)
 220   \brief         Set WiFi Module Options.
 221   \param[in]     interface Interface (0 = Station, 1 = Access Point)
 222   \param[in]     option    Option to set
 223   \param[in]     data      Pointer to data relevant to selected option
 224   \param[in]     len       Length of data (in bytes)
 225   \return        execution status
 226                    - \ref ARM_DRIVER_OK                : Operation successful
 227                    - \ref ARM_DRIVER_ERROR             : Operation failed
 228                    - \ref ARM_DRIVER_ERROR_UNSUPPORTED : Operation not supported
 229                    - \ref ARM_DRIVER_ERROR_PARAMETER   : Parameter error (invalid interface, NULL data pointer or len less than option specifies)
 230 */
 231 /**
 232   \fn            int32_t ARM_WIFI_GetOption (uint32_t interface, uint32_t option, void *data, uint32_t *len)
 233   \brief         Get WiFi Module Options.
 234   \param[in]     interface Interface (0 = Station, 1 = Access Point)
 235   \param[in]     option    Option to get
 236   \param[out]    data      Pointer to memory where data for selected option will be returned
 237   \param[in,out] len       Pointer to length of data (input/output)
 238                    - input: maximum length of data that can be returned (in bytes)
 239                    - output: length of returned data (in bytes)
 240   \return        execution status
 241                    - \ref ARM_DRIVER_OK                : Operation successful
 242                    - \ref ARM_DRIVER_ERROR             : Operation failed
 243                    - \ref ARM_DRIVER_ERROR_UNSUPPORTED : Operation not supported
 244                    - \ref ARM_DRIVER_ERROR_PARAMETER   : Parameter error (invalid interface, NULL data or len pointer, or *len less than option specifies)
 245 */
 246 /**
 247   \fn            int32_t ARM_WIFI_Scan (ARM_WIFI_SCAN_INFO_t scan_info[], uint32_t max_num)
 248   \brief         Scan for available networks in range.
 249   \param[out]    scan_info Pointer to array of ARM_WIFI_SCAN_INFO_t structures where available Scan Information will be returned
 250   \param[in]     max_num   Maximum number of Network Information structures to return
 251   \return        number of ARM_WIFI_SCAN_INFO_t structures returned or error code
 252                    - value >= 0                        : Number of ARM_WIFI_SCAN_INFO_t structures returned
 253                    - \ref ARM_DRIVER_ERROR             : Operation failed
 254                    - \ref ARM_DRIVER_ERROR_PARAMETER   : Parameter error (NULL scan_info pointer or max_num equal to 0)
 255 */
 256 /**
 257   \fn            int32_t ARM_WIFI_Activate (uint32_t interface, const ARM_WIFI_CONFIG_t *config)
 258   \brief         Activate interface (Connect to a wireless network or activate an access point).
 259   \param[in]     interface Interface (0 = Station, 1 = Access Point)
 260   \param[in]     config    Pointer to ARM_WIFI_CONFIG_t structure where Configuration parameters are located
 261   \return        execution status
 262                    - \ref ARM_DRIVER_OK                : Operation successful
 263                    - \ref ARM_DRIVER_ERROR             : Operation failed
 264                    - \ref ARM_DRIVER_ERROR_TIMEOUT     : Timeout occurred
 265                    - \ref ARM_DRIVER_ERROR_UNSUPPORTED : Operation not supported (security type, channel autodetect or WPS not supported)
 266                    - \ref ARM_DRIVER_ERROR_PARAMETER   : Parameter error (invalid interface, NULL config pointer or invalid configuration)
 267 */
 268 /**
 269   \fn            int32_t ARM_WIFI_Deactivate (uint32_t interface)
 270   \brief         Deactivate interface (Disconnect from a wireless network or deactivate an access point).
 271   \param[in]     interface Interface (0 = Station, 1 = Access Point)
 272   \return        execution status
 273                    - \ref ARM_DRIVER_OK                : Operation successful
 274                    - \ref ARM_DRIVER_ERROR             : Operation failed
 275                    - \ref ARM_DRIVER_ERROR_PARAMETER   : Parameter error (invalid interface)
 276 */
 277 /**
 278   \fn            uint32_t ARM_WIFI_IsConnected (void)
 279   \brief         Get station connection status.
 280   \return        station connection status
 281                    - value != 0: Station connected
 282                    - value = 0: Station not connected
 283 */
 284 /**
 285   \fn            int32_t ARM_WIFI_GetNetInfo (ARM_WIFI_NET_INFO_t *net_info)
 286   \brief         Get station Network Information.
 287   \param[out]    net_info  Pointer to ARM_WIFI_NET_INFO_t structure where station Network Information will be returned
 288   \return        execution status
 289                    - \ref ARM_DRIVER_OK                : Operation successful
 290                    - \ref ARM_DRIVER_ERROR             : Operation failed (station not connected)
 291                    - \ref ARM_DRIVER_ERROR_UNSUPPORTED : Operation not supported
 292                    - \ref ARM_DRIVER_ERROR_PARAMETER   : Parameter error (invalid interface or NULL net_info pointer)
 293 */
 294 /**
 295   \fn            int32_t ARM_WIFI_BypassControl (uint32_t interface, uint32_t mode)
 296   \brief         Enable or disable bypass (pass-through) mode. Transmit and receive Ethernet frames (IP layer bypassed and WiFi/Ethernet translation).
 297   \param[in]     interface Interface (0 = Station, 1 = Access Point)
 298   \param[in]     mode
 299                    - value = 1: all packets bypass internal IP stack
 300                    - value = 0: all packets processed by internal IP stack
 301   \return        execution status
 302                    - \ref ARM_DRIVER_OK                : Operation successful
 303                    - \ref ARM_DRIVER_ERROR             : Operation failed
 304                    - \ref ARM_DRIVER_ERROR_UNSUPPORTED : Operation not supported
 305                    - \ref ARM_DRIVER_ERROR_PARAMETER   : Parameter error (invalid interface or mode)
 306 */
 307 /**
 308   \fn            int32_t ARM_WIFI_EthSendFrame (uint32_t interface, const uint8_t *frame, uint32_t len)
 309   \brief         Send Ethernet frame (in bypass mode only).
 310   \param[in]     interface Interface (0 = Station, 1 = Access Point)
 311   \param[in]     frame    Pointer to frame buffer with data to send
 312   \param[in]     len      Frame buffer length in bytes
 313   \return        execution status
 314                    - \ref ARM_DRIVER_OK                : Operation successful
 315                    - \ref ARM_DRIVER_ERROR             : Operation failed
 316                    - \ref ARM_DRIVER_ERROR_BUSY        : Driver is busy
 317                    - \ref ARM_DRIVER_ERROR_UNSUPPORTED : Operation not supported
 318                    - \ref ARM_DRIVER_ERROR_PARAMETER   : Parameter error (invalid interface or NULL frame pointer)
 319 */
 320 /**
 321   \fn            int32_t ARM_WIFI_EthReadFrame (uint32_t interface, uint8_t *frame, uint32_t len)
 322   \brief         Read data of received Ethernet frame (in bypass mode only).
 323   \param[in]     interface Interface (0 = Station, 1 = Access Point)
 324   \param[in]     frame    Pointer to frame buffer for data to read into
 325   \param[in]     len      Frame buffer length in bytes
 326   \return        number of data bytes read or error code
 327                    - value >= 0                        : Number of data bytes read
 328                    - \ref ARM_DRIVER_ERROR             : Operation failed
 329                    - \ref ARM_DRIVER_ERROR_UNSUPPORTED : Operation not supported
 330                    - \ref ARM_DRIVER_ERROR_PARAMETER   : Parameter error (invalid interface or NULL frame pointer)
 331 */
 332 /**
 333   \fn            uint32_t ARM_WIFI_EthGetRxFrameSize (uint32_t interface)
 334   \brief         Get size of received Ethernet frame (in bypass mode only).
 335   \param[in]     interface Interface (0 = Station, 1 = Access Point)
 336   \return        number of bytes in received frame
 337 */
 338 /**
 339   \fn            int32_t ARM_WIFI_SocketCreate (int32_t af, int32_t type, int32_t protocol)
 340   \brief         Create a communication socket.
 341   \param[in]     af       Address family
 342   \param[in]     type     Socket type
 343   \param[in]     protocol Socket protocol
 344   \return        status information
 345                    - Socket identification number (>=0)
 346                    - \ref ARM_SOCKET_EINVAL            : Invalid argument
 347                    - \ref ARM_SOCKET_ENOTSUP           : Operation not supported
 348                    - \ref ARM_SOCKET_ENOMEM            : Not enough memory
 349                    - \ref ARM_SOCKET_ERROR             : Unspecified error
 350 */
 351 /**
 352   \fn            int32_t ARM_WIFI_SocketBind (int32_t socket, const uint8_t *ip, uint32_t ip_len, uint16_t port)
 353   \brief         Assign a local address to a socket.
 354   \param[in]     socket   Socket identification number
 355   \param[in]     ip       Pointer to local IP address
 356   \param[in]     ip_len   Length of 'ip' address in bytes
 357   \param[in]     port     Local port number
 358   \return        status information
 359                    - 0                                 : Operation successful
 360                    - \ref ARM_SOCKET_ESOCK             : Invalid socket
 361                    - \ref ARM_SOCKET_EINVAL            : Invalid argument (address or socket already bound)
 362                    - \ref ARM_SOCKET_EADDRINUSE        : Address already in use
 363                    - \ref ARM_SOCKET_ERROR             : Unspecified error
 364 */
 365 /**
 366   \fn            int32_t ARM_WIFI_SocketListen (int32_t socket, int32_t backlog)
 367   \brief         Listen for socket connections.
 368   \param[in]     socket   Socket identification number
 369   \param[in]     backlog  Number of connection requests that can be queued
 370   \return        status information
 371                    - 0                                 : Operation successful
 372                    - \ref ARM_SOCKET_ESOCK             : Invalid socket
 373                    - \ref ARM_SOCKET_EINVAL            : Invalid argument (socket not bound)
 374                    - \ref ARM_SOCKET_ENOTSUP           : Operation not supported
 375                    - \ref ARM_SOCKET_EISCONN           : Socket is already connected
 376                    - \ref ARM_SOCKET_ERROR             : Unspecified error
 377 */
 378 /**
 379   \fn            int32_t ARM_WIFI_SocketAccept (int32_t socket, uint8_t *ip, uint32_t *ip_len, uint16_t *port)
 380   \brief         Accept a new connection on a socket.
 381   \param[in]     socket   Socket identification number
 382   \param[out]    ip       Pointer to buffer where address of connecting socket shall be returned (NULL for none)
 383   \param[in,out] ip_len   Pointer to length of 'ip' (or NULL if 'ip' is NULL)
 384                    - length of supplied 'ip' on input
 385                    - length of stored 'ip' on output
 386   \param[out]    port     Pointer to buffer where port of connecting socket shall be returned (NULL for none)
 387   \return        status information
 388                    - socket identification number of accepted socket (>=0)
 389                    - \ref ARM_SOCKET_ESOCK             : Invalid socket
 390                    - \ref ARM_SOCKET_EINVAL            : Invalid argument (socket not in listen mode)
 391                    - \ref ARM_SOCKET_ENOTSUP           : Operation not supported (socket type does not support accepting connections)
 392                    - \ref ARM_SOCKET_ECONNRESET        : Connection reset by the peer
 393                    - \ref ARM_SOCKET_ECONNABORTED      : Connection aborted locally
 394                    - \ref ARM_SOCKET_EAGAIN            : Operation would block or timed out (may be called again)
 395                    - \ref ARM_SOCKET_ERROR             : Unspecified error
 396 */
 397 /**
 398   \fn            int32_t ARM_WIFI_SocketConnect (int32_t socket, const uint8_t *ip, uint32_t ip_len, uint16_t port)
 399   \brief         Connect a socket to a remote host.
 400   \param[in]     socket   Socket identification number
 401   \param[in]     ip       Pointer to remote IP address
 402   \param[in]     ip_len   Length of 'ip' address in bytes
 403   \param[in]     port     Remote port number
 404   \return        status information
 405                    - 0                                 : Operation successful
 406                    - \ref ARM_SOCKET_ESOCK             : Invalid socket
 407                    - \ref ARM_SOCKET_EINVAL            : Invalid argument
 408                    - \ref ARM_SOCKET_EALREADY          : Connection already in progress
 409                    - \ref ARM_SOCKET_EINPROGRESS       : Operation in progress
 410                    - \ref ARM_SOCKET_EISCONN           : Socket is connected
 411                    - \ref ARM_SOCKET_ECONNREFUSED      : Connection rejected by the peer
 412                    - \ref ARM_SOCKET_ECONNABORTED      : Connection aborted locally
 413                    - \ref ARM_SOCKET_EADDRINUSE        : Address already in use
 414                    - \ref ARM_SOCKET_ETIMEDOUT         : Operation timed out
 415                    - \ref ARM_SOCKET_ERROR             : Unspecified error
 416 */
 417 /**
 418   \fn            int32_t ARM_WIFI_SocketRecv (int32_t socket, void *buf, uint32_t len)
 419   \brief         Receive data or check if data is available on a connected socket.
 420   \param[in]     socket   Socket identification number
 421   \param[out]    buf      Pointer to buffer where data should be stored
 422   \param[in]     len      Length of buffer (in bytes), set len = 0 to check if data is available
 423   \return        status information
 424                    - number of bytes received (>=0), if len != 0
 425                    - 0                                 : Data is available (len = 0)
 426                    - \ref ARM_SOCKET_ESOCK             : Invalid socket
 427                    - \ref ARM_SOCKET_EINVAL            : Invalid argument (pointer to buffer or length)
 428                    - \ref ARM_SOCKET_ENOTCONN          : Socket is not connected
 429                    - \ref ARM_SOCKET_ECONNRESET        : Connection reset by the peer
 430                    - \ref ARM_SOCKET_ECONNABORTED      : Connection aborted locally
 431                    - \ref ARM_SOCKET_EAGAIN            : Operation would block or timed out (may be called again)
 432                    - \ref ARM_SOCKET_ERROR             : Unspecified error
 433 */
 434 /**
 435   \fn            int32_t ARM_WIFI_SocketRecvFrom (int32_t socket, void *buf, uint32_t len, uint8_t *ip, uint32_t *ip_len, uint16_t *port)
 436   \brief         Receive data or check if data is available on a socket.
 437   \param[in]     socket   Socket identification number
 438   \param[out]    buf      Pointer to buffer where data should be stored
 439   \param[in]     len      Length of buffer (in bytes), set len = 0 to check if data is available
 440   \param[out]    ip       Pointer to buffer where remote source address shall be returned (NULL for none)
 441   \param[in,out] ip_len   Pointer to length of 'ip' (or NULL if 'ip' is NULL)
 442                    - length of supplied 'ip' on input
 443                    - length of stored 'ip' on output
 444   \param[out]    port     Pointer to buffer where remote source port shall be returned (NULL for none)
 445   \return        status information
 446                    - number of bytes received (>=0), if len != 0
 447                    - 0                                 : Data is available (len = 0)
 448                    - \ref ARM_SOCKET_ESOCK             : Invalid socket
 449                    - \ref ARM_SOCKET_EINVAL            : Invalid argument (pointer to buffer or length)
 450                    - \ref ARM_SOCKET_ENOTCONN          : Socket is not connected
 451                    - \ref ARM_SOCKET_ECONNRESET        : Connection reset by the peer
 452                    - \ref ARM_SOCKET_ECONNABORTED      : Connection aborted locally
 453                    - \ref ARM_SOCKET_EAGAIN            : Operation would block or timed out (may be called again)
 454                    - \ref ARM_SOCKET_ERROR             : Unspecified error
 455 */
 456 /**
 457   \fn            int32_t ARM_WIFI_SocketSend (int32_t socket, const void *buf, uint32_t len)
 458   \brief         Send data or check if data can be sent on a connected socket.
 459   \param[in]     socket   Socket identification number
 460   \param[in]     buf      Pointer to buffer containing data to send
 461   \param[in]     len      Length of data (in bytes), set len = 0 to check if data can be sent
 462   \return        status information
 463                    - number of bytes sent (>=0), if len != 0
 464                    - 0                                 : Data can be sent (len = 0)
 465                    - \ref ARM_SOCKET_ESOCK             : Invalid socket
 466                    - \ref ARM_SOCKET_EINVAL            : Invalid argument (pointer to buffer or length)
 467                    - \ref ARM_SOCKET_ENOTCONN          : Socket is not connected
 468                    - \ref ARM_SOCKET_ECONNRESET        : Connection reset by the peer
 469                    - \ref ARM_SOCKET_ECONNABORTED      : Connection aborted locally
 470                    - \ref ARM_SOCKET_EAGAIN            : Operation would block or timed out (may be called again)
 471                    - \ref ARM_SOCKET_ERROR             : Unspecified error
 472 */
 473 /**
 474   \fn            int32_t ARM_WIFI_SocketSendTo (int32_t socket, const void *buf, uint32_t len, const uint8_t *ip, uint32_t ip_len, uint16_t port)
 475   \brief         Send data or check if data can be sent on a socket.
 476   \param[in]     socket   Socket identification number
 477   \param[in]     buf      Pointer to buffer containing data to send
 478   \param[in]     len      Length of data (in bytes), set len = 0 to check if data can be sent
 479   \param[in]     ip       Pointer to remote destination IP address
 480   \param[in]     ip_len   Length of 'ip' address in bytes
 481   \param[in]     port     Remote destination port number
 482   \return        status information
 483                    - number of bytes sent (>=0), if len != 0
 484                    - 0                                 : Data can be sent (len = 0)
 485                    - \ref ARM_SOCKET_ESOCK             : Invalid socket
 486                    - \ref ARM_SOCKET_EINVAL            : Invalid argument (pointer to buffer or length)
 487                    - \ref ARM_SOCKET_ENOTCONN          : Socket is not connected
 488                    - \ref ARM_SOCKET_ECONNRESET        : Connection reset by the peer
 489                    - \ref ARM_SOCKET_ECONNABORTED      : Connection aborted locally
 490                    - \ref ARM_SOCKET_EAGAIN            : Operation would block or timed out (may be called again)
 491                    - \ref ARM_SOCKET_ERROR             : Unspecified error
 492 */
 493 /**
 494   \fn            int32_t ARM_WIFI_SocketGetSockName (int32_t socket, uint8_t *ip, uint32_t *ip_len, uint16_t *port)
 495   \brief         Retrieve local IP address and port of a socket.
 496   \param[in]     socket   Socket identification number
 497   \param[out]    ip       Pointer to buffer where local address shall be returned (NULL for none)
 498   \param[in,out] ip_len   Pointer to length of 'ip' (or NULL if 'ip' is NULL)
 499                    - length of supplied 'ip' on input
 500                    - length of stored 'ip' on output
 501   \param[out]    port     Pointer to buffer where local port shall be returned (NULL for none)
 502   \return        status information
 503                    - 0                                 : Operation successful
 504                    - \ref ARM_SOCKET_ESOCK             : Invalid socket
 505                    - \ref ARM_SOCKET_EINVAL            : Invalid argument (pointer to buffer or length)
 506                    - \ref ARM_SOCKET_ERROR             : Unspecified error
 507 */
 508 /**
 509   \fn            int32_t ARM_WIFI_SocketGetPeerName (int32_t socket, uint8_t *ip, uint32_t *ip_len, uint16_t *port)
 510   \brief         Retrieve remote IP address and port of a socket.
 511   \param[in]     socket   Socket identification number
 512   \param[out]    ip       Pointer to buffer where remote address shall be returned (NULL for none)
 513   \param[in,out] ip_len   Pointer to length of 'ip' (or NULL if 'ip' is NULL)
 514                    - length of supplied 'ip' on input
 515                    - length of stored 'ip' on output
 516   \param[out]    port     Pointer to buffer where remote port shall be returned (NULL for none)
 517   \return        status information
 518                    - 0                                 : Operation successful
 519                    - \ref ARM_SOCKET_ESOCK             : Invalid socket
 520                    - \ref ARM_SOCKET_EINVAL            : Invalid argument (pointer to buffer or length)
 521                    - \ref ARM_SOCKET_ENOTCONN          : Socket is not connected
 522                    - \ref ARM_SOCKET_ERROR             : Unspecified error
 523 */
 524 /**
 525   \fn            int32_t ARM_WIFI_SocketGetOpt (int32_t socket, int32_t opt_id, void *opt_val, uint32_t *opt_len)
 526   \brief         Get socket option.
 527   \param[in]     socket   Socket identification number
 528   \param[in]     opt_id   Option identifier
 529   \param[out]    opt_val  Pointer to the buffer that will receive the option value
 530   \param[in,out] opt_len  Pointer to length of the option value
 531                    - length of buffer on input
 532                    - length of data on output
 533   \return        status information
 534                    - 0                                 : Operation successful
 535                    - \ref ARM_SOCKET_ESOCK             : Invalid socket
 536                    - \ref ARM_SOCKET_EINVAL            : Invalid argument
 537                    - \ref ARM_SOCKET_ENOTSUP           : Operation not supported
 538                    - \ref ARM_SOCKET_ERROR             : Unspecified error
 539 */
 540 /**
 541   \fn            int32_t ARM_WIFI_SocketSetOpt (int32_t socket, int32_t opt_id, const void *opt_val, uint32_t opt_len)
 542   \brief         Set socket option.
 543   \param[in]     socket   Socket identification number
 544   \param[in]     opt_id   Option identifier
 545   \param[in]     opt_val  Pointer to the option value
 546   \param[in]     opt_len  Length of the option value in bytes
 547   \return        status information
 548                    - 0                                 : Operation successful
 549                    - \ref ARM_SOCKET_ESOCK             : Invalid socket
 550                    - \ref ARM_SOCKET_EINVAL            : Invalid argument
 551                    - \ref ARM_SOCKET_ENOTSUP           : Operation not supported
 552                    - \ref ARM_SOCKET_ERROR             : Unspecified error
 553 */
 554 /**
 555   \fn            int32_t ARM_WIFI_SocketClose (int32_t socket)
 556   \brief         Close and release a socket.
 557   \param[in]     socket   Socket identification number
 558   \return        status information
 559                    - 0                                 : Operation successful
 560                    - \ref ARM_SOCKET_ESOCK             : Invalid socket
 561                    - \ref ARM_SOCKET_EAGAIN            : Operation would block (may be called again)
 562                    - \ref ARM_SOCKET_ERROR             : Unspecified error
 563 */
 564 /**
 565   \fn            int32_t ARM_WIFI_SocketGetHostByName (const char *name, int32_t af, uint8_t *ip, uint32_t *ip_len)
 566   \brief         Retrieve host IP address from host name.
 567   \param[in]     name     Host name
 568   \param[in]     af       Address family
 569   \param[out]    ip       Pointer to buffer where resolved IP address shall be returned
 570   \param[in,out] ip_len   Pointer to length of 'ip'
 571                    - length of supplied 'ip' on input
 572                    - length of stored 'ip' on output
 573   \return        status information
 574                    - 0                                 : Operation successful
 575                    - \ref ARM_SOCKET_EINVAL            : Invalid argument
 576                    - \ref ARM_SOCKET_ENOTSUP           : Operation not supported
 577                    - \ref ARM_SOCKET_ETIMEDOUT         : Operation timed out
 578                    - \ref ARM_SOCKET_EHOSTNOTFOUND     : Host not found
 579                    - \ref ARM_SOCKET_ERROR             : Unspecified error
 580 */
 581 /**
 582   \fn            int32_t ARM_WIFI_Ping (const uint8_t *ip, uint32_t ip_len)
 583   \brief         Probe remote host with Ping command.
 584   \param[in]     ip       Pointer to remote host IP address
 585   \param[in]     ip_len   Length of 'ip' address in bytes
 586   \return        execution status
 587                    - \ref ARM_DRIVER_OK                : Operation successful
 588                    - \ref ARM_DRIVER_ERROR             : Operation failed
 589                    - \ref ARM_DRIVER_ERROR_TIMEOUT     : Timeout occurred
 590                    - \ref ARM_DRIVER_ERROR_UNSUPPORTED : Operation not supported
 591                    - \ref ARM_DRIVER_ERROR_PARAMETER   : Parameter error (NULL ip pointer or ip_len different than 4 or 16)
 592 */
 593 /**
 594   \fn            void ARM_WIFI_SignalEvent (uint32_t event, void *arg)
 595   \brief         Signal WiFi Events.
 596   \param[in]     event    \ref wifi_event notification mask
 597   \param[in]     arg      Pointer to argument of signaled event
 598   \return        none
 599 */
 600
 601 typedef void (*ARM_WIFI_SignalEvent_t) (uint32_t event, void *arg); ///< Pointer to \ref ARM_WIFI_SignalEvent : Signal WiFi Event.
 602
 603
 604 /**
 605 \brief WiFi Driver Capabilities.
 606 */
 607 typedef struct _ARM_WIFI_CAPABILITIES {
 608   uint32_t station               : 1;   ///< Station
 609   uint32_t ap                    : 1;   ///< Access Point
 610   uint32_t station_ap            : 1;   ///< Concurrent Station and Access Point
 611   uint32_t wps_station           : 1;   ///< WiFi Protected Setup (WPS) for Station
 612   uint32_t wps_ap                : 1;   ///< WiFi Protected Setup (WPS) for Access Point
 613   uint32_t event_ap_connect      : 1;   ///< Access Point: event generated on Station connect
 614   uint32_t event_ap_disconnect   : 1;   ///< Access Point: event generated on Station disconnect
 615   uint32_t event_eth_rx_frame    : 1;   ///< Event generated on Ethernet frame reception in bypass mode
 616   uint32_t bypass_mode           : 1;   ///< Bypass or pass-through mode (Ethernet interface)
 617   uint32_t ip                    : 1;   ///< IP (UDP/TCP) (Socket interface)
 618   uint32_t ip6                   : 1;   ///< IPv6 (Socket interface)
 619   uint32_t ping                  : 1;   ///< Ping (ICMP)
 620   uint32_t reserved              : 20;  ///< Reserved (must be zero)
 621 } ARM_WIFI_CAPABILITIES;
 622
 623 /**
 624 \brief Access structure of the WiFi Driver.
 625 */
 626 typedef struct _ARM_DRIVER_WIFI {
 627   ARM_DRIVER_VERSION    (*GetVersion)                  (void);
 628   ARM_WIFI_CAPABILITIES (*GetCapabilities)             (void);
 629   int32_t               (*Initialize)                  (ARM_WIFI_SignalEvent_t cb_event);
 630   int32_t               (*Uninitialize)                (void);
 631   int32_t               (*PowerControl)                (ARM_POWER_STATE state);
 632   int32_t               (*GetModuleInfo)               (char *module_info, uint32_t max_len);
 633   int32_t               (*SetOption)                   (uint32_t interface, uint32_t option, const void *data, uint32_t  len);
 634   int32_t               (*GetOption)                   (uint32_t interface, uint32_t option,       void *data, uint32_t *len);
 635   int32_t               (*Scan)                        (ARM_WIFI_SCAN_INFO_t scan_info[], uint32_t max_num);
 636   int32_t               (*Activate)                    (uint32_t interface, const ARM_WIFI_CONFIG_t *config);
 637   int32_t               (*Deactivate)                  (uint32_t interface);
 638   uint32_t              (*IsConnected)                 (void);
 639   int32_t               (*GetNetInfo)                  (ARM_WIFI_NET_INFO_t *net_info);
 640   int32_t               (*BypassControl)               (uint32_t interface, uint32_t mode);
 641   int32_t               (*EthSendFrame)                (uint32_t interface, const uint8_t *frame, uint32_t len);
 642   int32_t               (*EthReadFrame)                (uint32_t interface,       uint8_t *frame, uint32_t len);
 643   uint32_t              (*EthGetRxFrameSize)           (uint32_t interface);
 644   int32_t               (*SocketCreate)                (int32_t af, int32_t type, int32_t protocol);
 645   int32_t               (*SocketBind)                  (int32_t socket, const uint8_t *ip, uint32_t  ip_len, uint16_t  port);
 646   int32_t               (*SocketListen)                (int32_t socket, int32_t backlog);
 647   int32_t               (*SocketAccept)                (int32_t socket,       uint8_t *ip, uint32_t *ip_len, uint16_t *port);
 648   int32_t               (*SocketConnect)               (int32_t socket, const uint8_t *ip, uint32_t  ip_len, uint16_t  port);
 649   int32_t               (*SocketRecv)                  (int32_t socket, void *buf, uint32_t len);
 650   int32_t               (*SocketRecvFrom)              (int32_t socket, void *buf, uint32_t len, uint8_t *ip, uint32_t *ip_len, uint16_t *port);
 651   int32_t               (*SocketSend)                  (int32_t socket, const void *buf, uint32_t len);
 652   int32_t               (*SocketSendTo)                (int32_t socket, const void *buf, uint32_t len, const uint8_t *ip, uint32_t ip_len, uint16_t port);
 653   int32_t               (*SocketGetSockName)           (int32_t socket, uint8_t *ip, uint32_t *ip_len, uint16_t *port);
 654   int32_t               (*SocketGetPeerName)           (int32_t socket, uint8_t *ip, uint32_t *ip_len, uint16_t *port);
 655   int32_t               (*SocketGetOpt)                (int32_t socket, int32_t opt_id,       void *opt_val, uint32_t *opt_len);
 656   int32_t               (*SocketSetOpt)                (int32_t socket, int32_t opt_id, const void *opt_val, uint32_t  opt_len);
 657   int32_t               (*SocketClose)                 (int32_t socket);
 658   int32_t               (*SocketGetHostByName)         (const char *name, int32_t af, uint8_t *ip, uint32_t *ip_len);
 659   int32_t               (*Ping)                        (const uint8_t *ip, uint32_t ip_len);
 660 } const ARM_DRIVER_WIFI;
 661
 662 #ifdef  __cplusplus
 663 }
 664 #endif
 665
 666 #endif /* DRIVER_WIFI_H_ */