root/trunk/libffado/src/libutil/ringbuffer.h

Revision 2802, 8.4 kB (checked in by jwoithe, 3 years ago)

Cosmetic: "Firewire" becomes "FireWire?".

Officially both the "F" and "W" were capitalised in the FireWire? name, so
reflect this throughout FFADO's source tree. This mostly affects comments.

This patch originated from pander on the ffado-devel mailing list. To
maintain consistency, the committed version has been expanded to include
files not originally included in the original patch.

Line 
1 /*
2  * Copyright (C) 2005-2008 by Pieter Palmers
3  *
4  * This file is part of FFADO
5  * FFADO = Free FireWire (pro-)audio drivers for linux
6  *
7  * FFADO is based upon FreeBoB
8  *
9  * This program is free software: you can redistribute it and/or modify
10  * it under the terms of the GNU General Public License as published by
11  * the Free Software Foundation, either version 2 of the License, or
12  * (at your option) version 3 of the License.
13  *
14  * This program is distributed in the hope that it will be useful,
15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
17  * GNU General Public License for more details.
18  *
19  * You should have received a copy of the GNU General Public License
20  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
21  *
22  */
23
24 /*
25  * Copied from the jackd sources
26  * function names changed in order to avoid naming problems when using this in
27  * a jackd backend.
28  */
29
30 /* Original license:
31  * note that LGPL2.1 allows relicensing the code to GPLv3 or higher
32  *
33  *  Copyright (C) 2000 Paul Davis
34  *  Copyright (C) 2003 Rohan Drape
35  *
36  *  This program is free software; you can redistribute it and/or modify
37  *  it under the terms of the GNU Lesser General Public License as published by
38  *  the Free Software Foundation; either version 2.1 of the License, or
39  *  (at your option) version 3 of the License.
40  *
41  *  This program is distributed in the hope that it will be useful,
42  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
43  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
44  *  GNU Lesser General Public License for more details.
45  *
46  *  You should have received a copy of the GNU Lesser General Public License
47  *  along with this program; if not, write to the Free Software
48  *  Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
49  *
50  */
51
52 #ifndef _FFADO_RINGBUFFER_H
53 #define _FFADO_RINGBUFFER_H
54
55 #ifdef __cplusplus
56 extern "C" {
57 #endif
58
59 #include <sys/types.h>
60
61 /** @file ringbuffer.h
62  *
63  *
64  * The key attribute of a ringbuffer is that it can be safely accessed
65  * by two threads simultaneously -- one reading from the buffer and
66  * the other writing to it -- without using any synchronization or
67  * mutual exclusion primitives.  For this to work correctly, there can
68  * only be a single reader and a single writer thread.  Their
69  * identities cannot be interchanged.
70  */
71
72 typedef struct
73 {
74   char  *buf;
75   size_t len;
76 }
77 ffado_ringbuffer_data_t ;
78
79 typedef struct
80 {
81   char         *buf;
82   volatile size_t write_ptr;
83   volatile size_t read_ptr;
84   size_t      size;
85   size_t      size_mask;
86   int          mlocked;
87 }
88 ffado_ringbuffer_t ;
89
90 /**
91  * Allocates a ringbuffer data structure of a specified size. The
92  * caller must arrange for a call to ffado_ringbuffer_free() to release
93  * the memory associated with the ringbuffer.
94  *
95  * @param sz the ringbuffer size in bytes.
96  *
97  * @return a pointer to a new ffado_ringbuffer_t, if successful; NULL
98  * otherwise.
99  */
100 ffado_ringbuffer_t *ffado_ringbuffer_create(size_t sz);
101
102 /**
103  * Frees the ringbuffer data structure allocated by an earlier call to
104  * ffado_ringbuffer_create().
105  *
106  * @param rb a pointer to the ringbuffer structure.
107  */
108 void ffado_ringbuffer_free(ffado_ringbuffer_t *rb);
109
110 /**
111  * Fill a data structure with a description of the current readable
112  * data held in the ringbuffer.  This description is returned in a two
113  * element array of ffado_ringbuffer_data_t.  Two elements are needed
114  * because the data to be read may be split across the end of the
115  * ringbuffer.
116  *
117  * The first element will always contain a valid @a len field, which
118  * may be zero or greater.  If the @a len field is non-zero, then data
119  * can be read in a contiguous fashion using the address given in the
120  * corresponding @a buf field.
121  *
122  * If the second element has a non-zero @a len field, then a second
123  * contiguous stretch of data can be read from the address given in
124  * its corresponding @a buf field.
125  *
126  * @param rb a pointer to the ringbuffer structure.
127  * @param vec a pointer to a 2 element array of ffado_ringbuffer_data_t.
128  *
129  */
130 void ffado_ringbuffer_get_read_vector(const ffado_ringbuffer_t *rb,
131                      ffado_ringbuffer_data_t *vec);
132
133 /**
134  * Fill a data structure with a description of the current writable
135  * space in the ringbuffer.  The description is returned in a two
136  * element array of ffado_ringbuffer_data_t.  Two elements are needed
137  * because the space available for writing may be split across the end
138  * of the ringbuffer.
139  *
140  * The first element will always contain a valid @a len field, which
141  * may be zero or greater.  If the @a len field is non-zero, then data
142  * can be written in a contiguous fashion using the address given in
143  * the corresponding @a buf field.
144  *
145  * If the second element has a non-zero @a len field, then a second
146  * contiguous stretch of data can be written to the address given in
147  * the corresponding @a buf field.
148  *
149  * @param rb a pointer to the ringbuffer structure.
150  * @param vec a pointer to a 2 element array of ffado_ringbuffer_data_t.
151  */
152 void ffado_ringbuffer_get_write_vector(const ffado_ringbuffer_t *rb,
153                       ffado_ringbuffer_data_t *vec);
154
155 /**
156  * Read data from the ringbuffer.
157  *
158  * @param rb a pointer to the ringbuffer structure.
159  * @param dest a pointer to a buffer where data read from the
160  * ringbuffer will go.
161  * @param cnt the number of bytes to read.
162  *
163  * @return the number of bytes read, which may range from 0 to cnt.
164  */
165 size_t ffado_ringbuffer_read(ffado_ringbuffer_t *rb, char *dest, size_t cnt);
166
167 /**
168  * Read data from the ringbuffer. Opposed to ffado_ringbuffer_read()
169  * this function does not move the read pointer. Thus it's
170  * a convenient way to inspect data in the ringbuffer in a
171  * continous fashion. The price is that the data is copied
172  * into a user provided buffer. For "raw" non-copy inspection
173  * of the data in the ringbuffer use ffado_ringbuffer_get_read_vector().
174  *
175  * @param rb a pointer to the ringbuffer structure.
176  * @param dest a pointer to a buffer where data read from the
177  * ringbuffer will go.
178  * @param cnt the number of bytes to read.
179  *
180  * @return the number of bytes read, which may range from 0 to cnt.
181  */
182 size_t ffado_ringbuffer_peek(ffado_ringbuffer_t *rb, char *dest, size_t cnt);
183
184 /**
185  * Advance the read pointer.
186  *
187  * After data have been read from the ringbuffer using the pointers
188  * returned by ffado_ringbuffer_get_read_vector(), use this function to
189  * advance the buffer pointers, making that space available for future
190  * write operations.
191  *
192  * @param rb a pointer to the ringbuffer structure.
193  * @param cnt the number of bytes read.
194  */
195 void ffado_ringbuffer_read_advance(ffado_ringbuffer_t *rb, size_t cnt);
196
197 /**
198  * Return the number of bytes available for reading.
199  *
200  * @param rb a pointer to the ringbuffer structure.
201  *
202  * @return the number of bytes available to read.
203  */
204 size_t ffado_ringbuffer_read_space(const ffado_ringbuffer_t *rb);
205
206 /**
207  * Lock a ringbuffer data block into memory.
208  *
209  * Uses the mlock() system call.  This is not a realtime operation.
210  *
211  * @param rb a pointer to the ringbuffer structure.
212  */
213 int ffado_ringbuffer_mlock(ffado_ringbuffer_t *rb);
214
215 /**
216  * Reset the read and write pointers, making an empty buffer.
217  *
218  * This is not thread safe.
219  *
220  * @param rb a pointer to the ringbuffer structure.
221  */
222 void ffado_ringbuffer_reset(ffado_ringbuffer_t *rb);
223
224 /**
225  * Write data into the ringbuffer.
226  *
227  * @param rb a pointer to the ringbuffer structure.
228  * @param src a pointer to the data to be written to the ringbuffer.
229  * @param cnt the number of bytes to write.
230  *
231  * @return the number of bytes write, which may range from 0 to cnt
232  */
233 size_t ffado_ringbuffer_write(ffado_ringbuffer_t *rb, const char *src,
234                  size_t cnt);
235
236 /**
237  * Advance the write pointer.
238  *
239  * After data have been written the ringbuffer using the pointers
240  * returned by ffado_ringbuffer_get_write_vector(), use this function
241  * to advance the buffer pointer, making the data available for future
242  * read operations.
243  *
244  * @param rb a pointer to the ringbuffer structure.
245  * @param cnt the number of bytes written.
246  */
247 void ffado_ringbuffer_write_advance(ffado_ringbuffer_t *rb, size_t cnt);
248
249 /**
250  * Return the number of bytes available for writing.
251  *
252  * @param rb a pointer to the ringbuffer structure.
253  *
254  * @return the amount of free space (in bytes) available for writing.
255  */
256 size_t ffado_ringbuffer_write_space(const ffado_ringbuffer_t *rb);
257
258
259 #ifdef __cplusplus
260 }
261 #endif
262
263 #endif // FFADO_RINGBUFFER
Note: See TracBrowser for help on using the browser.