1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
|
/*
ChibiOS/RT - Copyright (C) 2006-2007 Giovanni Di Sirio.
This file is part of ChibiOS/RT.
ChibiOS/RT is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 3 of the License, or
(at your option) any later version.
ChibiOS/RT is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
/**
* @file channels.h
* @brief I/O channels
* @addtogroup Channels
* @{
*/
#ifndef _CHANNELS_H_
#define _CHANNELS_H_
/**
* @brief Base channels methods.
*/
struct _base_channel_methods {
/**
* @brief Channel put method with timeout specification.
* @see chIOPut()
*/
msg_t (*put)(void *instance, uint8_t b, systime_t timeout);
/**
* @brief Channel get method with timeout specification.
* @see chIOGet()
*/
msg_t (*get)(void *instance, systime_t timeout);
};
/**
* @brief Base channels data.
* @note It is empty because @p BaseChannel is only an interface without
* implementation.
*/
struct _base_channel_data {
};
/**
* @brief Virtual methods table for base channels.
*/
struct _base_channel_vmt {
struct _base_channel_methods m0; /**< Class methods. */
};
/**
* @brief Base channel class.
* @details This class represents a generic, byte-wide, I/O channel.
*/
typedef struct {
struct _base_channel_vmt *vmt; /**< Virtual Methods Table. */
struct _base_channel_data d0; /**< Class data. */
} BaseChannel;
/**
* @brief Channel blocking byte write.
* @details This function writes a byte value to a channel. If the channel
* is not ready to accept data then the calling thread is suspended.
*
* @param[in] ip pointer to a @p BaseChannel or derived class
* @param[in] b the byte value to be written to the channel
* @return The operation status:
* @retval Q_OK if the operation succeeded.
* @retval Q_RESET if the channel associated queue (if any) was reset.
*/
#define chIOPut(ip, b) ((ip)->vmt->m0.put(ip, b, TIME_INFINITE))
/**
* @brief Channel blocking byte write with timeout.
* @details This function writes a byte value to a channel. If the channel
* is not ready to accept data then the calling thread is suspended.
*
* @param[in] ip pointer to a @p BaseChannel or derived class
* @param[in] b the byte value to be written to the channel
* @param[in] timeout the number of ticks before the operation timeouts,
* the following special values are allowed:
* - @a TIME_IMMEDIATE immediate timeout.
* - @a TIME_INFINITE no timeout.
* .
* @return The operation status:
* @retval Q_OK if the operation succeeded.
* @retval Q_TIMEOUT if the specified time expired.
* @retval Q_RESET if the channel associated queue (if any) was reset.
*/
#define chIOPutTimeout(ip, b, timeout) ((ip)->vmt->m0.put(ip, b, timeout))
/**
* @brief Channel blocking byte read.
* @details This function reads a byte value from a channel. If the data
* is not available then the calling thread is suspended.
*
* @param[in] ip pointer to a @p BaseChannel or derived class
* @return A byte value from the queue or:
* @retval Q_RESET if the channel associated queue (if any) was reset.
*/
#define chIOGet(ip) ((ip)->vmt->m0.put(ip, TIME_INFINITE))
/**
* @brief Channel blocking byte read with timeout.
* @details This function reads a byte value from a channel. If the data
* is not available then the calling thread is suspended.
*
* @param[in] ip pointer to a @p BaseChannel or derived class
* @param[in] timeout the number of ticks before the operation timeouts,
* the following special values are allowed:
* - @a TIME_IMMEDIATE immediate timeout.
* - @a TIME_INFINITE no timeout.
* .
* @return A byte value from the queue or:
* @retval Q_TIMEOUT if the specified time expired.
* @retval Q_RESET if the channel associated queue (if any) was reset.
*/
#define chIOGetTimeout(ip, timeout) ((ip)->vmt->m0.put(ip, timeout))
#if CH_USE_EVENTS
/**
* @brief Virtual methods table for base asynchronous channels.
*/
struct _base_asynchronous_channel_methods {
/**
* Channel asynchronous write method.
* @see chIOWrite()
*/
size_t (*write)(void *instance, uint8_t *buffer, size_t n);
/**
* Channel asynchronous read method.
* @see chIORead()
*/
size_t (*read)(void *instance, uint8_t *buffer, size_t n);
};
/**
* @brief Base asynchronous channels data.
*/
struct _base_asynchronous_channel_data {
/**
* Data Available @p EventSource. This event is generated when some incoming
* data is inserted in the input queue.
*/
EventSource ievent;
/**
* Data Transmitted @p EventSource. This event is generated when the
* output queue is empty.
*/
EventSource oevent;
};
/**
* @brief Virtual methods table for base asynchronous channels.
*/
struct _base_asynchronous_channel_vmt {
struct _base_channel_methods m0; /**< Super class methods. */
struct _base_asynchronous_channel_methods m1; /**< Class methods. */
};
/**
* @extends BaseChannel
*
* @brief Base asynchronous channel class.
* @details This class extends @p BaseChannel by adding methods for
* asynchronous I/O in an event-driven environment.
*/
typedef struct {
struct _base_asynchronous_channel_vmt *vmt; /**< Virtual Methods Table. */
struct _base_channel_data d0; /**< Super class data. */
struct _base_asynchronous_channel_data d1; /**< Class data. */
} BaseAsynchronousChannel;
/**
* @brief Channel non-blocking write.
* @details The function writes data from a buffer to a channel. The
* transfer is non-blocking and can return zero if the channel is
* not read to accept data.
*
* @param[in] ip pointer to a @p BaseAsynchronousChannel or derived class
* @param[out] bp pointer to the buffer where the data is stored
* @param[in] n the maximum amount of data to be transferred
* @return The number of bytes transferred.
*/
#define chIOWrite(ip, bp, n) ((ip)->vmt->m1.write(ip, bp, n))
/**
* @brief Channel non-blocking read.
* @details The function reads data from a channel into a buffer. The
* transfer is non-blocking and can return zero if the channel has
* no data immediately available.
*
* @param[in] ip pointer to a @p BaseChannel or derived class
* @param[out] bp pointer to the buffer where the input data is copied
* @param[in] n the maximum amount of data to be transferred
* @return The number of bytes transferred.
*/
#define chIORead(ip, bp, n) ((ip)->vmt->m1.read(ip, bp, n))
#endif /* CH_USE_EVENTS */
#endif /* _CHANNELS_H_ */
/** @} */
|
