hostc_sd_requests.htm

SDIO Linux documentation

		<p class="BODYTEXT">A bus request that&nbsp;requires read/write data
		will contain block parameters describing&nbsp;the
		manner&nbsp;in&nbsp;which a&nbsp;buffer of data is transferred to/from
		a&nbsp;card.&nbsp; The HCD does not need to decode the command
		arguments for&nbsp;block parameters.&nbsp;The <font face="Courier New">BlockCount</font>
		and <font face="Courier New">BlockLen</font> parameters
		indicate&nbsp;how many blocks and the number of bytes per
		block&nbsp;the transaction will consist of.&nbsp; These parameters are
		setup by the peripheral driver and&nbsp;specific to
		the&nbsp;card/function.&nbsp;&nbsp;The <font face="Courier New">pDataBuffer</font>
		field will point to an HCD-accessible buffer to retrieve/store data
		for the transaction.&nbsp; The HCD should not assume any specific
		data-type alignment to this buffer.</p>

		<p class="BODYTEXT">The HCD can use the <font face="Courier New">DataRemaining</font>
		and <font face="Courier New">pHcdContext</font> fields of the request
		to keep track of the data&nbsp;transfer progress. The HCD should use
		interrupt operation to transfer all blocks as read/write timeouts can
		be considerably long.&nbsp; The exception to this  is when a transfer 
		has been marked as a short transfer (see <a href="#shorttransfers">Short Transfers</a>).
		Upon completion	(success	or	failure)&nbsp;the
		HCD	should	indicate	the <font face="Courier New">EVENT_HCD_TRANSFER_DONE
		<font face="Arial">event</font>.&nbsp;</font></p>
		<p class="BODYTEXT"><a name="CompleteRequest"></a><strong>Completing Requests Immediately:</strong></p>
		<p class="BODYTEXT"">HCDs that  complete bus transactions within the request
		  callback (general failure, polling command completion, etc..) can return
		  a completion status other than <font face="Courier New, Courier, mono">SDIO_STATUS_PENDING</font>.
		  This will indicate to the SDIO core that the request was completed
		  immediately (inline) and higher-level request processing is required.
		  Under some circumstances the SDIO core will flag the HCD to complete
		  the request in a separate context using either a deferred procedure
		  or work item. This forces the HCD to handle the request as if the request
		  was processed in an interrupt service routine. The purpose of this
		  action is to break a recursive string of bus request that could result
		  in a stack overflow. The HCD must check the bus request flags
		  for the
		  <font face="Courier New, Courier, mono">SDREQ_FLAGS_FORCE_DEFERRED_COMPLETION</font> before
		  returning from the request callback. If set the HCD must make the 
		  <font face="Courier New, Courier, mono"><a href="HD_Reference.htm#FUNC_SDIO_HandleHcdEvent">SDIO_HandleHcdEvent</a></font> indication
		  in a separate work item  and return <font face="Courier New, Courier, mono">SDIO_STATUS_PENDING</font> from
		  the request callback. The request must be completed in this manner
		  regardless of whether the request was processed by hardware. For example,
		  if a
		  request failed
		  to acquire some resource
		  or	contained an invalid settings, the driver must always check this
		  flag and may be forced into processing it in a deferred context. The
		  follow code demonstrates this:</p>
		<p class="BODYTEXT"">
	<pre>
  ... set up request
  // check status
if (status != SDIO_STATUS_PENDING) {
   // request was completed inline or failed for whatever reason
   if (pRequest->Flags & SDREQ_FLAGS_FORCE_DEFERRED_COMPLETE) {
       // queue a work item to make the indication
	   QueueBusRequestCompleteWorkItem(pHct);
	       // always return status pending
	   return SDIO_STATUS_PENDING;
   } 
   // fall through and return completion status, we completed this in-line  
}
    
return status;</pre></p>
	  <p class="BODYTEXT""><a name="shorttransfers"></a><strong>Short Data Transfers:</strong>
	  </p>
	  <p class="BODYTEXT"">A function driver may provide a hint to the host controller
	    that a data transfer is short. This hint will allow the HCD to process
	    a data transfer immediately without employing interrupts. This can improve
	    overall throughput by reducing interrupt context switching. The following
	    guideline is used by function driver to determine whether a short transfer
	    operation shouldbe attempted:</p>
	  <p class="BODYTEXT""><ul>
  <li>The data transfer will be short consisting of 1 block and usually less
    than 8 bytes
in
length.</li>
  <li>If the transfer is a read operation, the  start bit  will occur within
    several clocks. The card will not introduce any significant delay to the
    start bit of read data.</li>
  <li>If the transfer is a write operation, the  program done signal will occur
    within several clock cycles. The card will not introduce any significant
    delay for program done.</li>
  </ul></p>
	  <p class="BODYTEXT"">If a short data transfer optimization is requested, the
	    function driver will set the <font face="Courier New, Courier, mono">SDREQ_FLAGS_DATA_SHORT_TRANSFER</font> flag
	    in the request. Implementing any optimation for short data transfers
	    is optional and the HCD can safely ignore this flag
	    and process
	    the request
	    as a normal
	    data
	    transfer (with interrupts). </p>
	  <p class="BODYTEXT""><strong>Direct Memory Access:</strong></p>
	  <p class="BODYTEXT"">Function drivers can indicate that data buffers associated
	    with
	    a bus request reside in address spaces that can be directly handled
	    by the system DMA controller or external bus master. The request flag,
	    <font face="Courier New, Courier, mono">SDREQ_FLAGS_DATA_DMA</font> has
	    been added for this purpose. As an additional reference the description
	    of DMA operations, from a function driver point of view, is provided
	    in the PDK help under: <a href="periph_io_requests.htm#DMAOperation">Function
	    Driver I/O Requests : Direct Memory Access</a>.</p>
	  <p class="BODYTEXT"">Function drivers will guarantee that the
	    data buffer for this request meets the
	    DMA requirements for this HCD and platform. While the <font face="Courier New, Courier, mono">SDREQ_FLAGS_DATA_DMA</font> flag
	    is only informational for the HCD, the data pointer of a request is handled
	    differently
	    when it is set. . When set, the <font face="Courier New, Courier, mono">pDataBuffer</font> member
	    of the request points to a list of <font face="Courier New, Courier, mono">SDDMA_DESCRIPTOR</font> structures.
	    The number of elements in this list is set in the <font face="Courier New, Courier, mono">DescriptorCount</font> field
	    of the
	    request. The descriptor count will be less
	    than the maximum number of descriptors per bus request that is reported
	    in the <font face="Courier New, Courier, mono">SDDMA_DESCRIPTION</font> provided
	    by each HCD. The <font face="Courier New, Courier, mono">SDDMA_DESCRIPTION</font> and <font face="Courier New, Courier, mono">SDDMA_DESCRIPTOR</font> structures
	    are OS dependent and contain DMA pertinent information about the platform
	    capabilties and data buffers, respectively. The <font face="Courier New, Courier, mono"><a href="hostc_structure.htm#SDHCDStruct" >SDHCD</a></font> structure
	    contains the <font face="Courier New, Courier, mono">pDmaDescription</font> member
	    that is set by DMA-capable HCDs before they register with the bus driver.
	    If the HCD does not support DMA, then it should set this
	    member to NULL. In this case, the HCD will never see a bus request with
	    the
	    <font face="Courier New, Courier, mono">SDREQ_FLAGS_DATA_DMA</font> set.</p>
	  <p class="BODYTEXT"">The <font face="Courier New, Courier, mono">SDDMA_DESCRIPTION</font> structure
	      is operating system dependent. It typically contains fields that define
	      the
	      highest address the device can DMA to/from, the maximum number of DMA
	      descriptor entries per request, the maximum number of bytes  that
	      can be processed for each descriptor and various address/length alignment
	      requirements. If the DMA controller does not support scatter gather
	    DMA (it may use
	      a single set
	      of hardware
	      registers in a DMA channel) the HCD can choose to set the maximum number
	      of DMA descriptors to one.  Alternatively, the HCD can set this value
	      greater than 1 and emulate scatter gather behavior by
      loading the next DMA descriptor on each DMA completion interrupt.  On some
	      OS implementations the HCD can provide a hint to the function drivers
	      that the DMA controller implements true scatter gather functionality.</p>
	  <p class="BODYTEXT"">Refer to the SDIO HCD samples for OS-specific
	    usage of the <font face="Courier New, Courier, mono">SDDMA_DESCRIPTION</font> and <font face="Courier New, Courier, mono">SDDMA_DESCRIPTOR</font> structures.
	     Refer to the <font face="Courier New, Courier, mono">ctsystem_xxxx.h</font> header
	    file (ex. <font face="Courier New, Courier, mono">ctsystem_linux.h</font>)
	    for the definition of these structures. The sample HCDs  cover a range of
	    DMA implementations/restrictions and techniques (scatter gather or simple
	    DMA).<br>
&nbsp;</p>
	  <!-- InstanceEndEditable -->
&nbsp;<br/>
</table></td></tr>
<table width="100%" border="0" cellspacing="0" cellpadding="2" >
  <tr> <td><div align="right"><a href="#TopTopic">Back to top</a></div></td></tr>
  <tr bgcolor="#0000FF"> 
    <td> 
      <font color="#FFFFFF"face="Arial, Helvetica, sans-serif"><strong>