diff options
Diffstat (limited to 'drivers/cc3100/inc/simplelink.h')
| -rw-r--r-- | drivers/cc3100/inc/simplelink.h | 592 |
1 files changed, 592 insertions, 0 deletions
diff --git a/drivers/cc3100/inc/simplelink.h b/drivers/cc3100/inc/simplelink.h new file mode 100644 index 0000000000..412d6242cb --- /dev/null +++ b/drivers/cc3100/inc/simplelink.h @@ -0,0 +1,592 @@ +/* + * simplelink.h - CC31xx/CC32xx Host Driver Implementation + * + * Copyright (C) 2014 Texas Instruments Incorporated - http://www.ti.com/ + * + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * + * Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * + * Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the + * distribution. + * + * Neither the name of Texas Instruments Incorporated nor the names of + * its contributors may be used to endorse or promote products derived + * from this software without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR + * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT + * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, + * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY + * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE + * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + * +*/ + + +/*! + \mainpage SimpleLink Driver + + \section intro_sec Introduction + + The SimpleLink CC31xx/CC2xx family allows to add Wi-Fi and networking capabilities + to low-cost embedded products without having prior Wi-Fi, RF or networking expertise. + The CC31xx/CC32xx is an ideal solution for microcontroller-based sensor and control + applications such as home appliances, home automation and smart metering. + The CC31xx/CC32xx has integrated a comprehensive TCP/IP network stack, Wi-Fi driver and + security supplicant leading to easier portability to microcontrollers, to an + ultra-low memory footprint, all without compromising the capabilities and robustness + of the final application. + + + + \section modules_sec Module Names + To make it simple, TI's SimpleLink CC31xx/CC32xx platform capabilities were divided into modules by topic (Silo). + These capabilities range from basic device management through wireless + network configuration, standard BSD socket and much more. + Listed below are the various modules in the SimpleLink CC31xx/CC32xx driver: + -# \ref device - controls the behaviour of the CC31xx/CC32xx device (start/stop, events masking and obtaining specific device status) + -# \ref wlan - controls the use of the WiFi WLAN module including: + - Connection features, such as: profiles, policies, SmartConfig™ + - Advanced WLAN features, such as: scans, rx filters and rx statistics collection + -# \ref socket - controls standard client/server sockets programming options and capabilities + -# \ref netapp - activates networking applications, such as: HTTP Server, DHCP Server, Ping, DNS and mDNS. + -# \ref netcfg - controls the configuration of the device addresses (i.e. IP and MAC addresses) + -# \ref FileSystem - provides file system capabilities to TI's CC31XX that can be used by both the CC31XX device and the user. + + + \section proting_sec Porting Guide + + The porting of the SimpleLink driver to any new platform is based on few simple steps. + This guide takes you through this process step by step. Please follow the instructions + carefully to avoid any problems during this process and to enable efficient and proper + work with the device. + Please notice that all modifications and porting adjustments of the driver should be + made in the user.h header file only. + Keep making any of the changes only in this file will ensure smoothly transaction to + new versions of the driver at the future! + + + \subsection porting_step1 Step 1 - Create your own user.h file + + The first step is to create a user.h file that will include your configurations and + adjustments. You can use the empty template provided as part of this driver or + you can choose to base your file on file from one of the wide range of examples + applications provided by Texas Instruments + + + \subsection porting_step2 Step 2 - Select the capabilities set required for your application + + Texas Instruments made a lot of efforts to build set of predefined capability sets that would + fit most of the target application. + It is recommended to try and choose one of this predefined capabilities set before going to + build your own customized set. If you find compatible set you can skip the rest of this step. + + The available sets are: + -# SL_TINY - Compatible to be used on platforms with very limited resources. Provides + the best in class foot print in terms of Code and Data consumption. + -# SL_SMALL - Compatible to most common networking applications. Provide the most + common APIs with decent balance between code size, data size, functionality + and performances + -# SL_FULL - Provide access to all SimpleLink functionalities + + + \subsection porting_step3 Step 3 - Bind the device enable/disable output line + + The enable/disable line (nHib) provide mechanism to enter the device into the least current + consumption mode. This mode could be used when no traffic is required (tx/rx). + when this line is not connected to any IO of the host this define should be left empty. + Not connecting this line results in ability to start the driver only once. + + + \subsection porting_step4 Step 4 - Writing your interface communication driver + + The SimpleLink device support several standard communication protocol among SPI and + UART. Depending on your needs and your hardware design, you should choose the + communication channel type. + The interface for this communication channel should include 4 simple access functions: + -# open + -# close + -# read + -# write + + The way this driver would be implemented is directly effecting the efficiency and + the performances of the SimpleLink device on this platform. + If your system has DMA you should consider to use it in order to increase the utilization + of the communication channel + If you have enough memory resources you should consider using a buffer to increase the + efficiency of the write operations. + + + \subsection porting_step5 Step 5 - Choose your memory management model + + The SimpleLink driver support two memory models: + -# Static (default) + -# Dynamic + + If you choose to work in dynamic model you will have to provide alloc and free functions + to be used by the Simple Link driver otherwise nothing need to be done. + + + \subsection porting_step6 Step 6 - OS adaptation + + The SimpleLink driver could run on two kind of platforms: + -# Non-Os / Single Threaded (default) + -# Multi-Threaded + + If you choose to work in multi-threaded environment under operating system you will have to + provide some basic adaptation routines to allow the driver to protect access to resources + for different threads (locking object) and to allow synchronization between threads (sync objects). + In additional the driver support running without dedicated thread allocated solely to the simple + link driver. If you choose to work in this mode, you should also supply a spawn method that + will enable to run function on a temporary context. + + + \subsection porting_step7 Step 7 - Set your asynchronous event handlers routines + + The SimpleLink device generate asynchronous events in several situations. + These asynchronous events could be masked. + In order to catch these events you have to provide handler routines. + Please notice that if you not provide a handler routine and the event is received, + the driver will drop this event without any indication of this drop. + + + \subsection porting_step8 Step 8 - Run diagnostic tools to validate the correctness of your porting + + The driver is delivered with some porting diagnostic tools to simplify the porting validation process + and to reduce issues latter. It is very important to follow carefully this process. + + The diagnostic process include: + -# Validating Interface Communication Driver + -# Validating OS adaptation layer + -# Validating HW integrity + -# Validating basic work with the device + + + \section sw_license License + + * + * + * Copyright (C) 2014 Texas Instruments Incorporated - http://www.ti.com/ + * + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * + * Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * + * Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the + * distribution. + * + * Neither the name of Texas Instruments Incorporated nor the names of + * its contributors may be used to endorse or promote products derived + * from this software without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR + * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT + * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, + * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY + * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE + * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + * +*/ + + + +#ifndef __SIMPLELINK_H__ +#define __SIMPLELINK_H__ + +#include "user.h" + +#ifdef __cplusplus +extern "C" +{ +#endif + + +/*! \attention Async event activation notes + Function prototypes for event callback handlers + Event handler function names should be defined in the user.h file + e.g. + "#define sl_WlanEvtHdlr SLWlanEventHandler" + Indicates all WLAN events are handled by User func "SLWlanEventHandler" + Important notes: + 1. Event handlers cannot activate another SimpleLink API from the event's context + 2. Event's data is valid during event's context. Any application data + which is required for the user application should be copied or marked + into user's variables + 3. It is not recommended to delay the execution of the event callback handler + +*/ + +/*! + + \addtogroup UserEvents + @{ + +*/ + + +/*****************************************************************************/ +/* Macro declarations for Host Driver version */ +/*****************************************************************************/ +#define SL_DRIVER_VERSION "1.0.0.1" +#define SL_MAJOR_VERSION_NUM 1L +#define SL_MINOR_VERSION_NUM 0L +#define SL_VERSION_NUM 0L +#define SL_SUB_VERSION_NUM 1L + + +/*****************************************************************************/ +/* Macro declarations for predefined configurations */ +/*****************************************************************************/ + +#ifdef SL_TINY +#undef SL_INC_ARG_CHECK +#undef SL_INC_EXT_API +#undef SL_INC_SOCK_CLIENT_SIDE_API +#undef SL_INC_SOCK_SEND_API +#undef SL_INC_WLAN_PKG +#undef SL_INC_NET_APP_PKG +#undef SL_INC_NET_CFG_PKG +#undef SL_INC_FS_PKG +#define SL_INC_SOCK_SERVER_SIDE_API +#define SL_INC_SOCK_RECV_API +#define SL_INC_SOCKET_PKG +#endif + +#ifdef SL_SMALL +#undef SL_INC_EXT_API +#undef SL_INC_NET_APP_PKG +#undef SL_INC_NET_CFG_PKG +#undef SL_INC_FS_PKG +#define SL_INC_ARG_CHECK +#define SL_INC_WLAN_PKG +#define SL_INC_SOCKET_PKG +#define SL_INC_SOCK_CLIENT_SIDE_API +#define SL_INC_SOCK_SERVER_SIDE_API +#define SL_INC_SOCK_RECV_API +#define SL_INC_SOCK_SEND_API +#endif + +#ifdef SL_FULL +#define SL_INC_EXT_API +#define SL_INC_NET_APP_PKG +#define SL_INC_NET_CFG_PKG +#define SL_INC_FS_PKG +#define SL_INC_ARG_CHECK +#define SL_INC_WLAN_PKG +#define SL_INC_SOCKET_PKG +#define SL_INC_SOCK_CLIENT_SIDE_API +#define SL_INC_SOCK_SERVER_SIDE_API +#define SL_INC_SOCK_RECV_API +#define SL_INC_SOCK_SEND_API +#endif + +#define SL_RET_CODE_OK (0) +#define SL_RET_CODE_INVALID_INPUT (-2) +#define SL_RET_CODE_SELF_ERROR (-3) +#define SL_RET_CODE_NWP_IF_ERROR (-4) +#define SL_RET_CODE_MALLOC_ERROR (-5) + +#define sl_Memcpy memcpy +#define sl_Memset memset + +#define sl_SyncObjClear(pObj) sl_SyncObjWait(pObj,SL_OS_NO_WAIT) + +#define SL_MAX_SOCKETS (8) + + +/*****************************************************************************/ +/* Types definitions */ +/*****************************************************************************/ +typedef void (*_SlSpawnEntryFunc_t)(void* pValue); + +#ifndef NULL +#define NULL (0) +#endif + +#ifndef FALSE +#define FALSE (0) +#endif + +#ifndef TRUE +#define TRUE (!FALSE) +#endif + +#ifndef OK +#define OK (0) +#endif + +#ifndef _SL_USER_TYPES + #define _u8 unsigned char + #define _i8 signed char + + #define _u16 unsigned short + #define _i16 signed short + + #define _u32 unsigned long + #define _i32 signed long + #define _volatile volatile + #define _const const +#endif + +typedef _u16 _SlOpcode_t; +typedef _u8 _SlArgSize_t; +typedef _i16 _SlDataSize_t; +typedef _i16 _SlReturnVal_t; + +#ifdef __cplusplus +} +#endif /* __cplusplus */ + + + +/*****************************************************************************/ +/* Include files */ +/*****************************************************************************/ + +#ifdef SL_PLATFORM_MULTI_THREADED + #include "../source/spawn.h" +#else + #include "../source/nonos.h" +#endif + + +/* + objInclusion.h and user.h must be included before all api header files + objInclusion.h must be the last arrangement just before including the API header files + since it based on the other configurations to decide which object should be included +*/ +#include "../source/objInclusion.h" +#include "trace.h" +#include "fs.h" +#include "socket.h" +#include "netapp.h" +#include "wlan.h" +#include "device.h" +#include "netcfg.h" +#include "wlan_rx_filters.h" + + + +/* Async functions description*/ + +/*! + \brief General async event for inspecting general events + + \param[out] pSlDeviceEvent pointer to SlDeviceEvent_t + + \par + Parameters: \n + <b>pSlDeviceEvent->Event = SL_DEVICE_FATAL_ERROR_EVENT </b> + - pSlDeviceEvent->EventData.deviceEvent fields: + - status: An error code indication from the device + - sender: The sender originator which is based on SlErrorSender_e enum + + \par Example: + \code + printf(General Event Handler - ID=%d Sender=%d\n\n", + pSlDeviceEvent->EventData.deviceEvent.status, // status of the general event + pSlDeviceEvent->EventData.deviceEvent.sender); // sender type + \endcode +*/ +#if (defined(sl_GeneralEvtHdlr)) +extern void sl_GeneralEvtHdlr(SlDeviceEvent_t *pSlDeviceEvent); +#endif + + +/*! + \brief WLAN Async event handler + + \param[out] pSlWlanEvent pointer to SlWlanEvent_t data + + \par + Parameters: + + - <b>pSlWlanEvent->Event = SL_WLAN_CONNECT_EVENT </b>, STA or P2P client connection indication event + - pSlWlanEvent->EventData.STAandP2PModeWlanConnected main fields: + - ssid_name + - ssid_len + - bssid + - go_peer_device_name + - go_peer_device_name_len + + - <b>pSlWlanEvent->Event = SL_WLAN_DISCONNECT_EVENT </b>, STA or P2P client disconnection event + - pSlWlanEvent->EventData.STAandP2PModeDisconnected main fields: + - ssid_name + - ssid_len + - reason_code + + - <b>pSlWlanEvent->Event = SL_WLAN_STA_CONNECTED_EVENT </b>, AP/P2P(Go) connected STA/P2P(Client) + - pSlWlanEvent->EventData.APModeStaConnected fields: + - go_peer_device_name + - mac + - go_peer_device_name_len + - wps_dev_password_id + - own_ssid: relevant for event sta-connected only + - own_ssid_len: relevant for event sta-connected only + + - <b>pSlWlanEvent->Event = SL_WLAN_STA_DISCONNECTED_EVENT </b>, AP/P2P(Go) disconnected STA/P2P(Client) + - pSlWlanEvent->EventData.APModestaDisconnected fields: + - go_peer_device_name + - mac + - go_peer_device_name_len + - wps_dev_password_id + - own_ssid: relevant for event sta-connected only + - own_ssid_len: relevant for event sta-connected only + + - <b>pSlWlanEvent->Event = SL_WLAN_SMART_CONFIG_COMPLETE_EVENT </b> + - pSlWlanEvent->EventData.smartConfigStartResponse fields: + - status + - ssid_len + - ssid + - private_token_len + - private_token + + - <b>pSlWlanEvent->Event = SL_WLAN_SMART_CONFIG_STOP_EVENT </b> + - pSlWlanEvent->EventData.smartConfigStopResponse fields: + - status + + - <b>pSlWlanEvent->Event = SL_WLAN_P2P_DEV_FOUND_EVENT </b> + - pSlWlanEvent->EventData.P2PModeDevFound fields: + - go_peer_device_name + - mac + - go_peer_device_name_len + - wps_dev_password_id + - own_ssid: relevant for event sta-connected only + - own_ssid_len: relevant for event sta-connected only + + - <b>pSlWlanEvent->Event = SL_WLAN_P2P_NEG_REQ_RECEIVED_EVENT </b> + - pSlWlanEvent->EventData.P2PModeNegReqReceived fields + - go_peer_device_name + - mac + - go_peer_device_name_len + - wps_dev_password_id + - own_ssid: relevant for event sta-connected only + + - <b>pSlWlanEvent->Event = SL_WLAN_CONNECTION_FAILED_EVENT </b>, P2P only + - pSlWlanEvent->EventData.P2PModewlanConnectionFailure fields: + - status +*/ +#if (defined(sl_WlanEvtHdlr)) +extern void sl_WlanEvtHdlr(SlWlanEvent_t *pSlWlanEvent); +#endif + + +/*! + \brief NETAPP Async event handler + + \param[out] pSlNetApp pointer to SlNetAppEvent_t data + + \par + Parameters: + - <b>pSlWlanEvent->Event = SL_NETAPP_IPV4_IPACQUIRED_EVENT</b>, IPV4 acquired event + - pSlWlanEvent->EventData.ipAcquiredV4 fields: + - ip + - gateway + - dns + + - <b>pSlWlanEvent->Event = SL_NETAPP_IP_LEASED_EVENT</b>, AP or P2P go dhcp lease event + - pSlWlanEvent->EventData.ipLeased fields: + - ip_address + - lease_time + - mac + + - <b>pSlWlanEvent->Event = SL_NETAPP_IP_RELEASED_EVENT</b>, AP or P2P go dhcp ip release event + - pSlWlanEvent->EventData.ipReleased fields + - ip_address + - mac + - reason + +*/ +#if (defined(sl_NetAppEvtHdlr)) +extern void sl_NetAppEvtHdlr(SlNetAppEvent_t *pSlNetApp); +#endif + +/*! + \brief Socket Async event handler + + \param[out] pSlSockEvent pointer to SlSockEvent_t data + + \par + Parameters:\n + - <b>pSlSockEvent->Event = SL_SOCKET_TX_FAILED_EVENT</b> + - pSlSockEvent->EventData fields: + - sd + - status + - <b>pSlSockEvent->Event = SL_SOCKET_ASYNC_EVENT</b> + - pSlSockEvent->EventData fields: + - sd + - type: SSL_ACCEPT or RX_FRAGMENTATION_TOO_BIG or OTHER_SIDE_CLOSE_SSL_DATA_NOT_ENCRYPTED + - val + +*/ +#if (defined(sl_SockEvtHdlr)) +extern void sl_SockEvtHdlr(SlSockEvent_t *pSlSockEvent); +#endif + +/*! + \brief HTTP server async event + + \param[out] pSlHttpServerEvent pointer to SlHttpServerEvent_t + \param[in] pSlHttpServerResponse pointer to SlHttpServerResponse_t + + \par + Parameters: \n + + - <b>pSlHttpServerEvent->Event = SL_NETAPP_HTTPGETTOKENVALUE_EVENT</b> + - pSlHttpServerEvent->EventData fields: + - httpTokenName + - data + - len + - pSlHttpServerResponse->ResponseData fields: + - data + - len + + - <b>pSlHttpServerEvent->Event = SL_NETAPP_HTTPPOSTTOKENVALUE_EVENT</b> + - pSlHttpServerEvent->EventData.httpPostData fields: + - action + - token_name + - token_value + - pSlHttpServerResponse->ResponseData fields: + - data + - len + +*/ +#if (defined(sl_HttpServerCallback)) +extern void sl_HttpServerCallback(SlHttpServerEvent_t *pSlHttpServerEvent, SlHttpServerResponse_t *pSlHttpServerResponse); +#endif +/*! + + Close the Doxygen group. + @} + + */ + +#ifdef __cplusplus +} +#endif /* __cplusplus */ + +#endif /* __SIMPLELINK_H__ */ + |