Objective:
To understand the functionality of CyU3PDmaChannelSetSuspend() API of FX3 through firmware example implementation.
Related APIs:
CyU3PDmaChannelResume()
CyU3PDmaChannelGetBuffer()
CyU3PDmaChannelCommitBuffer()
API Usage:
The CyU3PDmaChannelSetSuspend() API can be used to suspend either the PRODUCER or the CONSUMER socket of a particular DMA channel. When a socket is suspended, further write (to a PRODUCER socket) or read (from the CONSUMER socket) cannot be performed until it is resumed. This API can be helpful when the data needs to be modified before being committed to the CONSUMER socket. In case of MANUAL channels, this API is not much helpful since the data has to be manually committed each time. But, in the case of AUTO channels, this API can be used to modify the data before being committing it to the CONSUMER.
API Prototype:
CyU3PReturnStatus_t
CyU3PDmaChannelSetSuspend (
CyU3PDmaChannel *handle, /**< Handle to the channel to be modified. */
CyU3PDmaSckSuspType_t prodSusp, /**< Suspend option for the producer socket. */
CyU3PDmaSckSuspType_t consSusp /**< Suspend option for the consumer socket. */
);
API functionality:
- The CyU3PDmaChannel identifies the DMA channel of which the socket is to be suspended.
- The CyU3PDmaSckSuspType_t determines the nature in which the socket is suspended. The different options available are:
1. CY_U3P_DMA_SCK_SUSP_NONE - Socket will not be suspended and will be in normal mode of operation.
2. CY_U3P_DMA_SCK_SUSP_EOP - Socket will be suspended whenever the EOP bit in the buffer is set.
3. CY_U3P_DMA_SCK_SUSP_CUR_BUF - Socket will be suspended after the current buffer is processed.
4. CY_U3P_DMA_SCK_SUSP_CONS_PARTIAL_BUF - Socket will be suspended whenever there is a short packet from the PRODUCER socket.
Firmware Implementation:
The USBBulkSourceSink firmware and the GpifToUsb firmware that comes with the FX3 SDK have been modified with additional vendor commands to implement the socket suspend on DMA channel. Also, in the GpifToUsb firmware, the GPIF II state machine has been modified to include the COMMIT action. This generates an EOP condition on the buffer.
Vendor request handling is as follows. 0xFA implements a consumer socket suspend when there is an EOP condition, 0xFB implements a consumer socket suspend after the current buffer is completed and 0xFC implements a consumer socket suspend when there is a partial buffer, 0xFD gets the buffer and fills it with a known set of bytes (0xAA, 0xBB, 0xCC, 0xDD, 0xEE, 0xFF in the attached examples), commits the buffer to the consumer and then resumes the consumer socket.
NOTE 1: When the socket suspend option is set to CY_U3P_DMA_SCK_SUSP_EOP, the socket will be suspended after handling any buffer with the EOP bit set. Typically the EOP bit will be set on any data buffers that are wrapped up on the PIB (GPIF) side through a COMMIT action. The DMA buffer with the EOP bit set would have been handled before the socket gets suspended, meaning that it is not possible to make changes to the contents of that data packet.
NOTE 2: When using the mentioned vendor commands, set the wLength field ('Bytes to Transfer' box in Control Center) to 0.
Case 1: CY_U3P_DMA_SCK_SUSP_EOP
Test Procedure:
- Program the GpifToUsb firmware into the FX3 using the Cypress USB Control Center.
- Use Cypress USB Control Center to read data from the 0x81 BULK IN endpoint. Since the state machine has been modified, 24 bytes of data will be received on the Control Center window for each IN transfer.
- From the Cypress USB Control Center, issue the 0xFA vendor command. This sets up the DMA channel consumer to be suspended after handling a buffer with EOP bit set.
- Perform the next BULK IN transfer on the 0x81 endpoint. This transfer will be successful (Refer NOTE 1).
- On the next BULK IN transaction from 0x81 endpoint, there will be an error on the Control Center. This indicates that the socket is now suspended.
- From the Cypress USB Control Center, issue the 0xFD vendor command. The buffer is obtained, filled with known bytes of data and committed to the consumer. The socket suspend is removed and the channel is resumed.
- Perform an IN data transfer from the Cypress USB Control Center. The known bytes of data that was manually committed will be seen on the display window.
- On subsequent reads from the 0x81 BULK IN endpoint, 24 bytes of data will be received continuously.
Case 2: CY_U3P_DMA_SCK_SUSP_CUR_BUF:
Test Procedure:
- Program the USBBulkLoopAutoEnum firmware into the FX3 using the Cypress USB Control Center.
- Use the Bulkloop application from the FX3 SDK to perform OUT and IN transactions with the corresponding endpoints. The application shows 'Successes' on the transactions.
- From the Cypress USB Control Center, issue the 0xFB vendor command. This suspends the consumer socket after the current buffer is processed. The suspension of the socket will be evident from the Bulkloop application which now starts showing 'Failures'. Stop the transactions on the Bulkloop application.
- From the Cypress USB Control Center, issue the 0xFD vendor command. The buffer is obtained, filled with known bytes of data and committed to the consumer. The socket suspend is removed and the channel is resumed.
- Perform an IN data transfer from the Cypress USB Control Center. The known bytes of data that was manually committed will be seen on the display window.
- Bulkloop application can again be started which now shows 'Successes' indicating resumption of the channel socket.
Case 3: CY_U3P_DMA_SCK_SUSP_CONS_PARTIAL_BUF
Test Procedure:
- Program the USBBulkLoopAutoEnum firmware into the FX3 using the Cypress USB Control Center.
- Use the Bulkloop application from the FX3 SDK to perform OUT and IN transactions with the corresponding endpoints. The application shows 'Successes' on the transactions.
- From the Cypress USB Control Center, issue the 0xFB vendor command. This sets up the consumer socket to be suspended after it receives a short packet. The Bulkloop application continues to show 'Successes' indicating that the socket is not yet suspended.
- From the Cypress USB Control Center, send a smaller number of bytes of data (say 10 bytes) over the BULK OUT endpoint. This generates a partial buffer from the PRODUCER socket which in turn generates a suspend condition on the consumer socket. The suspension of the socket will be evident from the Bulkloop application which now starts showing 'Failures'. Stop the transfers on the Bulkloop application.
- From the Cypress USB Control Center, issue the 0xFD vendor command. The buffer is obtained, filled with known bytes of data and committed to the consumer. The socket suspend is removed and the channel is resumed.
- Perform an IN data transfer from the Cypress USB Control Center. The known bytes of data that was manually committed will be seen on the display window.
- Bulkloop application can again be started which now shows 'Successes' indicating resumption of the channel socket.
