minix/lib/liblwip/dist/src/include/lwip/sys.h

   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  * @param mutex pointer to the mutex to create
 129  * @return ERR_OK if successful, another err_t otherwise
 130  */
 131 err_t sys_mutex_new(sys_mutex_t *mutex);
 132 /**
 133  * @ingroup sys_mutex
 134  * Lock a mutex
 135  * @param mutex the mutex to lock
 136  */
 137 void sys_mutex_lock(sys_mutex_t *mutex);
 138 /**
 139  * @ingroup sys_mutex
 140  * Unlock a mutex
 141  * @param mutex the mutex to unlock
 142  */
 143 void sys_mutex_unlock(sys_mutex_t *mutex);
 144 /**
 145  * @ingroup sys_mutex
 146  * Delete a semaphore
 147  * @param mutex the mutex to delete
 148  */
 149 void sys_mutex_free(sys_mutex_t *mutex);
 150 #ifndef sys_mutex_valid
 151 /**
 152  * @ingroup sys_mutex
 153  * Check if a mutex is valid/allocated: return 1 for valid, 0 for invalid
 154  */
 155 int sys_mutex_valid(sys_mutex_t *mutex);
 156 #endif
 157 #ifndef sys_mutex_set_invalid
 158 /**
 159  * @ingroup sys_mutex
 160  * Set a mutex invalid so that sys_mutex_valid returns 0
 161  */
 162 void sys_mutex_set_invalid(sys_mutex_t *mutex);
 163 #endif
 164 #endif /* LWIP_COMPAT_MUTEX */
 165
 166 /* Semaphore functions: */
 167
 168 /**
 169  * @ingroup sys_sem
 170  * Create a new semaphore
 171  * @param sem pointer to the semaphore to create
 172  * @param count initial count of the semaphore
 173  * @return ERR_OK if successful, another err_t otherwise
 174  */
 175 err_t sys_sem_new(sys_sem_t *sem, u8_t count);
 176 /**
 177  * @ingroup sys_sem
 178  * Signals a semaphore
 179  * @param sem the semaphore to signal
 180  */
 181 void sys_sem_signal(sys_sem_t *sem);
 182 /**
 183  * @ingroup sys_sem
 184  * Wait for a semaphore for the specified timeout
 185  * @param sem the semaphore to wait for
 186  * @param timeout timeout in milliseconds to wait (0 = wait forever)
 187  * @return time (in milliseconds) waited for the semaphore
 188  *         or SYS_ARCH_TIMEOUT on timeout
 189  */
 190 u32_t sys_arch_sem_wait(sys_sem_t *sem, u32_t timeout);
 191 /**
 192  * @ingroup sys_sem
 193  * Delete a semaphore
 194  * @param sem semaphore to delete
 195  */
 196 void sys_sem_free(sys_sem_t *sem);
 197 /** Wait for a semaphore - forever/no timeout */
 198 #define sys_sem_wait(sem)                  sys_arch_sem_wait(sem, 0)
 199 #ifndef sys_sem_valid
 200 /**
 201  * @ingroup sys_sem
 202  * Check if a semaphore is valid/allocated: return 1 for valid, 0 for invalid
 203  */
 204 int sys_sem_valid(sys_sem_t *sem);
 205 #endif
 206 #ifndef sys_sem_set_invalid
 207 /**
 208  * @ingroup sys_sem
 209  * Set a semaphore invalid so that sys_sem_valid returns 0
 210  */
 211 void sys_sem_set_invalid(sys_sem_t *sem);
 212 #endif
 213 #ifndef sys_sem_valid_val
 214 /**
 215  * Same as sys_sem_valid() but taking a value, not a pointer
 216  */
 217 #define sys_sem_valid_val(sem)       sys_sem_valid(&(sem))
 218 #endif
 219 #ifndef sys_sem_set_invalid_val
 220 /**
 221  * Same as sys_sem_set_invalid() but taking a value, not a pointer
 222  */
 223 #define sys_sem_set_invalid_val(sem) sys_sem_set_invalid(&(sem))
 224 #endif
 225
 226 #ifndef sys_msleep
 227 /**
 228  * @ingroup sys_misc
 229  * Sleep for specified number of ms
 230  */
 231 void sys_msleep(u32_t ms); /* only has a (close to) 1 ms resolution. */
 232 #endif
 233
 234 /* Mailbox functions. */
 235
 236 /**
 237  * @ingroup sys_mbox
 238  * Create a new mbox of specified size
 239  * @param mbox pointer to the mbox to create
 240  * @param size (minimum) number of messages in this mbox
 241  * @return ERR_OK if successful, another err_t otherwise
 242  */
 243 err_t sys_mbox_new(sys_mbox_t *mbox, int size);
 244 /**
 245  * @ingroup sys_mbox
 246  * Post a message to an mbox - may not fail
 247  * -> blocks if full, only used from tasks not from ISR
 248  * @param mbox mbox to posts the message
 249  * @param msg message to post (ATTENTION: can be NULL)
 250  */
 251 void sys_mbox_post(sys_mbox_t *mbox, void *msg);
 252 /**
 253  * @ingroup sys_mbox
 254  * Try to post a message to an mbox - may fail if full or ISR
 255  * @param mbox mbox to posts the message
 256  * @param msg message to post (ATTENTION: can be NULL)
 257  */
 258 err_t sys_mbox_trypost(sys_mbox_t *mbox, void *msg);
 259 /**
 260  * @ingroup sys_mbox
 261  * Wait for a new message to arrive in the mbox
 262  * @param mbox mbox to get a message from
 263  * @param msg pointer where the message is stored
 264  * @param timeout maximum time (in milliseconds) to wait for a message (0 = wait forever)
 265  * @return time (in milliseconds) waited for a message, may be 0 if not waited
 266            or SYS_ARCH_TIMEOUT on timeout
 267  *         The returned time has to be accurate to prevent timer jitter!
 268  */
 269 u32_t sys_arch_mbox_fetch(sys_mbox_t *mbox, void **msg, u32_t timeout);
 270 /* Allow port to override with a macro, e.g. special timeout for sys_arch_mbox_fetch() */
 271 #ifndef sys_arch_mbox_tryfetch
 272 /**
 273  * @ingroup sys_mbox
 274  * Wait for a new message to arrive in the mbox
 275  * @param mbox mbox to get a message from
 276  * @param msg pointer where the message is stored
 277  * @return 0 (milliseconds) if a message has been received
 278  *         or SYS_MBOX_EMPTY if the mailbox is empty
 279  */
 280 u32_t sys_arch_mbox_tryfetch(sys_mbox_t *mbox, void **msg);
 281 #endif
 282 /**
 283  * For now, we map straight to sys_arch implementation.
 284  */
 285 #define sys_mbox_tryfetch(mbox, msg) sys_arch_mbox_tryfetch(mbox, msg)
 286 /**
 287  * @ingroup sys_mbox
 288  * Delete an mbox
 289  * @param mbox mbox to delete
 290  */
 291 void sys_mbox_free(sys_mbox_t *mbox);
 292 #define sys_mbox_fetch(mbox, msg) sys_arch_mbox_fetch(mbox, msg, 0)
 293 #ifndef sys_mbox_valid
 294 /**
 295  * @ingroup sys_mbox
 296  * Check if an mbox is valid/allocated: return 1 for valid, 0 for invalid
 297  */
 298 int sys_mbox_valid(sys_mbox_t *mbox);
 299 #endif
 300 #ifndef sys_mbox_set_invalid
 301 /**
 302  * @ingroup sys_mbox
 303  * Set an mbox invalid so that sys_mbox_valid returns 0
 304  */
 305 void sys_mbox_set_invalid(sys_mbox_t *mbox);
 306 #endif
 307 #ifndef sys_mbox_valid_val
 308 /**
 309  * Same as sys_mbox_valid() but taking a value, not a pointer
 310  */
 311 #define sys_mbox_valid_val(mbox)       sys_mbox_valid(&(mbox))
 312 #endif
 313 #ifndef sys_mbox_set_invalid_val
 314 /**
 315  * Same as sys_mbox_set_invalid() but taking a value, not a pointer
 316  */
 317 #define sys_mbox_set_invalid_val(mbox) sys_mbox_set_invalid(&(mbox))
 318 #endif
 319
 320
 321 /**
 322  * @ingroup sys_misc
 323  * The only thread function:
 324  * Creates a new thread
 325  * ATTENTION: although this function returns a value, it MUST NOT FAIL (ports have to assert this!)
 326  * @param name human-readable name for the thread (used for debugging purposes)
 327  * @param thread thread-function
 328  * @param arg parameter passed to 'thread'
 329  * @param stacksize stack size in bytes for the new thread (may be ignored by ports)
 330  * @param prio priority of the new thread (may be ignored by ports) */
 331 sys_thread_t sys_thread_new(const char *name, lwip_thread_fn thread, void *arg, int stacksize, int prio);
 332
 333 #endif /* NO_SYS */
 334
 335 /* sys_init() must be called before anything else. */
 336 void sys_init(void);
 337
 338 #ifndef sys_jiffies
 339 /**
 340  * Ticks/jiffies since power up.
 341  */
 342 u32_t sys_jiffies(void);
 343 #endif
 344
 345 /**
 346  * @ingroup sys_time
 347  * Returns the current time in milliseconds,
 348  * may be the same as sys_jiffies or at least based on it.
 349  */
 350 u32_t sys_now(void);
 351
 352 /* Critical Region Protection */
 353 /* These functions must be implemented in the sys_arch.c file.
 354    In some implementations they can provide a more light-weight protection
 355    mechanism than using semaphores. Otherwise semaphores can be used for
 356    implementation */
 357 #ifndef SYS_ARCH_PROTECT
 358 /** SYS_LIGHTWEIGHT_PROT
 359  * define SYS_LIGHTWEIGHT_PROT in lwipopts.h if you want inter-task protection
 360  * for certain critical regions during buffer allocation, deallocation and memory
 361  * allocation and deallocation.
 362  */
 363 #if SYS_LIGHTWEIGHT_PROT
 364
 365 /**
 366  * @ingroup sys_prot
 367  * SYS_ARCH_DECL_PROTECT
 368  * declare a protection variable. This macro will default to defining a variable of
 369  * type sys_prot_t. If a particular port needs a different implementation, then
 370  * this macro may be defined in sys_arch.h.
 371  */
 372 #define SYS_ARCH_DECL_PROTECT(lev) sys_prot_t lev
 373 /**
 374  * @ingroup sys_prot
 375  * SYS_ARCH_PROTECT
 376  * Perform a "fast" protect. This could be implemented by
 377  * disabling interrupts for an embedded system or by using a semaphore or
 378  * mutex. The implementation should allow calling SYS_ARCH_PROTECT when
 379  * already protected. The old protection level is returned in the variable
 380  * "lev". This macro will default to calling the sys_arch_protect() function
 381  * which should be implemented in sys_arch.c. If a particular port needs a
 382  * different implementation, then this macro may be defined in sys_arch.h
 383  */
 384 #define SYS_ARCH_PROTECT(lev) lev = sys_arch_protect()
 385 /**
 386  * @ingroup sys_prot
 387  * SYS_ARCH_UNPROTECT
 388  * Perform a "fast" set of the protection level to "lev". This could be
 389  * implemented by setting the interrupt level to "lev" within the MACRO or by
 390  * using a semaphore or mutex.  This macro will default to calling the
 391  * sys_arch_unprotect() function which should be implemented in
 392  * sys_arch.c. If a particular port needs a different implementation, then
 393  * this macro may be defined in sys_arch.h
 394  */
 395 #define SYS_ARCH_UNPROTECT(lev) sys_arch_unprotect(lev)
 396 sys_prot_t sys_arch_protect(void);
 397 void sys_arch_unprotect(sys_prot_t pval);
 398
 399 #else
 400
 401 #define SYS_ARCH_DECL_PROTECT(lev)
 402 #define SYS_ARCH_PROTECT(lev)
 403 #define SYS_ARCH_UNPROTECT(lev)
 404
 405 #endif /* SYS_LIGHTWEIGHT_PROT */
 406
 407 #endif /* SYS_ARCH_PROTECT */
 408
 409 /*
 410  * Macros to set/get and increase/decrease variables in a thread-safe way.
 411  * Use these for accessing variable that are used from more than one thread.
 412  */
 413
 414 #ifndef SYS_ARCH_INC
 415 #define SYS_ARCH_INC(var, val) do { \
 416                                 SYS_ARCH_DECL_PROTECT(old_level); \
 417                                 SYS_ARCH_PROTECT(old_level); \
 418                                 var += val; \
 419                                 SYS_ARCH_UNPROTECT(old_level); \
 420                               } while(0)
 421 #endif /* SYS_ARCH_INC */
 422
 423 #ifndef SYS_ARCH_DEC
 424 #define SYS_ARCH_DEC(var, val) do { \
 425                                 SYS_ARCH_DECL_PROTECT(old_level); \
 426                                 SYS_ARCH_PROTECT(old_level); \
 427                                 var -= val; \
 428                                 SYS_ARCH_UNPROTECT(old_level); \
 429                               } while(0)
 430 #endif /* SYS_ARCH_DEC */
 431
 432 #ifndef SYS_ARCH_GET
 433 #define SYS_ARCH_GET(var, ret) do { \
 434                                 SYS_ARCH_DECL_PROTECT(old_level); \
 435                                 SYS_ARCH_PROTECT(old_level); \
 436                                 ret = var; \
 437                                 SYS_ARCH_UNPROTECT(old_level); \
 438                               } while(0)
 439 #endif /* SYS_ARCH_GET */
 440
 441 #ifndef SYS_ARCH_SET
 442 #define SYS_ARCH_SET(var, val) do { \
 443                                 SYS_ARCH_DECL_PROTECT(old_level); \
 444                                 SYS_ARCH_PROTECT(old_level); \
 445                                 var = val; \
 446                                 SYS_ARCH_UNPROTECT(old_level); \
 447                               } while(0)
 448 #endif /* SYS_ARCH_SET */
 449
 450
 451 #ifdef __cplusplus
 452 }
 453 #endif
 454
 455 #endif /* LWIP_HDR_SYS_H */