hal_channels.h 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315
  1. /*
  2. ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio
  3. Licensed under the Apache License, Version 2.0 (the "License");
  4. you may not use this file except in compliance with the License.
  5. You may obtain a copy of the License at
  6. http://www.apache.org/licenses/LICENSE-2.0
  7. Unless required by applicable law or agreed to in writing, software
  8. distributed under the License is distributed on an "AS IS" BASIS,
  9. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  10. See the License for the specific language governing permissions and
  11. limitations under the License.
  12. */
  13. /**
  14. * @file hal_channels.h
  15. * @brief I/O channels access.
  16. * @details This header defines an abstract interface useful to access generic
  17. * I/O serial devices in a standardized way.
  18. *
  19. * @addtogroup IO_CHANNEL
  20. * @details This module defines an abstract interface for I/O channels by
  21. * extending the @p BaseSequentialStream interface.<br>
  22. * Note that no code is present, I/O channels are just abstract
  23. * interface like structures, you should look at the systems as
  24. * to a set of abstract C++ classes (even if written in C).
  25. * Specific device drivers can use/extend the interface and
  26. * implement them.<br>
  27. * This system has the advantage to make the access to channels
  28. * independent from the implementation logic.
  29. * @{
  30. */
  31. #ifndef HAL_CHANNELS_H
  32. #define HAL_CHANNELS_H
  33. /**
  34. * @name Default control operation codes.
  35. * @{
  36. */
  37. #define CHN_CTL_INVALID 0 /** @brief Invalid operation code. */
  38. #define CHN_CTL_NOP 1 /** @brief Does nothing. */
  39. #define CHN_CTL_TX_WAIT 2 /** @brief Wait for TX completion. */
  40. /** @} */
  41. /**
  42. * @brief @p BaseChannel specific methods.
  43. */
  44. #define _base_channel_methods \
  45. _base_sequential_stream_methods \
  46. /* Channel put method with timeout specification.*/ \
  47. msg_t (*putt)(void *instance, uint8_t b, sysinterval_t time); \
  48. /* Channel get method with timeout specification.*/ \
  49. msg_t (*gett)(void *instance, sysinterval_t time); \
  50. /* Channel write method with timeout specification.*/ \
  51. size_t (*writet)(void *instance, const uint8_t *bp, \
  52. size_t n, sysinterval_t time); \
  53. /* Channel read method with timeout specification.*/ \
  54. size_t (*readt)(void *instance, uint8_t *bp, size_t n, \
  55. sysinterval_t time); \
  56. /* Channel control method.*/ \
  57. msg_t (*ctl)(void *instance, unsigned int operation, void *arg);
  58. /**
  59. * @brief @p BaseChannel specific data.
  60. * @note It is empty because @p BaseChannel is only an interface without
  61. * implementation.
  62. */
  63. #define _base_channel_data \
  64. _base_sequential_stream_data
  65. /**
  66. * @extends BaseSequentialStreamVMT
  67. *
  68. * @brief @p BaseChannel virtual methods table.
  69. */
  70. struct BaseChannelVMT {
  71. _base_channel_methods
  72. };
  73. /**
  74. * @extends BaseSequentialStream
  75. *
  76. * @brief Base channel class.
  77. * @details This class represents a generic, byte-wide, I/O channel. This class
  78. * introduces generic I/O primitives with timeout specification.
  79. */
  80. typedef struct {
  81. /** @brief Virtual Methods Table.*/
  82. const struct BaseChannelVMT *vmt;
  83. _base_channel_data
  84. } BaseChannel;
  85. /**
  86. * @name Macro Functions (BaseChannel)
  87. * @{
  88. */
  89. /**
  90. * @brief Channel blocking byte write with timeout.
  91. * @details This function writes a byte value to a channel. If the channel
  92. * is not ready to accept data then the calling thread is suspended.
  93. *
  94. * @param[in] ip pointer to a @p BaseChannel or derived class
  95. * @param[in] b the byte value to be written to the channel
  96. * @param[in] time the number of ticks before the operation timeouts,
  97. * the following special values are allowed:
  98. * - @a TIME_IMMEDIATE immediate timeout.
  99. * - @a TIME_INFINITE no timeout.
  100. * .
  101. * @return The operation status.
  102. * @retval STM_OK if the operation succeeded.
  103. * @retval STM_TIMEOUT if the specified time expired.
  104. * @retval STM_RESET if the channel associated queue (if any) was reset.
  105. *
  106. * @api
  107. */
  108. #define chnPutTimeout(ip, b, time) ((ip)->vmt->putt(ip, b, time))
  109. /**
  110. * @brief Channel blocking byte read with timeout.
  111. * @details This function reads a byte value from a channel. If the data
  112. * is not available then the calling thread is suspended.
  113. *
  114. * @param[in] ip pointer to a @p BaseChannel or derived class
  115. * @param[in] time the number of ticks before the operation timeouts,
  116. * the following special values are allowed:
  117. * - @a TIME_IMMEDIATE immediate timeout.
  118. * - @a TIME_INFINITE no timeout.
  119. * .
  120. * @return A byte value from the queue.
  121. * @retval STM_TIMEOUT if the specified time expired.
  122. * @retval STM_RESET if the channel associated queue (if any) has been
  123. * reset.
  124. *
  125. * @api
  126. */
  127. #define chnGetTimeout(ip, time) ((ip)->vmt->gett(ip, time))
  128. /**
  129. * @brief Channel blocking write.
  130. * @details The function writes data from a buffer to a channel. If the channel
  131. * is not ready to accept data then the calling thread is suspended.
  132. *
  133. * @param[in] ip pointer to a @p BaseChannel or derived class
  134. * @param[out] bp pointer to the data buffer
  135. * @param[in] n the maximum amount of data to be transferred
  136. *
  137. * @return The number of bytes transferred.
  138. *
  139. * @api
  140. */
  141. #define chnWrite(ip, bp, n) streamWrite(ip, bp, n)
  142. /**
  143. * @brief Channel blocking write with timeout.
  144. * @details The function writes data from a buffer to a channel. If the channel
  145. * is not ready to accept data then the calling thread is suspended.
  146. *
  147. * @param[in] ip pointer to a @p BaseChannel or derived class
  148. * @param[out] bp pointer to the data buffer
  149. * @param[in] n the maximum amount of data to be transferred
  150. * @param[in] time the number of ticks before the operation timeouts,
  151. * the following special values are allowed:
  152. * - @a TIME_IMMEDIATE immediate timeout.
  153. * - @a TIME_INFINITE no timeout.
  154. * .
  155. * @return The number of bytes transferred.
  156. *
  157. * @api
  158. */
  159. #define chnWriteTimeout(ip, bp, n, time) ((ip)->vmt->writet(ip, bp, n, time))
  160. /**
  161. * @brief Channel blocking read.
  162. * @details The function reads data from a channel into a buffer. If the data
  163. * is not available then the calling thread is suspended.
  164. *
  165. * @param[in] ip pointer to a @p BaseChannel or derived class
  166. * @param[in] bp pointer to the data buffer
  167. * @param[in] n the maximum amount of data to be transferred
  168. *
  169. * @return The number of bytes transferred.
  170. *
  171. * @api
  172. */
  173. #define chnRead(ip, bp, n) streamRead(ip, bp, n)
  174. /**
  175. * @brief Channel blocking read with timeout.
  176. * @details The function reads data from a channel into a buffer. If the data
  177. * is not available then the calling thread is suspended.
  178. *
  179. * @param[in] ip pointer to a @p BaseChannel or derived class
  180. * @param[in] bp pointer to the data buffer
  181. * @param[in] n the maximum amount of data to be transferred
  182. * @param[in] time the number of ticks before the operation timeouts,
  183. * the following special values are allowed:
  184. * - @a TIME_IMMEDIATE immediate timeout.
  185. * - @a TIME_INFINITE no timeout.
  186. * .
  187. * @return The number of bytes transferred.
  188. *
  189. * @api
  190. */
  191. #define chnReadTimeout(ip, bp, n, time) ((ip)->vmt->readt(ip, bp, n, time))
  192. /**
  193. * @brief Control operation on a channel.
  194. *
  195. * @param[in] ip pointer to a @p BaseChannel or derived class
  196. * @param[in] operation control operation code
  197. * @param[in,out] arg operation argument
  198. *
  199. * @return The control operation status.
  200. * @retval MSG_OK in case of success.
  201. * @retval MSG_TIMEOUT in case of operation timeout.
  202. * @retval MSG_RESET in case of operation reset.
  203. *
  204. * @api
  205. */
  206. #define chnControl(ip, operation, arg) ((ip)->vmt->ctl(ip, operation, arg))
  207. /** @} */
  208. /**
  209. * @name I/O status flags added to the event listener
  210. * @{
  211. */
  212. /** @brief No pending conditions.*/
  213. #define CHN_NO_ERROR (eventflags_t)0
  214. /** @brief Connection happened.*/
  215. #define CHN_CONNECTED (eventflags_t)1
  216. /** @brief Disconnection happened.*/
  217. #define CHN_DISCONNECTED (eventflags_t)2
  218. /** @brief Data available in the input queue.*/
  219. #define CHN_INPUT_AVAILABLE (eventflags_t)4
  220. /** @brief Output queue empty.*/
  221. #define CHN_OUTPUT_EMPTY (eventflags_t)8
  222. /** @brief Transmission end.*/
  223. #define CHN_TRANSMISSION_END (eventflags_t)16
  224. /** @} */
  225. /**
  226. * @brief @p BaseAsynchronousChannel specific methods.
  227. */
  228. #define _base_asynchronous_channel_methods \
  229. _base_channel_methods \
  230. /**
  231. * @brief @p BaseAsynchronousChannel specific data.
  232. */
  233. #define _base_asynchronous_channel_data \
  234. _base_channel_data \
  235. /* I/O condition event source.*/ \
  236. event_source_t event;
  237. /**
  238. * @extends BaseChannelVMT
  239. *
  240. * @brief @p BaseAsynchronousChannel virtual methods table.
  241. */
  242. struct BaseAsynchronousChannelVMT {
  243. _base_asynchronous_channel_methods
  244. };
  245. /**
  246. * @extends BaseChannel
  247. *
  248. * @brief Base asynchronous channel class.
  249. * @details This class extends @p BaseChannel by adding event sources fields
  250. * for asynchronous I/O for use in an event-driven environment.
  251. */
  252. typedef struct {
  253. /** @brief Virtual Methods Table.*/
  254. const struct BaseAsynchronousChannelVMT *vmt;
  255. _base_asynchronous_channel_data
  256. } BaseAsynchronousChannel;
  257. /**
  258. * @name Macro Functions (BaseAsynchronousChannel)
  259. * @{
  260. */
  261. /**
  262. * @brief Returns the I/O condition event source.
  263. * @details The event source is broadcasted when an I/O condition happens.
  264. *
  265. * @param[in] ip pointer to a @p BaseAsynchronousChannel or derived
  266. * class
  267. * @return A pointer to an @p EventSource object.
  268. *
  269. * @api
  270. */
  271. #define chnGetEventSource(ip) (&((ip)->event))
  272. /**
  273. * @brief Adds status flags to the listeners's flags mask.
  274. * @details This function is usually called from the I/O ISRs in order to
  275. * notify I/O conditions such as data events, errors, signal
  276. * changes etc.
  277. *
  278. * @param[in] ip pointer to a @p BaseAsynchronousChannel or derived
  279. * class
  280. * @param[in] flags condition flags to be added to the listener flags mask
  281. *
  282. * @iclass
  283. */
  284. #define chnAddFlagsI(ip, flags) { \
  285. osalEventBroadcastFlagsI(&(ip)->event, flags); \
  286. }
  287. /** @} */
  288. #endif /* HAL_CHANNELS_H */
  289. /** @} */