fnet_stack.h

00001 /**************************************************************************
00002 *
00003 * Copyright 2011-2015 by Andrey Butok. FNET Community.
00004 * Copyright 2008-2010 by Andrey Butok. Freescale Semiconductor, Inc.
00005 *
00006 ***************************************************************************
00007 *
00008 *  Licensed under the Apache License, Version 2.0 (the "License"); you may
00009 *  not use this file except in compliance with the License.
00010 *  You may obtain a copy of the License at
00011 *
00012 *  http://www.apache.org/licenses/LICENSE-2.0
00013 *
00014 *  Unless required by applicable law or agreed to in writing, software
00015 *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
00016 *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00017 *  See the License for the specific language governing permissions and
00018 *  limitations under the License.
00019 *
00020 **********************************************************************/
00021 /*!
00022 * @brief Main including header for the FNET TCP/IP stack.
00023 *
00024 ***************************************************************************/
00025 
00026 #ifndef _FNET_STACK_H_
00027 
00028 #define _FNET_STACK_H_
00029 
00030 #include "fnet_assert.h"
00031 #include "fnet_error.h"
00032 #include "fnet_stdlib.h"
00033 #include "fnet_socket.h"
00034 #include "fnet_inet.h"
00035 #include "fnet_ip.h"
00036 #include "fnet_ip6.h"
00037 #include "fnet_netif.h"
00038 #include "fnet_timer.h"
00039 #include "fnet_debug.h"
00040 #include "fnet_eth.h"
00041 #include "fnet_isr.h"
00042 #include "fnet_netbuf.h"
00043 #include "fnet_arp.h"
00044 
00045 /*! @addtogroup fnet_stack_init
00046 * - The @ref fnet.h file includes all the other header files needed to use the FNET TCP/IP stack
00047 *   user interface. This means that it is the only file the application developer needs to include
00048 *   in the source code using the FNET stack API.
00049 * - The @ref fnet_init() function must be called
00050 *   in order to initialize the FNET TCP/IP stack.
00051 *   The return value from @ref fnet_init() must be verified to indicate the success before
00052 *   calling any other TCP/IP functions.
00053 * - After @ref fnet_init() returns the @ref FNET_OK value, the FNET TCP/IP stack is ready
00054 *   for use.
00055 * - Initialize required networking interfaces using @ref fnet_netif_init().
00056 *
00057 * For example:
00058 * @code
00059 * ...
00060 *    static fnet_uint8_t stack_heap[FAPP_CFG_HEAP_SIZE];
00061 *    struct fnet_init_params init_params;
00062 *
00063 *    // Input parameters for FNET stack initialization.
00064 *    init_params.netheap_ptr = stack_heap;
00065 *    init_params.netheap_size = sizeof(stack_heap);
00066 *
00067 *    // Init FNET stack.
00068 *    if(fnet_init(&init_params) != FNET_ERR)
00069 *    {
00070 *        // Initialize Network Interfaces.
00071          ,,,
00072 *        // Place your code here.
00073 *    }
00074 *    else
00075 *        fnet_printf("ERROR: FNET stack initialization is failed!\n");
00076 * ...
00077 * @endcode
00078 */
00079 /*! @{ */
00080 
00081 #if FNET_CFG_MULTITHREADING || defined(__DOXYGEN__)
00082 
00083 /**************************************************************************/ /*!
00084  * @brief Mutex type.
00085  * @see FNET_CFG_MULTITHREADING,
00086  ******************************************************************************/
00087 typedef void *fnet_mutex_t;
00088 
00089 /**************************************************************************/ /*!
00090  * @brief Mutex API.
00091  * It should be defined by application if @ref FNET_CFG_MULTITHREADING is enabled.
00092  * @see FNET_CFG_MULTITHREADING, fnet_init()
00093  ******************************************************************************/
00094 typedef struct
00095 {
00096     fnet_return_t (*mutex_init)( fnet_mutex_t * ); /**< @brief Create a new mutex. Parameter is pointer to the mutex to create. */
00097     void (*mutex_free)( fnet_mutex_t * ); /**< @brief  Delete a mutex. Parameter is pointer to the mutex to delete. */
00098     void (*mutex_lock)( fnet_mutex_t * ); /**< @brief  Lock a mutex. Parameter is the mutex to lock. */
00099     void (*mutex_unlock)( fnet_mutex_t * ); /**< @brief Unlock a mutex. Parameter is the mutex to unlock.  */
00100 } fnet_mutex_api_t;
00101 #endif /* FNET_CFG_MULTITHREADING */
00102 
00103 
00104 /**************************************************************************/ /*!
00105  * @brief Input parameters structure for @ref fnet_init()
00106  ******************************************************************************/
00107 struct fnet_init_params
00108 {
00109     void                        *netheap_ptr;   /**< @brief Pointer to the FNET heap buffer. @n
00110                                                 * @n
00111                                                 * The FNET uses this heap buffer for the internal
00112                                                 * dynamic data allocation as:
00113                                                 *  - Ethernet Tx/Rx frame buffers.
00114                                                 *  - Sockets Input/Output buffers.
00115                                                 *  - Protocol headers and service information.
00116                                                 *  - Various control structures.
00117                                                 *  - Temporary data.@n
00118                                                 * @n
00119                                                 * An application can allocate this buffer statically,
00120                                                 * dynamically, or use a special memory region (for example SRAM).*/
00121     fnet_size_t                 netheap_size;   /**< @brief Size of the FNET heap buffer. */
00122 #if FNET_CFG_MULTITHREADING || defined(__DOXYGEN__)
00123     const fnet_mutex_api_t      *mutex_api;    /**< @brief Mutex API. It is optional and availble only when FNET_CFG_MULTITHREADING is set.*/
00124 #endif
00125 };
00126 
00127 #if defined(__cplusplus)
00128 extern "C" {
00129 #endif
00130 
00131 /***************************************************************************/ /*!
00132  *
00133  * @brief    Initializes the FNET TCP/IP stack.
00134  *
00135  * @param init_params    Pointer to the initialization parameter structure.
00136  *
00137  * @return   This function returns:
00138  *   - @c FNET_OK  = Stack initialization is successful.
00139  *   - @c FNET_ERR = Stack initialization has failed.
00140  *
00141  *
00142  * @see fnet_release()
00143  *
00144  ******************************************************************************
00145  *
00146  * This function executes the initialization of the FNET TCP/IP stack.@n
00147  * Only after a succesful initialization, the application may use other FNET API
00148  * functions and services.
00149  *
00150  ******************************************************************************/
00151 fnet_return_t fnet_init( struct fnet_init_params *init_params );
00152 
00153 /***************************************************************************/ /*!
00154  *
00155  * @brief    Releases the FNET TCP/IP stack.
00156  *
00157  * @see fnet_init()
00158  *
00159  ******************************************************************************
00160  *
00161  * This function releases all resources occupied by the FNET TCP/IP stack.
00162  * But it does not release resources occupied by FNET services.
00163  *
00164  ******************************************************************************/
00165 void fnet_release(void);
00166 
00167 #if defined(__cplusplus)
00168 }
00169 #endif
00170 
00171 /*! @} */
00172 
00173 #endif /* _FNET_STACK_H_ */
00174