1 /** 2 * @file 3 * OS abstraction layer 4 */ 5 6 /* 7 * Copyright (c) 2001-2004 Swedish Institute of Computer Science. 8 * All rights reserved. 9 * 10 * Redistribution and use in source and binary forms, with or without modification, 11 * are permitted provided that the following conditions are met: 12 * 13 * 1. Redistributions of source code must retain the above copyright notice, 14 * this list of conditions and the following disclaimer. 15 * 2. Redistributions in binary form must reproduce the above copyright notice, 16 * this list of conditions and the following disclaimer in the documentation 17 * and/or other materials provided with the distribution. 18 * 3. The name of the author may not be used to endorse or promote products 19 * derived from this software without specific prior written permission. 20 * 21 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED 22 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 23 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT 24 * SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 25 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT 26 * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 27 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 28 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING 29 * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY 30 * OF SUCH DAMAGE. 31 * 32 * This file is part of the lwIP TCP/IP stack. 33 * 34 * Author: Adam Dunkels <adam@sics.se> 35 */ 36 37 #ifndef LWIP_HDR_SYS_H 38 #define LWIP_HDR_SYS_H 39 40 #include "lwip/opt.h" 41 42 #ifdef __cplusplus 43 extern "C" { 44 #endif 45 46 #if NO_SYS 47 48 /* For a totally minimal and standalone system, we provide null 49 definitions of the sys_ functions. */ 50 typedef u8_t sys_sem_t; 51 typedef u8_t sys_mutex_t; 52 typedef u8_t sys_mbox_t; 53 54 #define sys_sem_new(s, c) ERR_OK 55 #define sys_sem_signal(s) 56 #define sys_sem_wait(s) 57 #define sys_arch_sem_wait(s,t) 58 #define sys_sem_free(s) 59 #define sys_sem_valid(s) 0 60 #define sys_sem_valid_val(s) 0 61 #define sys_sem_set_invalid(s) 62 #define sys_sem_set_invalid_val(s) 63 #define sys_mutex_new(mu) ERR_OK 64 #define sys_mutex_lock(mu) 65 #define sys_mutex_unlock(mu) 66 #define sys_mutex_free(mu) 67 #define sys_mutex_valid(mu) 0 68 #define sys_mutex_set_invalid(mu) 69 #define sys_mbox_new(m, s) ERR_OK 70 #define sys_mbox_fetch(m,d) 71 #define sys_mbox_tryfetch(m,d) 72 #define sys_mbox_post(m,d) 73 #define sys_mbox_trypost(m,d) 74 #define sys_mbox_free(m) 75 #define sys_mbox_valid(m) 76 #define sys_mbox_valid_val(m) 77 #define sys_mbox_set_invalid(m) 78 #define sys_mbox_set_invalid_val(m) 79 80 #define sys_thread_new(n,t,a,s,p) 81 82 #define sys_msleep(t) 83 84 #else /* NO_SYS */ 85 86 /** Return code for timeouts from sys_arch_mbox_fetch and sys_arch_sem_wait */ 87 #define SYS_ARCH_TIMEOUT 0xffffffffUL 88 89 /** sys_mbox_tryfetch() returns SYS_MBOX_EMPTY if appropriate. 90 * For now we use the same magic value, but we allow this to change in future. 91 */ 92 #define SYS_MBOX_EMPTY SYS_ARCH_TIMEOUT 93 94 #include "lwip/err.h" 95 #include "arch/sys_arch.h" 96 97 /** Function prototype for thread functions */ 98 typedef void (*lwip_thread_fn)(void *arg); 99 100 /* Function prototypes for functions to be implemented by platform ports 101 (in sys_arch.c) */ 102 103 /* Mutex functions: */ 104 105 /** Define LWIP_COMPAT_MUTEX if the port has no mutexes and binary semaphores 106 should be used instead */ 107 #ifndef LWIP_COMPAT_MUTEX 108 #define LWIP_COMPAT_MUTEX 0 109 #endif 110 111 #if LWIP_COMPAT_MUTEX 112 /* for old ports that don't have mutexes: define them to binary semaphores */ 113 #define sys_mutex_t sys_sem_t 114 #define sys_mutex_new(mutex) sys_sem_new(mutex, 1) 115 #define sys_mutex_lock(mutex) sys_sem_wait(mutex) 116 #define sys_mutex_unlock(mutex) sys_sem_signal(mutex) 117 #define sys_mutex_free(mutex) sys_sem_free(mutex) 118 #define sys_mutex_valid(mutex) sys_sem_valid(mutex) 119 #define sys_mutex_set_invalid(mutex) sys_sem_set_invalid(mutex) 120 121 #else /* LWIP_COMPAT_MUTEX */ 122 123 /** 124 * @ingroup sys_mutex 125 * Create a new mutex. 126 * Note that mutexes are expected to not be taken recursively by the lwIP code, 127 * so both implementation types (recursive or non-recursive) should work. 128 * The mutex is allocated to the memory that 'mutex' 129 * points to (which can be both a pointer or the actual OS structure). 130 * If the mutex has been created, ERR_OK should be returned. Returning any 131 * other error will provide a hint what went wrong, but except for assertions, 132 * no real error handling is implemented. 133 * 134 * @param mutex pointer to the mutex to create 135 * @return ERR_OK if successful, another err_t otherwise 136 */ 137 err_t sys_mutex_new(sys_mutex_t *mutex); 138 /** 139 * @ingroup sys_mutex 140 * Blocks the thread until the mutex can be grabbed. 141 * @param mutex the mutex to lock 142 */ 143 void sys_mutex_lock(sys_mutex_t *mutex); 144 /** 145 * @ingroup sys_mutex 146 * Releases the mutex previously locked through 'sys_mutex_lock()'. 147 * @param mutex the mutex to unlock 148 */ 149 void sys_mutex_unlock(sys_mutex_t *mutex); 150 /** 151 * @ingroup sys_mutex 152 * Deallocates a mutex. 153 * @param mutex the mutex to delete 154 */ 155 void sys_mutex_free(sys_mutex_t *mutex); 156 #ifndef sys_mutex_valid 157 /** 158 * @ingroup sys_mutex 159 * Returns 1 if the mutes is valid, 0 if it is not valid. 160 * When using pointers, a simple way is to check the pointer for != NULL. 161 * When directly using OS structures, implementing this may be more complex. 162 * This may also be a define, in which case the function is not prototyped. 163 */ 164 int sys_mutex_valid(sys_mutex_t *mutex); 165 #endif 166 #ifndef sys_mutex_set_invalid 167 /** 168 * @ingroup sys_mutex 169 * Invalidate a mutex so that sys_mutex_valid() returns 0. 170 * ATTENTION: This does NOT mean that the mutex shall be deallocated: 171 * sys_mutex_free() is always called before calling this function! 172 * This may also be a define, in which case the function is not prototyped. 173 */ 174 void sys_mutex_set_invalid(sys_mutex_t *mutex); 175 #endif 176 #endif /* LWIP_COMPAT_MUTEX */ 177 178 /* Semaphore functions: */ 179 180 /** 181 * @ingroup sys_sem 182 * Create a new semaphore 183 * Creates a new semaphore. The semaphore is allocated to the memory that 'sem' 184 * points to (which can be both a pointer or the actual OS structure). 185 * The "count" argument specifies the initial state of the semaphore (which is 186 * either 0 or 1). 187 * If the semaphore has been created, ERR_OK should be returned. Returning any 188 * other error will provide a hint what went wrong, but except for assertions, 189 * no real error handling is implemented. 190 * 191 * @param sem pointer to the semaphore to create 192 * @param count initial count of the semaphore 193 * @return ERR_OK if successful, another err_t otherwise 194 */ 195 err_t sys_sem_new(sys_sem_t *sem, u8_t count); 196 /** 197 * @ingroup sys_sem 198 * Signals a semaphore 199 * @param sem the semaphore to signal 200 */ 201 void sys_sem_signal(sys_sem_t *sem); 202 /** 203 * @ingroup sys_sem 204 * Blocks the thread while waiting for the semaphore to be signaled. If the 205 * "timeout" argument is non-zero, the thread should only be blocked for the 206 * specified time (measured in milliseconds). If the "timeout" argument is zero, 207 * the thread should be blocked until the semaphore is signalled. 208 * 209 * The return value is SYS_ARCH_TIMEOUT if the semaphore wasn't signaled within 210 * the specified time or any other value if it was signaled (with or without 211 * waiting). 212 * Notice that lwIP implements a function with a similar name, 213 * sys_sem_wait(), that uses the sys_arch_sem_wait() function. 214 * 215 * @param sem the semaphore to wait for 216 * @param timeout timeout in milliseconds to wait (0 = wait forever) 217 * @return SYS_ARCH_TIMEOUT on timeout, any other value on success 218 */ 219 u32_t sys_arch_sem_wait(sys_sem_t *sem, u32_t timeout); 220 /** 221 * @ingroup sys_sem 222 * Deallocates a semaphore. 223 * @param sem semaphore to delete 224 */ 225 void sys_sem_free(sys_sem_t *sem); 226 /** Wait for a semaphore - forever/no timeout */ 227 #define sys_sem_wait(sem) sys_arch_sem_wait(sem, 0) 228 #ifndef sys_sem_valid 229 /** 230 * @ingroup sys_sem 231 * Returns 1 if the semaphore is valid, 0 if it is not valid. 232 * When using pointers, a simple way is to check the pointer for != NULL. 233 * When directly using OS structures, implementing this may be more complex. 234 * This may also be a define, in which case the function is not prototyped. 235 */ 236 int sys_sem_valid(sys_sem_t *sem); 237 #endif 238 #ifndef sys_sem_set_invalid 239 /** 240 * @ingroup sys_sem 241 * Invalidate a semaphore so that sys_sem_valid() returns 0. 242 * ATTENTION: This does NOT mean that the semaphore shall be deallocated: 243 * sys_sem_free() is always called before calling this function! 244 * This may also be a define, in which case the function is not prototyped. 245 */ 246 void sys_sem_set_invalid(sys_sem_t *sem); 247 #endif 248 #ifndef sys_sem_valid_val 249 /** 250 * Same as sys_sem_valid() but taking a value, not a pointer 251 */ 252 #define sys_sem_valid_val(sem) sys_sem_valid(&(sem)) 253 #endif 254 #ifndef sys_sem_set_invalid_val 255 /** 256 * Same as sys_sem_set_invalid() but taking a value, not a pointer 257 */ 258 #define sys_sem_set_invalid_val(sem) sys_sem_set_invalid(&(sem)) 259 #endif 260 261 #ifndef sys_msleep 262 /** 263 * @ingroup sys_misc 264 * Sleep for specified number of ms 265 */ 266 void sys_msleep(u32_t ms); /* only has a (close to) 1 ms resolution. */ 267 #endif 268 269 /* Mailbox functions. */ 270 271 /** 272 * @ingroup sys_mbox 273 * Creates an empty mailbox for maximum "size" elements. Elements stored 274 * in mailboxes are pointers. You have to define macros "_MBOX_SIZE" 275 * in your lwipopts.h, or ignore this parameter in your implementation 276 * and use a default size. 277 * If the mailbox has been created, ERR_OK should be returned. Returning any 278 * other error will provide a hint what went wrong, but except for assertions, 279 * no real error handling is implemented. 280 * 281 * @param mbox pointer to the mbox to create 282 * @param size (minimum) number of messages in this mbox 283 * @return ERR_OK if successful, another err_t otherwise 284 */ 285 err_t sys_mbox_new(sys_mbox_t *mbox, int size); 286 /** 287 * @ingroup sys_mbox 288 * Post a message to an mbox - may not fail 289 * -> blocks if full, only to be used from tasks NOT from ISR! 290 * 291 * @param mbox mbox to posts the message 292 * @param msg message to post (ATTENTION: can be NULL) 293 */ 294 void sys_mbox_post(sys_mbox_t *mbox, void *msg); 295 /** 296 * @ingroup sys_mbox 297 * Try to post a message to an mbox - may fail if full. 298 * Can be used from ISR (if the sys arch layer allows this). 299 * Returns ERR_MEM if it is full, else, ERR_OK if the "msg" is posted. 300 * 301 * @param mbox mbox to posts the message 302 * @param msg message to post (ATTENTION: can be NULL) 303 */ 304 err_t sys_mbox_trypost(sys_mbox_t *mbox, void *msg); 305 /** 306 * @ingroup sys_mbox 307 * Try to post a message to an mbox - may fail if full. 308 * To be be used from ISR. 309 * Returns ERR_MEM if it is full, else, ERR_OK if the "msg" is posted. 310 * 311 * @param mbox mbox to posts the message 312 * @param msg message to post (ATTENTION: can be NULL) 313 */ 314 err_t sys_mbox_trypost_fromisr(sys_mbox_t *mbox, void *msg); 315 /** 316 * @ingroup sys_mbox 317 * Blocks the thread until a message arrives in the mailbox, but does 318 * not block the thread longer than "timeout" milliseconds (similar to 319 * the sys_arch_sem_wait() function). If "timeout" is 0, the thread should 320 * be blocked until a message arrives. The "msg" argument is a result 321 * parameter that is set by the function (i.e., by doing "*msg = 322 * ptr"). The "msg" parameter maybe NULL to indicate that the message 323 * should be dropped. 324 * The return values are the same as for the sys_arch_sem_wait() function: 325 * SYS_ARCH_TIMEOUT if there was a timeout, any other value if a messages 326 * is received. 327 * 328 * Note that a function with a similar name, sys_mbox_fetch(), is 329 * implemented by lwIP. 330 * 331 * @param mbox mbox to get a message from 332 * @param msg pointer where the message is stored 333 * @param timeout maximum time (in milliseconds) to wait for a message (0 = wait forever) 334 * @return SYS_ARCH_TIMEOUT on timeout, any other value if a message has been received 335 */ 336 u32_t sys_arch_mbox_fetch(sys_mbox_t *mbox, void **msg, u32_t timeout); 337 /* Allow port to override with a macro, e.g. special timeout for sys_arch_mbox_fetch() */ 338 #ifndef sys_arch_mbox_tryfetch 339 /** 340 * @ingroup sys_mbox 341 * This is similar to sys_arch_mbox_fetch, however if a message is not 342 * present in the mailbox, it immediately returns with the code 343 * SYS_MBOX_EMPTY. On success 0 is returned. 344 * To allow for efficient implementations, this can be defined as a 345 * function-like macro in sys_arch.h instead of a normal function. For 346 * example, a naive implementation could be: 347 * \#define sys_arch_mbox_tryfetch(mbox,msg) sys_arch_mbox_fetch(mbox,msg,1) 348 * although this would introduce unnecessary delays. 349 * 350 * @param mbox mbox to get a message from 351 * @param msg pointer where the message is stored 352 * @return 0 (milliseconds) if a message has been received 353 * or SYS_MBOX_EMPTY if the mailbox is empty 354 */ 355 u32_t sys_arch_mbox_tryfetch(sys_mbox_t *mbox, void **msg); 356 #endif 357 /** 358 * For now, we map straight to sys_arch implementation. 359 */ 360 #define sys_mbox_tryfetch(mbox, msg) sys_arch_mbox_tryfetch(mbox, msg) 361 /** 362 * @ingroup sys_mbox 363 * Deallocates a mailbox. If there are messages still present in the 364 * mailbox when the mailbox is deallocated, it is an indication of a 365 * programming error in lwIP and the developer should be notified. 366 * 367 * @param mbox mbox to delete 368 */ 369 void sys_mbox_free(sys_mbox_t *mbox); 370 #define sys_mbox_fetch(mbox, msg) sys_arch_mbox_fetch(mbox, msg, 0) 371 #ifndef sys_mbox_valid 372 /** 373 * @ingroup sys_mbox 374 * Returns 1 if the mailbox is valid, 0 if it is not valid. 375 * When using pointers, a simple way is to check the pointer for != NULL. 376 * When directly using OS structures, implementing this may be more complex. 377 * This may also be a define, in which case the function is not prototyped. 378 */ 379 int sys_mbox_valid(sys_mbox_t *mbox); 380 #endif 381 #ifndef sys_mbox_set_invalid 382 /** 383 * @ingroup sys_mbox 384 * Invalidate a mailbox so that sys_mbox_valid() returns 0. 385 * ATTENTION: This does NOT mean that the mailbox shall be deallocated: 386 * sys_mbox_free() is always called before calling this function! 387 * This may also be a define, in which case the function is not prototyped. 388 */ 389 void sys_mbox_set_invalid(sys_mbox_t *mbox); 390 #endif 391 #ifndef sys_mbox_valid_val 392 /** 393 * Same as sys_mbox_valid() but taking a value, not a pointer 394 */ 395 #define sys_mbox_valid_val(mbox) sys_mbox_valid(&(mbox)) 396 #endif 397 #ifndef sys_mbox_set_invalid_val 398 /** 399 * Same as sys_mbox_set_invalid() but taking a value, not a pointer 400 */ 401 #define sys_mbox_set_invalid_val(mbox) sys_mbox_set_invalid(&(mbox)) 402 #endif 403 404 405 /** 406 * @ingroup sys_misc 407 * The only thread function: 408 * Starts a new thread named "name" with priority "prio" that will begin its 409 * execution in the function "thread()". The "arg" argument will be passed as an 410 * argument to the thread() function. The stack size to used for this thread is 411 * the "stacksize" parameter. The id of the new thread is returned. Both the id 412 * and the priority are system dependent. 413 * ATTENTION: although this function returns a value, it MUST NOT FAIL (ports have to assert this!) 414 * 415 * @param name human-readable name for the thread (used for debugging purposes) 416 * @param thread thread-function 417 * @param arg parameter passed to 'thread' 418 * @param stacksize stack size in bytes for the new thread (may be ignored by ports) 419 * @param prio priority of the new thread (may be ignored by ports) */ 420 sys_thread_t sys_thread_new(const char *name, lwip_thread_fn thread, void *arg, int stacksize, int prio); 421 422 #endif /* NO_SYS */ 423 424 /** 425 * @ingroup sys_misc 426 * sys_init() must be called before anything else. 427 * Initialize the sys_arch layer. 428 */ 429 void sys_init(void); 430 431 #ifndef sys_jiffies 432 /** 433 * Ticks/jiffies since power up. 434 */ 435 u32_t sys_jiffies(void); 436 #endif 437 438 /** 439 * @ingroup sys_time 440 * Returns the current time in milliseconds, 441 * may be the same as sys_jiffies or at least based on it. 442 * Don't care for wraparound, this is only used for time diffs. 443 * Not implementing this function means you cannot use some modules (e.g. TCP 444 * timestamps, internal timeouts for NO_SYS==1). 445 */ 446 u32_t sys_now(void); 447 448 /* Critical Region Protection */ 449 /* These functions must be implemented in the sys_arch.c file. 450 In some implementations they can provide a more light-weight protection 451 mechanism than using semaphores. Otherwise semaphores can be used for 452 implementation */ 453 #ifndef SYS_ARCH_PROTECT 454 /** SYS_LIGHTWEIGHT_PROT 455 * define SYS_LIGHTWEIGHT_PROT in lwipopts.h if you want inter-task protection 456 * for certain critical regions during buffer allocation, deallocation and memory 457 * allocation and deallocation. 458 */ 459 #if SYS_LIGHTWEIGHT_PROT 460 461 /** 462 * @ingroup sys_prot 463 * SYS_ARCH_DECL_PROTECT 464 * declare a protection variable. This macro will default to defining a variable of 465 * type sys_prot_t. If a particular port needs a different implementation, then 466 * this macro may be defined in sys_arch.h. 467 */ 468 #define SYS_ARCH_DECL_PROTECT(lev) sys_prot_t lev 469 /** 470 * @ingroup sys_prot 471 * SYS_ARCH_PROTECT 472 * Perform a "fast" protect. This could be implemented by 473 * disabling interrupts for an embedded system or by using a semaphore or 474 * mutex. The implementation should allow calling SYS_ARCH_PROTECT when 475 * already protected. The old protection level is returned in the variable 476 * "lev". This macro will default to calling the sys_arch_protect() function 477 * which should be implemented in sys_arch.c. If a particular port needs a 478 * different implementation, then this macro may be defined in sys_arch.h 479 */ 480 #define SYS_ARCH_PROTECT(lev) lev = sys_arch_protect() 481 /** 482 * @ingroup sys_prot 483 * SYS_ARCH_UNPROTECT 484 * Perform a "fast" set of the protection level to "lev". This could be 485 * implemented by setting the interrupt level to "lev" within the MACRO or by 486 * using a semaphore or mutex. This macro will default to calling the 487 * sys_arch_unprotect() function which should be implemented in 488 * sys_arch.c. If a particular port needs a different implementation, then 489 * this macro may be defined in sys_arch.h 490 */ 491 #define SYS_ARCH_UNPROTECT(lev) sys_arch_unprotect(lev) 492 sys_prot_t sys_arch_protect(void); 493 void sys_arch_unprotect(sys_prot_t pval); 494 495 #else 496 497 #define SYS_ARCH_DECL_PROTECT(lev) 498 #define SYS_ARCH_PROTECT(lev) 499 #define SYS_ARCH_UNPROTECT(lev) 500 501 #endif /* SYS_LIGHTWEIGHT_PROT */ 502 503 #endif /* SYS_ARCH_PROTECT */ 504 505 /* 506 * Macros to set/get and increase/decrease variables in a thread-safe way. 507 * Use these for accessing variable that are used from more than one thread. 508 */ 509 510 #ifndef SYS_ARCH_INC 511 #define SYS_ARCH_INC(var, val) do { \ 512 SYS_ARCH_DECL_PROTECT(old_level); \ 513 SYS_ARCH_PROTECT(old_level); \ 514 var += val; \ 515 SYS_ARCH_UNPROTECT(old_level); \ 516 } while(0) 517 #endif /* SYS_ARCH_INC */ 518 519 #ifndef SYS_ARCH_DEC 520 #define SYS_ARCH_DEC(var, val) do { \ 521 SYS_ARCH_DECL_PROTECT(old_level); \ 522 SYS_ARCH_PROTECT(old_level); \ 523 var -= val; \ 524 SYS_ARCH_UNPROTECT(old_level); \ 525 } while(0) 526 #endif /* SYS_ARCH_DEC */ 527 528 #ifndef SYS_ARCH_GET 529 #define SYS_ARCH_GET(var, ret) do { \ 530 SYS_ARCH_DECL_PROTECT(old_level); \ 531 SYS_ARCH_PROTECT(old_level); \ 532 ret = var; \ 533 SYS_ARCH_UNPROTECT(old_level); \ 534 } while(0) 535 #endif /* SYS_ARCH_GET */ 536 537 #ifndef SYS_ARCH_SET 538 #define SYS_ARCH_SET(var, val) do { \ 539 SYS_ARCH_DECL_PROTECT(old_level); \ 540 SYS_ARCH_PROTECT(old_level); \ 541 var = val; \ 542 SYS_ARCH_UNPROTECT(old_level); \ 543 } while(0) 544 #endif /* SYS_ARCH_SET */ 545 546 #ifndef SYS_ARCH_LOCKED 547 #define SYS_ARCH_LOCKED(code) do { \ 548 SYS_ARCH_DECL_PROTECT(old_level); \ 549 SYS_ARCH_PROTECT(old_level); \ 550 code; \ 551 SYS_ARCH_UNPROTECT(old_level); \ 552 } while(0) 553 #endif /* SYS_ARCH_LOCKED */ 554 555 556 #ifdef __cplusplus 557 } 558 #endif 559 560 #endif /* LWIP_HDR_SYS_H */ 561