/**************************************************************************** * driver/syslog/syslog_device.c * * Copyright (C) 2012, 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. * ****************************************************************************/ /**************************************************************************** * Included Files ****************************************************************************/ #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include #include "syslog.h" #if CONFIG_NFILE_DESCRIPTORS > 0 /**************************************************************************** * Pre-processor Definitions ****************************************************************************/ /* Open the device/file write-only, try to create (file) it if it doesn't * exist, if the file that already exists, then append the new log data to * end of the file. */ #define SYSLOG_OFLAGS (O_WRONLY | O_CREAT | O_APPEND) /* An invalid thread ID */ #define NO_HOLDER ((pid_t)-1) /**************************************************************************** * Private Types ****************************************************************************/ /* This enumeration represents the state of the SYSLOG device interface */ enum syslog_dev_state { SYSLOG_UNINITIALIZED = 0, /* SYSLOG has not been initialized */ SYSLOG_INITIALIZING, /* SYSLOG is being initialized */ SYSLOG_REOPEN, /* SYSLOG open failed... try again later */ SYSLOG_FAILURE, /* SYSLOG open failed... don't try again */ SYSLOG_OPENED, /* SYSLOG device is open and ready to use */ }; /* This structure contains all SYSLOGing state information */ struct syslog_dev_s { uint8_t sl_state; /* See enum syslog_dev_state */ uint8_t sl_oflags; /* Saved open mode (for re-open) */ uint16_t sl_mode; /* Saved open flags (for re-open) */ sem_t sl_sem; /* Enforces mutually exclusive access */ pid_t sl_holder; /* PID of the thread that holds the semaphore */ struct file sl_file; /* The syslog file structure */ FAR char *sl_devpath; /* Full path to the character device */ }; /**************************************************************************** * Private Data ****************************************************************************/ /* This is the device structure for the console or syslogging function. */ static struct syslog_dev_s g_syslog_dev; static const uint8_t g_syscrlf[2] = { '\r', '\n' }; /**************************************************************************** * Private Functions ****************************************************************************/ /**************************************************************************** * Name: syslog_dev_takesem * * Description: * Write to the syslog device * ****************************************************************************/ static inline int syslog_dev_takesem(void) { pid_t me = getpid(); int ret; /* Does this thread already hold the semaphore? That could happen if * we wer called recursively, i.e., if the logic kicked off by * syslog_dev_write() where to generate more debug output. Return an error * in that case. */ if (g_syslog_dev.sl_holder == me) { /* Return an error (instead of deadlocking) */ return -EWOULDBLOCK; } /* Either the semaphore is available or is currently held by another * thread. Wait for it to become available. */ ret = sem_wait(&g_syslog_dev.sl_sem); if (ret < 0) { return -get_errno(); } /* We hold the semaphore. We can safely mark ourself as the holder * of the semaphore. */ g_syslog_dev.sl_holder = me; return OK; } /**************************************************************************** * Name: syslog_dev_givesem * * Description: * Write to the syslog device * ****************************************************************************/ static inline void syslog_dev_givesem(void) { #ifdef CONFIG_DEBUG_ASSERTIONS pid_t me = getpid(); DEBUGASSERT(g_syslog_dev.sl_holder == me); #endif /* Relinquish the semaphore */ g_syslog_dev.sl_holder = NO_HOLDER; sem_post(&g_syslog_dev.sl_sem); } /**************************************************************************** * Name: syslog_dev_write * * Description: * Write to the syslog device * ****************************************************************************/ static inline ssize_t syslog_dev_write(FAR const void *buf, size_t nbytes) { FAR struct inode *inode; /* Let the driver perform the write */ inode = g_syslog_dev.sl_file.f_inode; DEBUGASSERT(inode != NULL); return inode->u.i_ops->write(&g_syslog_dev.sl_file, buf, nbytes); } /**************************************************************************** * Public Functions ****************************************************************************/ /**************************************************************************** * Name: syslog_dev_initialize * * Description: * Initialize to use the character device (or file) at * CONFIG_SYSLOG_DEVPATH as the SYSLOG sink. * * One power up, the SYSLOG facility is non-existent or limited to very * low-level output. This function may be called later in the * intialization sequence after full driver support has been initialized. * (via syslog_initialize()) It installs the configured SYSLOG drivers * and enables full SYSLOGing capability. * * NOTE that this implementation excludes using a network connection as * SYSLOG device. That would be a good extension. * * Input Parameters: * devpath - The full path to the character device to be used. * oflags - File open flags * mode - File open mode (only if oflags include O_CREAT) * * Returned Value: * Zero (OK) is returned on success; a negated errno value is returned on * any failure. * ****************************************************************************/ int syslog_dev_initialize(FAR const char *devpath, int oflags, int mode) { int fd; int ret; /* At this point, the only expected states are SYSLOG_UNINITIALIZED or * SYSLOG_REOPEN.. Not SYSLOG_INITIALIZING, SYSLOG_FAILURE, SYSLOG_OPENED. */ DEBUGASSERT(g_syslog_dev.sl_state == SYSLOG_UNINITIALIZED || g_syslog_dev.sl_state == SYSLOG_REOPEN); /* Save the the path to the device in case we have to re-open it. * If we get here and sl_devpath is not equal to NULL, that is a clue * that we will are re-openingthe file. */ if (g_syslog_dev.sl_state == SYSLOG_REOPEN) { /* Re-opening: Then we should already have a copy of the path to the * device. */ DEBUGASSERT(g_syslog_dev.sl_devpath != NULL && strcmp(g_syslog_dev.sl_devpath, devpath) == 0); } else { /* Initializing. Copy the device path so that we can use it if we * have to re-open the file. */ DEBUGASSERT(g_syslog_dev.sl_devpath == NULL); g_syslog_dev.sl_oflags = oflags; g_syslog_dev.sl_mode = mode; g_syslog_dev.sl_devpath = strdup(devpath); DEBUGASSERT(g_syslog_dev.sl_devpath != NULL); } g_syslog_dev.sl_state = SYSLOG_INITIALIZING; /* Open the device driver. */ fd = open(devpath, oflags, mode); if (fd < 0) { int errcode = get_errno(); DEBUGASSERT(errcode > 0); /* We failed to open the file. Perhaps it does exist? Perhaps it * exists, but is not ready because it depends on insertion of a * removable device? * * In any case we will attempt to re-open the device repeatedly. * The assumption is that the device path is valid but that the * driver has not yet been registered or a removable device has * not yet been installed. */ g_syslog_dev.sl_state = SYSLOG_REOPEN; return -errcode; } /* Detach the file descriptor from the file structure. The file * descriptor is a task-specific concept. Detaching the file * descriptor allows us to use the device on all threads in all tasks. */ ret = file_detach(fd, &g_syslog_dev.sl_file); if (ret < 0) { /* This should not happen and means that something very bad has * occurred. */ g_syslog_dev.sl_state = SYSLOG_FAILURE; close(fd); return ret; } /* The SYSLOG device is open and ready for writing. */ sem_init(&g_syslog_dev.sl_sem, 0, 1); g_syslog_dev.sl_holder = NO_HOLDER; g_syslog_dev.sl_state = SYSLOG_OPENED; return OK; } /**************************************************************************** * Name: syslog_dev_uninitialize * * Description: * Called to disable the last device/file channel in preparation to use * a different SYSLOG device. Currently only used for CONFIG_SYSLOG_FILE. * * Input Parameters: * None * * Returned Value: * Zero (OK) is returned on success; a negated errno value is returned on * any failure. * * Assumptions: * The caller has already switched the SYSLOG source to some safe channel * (the default channel). * ****************************************************************************/ #ifdef CONFIG_SYSLOG_FILE /* Currently only used in this configuration */ int syslog_dev_uninitialize(void) { /* Attempt to flush any buffered data */ sched_lock(); (void)syslog_dev_flush(); /* Close the detached file instance */ (void)file_close_detached(&g_syslog_dev.sl_file); /* Free the device path */ if (g_syslog_dev.sl_devpath != NULL) { kmm_free(g_syslog_dev.sl_devpath); } /* Destroy the semaphore */ sem_destroy(&g_syslog_dev.sl_sem); /* Reset the state structure */ memset(&g_syslog_dev, 0, sizeof(struct syslog_dev_s)); sched_unlock(); return OK; } #endif /* CONFIG_SYSLOG_FILE */ /**************************************************************************** * Name: syslog_dev_putc * * Description: * This is the low-level system logging interface provided for the * character driver 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_dev_putc(int ch) { ssize_t nbytes; uint8_t uch; int errcode; int ret; /* Ignore any output: * * (1) Before the SYSLOG device has been initialized. This could happen * from debug output that occurs early in the boot sequence before * syslog_dev_initialize() is called (SYSLOG_UNINITIALIZED). * (2) While the device is being initialized. The case could happen if * debug output is generated while syslog_dev_initialize() executes * (SYSLOG_INITIALIZING). * (3) While we are generating SYSLOG output. The case could happen if * debug output is generated while syslog_dev_putc() executes * (This case is actually handled inside of syslog_semtake()). * (4) Any debug output generated from interrupt handlers. A disadvantage * of using the generic character device for the SYSLOG is that it * cannot handle debug output generated from interrupt level handlers. * (5) Any debug output generated from the IDLE loop. The character * driver interface is blocking and the IDLE thread is not permitted * to block. * (6) If an irrecoverable failure occurred during initialization. In * this case, we won't ever bother to try again (ever). * * NOTE: That the third case is different. It applies only to the thread * that currently holds the sl_sem sempaphore. Other threads should wait. * that is why that case is handled in syslog_semtake(). */ /* Cases (4) and (5) */ if (up_interrupt_context() || getpid() == 0) { errcode = ENOSYS; goto errout_with_errcode; } /* We can save checks in the usual case: That after the SYSLOG device * has been successfully opened. */ if (g_syslog_dev.sl_state != SYSLOG_OPENED) { /* Case (1) and (2) */ if (g_syslog_dev.sl_state == SYSLOG_UNINITIALIZED || g_syslog_dev.sl_state == SYSLOG_INITIALIZING) { errcode = EAGAIN; /* Can't access the SYSLOG now... maybe next time? */ goto errout_with_errcode; } /* Case (6) */ if (g_syslog_dev.sl_state == SYSLOG_FAILURE) { errcode = ENXIO; /* There is no SYSLOG device */ goto errout_with_errcode; } /* syslog_dev_initialize() is called as soon as enough of the operating * system is in place to support the open operation... but it is * possible that the SYSLOG device is not yet registered at that time. * In this case, we know that the system is sufficiently initialized * to support an attempt to re-open the SYSLOG device. * * NOTE that the scheduler is locked. That is because we do not have * fully initialized semaphore capability until the SYSLOG device is * successfully initialized */ sched_lock(); if (g_syslog_dev.sl_state == SYSLOG_REOPEN) { /* Try again to initialize the device. We may do this repeatedly * because the log device might be something that was not ready * the first time that syslog_dev_initializee() was called (such as a * USB serial device that has not yet been connected or a file in * an NFS mounted file system that has not yet been mounted). */ DEBUGASSERT(g_syslog_dev.sl_devpath != NULL); ret = syslog_dev_initialize(g_syslog_dev.sl_devpath, (int)g_syslog_dev.sl_oflags, (int)g_syslog_dev.sl_mode); if (ret < 0) { sched_unlock(); errcode = -ret; goto errout_with_errcode; } } sched_unlock(); DEBUGASSERT(g_syslog_dev.sl_state == SYSLOG_OPENED); } /* Ignore carriage returns */ if (ch == '\r') { return ch; } /* The syslog device is ready for writing and we have something of * value to write. */ ret = syslog_dev_takesem(); if (ret < 0) { /* We probably already hold the semaphore and were probably * re-entered by the logic kicked off by syslog_dev_write(). * We might also have been interrupted by a signal. Either * way, we are outta here. */ errcode = -ret; goto errout_with_errcode; } /* Pre-pend a newline with a carriage return. */ if (ch == '\n') { /* Write the CR-LF sequence */ nbytes = syslog_dev_write(g_syscrlf, 2); /* Synchronize the file when each CR-LF is encountered (i.e., * implements line buffering always). */ #ifndef CONFIG_DISABLE_MOUNTPOINT if (nbytes > 0) { (void)syslog_dev_flush(); } #endif } else { /* Write the non-newline character (and don't flush) */ uch = (uint8_t)ch; nbytes = syslog_dev_write(&uch, 1); } syslog_dev_givesem(); /* Check if the write was successful. If not, nbytes will be * a negated errno value. */ if (nbytes < 0) { errcode = -ret; goto errout_with_errcode; } return ch; errout_with_errcode: set_errno(errcode); return EOF; } /**************************************************************************** * Name: syslog_dev_flush * * Description: * Flush any buffer data in the file system to media. * * Input Parameters: * None * * Returned Value: * Zero (OK) on success; a negated errno value is returned on any failure. * ****************************************************************************/ int syslog_dev_flush(void) { int ret = 0;; #ifndef CONFIG_DISABLE_MOUNTPOINT FAR struct inode *inode = g_syslog_dev.sl_file.f_inode; /* Is this a mountpoint? Does it support the sync method? */ if (inode != NULL && /* File opened (i.e., has inode)? */ INODE_IS_MOUNTPT(inode) && /* Inode is a mountpoint? */ inode->u.i_mops->sync != NULL) /* And supports synce method? */ { /* Yes... synchronize to the stream */ ret = inode->u.i_mops->sync(&g_syslog_dev.sl_file); } #endif return ret; } #endif /* CONFIG_NFILE_DESCRIPTORS > 0 */