BadVPN – Blame information for rev 1

Subversion Repositories:
Rev:
Rev Author Line No. Line
1 office 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 netifs NETIFs
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 * @page zerocopyrx Zero-copy RX
105 * The following code is an example for zero-copy RX ethernet driver:
106 * @include ZeroCopyRx.c
107 */
108  
109 /**
110 * @defgroup lwip_nosys Mainloop mode ("NO_SYS")
111 * @ingroup lwip
112 * Use this mode if you do not run an OS on your system. \#define NO_SYS to 1.
113 * Feed incoming packets to netif->input(pbuf, netif) function from mainloop,
114 * *not* *from* *interrupt* *context*. You can allocate a @ref pbuf in interrupt
115 * context and put them into a queue which is processed from mainloop.\n
116 * Call sys_check_timeouts() periodically in the mainloop.\n
117 * Porting: implement all functions in @ref sys_time, @ref sys_prot and
118 * @ref compiler_abstraction.\n
119 * You can only use @ref callbackstyle_api in this mode.\n
120 * Sample code:\n
121 * @include NO_SYS_SampleCode.c
122 */
123  
124 /**
125 * @defgroup lwip_os OS mode (TCPIP thread)
126 * @ingroup lwip
127 * Use this mode if you run an OS on your system. It is recommended to
128 * use an RTOS that correctly handles priority inversion and
129 * to use @ref LWIP_TCPIP_CORE_LOCKING.\n
130 * Porting: implement all functions in @ref sys_layer.\n
131 * You can use @ref callbackstyle_api together with @ref tcpip_callback,
132 * and all @ref sequential_api.
133 */
134  
135 /**
136 * @page raw_api lwIP API
137 * @verbinclude "rawapi.txt"
138 */