Page History

SYSLOG

...

Interfaces

Standard SYSLOG Interfaces

The NuttX SYSLOG is an architecture for getting debug and status information from the system. The syslogging interfaces are defined in the header file include/syslog.h. The primary interface to SYSLOG sub-system is the function syslog() and, to a lesser extent, its companion vsyslog():

    /****************************************************************************
   * Name: syslog and

...

 vsyslog
   *
   * Description:
   *   syslog() generates a log message. The priority argument is formed

...

 by
   *   ORing the facility and the level values (see include/syslog.h).

...

 The
   *   remaining arguments are a format, as in printf and any arguments to the
   *   format.
   *
   *   The NuttX implementation does not support any special formatting
   *   characters beyond those supported by printf.
   *
   *   The function vsyslog() performs the same task as syslog() with the
   *   difference that it takes a set of arguments which have been obtained
   *   using the stdarg variable argument list macros.
   *
   ****************************************************************************/

...

    
    int syslog(int priority, FAR const IPTR char *format, ...);
    int vsyslog(int priority, FAR const IPTR char *src, va_list ap);

The additional setlogmask() interface can use use to filter SYSLOG output:

    /****************************************************************************
   * Name:

...

 setlogmask
   *
   * Description:
   *   The setlogmask() function sets the logmask and returns the

...

 previous
   *   mask. If the mask argument is 0, the current logmask is not modified.

...

   *
   *   The SYSLOG priorities are: LOG_EMERG, LOG_ALERT, LOG_CRIT, LOG_ERR,

...

   *   LOG_WARNING, LOG_NOTICE, LOG_INFO, and LOG_DEBUG.  The bit

...

 corresponding
   *   to a priority p is LOG_MASK(p); LOG_UPTO(p) provides the mask of

...

 all
   *   priorities in the above list up to and including p.
   *
   *   Per OpenGroup.org "If the maskpri argument is 0, the current log mask
   *   is not modified."  In this implementation, the value zero is permitted
   *   in order to disable all syslog levels.
   *
   *   REVISIT: Per POSIX the syslog mask should be a per-process value but in
   *   NuttX, the scope of the mask is dependent on the nature of the build:
   *
   *   Flat Build:  There is one, global SYSLOG mask that controls all output.
   *   Protected Build:  There are two SYSLOG masks.  One within the kernel
   *     that controls only kernel output.  And one in user-space that controls
   *     only user SYSLOG output.
   *   Kernel Build:  The kernel build is compliant with the POSIX requirement:
   *     There will be one mask for for each user process, controlling the
   *     SYSLOG output only form that process.  There will be a separate mask
   *     accessable only in the kernel code to control kernel SYSLOG output.
   *
   ****************************************************************************/

...

    
    int setlogmask(int mask);

...

These are all standard interfaces as defined at OpenGroup.org.

Debug Interfaces

In NuttX, syslog output is really synonymous to debug output and, therefore, the debugging interface macros defined in the header file include/debug.h are also syslogging interfaces. Those macros are simply wrappers around syslog(). The debugging interfaces differ from the syslog interfaces in that:

...

• info(). The info() macro is the lowest priority (LOG_INFO) and is intended to provide general information about the flow of program execution so that you can get an overview of the behavior of the program. info() is often very chatty and voluminous and usually more information than you may want to see. The info() macro is controlled via CONFIG_DEBUG+subsystem+INFO
• warn(). The warn() macro has medium priority (LOG_WARN) and is controlled by CONFIG_DEBUG+subsystem+WARN. The warn() is intended to note exceptional or unexpected conditions that meigh be potential errors or, perhaps, minor errors that easily recovered.
• err(). This is a high priority debug macro (LOG_ERROR) and controlled by CONFIG_DEBUG+subsystem+ERROR. The err() is reserved to indicate important error conditions.
• alert(). The highest priority debug macro (LOG_EMERG) and is controlled by CONFIG_DEBUG_ALERT. The alert() macro is reserved for use solely by assertion and crash handling logic. It also differs from the other macros in that it is global and cannot be enabled or disabled per subsystem.

SYSLOG Channels

SYSLOG Channel Interfaces

In the NuttX SYSLOG implementation, the underlying device logic the supports the SYSLOG output is referred to as a SYSLOG channel. Each SYSLOG channel is represented by an interface defined in include/nuttx/syslog/syslog.h:

...

The channel interface is instantiated by calling syslog_channel():

    /****************************************************************************
* Name: syslog_channel

...

*
* Description:

...

* Configure the SYSLOGging function to use the provided channel to

...

* generate SYSLOG output.

...

*
* Input Parameters:

...

* channel - Provides the interface to the channel to be used.

...

*
* Returned Value:

...

* Zero (OK)is returned on success. A negated errno value is returned

...

* on any failure.

...

*
****************************************************************************/

...

    
    int syslog_channel(FAR const struct syslog_channel_s *channel);

syslog_channel() is a non-standard, internal OS interface and is not available to applications. It may be called numerous times as necessary to change channel interfaces. By default, all system log output goes to console (/dev/console).

SYSLOG Channel Initialization

The initial, default SYSLOG channel is established with statically initialized global variables so that some level of SYSLOG output may be available immediately upon reset. This initialized data is in the file drivers/syslog/syslog_channel.c. The initial SYSLOG capability is determined by the selected SYSLOG channel:

...

The syslog channel device is initialized when the bring-up logic calls syslog_intialize():

    /****************************************************************************
   * Name: syslog_initialize

...

   *
   * Description:
   *   One power up, the SYSLOG facility is non-existent or limited to very
   *   low-level output.  This function is called later in the initialization
   *   sequence after full driver support has been initialized.  It installs
   *   the configured SYSLOG drivers and enables full SYSLOGing capability.
   *
   *   This function performs these basic operations:
   *
   *   - Initialize the SYSLOG device
   *   - Call syslog_channel() to begin using that device.
   *
   *   If CONFIG_ARCH_SYSLOG is selected, then the architecture-specific
   *   logic will provide its own SYSLOG device initialize which must include
   *   as a minimum a call to syslog_channel() to use the device.
   *
   * Input Parameters:
   *   phase - One of {SYSLOG_INIT_EARLY, SYSLOG_INIT_LATE}

...

   *
   * Returned Value:
   *   Zero (OK) is returned on success; a negated errno value is returned

...

 on
   *   any failure.
   *
   ****************************************************************************/

...

    
    #ifndef CONFIG_ARCH_SYSLOG
    int syslog_initialize(enum syslog_init_e phase);
    #else
    #  define syslog_initialize(phase)
    #endif

Different types of SYSLOG devices have different OS initialization requirements. Some are available immediately at reset, some are available after some basic OS initialization, and some only after OS is fully initialized. In order to satisfy these different initialization requirements, syslog_initialize() is called twice from the boot-up logic:

...

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.

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.

...

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

SYSLOG Console Device

The typical SYSLOG device is the system console. If you are using a serial console, for example, then the SYSLOG output will appear on that serial port.

...

References: drivers/syslog/syslog_consolechannel.c and drivers/syslog/syslog_device.c

SYSLOG Character Device

The system console device, /dev/console, is a character driver with some special properties. However, any character driver may be used as the SYSLOG output channel. For example, suppose you have a serial console on /dev/ttyS0 and you want SYSLOG output on /dev/ttyS1. Or suppose you support only a Telnet console but want to capture debug output /dev/ttyS0.

...

References: drivers/syslog/syslog_devchannel.c and drivers/syslog/syslog_device.c

SYSLOG File Device

Files can also be used as the sink for SYSLOG output. There is, however, a very fundamental difference in using a file as opposed the system console, a RAM buffer, or character device: You must first mount the file system that supports the SYSLOG file. That difference means that the file SYSLOG channel cannot be supported during the boot-up phase but can be instantiated later when board level logic configures the application environment, including mounting of the file systems.

The interface syslog_file_channel() is used to configure the SYSLOG file channel:

    /****************************************************************************
   * Name: syslog_file_channel

...

   *
   * Description:
   *   Configure to use a file in a mounted file system at 'devpath' as the
   *   SYSLOG channel.
   *
   *   This tiny function is simply a wrapper around syslog_dev_initialize()

...

   *   and syslog_channel().  It calls syslog_dev_initialize() to

...

 configure
   *   the character file at 'devpath then calls syslog_channel() to use

...

 that
   *   device as the SYSLOG output channel.
   *
   *   File SYSLOG channels differ from other SYSLOG channels in that they
   *   cannot be established until after fully booting and mounting the target
   *   file system.  This function would need to be called from board-specific
   *   bring-up logic AFTER mounting the file system containing 'devpath'.
   *
   *   SYSLOG data generated prior to calling syslog_file_channel will, of
   *   course, not be included in the file.
   *
   *   NOTE interrupt level SYSLOG output will be lost in this case unless
   *   the interrupt buffer is used.
   *
   * Input Parameters:
   *   devpath - The full path to the file to be used for SYSLOG output.
   *     This may be an existing file or not.  If the file exists,
   *     syslog_file_channel() will append new SYSLOG data to the end of

...

 the
   *     file.  If it does not, then syslog_file_channel() will create

...

 the
   *     file.
   *
   * Returned Value:
   *   Zero (OK) is returned on success; a negated errno value is returned on
   *   any failure.
   *
   ****************************************************************************/

...

    
    #ifdef CONFIG_SYSLOG_FILE
    int syslog_file_channel(FAR const char *devpath);
    #endif
    

References: drivers/syslog/syslog_filechannel.c, drivers/syslog/syslog_device.c, and include/nuttx/syslog/syslog.h.

SYSLOG RAMLOG Device

The RAMLOG is a standalone feature that can be used to buffer any character data in memory. There are, however, special configurations that can be used to configure the RAMLOG as a SYSLOG channel. The RAMLOG functionality is described in a more general way in the following paragraphs.

RAM Logging Device

The RAM logging driver is a driver that was intended to support debugging output (SYSLOG) when the normal serial output is not available. For example, if you are using a Telnet or USB serial console, the debug output will get lost – or worse. For example, what if you want to debug the network over Telnet?

...

This driver is built when CONFIG_RAMLOG is defined in the Nuttx configuration.

dmesg

When the RAMLOG (with SYSLOG) is enabled, a new NuttShell (NSH) command will appear: dmesg. The dmsg command will dump the contents of the circular buffer to the console (and also clear the circular buffer).

RAMLOG Configuration options

• CONFIG_RAMLOG - Enables the RAM logging feature

...

• CONFIG_RAMLOG_NPOLLWAITERS - The maximum number of threads that may be waiting on the poll method.

SYSLOG (Input) Character Device

If the option CONFIG_SYSLOG_CHARDEV is selected then support for a special character device at /dev/syslog is supported. The function {{ syslog_register()}} can be used to register that character device:

    /****************************************************************************
   * Name: syslog_register

...

   *
   * Description:
   *   Register a simple character driver at /dev/syslog whose write()

...

 method
   *   will transfer data to the SYSLOG device.  This can be useful if, for
   *   example, you want to redirect the output of a program to the SYSLOG.
   *
   *   NOTE that unlike other syslog output, this data is unformatted raw
   *   byte output with no time-stamping or any other SYSLOG features
   *   supported.
   *
   ****************************************************************************/

...

    
    void syslog_register(void);

...