1/** 2 * @defgroup lwip lwIP 3 * 4 * @defgroup infrastructure Infrastructure 5 * 6 * @defgroup callbackstyle_api Callback-style APIs 7 * Non thread-safe APIs, callback style for maximum performance and minimum 8 * memory footprint. 9 * 10 * @defgroup sequential_api Sequential-style APIs 11 * Sequential-style APIs, blocking functions. More overhead, but can be called 12 * from any thread except TCPIP thread. 13 * 14 * @defgroup addons Addons 15 * 16 * @defgroup apps Applications 17 */ 18 19/** 20 * @mainpage Overview 21 * @verbinclude "README" 22 */ 23 24/** 25 * @page upgrading Upgrading 26 * @verbinclude "UPGRADING" 27 */ 28 29/** 30 * @page changelog Changelog 31 * @verbinclude "CHANGELOG" 32 */ 33 34/** 35 * @page contrib How to contribute to lwIP 36 * @verbinclude "contrib.txt" 37 */ 38 39/** 40 * @page pitfalls Common pitfalls 41 * 42 * Multiple Execution Contexts in lwIP code 43 * ======================================== 44 * 45 * The most common source of lwIP problems is to have multiple execution contexts 46 * inside the lwIP code. 47 * 48 * lwIP can be used in two basic modes: @ref lwip_nosys (no OS/RTOS 49 * running on target system) or @ref lwip_os (there is an OS running 50 * on the target system). 51 * 52 * Mainloop Mode 53 * ------------- 54 * In mainloop mode, only @ref callbackstyle_api can be used. 55 * The user has two possibilities to ensure there is only one 56 * exection context at a time in lwIP: 57 * 58 * 1) Deliver RX ethernet packets directly in interrupt context to lwIP 59 * by calling netif->input directly in interrupt. This implies all lwIP 60 * callback functions are called in IRQ context, which may cause further 61 * problems in application code: IRQ is blocked for a long time, multiple 62 * execution contexts in application code etc. When the application wants 63 * to call lwIP, it only needs to disable interrupts during the call. 64 * If timers are involved, even more locking code is needed to lock out 65 * timer IRQ and ethernet IRQ from each other, assuming these may be nested. 66 * 67 * 2) Run lwIP in a mainloop. There is example code here: @ref lwip_nosys. 68 * lwIP is _ONLY_ called from mainloop callstacks here. The ethernet IRQ 69 * has to put received telegrams into a queue which is polled in the 70 * mainloop. Ensure lwIP is _NEVER_ called from an interrupt, e.g. 71 * some SPI IRQ wants to forward data to udp_send() or tcp_write()! 72 * 73 * OS Mode 74 * ------- 75 * In OS mode, @ref callbackstyle_api AND @ref sequential_api can be used. 76 * @ref sequential_api are designed to be called from threads other than 77 * the TCPIP thread, so there is nothing to consider here. 78 * But @ref callbackstyle_api functions must _ONLY_ be called from 79 * TCPIP thread. It is a common error to call these from other threads 80 * or from IRQ contexts. ���Ethernet RX needs to deliver incoming packets 81 * in the correct way by sending a message to TCPIP thread, this is 82 * implemented in tcpip_input().������ 83 * Again, ensure lwIP is _NEVER_ called from an interrupt, e.g. 84 * some SPI IRQ wants to forward data to udp_send() or tcp_write()! 85 * 86 * 1) tcpip_callback() can be used get called back from TCPIP thread, 87 * it is safe to call any @ref callbackstyle_api from there. 88 * 89 * 2) Use @ref LWIP_TCPIP_CORE_LOCKING. All @ref callbackstyle_api 90 * functions can be called when lwIP core lock is aquired, see 91 * @ref LOCK_TCPIP_CORE() and @ref UNLOCK_TCPIP_CORE(). 92 * These macros cannot be used in an interrupt context! 93 * Note the OS must correctly handle priority inversion for this. 94 */ 95 96/** 97 * @page bugs Reporting bugs 98 * Please report bugs in the lwIP bug tracker at savannah.\n 99 * BEFORE submitting, please check if the bug has already been reported!\n 100 * https://savannah.nongnu.org/bugs/?group=lwip 101 */ 102 103/** 104 * @defgroup lwip_nosys Mainloop mode ("NO_SYS") 105 * @ingroup lwip 106 * Use this mode if you do not run an OS on your system. \#define NO_SYS to 1. 107 * Feed incoming packets to netif->input(pbuf, netif) function from mainloop, 108 * *not* *from* *interrupt* *context*. You can allocate a @ref pbuf in interrupt 109 * context and put them into a queue which is processed from mainloop.\n 110 * Call sys_check_timeouts() periodically in the mainloop.\n 111 * Porting: implement all functions in @ref sys_time, @ref sys_prot and 112 * @ref compiler_abstraction.\n 113 * You can only use @ref callbackstyle_api in this mode.\n 114 * Sample code:\n 115 * @include NO_SYS_SampleCode.c 116 */ 117 118/** 119 * @defgroup lwip_os OS mode (TCPIP thread) 120 * @ingroup lwip 121 * Use this mode if you run an OS on your system. It is recommended to 122 * use an RTOS that correctly handles priority inversion and 123 * to use @ref LWIP_TCPIP_CORE_LOCKING.\n 124 * Porting: implement all functions in @ref sys_layer.\n 125 * You can use @ref callbackstyle_api together with @ref tcpip_callback, 126 * and all @ref sequential_api. 127 */ 128 129/** 130 * @page raw_api lwIP API 131 * @verbinclude "rawapi.txt" 132 */ 133