/**************************************************************************** * include/nuttx/syslog/syslog.h * The NuttX SYSLOGing interface * * Copyright (C) 2012, 2014-2016 Gregory Nutt. All rights reserved. * Author: Gregory Nutt * * 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 #include #include #include /**************************************************************************** * 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 ****************************************************************************/ /* 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 */ 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) */ #ifdef CONFIG_SYSLOG_WRITE syslog_write_t sc_write; /* Write multiple bytes */ #endif /* 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: * 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: * 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); #undef EXTERN #ifdef __cplusplus } #endif #endif /* __ASSEMBLY__ */ #endif /* __INCLUDE_NUTTX_SYSLOG_SYSLOG_H */