1.8.10.5 MCSPIx_Read Function
C
/* x = MCSPI instance number */ /* MCSPI master mode */ bool MCSPIx_Read(void* pRdBuffer, size_t rxSize) /* MCSPI slave mode */ size_t MCSPIx_Read(void* pRdBuffer, size_t rxSize)
Summary
MCSPI master mode
Reads data on the MCSPI peripheral.
MCSPI slave mode
Reads data from the PLIB's internal buffer to the application buffer
Description
MCSPI master mode
This function reads "rxSize" number of bytes on MCSPI module. The received data is stored in the buffer pointed by pRdBuffer. When the interrupt is disabled in the PLIB, this function will be blocking in nature. In this mode, the function will not return until all the requested data is transferred. The function returns true after receiving "rxSize" number of bytes. This indicates that the operation has been completed. When interrupt is enabled, the function will be non-blocking in nature. The function returns immediately. The data transfer process continues from the peripheral interrupt. The application specified receive buffer is owned by the PLIB until the data transfer is complete and should not be modified by the application till the transfer is complete. Only one transfer is allowed at any time. The application can use a callback function or a polling function to check for completion of the transfer. If a callback is required then it should be registered prior to calling the MCSPIx_Read() function. The application can use the MCSPIx_IsBusy() to poll for completion of transfer.
MCSPI slave mode
This function reads "rxSize" number of bytes received from MCSPI master. The function copies the data that is already received by the PLIB in its internal buffer to the application's buffer specified by pRdBuffer. The return value indicates the actual number of bytes copied to the application buffer. The MCSPIx_ReadCountGet API can be used to know the available bytes in the PLIB. Application must call this API from the callback function itself.
Precondition
The MCSPIx_Initialize function must have been called.
MCSPI master mode
Callback can be registered using MCSPIx_CallbackRegister API if the PLIB is configured in Interrupt mode and transfer completion status needs to be communicated back to application via callback.
MCSPI slave mode
Callback must have been registered using MCSPIx_CallbackRegister API to get notified when the transfer is complete.
Parameters
MCSPI master mode
Param | Description |
---|---|
pRdBuffer | Pointer to the buffer where the received data will be stored. In "Interrupt Mode", this buffer should not be modified after calling the function and before the callback function has been called or the MCSPIx_IsBusy() function returns false. |
rxSize | Number of bytes to be received. This value is the byte size of the buffer irrespective of 8/16/32 bit transfer mode. |
MCSPI slave mode
Param | Description |
---|---|
pRdBuffer | Pointer to the buffer where the data from the PLIB's internal buffer must be copied |
rxSize | Number of bytes to copy. If 16/32 bit modes are supported, the rxSize must be specified in terms of 16/32 bit words |
Returns
MCSPI master mode
true - If configured for non-interrupt mode, the function has received the requested number of bytes. If configured for Interrupt mode, the request was accepted successfully and will be processed in the interrupt.
false - If pRdBuffer is NULL or rxSize is 0. In Interrupt mode, the function will additionally return false if there is an on-going data transfer at the time of calling the function.
MCSPI slave mode
Returns the number of bytes actually copied into the pRdBuffer. If 16/32 bit modes are supported, the return value is specified in terms of 16/32 bit words.
Example
MCSPI master mode
uint8_t rxBuffer[10]; size_t rxSize = 10; void MCSPIEventHandler(uintptr_t context) { //Transfer was completed without error, do something else now. } MCSPI1_Initialize(); MCSPI1_CallbackRegister(MCSPIEventHandler, (uintptr_t)0); if(MCSPI1_Read(&rxBuffer, rxSize)) { // request got accepted } else { // request didn't get accepted, try again later with correct arguments }
MCSPI slave mode
uint8_t APP_RxData[10]; void MCSPIEventHandler(uintptr_t context ) { if (MCSPI1_ErrorGet() == MCSPI_SLAVE_ERROR_NONE) { // Read out the received data. This could be meaningful data if MCSPI master is // writing to slave or it could be dummy data if MCSPI master is reading from slave. // However, irrespective of whether slave is expecting meaningful data or dummy // data from master, MCSPI slave must always read out the data to clear the PLIB's // internal receive buffer. appData.nBytesRead = MCSPI1_Read(APP_RxData, MCSPI1_ReadCountGet()); } else { // Handle error } } MCSPI1_CallbackRegister(MCSPIEventHandler, (uintptr_t) 0);
Remarks
None