ChibiOS 21.11.4
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 */
52typedef 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
134extern "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 */
158static 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 */
174static 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 */
187static 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 */
199static 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/** @} */
mutex_t
struct ch_mutex mutex_t
Type of a mutex structure.
Definition chmtx.h:52
thread_reference_t
thread_t * thread_reference_t
Type of a thread reference.
Definition chobjects.h:138
chPipeReadTimeout
size_t chPipeReadTimeout(pipe_t *pp, uint8_t *bp, size_t n, sysinterval_t timeout)
Pipe read with timeout.
Definition chpipes.c:343
chPipeGetUsedCount
static size_t chPipeGetUsedCount(const pipe_t *pp)
Returns the number of used byte slots into a pipe.
Definition chpipes.h:174
chPipeGetSize
static size_t chPipeGetSize(const pipe_t *pp)
Returns the pipe buffer size as number of bytes.
Definition chpipes.h:158
chPipeResume
static void chPipeResume(pipe_t *pp)
Terminates the reset state.
Definition chpipes.h:199
chPipeGetFreeCount
static size_t chPipeGetFreeCount(const pipe_t *pp)
Returns the number of free byte slots into a pipe.
Definition chpipes.h:187
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
chPipeObjectInit
void chPipeObjectInit(pipe_t *pp, uint8_t *buf, size_t n)
Initializes a mailbox_t object.
Definition chpipes.c:207
chPipeReset
void chPipeReset(pipe_t *pp)
Resets a pipe_t object.
Definition chpipes.c:236
semaphore_t
struct ch_semaphore semaphore_t
Semaphore structure.
sysinterval_t
uint64_t sysinterval_t
Type of time interval.
Definition chtime.h:119
pipe_t
Structure representing a pipe object.
Definition chpipes.h:52
pipe_t::rtr
thread_reference_t rtr
Waiting reader.
Definition chpipes.h:62
pipe_t::cmtx
mutex_t cmtx
Common access mutex.
Definition chpipes.h:64
pipe_t::wrptr
uint8_t * wrptr
Write pointer.
Definition chpipes.h:57
pipe_t::cnt
size_t cnt
Bytes in the pipe.
Definition chpipes.h:59
pipe_t::rmtx
mutex_t rmtx
Read access mutex.
Definition chpipes.h:66
pipe_t::top
uint8_t * top
Pointer to the location after the buffer.
Definition chpipes.h:55
pipe_t::wmtx
mutex_t wmtx
Write access mutex.
Definition chpipes.h:65
pipe_t::buffer
uint8_t * buffer
Pointer to the pipe buffer.
Definition chpipes.h:53
pipe_t::reset
bool reset
True if in reset state.
Definition chpipes.h:60
pipe_t::wtr
thread_reference_t wtr
Waiting writer.
Definition chpipes.h:61
pipe_t::rdptr
uint8_t * rdptr
Read pointer.
Definition chpipes.h:58