ChibiOS/NIL  3.2.2
chmboxes.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 chmboxes.h
22  * @brief Mailboxes macros and structures.
23  *
24  * @addtogroup oslib_mailboxes
25  * @{
26  */
27 
28 #ifndef CHMBOXES_H
29 #define CHMBOXES_H
30 
31 #if (CH_CFG_USE_MAILBOXES == TRUE) || defined(__DOXYGEN__)
32 
33 /*===========================================================================*/
34 /* Module constants. */
35 /*===========================================================================*/
36 
37 /*===========================================================================*/
38 /* Module pre-compile time settings. */
39 /*===========================================================================*/
40 
41 /*===========================================================================*/
42 /* Derived constants and error checks. */
43 /*===========================================================================*/
44 
45 /*===========================================================================*/
46 /* Module data structures and types. */
47 /*===========================================================================*/
48 
49 /**
50  * @brief Structure representing a mailbox object.
51  */
52 typedef struct {
53  msg_t *buffer; /**< @brief Pointer to the mailbox
54  buffer. */
55  msg_t *top; /**< @brief Pointer to the location
56  after the buffer. */
57  msg_t *wrptr; /**< @brief Write pointer. */
58  msg_t *rdptr; /**< @brief Read pointer. */
59  size_t cnt; /**< @brief Messages in queue. */
60  bool reset; /**< @brief True in reset state. */
61  threads_queue_t qw; /**< @brief Queued writers. */
62  threads_queue_t qr; /**< @brief Queued readers. */
63 } mailbox_t;
64 
65 /*===========================================================================*/
66 /* Module macros. */
67 /*===========================================================================*/
68 
69 /**
70  * @brief Data part of a static mailbox initializer.
71  * @details This macro should be used when statically initializing a
72  * mailbox that is part of a bigger structure.
73  *
74  * @param[in] name the name of the mailbox variable
75  * @param[in] buffer pointer to the mailbox buffer array of @p msg_t
76  * @param[in] size number of @p msg_t elements in the buffer array
77  */
78 #define _MAILBOX_DATA(name, buffer, size) { \
79  (msg_t *)(buffer), \
80  (msg_t *)(buffer) + size, \
81  (msg_t *)(buffer), \
82  (msg_t *)(buffer), \
83  (size_t)0, \
84  false, \
85  _THREADS_QUEUE_DATA(name.qw), \
86  _THREADS_QUEUE_DATA(name.qr), \
87 }
88 
89 /**
90  * @brief Static mailbox initializer.
91  * @details Statically initialized mailboxes require no explicit
92  * initialization using @p chMBObjectInit().
93  *
94  * @param[in] name the name of the mailbox variable
95  * @param[in] buffer pointer to the mailbox buffer array of @p msg_t
96  * @param[in] size number of @p msg_t elements in the buffer array
97  */
98 #define MAILBOX_DECL(name, buffer, size) \
99  mailbox_t name = _MAILBOX_DATA(name, buffer, size)
100 
101 /*===========================================================================*/
102 /* External declarations. */
103 /*===========================================================================*/
104 
105 #ifdef __cplusplus
106 extern "C" {
107 #endif
108  void chMBObjectInit(mailbox_t *mbp, msg_t *buf, size_t n);
109  void chMBReset(mailbox_t *mbp);
110  void chMBResetI(mailbox_t *mbp);
111  msg_t chMBPostTimeout(mailbox_t *mbp, msg_t msg, sysinterval_t timeout);
112  msg_t chMBPostTimeoutS(mailbox_t *mbp, msg_t msg, sysinterval_t timeout);
113  msg_t chMBPostI(mailbox_t *mbp, msg_t msg);
114  msg_t chMBPostAheadTimeout(mailbox_t *mbp, msg_t msg, sysinterval_t timeout);
115  msg_t chMBPostAheadTimeoutS(mailbox_t *mbp, msg_t msg, sysinterval_t timeout);
116  msg_t chMBPostAheadI(mailbox_t *mbp, msg_t msg);
117  msg_t chMBFetchTimeout(mailbox_t *mbp, msg_t *msgp, sysinterval_t timeout);
118  msg_t chMBFetchTimeoutS(mailbox_t *mbp, msg_t *msgp, sysinterval_t timeout);
119  msg_t chMBFetchI(mailbox_t *mbp, msg_t *msgp);
120 #ifdef __cplusplus
121 }
122 #endif
123 
124 /*===========================================================================*/
125 /* Module inline functions. */
126 /*===========================================================================*/
127 
128 /**
129  * @brief Returns the mailbox buffer size as number of messages.
130  *
131  * @param[in] mbp the pointer to an initialized @p mailbox_t object
132  * @return The size of the mailbox.
133  *
134  * @iclass
135  */
136 static inline size_t chMBGetSizeI(const mailbox_t *mbp) {
137 
138  /*lint -save -e9033 [10.8] Perfectly safe pointers
139  arithmetic.*/
140  return (size_t)(mbp->top - mbp->buffer);
141  /*lint -restore*/
142 }
143 
144 /**
145  * @brief Returns the number of used message slots into a mailbox.
146  *
147  * @param[in] mbp the pointer to an initialized @p mailbox_t object
148  * @return The number of queued messages.
149  *
150  * @iclass
151  */
152 static inline size_t chMBGetUsedCountI(const mailbox_t *mbp) {
153 
155 
156  return mbp->cnt;
157 }
158 
159 /**
160  * @brief Returns the number of free message slots into a mailbox.
161  *
162  * @param[in] mbp the pointer to an initialized @p mailbox_t object
163  * @return The number of empty message slots.
164  *
165  * @iclass
166  */
167 static inline size_t chMBGetFreeCountI(const mailbox_t *mbp) {
168 
170 
171  return chMBGetSizeI(mbp) - chMBGetUsedCountI(mbp);
172 }
173 
174 /**
175  * @brief Returns the next message in the queue without removing it.
176  * @pre A message must be waiting in the queue for this function to work
177  * or it would return garbage. The correct way to use this macro is
178  * to use @p chMBGetUsedCountI() and then use this macro, all within
179  * a lock state.
180  *
181  * @param[in] mbp the pointer to an initialized @p mailbox_t object
182  * @return The next message in queue.
183  *
184  * @iclass
185  */
186 static inline msg_t chMBPeekI(const mailbox_t *mbp) {
187 
189 
190  return *mbp->rdptr;
191 }
192 
193 /**
194  * @brief Terminates the reset state.
195  *
196  * @param[in] mbp the pointer to an initialized @p mailbox_t object
197  *
198  * @xclass
199  */
200 static inline void chMBResumeX(mailbox_t *mbp) {
201 
202  mbp->reset = false;
203 }
204 
205 #endif /* CH_CFG_USE_MAILBOXES == TRUE */
206 
207 #endif /* CHMBOXES_H */
208 
209 /** @} */
msg_t chMBPostI(mailbox_t *mbp, msg_t msg)
Posts a message into a mailbox.
Definition: chmboxes.c:243
size_t cnt
Messages in queue.
Definition: chmboxes.h:59
static size_t chMBGetUsedCountI(const mailbox_t *mbp)
Returns the number of used message slots into a mailbox.
Definition: chmboxes.h:152
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 chMBObjectInit(mailbox_t *mbp, msg_t *buf, size_t n)
Initializes a mailbox_t object.
Definition: chmboxes.c:87
msg_t chMBFetchI(mailbox_t *mbp, msg_t *msgp)
Retrieves a message from a mailbox.
Definition: chmboxes.c:493
void chMBReset(mailbox_t *mbp)
Resets a mailbox_t object.
Definition: chmboxes.c:113
msg_t * top
Pointer to the location after the buffer.
Definition: chmboxes.h:55
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
void chDbgCheckClassI(void)
I-class functions context check.
Definition: ch.c:239
msg_t chMBPostAheadI(mailbox_t *mbp, msg_t msg)
Posts an high priority message into a mailbox.
Definition: chmboxes.c:368
uint32_t sysinterval_t
Type of time interval.
Definition: ch.h:553
static size_t chMBGetFreeCountI(const mailbox_t *mbp)
Returns the number of free message slots into a mailbox.
Definition: chmboxes.h:167
msg_t chMBFetchTimeout(mailbox_t *mbp, msg_t *msgp, sysinterval_t timeout)
Retrieves a message from a mailbox.
Definition: chmboxes.c:415
msg_t * buffer
Pointer to the mailbox buffer.
Definition: chmboxes.h:53
static size_t chMBGetSizeI(const mailbox_t *mbp)
Returns the mailbox buffer size as number of messages.
Definition: chmboxes.h:136
void chMBResetI(mailbox_t *mbp)
Resets a mailbox_t object.
Definition: chmboxes.c:133
threads_queue_t qr
Queued readers.
Definition: chmboxes.h:62
msg_t * wrptr
Write pointer.
Definition: chmboxes.h:57
threads_queue_t qw
Queued writers.
Definition: chmboxes.h:61
static msg_t chMBPeekI(const mailbox_t *mbp)
Returns the next message in the queue without removing it.
Definition: chmboxes.h:186
Structure representing a queue of threads.
Definition: ch.h:579
bool reset
True in reset state.
Definition: chmboxes.h:60
static void chMBResumeX(mailbox_t *mbp)
Terminates the reset state.
Definition: chmboxes.h:200
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
msg_t * rdptr
Read pointer.
Definition: chmboxes.h:58
msg_t chMBFetchTimeoutS(mailbox_t *mbp, msg_t *msgp, sysinterval_t timeout)
Retrieves a message from a mailbox.
Definition: chmboxes.c:444