c-periph.html

linux2.4.20下的针对三星公司的s3c2410的usb模块驱动代码

<dd><p class="Body"><a name="87335"></a>This module is the TCD for the Philips PDIUSBD12 evaluation kit. All hardware-dependent code for a target controller is contained in the TCD. Each TCD exports a single entry point, generally with a name of the form <b class="routine">usbTcd</b><i class="textVariable">Xxxx</i><b class="routine">Exec</b><b>(&nbsp;)</b>, and all communication with the TCD is performed through this function. There is no direct link between <b class="library">usbTargLib</b> and any underlying TCD; that is, <b class="library">usbTargLib</b> has no prior (compile-time) knowledge of which TCDs are to be loaded in a particular system. Each TCD's entry point is exposed to <b class="library">usbTargLib</b> during a process called <i class="term">TCD attachment</i>, described in <a href="c-periph.html#87352"><i class="title">2.2.2&nbsp;Attaching and Detaching TCDs</i></a>.</p>
</dl>

<dd><font face="Helvetica, sans-serif" size="-1" class="sans">
<h5 class="HU"><i><a name="87339"></a>usbIsaLib or usbPciLib</i></h5>
</font><dl class="margin">

<dd><p class="Body"><a name="87340"></a>This module provides the TCD with an abstract set of ISA bus services, allowing the TCD to be written independent of variations in the underlying BSP. In the case of the <b class="symbol_lc">pcPentium</b> BSP, on which the Wind River USB peripheral stack was developed and tested, each of the <b class="library">usbIsaLib</b> functions is redirected to a corresponding function in <b class="library">usbPciLib</b>. For a description of <b class="library">usbPciLib</b>, see <a href="/folk/docs/usb/1.1.2/guide/c-chapter.html#91472"><i class="title">1.2&nbsp;Architecture Overview</i></a>. </p>
<dd><p class="Body"><a name="87341"></a>There is no requirement that a particular TCD be written to use <b class="library">usbIsaLib</b> or even <b class="library">usbPciLib</b>. These modules were designed to promote portability across BSP platforms. In systems where that is not an issue, developers can freely code "directly to the hardware" in the TCD itself.</p>
</dl>

</dl>


<br class="H2"><a name="87343"></a>
<br class="H2navbar">
<font face="Helvetica, sans-serif" class="sans">
<h3 class="H2"><i>2.2  &nbsp;&nbsp;
USB Target Driver (usbTargLib)</i></h3>
</font>

<dl class="margin">

<dl class="margin">

<dd><p class="Body"><a name="87344"></a>This section describes typical use of the <b class="library">usbTargLib</b>, activities such as initialization, TCD attachment, and data transfers. It also discusses key features of module's internal design.</p>
</dl>

</dl>

<font face="Helvetica, sans-serif" class="sans">
<h4 class="H3"><i><a name="87346"></a>2.2.1  &nbsp;&nbsp;Initializing usbTargLib</i></h4>
</font>
<dl class="margin">

<dl class="margin">

<dd><p class="Body"><a name="87347"></a>Initializing <b class="library">usbTargLib</b> is a two-step process. First, <b class="library">usbTargLib</b>'s entry point, <b class="routine">usbTargInitialize(&nbsp;)</b>, must be called at least once. The <b class="routine">usbTargInitialize</b><b>(&nbsp;)</b> routine initializes internal <b class="library">usbTargLib</b> data structures and, in turn, calls the initialization entry points of other modules in the USB driver stack. For a given system, it is acceptable to call <b class="routine">usbTargInitialize</b><b>(&nbsp;)</b> once (perhaps during the boot sequence) or to call it many times (as during the initialization of each TCD or target application). The <b class="library">usbTargLib</b> driver maintains a usage count that is incremented for each successful call to <b class="routine">usbTargInitialize</b><b>(&nbsp;)</b> and decremented for each corresponding call to <b class="routine">usbTargShutdown</b><b>(&nbsp;)</b>. The driver only truly initializes itself when the usage count goes from zero to one, and it only truly "shuts down" when the usage count returns to zero.</p>
<dd><p class="Body"><a name="87348"></a>The following code fragment illustrates the proper initialization and shutdown of <b class="library">usbTargLib</b>:</p>
</dl>

<dl class="margin">

<dd><font color="0000a0">
<pre class="Code"><a name="87349"></a>&nbsp;&nbsp;&nbsp;&nbsp;... 
 
&nbsp;&nbsp;&nbsp;&nbsp;/* Initialize usbTargLib. */ 
 
&nbsp;&nbsp;&nbsp;&nbsp;if (usbTargInitialize () != OK) 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return ERROR; 
&nbsp;&nbsp;&nbsp;&nbsp;... 
&nbsp;&nbsp;&nbsp;&nbsp;... 
 
&nbsp;&nbsp;&nbsp;&nbsp;/* target application code. */ 
&nbsp;&nbsp;&nbsp;&nbsp;... 
&nbsp;&nbsp;&nbsp;&nbsp;... 
 
&nbsp;&nbsp;&nbsp;&nbsp;/* Shut down usbTargLib. Note: we only execute this code if the return 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;* code from usbTargInitialize() was OK. Note also that there's really no 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;* reason to check the result of usbTargShutdown(). 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*/ 
 
&nbsp;&nbsp;&nbsp;&nbsp;usbTargShutdown (); 
</pre>
</font>
</dl>

<dl class="margin">

<dd><p class="Body"><a name="87350"></a>The second step of <b class="library">usbTargLib</b> initialization is to attach at least one TCD to the driver, using <b class="library">usbTargLib</b>'s <b class="routine">usbTargTcdAttach</b><b>(&nbsp;)</b> routine. Normally, the attachment of TCDs to <b class="library">usbTargLib</b> happens during the VxWorks boot sequence. However, <b class="library">usbTargLib</b> is designed to allow TCDs to be attached (and detached) at run-time. This flexibility allows <b class="library">usbTargLib</b> to support systems in which USB target controllers can be "hot-swapped" without restarting the system.</p>
</dl>

</dl>

<font face="Helvetica, sans-serif" class="sans">
<h4 class="H3"><i><a name="87352"></a>2.2.2  &nbsp;&nbsp;Attaching and Detaching TCDs</i></h4>
</font>
<dl class="margin">

<dl class="margin">

<dd><p class="Body"><a name="87353"></a>You decide when to attach TCDs to <b class="library">usbTargLib</b> and when to detach them, if ever. In most peripheral applications, a single TCD and corresponding target application are attached to <b class="library">usbTargLib</b> during the initial boot sequence and remain attached indefinitely.</p>
<dd><p class="Body"><a name="87354"></a>In order to attach a TCD to <b class="library">usbTargLib</b>, the caller passes the TCD's execution entry point and a TCD-defined parameter (the TCD attachment parameter) to the <b class="routine">usbTargTcdAttach</b><b>(&nbsp;)</b> routine. The caller must also provide the address of a <i class="term">callback table</i> that identifies key entry points in the target application. The target application's callback table is described more fully in <a href="c-periph.html#87384"><i class="title">2.2.4&nbsp;Target Application Callback Table</i></a>. Finally, the caller provides pointers to variables that receive information about the TCD attachment, including a handle to the attached TCD and information about the USB endpoints supported by the TCD.</p>
<dd><p class="Body"><a name="87358"></a>In response to the <b class="routine">usbTargTcdAttach</b><b>(&nbsp;)</b> call, <b class="library">usbTargLib</b> invokes the TCD's execution entry point with a <b class="symbol_UC">TCD_FNC_ATTACH</b> service request, passing it the same TCD attachment parameter provided by the caller. Use of this TCD-defined parameter can vary, however the Philips PDIUSBD12 example interprets this parameter as a pointer to a structure of the following form:</p>
</dl>

<dl class="margin">

<dd><font color="0000a0">
<pre class="Code"><a name="87359"></a>typedef struct usb_tcd_pdiusbd12_params 
&nbsp;&nbsp;&nbsp;&nbsp;{ 
&nbsp;&nbsp;&nbsp;&nbsp;UINT32 ioBase;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* Base I/O address range */ 
&nbsp;&nbsp;&nbsp;&nbsp;UINT16 irq;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* IRQ channel (e.g., 5 = IRQ5) */ 
&nbsp;&nbsp;&nbsp;&nbsp;UINT16 dma;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* DMA channel (e.g., 3 = DMA3) */ 
&nbsp;&nbsp;&nbsp;&nbsp;} USB_TCD_PDIUSBD12_PARAMS, *pUSB_TCD_PDIUSBD12_PARAMS;</pre>
</font>
</dl>

<dl class="margin">

<dd><p class="Body"><a name="87360"></a>For the Philips evaluation kit, the caller must initialize this structure with settings corresponding to the Philips ISA bus board. For other target systems, these values can be hard-coded. The TCD uses the information in this structure to locate and manage the specified target controller. </p>
<dd><p class="Body"><a name="87361"></a>The following code fragment demonstrates how to attach the Philips evaluation kit to <b class="library">usbTargLib</b>:</p>
</dl>

<dl class="margin">

<dd><font color="0000a0">
<pre class="Code"><a name="87362"></a>&nbsp;&nbsp;&nbsp;&nbsp;/* Attach the Philips PDIUSBD12 evaluation kit TCD to usbTargLib. */ 
 
&nbsp;&nbsp;&nbsp;&nbsp;USB_TCD_PDIUSBD12_PARAMS params; 
 
&nbsp;&nbsp;&nbsp;&nbsp;memset (&amp;params, 0, sizeof (params)); 
&nbsp;&nbsp;&nbsp;&nbsp;params.ioBase = (UINT32) 0x368; 
&nbsp;&nbsp;&nbsp;&nbsp;params.irq = (UINT16) 5; 
&nbsp;&nbsp;&nbsp;&nbsp;params.dma = (UINT16) 7; 
 
&nbsp;&nbsp;&nbsp;&nbsp;if (usbTargTcdAttach ( 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;usbTcdPdiusbd12EvalExec,&nbsp;&nbsp;&nbsp;&nbsp;/* TCD's entry point */ 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(pVOID) &amp;params,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* TCD-specific parameter */ 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;callbackTable,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* target app's callback table */ 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* is defined elsewhere */  
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;callbackParam,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* target app-specific parameter */ 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;targChannel,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;/* "handle" returned by usbTargLib */ 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;numEndpoints,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* nbr of endpoints supported by TCD */ 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;pEndpoints,)&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* an array of info about endpoints */)  
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;== OK) 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* TCD &amp; target application were initialized successfully. */ 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* Do post-attach processing. */ 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;... 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;... 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* Now enable the TCD. */ 
 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;if (usbTargEnable (targChannel) != OK) 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* Failed to enable TCD. */ 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} 
&nbsp;&nbsp;&nbsp;&nbsp;else 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{ 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* Failed to attach the TCD &amp; initialize the target application. */ 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;}  
</pre>
</font>
</dl>

</dl>

<dl class="margin">
<dd>
<p class="table">
<table border="0" cellpadding="2" cellspacing="0">
<tr valign="top">
<td colspan=1 rowspan=1></td><td><hr></td></tr>
<tr valign="top"><td>
<img border="0" alt="*" src="icons/caution.gif">
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
</td>
<td colspan=1 rowspan=1><div class="CalloutCell"><a name="87367"></a>
<b class="symbol_UC"><font face="Helvetica, sans-serif" size="-1" class="sans">CAUTION:  </font></b>
While <b class="library">usbTargLib</b> and the sample Philips TCD are designed to support the dynamic attachment and detachment of TCDs, some Wind River BSPs do not support the disconnection of the USB TCD from the underlying interrupt vector, a function essential to the detaching process. If the vector is subsequently re-enabled, the system may attempt to execute a stale interrupt service routine and will fault. </div>
</td>
</tr>
<tr valign="top">
<td colspan=1 rowspan=1></td>
<td colspan=1 rowspan=1><hr>
</td>
</tr>

<tr valign="middle">
<td colspan="20">

</td>
</tr>
</table>
</p>



</dl>
<font face="Helvetica, sans-serif" class="sans">
<h4 class="H3"><i><a name="87375"></a>2.2.3  &nbsp;&nbsp;Enabling and Disabling TCDs</i></h4>
</font>
<dl class="margin">

<dl class="margin">

<dd><p class="Body"><a name="87376"></a>In some situations, the target application may not be ready to begin handling USB requests as soon as it calls <b class="routine">usbTargTcdAttach</b><b>(&nbsp;)</b>. For example, the target application may need to store and process the endpoint information returned by <b class="routine">usbTargTcdAttach</b><b>(&nbsp;)</b> first. For this reason, <b class="library">usbTargLib</b> provides two additional functions to enable and disable the TCD.</p>
<dd><p class="Body"><a name="87377"></a>The routine <b class="routine">usbTargEnable</b><b>(&nbsp;) </b>enables the specified TCD. The TCD, in turn, enables the underlying USB target controller. By convention, the target controller should not turn on its USB drivers until the TCD has been enabled by calling <b class="routine">usbTargEnable</b><b>(&nbsp;)</b>. Thus, until <b class="routine">usbTargEnable</b><b>(&nbsp;)</b> has been called, the target controller, and thus the peripheral, is not visible on the USB.</p>
<dd><p class="Body"><a name="87378"></a>The routine <b class="routine">usbTargDisable</b><b>(&nbsp;)</b> disables the specified TCD and is generally called just before detaching a TCD.</p>
<dd><p class="Body"><a name="87382"></a>The previous code fragment in <a href="c-periph.html#87352"><i class="title">2.2.2&nbsp;Attaching and Detaching TCDs</i></a> illustrates one use of the <b class="routine">usbTargEnable</b><b>(&nbsp;)</b> function.</p>
</dl>

</dl>

<font face="Helvetica, sans-serif" class="sans">
<h4 class="H3"><i><a name="87384"></a>2.2.4  &nbsp;&nbsp;Target Application Callback Table</i></h4>
</font>
<dl class="margin">

<dl class="margin">

<dd><p class="Body"><a name="87391"></a>USB peripherals never initiate activity on the USB<sup><a href="#foot"><b class="FootnoteMarker">1</b></a></sup>
. Instead, all USB activity is initiated by the USB host. The architecture of the USB peripheral stack reflects this in the way communication is handled between <b class="library">usbTargLib</b> and the target application. Once the TCD and its associated target application have been attached to <b class="library">usbTargLib</b>, <b class="library">usbTargLib</b> asynchronously calls back into the target application by way of the entry points exposed in the target application's callback table. The callback table takes the following form:</p>
</dl>

<dl class="margin">