Functions
UsbCdc.c File Reference

Detailed Description

Contains APIs related to CDC (Virtual COMport) device class.

Functions

BYTE USBCDC_sendData (const BYTE *data, WORD size, BYTE intfNum)
BYTE USBCDC_abortSend (WORD *size, BYTE intfNum)
BYTE USBCDC_receiveData (BYTE *data, WORD size, BYTE intfNum)
BYTE USBCDC_abortReceive (WORD *size, BYTE intfNum)
BYTE USBCDC_rejectData (BYTE intfNum)
BYTE USBCDC_intfStatus (BYTE intfNum, WORD *bytesSent, WORD *bytesReceived)
BYTE USBCDC_bytesInUSBBuffer (BYTE intfNum)

Function Documentation

BYTE USBCDC_sendData ( const BYTE *  data,
WORD  size,
BYTE  intfNum 
)

Begins a Send Operation to the USB Host.

Parameters:
*datais an array of data to be sent.
sizeis the number of bytes to be sent, starting from address data.
intfNumselects which data should be transmitted over.

Initiates sending of a user buffer over CDC interface intfNum, of size size and starting at address data. If size is larger than the packet size, the function handles all packetization and buffer management. size has no inherent upper limit (beyond being a 16-bit value).

In most cases where a send operation is successfully started, the function will return kUSBCDC_sendStarted. A send operation is said to be underway. At some point, either before or after the function returns, the send operation will complete, barring any events that would preclude it. (Even if the operation completes before the function returns, the return code will still be kUSBCDC_sendStarted.) If the bus is not connected when the function is called, the function returns kUSBCDC_busNotAvailable, and no operation is begun. If size is 0, the function returns kUSBCDC_generalError. If a previous send operation is already underway for this data interface, the function returns with kUSBCDC_intfBusyError.

USB includes low-level mechanisms that ensure valid transmission of data.

See Sec. 7.2 of "Programmer's Guide: MSP430 USB API Stack for CDC/PHDC/HID/MSC" for a detailed discussion of send operations.

Returns:
Any of the following:
  • kUSBCDC_sendStarted: a send operation was successfully started
  • kUSBCDC_intfBusyError: a previous send operation is underway
  • kUSBCDC_busNotAvailable: the bus is either suspended or disconnected
  • kUSBCDC_generalError: size was zero, or other error

Referenced by cdcSendDataInBackground(), and cdcSendDataWaitTilDone().

BYTE USBCDC_abortSend ( WORD *  size,
BYTE  intfNum 
)

Aborts an Active Send Operation.

Parameters:
sizeis the number of bytes that were sent prior to the abort action.
intfNumis the data interface for which the send should be aborted.

Aborts an active send operation on data interface intfNum. Returns the number of bytes that were sent prior to the abort, in size.

An application may choose to call this function if sending failed, due to factors such as:

  • a surprise removal of the bus
  • a USB suspend event
  • any send operation that extends longer than desired (perhaps due to no open COM port on the host.)
Returns:
kUSB_succeed
BYTE USBCDC_receiveData ( BYTE *  data,
WORD  size,
BYTE  intfNum 
)

Begins a Receive Operation from the USB Host.

Parameters:
*datais an array to contain the data received.
sizeis the number of bytes to be received.
intfNumis which data interface to receive from.

Receives size bytes over CDC interface intfNum into memory starting at address data. size has no inherent upper limit (beyond being a 16-bit value).

The function may return with kUSBCDC_receiveStarted, indicating that a receive operation is underway. The operation completes when size bytes are received. The application should ensure that the data memory buffer be available during the whole of the receive operation.

The function may also return with kUSBCDC_receiveCompleted. This means that the receive operation was complete by the time the function returned.

If the bus is not connected when the function is called, the function returns kUSBCDC_busNotAvailable, and no operation is begun. If size is 0, the function returns kUSBCDC_generalError. If a previous receive operation is already underway for this data interface, the function returns kUSBCDC_intfBusyError.

USB includes low-level mechanisms that ensure valid transmission of data.

See Sec. 7.2 of "Programmer's Guide: MSP430 USB API Stack for CDC/PHDC/HID/MSC" for a detailed discussion of receive operations.

Returns:
Any of the following:
  • kUSBCDC_receiveStarted: A receive operation has been succesfully started.
  • kUSBCDC_receiveCompleted: The receive operation is already completed.
  • kUSBCDC_intfBusyError: a previous receive operation is underway.
  • kUSBCDC_busNotAvailable: the bus is either suspended or disconnected.
  • kUSBCDC_generalError: size was zero, or other error.

Referenced by cdcReceiveDataInBuffer().

BYTE USBCDC_abortReceive ( WORD *  size,
BYTE  intfNum 
)

Aborts an Active Receive Operation.

Parameters:
*sizeis the number of bytes that were received and are waiting at the assigned address.
intfNumis the data interface for which the send should be aborted.

Aborts an active receive operation on CDC interface intfNum. Returns the number of bytes that were received and transferred to the data location established for this receive operation. The data moved to the buffer up to that time remains valid.

An application may choose to call this function if it decides it no longer wants to receive data from the USB host. It should be noted that if a continuous stream of data is being received from the host, aborting the operation is akin to pressing a "pause" button; the host will be NAK'ed until another receive operation is opened.

See Sec. 7.2 of "Programmer's Guide: MSP430 USB API Stack for CDC/PHDC/HID/MSC" for a detailed discussion of receive operations.

Returns:
kUSB_succeed
BYTE USBCDC_rejectData ( BYTE  intfNum)

Rejects the Data Received from the Host.

This function rejects data that has been received from the host, for interface inftNum, that does not have an active receive operation underway. It resides in the USB endpoint buffer and blocks further data until a receive operation is opened, or until rejected. When this function is called, the buffer for this interface is purged, and the data lost. This frees the USB path to resume communication.

See Sec. 7.2 of "Programmer's Guide: MSP430 USB API Stack for CDC/PHDC/HID/MSC" for a detailed discussion of receive operations.

Returns:
kUSB_succeed
BYTE USBCDC_intfStatus ( BYTE  intfNum,
WORD *  bytesSent,
WORD *  bytesReceived 
)

Indicates the Status of the CDC Interface.

Parameters:
intfNumis the interface number for which status is being retrieved.
bytesSentIf a send operation is underway, the number of bytes that send have been transferred to the host is returned in this location. If no operation is underway, this returns zero.
bytesReceivedIf a receive operation is underway, the number of bytes that have been transferred to the assigned memory location is returned in this location. If no receive operation is underway, this returns zero.

Indicates the status of the CDC interface intfNum. If a send operation is active for this interface, the function also returns the number of bytes that have been transmitted to the host. If a receive operation is active for this interface, the function also returns the number of bytes that have been received from the host and are waiting at the assigned address.

Because multiple flags can be returned, the possible values can be masked together - for example, kUSBCDC_waitingForSend + kUSBCDC_dataWaiting.

Returns:
Any combination of the following:
  • kUSBCDC_waitingForSend: Indicates that a send operation is open ont his interface
  • kUSBCDC_waitingForReceive: Indicates that a receive operation is open on this interface
  • kUSBCDC_dataWaiting: Indicates that data has been received from the host for this interface, waiting in the USB receive buffers, lacking an open receive operation to accept it.
  • kUSBCDC_busNotAvailable: Indicates that the bus is either suspended or disconnected. Any operations that had previously been underway are now aborted.

Referenced by cdcSendDataInBackground(), and cdcSendDataWaitTilDone().

BYTE USBCDC_bytesInUSBBuffer ( BYTE  intfNum)

Gives the Number of Bytes in the USB Endpoint Buffer.

Parameters:
intfNumis the data interface whose buffer is to be checked.

Returns the number of bytes waiting in the USB endpoint buffer for intfNum. A non-zero value generally means that no receive operation is open by which these bytes can be copied to a user buffer. If the value is non-zero, the application should either open a receive operation so that the data can be moved out of the endpoint buffer, or the data should be rejected (USBCDC_rejectData()).

Returns:
The number of bytes waiting in this buffer.

Referenced by cdcReceiveDataInBuffer().


Copyright 2013, Texas Instruments Incorporated