ChibiOS/RT 7.0.6
chpipes.h
Go to the documentation of this file.
1/*
2 ChibiOS - Copyright (C) 2006-2026 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 version 3 of the License.
9
10 ChibiOS is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 GNU General Public License for more details.
14
15 You should have received a copy of the GNU General Public License
16 along with this program. If not, see <http://www.gnu.org/licenses/>.
17*/
18
19/**
20 * @file oslib/include/chpipes.h
21 * @brief Pipes macros and structures.
22 *
23 * @addtogroup oslib_pipes
24 * @{
25 */
26
27#ifndef CHPIPES_H
28#define CHPIPES_H
29
30#if (CH_CFG_USE_PIPES == TRUE) || defined(__DOXYGEN__)
31
32/*===========================================================================*/
33/* Module constants. */
34/*===========================================================================*/
35
36/*===========================================================================*/
37/* Module pre-compile time settings. */
38/*===========================================================================*/
39
40/*===========================================================================*/
41/* Derived constants and error checks. */
42/*===========================================================================*/
43
44/*===========================================================================*/
45/* Module data structures and types. */
46/*===========================================================================*/
47
48/**
49 * @brief Structure representing a pipe object.
50 */
51typedef struct {
52 uint8_t *buffer; /**< @brief Pointer to the pipe
53 buffer. */
54 uint8_t *top; /**< @brief Pointer to the location
55 after the buffer. */
56 uint8_t *wrptr; /**< @brief Write pointer. */
57 uint8_t *rdptr; /**< @brief Read pointer. */
58 size_t cnt; /**< @brief Bytes in the pipe. */
59 bool reset; /**< @brief True if in reset state. */
60 thread_reference_t wtr; /**< @brief Waiting writer. */
61 thread_reference_t rtr; /**< @brief Waiting reader. */
62#if (CH_CFG_USE_MUTEXES == TRUE) || defined(__DOXYGEN__)
63 mutex_t cmtx; /**< @brief Common access mutex. */
64 mutex_t wmtx; /**< @brief Write access mutex. */
65 mutex_t rmtx; /**< @brief Read access mutex. */
66#else
67 semaphore_t csem; /**< @brief Common access semaphore.*/
68 semaphore_t wsem; /**< @brief Write access semaphore. */
69 semaphore_t rsem; /**< @brief Read access semaphore. */
70#endif
71} pipe_t;
72
73/*===========================================================================*/
74/* Module macros. */
75/*===========================================================================*/
76
77/**
78 * @brief Data part of a static pipe initializer.
79 * @details This macro should be used when statically initializing a
80 * pipe that is part of a bigger structure.
81 *
82 * @param[in] name the name of the pipe variable
83 * @param[in] buffer pointer to the pipe buffer array of @p uint8_t
84 * @param[in] size number of @p uint8_t elements in the buffer array
85 */
86#if (CH_CFG_USE_MUTEXES == TRUE) || defined(__DOXYGEN__)
87#define __PIPE_DATA(name, buffer, size) { \
88 (uint8_t *)(buffer), \
89 (uint8_t *)(buffer) + size, \
90 (uint8_t *)(buffer), \
91 (uint8_t *)(buffer), \
92 (size_t)0, \
93 false, \
94 NULL, \
95 NULL, \
96 __MUTEX_DATA(name.cmtx), \
97 __MUTEX_DATA(name.wmtx), \
98 __MUTEX_DATA(name.rmtx), \
99}
100#else /* CH_CFG_USE_MUTEXES == FALSE */
101#define __PIPE_DATA(name, buffer, size) { \
102 (uint8_t *)(buffer), \
103 (uint8_t *)(buffer) + size, \
104 (uint8_t *)(buffer), \
105 (uint8_t *)(buffer), \
106 (size_t)0, \
107 false, \
108 NULL, \
109 NULL, \
110 __SEMAPHORE_DATA(name.csem, (cnt_t)1), \
111 __SEMAPHORE_DATA(name.wsem, (cnt_t)1), \
112 __SEMAPHORE_DATA(name.rsem, (cnt_t)1), \
113}
114#endif /* CH_CFG_USE_MUTEXES == FALSE */
115
116/**
117 * @brief Static pipe initializer.
118 * @details Statically initialized pipes require no explicit
119 * initialization using @p chPipeObjectInit().
120 *
121 * @param[in] name the name of the pipe variable
122 * @param[in] buffer pointer to the pipe buffer array of @p uint8_t
123 * @param[in] size number of @p uint8_t elements in the buffer array
124 */
125#define PIPE_DECL(name, buffer, size) \
126 pipe_t name = __PIPE_DATA(name, buffer, size)
127
128/*===========================================================================*/
129/* External declarations. */
130/*===========================================================================*/
131
132#ifdef __cplusplus
133extern "C" {
134#endif
135 void chPipeObjectInit(pipe_t *pp, uint8_t *buf, size_t n);
136 void chPipeReset(pipe_t *pp);
137 size_t chPipeWriteTimeout(pipe_t *pp, const uint8_t *bp,
138 size_t n, sysinterval_t timeout);
139 size_t chPipeReadTimeout(pipe_t *pp, uint8_t *bp,
140 size_t n, sysinterval_t timeout);
141#ifdef __cplusplus
142}
143#endif
144
145/*===========================================================================*/
146/* Module inline functions. */
147/*===========================================================================*/
148
149/**
150 * @brief Returns the pipe buffer size as number of bytes.
151 *
152 * @param[in] pp the pointer to an initialized @p pipe_t object
153 * @return The size of the pipe.
154 *
155 * @api
156 */
157static inline size_t chPipeGetSize(const pipe_t *pp) {
158
159 /*lint -save -e9033 [10.8] Perfectly safe pointers
160 arithmetic.*/
161 return (size_t)(pp->top - pp->buffer);
162 /*lint -restore*/
163}
164
165/**
166 * @brief Returns the number of used byte slots into a pipe.
167 *
168 * @param[in] pp the pointer to an initialized @p pipe_t object
169 * @return The number of queued bytes.
170 *
171 * @api
172 */
173static inline size_t chPipeGetUsedCount(const pipe_t *pp) {
174
175 return pp->cnt;
176}
177
178/**
179 * @brief Returns the number of free byte slots into a pipe.
180 *
181 * @param[in] pp the pointer to an initialized @p pipe_t object
182 * @return The number of empty byte slots.
183 *
184 * @api
185 */
186static inline size_t chPipeGetFreeCount(const pipe_t *pp) {
187
188 return chPipeGetSize(pp) - chPipeGetUsedCount(pp);
189}
190
191/**
192 * @brief Terminates the reset state.
193 *
194 * @param[in] pp the pointer to an initialized @p pipe_t object
195 *
196 * @api
197 */
198static inline void chPipeResume(pipe_t *pp) {
199
200 pp->reset = false;
201}
202
203#endif /* CH_CFG_USE_PIPES == TRUE */
204
205#endif /* CHPIPES_H */
206
207/** @} */
mutex_t
struct ch_mutex mutex_t
Type of a mutex structure.
Definition chmtx.h:51
thread_reference_t
thread_t * thread_reference_t
Type of a thread reference.
Definition chobjects.h:135
chPipeReadTimeout
size_t chPipeReadTimeout(pipe_t *pp, uint8_t *bp, size_t n, sysinterval_t timeout)
Pipe read with timeout.
Definition chpipes.c:342
chPipeGetUsedCount
static size_t chPipeGetUsedCount(const pipe_t *pp)
Returns the number of used byte slots into a pipe.
Definition chpipes.h:173
chPipeGetSize
static size_t chPipeGetSize(const pipe_t *pp)
Returns the pipe buffer size as number of bytes.
Definition chpipes.h:157
chPipeResume
static void chPipeResume(pipe_t *pp)
Terminates the reset state.
Definition chpipes.h:198
chPipeGetFreeCount
static size_t chPipeGetFreeCount(const pipe_t *pp)
Returns the number of free byte slots into a pipe.
Definition chpipes.h:186
chPipeWriteTimeout
size_t chPipeWriteTimeout(pipe_t *pp, const uint8_t *bp, size_t n, sysinterval_t timeout)
Pipe write with timeout.
Definition chpipes.c:277
chPipeObjectInit
void chPipeObjectInit(pipe_t *pp, uint8_t *buf, size_t n)
Initializes a mailbox_t object.
Definition chpipes.c:206
chPipeReset
void chPipeReset(pipe_t *pp)
Resets a pipe_t object.
Definition chpipes.c:235
semaphore_t
struct ch_semaphore semaphore_t
Semaphore structure.
sysinterval_t
uint64_t sysinterval_t
Type of time interval.
Definition chtime.h:118
pipe_t
Structure representing a pipe object.
Definition chpipes.h:51
pipe_t::rtr
thread_reference_t rtr
Waiting reader.
Definition chpipes.h:61
pipe_t::cmtx
mutex_t cmtx
Common access mutex.
Definition chpipes.h:63
pipe_t::wrptr
uint8_t * wrptr
Write pointer.
Definition chpipes.h:56
pipe_t::cnt
size_t cnt
Bytes in the pipe.
Definition chpipes.h:58
pipe_t::rmtx
mutex_t rmtx
Read access mutex.
Definition chpipes.h:65
pipe_t::top
uint8_t * top
Pointer to the location after the buffer.
Definition chpipes.h:54
pipe_t::wmtx
mutex_t wmtx
Write access mutex.
Definition chpipes.h:64
pipe_t::buffer
uint8_t * buffer
Pointer to the pipe buffer.
Definition chpipes.h:52
pipe_t::reset
bool reset
True if in reset state.
Definition chpipes.h:59
pipe_t::wtr
thread_reference_t wtr
Waiting writer.
Definition chpipes.h:60
pipe_t::rdptr
uint8_t * rdptr
Read pointer.
Definition chpipes.h:57