Project

General

Profile

Statistics
| Revision:

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

History | View | Annotate | Download (18.6 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="doxygen.css" rel="stylesheet" type="text/css">
5
<link href="tabs.css" rel="stylesheet" type="text/css">
6
</head><body>
7
<!-- Generated by Doxygen 1.5.5 -->
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>
19
<div class="contents">
20
<h1>ring_buffer.h File Reference</h1>Ring Buffer. <a href="#_details">More...</a>
21
<p>
22

    
23
<p>
24
<a href="ring__buffer_8h-source.html">Go to the source code of this file.</a><table border="0" cellpadding="0" cellspacing="0">
25
<tr><td></td></tr>
26
<tr><td colspan="2"><br><h2>Defines</h2></td></tr>
27
<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>
28

    
29
<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>
30
<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>
31

    
32
<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>
33
<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>
34

    
35
<tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Sets the specified ring buffer to be empty.  <a href="#0ae5ca959a3b05583623551cc287a534"></a><br></td></tr>
36
<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>
37

    
38
<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>
39
<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>
40

    
41
<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>
42
<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>
43

    
44
<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>
45
<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>
46

    
47
<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>
48
<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>
49

    
50
<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>
51
</table>
52
<hr><a name="_details"></a><h2>Detailed Description</h2>
53
Ring Buffer. 
54
<p>
55
Copyright (c) 2007 Colony Project<p>
56
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>
57
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.<p>
58
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>
59
<dl class="author" compact><dt><b>Author:</b></dt><dd>Cornell Wright (cgwright) <p>
60
Jason P. Winters (jpwinter) </dd></dl>
61
<hr><h2>Define Documentation</h2>
62
<a class="anchor" name="7708daab49219e2fd35534bc9cd15245"></a><!-- doxytag: member="ring_buffer.h::RING_BUFFER_ADD" ref="7708daab49219e2fd35534bc9cd15245" args="(buf, val)" -->
63
<div class="memitem">
64
<div class="memproto">
65
      <table class="memname">
66
        <tr>
67
          <td class="memname">#define RING_BUFFER_ADD          </td>
68
          <td>(</td>
69
          <td class="paramtype">buf,         <tr>
70
          <td class="paramkey"></td>
71
          <td></td>
72
          <td class="paramtype">val&nbsp;</td>
73
          <td class="paramname">          </td>
74
          <td>&nbsp;)&nbsp;</td>
75
          <td width="100%"></td>
76
        </tr>
77
      </table>
78
</div>
79
<div class="memdoc">
80

    
81
<p>
82
<b>Value:</b><div class="fragment"><pre class="fragment"><span class="keywordflow">do</span> {                                                            \
83
                (buf).queue[(buf).end] = val;   \
84
                (buf).end = ((buf).end + 1) % (buf).buffer_size;        \
85
        } <span class="keywordflow">while</span> (0)
86
</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. 
87
<p>
88
<dl compact><dt><b>Parameters:</b></dt><dd>
89
  <table border="0" cellspacing="2" cellpadding="0">
90
    <tr><td valign="top"></td><td valign="top"><em>buf</em>&nbsp;</td><td>The ring buffer to add to. </td></tr>
91
    <tr><td valign="top"></td><td valign="top"><em>val</em>&nbsp;</td><td>The value to add. </td></tr>
92
  </table>
93
</dl>
94

    
95
<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>
96

    
97
</div>
98
</div><p>
99
<a class="anchor" name="0ae5ca959a3b05583623551cc287a534"></a><!-- doxytag: member="ring_buffer.h::RING_BUFFER_CLEAR" ref="0ae5ca959a3b05583623551cc287a534" args="(buf)" -->
100
<div class="memitem">
101
<div class="memproto">
102
      <table class="memname">
103
        <tr>
104
          <td class="memname">#define RING_BUFFER_CLEAR          </td>
105
          <td>(</td>
106
          <td class="paramtype">buf&nbsp;</td>
107
          <td class="paramname">          </td>
108
          <td>&nbsp;)&nbsp;</td>
109
          <td width="100%"></td>
110
        </tr>
111
      </table>
112
</div>
113
<div class="memdoc">
114

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

    
128
<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>
129

    
130
</div>
131
</div><p>
132
<a class="anchor" name="19daf3026b69a26bb3d383b14ae90e23"></a><!-- doxytag: member="ring_buffer.h::RING_BUFFER_EMPTY" ref="19daf3026b69a26bb3d383b14ae90e23" args="(buf)" -->
133
<div class="memitem">
134
<div class="memproto">
135
      <table class="memname">
136
        <tr>
137
          <td class="memname">#define RING_BUFFER_EMPTY          </td>
138
          <td>(</td>
139
          <td class="paramtype">buf&nbsp;</td>
140
          <td class="paramname">          </td>
141
          <td>&nbsp;)&nbsp;</td>
142
          <td width="100%">&nbsp;&nbsp;&nbsp;((buf).start == (buf).end)</td>
143
        </tr>
144
      </table>
145
</div>
146
<div class="memdoc">
147

    
148
<p>
149
Returns true if the ring buffer specified is empty. 
150
<p>
151
<dl compact><dt><b>Parameters:</b></dt><dd>
152
  <table border="0" cellspacing="2" cellpadding="0">
153
    <tr><td valign="top"></td><td valign="top"><em>buf</em>&nbsp;</td><td>The buffer to check emptiness of. </td></tr>
154
  </table>
155
</dl>
156

    
157
<p>Referenced by <a class="el" href="i2c_8c-source.html#l00214">ISR()</a>.</p>
158

    
159
</div>
160
</div><p>
161
<a class="anchor" name="2ed153688dc60c5503f2f7fdd2b73a4a"></a><!-- doxytag: member="ring_buffer.h::RING_BUFFER_FULL" ref="2ed153688dc60c5503f2f7fdd2b73a4a" args="(buf)" -->
162
<div class="memitem">
163
<div class="memproto">
164
      <table class="memname">
165
        <tr>
166
          <td class="memname">#define RING_BUFFER_FULL          </td>
167
          <td>(</td>
168
          <td class="paramtype">buf&nbsp;</td>
169
          <td class="paramname">          </td>
170
          <td>&nbsp;)&nbsp;</td>
171
          <td width="100%">&nbsp;&nbsp;&nbsp;(((buf).end + 1) % (buf).buffer_size == (buf).start)</td>
172
        </tr>
173
      </table>
174
</div>
175
<div class="memdoc">
176

    
177
<p>
178
Returns true if the ring buffer specified is full. 
179
<p>
180
<dl compact><dt><b>Parameters:</b></dt><dd>
181
  <table border="0" cellspacing="2" cellpadding="0">
182
    <tr><td valign="top"></td><td valign="top"><em>buf</em>&nbsp;</td><td>The buffer to check fullness of. </td></tr>
183
  </table>
184
</dl>
185

    
186
<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>
187

    
188
</div>
189
</div><p>
190
<a class="anchor" name="3c186ab6ff12fa96c18f6d064720cc2c"></a><!-- doxytag: member="ring_buffer.h::RING_BUFFER_INIT" ref="3c186ab6ff12fa96c18f6d064720cc2c" args="(buf, size)" -->
191
<div class="memitem">
192
<div class="memproto">
193
      <table class="memname">
194
        <tr>
195
          <td class="memname">#define RING_BUFFER_INIT          </td>
196
          <td>(</td>
197
          <td class="paramtype">buf,         <tr>
198
          <td class="paramkey"></td>
199
          <td></td>
200
          <td class="paramtype">size&nbsp;</td>
201
          <td class="paramname">          </td>
202
          <td>&nbsp;)&nbsp;</td>
203
          <td width="100%"></td>
204
        </tr>
205
      </table>
206
</div>
207
<div class="memdoc">
208

    
209
<p>
210
<b>Value:</b><div class="fragment"><pre class="fragment"><span class="keywordflow">do</span> {                                                                            \
211
                (buf).buffer_size = size;                               \
212
        } <span class="keywordflow">while</span>(0)
213
</pre></div>Initializes the ring buffer, setting its size to the correct value. 
214
<p>
215
<dl compact><dt><b>Parameters:</b></dt><dd>
216
  <table border="0" cellspacing="2" cellpadding="0">
217
    <tr><td valign="top"></td><td valign="top"><em>buf</em>&nbsp;</td><td>The ring buffer to initialize.</td></tr>
218
    <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>
219
  </table>
220
</dl>
221

    
222
</div>
223
</div><p>
224
<a class="anchor" name="883368e450d3596622905053d3b3ab83"></a><!-- doxytag: member="ring_buffer.h::RING_BUFFER_NEW" ref="883368e450d3596622905053d3b3ab83" args="(struct_name, size, type,...)" -->
225
<div class="memitem">
226
<div class="memproto">
227
      <table class="memname">
228
        <tr>
229
          <td class="memname">#define RING_BUFFER_NEW          </td>
230
          <td>(</td>
231
          <td class="paramtype">struct_name,         <tr>
232
          <td class="paramkey"></td>
233
          <td></td>
234
          <td class="paramtype">size,         <tr>
235
          <td class="paramkey"></td>
236
          <td></td>
237
          <td class="paramtype">type,         <tr>
238
          <td class="paramkey"></td>
239
          <td></td>
240
          <td class="paramtype"> <em>...</em>&nbsp;</td>
241
          <td class="paramname">          </td>
242
          <td>&nbsp;)&nbsp;</td>
243
          <td width="100%"></td>
244
        </tr>
245
      </table>
246
</div>
247
<div class="memdoc">
248

    
249
<p>
250
<b>Value:</b><div class="fragment"><pre class="fragment"><span class="keyword">struct </span>struct_name {    \
251
                type queue[size];       \
252
                uint8_t start;                  \
253
                uint8_t end;                    \
254
                uint8_t buffer_size;                    \
255
        } __VA_ARGS__
256
</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. 
257
<p>
258
<dl compact><dt><b>Parameters:</b></dt><dd>
259
  <table border="0" cellspacing="2" cellpadding="0">
260
    <tr><td valign="top"></td><td valign="top"><em>struct_name</em>&nbsp;</td><td>Name of the ring buffer struct.</td></tr>
261
    <tr><td valign="top"></td><td valign="top"><em>size</em>&nbsp;</td><td>The size of the buffer to create.</td></tr>
262
    <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>
263
    <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>
264
  </table>
265
</dl>
266

    
267
</div>
268
</div><p>
269
<a class="anchor" name="6cb5596d0d7edccd628aca097f088f91"></a><!-- doxytag: member="ring_buffer.h::RING_BUFFER_PEEK" ref="6cb5596d0d7edccd628aca097f088f91" args="(buf, val_ret)" -->
270
<div class="memitem">
271
<div class="memproto">
272
      <table class="memname">
273
        <tr>
274
          <td class="memname">#define RING_BUFFER_PEEK          </td>
275
          <td>(</td>
276
          <td class="paramtype">buf,         <tr>
277
          <td class="paramkey"></td>
278
          <td></td>
279
          <td class="paramtype">val_ret&nbsp;</td>
280
          <td class="paramname">          </td>
281
          <td>&nbsp;)&nbsp;</td>
282
          <td width="100%"></td>
283
        </tr>
284
      </table>
285
</div>
286
<div class="memdoc">
287

    
288
<p>
289
<b>Value:</b><div class="fragment"><pre class="fragment"><span class="keywordflow">do</span> { \
290
    (val_ret) = (buf).queue[(buf).start]; \
291
  } <span class="keywordflow">while</span>(0)
292
</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. 
293
<p>
294
<dl compact><dt><b>Parameters:</b></dt><dd>
295
  <table border="0" cellspacing="2" cellpadding="0">
296
    <tr><td valign="top"></td><td valign="top"><em>buf</em>&nbsp;</td><td>The ring buffer to check from </td></tr>
297
    <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>
298
  </table>
299
</dl>
300

    
301
<p>Referenced by <a class="el" href="i2c_8c-source.html#l00214">ISR()</a>.</p>
302

    
303
</div>
304
</div><p>
305
<a class="anchor" name="4a0f9de5ac14f60d678cda392921a629"></a><!-- doxytag: member="ring_buffer.h::RING_BUFFER_REMOVE" ref="4a0f9de5ac14f60d678cda392921a629" args="(buf, val_ret)" -->
306
<div class="memitem">
307
<div class="memproto">
308
      <table class="memname">
309
        <tr>
310
          <td class="memname">#define RING_BUFFER_REMOVE          </td>
311
          <td>(</td>
312
          <td class="paramtype">buf,         <tr>
313
          <td class="paramkey"></td>
314
          <td></td>
315
          <td class="paramtype">val_ret&nbsp;</td>
316
          <td class="paramname">          </td>
317
          <td>&nbsp;)&nbsp;</td>
318
          <td width="100%"></td>
319
        </tr>
320
      </table>
321
</div>
322
<div class="memdoc">
323

    
324
<p>
325
<b>Value:</b><div class="fragment"><pre class="fragment"><span class="keywordflow">do</span> {    \
326
                (val_ret) = (buf).queue[(buf).start];   \
327
                (buf).start = ((buf).start + 1) % (buf).buffer_size;    \
328
        } <span class="keywordflow">while</span> (0)
329
</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. 
330
<p>
331
<dl compact><dt><b>Parameters:</b></dt><dd>
332
  <table border="0" cellspacing="2" cellpadding="0">
333
    <tr><td valign="top"></td><td valign="top"><em>buf</em>&nbsp;</td><td>The ring buffer to remove from. </td></tr>
334
    <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>
335
  </table>
336
</dl>
337

    
338
<p>Referenced by <a class="el" href="i2c_8c-source.html#l00214">ISR()</a>.</p>
339

    
340
</div>
341
</div><p>
342
</div>
343
<hr size="1"><address style="text-align: right;"><small>Generated on Fri Sep 26 13:39:28 2008 for libdragonfly by&nbsp;
344
<a href="http://www.doxygen.org/index.html">
345
<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.5 </small></address>
346
</body>
347
</html>