ChibiOS  21.6.0
chpipes.h
Go to the documentation of this file.
1 /*
2  ChibiOS - Copyright (C) 2006,2007,2008,2009,2010,2011,2012,2013,2014,
3  2015,2016,2017,2018,2019,2020,2021 Giovanni Di Sirio.
4 
5  This file is part of ChibiOS.
6 
7  ChibiOS is free software; you can redistribute it and/or modify
8  it under the terms of the GNU General Public License as published by
9  the Free Software Foundation version 3 of the License.
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 oslib/include/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 Bytes in the pipe. */
60  bool reset; /**< @brief True if in reset state. */
61  thread_reference_t wtr; /**< @brief Waiting writer. */
62  thread_reference_t rtr; /**< @brief Waiting reader. */
63 #if (CH_CFG_USE_MUTEXES == TRUE) || defined(__DOXYGEN__)
64  mutex_t cmtx; /**< @brief Common access mutex. */
65  mutex_t wmtx; /**< @brief Write access mutex. */
66  mutex_t rmtx; /**< @brief Read access mutex. */
67 #else
68  semaphore_t csem; /**< @brief Common access semaphore.*/
69  semaphore_t wsem; /**< @brief Write access semaphore. */
70  semaphore_t rsem; /**< @brief Read access semaphore. */
71 #endif
72 } pipe_t;
73 
74 /*===========================================================================*/
75 /* Module macros. */
76 /*===========================================================================*/
77 
78 /**
79  * @brief Data part of a static pipe initializer.
80  * @details This macro should be used when statically initializing a
81  * pipe that is part of a bigger structure.
82  *
83  * @param[in] name the name of the pipe variable
84  * @param[in] buffer pointer to the pipe buffer array of @p uint8_t
85  * @param[in] size number of @p uint8_t elements in the buffer array
86  */
87 #if (CH_CFG_USE_MUTEXES == TRUE) || defined(__DOXYGEN__)
88 #define __PIPE_DATA(name, buffer, size) { \
89  (uint8_t *)(buffer), \
90  (uint8_t *)(buffer) + size, \
91  (uint8_t *)(buffer), \
92  (uint8_t *)(buffer), \
93  (size_t)0, \
94  false, \
95  NULL, \
96  NULL, \
97  __MUTEX_DATA(name.cmtx), \
98  __MUTEX_DATA(name.wmtx), \
99  __MUTEX_DATA(name.rmtx), \
100 }
101 #else /* CH_CFG_USE_MUTEXES == FALSE */
102 #define __PIPE_DATA(name, buffer, size) { \
103  (uint8_t *)(buffer), \
104  (uint8_t *)(buffer) + size, \
105  (uint8_t *)(buffer), \
106  (uint8_t *)(buffer), \
107  (size_t)0, \
108  false, \
109  NULL, \
110  NULL, \
111  __SEMAPHORE_DATA(name.csem, (cnt_t)1), \
112  __SEMAPHORE_DATA(name.wsem, (cnt_t)1), \
113  __SEMAPHORE_DATA(name.rsem, (cnt_t)1), \
114 }
115 #endif /* CH_CFG_USE_MUTEXES == FALSE */
116 
117 /**
118  * @brief Static pipe initializer.
119  * @details Statically initialized pipes require no explicit
120  * initialization using @p chPipeObjectInit().
121  *
122  * @param[in] name the name of the pipe variable
123  * @param[in] buffer pointer to the pipe buffer array of @p uint8_t
124  * @param[in] size number of @p uint8_t elements in the buffer array
125  */
126 #define PIPE_DECL(name, buffer, size) \
127  pipe_t name = __PIPE_DATA(name, buffer, size)
128 
129 /*===========================================================================*/
130 /* External declarations. */
131 /*===========================================================================*/
132 
133 #ifdef __cplusplus
134 extern "C" {
135 #endif
136  void chPipeObjectInit(pipe_t *pp, uint8_t *buf, size_t n);
137  void chPipeReset(pipe_t *pp);
138  size_t chPipeWriteTimeout(pipe_t *pp, const uint8_t *bp,
139  size_t n, sysinterval_t timeout);
140  size_t chPipeReadTimeout(pipe_t *pp, uint8_t *bp,
141  size_t n, sysinterval_t timeout);
142 #ifdef __cplusplus
143 }
144 #endif
145 
146 /*===========================================================================*/
147 /* Module inline functions. */
148 /*===========================================================================*/
149 
150 /**
151  * @brief Returns the pipe buffer size as number of bytes.
152  *
153  * @param[in] pp the pointer to an initialized @p pipe_t object
154  * @return The size of the pipe.
155  *
156  * @api
157  */
158 static inline size_t chPipeGetSize(const pipe_t *pp) {
159 
160  /*lint -save -e9033 [10.8] Perfectly safe pointers
161  arithmetic.*/
162  return (size_t)(pp->top - pp->buffer);
163  /*lint -restore*/
164 }
165 
166 /**
167  * @brief Returns the number of used byte slots into a pipe.
168  *
169  * @param[in] pp the pointer to an initialized @p pipe_t object
170  * @return The number of queued bytes.
171  *
172  * @api
173  */
174 static inline size_t chPipeGetUsedCount(const pipe_t *pp) {
175 
176  return pp->cnt;
177 }
178 
179 /**
180  * @brief Returns the number of free byte slots into a pipe.
181  *
182  * @param[in] pp the pointer to an initialized @p pipe_t object
183  * @return The number of empty byte slots.
184  *
185  * @api
186  */
187 static inline size_t chPipeGetFreeCount(const pipe_t *pp) {
188 
189  return chPipeGetSize(pp) - chPipeGetUsedCount(pp);
190 }
191 
192 /**
193  * @brief Terminates the reset state.
194  *
195  * @param[in] pp the pointer to an initialized @p pipe_t object
196  *
197  * @api
198  */
199 static inline void chPipeResume(pipe_t *pp) {
200 
201  pp->reset = false;
202 }
203 
204 #endif /* CH_CFG_USE_PIPES == TRUE */
205 
206 #endif /* CHPIPES_H */
207 
208 /** @} */
pipe_t::wtr
thread_reference_t wtr
Waiting writer.
Definition: chpipes.h:61
pipe_t::cnt
size_t cnt
Bytes in the pipe.
Definition: chpipes.h:59
chPipeResume
static void chPipeResume(pipe_t *pp)
Terminates the reset state.
Definition: chpipes.h:199
pipe_t::wrptr
uint8_t * wrptr
Write pointer.
Definition: chpipes.h:57
pipe_t::cmtx
mutex_t cmtx
Common access mutex.
Definition: chpipes.h:64
chPipeGetSize
static size_t chPipeGetSize(const pipe_t *pp)
Returns the pipe buffer size as number of bytes.
Definition: chpipes.h:158
chPipeReset
void chPipeReset(pipe_t *pp)
Resets a pipe_t object.
Definition: chpipes.c:236
chPipeWriteTimeout
size_t chPipeWriteTimeout(pipe_t *pp, const uint8_t *bp, size_t n, sysinterval_t timeout)
Pipe write with timeout.
Definition: chpipes.c:278
ch_thread
Structure representing a thread.
Definition: chobjects.h:156
ch_semaphore
Semaphore structure.
Definition: rt/include/chsem.h:52
pipe_t::rmtx
mutex_t rmtx
Read access mutex.
Definition: chpipes.h:66
pipe_t
Structure representing a pipe object.
Definition: chpipes.h:52
ch_mutex
Mutex structure.
Definition: chmtx.h:57
sysinterval_t
uint64_t sysinterval_t
Type of time interval.
Definition: chtime.h:119
chPipeGetUsedCount
static size_t chPipeGetUsedCount(const pipe_t *pp)
Returns the number of used byte slots into a pipe.
Definition: chpipes.h:174
pipe_t::top
uint8_t * top
Pointer to the location after the buffer.
Definition: chpipes.h:55
pipe_t::reset
bool reset
True if in reset state.
Definition: chpipes.h:60
pipe_t::rdptr
uint8_t * rdptr
Read pointer.
Definition: chpipes.h:58
chPipeObjectInit
void chPipeObjectInit(pipe_t *pp, uint8_t *buf, size_t n)
Initializes a mailbox_t object.
Definition: chpipes.c:207
chPipeGetFreeCount
static size_t chPipeGetFreeCount(const pipe_t *pp)
Returns the number of free byte slots into a pipe.
Definition: chpipes.h:187
chPipeReadTimeout
size_t chPipeReadTimeout(pipe_t *pp, uint8_t *bp, size_t n, sysinterval_t timeout)
Pipe read with timeout.
Definition: chpipes.c:343
pipe_t::wmtx
mutex_t wmtx
Write access mutex.
Definition: chpipes.h:65
pipe_t::rtr
thread_reference_t rtr
Waiting reader.
Definition: chpipes.h:62
pipe_t::buffer
uint8_t * buffer
Pointer to the pipe buffer.
Definition: chpipes.h:53