305 lines
11 KiB
C
305 lines
11 KiB
C
/****************************************************************************
|
|
* include/nuttx/syslog/syslog.h
|
|
* The NuttX SYSLOGing interface
|
|
*
|
|
* Copyright (C) 2012, 2014-2016 Gregory Nutt. All rights reserved.
|
|
* Author: Gregory Nutt <gnutt@nuttx.org>
|
|
*
|
|
* Redistribution and use in source and binary forms, with or without
|
|
* modification, are permitted provided that the following conditions
|
|
* are met:
|
|
*
|
|
* 1. Redistributions of source code must retain the above copyright
|
|
* notice, this list of conditions and the following disclaimer.
|
|
* 2. Redistributions in binary form must reproduce the above copyright
|
|
* notice, this list of conditions and the following disclaimer in
|
|
* the documentation and/or other materials provided with the
|
|
* distribution.
|
|
* 3. Neither the name NuttX nor the names of its contributors may be
|
|
* used to endorse or promote products derived from this software
|
|
* without specific prior written permission.
|
|
*
|
|
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
|
|
* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
|
|
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
|
|
* FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
|
|
* COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
|
|
* INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
|
|
* BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
|
|
* OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
|
|
* AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
* LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
|
|
* ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
|
* POSSIBILITY OF SUCH DAMAGE.
|
|
*
|
|
****************************************************************************/
|
|
|
|
#ifndef __INCLUDE_NUTTX_SYSLOG_SYSLOG_H
|
|
#define __INCLUDE_NUTTX_SYSLOG_SYSLOG_H
|
|
|
|
/****************************************************************************
|
|
* Included Files
|
|
****************************************************************************/
|
|
|
|
#include <nuttx/config.h>
|
|
#include <nuttx/compiler.h>
|
|
|
|
#include <sys/types.h>
|
|
#include <stdarg.h>
|
|
|
|
/****************************************************************************
|
|
* Pre-processor Definitions
|
|
****************************************************************************/
|
|
/* Configuration ************************************************************/
|
|
/* CONFIG_SYSLOG_INTBUFFER - Enables an interrupt buffer that will be used
|
|
* to serialize debug output from interrupt handlers.
|
|
* CONFIG_SYSLOG_INTBUFSIZE - The size of the interrupt buffer in bytes.
|
|
* CONFIG_SYSLOG_DEVPATH - The full path to the system logging device
|
|
*
|
|
* In addition, some SYSLOG device must also be enabled that will provide
|
|
* the syslog output "channel. As of this writing, there are two SYSLOG
|
|
* devices avaiable:
|
|
*
|
|
* 1. A RAM SYSLOGing device that will log data into a circular buffer
|
|
* that can be dumped using the NSH dmesg command. This device is
|
|
* described in the include/nuttx/syslog/ramlog.h header file.
|
|
*
|
|
* 2. And a generic character device that may be used as the SYSLOG. The
|
|
* generic device interfaces are described in this file. A disadvantage
|
|
* of using the generic character device for the SYSLOG is that it
|
|
* cannot handle debug output generated from interrupt level handlers.
|
|
*
|
|
* CONFIG_SYSLOG_CHAR - Enable the generic character device for the SYSLOG.
|
|
* The full path to the SYSLOG device is provided by CONFIG_SYSLOG_DEVPATH.
|
|
* A valid character device must exist at this path. It will by opened
|
|
* by logic in syslog_initialize() based on the current configuration.
|
|
*
|
|
* NOTE: No more than one SYSLOG device should be configured.
|
|
*/
|
|
|
|
#if defined(CONFIG_SYSLOG_CHAR) && !defined(CONFIG_SYSLOG_DEVPATH)
|
|
# define CONFIG_SYSLOG_DEVPATH "/dev/ttyS1"
|
|
#endif
|
|
|
|
#ifdef CONFIG_SYSLOG_INTBUFFER
|
|
# ifndef CONFIG_SYSLOG_INTBUFSIZE
|
|
# define CONFIG_SYSLOG_INTBUFSIZE 512
|
|
# endif
|
|
# if CONFIG_SYSLOG_INTBUFSIZE > 65535
|
|
# undef CONFIG_SYSLOG_INTBUFSIZE
|
|
# define CONFIG_SYSLOG_INTBUFSIZE 65535
|
|
# endif
|
|
#endif
|
|
|
|
/****************************************************************************
|
|
* Public Types
|
|
****************************************************************************/
|
|
|
|
/* Initialization phases */
|
|
|
|
enum syslog_init_e
|
|
{
|
|
SYSLOG_INIT_RESET = 0, /* Power on SYSLOG initializaton phase */
|
|
SYSLOG_INIT_EARLY, /* Early initialization in up_initialize() */
|
|
SYSLOG_INIT_LATE /* Late initialization in os_start(). */
|
|
};
|
|
|
|
/* This structure provides the interface to a SYSLOG device */
|
|
|
|
typedef CODE ssize_t (*syslog_write_t)(FAR const char *buf, size_t buflen);
|
|
typedef CODE int (*syslog_putc_t)(int ch);
|
|
typedef CODE int (*syslog_flush_t)(void);
|
|
|
|
struct syslog_channel_s
|
|
{
|
|
/* I/O redirection methods */
|
|
|
|
#ifdef CONFIG_SYSLOG_WRITE
|
|
syslog_write_t sc_write; /* Write multiple bytes */
|
|
#endif
|
|
syslog_putc_t sc_putc; /* Normal buffered output */
|
|
syslog_putc_t sc_force; /* Low-level output for interrupt handlers */
|
|
syslog_flush_t sc_flush; /* Flush buffered output (on crash) */
|
|
|
|
/* Implementation specific logic may follow */
|
|
};
|
|
|
|
/****************************************************************************
|
|
* Public Data
|
|
****************************************************************************/
|
|
|
|
#ifndef __ASSEMBLY__
|
|
|
|
#ifdef __cplusplus
|
|
#define EXTERN extern "C"
|
|
extern "C"
|
|
{
|
|
#else
|
|
#define EXTERN extern
|
|
#endif
|
|
|
|
/****************************************************************************
|
|
* Public Function Prototypes
|
|
****************************************************************************/
|
|
|
|
/****************************************************************************
|
|
* 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);
|
|
|
|
/****************************************************************************
|
|
* 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-specifica
|
|
* 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
|
|
|
|
/****************************************************************************
|
|
* 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
|
|
|
|
/****************************************************************************
|
|
* Name: syslog_flush
|
|
*
|
|
* Description:
|
|
* This is called by system crash-handling logic. It must flush any
|
|
* buffered data to the SYSLOG device.
|
|
*
|
|
* Interrupts are disabled at the time of the crash and this logic must
|
|
* perform the flush using low-level, non-interrupt driven logic.
|
|
*
|
|
* REVISIT: There is an implementation problem in that if a character
|
|
* driver is the underlying device, then there is no mechanism to flush
|
|
* the data buffered in the driver with interrupts disabled.
|
|
*
|
|
* Currently, this function on (a) dumps the interrupt buffer (if the
|
|
* SYSLOG interrupt buffer is enabled), and (b) only the SYSLOG interface
|
|
* supports supports the 'sc_force()' method.
|
|
*
|
|
* Input Parameters:
|
|
* None
|
|
*
|
|
* Returned Value:
|
|
* Zero (OK)is returned on success. A negated errno value is returned
|
|
* on any failure.
|
|
*
|
|
****************************************************************************/
|
|
|
|
int syslog_flush(void);
|
|
|
|
/****************************************************************************
|
|
* Name: nx_vsyslog
|
|
*
|
|
* Description:
|
|
* nx_vsyslog() handles the system logging system calls. It is functionally
|
|
* equivalent to vsyslog() except that (1) the per-process priority
|
|
* filtering has already been performed and the va_list parameter is
|
|
* passed by reference. That is because the va_list is a structure in
|
|
* some compilers and passing of structures in the NuttX sycalls does
|
|
* not work.
|
|
*
|
|
****************************************************************************/
|
|
|
|
int nx_vsyslog(int priority, FAR const IPTR char *src, FAR va_list *ap);
|
|
|
|
/****************************************************************************
|
|
* 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.
|
|
*
|
|
****************************************************************************/
|
|
|
|
#ifdef CONFIG_SYSLOG_CHARDEV
|
|
void syslog_register(void);
|
|
#endif
|
|
|
|
#undef EXTERN
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif /* __ASSEMBLY__ */
|
|
#endif /* __INCLUDE_NUTTX_SYSLOG_SYSLOG_H */
|