ChibiOS  0.0.0
chpipes.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 chpipes.h
22  * @brief Pipes macros and structures.
23  *
24  * @addtogroup oslib_pipes
25  * @{
26  */
27 
28 #ifndef CHPIPES_H
29 #define CHPIPES_H
30 
31 #if (CH_CFG_USE_PIPES == 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 pipe object.
51  */
52 typedef struct {
53  uint8_t *buffer; /**< @brief Pointer to the pipe
54  buffer. */
55  uint8_t *top; /**< @brief Pointer to the location
56  after the buffer. */
57  uint8_t *wrptr; /**< @brief Write pointer. */
58  uint8_t *rdptr; /**< @brief Read pointer. */
59  size_t cnt; /**< @brief Messages in queue. */
60  bool reset; /**< @brief True if in reset state. */
61  threads_queue_t qw; /**< @brief Queued writers. */
62  threads_queue_t qr; /**< @brief Queued readers. */
63 #if (CH_CFG_USE_MUTEXES == TRUE) || defined(__DOXYGEN__)
64  mutex_t mtx; /**< @brief Heap access mutex. */
65 #else
66  semaphore_t sem; /**< @brief Heap access semaphore. */
67 #endif
68 } pipe_t;
69 
70 /*===========================================================================*/
71 /* Module macros. */
72 /*===========================================================================*/
73 
74 /**
75  * @brief Data part of a static pipe initializer.
76  * @details This macro should be used when statically initializing a
77  * pipe that is part of a bigger structure.
78  *
79  * @param[in] name the name of the pipe variable
80  * @param[in] buffer pointer to the pipe buffer array of @p uint8_t
81  * @param[in] size number of @p uint8_t elements in the buffer array
82  */
83 #if (CH_CFG_USE_MUTEXES == TRUE) || defined(__DOXYGEN__)
84 #define _PIPE_DATA(name, buffer, size) { \
85  (uint8_t *)(buffer), \
86  (uint8_t *)(buffer) + size, \
87  (uint8_t *)(buffer), \
88  (uint8_t *)(buffer), \
89  (size_t)0, \
90  false, \
91  _THREADS_QUEUE_DATA(name.qw), \
92  _THREADS_QUEUE_DATA(name.qr), \
93  _MUTEX_DATA(name.mtx), \
94 }
95 #else /* CH_CFG_USE_MUTEXES == FALSE */
96 #define _PIPE_DATA(name, buffer, size) { \
97  (uint8_t *)(buffer), \
98  (uint8_t *)(buffer) + size, \
99  (uint8_t *)(buffer), \
100  (uint8_t *)(buffer), \
101  (size_t)0, \
102  false, \
103  _THREADS_QUEUE_DATA(name.qw), \
104  _THREADS_QUEUE_DATA(name.qr), \
105  _SEMAPHORE_DATA(name.sem, (cnt_t)1), \
106 }
107 #endif /* CH_CFG_USE_MUTEXES == FALSE */
108 
109 /**
110  * @brief Static pipe initializer.
111  * @details Statically initialized pipes require no explicit
112  * initialization using @p chPipeObjectInit().
113  *
114  * @param[in] name the name of the pipe variable
115  * @param[in] buffer pointer to the pipe buffer array of @p uint8_t
116  * @param[in] size number of @p uint8_t elements in the buffer array
117  */
118 #define PIPE_DECL(name, buffer, size) \
119  pipe_t name = _PIPE_DATA(name, buffer, size)
120 
121 /*===========================================================================*/
122 /* External declarations. */
123 /*===========================================================================*/
124 
125 #ifdef __cplusplus
126 extern "C" {
127 #endif
128  void chPipeObjectInit(pipe_t *pp, uint8_t *buf, size_t n);
129  void chPipeReset(pipe_t *pp);
130  size_t chPipeWriteTimeout(pipe_t *pp, const uint8_t *bp,
131  size_t n, sysinterval_t timeout);
132  size_t chPipeReadTimeout(pipe_t *pp, uint8_t *bp,
133  size_t n, sysinterval_t timeout);
134 #ifdef __cplusplus
135 }
136 #endif
137 
138 /*===========================================================================*/
139 /* Module inline functions. */
140 /*===========================================================================*/
141 
142 /**
143  * @brief Returns the pipe buffer size as number of bytes.
144  *
145  * @param[in] pp the pointer to an initialized @p pipe_t object
146  * @return The size of the pipe.
147  *
148  * @iclass
149  */
150 static inline size_t chPipeGetSizeI(const pipe_t *pp) {
151 
152  /*lint -save -e9033 [10.8] Perfectly safe pointers
153  arithmetic.*/
154  return (size_t)(pp->top - pp->buffer);
155  /*lint -restore*/
156 }
157 
158 /**
159  * @brief Returns the number of used byte slots into a pipe.
160  *
161  * @param[in] pp the pointer to an initialized @p pipe_t object
162  * @return The number of queued bytes.
163  *
164  * @iclass
165  */
166 static inline size_t chPipeGetUsedCountI(const pipe_t *pp) {
167 
168  chDbgCheckClassI();
169 
170  return pp->cnt;
171 }
172 
173 /**
174  * @brief Returns the number of free byte slots into a pipe.
175  *
176  * @param[in] pp the pointer to an initialized @p pipe_t object
177  * @return The number of empty byte slots.
178  *
179  * @iclass
180  */
181 static inline size_t chPipeGetFreeCountI(const pipe_t *pp) {
182 
183  chDbgCheckClassI();
184 
185  return chPipeGetSizeI(pp) - chPipeGetUsedCountI(pp);
186 }
187 
188 /**
189  * @brief Returns the next byte in the queue without removing it.
190  * @pre A byte must be present in the queue for this function to work
191  * or it would return garbage. The correct way to use this macro is
192  * to use @p chPipeGetFullCountI() and then use this macro, all within
193  * a lock state.
194  *
195  * @param[in] pp the pointer to an initialized @p pipe_t object
196  * @return The next byte in queue.
197  *
198  * @iclass
199  */
200 static inline uint8_t chPipePeekI(const pipe_t *pp) {
201 
202  chDbgCheckClassI();
203 
204  return *pp->rdptr;
205 }
206 
207 /**
208  * @brief Terminates the reset state.
209  *
210  * @param[in] pp the pointer to an initialized @p pipe_t object
211  *
212  * @xclass
213  */
214 static inline void chPipeResumeX(pipe_t *pp) {
215 
216  pp->reset = false;
217 }
218 
219 #endif /* CH_CFG_USE_PIPES == TRUE */
220 
221 #endif /* CHPIPES_H */
222 
223 /** @} */
pipe_t::qw
threads_queue_t qw
Queued writers.
Definition: chpipes.h:61
pipe_t::reset
bool reset
True if in reset state.
Definition: chpipes.h:60
chPipeResumeX
static void chPipeResumeX(pipe_t *pp)
Terminates the reset state.
Definition: chpipes.h:214
sysinterval_t
uint64_t sysinterval_t
Type of time interval.
Definition: chtime.h:119
pipe_t::rdptr
uint8_t * rdptr
Read pointer.
Definition: chpipes.h:58
chPipeGetFreeCountI
static size_t chPipeGetFreeCountI(const pipe_t *pp)
Returns the number of free byte slots into a pipe.
Definition: chpipes.h:181
chPipeReadTimeout
size_t chPipeReadTimeout(pipe_t *pp, uint8_t *bp, size_t n, sysinterval_t timeout)
Pipe read with timeout.
Definition: chpipes.c:181
pipe_t::top
uint8_t * top
Pointer to the location after the buffer.
Definition: chpipes.h:55
pipe_t::cnt
size_t cnt
Messages in queue.
Definition: chpipes.h:59
pipe_t
Structure representing a pipe object.
Definition: chpipes.h:52
chPipePeekI
static uint8_t chPipePeekI(const pipe_t *pp)
Returns the next byte in the queue without removing it.
Definition: chpipes.h:200
ch_mutex
Mutex structure.
Definition: chmtx.h:57
threads_queue_t
Type of a thread queue.
Definition: osal.h:232
chPipeWriteTimeout
size_t chPipeWriteTimeout(pipe_t *pp, const uint8_t *bp, size_t n, sysinterval_t timeout)
Pipe write with timeout.
Definition: chpipes.c:154
pipe_t::mtx
mutex_t mtx
Heap access mutex.
Definition: chpipes.h:64
pipe_t::buffer
uint8_t * buffer
Pointer to the pipe buffer.
Definition: chpipes.h:53
ch_semaphore
Semaphore structure.
Definition: chsem.h:52
pipe_t::wrptr
uint8_t * wrptr
Write pointer.
Definition: chpipes.h:57
chPipeReset
void chPipeReset(pipe_t *pp)
Resets a pipe_t object.
Definition: chpipes.c:115
chPipeGetSizeI
static size_t chPipeGetSizeI(const pipe_t *pp)
Returns the pipe buffer size as number of bytes.
Definition: chpipes.h:150
pipe_t::qr
threads_queue_t qr
Queued readers.
Definition: chpipes.h:62
chPipeObjectInit
void chPipeObjectInit(pipe_t *pp, uint8_t *buf, size_t n)
Initializes a mailbox_t object.
Definition: chpipes.c:89
chPipeGetUsedCountI
static size_t chPipeGetUsedCountI(const pipe_t *pp)
Returns the number of used byte slots into a pipe.
Definition: chpipes.h:166