ChibiOS/HAL  6.1.0
hal_buffers.h
Go to the documentation of this file.
1 /*
2  ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio
3 
4  Licensed under the Apache License, Version 2.0 (the "License");
5  you may not use this file except in compliance with the License.
6  You may obtain a copy of the License at
7 
8  http://www.apache.org/licenses/LICENSE-2.0
9 
10  Unless required by applicable law or agreed to in writing, software
11  distributed under the License is distributed on an "AS IS" BASIS,
12  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  See the License for the specific language governing permissions and
14  limitations under the License.
15 */
16 
17 /**
18  * @file hal_buffers.h
19  * @brief I/O Buffers macros and structures.
20  *
21  * @addtogroup HAL_BUFFERS
22  * @{
23  */
24 
25 #ifndef HAL_BUFFERS_H
26 #define HAL_BUFFERS_H
27 
28 /*===========================================================================*/
29 /* Driver constants. */
30 /*===========================================================================*/
31 
32 /*===========================================================================*/
33 /* Driver pre-compile time settings. */
34 /*===========================================================================*/
35 
36 /*===========================================================================*/
37 /* Derived constants and error checks. */
38 /*===========================================================================*/
39 
40 /*===========================================================================*/
41 /* Driver data structures and types. */
42 /*===========================================================================*/
43 
44 /**
45  * @brief Type of a generic queue of buffers.
46  */
48 
49 /**
50  * @brief Double buffer notification callback type.
51  *
52  * @param[in] iodbp the buffers queue pointer
53  */
54 typedef void (*bqnotify_t)(io_buffers_queue_t *bqp);
55 
56 /**
57  * @brief Structure of a generic buffers queue.
58  */
60  /**
61  * @brief Queue of waiting threads.
62  */
64  /**
65  * @brief Queue suspended state flag.
66  */
67  bool suspended;
68  /**
69  * @brief Active buffers counter.
70  */
71  volatile size_t bcounter;
72  /**
73  * @brief Buffer write pointer.
74  */
75  uint8_t *bwrptr;
76  /**
77  * @brief Buffer read pointer.
78  */
79  uint8_t *brdptr;
80  /**
81  * @brief Pointer to the buffers boundary.
82  */
83  uint8_t *btop;
84  /**
85  * @brief Size of buffers.
86  * @note The buffer size must be not lower than <tt>sizeof(size_t) + 2</tt>
87  * because the first bytes are used to store the used size of the
88  * buffer.
89  */
90  size_t bsize;
91  /**
92  * @brief Number of buffers.
93  */
94  size_t bn;
95  /**
96  * @brief Queue of buffer objects.
97  */
98  uint8_t *buffers;
99  /**
100  * @brief Pointer for R/W sequential access.
101  * @note It is @p NULL if a new buffer must be fetched from the queue.
102  */
103  uint8_t *ptr;
104  /**
105  * @brief Boundary for R/W sequential access.
106  */
107  uint8_t *top;
108  /**
109  * @brief Data notification callback.
110  */
112  /**
113  * @brief Application defined field.
114  */
115  void *link;
116 };
117 
118 /**
119  * @brief Type of an input buffers queue.
120  */
122 
123 /**
124  * @brief Type of an output buffers queue.
125  */
127 
128 /*===========================================================================*/
129 /* Driver macros. */
130 /*===========================================================================*/
131 
132 /**
133  * @brief Computes the size of a buffers queue buffer size.
134  *
135  * @param[in] n number of buffers in the queue
136  * @param[in] size size of the buffers
137  */
138 #define BQ_BUFFER_SIZE(n, size) \
139  (((size_t)(size) + sizeof (size_t)) * (size_t)(n))
140 
141 /**
142  * @name Macro Functions
143  * @{
144  */
145 /**
146  * @brief Returns the queue's number of buffers.
147  *
148  * @param[in] bqp pointer to an @p io_buffers_queue_t structure
149  * @return The number of buffers.
150  *
151  * @xclass
152  */
153 #define bqSizeX(bqp) ((bqp)->bn)
154 
155 /**
156  * @brief Return the ready buffers number.
157  * @details Returns the number of filled buffers if used on an input queue
158  * or the number of empty buffers if used on an output queue.
159  *
160  * @param[in] bqp pointer to an @p io_buffers_queue_t structure
161  * @return The number of ready buffers.
162  *
163  * @iclass
164  */
165 #define bqSpaceI(bqp) ((bqp)->bcounter)
166 
167 /**
168  * @brief Returns the queue application-defined link.
169  *
170  * @param[in] bqp pointer to an @p io_buffers_queue_t structure
171  * @return The application-defined link.
172  *
173  * @special
174  */
175 #define bqGetLinkX(bqp) ((bqp)->link)
176 
177 /**
178  * @brief Return the suspended state of the queue.
179  *
180  * @param[in] bqp pointer to an @p io_buffers_queue_t structure
181  * @return The suspended state.
182  * @retval false if blocking access to the queue is enabled.
183  * @retval true if blocking access to the queue is suspended.
184  *
185  * @xclass
186  */
187 #define bqIsSuspendedX(bqp) ((bqp)->suspended)
188 
189 /**
190  * @brief Puts the queue in suspended state.
191  * @details When the queue is put in suspended state all waiting threads are
192  * woken with message @p MSG_RESET and subsequent attempt at waiting
193  * on the queue will result in an immediate return with @p MSG_RESET
194  * message.
195  * @note The content of the queue is not altered, queues can be accessed
196  * is suspended state until a blocking operation is met then a
197  * @p MSG_RESET occurs.
198  *
199  * @param[in] bqp pointer to an @p io_buffers_queue_t structure
200  *
201  * @iclass
202  */
203 #define bqSuspendI(bqp) { \
204  (bqp)->suspended = true; \
205  osalThreadDequeueAllI(&(bqp)->waiting, MSG_RESET); \
206 }
207 
208 /**
209  * @brief Resumes normal queue operations.
210  *
211  * @param[in] bqp pointer to an @p io_buffers_queue_t structure
212  *
213  * @xclass
214  */
215 #define bqResumeX(bqp) { \
216  (bqp)->suspended = false; \
217 }
218 
219 /**
220  * @brief Evaluates to @p true if the specified input buffers queue is empty.
221  *
222  * @param[in] ibqp pointer to an @p input_buffers_queue_t structure
223  * @return The queue status.
224  * @retval false if the queue is not empty.
225  * @retval true if the queue is empty.
226  *
227  * @iclass
228  */
229 #define ibqIsEmptyI(ibqp) ((bool)(bqSpaceI(ibqp) == 0U))
230 
231 /**
232  * @brief Evaluates to @p true if the specified input buffers queue is full.
233  *
234  * @param[in] ibqp pointer to an @p input_buffers_queue_t structure
235  * @return The queue status.
236  * @retval false if the queue is not full.
237  * @retval true if the queue is full.
238  *
239  * @iclass
240  */
241 #define ibqIsFullI(ibqp) \
242  /*lint -save -e9007 [13.5] No side effects, a pointer is passed.*/ \
243  ((bool)(((ibqp)->bwrptr == (ibqp)->brdptr) && ((ibqp)->bcounter != 0U))) \
244  /*lint -restore*/
245 
246 /**
247  * @brief Evaluates to @p true if the specified output buffers queue is empty.
248  *
249  * @param[in] obqp pointer to an @p output_buffers_queue_t structure
250  * @return The queue status.
251  * @retval false if the queue is not empty.
252  * @retval true if the queue is empty.
253  *
254  * @iclass
255  */
256 #define obqIsEmptyI(obqp) \
257  /*lint -save -e9007 [13.5] No side effects, a pointer is passed.*/ \
258  ((bool)(((obqp)->bwrptr == (obqp)->brdptr) && ((obqp)->bcounter != 0U))) \
259  /*lint -restore*/
260 
261 /**
262  * @brief Evaluates to @p true if the specified output buffers queue is full.
263  *
264  * @param[in] obqp pointer to an @p output_buffers_queue_t structure
265  * @return The queue status.
266  * @retval false if the queue is not full.
267  * @retval true if the queue is full.
268  *
269  * @iclass
270  */
271 #define obqIsFullI(obqp) ((bool)(bqSpaceI(obqp) == 0U))
272 /** @} */
273 
274 /*===========================================================================*/
275 /* External declarations. */
276 /*===========================================================================*/
277 
278 #ifdef __cplusplus
279 extern "C" {
280 #endif
281  void ibqObjectInit(input_buffers_queue_t *ibqp, bool suspended, uint8_t *bp,
282  size_t size, size_t n, bqnotify_t infy, void *link);
283  void ibqResetI(input_buffers_queue_t *ibqp);
285  void ibqPostFullBufferI(input_buffers_queue_t *ibqp, size_t size);
287  sysinterval_t timeout);
289  sysinterval_t timeout);
293  size_t ibqReadTimeout(input_buffers_queue_t *ibqp, uint8_t *bp,
294  size_t n, sysinterval_t timeout);
295  void obqObjectInit(output_buffers_queue_t *obqp, bool suspended, uint8_t *bp,
296  size_t size, size_t n, bqnotify_t onfy, void *link);
297  void obqResetI(output_buffers_queue_t *obqp);
299  size_t *sizep);
302  sysinterval_t timeout);
304  sysinterval_t timeout);
305  void obqPostFullBuffer(output_buffers_queue_t *obqp, size_t size);
306  void obqPostFullBufferS(output_buffers_queue_t *obqp, size_t size);
307  msg_t obqPutTimeout(output_buffers_queue_t *obqp, uint8_t b,
308  sysinterval_t timeout);
309  size_t obqWriteTimeout(output_buffers_queue_t *obqp, const uint8_t *bp,
310  size_t n, sysinterval_t timeout);
312  void obqFlush(output_buffers_queue_t *obqp);
313 #ifdef __cplusplus
314 }
315 #endif
316 
317 #endif /* HAL_BUFFERS_H */
318 
319 /** @} */
void obqFlush(output_buffers_queue_t *obqp)
Flushes the current, partially filled, buffer to the queue.
Definition: hal_buffers.c:832
uint8_t * ibqGetEmptyBufferI(input_buffers_queue_t *ibqp)
Gets the next empty buffer from the queue.
Definition: hal_buffers.c:129
uint8_t * obqGetFullBufferI(output_buffers_queue_t *obqp, size_t *sizep)
Gets the next filled buffer from the queue.
Definition: hal_buffers.c:486
msg_t obqGetEmptyBufferTimeoutS(output_buffers_queue_t *obqp, sysinterval_t timeout)
Gets the next empty buffer from the queue.
Definition: hal_buffers.c:577
void obqReleaseEmptyBufferI(output_buffers_queue_t *obqp)
Releases the next filled buffer back in the queue.
Definition: hal_buffers.c:508
io_buffers_queue_t output_buffers_queue_t
Type of an output buffers queue.
Definition: hal_buffers.h:126
volatile size_t bcounter
Active buffers counter.
Definition: hal_buffers.h:71
msg_t ibqGetFullBufferTimeout(input_buffers_queue_t *ibqp, sysinterval_t timeout)
Gets the next filled buffer from the queue.
Definition: hal_buffers.c:190
uint8_t * btop
Pointer to the buffers boundary.
Definition: hal_buffers.h:83
void ibqResetI(input_buffers_queue_t *ibqp)
Resets an input buffers queue.
Definition: hal_buffers.c:107
void * link
Application defined field.
Definition: hal_buffers.h:115
bqnotify_t notify
Data notification callback.
Definition: hal_buffers.h:111
io_buffers_queue_t input_buffers_queue_t
Type of an input buffers queue.
Definition: hal_buffers.h:121
void obqPostFullBufferS(output_buffers_queue_t *obqp, size_t size)
Posts a new filled buffer to the queue.
Definition: hal_buffers.c:626
uint8_t * ptr
Pointer for R/W sequential access.
Definition: hal_buffers.h:103
int32_t msg_t
Type of a message.
Definition: osal.h:160
size_t ibqReadTimeout(input_buffers_queue_t *ibqp, uint8_t *bp, size_t n, sysinterval_t timeout)
Input queue read with timeout.
Definition: hal_buffers.c:358
Type of a thread queue.
Definition: osal.h:232
uint8_t * bwrptr
Buffer write pointer.
Definition: hal_buffers.h:75
void obqPostFullBuffer(output_buffers_queue_t *obqp, size_t size)
Posts a new filled buffer to the queue.
Definition: hal_buffers.c:610
size_t bn
Number of buffers.
Definition: hal_buffers.h:94
void ibqPostFullBufferI(input_buffers_queue_t *ibqp, size_t size)
Posts a new filled buffer to the queue.
Definition: hal_buffers.c:148
msg_t ibqGetFullBufferTimeoutS(input_buffers_queue_t *ibqp, sysinterval_t timeout)
Gets the next filled buffer from the queue.
Definition: hal_buffers.c:222
size_t obqWriteTimeout(output_buffers_queue_t *obqp, const uint8_t *bp, size_t n, sysinterval_t timeout)
Output queue write with timeout.
Definition: hal_buffers.c:721
bool obqTryFlushI(output_buffers_queue_t *obqp)
Flushes the current, partially filled, buffer to the queue.
Definition: hal_buffers.c:795
void(* bqnotify_t)(io_buffers_queue_t *bqp)
Double buffer notification callback type.
Definition: hal_buffers.h:54
msg_t obqGetEmptyBufferTimeout(output_buffers_queue_t *obqp, sysinterval_t timeout)
Gets the next empty buffer from the queue.
Definition: hal_buffers.c:545
void obqObjectInit(output_buffers_queue_t *obqp, bool suspended, uint8_t *bp, size_t size, size_t n, bqnotify_t onfy, void *link)
Initializes an output buffers queue object.
Definition: hal_buffers.c:432
uint8_t * buffers
Queue of buffer objects.
Definition: hal_buffers.h:98
uint32_t sysinterval_t
Type of system time interval.
Definition: osal.h:170
msg_t obqPutTimeout(output_buffers_queue_t *obqp, uint8_t b, sysinterval_t timeout)
Output queue write with timeout.
Definition: hal_buffers.c:671
size_t bsize
Size of buffers.
Definition: hal_buffers.h:90
Structure of a generic buffers queue.
Definition: hal_buffers.h:59
threads_queue_t waiting
Queue of waiting threads.
Definition: hal_buffers.h:63
bool suspended
Queue suspended state flag.
Definition: hal_buffers.h:67
msg_t ibqGetTimeout(input_buffers_queue_t *ibqp, sysinterval_t timeout)
Input queue read with timeout.
Definition: hal_buffers.c:309
void obqResetI(output_buffers_queue_t *obqp)
Resets an output buffers queue.
Definition: hal_buffers.c:463
uint8_t * top
Boundary for R/W sequential access.
Definition: hal_buffers.h:107
void ibqReleaseEmptyBufferS(input_buffers_queue_t *ibqp)
Releases the buffer back in the queue.
Definition: hal_buffers.c:269
void ibqObjectInit(input_buffers_queue_t *ibqp, bool suspended, uint8_t *bp, size_t size, size_t n, bqnotify_t infy, void *link)
Initializes an input buffers queue object.
Definition: hal_buffers.c:76
uint8_t * brdptr
Buffer read pointer.
Definition: hal_buffers.h:79
void ibqReleaseEmptyBuffer(input_buffers_queue_t *ibqp)
Releases the buffer back in the queue.
Definition: hal_buffers.c:254