Functions
usbConstructs.c File Reference

Detailed Description

Contains example constructs for send/receive operations.

Functions

uint8_t USBHID_sendDataAndWaitTillDone (uint8_t *dataBuf, uint16_t size, uint8_t intfNum, uint32_t ulTimeout)
 
uint8_t USBHID_sendDataInBackground (uint8_t *dataBuf, uint16_t size, uint8_t intfNum, uint32_t ulTimeout)
 
uint16_t USBHID_receiveDataInBuffer (uint8_t *dataBuf, uint16_t size, uint8_t intfNum)
 
uint8_t USBCDC_sendDataAndWaitTillDone (uint8_t *dataBuf, uint16_t size, uint8_t intfNum, uint32_t ulTimeout)
 
uint8_t USBCDC_sendDataInBackground (uint8_t *dataBuf, uint16_t size, uint8_t intfNum, uint32_t ulTimeout)
 
uint16_t USBCDC_receiveDataInBuffer (uint8_t *dataBuf, uint16_t size, uint8_t intfNum)
 

Function Documentation

uint8_t USBHID_sendDataAndWaitTillDone ( uint8_t *  dataBuf,
uint16_t  size,
uint8_t  intfNum,
uint32_t  ulTimeout 
)

Completely Sends the Data in dataBuf

Parameters
*dataBufis the address of the data buffer.
sizeis the size of the data.
intfnumintfNum is which HID interface is being used.
ulTimeoutis the (32-bit) number of polls to USBHID_getInterfaceStatus().

Sends the data in dataBuf, of size size, using the post-call polling method. It does so over interface intfNum. The function doesn’t return until the send has completed. Because of this, the user buffer can be edited immediately after the function returns, without consequence. The function assumes that size is non-zero. It assumes no previous send operation is underway.

The 32-bit number ulTimeout selects how many times USBHID_getInterfaceStatus() will be polled while waiting for the operation to complete. If the value is zero, then no timeout is employed; it will wait indefinitely. When choosing a number, it is advised to consider MCLK speed, as a faster CPU will cycle through the calls more quickly. The function provides the simplest coding, at the expense of wasted cycles and potentially allowing MCU execution to become "locked" to the host, a disadvantage if the host (or bus) is slow.

The function also checks all valid return codes, and returns non-zero if an error occurred. In many applications, the return value can simply be evaluated as zero or non-zero, where nonzero means the call failed for reasons of host or bus non-availability. Therefore, it may desirable for the application to break from execution. Other applications may wish to handle return values 1 and 2 in different ways.

It’s recommended not to call this function from within an event handler. This is because if an interface currently has an open send operation, the operation will never complete during the event handler; rather, only after the ISR that spawned the event returns. Thus the USBHID_getInterfaceStatus() polling would loop indefinitely (or timeout). It’s better to set a flag from within the event handler, and use this flag to trigger the calling of this function from within main().

Returns
0 if the call succeeded; all data has been sent.
1 if the call timed out, either because the host is unavailable or a COM port with an active application on the host wasn't opened.
2 if the bus is unavailable.
uint8_t USBHID_sendDataInBackground ( uint8_t *  dataBuf,
uint16_t  size,
uint8_t  intfNum,
uint32_t  ulTimeout 
)

Completely Sends the Data in dataBuf

Parameters
*dataBufis the address of the data buffer.
sizeis the size of the data.
intfnumintfNum is which HID interface is being used.
ulTimeoutis the (32-bit) number of polls to USBHID_getInterfaceStatus().

Sends the data in dataBuf, of size size, using the pre-call polling method. It does so over interface intfNum. The send operation may still be active after the function returns, and dataBuf should not be edited until it can be verified that the operation has completed. The function assumes that size is non-zero. This call assumes a previous send operation might be underway.

The 32-bit number ulTimeout selects how many times USBHID_getInterfaceStatus() will be polled while waiting for the previous operation to complete. If the value is zero, then no timeout is employed; it will wait indefinitely. When choosing a number, it is advised to consider MCLK speed, as a faster CPU will cycle through the calls more quickly. The function provides simple coding while also taking advantage of the efficiencies of background processing. If a previous send operation is underway, this function does waste cycles polling, like xxxsendDataWaitTilDone(); however it's less likely to do so since much of the sending presumably took place in the background since the last call to xxxsendDataInBackground().

The function also checks all valid return codes, and returns non-zero if an error occurred. In many applications, the return value can simply be evaluated as zero or non-zero, where nonzero means the call failed for reasons of host or bus non-availability. Therefore, it may desirable for the application to break from execution. Other applications may wish to handle return values 1 and 2 in different ways.

It’s recommended not to call this function from within an event handler. This is because if an interface currently has an open send operation, the operation will never complete during the event handler; rather, only after the ISR that spawned the event returns. Thus the USBHID_getInterfaceStatus() polling would loop indefinitely (or timeout). It’s better to set a flag from within the event handler, and use this flag to trigger the calling of this function from within main().

Returns
0 if the call succeeded; all data has been sent.
1 if the call timed out, either because the host is unavailable or a COM port with an active application on the host wasn't opened.
2 if the bus is unavailable.
uint16_t USBHID_receiveDataInBuffer ( uint8_t *  dataBuf,
uint16_t  size,
uint8_t  intfNum 
)

Opens a Receive Operation

Parameters
*dataBufis the address of the data buffer.
sizeis the size of the data.
intfnumintfNum is which HID interface is being used.

Opens a brief receive operation for any data that has already been received into the USB buffer over interface intfNum. This call only retrieves data that is already waiting in the USB buffer – that is, data that has already been received by the MCU. It assumes a previous, open receive operation (began by a direct call to USBxxx_receiveData()) is NOT underway on this interface; and no receive operation remains open after this call returns. It doesn't check for kUSBxxx_busNotAvailable, because it doesn't matter if it's not. The data in the USB buffer is copied into dataBuf, and the function returns the number of bytes received.

size is the maximum that is allowed to be received before exiting; i.e., it is the size allotted to dataBuf. If size bytes are received, the function ends, returning size. In this case, it’s possible that more bytes are still in the USB buffer; it might be a good idea to open another receive operation to retrieve them. For this reason, operation is simplified by using large size values, since it helps ensure all the data is retrieved at one time.

This function is usually called when a USBHID_handleDataReceived() event flags the application that data has been received into the USB buffer.

Returns
The number of bytes received into dataBuf.
uint8_t USBCDC_sendDataAndWaitTillDone ( uint8_t *  dataBuf,
uint16_t  size,
uint8_t  intfNum,
uint32_t  ulTimeout 
)

Completely Sends the Data in dataBuf

Parameters
*dataBufis the address of the data buffer.
sizeis the size of the data.
intfnumintfNum is which interface is being used.
ulTimeoutis the (32-bit) number of polls to USBCDC_getInterfaceStatus().

Sends the data in dataBuf, of size size, using the post-call polling method. It does so over interface intfNum. The function doesn’t return until the send has completed. Because of this, the user buffer can be edited immediately after the function returns, without consequence. The function assumes that size is non-zero. It assumes no previous send operation is underway.

The 32-bit number ulTimeout selects how many times USBCDC_getInterfaceStatus() will be polled while waiting for the operation to complete. If the value is zero, then no timeout is employed; it will wait indefinitely. When choosing a number, it is advised to consider MCLK speed, as a faster CPU will cycle through the calls more quickly. The function provides the simplest coding, at the expense of wasted cycles and potentially allowing MCU execution to become "locked" to the host, a disadvantage if the host (or bus) is slow.

The function also checks all valid return codes, and returns non-zero if an error occurred. In many applications, the return value can simply be evaluated as zero or non-zero, where nonzero means the call failed for reasons of host or bus non-availability. Therefore, it may desirable for the application to break from execution. Other applications may wish to handle return values 1 and 2 in different ways.

It’s recommended not to call this function from within an event handler. This is because if an interface currently has an open send operation, the operation will never complete during the event handler; rather, only after the ISR that spawned the event returns. Thus the USBCDC_getInterfaceStatus() polling would loop indefinitely (or timeout). It’s better to set a flag from within the event handler, and use this flag to trigger the calling of this function from within main().

Returns
0 if the call succeeded; all data has been sent.
1 if the call timed out, either because the host is unavailable or a COM port with an active application on the host wasn't opened.
2 if the bus is unavailable.
uint8_t USBCDC_sendDataInBackground ( uint8_t *  dataBuf,
uint16_t  size,
uint8_t  intfNum,
uint32_t  ulTimeout 
)

Completely Sends the Data in dataBuf

Parameters
*dataBufis the address of the data buffer.
sizeis the size of the data.
intfnumintfNum is which interface is being used.
ulTimeoutis the (32-bit) number of polls to USBCDC_getInterfaceStatus().

Sends the data in dataBuf, of size size, using the pre-call polling method. It does so over interface intfNum. The send operation may still be active after the function returns, and dataBuf should not be edited until it can be verified that the operation has completed. The function assumes that size is non-zero. This call assumes a previous send operation might be underway.

The 32-bit number ulTimeout selects how many times USBCDC_getInterfaceStatus() will be polled while waiting for the previous operation to complete. If the value is zero, then no timeout is employed; it will wait indefinitely. When choosing a number, it is advised to consider MCLK speed, as a faster CPU will cycle through the calls more quickly. The function provides simple coding while also taking advantage of the efficiencies of background processing. If a previous send operation is underway, this function does waste cycles polling, like xxxsendDataWaitTilDone(); however it's less likely to do so since much of the sending presumably took place in the background since the last call to xxxsendDataInBackground().

The function also checks all valid return codes, and returns non-zero if an error occurred. In many applications, the return value can simply be evaluated as zero or non-zero, where nonzero means the call failed for reasons of host or bus non-availability. Therefore, it may desirable for the application to break from execution. Other applications may wish to handle return values 1 and 2 in different ways.

It’s recommended not to call this function from within an event handler. This is because if an interface currently has an open send operation, the operation will never complete during the event handler; rather, only after the ISR that spawned the event returns. Thus the USBCDC_getInterfaceStatus() polling would loop indefinitely (or timeout). It’s better to set a flag from within the event handler, and use this flag to trigger the calling of this function from within main().

Returns
0 if the call succeeded; all data has been sent.
1 if the call timed out, either because the host is unavailable or a COM port with an active application on the host wasn't opened.
2 if the bus is unavailable.
uint16_t USBCDC_receiveDataInBuffer ( uint8_t *  dataBuf,
uint16_t  size,
uint8_t  intfNum 
)

Opens a Receive Operation

Parameters
*dataBufis the address of the data buffer.
sizeis the size of the data.
intfnumintfNum is which CDC interface is being used.

Opens a brief receive operation for any data that has already been received into the USB buffer over interface intfNum. This call only retrieves data that is already waiting in the USB buffer – that is, data that has already been received by the MCU. It assumes a previous, open receive operation (began by a direct call to USBxxx_receiveData()) is NOT underway on this interface; and no receive operation remains open after this call returns. It doesn't check for kUSBxxx_busNotAvailable, because it doesn't matter if it's not. The data in the USB buffer is copied into dataBuf, and the function returns the number of bytes received.

size is the maximum that is allowed to be received before exiting; i.e., it is the size allotted to dataBuf. If size bytes are received, the function ends, returning size. In this case, it’s possible that more bytes are still in the USB buffer; it might be a good idea to open another receive operation to retrieve them. For this reason, operation is simplified by using large size values, since it helps ensure all the data is retrieved at one time.

This function is usually called when a USBCDC_handleDataReceived() event flags the application that data has been received into the USB buffer.

Returns
The number of bytes received into dataBuf.

Copyright 2015, Texas Instruments Incorporated