Project

General

Profile

Statistics
| Revision:

root / trunk / docs / libdragonfly / ring__buffer_8h.html @ 1398

History | View | Annotate | Download (18.7 KB)

1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2
<html><head><meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
3
<title>libdragonfly: ring_buffer.h File Reference</title>
4
<link href="tabs.css" rel="stylesheet" type="text/css">
5
<link href="doxygen.css" rel="stylesheet" type="text/css">
6
</head><body>
7
<!-- Generated by Doxygen 1.5.9 -->
8
<div class="navigation" id="top">
9
  <div class="tabs">
10
    <ul>
11
      <li><a href="index.html"><span>Main&nbsp;Page</span></a></li>
12
      <li><a href="pages.html"><span>Related&nbsp;Pages</span></a></li>
13
      <li><a href="modules.html"><span>Modules</span></a></li>
14
      <li><a href="annotated.html"><span>Data&nbsp;Structures</span></a></li>
15
      <li class="current"><a href="files.html"><span>Files</span></a></li>
16
    </ul>
17
  </div>
18
  <div class="tabs">
19
    <ul>
20
      <li><a href="files.html"><span>File&nbsp;List</span></a></li>
21
      <li><a href="globals.html"><span>Globals</span></a></li>
22
    </ul>
23
  </div>
24
</div>
25
<div class="contents">
26
<h1>ring_buffer.h File Reference</h1>Ring Buffer.  
27
<a href="#_details">More...</a>
28
<p>
29

    
30
<p>
31
<a href="ring__buffer_8h_source.html">Go to the source code of this file.</a><table border="0" cellpadding="0" cellspacing="0">
32
<tr><td></td></tr>
33
<tr><td colspan="2"><br><h2>Defines</h2></td></tr>
34
<tr><td class="memItemLeft" nowrap align="right" valign="top">#define&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="ring__buffer_8h.html#883368e450d3596622905053d3b3ab83">RING_BUFFER_NEW</a>(struct_name, size, type,...)</td></tr>
35

    
36
<tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Creates the struct for a new ring buffer. This just expands to a structure definition and thus should be invoked in the global context.  <a href="#883368e450d3596622905053d3b3ab83"></a><br></td></tr>
37
<tr><td class="memItemLeft" nowrap align="right" valign="top">#define&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="ring__buffer_8h.html#3c186ab6ff12fa96c18f6d064720cc2c">RING_BUFFER_INIT</a>(buf, size)</td></tr>
38

    
39
<tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Initializes the ring buffer, setting its size to the correct value.  <a href="#3c186ab6ff12fa96c18f6d064720cc2c"></a><br></td></tr>
40
<tr><td class="memItemLeft" nowrap align="right" valign="top">#define&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="ring__buffer_8h.html#0ae5ca959a3b05583623551cc287a534">RING_BUFFER_CLEAR</a>(buf)</td></tr>
41

    
42
<tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Sets the specified ring buffer to be empty.  <a href="#0ae5ca959a3b05583623551cc287a534"></a><br></td></tr>
43
<tr><td class="memItemLeft" nowrap align="right" valign="top">#define&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="ring__buffer_8h.html#19daf3026b69a26bb3d383b14ae90e23">RING_BUFFER_EMPTY</a>(buf)&nbsp;&nbsp;&nbsp;((buf).start == (buf).end)</td></tr>
44

    
45
<tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Returns true if the ring buffer specified is empty.  <a href="#19daf3026b69a26bb3d383b14ae90e23"></a><br></td></tr>
46
<tr><td class="memItemLeft" nowrap align="right" valign="top">#define&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="ring__buffer_8h.html#2ed153688dc60c5503f2f7fdd2b73a4a">RING_BUFFER_FULL</a>(buf)&nbsp;&nbsp;&nbsp;(((buf).end + 1) % (buf).buffer_size == (buf).start)</td></tr>
47

    
48
<tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Returns true if the ring buffer specified is full.  <a href="#2ed153688dc60c5503f2f7fdd2b73a4a"></a><br></td></tr>
49
<tr><td class="memItemLeft" nowrap align="right" valign="top">#define&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="ring__buffer_8h.html#7708daab49219e2fd35534bc9cd15245">RING_BUFFER_ADD</a>(buf, val)</td></tr>
50

    
51
<tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Adds val to ring buffer buf. Note that val must be of the type used in creating the ring buffer to prevent the compiler from spewing confusing errors. Also, this assumes that the ring buffer is not full.  <a href="#7708daab49219e2fd35534bc9cd15245"></a><br></td></tr>
52
<tr><td class="memItemLeft" nowrap align="right" valign="top">#define&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="ring__buffer_8h.html#4a0f9de5ac14f60d678cda392921a629">RING_BUFFER_REMOVE</a>(buf, val_ret)</td></tr>
53

    
54
<tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Removes the value at the head of the ring buffer and puts it in val_ret. Note that val_ret must be the same type used in creating the ring buffer to prevent the compiler from spewing confusing errors. Also, this assumes that the ring buffer is not empty.  <a href="#4a0f9de5ac14f60d678cda392921a629"></a><br></td></tr>
55
<tr><td class="memItemLeft" nowrap align="right" valign="top">#define&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="ring__buffer_8h.html#6cb5596d0d7edccd628aca097f088f91">RING_BUFFER_PEEK</a>(buf, val_ret)</td></tr>
56

    
57
<tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Checks the value at the head of the ring buffer without removing it and puts it into val_ret. Note that val_ret must be the same type used in creating the ring buffer to prevent the compiler from spewing confusing errors. Also, this assumes that the ring buffer is not empty.  <a href="#6cb5596d0d7edccd628aca097f088f91"></a><br></td></tr>
58
</table>
59
<hr><h2>Detailed Description</h2>
60
Ring Buffer. 
61
<p>
62
Copyright (c) 2007 Colony Project<p>
63
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:<p>
64
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.<p>
65
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. Include macros to create a ring buffer. Originally written for 15-410. Modified for use in ATMega128 serial driver<p>
66
<dl class="author" compact><dt><b>Author:</b></dt><dd>Cornell Wright (cgwright) <p>
67
Jason P. Winters (jpwinter) </dd></dl>
68
<hr><h2>Define Documentation</h2>
69
<a class="anchor" name="7708daab49219e2fd35534bc9cd15245"></a><!-- doxytag: member="ring_buffer.h::RING_BUFFER_ADD" ref="7708daab49219e2fd35534bc9cd15245" args="(buf, val)" -->
70
<div class="memitem">
71
<div class="memproto">
72
      <table class="memname">
73
        <tr>
74
          <td class="memname">#define RING_BUFFER_ADD          </td>
75
          <td>(</td>
76
          <td class="paramtype">buf,         <tr>
77
          <td class="paramkey"></td>
78
          <td></td>
79
          <td class="paramtype">val&nbsp;</td>
80
          <td class="paramname">          </td>
81
          <td>&nbsp;)&nbsp;</td>
82
          <td></td>
83
        </tr>
84
      </table>
85
</div>
86
<div class="memdoc">
87

    
88
<p>
89
<b>Value:</b><div class="fragment"><pre class="fragment"><span class="keywordflow">do</span> {                                                            \
90
                (buf).queue[(buf).end] = val;   \
91
                (buf).end = ((buf).end + 1) % (buf).buffer_size;        \
92
        } <span class="keywordflow">while</span> (0)
93
</pre></div>Adds val to ring buffer buf. Note that val must be of the type used in creating the ring buffer to prevent the compiler from spewing confusing errors. Also, this assumes that the ring buffer is not full. 
94
<p>
95
<dl compact><dt><b>Parameters:</b></dt><dd>
96
  <table border="0" cellspacing="2" cellpadding="0">
97
    <tr><td valign="top"></td><td valign="top"><em>buf</em>&nbsp;</td><td>The ring buffer to add to. </td></tr>
98
    <tr><td valign="top"></td><td valign="top"><em>val</em>&nbsp;</td><td>The value to add. </td></tr>
99
  </table>
100
</dl>
101

    
102
<p>Referenced by <a class="el" href="i2c_8c_source.html#l00182">i2c_request()</a>, and <a class="el" href="i2c_8c_source.html#l00141">i2c_send()</a>.</p>
103

    
104
</div>
105
</div><p>
106
<a class="anchor" name="0ae5ca959a3b05583623551cc287a534"></a><!-- doxytag: member="ring_buffer.h::RING_BUFFER_CLEAR" ref="0ae5ca959a3b05583623551cc287a534" args="(buf)" -->
107
<div class="memitem">
108
<div class="memproto">
109
      <table class="memname">
110
        <tr>
111
          <td class="memname">#define RING_BUFFER_CLEAR          </td>
112
          <td>(</td>
113
          <td class="paramtype">buf&nbsp;</td>
114
          <td class="paramname">          </td>
115
          <td>&nbsp;)&nbsp;</td>
116
          <td></td>
117
        </tr>
118
      </table>
119
</div>
120
<div class="memdoc">
121

    
122
<p>
123
<b>Value:</b><div class="fragment"><pre class="fragment"><span class="keywordflow">do</span> {                                            \
124
                (buf).start = 0;                \
125
                (buf).end = 0;                  \
126
        } <span class="keywordflow">while</span> (0)
127
</pre></div>Sets the specified ring buffer to be empty. 
128
<p>
129
<dl compact><dt><b>Parameters:</b></dt><dd>
130
  <table border="0" cellspacing="2" cellpadding="0">
131
    <tr><td valign="top"></td><td valign="top"><em>buf</em>&nbsp;</td><td>The ring buffer to make empty. </td></tr>
132
  </table>
133
</dl>
134

    
135
<p>Referenced by <a class="el" href="i2c_8c_source.html#l00107">i2c_init()</a>, and <a class="el" href="i2c_8c_source.html#l00214">ISR()</a>.</p>
136

    
137
</div>
138
</div><p>
139
<a class="anchor" name="19daf3026b69a26bb3d383b14ae90e23"></a><!-- doxytag: member="ring_buffer.h::RING_BUFFER_EMPTY" ref="19daf3026b69a26bb3d383b14ae90e23" args="(buf)" -->
140
<div class="memitem">
141
<div class="memproto">
142
      <table class="memname">
143
        <tr>
144
          <td class="memname">#define RING_BUFFER_EMPTY          </td>
145
          <td>(</td>
146
          <td class="paramtype">buf&nbsp;</td>
147
          <td class="paramname">          </td>
148
          <td>&nbsp;)&nbsp;</td>
149
          <td>&nbsp;&nbsp;&nbsp;((buf).start == (buf).end)</td>
150
        </tr>
151
      </table>
152
</div>
153
<div class="memdoc">
154

    
155
<p>
156
Returns true if the ring buffer specified is empty. 
157
<p>
158
<dl compact><dt><b>Parameters:</b></dt><dd>
159
  <table border="0" cellspacing="2" cellpadding="0">
160
    <tr><td valign="top"></td><td valign="top"><em>buf</em>&nbsp;</td><td>The buffer to check emptiness of. </td></tr>
161
  </table>
162
</dl>
163

    
164
<p>Referenced by <a class="el" href="i2c_8c_source.html#l00214">ISR()</a>.</p>
165

    
166
</div>
167
</div><p>
168
<a class="anchor" name="2ed153688dc60c5503f2f7fdd2b73a4a"></a><!-- doxytag: member="ring_buffer.h::RING_BUFFER_FULL" ref="2ed153688dc60c5503f2f7fdd2b73a4a" args="(buf)" -->
169
<div class="memitem">
170
<div class="memproto">
171
      <table class="memname">
172
        <tr>
173
          <td class="memname">#define RING_BUFFER_FULL          </td>
174
          <td>(</td>
175
          <td class="paramtype">buf&nbsp;</td>
176
          <td class="paramname">          </td>
177
          <td>&nbsp;)&nbsp;</td>
178
          <td>&nbsp;&nbsp;&nbsp;(((buf).end + 1) % (buf).buffer_size == (buf).start)</td>
179
        </tr>
180
      </table>
181
</div>
182
<div class="memdoc">
183

    
184
<p>
185
Returns true if the ring buffer specified is full. 
186
<p>
187
<dl compact><dt><b>Parameters:</b></dt><dd>
188
  <table border="0" cellspacing="2" cellpadding="0">
189
    <tr><td valign="top"></td><td valign="top"><em>buf</em>&nbsp;</td><td>The buffer to check fullness of. </td></tr>
190
  </table>
191
</dl>
192

    
193
<p>Referenced by <a class="el" href="i2c_8c_source.html#l00182">i2c_request()</a>, and <a class="el" href="i2c_8c_source.html#l00141">i2c_send()</a>.</p>
194

    
195
</div>
196
</div><p>
197
<a class="anchor" name="3c186ab6ff12fa96c18f6d064720cc2c"></a><!-- doxytag: member="ring_buffer.h::RING_BUFFER_INIT" ref="3c186ab6ff12fa96c18f6d064720cc2c" args="(buf, size)" -->
198
<div class="memitem">
199
<div class="memproto">
200
      <table class="memname">
201
        <tr>
202
          <td class="memname">#define RING_BUFFER_INIT          </td>
203
          <td>(</td>
204
          <td class="paramtype">buf,         <tr>
205
          <td class="paramkey"></td>
206
          <td></td>
207
          <td class="paramtype">size&nbsp;</td>
208
          <td class="paramname">          </td>
209
          <td>&nbsp;)&nbsp;</td>
210
          <td></td>
211
        </tr>
212
      </table>
213
</div>
214
<div class="memdoc">
215

    
216
<p>
217
<b>Value:</b><div class="fragment"><pre class="fragment"><span class="keywordflow">do</span> {                                                                            \
218
                (buf).buffer_size = size;                               \
219
        } <span class="keywordflow">while</span>(0)
220
</pre></div>Initializes the ring buffer, setting its size to the correct value. 
221
<p>
222
<dl compact><dt><b>Parameters:</b></dt><dd>
223
  <table border="0" cellspacing="2" cellpadding="0">
224
    <tr><td valign="top"></td><td valign="top"><em>buf</em>&nbsp;</td><td>The ring buffer to initialize.</td></tr>
225
    <tr><td valign="top"></td><td valign="top"><em>size</em>&nbsp;</td><td>The size of the ring buffer (in array elements) </td></tr>
226
  </table>
227
</dl>
228

    
229
</div>
230
</div><p>
231
<a class="anchor" name="883368e450d3596622905053d3b3ab83"></a><!-- doxytag: member="ring_buffer.h::RING_BUFFER_NEW" ref="883368e450d3596622905053d3b3ab83" args="(struct_name, size, type,...)" -->
232
<div class="memitem">
233
<div class="memproto">
234
      <table class="memname">
235
        <tr>
236
          <td class="memname">#define RING_BUFFER_NEW          </td>
237
          <td>(</td>
238
          <td class="paramtype">struct_name,         <tr>
239
          <td class="paramkey"></td>
240
          <td></td>
241
          <td class="paramtype">size,         <tr>
242
          <td class="paramkey"></td>
243
          <td></td>
244
          <td class="paramtype">type,         <tr>
245
          <td class="paramkey"></td>
246
          <td></td>
247
          <td class="paramtype"> <em>...</em>&nbsp;</td>
248
          <td class="paramname">          </td>
249
          <td>&nbsp;)&nbsp;</td>
250
          <td></td>
251
        </tr>
252
      </table>
253
</div>
254
<div class="memdoc">
255

    
256
<p>
257
<b>Value:</b><div class="fragment"><pre class="fragment"><span class="keyword">struct </span>struct_name {    \
258
                type queue[size];       \
259
                uint8_t start;                  \
260
                uint8_t end;                    \
261
                uint8_t buffer_size;                    \
262
        } __VA_ARGS__
263
</pre></div>Creates the struct for a new ring buffer. This just expands to a structure definition and thus should be invoked in the global context. 
264
<p>
265
<dl compact><dt><b>Parameters:</b></dt><dd>
266
  <table border="0" cellspacing="2" cellpadding="0">
267
    <tr><td valign="top"></td><td valign="top"><em>struct_name</em>&nbsp;</td><td>Name of the ring buffer struct.</td></tr>
268
    <tr><td valign="top"></td><td valign="top"><em>size</em>&nbsp;</td><td>The size of the buffer to create.</td></tr>
269
    <tr><td valign="top"></td><td valign="top"><em>type</em>&nbsp;</td><td>The type of object that the queue is to hold.</td></tr>
270
    <tr><td valign="top"></td><td valign="top"><em>...</em>&nbsp;</td><td>Name or names of the instance or instances of the ring buffer(s) to be created. </td></tr>
271
  </table>
272
</dl>
273

    
274
</div>
275
</div><p>
276
<a class="anchor" name="6cb5596d0d7edccd628aca097f088f91"></a><!-- doxytag: member="ring_buffer.h::RING_BUFFER_PEEK" ref="6cb5596d0d7edccd628aca097f088f91" args="(buf, val_ret)" -->
277
<div class="memitem">
278
<div class="memproto">
279
      <table class="memname">
280
        <tr>
281
          <td class="memname">#define RING_BUFFER_PEEK          </td>
282
          <td>(</td>
283
          <td class="paramtype">buf,         <tr>
284
          <td class="paramkey"></td>
285
          <td></td>
286
          <td class="paramtype">val_ret&nbsp;</td>
287
          <td class="paramname">          </td>
288
          <td>&nbsp;)&nbsp;</td>
289
          <td></td>
290
        </tr>
291
      </table>
292
</div>
293
<div class="memdoc">
294

    
295
<p>
296
<b>Value:</b><div class="fragment"><pre class="fragment"><span class="keywordflow">do</span> { \
297
    (val_ret) = (buf).queue[(buf).start]; \
298
  } <span class="keywordflow">while</span>(0)
299
</pre></div>Checks the value at the head of the ring buffer without removing it and puts it into val_ret. Note that val_ret must be the same type used in creating the ring buffer to prevent the compiler from spewing confusing errors. Also, this assumes that the ring buffer is not empty. 
300
<p>
301
<dl compact><dt><b>Parameters:</b></dt><dd>
302
  <table border="0" cellspacing="2" cellpadding="0">
303
    <tr><td valign="top"></td><td valign="top"><em>buf</em>&nbsp;</td><td>The ring buffer to check from </td></tr>
304
    <tr><td valign="top"></td><td valign="top"><em>val_ret</em>&nbsp;</td><td>where to put the value checked from the head of the ring </td></tr>
305
  </table>
306
</dl>
307

    
308
<p>Referenced by <a class="el" href="i2c_8c_source.html#l00214">ISR()</a>.</p>
309

    
310
</div>
311
</div><p>
312
<a class="anchor" name="4a0f9de5ac14f60d678cda392921a629"></a><!-- doxytag: member="ring_buffer.h::RING_BUFFER_REMOVE" ref="4a0f9de5ac14f60d678cda392921a629" args="(buf, val_ret)" -->
313
<div class="memitem">
314
<div class="memproto">
315
      <table class="memname">
316
        <tr>
317
          <td class="memname">#define RING_BUFFER_REMOVE          </td>
318
          <td>(</td>
319
          <td class="paramtype">buf,         <tr>
320
          <td class="paramkey"></td>
321
          <td></td>
322
          <td class="paramtype">val_ret&nbsp;</td>
323
          <td class="paramname">          </td>
324
          <td>&nbsp;)&nbsp;</td>
325
          <td></td>
326
        </tr>
327
      </table>
328
</div>
329
<div class="memdoc">
330

    
331
<p>
332
<b>Value:</b><div class="fragment"><pre class="fragment"><span class="keywordflow">do</span> {    \
333
                (val_ret) = (buf).queue[(buf).start];   \
334
                (buf).start = ((buf).start + 1) % (buf).buffer_size;    \
335
        } <span class="keywordflow">while</span> (0)
336
</pre></div>Removes the value at the head of the ring buffer and puts it in val_ret. Note that val_ret must be the same type used in creating the ring buffer to prevent the compiler from spewing confusing errors. Also, this assumes that the ring buffer is not empty. 
337
<p>
338
<dl compact><dt><b>Parameters:</b></dt><dd>
339
  <table border="0" cellspacing="2" cellpadding="0">
340
    <tr><td valign="top"></td><td valign="top"><em>buf</em>&nbsp;</td><td>The ring buffer to remove from. </td></tr>
341
    <tr><td valign="top"></td><td valign="top"><em>val_ret</em>&nbsp;</td><td>Where to put the value removed from the head of the ring buffer. </td></tr>
342
  </table>
343
</dl>
344

    
345
<p>Referenced by <a class="el" href="i2c_8c_source.html#l00214">ISR()</a>.</p>
346

    
347
</div>
348
</div><p>
349
</div>
350
<hr size="1"><address style="text-align: right;"><small>Generated on Mon Sep 7 19:07:28 2009 for libdragonfly by&nbsp;
351
<a href="http://www.doxygen.org/index.html">
352
<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.9 </small></address>
353
</body>
354
</html>