David Fletcher
TI's CC3100 host driver and demo. Experimental and a work in progress.
Diff: simplelink/cc3100_simplelink.h
- Revision:
- 0:bbe98578d4c0
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/simplelink/cc3100_simplelink.h Mon Nov 17 19:38:34 2014 +0000
@@ -0,0 +1,597 @@
+/*
+ * 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 "cc3100_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 "cc3100_spawn.h"
+#else
+ #include "cc3100_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 "cc3100_objInclusion.h"
+#include "cc3100_trace.h"
+#include "cc3100_fs.h"
+#include "cc3100_socket.h"
+#include "cc3100_netapp.h"
+#include "cc3100_wlan.h"
+#include "cc3100_device.h"
+#include "cc3100_netcfg.h"
+#include "cc3100_wlan_rx_filters.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+
+
+/* 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__ */
+
+