ChibiOS/NIL  3.2.2
chobjfifos.h
Go to the documentation of this file.
1 /*
2  ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio.
3 
4  This file is part of ChibiOS.
5 
6  ChibiOS is free software; you can redistribute it and/or modify
7  it under the terms of the GNU General Public License as published by
8  the Free Software Foundation; either version 3 of the License, or
9  (at your option) any later version.
10 
11  ChibiOS is distributed in the hope that it will be useful,
12  but WITHOUT ANY WARRANTY; without even the implied warranty of
13  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14  GNU General Public License for more details.
15 
16  You should have received a copy of the GNU General Public License
17  along with this program. If not, see <http://www.gnu.org/licenses/>.
18 */
19 
20 /**
21  * @file chobjfifos.h
22  * @brief Objects FIFO structures and macros.
23  * @details This module implements a generic FIFO queue of objects by
24  * coupling a Guarded Memory Pool (for objects storage) and
25  * a MailBox.<br>
26  * On the sender side free objects are taken from the pool, filled
27  * and then sent to the receiver, on the receiver side objects are
28  * fetched, used and then returned to the pool.
29  * Operations defined for object FIFOs:
30  * - <b>Take</b>: An object is taken from the pool of the free
31  * objects, can be blocking.
32  * - <b>Return</b>: An object is returned to the pool of the
33  * free objects, it is guaranteed to be non-blocking.
34  * - <b>Send</b>: An object is sent through the mailbox, it is
35  * guaranteed to be non-blocking
36  * - <b>Receive</b>: An object is received from the mailbox,
37  * can be blocking.
38  * .
39  *
40  * @addtogroup oslib_objects_fifos
41  * @{
42  */
43 
44 #ifndef CHOBJFIFOS_H
45 #define CHOBJFIFOS_H
46 
47 #if (CH_CFG_USE_OBJ_FIFOS == TRUE) || defined(__DOXYGEN__)
48 
49 /*===========================================================================*/
50 /* Module constants. */
51 /*===========================================================================*/
52 
53 /*===========================================================================*/
54 /* Module pre-compile time settings. */
55 /*===========================================================================*/
56 
57 /*===========================================================================*/
58 /* Derived constants and error checks. */
59 /*===========================================================================*/
60 
61 #if CH_CFG_USE_MEMPOOLS == FALSE
62 #error "CH_CFG_USE_OBJ_FIFOS requires CH_CFG_USE_MEMPOOLS"
63 #endif
64 
65 #if CH_CFG_USE_SEMAPHORES == FALSE
66 #error "CH_CFG_USE_OBJ_FIFOS requires CH_CFG_USE_SEMAPHORES"
67 #endif
68 
69 #if CH_CFG_USE_MAILBOXES == FALSE
70 #error "CH_CFG_USE_OBJ_FIFOS requires CH_CFG_USE_MAILBOXES"
71 #endif
72 
73 /*===========================================================================*/
74 /* Module data structures and types. */
75 /*===========================================================================*/
76 
77 /**
78  * @brief Type of an objects FIFO.
79  */
80 typedef struct ch_objects_fifo {
81  /**
82  * @brief Pool of the free objects.
83  */
85  /**
86  * @brief Mailbox of the sent objects.
87  */
90 
91 /*===========================================================================*/
92 /* Module macros. */
93 /*===========================================================================*/
94 
95 /*===========================================================================*/
96 /* External declarations. */
97 /*===========================================================================*/
98 
99 #ifdef __cplusplus
100 extern "C" {
101 #endif
102 
103 #ifdef __cplusplus
104 }
105 #endif
106 
107 /*===========================================================================*/
108 /* Module inline functions. */
109 /*===========================================================================*/
110 
111 /**
112  * @brief Initializes a FIFO object.
113  * @pre The messages size must be a multiple of the alignment
114  * requirement.
115  *
116  * @param[out] ofp pointer to a @p objects_fifo_t structure
117  * @param[in] objsize size of objects
118  * @param[in] objn number of objects available
119  * @param[in] objalign required objects alignment
120  * @param[in] objbuf pointer to the buffer of objects, it must be able
121  * to hold @p objn objects of @p objsize size with
122  * @p objealign alignment
123  * @param[in] msgbuf pointer to the buffer of messages, it must be able
124  * to hold @p objn messages
125  *
126  * @init
127  */
128 static inline void chFifoObjectInitAligned(objects_fifo_t *ofp, size_t objsize,
129  size_t objn, unsigned objalign,
130  void *objbuf, msg_t *msgbuf) {
131 
132  chDbgCheck((objsize >= objalign) && ((objsize % objalign) == 0U));
133 
134  chGuardedPoolObjectInitAligned(&ofp->free, objsize, objalign);
135  chGuardedPoolLoadArray(&ofp->free, objbuf, objn);
136  chMBObjectInit(&ofp->mbx, msgbuf, objn);
137 }
138 
139 /**
140  * @brief Initializes a FIFO object.
141  * @pre The messages size must be a multiple of the alignment
142  * requirement.
143  *
144  * @param[out] ofp pointer to a @p objects_fifo_t structure
145  * @param[in] objsize size of objects
146  * @param[in] objn number of objects available
147  * @param[in] objbuf pointer to the buffer of objects, it must be able
148  * to hold @p objn objects of @p objsize size with
149  * @p objealign alignment
150  * @param[in] msgbuf pointer to the buffer of messages, it must be able
151  * to hold @p objn messages
152  *
153  * @init
154  */
155 static inline void chFifoObjectInit(objects_fifo_t *ofp, size_t objsize,
156  size_t objn, void *objbuf,
157  msg_t *msgbuf) {
158 
159  chFifoObjectInitAligned(ofp, objsize, objn,
160  PORT_NATURAL_ALIGN,
161  objbuf, msgbuf);
162 }
163 
164 /**
165  * @brief Allocates a free object.
166  *
167  * @param[in] ofp pointer to a @p objects_fifo_t structure
168  * @return The pointer to the allocated object.
169  * @retval NULL if an object is not immediately available.
170  *
171  * @iclass
172  */
173 static inline void *chFifoTakeObjectI(objects_fifo_t *ofp) {
174 
175  return chGuardedPoolAllocI(&ofp->free);
176 }
177 
178 /**
179  * @brief Allocates a free object.
180  *
181  * @param[in] ofp pointer to a @p objects_fifo_t structure
182  * @param[in] timeout the number of ticks before the operation timeouts,
183  * the following special values are allowed:
184  * - @a TIME_IMMEDIATE immediate timeout.
185  * - @a TIME_INFINITE no timeout.
186  * .
187  * @return The pointer to the allocated object.
188  * @retval NULL if an object is not available within the specified
189  * timeout.
190  *
191  * @sclass
192  */
193 static inline void *chFifoTakeObjectTimeoutS(objects_fifo_t *ofp,
194  sysinterval_t timeout) {
195 
196  return chGuardedPoolAllocTimeoutS(&ofp->free, timeout);
197 }
198 
199 /**
200  * @brief Allocates a free object.
201  *
202  * @param[in] ofp pointer to a @p objects_fifo_t structure
203  * @param[in] timeout the number of ticks before the operation timeouts,
204  * the following special values are allowed:
205  * - @a TIME_IMMEDIATE immediate timeout.
206  * - @a TIME_INFINITE no timeout.
207  * .
208  * @return The pointer to the allocated object.
209  * @retval NULL if an object is not available within the specified
210  * timeout.
211  *
212  * @api
213  */
214 static inline void *chFifoTakeObjectTimeout(objects_fifo_t *ofp,
215  sysinterval_t timeout) {
216 
217  return chGuardedPoolAllocTimeout(&ofp->free, timeout);
218 }
219 
220 /**
221  * @brief Releases a fetched object.
222  *
223  * @param[in] ofp pointer to a @p objects_fifo_t structure
224  * @param[in] objp pointer to the object to be released
225  *
226  * @iclass
227  */
228 static inline void chFifoReturnObjectI(objects_fifo_t *ofp,
229  void *objp) {
230 
231  chGuardedPoolFreeI(&ofp->free, objp);
232 }
233 
234 /**
235  * @brief Releases a fetched object.
236  *
237  * @param[in] ofp pointer to a @p objects_fifo_t structure
238  * @param[in] objp pointer to the object to be released
239  *
240  * @sclass
241  */
242 static inline void chFifoReturnObjectS(objects_fifo_t *ofp,
243  void *objp) {
244 
245  chGuardedPoolFreeS(&ofp->free, objp);
246 }
247 
248 /**
249  * @brief Releases a fetched object.
250  *
251  * @param[in] ofp pointer to a @p objects_fifo_t structure
252  * @param[in] objp pointer to the object to be released
253  *
254  * @api
255  */
256 static inline void chFifoReturnObject(objects_fifo_t *ofp,
257  void *objp) {
258 
259  chGuardedPoolFree(&ofp->free, objp);
260 }
261 
262 /**
263  * @brief Posts an object.
264  * @note By design the object can be always immediately posted.
265  *
266  * @param[in] ofp pointer to a @p objects_fifo_t structure
267  * @param[in] objp pointer to the object to be posted
268  *
269  * @iclass
270  */
271 static inline void chFifoSendObjectI(objects_fifo_t *ofp,
272  void *objp) {
273  msg_t msg;
274 
275  msg = chMBPostI(&ofp->mbx, (msg_t)objp);
276  chDbgAssert(msg == MSG_OK, "post failed");
277 }
278 
279 /**
280  * @brief Posts an object.
281  * @note By design the object can be always immediately posted.
282  *
283  * @param[in] ofp pointer to a @p objects_fifo_t structure
284  * @param[in] objp pointer to the object to be posted
285  *
286  * @sclass
287  */
288 static inline void chFifoSendObjectS(objects_fifo_t *ofp,
289  void *objp) {
290  msg_t msg;
291 
292  msg = chMBPostTimeoutS(&ofp->mbx, (msg_t)objp, TIME_IMMEDIATE);
293  chDbgAssert(msg == MSG_OK, "post failed");
294 }
295 
296 /**
297  * @brief Posts an object.
298  * @note By design the object can be always immediately posted.
299  *
300  * @param[in] ofp pointer to a @p objects_fifo_t structure
301  * @param[in] objp pointer to the object to be released
302  *
303  * @api
304  */
305 static inline void chFifoSendObject(objects_fifo_t *ofp, void *objp) {
306 
307  msg_t msg;
308 
309  msg = chMBPostTimeout(&ofp->mbx, (msg_t)objp, TIME_IMMEDIATE);
310  chDbgAssert(msg == MSG_OK, "post failed");
311 }
312 
313 /**
314  * @brief Posts an high priority object.
315  * @note By design the object can be always immediately posted.
316  *
317  * @param[in] ofp pointer to a @p objects_fifo_t structure
318  * @param[in] objp pointer to the object to be posted
319  *
320  * @iclass
321  */
322 static inline void chFifoSendObjectAheadI(objects_fifo_t *ofp,
323  void *objp) {
324  msg_t msg;
325 
326  msg = chMBPostAheadI(&ofp->mbx, (msg_t)objp);
327  chDbgAssert(msg == MSG_OK, "post failed");
328 }
329 
330 /**
331  * @brief Posts an high priority object.
332  * @note By design the object can be always immediately posted.
333  *
334  * @param[in] ofp pointer to a @p objects_fifo_t structure
335  * @param[in] objp pointer to the object to be posted
336  *
337  * @sclass
338  */
339 static inline void chFifoSendObjectAheadS(objects_fifo_t *ofp,
340  void *objp) {
341  msg_t msg;
342 
343  msg = chMBPostAheadTimeoutS(&ofp->mbx, (msg_t)objp, TIME_IMMEDIATE);
344  chDbgAssert(msg == MSG_OK, "post failed");
345 }
346 
347 /**
348  * @brief Posts an high priority object.
349  * @note By design the object can be always immediately posted.
350  *
351  * @param[in] ofp pointer to a @p objects_fifo_t structure
352  * @param[in] objp pointer to the object to be released
353  *
354  * @api
355  */
356 static inline void chFifoSendObjectAhead(objects_fifo_t *ofp, void *objp) {
357 
358  msg_t msg;
359 
360  msg = chMBPostAheadTimeout(&ofp->mbx, (msg_t)objp, TIME_IMMEDIATE);
361  chDbgAssert(msg == MSG_OK, "post failed");
362 }
363 
364 /**
365  * @brief Fetches an object.
366  *
367  * @param[in] ofp pointer to a @p objects_fifo_t structure
368  * @param[in] objpp pointer to the fetched object reference
369  * @return The operation status.
370  * @retval MSG_OK if an object has been correctly fetched.
371  * @retval MSG_TIMEOUT if the FIFO is empty and a message cannot be fetched.
372  *
373  * @iclass
374  */
375 static inline msg_t chFifoReceiveObjectI(objects_fifo_t *ofp,
376  void **objpp) {
377 
378  return chMBFetchI(&ofp->mbx, (msg_t *)objpp);
379 }
380 
381 /**
382  * @brief Fetches an object.
383  *
384  * @param[in] ofp pointer to a @p objects_fifo_t structure
385  * @param[in] objpp pointer to the fetched object reference
386  * @param[in] timeout the number of ticks before the operation timeouts,
387  * the following special values are allowed:
388  * - @a TIME_IMMEDIATE immediate timeout.
389  * - @a TIME_INFINITE no timeout.
390  * .
391  * @return The operation status.
392  * @retval MSG_OK if an object has been correctly fetched.
393  * @retval MSG_TIMEOUT if the operation has timed out.
394  *
395  * @sclass
396  */
398  void **objpp,
399  sysinterval_t timeout) {
400 
401  return chMBFetchTimeoutS(&ofp->mbx, (msg_t *)objpp, timeout);
402 }
403 
404 /**
405  * @brief Fetches an object.
406  *
407  * @param[in] ofp pointer to a @p objects_fifo_t structure
408  * @param[in] objpp pointer to the fetched object reference
409  * @param[in] timeout the number of ticks before the operation timeouts,
410  * the following special values are allowed:
411  * - @a TIME_IMMEDIATE immediate timeout.
412  * - @a TIME_INFINITE no timeout.
413  * .
414  * @return The operation status.
415  * @retval MSG_OK if an object has been correctly fetched.
416  * @retval MSG_TIMEOUT if the operation has timed out.
417  *
418  * @api
419  */
421  void **objpp,
422  sysinterval_t timeout) {
423 
424  return chMBFetchTimeout(&ofp->mbx, (msg_t *)objpp, timeout);
425 }
426 #endif /* CH_CFG_USE_OBJ_FIFOS == TRUE */
427 
428 #endif /* CHOBJFIFOS_H */
429 
430 /** @} */
mailbox_t mbx
Mailbox of the sent objects.
Definition: chobjfifos.h:88
static void chFifoReturnObjectI(objects_fifo_t *ofp, void *objp)
Releases a fetched object.
Definition: chobjfifos.h:228
msg_t chMBPostI(mailbox_t *mbp, msg_t msg)
Posts a message into a mailbox.
Definition: chmboxes.c:243
static void chFifoSendObjectI(objects_fifo_t *ofp, void *objp)
Posts an object.
Definition: chobjfifos.h:271
static msg_t chFifoReceiveObjectI(objects_fifo_t *ofp, void **objpp)
Fetches an object.
Definition: chobjfifos.h:375
void chGuardedPoolFree(guarded_memory_pool_t *gmp, void *objp)
Releases an object into a guarded memory pool.
Definition: chmempools.c:325
static void chFifoSendObject(objects_fifo_t *ofp, void *objp)
Posts an object.
Definition: chobjfifos.h:305
static void chFifoSendObjectAheadI(objects_fifo_t *ofp, void *objp)
Posts an high priority object.
Definition: chobjfifos.h:322
static void * chFifoTakeObjectTimeout(objects_fifo_t *ofp, sysinterval_t timeout)
Allocates a free object.
Definition: chobjfifos.h:214
msg_t chMBPostAheadTimeoutS(mailbox_t *mbp, msg_t msg, sysinterval_t timeout)
Posts an high priority message into a mailbox.
Definition: chmboxes.c:319
void * chGuardedPoolAllocTimeout(guarded_memory_pool_t *gmp, sysinterval_t timeout)
Allocates an object from a guarded memory pool.
Definition: chmempools.c:302
void chMBObjectInit(mailbox_t *mbp, msg_t *buf, size_t n)
Initializes a mailbox_t object.
Definition: chmboxes.c:87
#define TIME_IMMEDIATE
Zero time specification for some functions with a timeout specification.
Definition: ch.h:119
static void * chGuardedPoolAllocI(guarded_memory_pool_t *gmp)
Allocates an object from a guarded memory pool.
Definition: chmempools.h:275
msg_t chMBFetchI(mailbox_t *mbp, msg_t *msgp)
Retrieves a message from a mailbox.
Definition: chmboxes.c:493
static void chFifoReturnObjectS(objects_fifo_t *ofp, void *objp)
Releases a fetched object.
Definition: chobjfifos.h:242
static void chFifoSendObjectAheadS(objects_fifo_t *ofp, void *objp)
Posts an high priority object.
Definition: chobjfifos.h:339
msg_t chMBPostAheadTimeout(mailbox_t *mbp, msg_t msg, sysinterval_t timeout)
Posts an high priority message into a mailbox.
Definition: chmboxes.c:290
msg_t chMBPostTimeoutS(mailbox_t *mbp, msg_t msg, sysinterval_t timeout)
Posts a message into a mailbox.
Definition: chmboxes.c:194
Type of an objects FIFO.
Definition: chobjfifos.h:80
static void * chFifoTakeObjectTimeoutS(objects_fifo_t *ofp, sysinterval_t timeout)
Allocates a free object.
Definition: chobjfifos.h:193
static void * chFifoTakeObjectI(objects_fifo_t *ofp)
Allocates a free object.
Definition: chobjfifos.h:173
static void chGuardedPoolFreeS(guarded_memory_pool_t *gmp, void *objp)
Releases an object into a guarded memory pool.
Definition: chmempools.h:317
msg_t chMBPostAheadI(mailbox_t *mbp, msg_t msg)
Posts an high priority message into a mailbox.
Definition: chmboxes.c:368
#define chDbgAssert(c, r)
Condition assertion.
Definition: ch.h:1477
static msg_t chFifoReceiveObjectTimeout(objects_fifo_t *ofp, void **objpp, sysinterval_t timeout)
Fetches an object.
Definition: chobjfifos.h:420
uint32_t sysinterval_t
Type of time interval.
Definition: ch.h:553
msg_t chMBFetchTimeout(mailbox_t *mbp, msg_t *msgp, sysinterval_t timeout)
Retrieves a message from a mailbox.
Definition: chmboxes.c:415
static void chFifoSendObjectAhead(objects_fifo_t *ofp, void *objp)
Posts an high priority object.
Definition: chobjfifos.h:356
static void chFifoObjectInitAligned(objects_fifo_t *ofp, size_t objsize, size_t objn, unsigned objalign, void *objbuf, msg_t *msgbuf)
Initializes a FIFO object.
Definition: chobjfifos.h:128
static void chFifoObjectInit(objects_fifo_t *ofp, size_t objsize, size_t objn, void *objbuf, msg_t *msgbuf)
Initializes a FIFO object.
Definition: chobjfifos.h:155
#define MSG_OK
OK wakeup message.
Definition: ch.h:100
static void chGuardedPoolFreeI(guarded_memory_pool_t *gmp, void *objp)
Releases an object into a guarded memory pool.
Definition: chmempools.h:299
static void chFifoSendObjectS(objects_fifo_t *ofp, void *objp)
Posts an object.
Definition: chobjfifos.h:288
void * chGuardedPoolAllocTimeoutS(guarded_memory_pool_t *gmp, sysinterval_t timeout)
Allocates an object from a guarded memory pool.
Definition: chmempools.c:275
struct ch_objects_fifo objects_fifo_t
Type of an objects FIFO.
static msg_t chFifoReceiveObjectTimeoutS(objects_fifo_t *ofp, void **objpp, sysinterval_t timeout)
Fetches an object.
Definition: chobjfifos.h:397
#define chDbgCheck(c)
Function parameters check.
Definition: ch.h:1451
guarded_memory_pool_t free
Pool of the free objects.
Definition: chobjfifos.h:84
void chGuardedPoolObjectInitAligned(guarded_memory_pool_t *gmp, size_t size, unsigned align)
Initializes an empty guarded memory pool.
Definition: chmempools.c:226
Guarded memory pool descriptor.
Definition: chmempools.h:77
msg_t chMBPostTimeout(mailbox_t *mbp, msg_t msg, sysinterval_t timeout)
Posts a message into a mailbox.
Definition: chmboxes.c:165
Structure representing a mailbox object.
Definition: chmboxes.h:52
void chGuardedPoolLoadArray(guarded_memory_pool_t *gmp, void *p, size_t n)
Loads a guarded memory pool with an array of static objects.
Definition: chmempools.c:247
msg_t chMBFetchTimeoutS(mailbox_t *mbp, msg_t *msgp, sysinterval_t timeout)
Retrieves a message from a mailbox.
Definition: chmboxes.c:444
static void chFifoReturnObject(objects_fifo_t *ofp, void *objp)
Releases a fetched object.
Definition: chobjfifos.h:256