2 * @brief Host mode driver for the library USB CDC Class driver
\r
5 * Copyright(C) NXP Semiconductors, 2012
\r
6 * Copyright(C) Dean Camera, 2011, 2012
\r
7 * All rights reserved.
\r
10 * Software that is described herein is for illustrative purposes only
\r
11 * which provides customers with programming information regarding the
\r
12 * LPC products. This software is supplied "AS IS" without any warranties of
\r
13 * any kind, and NXP Semiconductors and its licensor disclaim any and
\r
14 * all warranties, express or implied, including all implied warranties of
\r
15 * merchantability, fitness for a particular purpose and non-infringement of
\r
16 * intellectual property rights. NXP Semiconductors assumes no responsibility
\r
17 * or liability for the use of the software, conveys no license or rights under any
\r
18 * patent, copyright, mask work right, or any other intellectual property rights in
\r
19 * or to any products. NXP Semiconductors reserves the right to make changes
\r
20 * in the software without notification. NXP Semiconductors also makes no
\r
21 * representation or warranty that such application will be suitable for the
\r
22 * specified use without further testing or modification.
\r
25 * Permission to use, copy, modify, and distribute this software and its
\r
26 * documentation is hereby granted, under NXP Semiconductors' and its
\r
27 * licensor's relevant copyrights in the software, without fee, provided that it
\r
28 * is used in conjunction with NXP Semiconductors microcontrollers. This
\r
29 * copyright, permission, and disclaimer notice must appear in all copies of
\r
33 /** @ingroup Group_USBClassCDC
\r
34 * @defgroup Group_USBClassCDCHost CDC Class Host Mode Driver
\r
36 * @section Sec_Dependencies Module Source Dependencies
\r
37 * The following files must be built with any user project that uses this module:
\r
38 * - LPCUSBlib/Drivers/USB/Class/Host/CDC.c <i>(Makefile source module name: LPCUSBlib_SRC_USBCLASS)</i>
\r
40 * @section Sec_ModDescription Module Description
\r
41 * Host Mode USB Class driver framework interface, for the CDC USB Class driver.
\r
46 #ifndef __CDC_CLASS_HOST_H__
\r
47 #define __CDC_CLASS_HOST_H__
\r
50 #include "../../USB.h"
\r
51 #include "../Common/CDCClassCommon.h"
\r
55 /* Enable C linkage for C++ Compilers: */
\r
56 #if defined(__cplusplus)
\r
60 /* Preprocessor Checks: */
\r
61 #if !defined(__INCLUDE_FROM_CDC_DRIVER)
\r
62 #error Do not include this file directly. Include LPCUSBlib/Drivers/USB.h instead.
\r
65 /* Public Interface - May be used in end-application: */
\r
67 /** @brief CDC Class Host Mode Configuration and State Structure.
\r
69 * Class state structure. An instance of this structure should be made within the user application,
\r
70 * and passed to each of the CDC class driver functions as the \c CDCInterfaceInfo parameter. This
\r
71 * stores each CDC interface's configuration and state information.
\r
77 uint8_t DataINPipeNumber; /**< Pipe number of the CDC interface's IN data pipe. */
\r
78 bool DataINPipeDoubleBank; /**< Indicates if the CDC interface's IN data pipe should use double banking. */
\r
80 uint8_t DataOUTPipeNumber; /**< Pipe number of the CDC interface's OUT data pipe. */
\r
81 bool DataOUTPipeDoubleBank; /**< Indicates if the CDC interface's OUT data pipe should use double banking. */
\r
83 uint8_t NotificationPipeNumber; /**< Pipe number of the CDC interface's IN notification endpoint, if used. */
\r
84 bool NotificationPipeDoubleBank; /**< Indicates if the CDC interface's notification pipe should use double banking. */
\r
86 uint8_t PortNumber; /**< Port number that this interface is running.
\r
88 } Config; /**< Config data for the USB class interface within the device. All elements in this section
\r
89 * <b>must</b> be set or the interface will fail to enumerate and operate correctly.
\r
93 bool IsActive; /**< Indicates if the current interface instance is connected to an attached device, valid
\r
94 * after @ref CDC_Host_ConfigurePipes() is called and the Host state machine is in the
\r
97 uint8_t ControlInterfaceNumber; /**< Interface index of the CDC-ACM control interface within the attached device. */
\r
99 uint16_t DataINPipeSize; /**< Size in bytes of the CDC interface's IN data pipe. */
\r
100 uint16_t DataOUTPipeSize; /**< Size in bytes of the CDC interface's OUT data pipe. */
\r
101 uint16_t NotificationPipeSize; /**< Size in bytes of the CDC interface's IN notification pipe, if used. */
\r
105 uint8_t HostToDevice; /**< Control line states from the host to device, as a set of \c CDC_CONTROL_LINE_OUT_*
\r
106 * masks - to notify the device of changes to these values, call the
\r
107 * @ref CDC_Host_SendControlLineStateChange() function.
\r
109 uint8_t DeviceToHost; /**< Control line states from the device to host, as a set of \c CDC_CONTROL_LINE_IN_*
\r
110 * masks. This value is updated each time @ref CDC_Host_USBTask() is called.
\r
112 } ControlLineStates; /**< Current states of the virtual serial port's control lines between the device and host. */
\r
114 CDC_LineEncoding_t LineEncoding; /**< Line encoding used in the virtual serial port, for the device's information.
\r
115 * This is generally only used if the virtual serial port data is to be
\r
116 * reconstructed on a physical UART. When set by the host application, the
\r
117 * @ref CDC_Host_SetLineEncoding() function must be called to push the changes
\r
120 } State; /**< State data for the USB class interface within the device. All elements in this section
\r
121 * <b>may</b> be set to initial values, but may also be ignored to default to sane values when
\r
122 * the interface is enumerated.
\r
124 } USB_ClassInfo_CDC_Host_t;
\r
127 /** Enum for the possible error codes returned by the @ref CDC_Host_ConfigurePipes() function. */
\r
128 enum CDC_Host_EnumerationFailure_ErrorCodes_t
\r
130 CDC_ENUMERROR_NoError = 0, /**< Configuration Descriptor was processed successfully. */
\r
131 CDC_ENUMERROR_InvalidConfigDescriptor = 1, /**< The device returned an invalid Configuration Descriptor. */
\r
132 CDC_ENUMERROR_NoCompatibleInterfaceFound = 2, /**< A compatible CDC interface was not found in the device's Configuration Descriptor. */
\r
133 CDC_ENUMERROR_PipeConfigurationFailed = 3, /**< One or more pipes for the specified interface could not be configured correctly. */
\r
136 /* Function Prototypes: */
\r
137 /** @brief General management task for a given CDC host class interface, required for the correct operation of the interface. This should
\r
138 * be called frequently in the main program loop, before the master USB management task @ref USB_USBTask().
\r
140 * @param CDCInterfaceInfo : Pointer to a structure containing an CDC Class host configuration and state.
\r
143 void CDC_Host_USBTask(USB_ClassInfo_CDC_Host_t* const CDCInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);
\r
145 /** @brief Host interface configuration routine, to configure a given CDC host interface instance using the Configuration
\r
146 * Descriptor read from an attached USB device. This function automatically updates the given CDC Host instance's
\r
147 * state values and configures the pipes required to communicate with the interface if it is found within the device.
\r
148 * This should be called once after the stack has enumerated the attached device, while the host state machine is in
\r
149 * the Addressed state.
\r
151 * @param CDCInterfaceInfo : Pointer to a structure containing an CDC Class host configuration and state.
\r
152 * @param ConfigDescriptorSize : Length of the attached device's Configuration Descriptor.
\r
153 * @param DeviceConfigDescriptor : Pointer to a buffer containing the attached device's Configuration Descriptor.
\r
155 * @return A value from the @ref CDC_Host_EnumerationFailure_ErrorCodes_t enum.
\r
157 uint8_t CDC_Host_ConfigurePipes(USB_ClassInfo_CDC_Host_t* const CDCInterfaceInfo,
\r
158 uint16_t ConfigDescriptorSize,
\r
159 void* DeviceConfigDescriptor) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(3);
\r
161 /** @brief Sets the line encoding for the attached device's virtual serial port. This should be called when the \c LineEncoding
\r
162 * values of the interface have been changed to push the new settings to the USB device.
\r
164 * @param CDCInterfaceInfo : Pointer to a structure containing a CDC Class host configuration and state.
\r
166 * @return A value from the @ref USB_Host_SendControlErrorCodes_t enum.
\r
168 uint8_t CDC_Host_SetLineEncoding(USB_ClassInfo_CDC_Host_t* const CDCInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);
\r
170 /** @brief Sends a Serial Control Line State Change notification to the device. This should be called when the virtual serial
\r
171 * control lines (DTR, RTS, etc.) have changed states. Line states persist until they are cleared via a second
\r
172 * notification. This should be called each time the CDC class driver's \c ControlLineStates.HostToDevice value is updated
\r
173 * to push the new states to the USB device.
\r
175 * @param CDCInterfaceInfo : Pointer to a structure containing a CDC Class host configuration and state.
\r
177 * @return A value from the @ref USB_Host_SendControlErrorCodes_t enum.
\r
179 uint8_t CDC_Host_SendControlLineStateChange(USB_ClassInfo_CDC_Host_t* const CDCInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);
\r
181 /** @brief Sends a Send Break request to the device. This is generally used to separate data or to indicate a special condition
\r
182 * to the receiving device.
\r
184 * @param CDCInterfaceInfo : Pointer to a structure containing a CDC Class host configuration and state.
\r
185 * @param Duration : Duration of the break, in milliseconds.
\r
187 * @return A value from the @ref USB_Host_SendControlErrorCodes_t enum.
\r
189 uint8_t CDC_Host_SendBreak(USB_ClassInfo_CDC_Host_t* const CDCInterfaceInfo,
\r
190 const uint8_t Duration) ATTR_NON_NULL_PTR_ARG(1);
\r
192 /** @brief Sends a given data buffer to the attached USB device, if connected. If a device is not connected when the function is
\r
193 * called, the data will be discarded. Bytes will be queued for transmission to the device until either the pipe bank
\r
194 * becomes full, or the @ref CDC_Host_Flush() function is called to flush the pending data to the device. This allows for
\r
195 * multiple bytes to be packed into a single pipe packet, increasing data throughput.
\r
197 * @pre This function must only be called when the Host state machine is in the @ref HOST_STATE_Configured state or the
\r
200 * @param CDCInterfaceInfo : Pointer to a structure containing a CDC Class host configuration and state.
\r
201 * @param Buffer : Pointer to a buffer containing the data to send to the device.
\r
202 * @param Length : Length of the data to send to the device.
\r
204 * @return A value from the @ref Pipe_Stream_RW_ErrorCodes_t enum.
\r
206 uint8_t CDC_Host_SendData(USB_ClassInfo_CDC_Host_t* const CDCInterfaceInfo,
\r
207 const uint8_t* const Buffer,
\r
208 const uint16_t Length);
\r
210 /** @brief Sends a given null-terminated string to the attached USB device, if connected. If a device is not connected when the
\r
211 * function is called, the string is discarded. Bytes will be queued for transmission to the device until either the pipe
\r
212 * bank becomes full, or the @ref CDC_Host_Flush() function is called to flush the pending data to the device. This allows
\r
213 * for multiple bytes to be packed into a single pipe packet, increasing data throughput.
\r
215 * @pre This function must only be called when the Host state machine is in the @ref HOST_STATE_Configured state or the
\r
218 * @param CDCInterfaceInfo : Pointer to a structure containing a CDC Class host configuration and state.
\r
219 * @param String : Pointer to the null terminated string to send to the device.
\r
221 * @return A value from the @ref Pipe_Stream_RW_ErrorCodes_t enum.
\r
223 uint8_t CDC_Host_SendString(USB_ClassInfo_CDC_Host_t* const CDCInterfaceInfo,
\r
224 const char* const String) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2);
\r
226 /** @brief Sends a given byte to the attached USB device, if connected. If a device is not connected when the function is called, the
\r
227 * byte is discarded. Bytes will be queued for transmission to the device until either the pipe bank becomes full, or the
\r
228 * @ref CDC_Host_Flush() function is called to flush the pending data to the host. This allows for multiple bytes to be
\r
229 * packed into a single pipe packet, increasing data throughput.
\r
231 * @pre This function must only be called when the Host state machine is in the @ref HOST_STATE_Configured state or the
\r
234 * @param CDCInterfaceInfo : Pointer to a structure containing a CDC Class host configuration and state.
\r
235 * @param Data : Byte of data to send to the device.
\r
237 * @return A value from the @ref Pipe_WaitUntilReady_ErrorCodes_t enum.
\r
239 uint8_t CDC_Host_SendByte(USB_ClassInfo_CDC_Host_t* const CDCInterfaceInfo,
\r
240 const uint8_t Data) ATTR_NON_NULL_PTR_ARG(1);
\r
242 /** @brief Determines the number of bytes received by the CDC interface from the device, waiting to be read. This indicates the number
\r
243 * of bytes in the IN pipe bank only, and thus the number of calls to @ref CDC_Host_ReceiveByte() which are guaranteed to succeed
\r
244 * immediately. If multiple bytes are to be received, they should be buffered by the user application, as the pipe bank will not be
\r
245 * released back to the USB controller until all bytes are read.
\r
247 * @pre This function must only be called when the Host state machine is in the @ref HOST_STATE_Configured state or the
\r
250 * @param CDCInterfaceInfo : Pointer to a structure containing a CDC Class host configuration and state.
\r
252 * @return Total number of buffered bytes received from the device.
\r
254 uint16_t CDC_Host_BytesReceived(USB_ClassInfo_CDC_Host_t* const CDCInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);
\r
256 /** @brief Reads a byte of data from the device. If no data is waiting to be read of if a USB device is not connected, the function
\r
257 * returns a negative value. The @ref CDC_Host_BytesReceived() function may be queried in advance to determine how many bytes
\r
258 * are currently buffered in the CDC interface's data receive pipe.
\r
260 * @pre This function must only be called when the Host state machine is in the @ref HOST_STATE_Configured state or the
\r
263 * @param CDCInterfaceInfo : Pointer to a structure containing a CDC Class host configuration and state.
\r
265 * @return Next received byte from the device, or a negative value if no data received.
\r
267 int16_t CDC_Host_ReceiveByte(USB_ClassInfo_CDC_Host_t* const CDCInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);
\r
269 /** @brief Flushes any data waiting to be sent, ensuring that the send buffer is cleared.
\r
271 * @pre This function must only be called when the Host state machine is in the @ref HOST_STATE_Configured state or the
\r
274 * @param CDCInterfaceInfo : Pointer to a structure containing a CDC Class host configuration and state.
\r
276 * @return A value from the @ref Pipe_WaitUntilReady_ErrorCodes_t enum.
\r
278 uint8_t CDC_Host_Flush(USB_ClassInfo_CDC_Host_t* const CDCInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);
\r
280 #if (!defined(__IAR_SYSTEMS_ICC__) || (_DLIB_FILE_DESCRIPTOR == 1))
\r
281 /** @brief Creates a standard character stream for the given CDC Device instance so that it can be used with all the regular
\r
282 * functions in the standard \c <stdio.h> library that accept a \c FILE stream as a destination (e.g. \c fprintf). The created
\r
283 * stream is bidirectional and can be used for both input and output functions.
\r
285 * Reading data from this stream is non-blocking, i.e. in most instances, complete strings cannot be read in by a single
\r
286 * fetch, as the endpoint will not be ready at some point in the transmission, aborting the transfer. However, this may
\r
287 * be used when the read data is processed byte-per-bye (via \c getc()) or when the user application will implement its own
\r
290 * @note The created stream can be given as stdout if desired to direct the standard output from all \c <stdio.h> functions
\r
291 * to the given CDC interface.
\r
294 * @note This function is not available on all microcontroller architectures.
\r
296 * @param CDCInterfaceInfo : Pointer to a structure containing a CDC Class configuration and state.
\r
297 * @param Stream : Pointer to a FILE structure where the created stream should be placed.
\r
300 void CDC_Host_CreateStream(USB_ClassInfo_CDC_Host_t* const CDCInterfaceInfo,
\r
301 FILE* const Stream);
\r
303 /** @brief Identical to @ref CDC_Host_CreateStream(), except that reads are blocking until the calling stream function terminates
\r
304 * the transfer. While blocking, the USB and CDC service tasks are called repeatedly to maintain USB communications.
\r
306 * @note This function is not available on all microcontroller architectures.
\r
308 * @param CDCInterfaceInfo : Pointer to a structure containing a CDC Class configuration and state.
\r
309 * @param Stream : Pointer to a FILE structure where the created stream should be placed.
\r
312 void CDC_Host_CreateBlockingStream(USB_ClassInfo_CDC_Host_t* const CDCInterfaceInfo,
\r
313 FILE* const Stream);
\r
314 #endif /* IAR DLAB checking */
\r
316 /** @brief CDC class driver event for a control line state change on a CDC host interface. This event fires each time the device notifies
\r
317 * the host of a control line state change (containing the virtual serial control line states, such as DCD) and may be hooked in the
\r
318 * user program by declaring a handler function with the same name and parameters listed here. The new control line states
\r
319 * are available in the ControlLineStates.DeviceToHost value inside the CDC host interface structure passed as a parameter, set as
\r
320 * a mask of \c CDC_CONTROL_LINE_IN_* masks.
\r
322 * @param CDCInterfaceInfo : Pointer to a structure containing a CDC Class host configuration and state.
\r
325 void EVENT_CDC_Host_ControLineStateChanged(USB_ClassInfo_CDC_Host_t* const CDCInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);
\r
327 /* Private Interface - For use in library only: */
\r
328 #if !defined(__DOXYGEN__)
\r
329 /* Function Prototypes: */
\r
330 #if defined(__INCLUDE_FROM_CDC_HOST_C)
\r
331 #if defined(FDEV_SETUP_STREAM)
\r
332 static int CDC_Host_putchar(char c,
\r
333 FILE* Stream) ATTR_NON_NULL_PTR_ARG(2);
\r
334 static int CDC_Host_getchar(FILE* Stream) ATTR_NON_NULL_PTR_ARG(1);
\r
335 static int CDC_Host_getchar_Blocking(FILE* Stream) ATTR_NON_NULL_PTR_ARG(1);
\r
338 void CDC_Host_Event_Stub(void) ATTR_CONST;
\r
340 void EVENT_CDC_Host_ControLineStateChanged(USB_ClassInfo_CDC_Host_t* const CDCInterfaceInfo)
\r
341 ATTR_WEAK ATTR_NON_NULL_PTR_ARG(1) ATTR_ALIAS(CDC_Host_Event_Stub);
\r
343 static uint8_t DCOMP_CDC_Host_NextCDCControlInterface(void* const CurrentDescriptor)
\r
344 ATTR_WARN_UNUSED_RESULT ATTR_NON_NULL_PTR_ARG(1);
\r
345 static uint8_t DCOMP_CDC_Host_NextCDCDataInterface(void* const CurrentDescriptor)
\r
346 ATTR_WARN_UNUSED_RESULT ATTR_NON_NULL_PTR_ARG(1);
\r
347 static uint8_t DCOMP_CDC_Host_NextCDCInterfaceEndpoint(void* const CurrentDescriptor)
\r
348 ATTR_WARN_UNUSED_RESULT ATTR_NON_NULL_PTR_ARG(1);
\r
352 /* Disable C linkage for C++ Compilers: */
\r
353 #if defined(__cplusplus)
\r
projects / freertos / blob