1.1.7.1 How the Library Works

The SDSPI driver library is a multi-client, multi-instance buffer queue model based block driver interface.

Abstraction Model

The SDSPI driver provides abstraction to communicate with SD card through the SPI peripheral library or SPI driver interface.

drv_sdspi_abstraction_model

SDSPI Driver Features:

  • The SDSPI driver is built on top of SPI peripheral library or SPI driver

  • The SDSPI driver Library registers an event handler with the underlying SPI peripheral library or the SPI Driver instance. This event handler is called by the SPI PLIB or the SPI driver from the interrupt context to notify the SDSPI driver that the requested transfer is complete

  • When DMA is enabled and SPI PLIB is used, the SDSPI Driver registers an event handler with the DMA peripheral library. This event handler is called by by the DMA PLIB from the interrupt context once the DMA transfer is complete.

  • When using SPI driver, the DMA operations are handled internally by the SPI driver. In this case, the SDSPI registers a callback with the SPI driver which in turn registers a callback with the DMA peripheral library.

  • The SD Card driver state machine checks for SD Card attach/detach status using command-response mechanism. Once a SD Card is detected,

    • The state machine initializes the SD Card making it ready for the client to submit read/write requests.

    • After the SD Card is initialized, the state machine periodically checks if the SD Card is still connected using command/response mechanism.

    • The rate at which the SD card driver checks for the SD Card attach/detach event can be specified via an MHC configuration option. In case RTOS is enabled, the RTOS Task Delay value for the SDSPI Driver task also affects the rate at which the SD Card attach/detach is checked.

SDSPI driver is capable of working in both Asynchronous and Synchronous modes.

SDSPI driver in Asynchronous mode

Asynchronous mode APIs are non-blocking in nature. These APIs submit a request and return back to the application.

Typically, if there are no on-going or pending requests in the driver's transfer queue, then the transfer is started by the API and completed from the peripheral interrupt. If there is an on-going transfer or one or more requests pending in the driver's transfer queue, then the request is added to the queue and executed when all the pending requests are complete. The size of the transfer queue is configurable using MCC based on application needs. The SD card driver state machine checks the driver transfer queue and executes any pending requests.

The transfer APIs provide a transfer handle back to the application. If the driver was unable to accept the request, then the transfer handle will be set to NULL. This usually happens if the transfer queue is full or if invalid argruments are passed to the API. Application must check the value of the transfer handle to ensure the request was accepted successfully. Transfer handle can be used to identify/track the request.

Application can either register a callback to get notified when the transfer is complete or poll the status of the request by calling the DRV_SDSPI_CommandStatusGet() API. Asynchronous mode APIs are available in both bare-metal and RTOS mode.

SDSPI driver in Synchronous mode

Synchronous mode APIs are blocking in nature. These APIs block until the transfer/request is complete. Synchronous mode APIs are only supported in RTOS mode. These APIs initate the transfer and then block on a semaphore while the transfer is in progress, thereby allowing other ready tasks to run. Once the transfer is complete, the semaphore is given (from the peripheral interrupt's context) thereby unblocking the calling task. The return value usually provides the status of the transfer.