BadVPN – Blame information for rev 1
?pathlinks?
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 | */ |