1 |
/* |
---|
2 |
* Copyright (C) 2005-2007 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 3 of the License, or |
---|
12 |
* (at your option) any later version. |
---|
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) any later version. |
---|
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 |
---|