Asynchronous Bus Requests
Other versions of this page are also available for the following:
.gif "A hyphen indicates that the information in this topic is not relevant for this platform, or that the platform does not support the API that is listed.")
.gif "A checkmark indicates that the information in this topic is relevant for this platform, and that any API listed is also supported on this platform.")
8/28/2008
By using asynchronous bus requests, a client driver can issue multiple bus requests without the need to wait for previous requests to complete. The bus requests are internally queued within the bus driver, and sequentially issued to the Secure Digital (SD) device when the SD bus is available.
By making use of asynchronous requests, a client driver can maximize use of the available SD bus bandwidth. For example, while a SD I/O (SDIO) network adapter is busy transmitting a packet, the client driver can be formatting the next packet to be sent.
As each request completes, the bus driver invokes a callback routine by using the client driver. This callback routine can then inform the main client driver thread that the request has completed. With a sequence of requests, the callback routine should keep track of the outstanding requests and signal the main client driver thread when all outstanding requests are complete.
SDBusRequest
An asynchronous bus request is issued by calling the SDBusRequest function. The pCallbackparameter is a pointer to a callback routine that will be called by the completion thread of the bus driver when the bus request is complete. The RequestParamparameter is optional and is passed to the callback routine for the bus request.
The ppRequestparameter is used to obtain a pointer to a newly created bus request structure. Usually, the client driver should store this pointer to enable request cancellation and deletion. This is not mandatory, since the pointer is also passed to the callback function upon completion of the request.
SDFreeBusRequest
The client driver is responsible for freeing the memory allocated for this new bus request. This can be done with a call to the SDFreeBusRequest function within the callback when a request is completed. The callback is invoked whenever a request is completed. A request can be completed on success, error, or cancellation.
Since the callback will run in the completion thread of the bus driver, the callback should do as little as possible. Most importantly, it must not make any blocking function calls. Several blocking or potentially blocking function calls are:
SDCancelBusRequest
The client driver is able to cancel any outstanding bus request by calling the SDCancelBusRequest function. If the bus request has yet to be sent, it will be removed from the queue of requests, and the completion callback will be called. The callback routine must free the bus request as normal. The request status of SD_API_STATUS_CANCELED indicates the request was cancelled. In all cases, the client driver should wait until all requests have been completed.**
SDBusRequestResponse
The client driver is able to retrieve the command response for the asynchronous bus request by calling the SDBusRequestResponse function. If the asynchronous request failed, it will return with the status code. If the asynchronous request succeeded, the pCommandResp will return the command response associated with the request. This function is usually called in the completion callback function to determine whether the request succeeded or not.**
See Also
Reference
SDBusRequest
SDFreeBusRequest
SDSynchronousBusRequest
SDSetCardFeature
SDCardInfoQuery
SDCancelBusRequest
SDBusRequestResponse