ChibiOS/HAL  6.1.0
hal_serial_usb.h
Go to the documentation of this file.
1 /*
2  ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio
3 
4  Licensed under the Apache License, Version 2.0 (the "License");
5  you may not use this file except in compliance with the License.
6  You may obtain a copy of the License at
7 
8  http://www.apache.org/licenses/LICENSE-2.0
9 
10  Unless required by applicable law or agreed to in writing, software
11  distributed under the License is distributed on an "AS IS" BASIS,
12  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  See the License for the specific language governing permissions and
14  limitations under the License.
15 */
16 
17 /**
18  * @file hal_serial_usb.h
19  * @brief Serial over USB Driver macros and structures.
20  *
21  * @addtogroup SERIAL_USB
22  * @{
23  */
24 
25 #ifndef HAL_SERIAL_USB_H
26 #define HAL_SERIAL_USB_H
27 
28 #if (HAL_USE_SERIAL_USB == TRUE) || defined(__DOXYGEN__)
29 
30 #include "hal_usb_cdc.h"
31 
32 /*===========================================================================*/
33 /* Driver constants. */
34 /*===========================================================================*/
35 
36 /*===========================================================================*/
37 /* Driver pre-compile time settings. */
38 /*===========================================================================*/
39 
40 /**
41  * @name SERIAL_USB configuration options
42  * @{
43  */
44 /**
45  * @brief Serial over USB buffers size.
46  * @details Configuration parameter, the buffer size must be a multiple of
47  * the USB data endpoint maximum packet size.
48  * @note The default is 256 bytes for both the transmission and receive
49  * buffers.
50  */
51 #if !defined(SERIAL_USB_BUFFERS_SIZE) || defined(__DOXYGEN__)
52 #define SERIAL_USB_BUFFERS_SIZE 256
53 #endif
54 
55 /**
56  * @brief Serial over USB number of buffers.
57  * @note The default is 2 buffers.
58  */
59 #if !defined(SERIAL_USB_BUFFERS_NUMBER) || defined(__DOXYGEN__)
60 #define SERIAL_USB_BUFFERS_NUMBER 2
61 #endif
62 /** @} */
63 
64 /*===========================================================================*/
65 /* Derived constants and error checks. */
66 /*===========================================================================*/
67 
68 #if HAL_USE_USB == FALSE
69 #error "Serial over USB Driver requires HAL_USE_USB"
70 #endif
71 
72 /*===========================================================================*/
73 /* Driver data structures and types. */
74 /*===========================================================================*/
75 
76 /**
77  * @brief Driver state machine possible states.
78  */
79 typedef enum {
80  SDU_UNINIT = 0, /**< Not initialized. */
81  SDU_STOP = 1, /**< Stopped. */
82  SDU_READY = 2 /**< Ready. */
83 } sdustate_t;
84 
85 /**
86  * @brief Structure representing a serial over USB driver.
87  */
89 
90 /**
91  * @brief Serial over USB Driver configuration structure.
92  * @details An instance of this structure must be passed to @p sduStart()
93  * in order to configure and start the driver operations.
94  */
95 typedef struct {
96  /**
97  * @brief USB driver to use.
98  */
100  /**
101  * @brief Bulk IN endpoint used for outgoing data transfer.
102  */
104  /**
105  * @brief Bulk OUT endpoint used for incoming data transfer.
106  */
108  /**
109  * @brief Interrupt IN endpoint used for notifications.
110  * @note If set to zero then the INT endpoint is assumed to be not
111  * present, USB descriptors must be changed accordingly.
112  */
115 
116 /**
117  * @brief @p SerialDriver specific data.
118  */
119 #define _serial_usb_driver_data \
120  _base_asynchronous_channel_data \
121  /* Driver state.*/ \
122  sdustate_t state; \
123  /* Input buffers queue.*/ \
124  input_buffers_queue_t ibqueue; \
125  /* Output queue.*/ \
126  output_buffers_queue_t obqueue; \
127  /* Input buffer.*/ \
128  uint8_t ib[BQ_BUFFER_SIZE(SERIAL_USB_BUFFERS_NUMBER, \
129  SERIAL_USB_BUFFERS_SIZE)]; \
130  /* Output buffer.*/ \
131  uint8_t ob[BQ_BUFFER_SIZE(SERIAL_USB_BUFFERS_NUMBER, \
132  SERIAL_USB_BUFFERS_SIZE)]; \
133  /* End of the mandatory fields.*/ \
134  /* Current configuration data.*/ \
135  const SerialUSBConfig *config;
136 
137 /**
138  * @brief @p SerialUSBDriver specific methods.
139  */
140 #define _serial_usb_driver_methods \
141  _base_asynchronous_channel_methods
142 
143 /**
144  * @extends BaseAsynchronousChannelVMT
145  *
146  * @brief @p SerialDriver virtual methods table.
147  */
150 };
151 
152 /**
153  * @extends BaseAsynchronousChannel
154  *
155  * @brief Full duplex serial driver class.
156  * @details This class extends @p BaseAsynchronousChannel by adding physical
157  * I/O queues.
158  */
160  /** @brief Virtual Methods Table.*/
161  const struct SerialUSBDriverVMT *vmt;
163 };
164 
165 /*===========================================================================*/
166 /* Driver macros. */
167 /*===========================================================================*/
168 
169 /*===========================================================================*/
170 /* External declarations. */
171 /*===========================================================================*/
172 
173 #ifdef __cplusplus
174 extern "C" {
175 #endif
176  void sduInit(void);
177  void sduObjectInit(SerialUSBDriver *sdup);
178  void sduStart(SerialUSBDriver *sdup, const SerialUSBConfig *config);
179  void sduStop(SerialUSBDriver *sdup);
180  void sduSuspendHookI(SerialUSBDriver *sdup);
181  void sduWakeupHookI(SerialUSBDriver *sdup);
183  bool sduRequestsHook(USBDriver *usbp);
184  void sduSOFHookI(SerialUSBDriver *sdup);
185  void sduDataTransmitted(USBDriver *usbp, usbep_t ep);
186  void sduDataReceived(USBDriver *usbp, usbep_t ep);
187  void sduInterruptTransmitted(USBDriver *usbp, usbep_t ep);
188  msg_t sduControl(USBDriver *usbp, unsigned int operation, void *arg);
189 #ifdef __cplusplus
190 }
191 #endif
192 
193 #endif /* HAL_USE_SERIAL_USB == TRUE */
194 
195 #endif /* HAL_SERIAL_USB_H */
196 
197 /** @} */
#define _serial_usb_driver_data
SerialDriver specific data.
USBDriver * usbp
USB driver to use.
void sduWakeupHookI(SerialUSBDriver *sdup)
USB device wakeup handler.
void sduStop(SerialUSBDriver *sdup)
Stops the driver.
void sduConfigureHookI(SerialUSBDriver *sdup)
USB device configured handler.
void sduInterruptTransmitted(USBDriver *usbp, usbep_t ep)
Default data received callback.
void sduInit(void)
Serial Driver initialization.
bool sduRequestsHook(USBDriver *usbp)
Default requests hook.
void sduDataTransmitted(USBDriver *usbp, usbep_t ep)
Default data transmitted callback.
const struct SerialUSBDriverVMT * vmt
Virtual Methods Table.
Structure representing an USB driver.
Definition: hal_usb_lld.h:217
usbep_t bulk_out
Bulk OUT endpoint used for incoming data transfer.
void sduStart(SerialUSBDriver *sdup, const SerialUSBConfig *config)
Configures and starts the driver.
int32_t msg_t
Type of a message.
Definition: osal.h:160
sdustate_t
Driver state machine possible states.
void sduSOFHookI(SerialUSBDriver *sdup)
SOF handler.
void sduDataReceived(USBDriver *usbp, usbep_t ep)
Default data received callback.
void sduObjectInit(SerialUSBDriver *sdup)
Initializes a generic full duplex driver object.
usbep_t bulk_in
Bulk IN endpoint used for outgoing data transfer.
usbep_t int_in
Interrupt IN endpoint used for notifications.
#define _serial_usb_driver_methods
SerialUSBDriver specific methods.
void sduSuspendHookI(SerialUSBDriver *sdup)
USB device suspend handler.
Full duplex serial driver class.
SerialDriver virtual methods table.
uint8_t usbep_t
Type of an endpoint identifier.
Definition: hal_usb.h:264
msg_t sduControl(USBDriver *usbp, unsigned int operation, void *arg)
Control operation on a serial USB port.
USB CDC macros and structures.
Serial over USB Driver configuration structure.