Diff: simplelink/cc3100_simplelink.h

Revision:

0:e89ba455dbcf

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/simplelink/cc3100_simplelink.h	Tue Feb 10 12:09:29 2015 +0000
@@ -0,0 +1,580 @@
+/*
+ * 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 "mbed.h"
+#include "cc3100_user.h"
+
+namespace mbed_cc3100 {
+
+/*! \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_SyncObjClear(pObj)     sl_SyncObjWait(pObj,NON_OS_SYNC_OBJ_SIGNAL_VALUE,NON_OS_SYNC_OBJ_CLEAR_VALUE,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 uint16_t  _SlOpcode_t;
+typedef uint8_t   _SlArgSize_t;
+typedef int16_t   _SlDataSize_t;
+typedef int16_t   _SlReturnVal_t;
+}//namespace mbed_cc3100
+/*****************************************************************************/
+/* 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.h"
+#include "cc3100_netcfg.h"
+#include "cc3100_wlan_rx_filters.h"
+
+namespace mbed_cc3100 {
+
+/* 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))
+//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))
+//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))
+//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))
+//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))
+//void sl_HttpServerCallback(SlHttpServerEvent_t *pSlHttpServerEvent, SlHttpServerResponse_t *pSlHttpServerResponse);
+//#endif
+/*!
+
+ Close the Doxygen group.
+ @}
+
+ */
+
+}//namespace mbed_cc3100
+
+#endif    /*  __SIMPLELINK_H__ */
+
+