/**************************************************************************** * 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 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 buffer: * 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. * * Input Parameters: * None * * Returned Value: * Zero (OK)is returned on success. A negated errno value is returned * on any failure. * ****************************************************************************/ #if 0 /* REVISIT: (1) Not yet integrated into assertion handlers and (2) 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. */ int syslog_flush(void); #endif /**************************************************************************** * Name: _vsyslog * * Description: * _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 _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 */