main_page.h

00001 /**
00002  * @defgroup lwip lwIP
00003  *
00004  * @defgroup infrastructure Infrastructure
00005  *
00006  * @defgroup callbackstyle_api Callback-style APIs
00007  * Non thread-safe APIs, callback style for maximum performance and minimum
00008  * memory footprint.
00009  * 
00010  * @defgroup sequential_api Sequential-style APIs
00011  * Sequential-style APIs, blocking functions. More overhead, but can be called
00012  * from any thread except TCPIP thread.
00013  * 
00014  * @defgroup addons Addons
00015  * 
00016  * @defgroup apps Applications
00017  */
00018 
00019 /**
00020  * @mainpage Overview
00021  * @verbinclude "README"
00022  */
00023 
00024 /**
00025  * @page upgrading Upgrading
00026  * @verbinclude "UPGRADING"
00027  */
00028 
00029 /**
00030  * @page contrib How to contribute to lwIP
00031  * @verbinclude "contrib.txt"
00032  */
00033 
00034 /**
00035  * @page pitfalls Common pitfalls
00036  *
00037  * Multiple Execution Contexts in lwIP code
00038  * ========================================
00039  *
00040  * The most common source of lwIP problems is to have multiple execution contexts
00041  * inside the lwIP code.
00042  * 
00043  * lwIP can be used in two basic modes: @ref lwip_nosys (no OS/RTOS 
00044  * running on target system) or @ref lwip_os (there is an OS running
00045  * on the target system).
00046  *
00047  * Mainloop Mode
00048  * -------------
00049  * In mainloop mode, only @ref callbackstyle_api can be used.
00050  * The user has two possibilities to ensure there is only one 
00051  * exection context at a time in lwIP:
00052  *
00053  * 1) Deliver RX ethernet packets directly in interrupt context to lwIP
00054  *    by calling netif->input directly in interrupt. This implies all lwIP 
00055  *    callback functions are called in IRQ context, which may cause further
00056  *    problems in application code: IRQ is blocked for a long time, multiple
00057  *    execution contexts in application code etc. When the application wants
00058  *    to call lwIP, it only needs to disable interrupts during the call.
00059  *    If timers are involved, even more locking code is needed to lock out
00060  *    timer IRQ and ethernet IRQ from each other, assuming these may be nested.
00061  *
00062  * 2) Run lwIP in a mainloop. There is example code here: @ref lwip_nosys.
00063  *    lwIP is _ONLY_ called from mainloop callstacks here. The ethernet IRQ
00064  *    has to put received telegrams into a queue which is polled in the
00065  *    mainloop. Ensure lwIP is _NEVER_ called from an interrupt, e.g.
00066  *    some SPI IRQ wants to forward data to udp_send() or tcp_write()!
00067  *
00068  * OS Mode
00069  * -------
00070  * In OS mode, @ref callbackstyle_api AND @ref sequential_api can be used.
00071  * @ref sequential_api are designed to be called from threads other than
00072  * the TCPIP thread, so there is nothing to consider here.
00073  * But @ref callbackstyle_api functions must _ONLY_ be called from
00074  * TCPIP thread. It is a common error to call these from other threads
00075  * or from IRQ contexts. ​Ethernet RX needs to deliver incoming packets
00076  * in the correct way by sending a message to TCPIP thread, this is
00077  * implemented in tcpip_input().​​
00078  * Again, ensure lwIP is _NEVER_ called from an interrupt, e.g.
00079  * some SPI IRQ wants to forward data to udp_send() or tcp_write()!
00080  * 
00081  * 1) tcpip_callback() can be used get called back from TCPIP thread,
00082  *    it is safe to call any @ref callbackstyle_api from there.
00083  *
00084  * 2) Use @ref LWIP_TCPIP_CORE_LOCKING. All @ref callbackstyle_api
00085  *    functions can be called when lwIP core lock is aquired, see
00086  *    @ref LOCK_TCPIP_CORE() and @ref UNLOCK_TCPIP_CORE().
00087  *    These macros cannot be used in an interrupt context!
00088  *    Note the OS must correctly handle priority inversion for this.
00089  */
00090 
00091 /**
00092  * @page bugs Reporting bugs
00093  * Please report bugs in the lwIP bug tracker at savannah.\n
00094  * BEFORE submitting, please check if the bug has already been reported!\n
00095  * https://savannah.nongnu.org/bugs/?group=lwip
00096  */
00097 
00098 /**
00099  * @defgroup lwip_nosys Mainloop mode ("NO_SYS")
00100  * @ingroup lwip
00101  * Use this mode if you do not run an OS on your system. \#define NO_SYS to 1.
00102  * Feed incoming packets to netif->input(pbuf, netif) function from mainloop,
00103  * *not* *from* *interrupt* *context*. You can allocate a @ref pbuf in interrupt
00104  * context and put them into a queue which is processed from mainloop.\n
00105  * Call sys_check_timeouts() periodically in the mainloop.\n
00106  * Porting: implement all functions in @ref sys_time, @ref sys_prot and 
00107  * @ref compiler_abstraction.\n
00108  * You can only use @ref callbackstyle_api in this mode.\n
00109  * Sample code:\n
00110  * @include NO_SYS_SampleCode.c
00111  */
00112 
00113 /**
00114  * @defgroup lwip_os OS mode (TCPIP thread)
00115  * @ingroup lwip
00116  * Use this mode if you run an OS on your system. It is recommended to
00117  * use an RTOS that correctly handles priority inversion and
00118  * to use @ref LWIP_TCPIP_CORE_LOCKING.\n
00119  * Porting: implement all functions in @ref sys_layer.\n
00120  * You can use @ref callbackstyle_api together with @ref tcpip_callback,
00121  * and all @ref sequential_api.
00122  */
00123 
00124 /**
00125  * @page raw_api lwIP API
00126  * @verbinclude "rawapi.txt"
00127  */