[DELAYIMP] Fix 2 Clang-Cl warnings about __pfnDliNotifyHook2Default and __pfnDliFailu...
[reactos.git] / sdk / lib / drivers / lwip / doc / sys_arch.txt
1 sys_arch interface for lwIP 0.6++
2
3 Author: Adam Dunkels
4
5 The operating system emulation layer provides a common interface
6 between the lwIP code and the underlying operating system kernel. The
7 general idea is that porting lwIP to new architectures requires only
8 small changes to a few header files and a new sys_arch
9 implementation. It is also possible to do a sys_arch implementation
10 that does not rely on any underlying operating system.
11
12 The sys_arch provides semaphores and mailboxes to lwIP. For the full
13 lwIP functionality, multiple threads support can be implemented in the
14 sys_arch, but this is not required for the basic lwIP
15 functionality. Previous versions of lwIP required the sys_arch to
16 implement timer scheduling as well but as of lwIP 0.5 this is
17 implemented in a higher layer.
18
19 In addition to the source file providing the functionality of sys_arch,
20 the OS emulation layer must provide several header files defining
21 macros used throughout lwip. The files required and the macros they
22 must define are listed below the sys_arch description.
23
24 Semaphores can be either counting or binary - lwIP works with both
25 kinds. Mailboxes are used for message passing and can be implemented
26 either as a queue which allows multiple messages to be posted to a
27 mailbox, or as a rendez-vous point where only one message can be
28 posted at a time. lwIP works with both kinds, but the former type will
29 be more efficient. A message in a mailbox is just a pointer, nothing
30 more.
31
32 Semaphores are represented by the type "sys_sem_t" which is typedef'd
33 in the sys_arch.h file. Mailboxes are equivalently represented by the
34 type "sys_mbox_t". lwIP does not place any restrictions on how
35 sys_sem_t or sys_mbox_t are represented internally.
36
37 Since lwIP 1.4.0, semaphore and mailbox functions are prototyped in a way that
38 allows both using pointers or actual OS structures to be used. This way, memory
39 required for such types can be either allocated in place (globally or on the
40 stack) or on the heap (allocated internally in the "*_new()" functions).
41
42 The following functions must be implemented by the sys_arch:
43
44 - void sys_init(void)
45
46 Is called to initialize the sys_arch layer.
47
48 - err_t sys_sem_new(sys_sem_t *sem, u8_t count)
49
50 Creates a new semaphore. The semaphore is allocated to the memory that 'sem'
51 points to (which can be both a pointer or the actual OS structure).
52 The "count" argument specifies the initial state of the semaphore (which is
53 either 0 or 1).
54 If the semaphore has been created, ERR_OK should be returned. Returning any
55 other error will provide a hint what went wrong, but except for assertions,
56 no real error handling is implemented.
57
58 - void sys_sem_free(sys_sem_t *sem)
59
60 Deallocates a semaphore.
61
62 - void sys_sem_signal(sys_sem_t *sem)
63
64 Signals a semaphore.
65
66 - u32_t sys_arch_sem_wait(sys_sem_t *sem, u32_t timeout)
67
68 Blocks the thread while waiting for the semaphore to be
69 signaled. If the "timeout" argument is non-zero, the thread should
70 only be blocked for the specified time (measured in
71 milliseconds). If the "timeout" argument is zero, the thread should be
72 blocked until the semaphore is signalled.
73
74 If the timeout argument is non-zero, the return value is the number of
75 milliseconds spent waiting for the semaphore to be signaled. If the
76 semaphore wasn't signaled within the specified time, the return value is
77 SYS_ARCH_TIMEOUT. If the thread didn't have to wait for the semaphore
78 (i.e., it was already signaled), the function may return zero.
79
80 Notice that lwIP implements a function with a similar name,
81 sys_sem_wait(), that uses the sys_arch_sem_wait() function.
82
83 - int sys_sem_valid(sys_sem_t *sem)
84
85 Returns 1 if the semaphore is valid, 0 if it is not valid.
86 When using pointers, a simple way is to check the pointer for != NULL.
87 When directly using OS structures, implementing this may be more complex.
88 This may also be a define, in which case the function is not prototyped.
89
90 - void sys_sem_set_invalid(sys_sem_t *sem)
91
92 Invalidate a semaphore so that sys_sem_valid() returns 0.
93 ATTENTION: This does NOT mean that the semaphore shall be deallocated:
94 sys_sem_free() is always called before calling this function!
95 This may also be a define, in which case the function is not prototyped.
96
97 - err_t sys_mbox_new(sys_mbox_t *mbox, int size)
98
99 Creates an empty mailbox for maximum "size" elements. Elements stored
100 in mailboxes are pointers. You have to define macros "_MBOX_SIZE"
101 in your lwipopts.h, or ignore this parameter in your implementation
102 and use a default size.
103 If the mailbox has been created, ERR_OK should be returned. Returning any
104 other error will provide a hint what went wrong, but except for assertions,
105 no real error handling is implemented.
106
107 - void sys_mbox_free(sys_mbox_t *mbox)
108
109 Deallocates a mailbox. If there are messages still present in the
110 mailbox when the mailbox is deallocated, it is an indication of a
111 programming error in lwIP and the developer should be notified.
112
113 - void sys_mbox_post(sys_mbox_t *mbox, void *msg)
114
115 Posts the "msg" to the mailbox. This function have to block until
116 the "msg" is really posted.
117
118 - err_t sys_mbox_trypost(sys_mbox_t *mbox, void *msg)
119
120 Try to post the "msg" to the mailbox. Returns ERR_MEM if this one
121 is full, else, ERR_OK if the "msg" is posted.
122
123 - u32_t sys_arch_mbox_fetch(sys_mbox_t *mbox, void **msg, u32_t timeout)
124
125 Blocks the thread until a message arrives in the mailbox, but does
126 not block the thread longer than "timeout" milliseconds (similar to
127 the sys_arch_sem_wait() function). If "timeout" is 0, the thread should
128 be blocked until a message arrives. The "msg" argument is a result
129 parameter that is set by the function (i.e., by doing "*msg =
130 ptr"). The "msg" parameter maybe NULL to indicate that the message
131 should be dropped.
132
133 The return values are the same as for the sys_arch_sem_wait() function:
134 Number of milliseconds spent waiting or SYS_ARCH_TIMEOUT if there was a
135 timeout.
136
137 Note that a function with a similar name, sys_mbox_fetch(), is
138 implemented by lwIP.
139
140 - u32_t sys_arch_mbox_tryfetch(sys_mbox_t *mbox, void **msg)
141
142 This is similar to sys_arch_mbox_fetch, however if a message is not
143 present in the mailbox, it immediately returns with the code
144 SYS_MBOX_EMPTY. On success 0 is returned.
145
146 To allow for efficient implementations, this can be defined as a
147 function-like macro in sys_arch.h instead of a normal function. For
148 example, a naive implementation could be:
149 #define sys_arch_mbox_tryfetch(mbox,msg) \
150 sys_arch_mbox_fetch(mbox,msg,1)
151 although this would introduce unnecessary delays.
152
153 - int sys_mbox_valid(sys_mbox_t *mbox)
154
155 Returns 1 if the mailbox is valid, 0 if it is not valid.
156 When using pointers, a simple way is to check the pointer for != NULL.
157 When directly using OS structures, implementing this may be more complex.
158 This may also be a define, in which case the function is not prototyped.
159
160 - void sys_mbox_set_invalid(sys_mbox_t *mbox)
161
162 Invalidate a mailbox so that sys_mbox_valid() returns 0.
163 ATTENTION: This does NOT mean that the mailbox shall be deallocated:
164 sys_mbox_free() is always called before calling this function!
165 This may also be a define, in which case the function is not prototyped.
166
167 If threads are supported by the underlying operating system and if
168 such functionality is needed in lwIP, the following function will have
169 to be implemented as well:
170
171 - sys_thread_t sys_thread_new(char *name, void (* thread)(void *arg), void *arg, int stacksize, int prio)
172
173 Starts a new thread named "name" with priority "prio" that will begin its
174 execution in the function "thread()". The "arg" argument will be passed as an
175 argument to the thread() function. The stack size to used for this thread is
176 the "stacksize" parameter. The id of the new thread is returned. Both the id
177 and the priority are system dependent.
178
179 - sys_prot_t sys_arch_protect(void)
180
181 This optional function does a "fast" critical region protection and returns
182 the previous protection level. This function is only called during very short
183 critical regions. An embedded system which supports ISR-based drivers might
184 want to implement this function by disabling interrupts. Task-based systems
185 might want to implement this by using a mutex or disabling tasking. This
186 function should support recursive calls from the same task or interrupt. In
187 other words, sys_arch_protect() could be called while already protected. In
188 that case the return value indicates that it is already protected.
189
190 sys_arch_protect() is only required if your port is supporting an operating
191 system.
192
193 - void sys_arch_unprotect(sys_prot_t pval)
194
195 This optional function does a "fast" set of critical region protection to the
196 value specified by pval. See the documentation for sys_arch_protect() for
197 more information. This function is only required if your port is supporting
198 an operating system.
199
200 For some configurations, you also need:
201
202 - u32_t sys_now(void)
203
204 This optional function returns the current time in milliseconds (don't care
205 for wraparound, this is only used for time diffs).
206 Not implementing this function means you cannot use some modules (e.g. TCP
207 timestamps, internal timeouts for NO_SYS==1).
208
209
210 Note:
211
212 Be carefull with using mem_malloc() in sys_arch. When malloc() refers to
213 mem_malloc() you can run into a circular function call problem. In mem.c
214 mem_init() tries to allcate a semaphore using mem_malloc, which of course
215 can't be performed when sys_arch uses mem_malloc.
216
217 -------------------------------------------------------------------------------
218 Additional files required for the "OS support" emulation layer:
219 -------------------------------------------------------------------------------
220
221 cc.h - Architecture environment, some compiler specific, some
222 environment specific (probably should move env stuff
223 to sys_arch.h.)
224
225 Typedefs for the types used by lwip -
226 u8_t, s8_t, u16_t, s16_t, u32_t, s32_t, mem_ptr_t
227
228 Compiler hints for packing lwip's structures -
229 PACK_STRUCT_FIELD(x)
230 PACK_STRUCT_STRUCT
231 PACK_STRUCT_BEGIN
232 PACK_STRUCT_END
233
234 Platform specific diagnostic output -
235 LWIP_PLATFORM_DIAG(x) - non-fatal, print a message.
236 LWIP_PLATFORM_ASSERT(x) - fatal, print message and abandon execution.
237 Portability defines for printf formatters:
238 U16_F, S16_F, X16_F, U32_F, S32_F, X32_F, SZT_F
239
240 "lightweight" synchronization mechanisms -
241 SYS_ARCH_DECL_PROTECT(x) - declare a protection state variable.
242 SYS_ARCH_PROTECT(x) - enter protection mode.
243 SYS_ARCH_UNPROTECT(x) - leave protection mode.
244
245 If the compiler does not provide memset() this file must include a
246 definition of it, or include a file which defines it.
247
248 This file must either include a system-local <errno.h> which defines
249 the standard *nix error codes, or it should #define LWIP_PROVIDE_ERRNO
250 to make lwip/arch.h define the codes which are used throughout.
251
252
253 perf.h - Architecture specific performance measurement.
254 Measurement calls made throughout lwip, these can be defined to nothing.
255 PERF_START - start measuring something.
256 PERF_STOP(x) - stop measuring something, and record the result.
257
258 sys_arch.h - Tied to sys_arch.c
259
260 Arch dependent types for the following objects:
261 sys_sem_t, sys_mbox_t, sys_thread_t,
262 And, optionally:
263 sys_prot_t
264
265 Defines to set vars of sys_mbox_t and sys_sem_t to NULL.
266 SYS_MBOX_NULL NULL
267 SYS_SEM_NULL NULL