efd1b838e6
It is used to write the log message to the channel immediately when the log message is generated in the interrupt context, which is faster than the normal force callback. Signed-off-by: Xiang Xiao <xiaoxiang@xiaomi.com>
358 lines
13 KiB
C
358 lines
13 KiB
C
/****************************************************************************
|
|
* include/nuttx/syslog/syslog.h
|
|
* The NuttX SYSLOGing interface
|
|
*
|
|
* Licensed to the Apache Software Foundation (ASF) under one or more
|
|
* contributor license agreements. See the NOTICE file distributed with
|
|
* this work for additional information regarding copyright ownership. The
|
|
* ASF licenses this file to you under the Apache License, Version 2.0 (the
|
|
* "License"); you may not use this file except in compliance with the
|
|
* License. You may obtain a copy of the License at
|
|
*
|
|
* http://www.apache.org/licenses/LICENSE-2.0
|
|
*
|
|
* Unless required by applicable law or agreed to in writing, software
|
|
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
|
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
|
|
* License for the specific language governing permissions and limitations
|
|
* under the License.
|
|
*
|
|
****************************************************************************/
|
|
|
|
#ifndef __INCLUDE_NUTTX_SYSLOG_SYSLOG_H
|
|
#define __INCLUDE_NUTTX_SYSLOG_SYSLOG_H
|
|
|
|
/****************************************************************************
|
|
* Included Files
|
|
****************************************************************************/
|
|
|
|
#include <nuttx/config.h>
|
|
#include <nuttx/compiler.h>
|
|
#include <nuttx/streams.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 available:
|
|
*
|
|
* 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
|
|
****************************************************************************/
|
|
|
|
/* Forward declaration */
|
|
|
|
struct syslog_channel_s;
|
|
|
|
/* SYSLOG I/O redirection methods */
|
|
|
|
typedef CODE ssize_t (*syslog_write_t)(FAR struct syslog_channel_s *channel,
|
|
FAR const char *buf, size_t buflen);
|
|
typedef CODE int (*syslog_putc_t)(FAR struct syslog_channel_s *channel,
|
|
int ch);
|
|
typedef CODE int (*syslog_flush_t)(FAR struct syslog_channel_s *channel);
|
|
typedef CODE void (*syslog_close_t)(FAR struct syslog_channel_s *channel);
|
|
|
|
/* SYSLOG device operations */
|
|
|
|
struct syslog_channel_ops_s
|
|
{
|
|
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) */
|
|
syslog_write_t sc_write; /* Write multiple bytes */
|
|
syslog_write_t sc_write_force; /* Write multiple bytes for interrupt handlers */
|
|
syslog_close_t sc_close; /* Channel close callback */
|
|
};
|
|
|
|
/* This structure provides the interface to a SYSLOG channel */
|
|
|
|
struct syslog_channel_s
|
|
{
|
|
/* Channel operations */
|
|
|
|
FAR const struct syslog_channel_ops_s *sc_ops;
|
|
|
|
/* 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 struct syslog_channel_s *channel);
|
|
|
|
/****************************************************************************
|
|
* Name: syslog_channel_remove
|
|
*
|
|
* Description:
|
|
* Removes an already configured SYSLOG channel from the list of used
|
|
* channels.
|
|
*
|
|
* Input Parameters:
|
|
* channel - Provides the interface to the channel to be removed.
|
|
*
|
|
* Returned Value:
|
|
* Zero (OK) is returned on success. A negated errno value is returned
|
|
* on any failure.
|
|
*
|
|
****************************************************************************/
|
|
|
|
int syslog_channel_remove(FAR 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:
|
|
* None
|
|
*
|
|
* Returned Value:
|
|
* Zero (OK) is returned on success; a negated errno value is returned on
|
|
* any failure.
|
|
*
|
|
****************************************************************************/
|
|
|
|
#ifndef CONFIG_ARCH_SYSLOG
|
|
int syslog_initialize(void);
|
|
#else
|
|
# define syslog_initialize()
|
|
#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:
|
|
* A pointer to the new SYSLOG channel; NULL is returned on any failure.
|
|
*
|
|
****************************************************************************/
|
|
|
|
#ifdef CONFIG_SYSLOG_FILE
|
|
FAR struct syslog_channel_s *syslog_file_channel(FAR const char *devpath);
|
|
#endif
|
|
|
|
/****************************************************************************
|
|
* Name: syslog_stream_channel
|
|
*
|
|
* Description:
|
|
* Initialize to use the device stream as the SYSLOG sink.
|
|
*
|
|
* On power up, the SYSLOG facility is non-existent or limited to very
|
|
* low-level output. This function may be called later in the
|
|
* initialization sequence after full driver support has been initialized.
|
|
* (via syslog_initialize()) It installs the configured SYSLOG drivers
|
|
* and enables full SYSLOGing capability.
|
|
*
|
|
* Input Parameters:
|
|
* stream - The stream device to be used.
|
|
*
|
|
* Returned Value:
|
|
* Returns a newly created SYSLOG channel, or NULL in case of any failure.
|
|
*
|
|
****************************************************************************/
|
|
|
|
#ifdef CONFIG_SYSLOG_STREAM
|
|
FAR struct syslog_channel_s *
|
|
syslog_stream_channel(FAR struct lib_outstream_s *stream);
|
|
#endif
|
|
|
|
/****************************************************************************
|
|
* Name: syslog_putc
|
|
*
|
|
* Description:
|
|
* This is the low-level, single character, system logging interface.
|
|
*
|
|
* Input Parameters:
|
|
* ch - The character to add to the SYSLOG (must be positive).
|
|
*
|
|
* Returned Value:
|
|
* On success, the character is echoed back to the caller. A negated
|
|
* errno value is returned on any failure.
|
|
*
|
|
****************************************************************************/
|
|
|
|
int syslog_putc(int ch);
|
|
|
|
/****************************************************************************
|
|
* Name: syslog_write
|
|
*
|
|
* Description:
|
|
* This is the low-level, multiple character, system logging interface.
|
|
*
|
|
* Input Parameters:
|
|
* buffer - The buffer containing the data to be output
|
|
* buflen - The number of bytes in the buffer
|
|
*
|
|
* Returned Value:
|
|
* On success, the number of characters written is returned. A negated
|
|
* errno value is returned on any failure.
|
|
*
|
|
****************************************************************************/
|
|
|
|
ssize_t syslog_write(FAR const char *buffer, size_t buflen);
|
|
|
|
/****************************************************************************
|
|
* 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);
|
|
|
|
#undef EXTERN
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif /* __ASSEMBLY__ */
|
|
#endif /* __INCLUDE_NUTTX_SYSLOG_SYSLOG_H */
|