third_party/lwip/repo/lwip/doc/doxygen/main_page.h

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