diff --git a/Documentation/NuttxPortingGuide.html b/Documentation/NuttxPortingGuide.html index c56acbbf20..c19c544a79 100644 --- a/Documentation/NuttxPortingGuide.html +++ b/Documentation/NuttxPortingGuide.html @@ -5801,6 +5801,62 @@ int syslog_initialize(enum syslog_init_e phase); There are other types of SYSLOG channel devices that may require even further initialization. For example, the file SYSLOG channel (described below) cannot be initialized until the necessary file systems have been mounted.

+

6.4.2.3 Interrupt Level SYSLOG Output

+

+ As a general statement, SYSLOG output only supports //normal// output from NuttX tasks. However, for debugging purposes, it is also useful to get SYSLOG output from interrupt level logic. In an embedded system, that is often where the most critical operations are performed. +

+

+ There are three conditions under which SYSLOG output generated from interrupt level processing can a included the SYSLOG output stream: +

+
    +
  1. +

    Low-Level Serial Output. + If you are using a SYSLOG console channel (CONFIG_SYSLOG_CONSOLE) with a serial console (CONFIG_SYSLOG_SERIAL_CONSOLE) and if the underlying architecture supports the low-level up_putc() interface(CONFIG_ARCH_LOWPUTC), then the SYLOG logic will direct the output to up_putc() which is capable of generating the serial output within the context of an interrupt handler. +

    +

    + There are a few issues in doing this however: +

    + + +
    2. +
  2. +

    In-Memory Buffering. + If the RAMLOG SYSLOG channel is supported, then all SYSLOG output is buffered in memory. Interrupt level SYSLOG output is no different than normal SYSLOG output in this case. +

    +
    3. +
  3. +

    Serialization Buffer. + A final option is the use the an interrupt buffer to buffer the interrupt level SYSLOG output. In this case: +

    + +

    + The SYSLOG interrupt buffer is enabled with CONFIG_SYSLOG_INTBUFFER. When the interrupt buffer is enabled, you must also provide the size of the interrupt buffer with CONFIG_SYSLOG_INTBUFSIZE. +

    +
    4. +
+

6.4.3 SYSLOG Channel Options

6.4.3.1 SYSLOG Console Device

diff --git a/drivers/syslog/README.txt b/drivers/syslog/README.txt index 3d3da0bdc3..07ac0cf31e 100644 --- a/drivers/syslog/README.txt +++ b/drivers/syslog/README.txt @@ -234,6 +234,63 @@ SYSLOG Channels below) cannot be initialized until the necessary file systems have been mounted. + Interrupt Level SYSLOG Output + ----------------------------- + As a general statement, SYSLOG output only supports //normal// output from + NuttX tasks. However, for debugging purposes, it is also useful to get + SYSLOG output from interrupt level logic. In an embedded system, that is + often where the most critical operations are performed. + + There are three conditions under which SYSLOG output generated from interrupt level processing can a included the SYSLOG output stream: + + 1. Low-Level Serial Output + -------------------------- + If you are using a SYSLOG console channel (CONFIG_SYSLOG_CONSOLE) with a + serial console (CONFIG_SYSLOG_SERIAL_CONSOLE) and if the underlying + architecture supports the low-level up_putc() interface + (CONFIG_ARCH_LOWPUTC), then the SYLOG logic will direct the output to + up_putc() which is capable of generating the serial output within the + context of an interrupt handler. + + There are a few issues in doing this however: + + * up_putc() is able to generate debug output in any context because it + disables serial interrupts and polls the hardware directly. These + polls may take many milliseconds and during that time, all interrupts + are disable within the interrupt handler. This, of course, interferes + with the real-time behavior of the RTOS. + * The output generated by up_putc() is immediate and in real-time. The + normal SYSLOG output, on the other hand, is buffered in the serial + driver and may be delayed with respect to the immediate output by many + lines. Therefore, the interrupt level SYSLOG ouput provided throug + up_putc() is grossly out of synchronization with other debug output + + 2. In-Memory Buffering + ---------------------- + If the RAMLOG SYSLOG channel is supported, then all SYSLOG output is + buffered in memory. Interrupt level SYSLOG output is no different than + normal SYSLOG output in this case. + + 3. Serialization Buffer + ----------------------- + A final option is the use the an "interrupt buffer" to buffer the + interrupt level SYSLOG output. In this case: + + * SYSLOG output generated from interrupt level process in not sent to + the SYSLOG channel immediately. Rather, it is buffered in the + interrupt serialization buffer. + * Later, when the next normal syslog output is generated, it will first + empty the content of the interrupt buffer to the SYSLOG device in the + proper context. It will then be followed by the normal syslog output. + In this case, the interrupt level SYSLOG output will interrupt the + normal output stream and the interrupt level SYSLOG output will be + inserted into the correct position in the SYSLOG output when the next + normal SYLOG output is generated. + + The SYSLOG interrupt buffer is enabled with CONFIG_SYSLOG_INTBUFFER. When + the interrupt buffer is enabled, you must also provide the size of the + interrupt buffer with CONFIG_SYSLOG_INTBUFSIZE. + SYSLOG Channel Options ======================