Contiki-NG
ringbuf.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2008, Swedish Institute of Computer Science.
3  * All rights reserved.
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions
7  * are met:
8  * 1. Redistributions of source code must retain the above copyright
9  * notice, this list of conditions and the following disclaimer.
10  * 2. Redistributions in binary form must reproduce the above copyright
11  * notice, this list of conditions and the following disclaimer in the
12  * documentation and/or other materials provided with the distribution.
13  * 3. Neither the name of the Institute nor the names of its contributors
14  * may be used to endorse or promote products derived from this software
15  * without specific prior written permission.
16  *
17  * THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
18  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
19  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
20  * ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
21  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
22  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
23  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
24  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
25  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
26  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
27  * SUCH DAMAGE.
28  *
29  * This file is part of the Contiki operating system.
30  *
31  */
32 
33 /**
34  * \file
35  * Header file for the ring buffer library
36  * \author
37  * Adam Dunkels <adam@sics.se>
38  */
39 
40 /** \addtogroup data
41  * @{ */
42 
43 /**
44  * \defgroup ringbuf Ring buffer library
45  * @{
46  *
47  * The ring buffer library implements ring (circular) buffer where
48  * bytes can be read and written independently. A ring buffer is
49  * particularly useful in device drivers where data can come in
50  * through interrupts.
51  *
52  */
53 
54 #ifndef RINGBUF_H_
55 #define RINGBUF_H_
56 
57 #include "contiki.h"
58 
59 /**
60  * \brief Structure that holds the state of a ring buffer.
61  *
62  * This structure holds the state of a ring buffer. The
63  * actual buffer needs to be defined separately. This
64  * struct is an opaque structure with no user-visible
65  * elements.
66  *
67  */
68 struct ringbuf {
69  uint8_t *data;
70  uint8_t mask;
71 
72  /* XXX these must be 8-bit quantities to avoid race conditions. */
73  uint8_t put_ptr, get_ptr;
74 };
75 
76 /**
77  * \brief Initialize a ring buffer
78  * \param r A pointer to a struct ringbuf to hold the state of the ring buffer
79  * \param a A pointer to an array to hold the data in the buffer
80  * \param size_power_of_two The size of the ring buffer, which must be a power of two
81  *
82  * This function initiates a ring buffer. The data in the
83  * buffer is stored in an external array, to which a
84  * pointer must be supplied. The size of the ring buffer
85  * must be a power of two and cannot be larger than 128
86  * bytes.
87  *
88  */
89 void ringbuf_init(struct ringbuf *r, uint8_t *a,
90  uint8_t size_power_of_two);
91 
92 /**
93  * \brief Insert a byte into the ring buffer
94  * \param r A pointer to a struct ringbuf to hold the state of the ring buffer
95  * \param c The byte to be written to the buffer
96  * \return Non-zero if there data could be written, or zero if the buffer was full.
97  *
98  * This function inserts a byte into the ring buffer. It
99  * is safe to call this function from an interrupt
100  * handler.
101  *
102  */
103 int ringbuf_put(struct ringbuf *r, uint8_t c);
104 
105 
106 /**
107  * \brief Get a byte from the ring buffer
108  * \param r A pointer to a struct ringbuf to hold the state of the ring buffer
109  * \return The data from the buffer, or -1 if the buffer was empty
110  *
111  * This function removes a byte from the ring buffer. It
112  * is safe to call this function from an interrupt
113  * handler.
114  *
115  */
116 int ringbuf_get(struct ringbuf *r);
117 
118 /**
119  * \brief Get the size of a ring buffer
120  * \param r A pointer to a struct ringbuf to hold the state of the ring buffer
121  * \return The size of the buffer.
122  */
123 int ringbuf_size(struct ringbuf *r);
124 
125 /**
126  * \brief Get the number of elements currently in the ring buffer
127  * \param r A pointer to a struct ringbuf to hold the state of the ring buffer
128  * \return The number of elements in the buffer.
129  */
130 int ringbuf_elements(struct ringbuf *r);
131 
132 #endif /* RINGBUF_H_ */
133 
134 /** @}*/
135 /** @}*/
int ringbuf_elements(struct ringbuf *r)
Get the number of elements currently in the ring buffer.
Definition: ringbuf.c:119
int ringbuf_get(struct ringbuf *r)
Get a byte from the ring buffer.
Definition: ringbuf.c:80
int ringbuf_size(struct ringbuf *r)
Get the size of a ring buffer.
Definition: ringbuf.c:113
Structure that holds the state of a ring buffer.
Definition: ringbuf.h:68
int ringbuf_put(struct ringbuf *r, uint8_t c)
Insert a byte into the ring buffer.
Definition: ringbuf.c:53
void ringbuf_init(struct ringbuf *r, uint8_t *a, uint8_t size_power_of_two)
Initialize a ring buffer.
Definition: ringbuf.c:44