X-Git-Url: http://git.linex4red.de/pub/USBasp.git/blobdiff_plain/6b5e684c77e5fa855b609d01e9a07fec296e9257..5517f96e86b9447780a3e27bb455697f9fc65eea:/LUFA/Drivers/USB/Class/Host/CDC.h?ds=inline diff --git a/LUFA/Drivers/USB/Class/Host/CDC.h b/LUFA/Drivers/USB/Class/Host/CDC.h index 1c69a3126..8a4b576ca 100644 --- a/LUFA/Drivers/USB/Class/Host/CDC.h +++ b/LUFA/Drivers/USB/Class/Host/CDC.h @@ -1,7 +1,7 @@ /* LUFA Library Copyright (C) Dean Camera, 2010. - + dean [at] fourwalledcubicle [dot] com www.fourwalledcubicle.com */ @@ -9,13 +9,13 @@ /* Copyright 2010 Dean Camera (dean [at] fourwalledcubicle [dot] com) - Permission to use, copy, modify, distribute, and sell this + Permission to use, copy, modify, distribute, and sell this software and its documentation for any purpose is hereby granted - without fee, provided that the above copyright notice appear in + without fee, provided that the above copyright notice appear in all copies and that both that the copyright notice and this - permission notice and warranty disclaimer appear in supporting - documentation, and that the name of the author not be used in - advertising or publicity pertaining to distribution of the + permission notice and warranty disclaimer appear in supporting + documentation, and that the name of the author not be used in + advertising or publicity pertaining to distribution of the software without specific, written prior permission. The author disclaim all warranties with regard to this @@ -59,7 +59,7 @@ #include #include - + /* Enable C linkage for C++ Compilers: */ #if defined(__cplusplus) extern "C" { @@ -88,7 +88,7 @@ uint8_t DataOUTPipeNumber; /**< Pipe number of the CDC interface's OUT data pipe. */ bool DataOUTPipeDoubleBank; /**< Indicates if the CDC interface's OUT data pipe should use double banking. */ - uint8_t NotificationPipeNumber; /**< Pipe number of the CDC interface's IN notification endpoint, if used. */ + uint8_t NotificationPipeNumber; /**< Pipe number of the CDC interface's IN notification endpoint, if used. */ bool NotificationPipeDoubleBank; /**< Indicates if the CDC interface's notification pipe should use double banking. */ } Config; /**< Config data for the USB class interface within the device. All elements in this section * must be set or the interface will fail to enumerate and operate correctly. @@ -100,11 +100,11 @@ * Configured state. */ uint8_t ControlInterfaceNumber; /**< Interface index of the CDC-ACM control interface within the attached device. */ - + uint16_t DataINPipeSize; /**< Size in bytes of the CDC interface's IN data pipe. */ uint16_t DataOUTPipeSize; /**< Size in bytes of the CDC interface's OUT data pipe. */ uint16_t NotificationPipeSize; /**< Size in bytes of the CDC interface's IN notification pipe, if used. */ - + struct { uint8_t HostToDevice; /**< Control line states from the host to device, as a set of CDC_CONTROL_LINE_OUT_* @@ -115,7 +115,7 @@ * masks. This value is updated each time \ref CDC_Host_USBTask() is called. */ } ControlLineStates; /**< Current states of the virtual serial port's control lines between the device and host. */ - + struct { uint32_t BaudRateBPS; /**< Baud rate of the virtual serial port, in bits per second. */ @@ -136,17 +136,16 @@ * the interface is enumerated. */ } USB_ClassInfo_CDC_Host_t; - + /* Enums: */ /** Enum for the possible error codes returned by the \ref CDC_Host_ConfigurePipes() function. */ - enum CDCHost_EnumerationFailure_ErrorCodes_t + enum CDC_Host_EnumerationFailure_ErrorCodes_t { CDC_ENUMERROR_NoError = 0, /**< Configuration Descriptor was processed successfully. */ CDC_ENUMERROR_InvalidConfigDescriptor = 1, /**< The device returned an invalid Configuration Descriptor. */ - CDC_ENUMERROR_NoCDCInterfaceFound = 2, /**< A compatible CDC interface was not found in the device's Configuration Descriptor. */ - CDC_ENUMERROR_EndpointsNotFound = 3, /**< Compatible CDC endpoints were not found in the device's CDC interface. */ + CDC_ENUMERROR_NoCompatibleInterfaceFound = 2, /**< A compatible CDC interface was not found in the device's Configuration Descriptor. */ }; - + /* Function Prototypes: */ /** General management task for a given CDC host class interface, required for the correct operation of the interface. This should * be called frequently in the main program loop, before the master USB management task \ref USB_USBTask(). @@ -154,22 +153,27 @@ * \param[in,out] CDCInterfaceInfo Pointer to a structure containing an CDC Class host configuration and state. */ void CDC_Host_USBTask(USB_ClassInfo_CDC_Host_t* const CDCInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1); - + /** Host interface configuration routine, to configure a given CDC host interface instance using the Configuration * Descriptor read from an attached USB device. This function automatically updates the given CDC Host instance's * state values and configures the pipes required to communicate with the interface if it is found within the device. * This should be called once after the stack has enumerated the attached device, while the host state machine is in * the Addressed state. * + * \note The pipe index numbers as given in the interface's configuration structure must not overlap with any other + * interface, or pipe bank corruption will occur. Gaps in the allocated pipe numbers or non-sequential indexes + * within a single interface is allowed, but no two interfaces of any type have have interleaved pipe indexes. + * * \param[in,out] CDCInterfaceInfo Pointer to a structure containing an CDC Class host configuration and state. * \param[in] ConfigDescriptorSize Length of the attached device's Configuration Descriptor. * \param[in] DeviceConfigDescriptor Pointer to a buffer containing the attached device's Configuration Descriptor. * - * \return A value from the \ref CDCHost_EnumerationFailure_ErrorCodes_t enum. + * \return A value from the \ref CDC_Host_EnumerationFailure_ErrorCodes_t enum. */ - uint8_t CDC_Host_ConfigurePipes(USB_ClassInfo_CDC_Host_t* const CDCInterfaceInfo, uint16_t ConfigDescriptorSize, + uint8_t CDC_Host_ConfigurePipes(USB_ClassInfo_CDC_Host_t* const CDCInterfaceInfo, + uint16_t ConfigDescriptorSize, void* DeviceConfigDescriptor) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(3); - + /** Sets the line encoding for the attached device's virtual serial port. This should be called when the LineEncoding * values of the interface have been changed to push the new settings to the USB device. * @@ -189,7 +193,7 @@ * \return A value from the \ref USB_Host_SendControlErrorCodes_t enum. */ uint8_t CDC_Host_SendControlLineStateChange(USB_ClassInfo_CDC_Host_t* const CDCInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1); - + /** Sends a Send Break request to the device. This is generally used to separate data data or to indicate a special condition * to the receiving device. * @@ -198,14 +202,15 @@ * * \return A value from the \ref USB_Host_SendControlErrorCodes_t enum. */ - uint8_t CDC_Host_SendBreak(USB_ClassInfo_CDC_Host_t* const CDCInterfaceInfo, const uint8_t Duration) ATTR_NON_NULL_PTR_ARG(1); - + uint8_t CDC_Host_SendBreak(USB_ClassInfo_CDC_Host_t* const CDCInterfaceInfo, + const uint8_t Duration) ATTR_NON_NULL_PTR_ARG(1); + /** Sends a given string to the attached USB device, if connected. If a device is not connected when the function is called, the * string is discarded. Bytes will be queued for transmission to the device until either the pipe bank becomes full, or the - * \ref CDC_Host_Flush() function is called to flush the pending data to the host. This allows for multiple bytes to be + * \ref CDC_Host_Flush() function is called to flush the pending data to the host. This allows for multiple bytes to be * packed into a single pipe packet, increasing data throughput. * - * \pre This function must only be called when the Host state machine is in the HOST_STATE_Configured state or the + * \pre This function must only be called when the Host state machine is in the \ref HOST_STATE_Configured state or the * call will fail. * * \param[in,out] CDCInterfaceInfo Pointer to a structure containing a CDC Class host configuration and state. @@ -214,15 +219,16 @@ * * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum. */ - uint8_t CDC_Host_SendString(USB_ClassInfo_CDC_Host_t* const CDCInterfaceInfo, char* Data, const uint16_t Length) - ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2); - + uint8_t CDC_Host_SendString(USB_ClassInfo_CDC_Host_t* const CDCInterfaceInfo, + const char* const Data, + const uint16_t Length) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2); + /** Sends a given byte to the attached USB device, if connected. If a device is not connected when the function is called, the * byte is discarded. Bytes will be queued for transmission to the device until either the pipe bank becomes full, or the - * \ref CDC_Host_Flush() function is called to flush the pending data to the host. This allows for multiple bytes to be + * \ref CDC_Host_Flush() function is called to flush the pending data to the host. This allows for multiple bytes to be * packed into a single pipe packet, increasing data throughput. * - * \pre This function must only be called when the Host state machine is in the HOST_STATE_Configured state or the + * \pre This function must only be called when the Host state machine is in the \ref HOST_STATE_Configured state or the * call will fail. * * \param[in,out] CDCInterfaceInfo Pointer to a structure containing a CDC Class host configuration and state. @@ -230,11 +236,15 @@ * * \return A value from the \ref Pipe_WaitUntilReady_ErrorCodes_t enum. */ - uint8_t CDC_Host_SendByte(USB_ClassInfo_CDC_Host_t* const CDCInterfaceInfo, const uint8_t Data) ATTR_NON_NULL_PTR_ARG(1); + uint8_t CDC_Host_SendByte(USB_ClassInfo_CDC_Host_t* const CDCInterfaceInfo, + const uint8_t Data) ATTR_NON_NULL_PTR_ARG(1); - /** Determines the number of bytes received by the CDC interface from the device, waiting to be read. + /** Determines the number of bytes received by the CDC interface from the device, waiting to be read. This indicates the number + * of bytes in the IN pipe bank only, and thus the number of calls to \ref CDC_Host_ReceiveByte() which are guaranteed to succeed + * immediately. If multiple bytes are to be received, they should be buffered by the user application, as the pipe bank will not be + * released back to the USB controller until all bytes are read. * - * \pre This function must only be called when the Host state machine is in the HOST_STATE_Configured state or the + * \pre This function must only be called when the Host state machine is in the \ref HOST_STATE_Configured state or the * call will fail. * * \param[in,out] CDCInterfaceInfo Pointer to a structure containing a CDC Class host configuration and state. @@ -244,21 +254,21 @@ uint16_t CDC_Host_BytesReceived(USB_ClassInfo_CDC_Host_t* const CDCInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1); /** 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 - * returns 0. The \ref CDC_Host_BytesReceived() function should be queried before data is received to ensure that no data - * underflow occurs. + * returns a negative value. The \ref CDC_Host_BytesReceived() function may be queried in advance to determine how many bytes + * are currently buffered in the CDC interface's data receive pipe. * - * \pre This function must only be called when the Host state machine is in the HOST_STATE_Configured state or the + * \pre This function must only be called when the Host state machine is in the \ref HOST_STATE_Configured state or the * call will fail. * * \param[in,out] CDCInterfaceInfo Pointer to a structure containing a CDC Class host configuration and state. * - * \return Next received byte from the device, or 0 if no data received. + * \return Next received byte from the device, or a negative value if no data received. */ - uint8_t CDC_Host_ReceiveByte(USB_ClassInfo_CDC_Host_t* const CDCInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1); - + int16_t CDC_Host_ReceiveByte(USB_ClassInfo_CDC_Host_t* const CDCInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1); + /** Flushes any data waiting to be sent, ensuring that the send buffer is cleared. * - * \pre This function must only be called when the Host state machine is in the HOST_STATE_Configured state or the + * \pre This function must only be called when the Host state machine is in the \ref HOST_STATE_Configured state or the * call will fail. * * \param[in,out] CDCInterfaceInfo Pointer to a structure containing a CDC Class host configuration and state. @@ -277,7 +287,8 @@ * \param[in,out] CDCInterfaceInfo Pointer to a structure containing a CDC Class configuration and state. * \param[in,out] Stream Pointer to a FILE structure where the created stream should be placed. */ - void CDC_Host_CreateStream(USB_ClassInfo_CDC_Host_t* const CDCInterfaceInfo, FILE* const Stream); + void CDC_Host_CreateStream(USB_ClassInfo_CDC_Host_t* const CDCInterfaceInfo, + FILE* const Stream); /** Identical to CDC_Host_CreateStream(), except that reads are blocking until the calling stream function terminates * the transfer. While blocking, the USB and CDC service tasks are called repeatedly to maintain USB communications. @@ -285,7 +296,8 @@ * \param[in,out] CDCInterfaceInfo Pointer to a structure containing a CDC Class configuration and state. * \param[in,out] Stream Pointer to a FILE structure where the created stream should be placed. */ - void CDC_Host_CreateBlockingStream(USB_ClassInfo_CDC_Host_t* const CDCInterfaceInfo, FILE* const Stream); + void CDC_Host_CreateBlockingStream(USB_ClassInfo_CDC_Host_t* const CDCInterfaceInfo, + FILE* const Stream); /** CDC class driver event for a control line state change on a CDC host interface. This event fires each time the device notifies * the host of a control line state change (containing the virtual serial control line states, such as DCD) and may be hooked in the @@ -306,14 +318,11 @@ #define CDC_DATA_CLASS 0x0A #define CDC_DATA_SUBCLASS 0x00 #define CDC_DATA_PROTOCOL 0x00 - - #define CDC_FOUND_DATAPIPE_IN (1 << 0) - #define CDC_FOUND_DATAPIPE_OUT (1 << 1) - #define CDC_FOUND_NOTIFICATION_IN (1 << 2) /* Function Prototypes: */ #if defined(__INCLUDE_FROM_CDC_CLASS_HOST_C) - static int CDC_Host_putchar(char c, FILE* Stream) ATTR_NON_NULL_PTR_ARG(2); + static int CDC_Host_putchar(char c, + FILE* Stream) ATTR_NON_NULL_PTR_ARG(2); static int CDC_Host_getchar(FILE* Stream) ATTR_NON_NULL_PTR_ARG(1); static int CDC_Host_getchar_Blocking(FILE* Stream) ATTR_NON_NULL_PTR_ARG(1); @@ -324,9 +333,9 @@ static uint8_t DCOMP_CDC_Host_NextCDCControlInterface(void* const CurrentDescriptor) ATTR_NON_NULL_PTR_ARG(1); static uint8_t DCOMP_CDC_Host_NextCDCDataInterface(void* const CurrentDescriptor) ATTR_NON_NULL_PTR_ARG(1); static uint8_t DCOMP_CDC_Host_NextCDCInterfaceEndpoint(void* const CurrentDescriptor) ATTR_NON_NULL_PTR_ARG(1); - #endif + #endif #endif - + /* Disable C linkage for C++ Compilers: */ #if defined(__cplusplus) } @@ -335,3 +344,4 @@ #endif /** @} */ +