123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455 |
- /*
- *
- * Copyright (c) 2003 The Regents of the University of California. All
- * rights reserved.
- *
- * Redistribution and use in source and binary forms, with or without
- * modification, are permitted provided that the following conditions
- * are met:
- *
- * - Redistributions of source code must retain the above copyright
- * notice, this list of conditions and the following disclaimer.
- *
- * - Neither the name of the University 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 REGENTS 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 REGENTS 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.
- *
- */
-
- /*
- * FUSD - The Framework for UserSpace Devices - Example program
- *
- * Jeremy Elson <jelson@circlemud.org>
- *
- * logring.c: Implementation of a circular buffer log device
- *
- * logring makes it easy to access the most recent (and only the most
- * recent) output from a process. It works just like "tail -f" on a
- * log file, except that the storage required never grows. This can be
- * useful in embedded systems where there isn't enough memory or disk
- * space for keeping complete log files, but the most recent debugging
- * messages are sometimes needed (e.g., after an error is observed).
- *
- * Logring uses FUSD to implement a character device, /dev/logring,
- * that acts like a named pipe that has a finite, circular buffer.
- * The size of the buffer is given as a command-line argument. As
- * more data is written into the buffer, the oldest data is discarded.
- * A process that reads from the logring device will first read the
- * existing buffer, then block and see new data as it's written,
- * similar to monitoring a log file using "tail -f".
- *
- * Non-blocking reads are supported; if a process needs to get the
- * current contents of the log without blocking to wait for new data,
- * it can set the O_NONBLOCK flag when it does the open(), or set it
- * later using ioctl().
- *
- * The select() interface is also supported; programs can select on
- * /dev/logring to be notified when new data is available.
- *
- * Run this example program by typing "logring X", where X is the size
- * of the circular buffer in bytes. Then, type "cat /dev/logring" in
- * one shell. The cat process will block, waiting for data, similar
- * to "tail -f". From another shell, write to the logring (e.g.,
- * "echo Hi there > /dev/logring".) The 'cat' process will see the
- * message appear.
- *
- * Note: this example program is based on "emlog", a true Linux kernel
- * module with identical functionality. If you find logring useful,
- * but want to use it on a system that does not have FUSD, check out
- * emlog at http://www.circlemud.org/~jelson/software/emlog.
- *
- * $Id: logring.c 12351 2007-01-19 07:22:54Z xiphmont $
- */
- #include <stdio.h>
- #include <stdlib.h>
- #include <string.h>
- #include <errno.h>
- #include <fcntl.h>
- #include <fusd.h>
- /* per-client structure to keep track of who has an open FD to us */
- struct logring_client {
- /* used to store outstanding read and polldiff requests */
- struct fusd_file_info *read;
- struct fusd_file_info *polldiff;
- /* to construct the linked list */
- struct logring_client *next;
- };
- /* list of currently open file descriptors */
- struct logring_client *client_list = NULL;
- char *logring_data = NULL; /* the data buffer used for the logring */
- int logring_size = 0; /* buffer space in the logring */
- int logring_writeindex = 0; /* write point in the logring array */
- int logring_readindex = 0; /* read point in the logring array */
- int logring_offset = 0; /* how far into the total stream is
- * logring_read pointing? */
- /* amount of data in the queue */
- #define LOGRING_QLEN (logring_writeindex >= logring_readindex ? \
- logring_writeindex - logring_readindex : \
- logring_size - logring_readindex + logring_writeindex)
- /* stream byte number of the last byte in the queue */
- #define LOGRING_FIRST_EMPTY_BYTE (logring_offset + LOGRING_QLEN)
- #define MIN(x, y) ((x) < (y) ? (x) : (y))
- /************************************************************************/
- /*
- * this function removes an element from a linked list. the
- * pointer-manipulation insanity below is a trick that prevents the
- * "element to be removed is the head of the list" from being a
- * special case.
- */
- void client_list_remove(struct logring_client *c)
- {
- struct logring_client **ptr;
- if (c == NULL || client_list == NULL)
- return;
- for (ptr = &client_list; *ptr != c; ptr = &((**ptr).next)) {
- if (!*ptr) {
- fprintf(stderr, "trying to remove a client that isn't in the list\n");
- return;
- }
- }
- *ptr = c->next;
- }
- /* open on /dev/logring: create state for this client */
- static int logring_open(struct fusd_file_info *file)
- {
- /* create state for this client */
- struct logring_client *c = malloc(sizeof(struct logring_client));
- if (c == NULL)
- return -ENOBUFS;
- /* initialize fields of this client state */
- memset(c, 0, sizeof(struct logring_client));
- /* save the pointer to this state so it gets returned to us later */
- file->private_data = c;
- /* add this client to the client list */
- c->next = client_list;
- client_list = c;
-
- return 0;
- }
- /* close on /dev/logring: destroy state for this client */
- static int logring_close(struct fusd_file_info *file)
- {
- struct logring_client *c;
- if ((c = (struct logring_client *) file->private_data) != NULL) {
- /* take this client off our client list */
- client_list_remove(c);
- /* if there is a read outstanding, free the state */
- if (c->read != NULL) {
- fusd_destroy(c->read);
- c->read = NULL;
- }
- /* destroy any outstanding polldiffs */
- if (c->polldiff != NULL) {
- fusd_destroy(c->polldiff);
- c->polldiff = NULL;
- }
- /* get rid of the struct */
- free(c);
- file->private_data = NULL;
- }
- return 0;
- }
- /*
- * This function "completes" a read: that is, matches up a client who
- * is requesting data with data that's waiting to be served.
- *
- * This function is called in two cases:
- *
- * 1- When a new read request comes in (it might be able to complete
- * immediately, if there's data waiting that the client hasn't seen
- * yet)
- *
- * 2- When new data comes in (the new data might be able to complete
- * a read that had been previously blocked)
- */
- void logring_complete_read(struct logring_client *c)
- {
- loff_t *user_offset;
- char *user_buffer;
- size_t user_length;
- int bytes_copied = 0, n, start_point, retval;
- /* if there is no outstanding read, do nothing */
- if (c == NULL || c->read == NULL)
- return;
- /* retrieve the read callback's arguments */
- user_offset = fusd_get_offset(c->read);
- user_buffer = fusd_get_read_buffer(c->read);
- user_length = fusd_get_length(c->read);
- /* is the client trying to read data that has scrolled off? */
- if (*user_offset < logring_offset)
- *user_offset = logring_offset;
- /* is there new data this user hasn't seen yet, or are we at EOF? */
- /* If we have reached EOF:
- * If this is a nonblocking read, return EAGAIN.
- * else return without doing anything; keep the read blocked.
- */
- if (*user_offset >= LOGRING_FIRST_EMPTY_BYTE) {
- if (c->read->flags & O_NONBLOCK) {
- retval = -EAGAIN;
- goto done;
- } else {
- return;
- }
- }
- /* find the smaller of the total bytes we have available and what
- * the user is asking for */
- user_length = MIN(user_length, LOGRING_FIRST_EMPTY_BYTE - *user_offset);
- retval = user_length;
- /* figure out where to start copying data from, based on user's offset */
- start_point =
- (logring_readindex + (*user_offset-logring_offset)) % logring_size;
- /* copy the (possibly noncontiguous) data into user's buffer) */
- while (user_length) {
- n = MIN(user_length, logring_size - start_point);
- memcpy(user_buffer + bytes_copied, logring_data + start_point, n);
- bytes_copied += n;
- user_length -= n;
- start_point = (start_point + n) % logring_size;
- }
- /* advance the user's file pointer */
- *user_offset += retval;
- done:
- /* and complete the read system call */
- fusd_return(c->read, retval);
- c->read = NULL;
- }
- /*
- * read on /dev/logring: store the fusd_file_info pointer. then call
- * complete_read, which will immediately call fusd_return, if there is
- * data already waiting.
- *
- * Note that this shows a trick we use commonly in FUSD drivers: you
- * are allowed to call fusd_return() from within a callback as long as
- * you return -FUSD_NOREPLY. In other words, a driver can EITHER
- * return a real return value from its callback, OR call fusd_return
- * explicitly, but not both.
- */
- static ssize_t logring_read(struct fusd_file_info *file, char *buffer,
- size_t len, loff_t *offset)
- {
- struct logring_client *c = (struct logring_client *) file->private_data;
- if (c == NULL || c->read != NULL) {
- fprintf(stderr, "logring_read's arguments are confusd, alas");
- return -EINVAL;
- }
- c->read = file;
- logring_complete_read(c);
- return -FUSD_NOREPLY;
- }
- /*
- * complete_polldiff: if a client has an outstanding 'polldiff'
- * request, possibly return updated poll-state information to the
- * kernel, if indeed the state has changed.
- */
- void logring_complete_polldiff(struct logring_client *c)
- {
- int curr_state, cached_state;
- /* if there is no outstanding polldiff, do nothing */
- if (c == NULL || c->polldiff == NULL)
- return;
- /* figure out the "current" state: i.e. whether or not the logring
- * is readable for this client based on its current position in the
- * stream. The logring is *always* writable. */
- if (*(fusd_get_offset(c->polldiff)) < LOGRING_FIRST_EMPTY_BYTE)
- curr_state = FUSD_NOTIFY_INPUT | FUSD_NOTIFY_OUTPUT; /* read and write */
- else
- curr_state = FUSD_NOTIFY_OUTPUT; /* writable only */
- /* cached_state is what the kernel *thinks* the state is */
- cached_state = fusd_get_poll_diff_cached_state(c->polldiff);
- /* if the state is not what the kernel thinks it is, notify the
- kernel of the change */
- if (curr_state != cached_state) {
- fusd_return(c->polldiff, curr_state);
- c->polldiff = NULL;
- }
- }
- /* This function is only called on behalf of clients who are trying to
- * use select(). The kernel keeps us up to date on what it thinks the
- * current "poll state" is, i.e. readable and/or writable. The kernel
- * calls this function every time its assumption about the current
- * poll state changes. Every time the driver's notion of the state
- * differs from what the kernel thinks it is, it should return the
- * poll_diff request with the updated state. Note that a 2nd request
- * may come from the kernel before the driver has returned the first
- * one; if this happens, use fusd_destroy() to get rid of the older one.
- */
- int logring_polldiff(struct fusd_file_info *file, unsigned int flags)
- {
- struct logring_client *c = (struct logring_client *) file->private_data;
- if (c == NULL)
- return -EIO;
- /* if we're already holding a polldiff request that we haven't
- * replied to yet, destroy the old one and hold onto only the new
- * one */
- if (c->polldiff != NULL) {
- fusd_destroy(c->polldiff);
- c->polldiff = NULL;
- }
- c->polldiff = file;
- logring_complete_polldiff(c);
- return -FUSD_NOREPLY;
- }
- /*
- * a write on /dev/logring: first, copy the data from the user into our
- * data queue. Then, complete any reads and polldiffs that might be
- * outstanding.
- */
- ssize_t logring_write(struct fusd_file_info *file, const char *buffer,
- size_t len, loff_t *offset)
- {
- struct logring_client *c;
- int overflow = 0, bytes_copied = 0, n, retval;
- /* if the message is longer than the buffer, just take the beginning
- * of it, in hopes that the reader (if any) will have time to read
- * before we wrap around and obliterate it */
- len = MIN(len, logring_size - 1);
- retval = len;
- if (len + LOGRING_QLEN >= (logring_size-1)) {
- overflow = 1;
- /* in case of overflow, figure out where the new buffer will
- * begin. we start by figuring out where the current buffer ENDS:
- * logring_offset + LOGRING_QLEN. we then advance the end-offset
- * by the length of the current write, and work backwards to
- * figure out what the oldest unoverwritten data will be (i.e.,
- * size of the buffer). was that all quite clear? :-) */
- logring_offset = logring_offset + LOGRING_QLEN + len - logring_size + 1;
- }
-
- while (len) {
- /* how many contiguous bytes are available from the write point to
- * the end of the circular buffer? */
- n = MIN(len, logring_size - logring_writeindex);
- memcpy(logring_data + logring_writeindex, buffer + bytes_copied, n);
- bytes_copied += n;
- len -= n;
- logring_writeindex = (logring_writeindex + n) % logring_size;
- }
- /* if there was an overflow (i.e., new data wrapped around and
- * overwrote old data that had not yet been read), then, reset the
- * read point to be whatever the oldest data is that we have. */
- if (overflow)
- logring_readindex = (logring_writeindex + 1) % logring_size;
- /* now, complete any blocked reads and/or polldiffs */
- for (c = client_list; c != NULL; c = c->next) {
- logring_complete_read(c);
- logring_complete_polldiff(c);
- }
- /* now tell the client how many bytes we acutally wrote */
- return retval;
- }
- int main(int argc, char *argv[])
- {
- char *name;
- /* size must be provided, and an optional logring name */
- if (argc != 2 && argc != 3) {
- fprintf(stderr, "usage: %s <logring-size> [logring-name]\n", argv[0]);
- exit(1);
- }
- name = (argc == 3 ? argv[2] : "/dev/logring");
- /* convert the arg to an int and alloc memory for the logring */
- if ((logring_size = atoi(argv[1])) <= 0) {
- fprintf(stderr, "invalid logring size; it must be >0\n");
- exit(1);
- }
- if ((logring_data = (char *) malloc(sizeof(char) * logring_size)) == NULL) {
- fprintf(stderr, "couldn't allocate %d bytes!\n", logring_size);
- exit(1);
- }
- /* register the fusd device */
- fusd_simple_register(name, "misc", "logring", 0666, NULL,
- open: logring_open, close: logring_close,
- read: logring_read, write: logring_write,
- poll_diff: logring_polldiff);
- printf("calling fusd_run; reads from /dev/logring will now block\n"
- "until someone writes to /dev/logring...\n");
- fusd_run();
- return 0;
- }
|