Contiki 2.6
|
00001 /** \addtogroup lib 00002 * @{ */ 00003 00004 /** 00005 * \defgroup ringbuf Ring buffer library 00006 * @{ 00007 * 00008 * The ring buffer library implements ring (circular) buffer where 00009 * bytes can be read and written independently. A ring buffer is 00010 * particularly useful in device drivers where data can come in 00011 * through interrupts. 00012 * 00013 */ 00014 /* 00015 * Copyright (c) 2008, Swedish Institute of Computer Science. 00016 * All rights reserved. 00017 * 00018 * Redistribution and use in source and binary forms, with or without 00019 * modification, are permitted provided that the following conditions 00020 * are met: 00021 * 1. Redistributions of source code must retain the above copyright 00022 * notice, this list of conditions and the following disclaimer. 00023 * 2. Redistributions in binary form must reproduce the above copyright 00024 * notice, this list of conditions and the following disclaimer in the 00025 * documentation and/or other materials provided with the distribution. 00026 * 3. Neither the name of the Institute nor the names of its contributors 00027 * may be used to endorse or promote products derived from this software 00028 * without specific prior written permission. 00029 * 00030 * THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND 00031 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 00032 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 00033 * ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE 00034 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 00035 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 00036 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 00037 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 00038 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 00039 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 00040 * SUCH DAMAGE. 00041 * 00042 * This file is part of the Contiki operating system. 00043 * 00044 * $Id: ringbuf.h,v 1.1 2009/03/01 20:23:56 adamdunkels Exp $ 00045 */ 00046 00047 /** 00048 * \file 00049 * Header file for the ring buffer library 00050 * \author 00051 * Adam Dunkels <adam@sics.se> 00052 */ 00053 00054 #ifndef __RINGBUF_H__ 00055 #define __RINGBUF_H__ 00056 00057 #include "contiki-conf.h" 00058 00059 /** 00060 * \brief Structure that holds the state of a ring buffer. 00061 * 00062 * This structure holds the state of a ring buffer. The 00063 * actual buffer needs to be defined separately. This 00064 * struct is an opaque structure with no user-visible 00065 * elements. 00066 * 00067 */ 00068 struct ringbuf { 00069 uint8_t *data; 00070 uint8_t mask; 00071 00072 /* XXX these must be 8-bit quantities to avoid race conditions. */ 00073 uint8_t put_ptr, get_ptr; 00074 }; 00075 00076 /** 00077 * \brief Initialize a ring buffer 00078 * \param r A pointer to a struct ringbuf to hold the state of the ring buffer 00079 * \param a A pointer to an array to hold the data in the buffer 00080 * \param size_power_of_two The size of the ring buffer, which must be a power of two 00081 * 00082 * This function initiates a ring buffer. The data in the 00083 * buffer is stored in an external array, to which a 00084 * pointer must be supplied. The size of the ring buffer 00085 * must be a power of two and cannot be larger than 128 00086 * bytes. 00087 * 00088 */ 00089 void ringbuf_init(struct ringbuf *r, uint8_t *a, 00090 uint8_t size_power_of_two); 00091 00092 /** 00093 * \brief Insert a byte into the ring buffer 00094 * \param r A pointer to a struct ringbuf to hold the state of the ring buffer 00095 * \param c The byte to be written to the buffer 00096 * \return Non-zero if there data could be written, or zero if the buffer was full. 00097 * 00098 * This function inserts a byte into the ring buffer. It 00099 * is safe to call this function from an interrupt 00100 * handler. 00101 * 00102 */ 00103 int ringbuf_put(struct ringbuf *r, uint8_t c); 00104 00105 00106 /** 00107 * \brief Get a byte from the ring buffer 00108 * \param r A pointer to a struct ringbuf to hold the state of the ring buffer 00109 * \return The data from the buffer, or -1 if the buffer was empty 00110 * 00111 * This function removes a byte from the ring buffer. It 00112 * is safe to call this function from an interrupt 00113 * handler. 00114 * 00115 */ 00116 int ringbuf_get(struct ringbuf *r); 00117 00118 /** 00119 * \brief Get the size of a ring buffer 00120 * \param r A pointer to a struct ringbuf to hold the state of the ring buffer 00121 * \return The size of the buffer. 00122 */ 00123 int ringbuf_size(struct ringbuf *r); 00124 00125 /** 00126 * \brief Get the number of elements currently in the ring buffer 00127 * \param r A pointer to a struct ringbuf to hold the state of the ring buffer 00128 * \return The number of elements in the buffer. 00129 */ 00130 int ringbuf_elements(struct ringbuf *r); 00131 00132 #endif /* __RINGBUF_H__ */