pci.sgml

eCos/RedBoot for勤研ARM AnywhereII(4510) 含全部源代码

<!-- {{{ Banner                         -->

<!-- =============================================================== -->
<!--                                                                 -->
<!--     pci.sgml                                                    -->
<!--                                                                 -->
<!--     eCos PCI support                                            -->
<!--                                                                 -->
<!-- =============================================================== -->
<!-- ####COPYRIGHTBEGIN####                                          -->
<!--                                                                 -->
<!-- =============================================================== -->
<!-- Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002 Red Hat, Inc.  -->
<!-- This material may be distributed only subject to the terms      -->
<!-- and conditions set forth in the Open Publication License, v1.0  -->
<!-- or later (the latest version is presently available at          -->
<!-- http://www.opencontent.org/openpub/)                            -->
<!-- Distribution of the work or derivative of the work in any       -->
<!-- standard (paper) book form is prohibited unless prior           -->
<!-- permission obtained from the copyright holder                   -->
<!-- =============================================================== -->
<!--                                                                 -->      
<!-- ####COPYRIGHTEND####                                            -->
<!-- =============================================================== -->
<!-- #####DESCRIPTIONBEGIN####                                       -->
<!--                                                                 -->
<!-- ####DESCRIPTIONEND####                                          -->
<!-- =============================================================== -->

<!-- }}} -->

<PART id="io-pci">
<TITLE>PCI Library</TITLE>
<CHAPTER id="ecos-pci-library">
<TITLE>The eCos PCI Library</TITLE>
<PARA>The PCI library is an optional part of eCos, and is only
	applicable to some platforms.</PARA>
<SECT1 id="pci-library">
<TITLE>PCI Library</TITLE>
<PARA>The eCos PCI library provides the following functionality:</PARA>
<orderedlist>
<listitem><para>Scan the PCI bus for specific devices or devices of a certain
class.</para></listitem>
<listitem><para>Read and change generic PCI information.</para></listitem>
<listitem><para>Read and change device-specific PCI information.</para></listitem>
<listitem><para>Allocate PCI memory and IO space to devices.</para></listitem>
<listitem><para>Translate a device's PCI interrupts to equivalent HAL
vectors.</para></listitem>
</orderedlist>
<PARA>Example code fragments are from the pci1 test (see <filename>io/pci/&lt;release&gt;/tests/pci1.c</filename>).</PARA>
<PARA>All of the functions described below are declared in the header
file <filename>&lt;cyg/io/pci.h&gt;</filename> which all
clients of the PCI library should include.</PARA>
<SECT2>
<TITLE>PCI Overview</TITLE>
<PARA>The PCI bus supports several address spaces: memory, IO, and configuration. All PCI
devices must support mandatory configuration space registers. Some devices may also present
IO mapped and/or memory mapped resources. Before devices on the bus can be used, they must
be configured. Basically, configuration will assign PCI IO and/or memory address ranges to
each device and then enable that device. All PCI devices have a unique address in
configuration space. This address is comprised of a bus number, a device number, and a
function number. Special devices called bridges are used to connect two PCI busses together.
The PCI standard supports up to 255 busses with each bus having up to 32 devices and each
device having up to 8 functions.
</PARA>
<PARA>The environment in which a platform operates will dictate if and how eCos should
configure devices on the PCI bus. If the platform acts as a host on a single PCI bus,
then devices may be configured individually from the relevant device driver. If the
platform is not the primary host, such as a PCI card plugged into a PC, configuration
of PCI devices may be left to the PC BIOS. If PCI-PCI bridges are involved, configuration
of all devices is best done all at once early in the boot process. This is because all
devices on the secondary side of a bridge must be evaluated for their IO and memory space
requirements before the bridge can be configured.
</PARA>
</SECT2>
<SECT2>
<TITLE>Initializing the bus</TITLE>
<PARA>The PCI bus needs to be initialized before it can be used.
This only needs to be done once - some HALs may do it as part of
the platform initialization procedure, other HALs may leave it to
the application or device drivers to do it. The following function
will do the initialization only once, so it's safe to call from
multiple drivers:</PARA>
<PROGRAMLISTING>void cyg_pci_init( void );</PROGRAMLISTING>
</SECT2>
<SECT2>
<TITLE>Scanning for devices</TITLE>
<PARA>After the bus has been initialized, it is possible to scan
it for devices. This is done using the function:</PARA>
<PROGRAMLISTING>cyg_bool cyg_pci_find_next(  cyg_pci_device_id cur_devid, 
	                     cyg_pci_device_id *next_devid );
</PROGRAMLISTING>
<PARA>It will scan the bus for devices starting at <parameter>cur_devid
</parameter>. If a device is found, its devid is stored in <parameter>
next_devid</parameter> and the function returns <constant>true</constant>.
</PARA>
<PARA>The <filename>pci1</filename> test's outer loop looks like:</PARA>
<PROGRAMLISTING>
    cyg_pci_init();
    if (cyg_pci_find_next(CYG_PCI_NULL_DEVID, &amp;devid)) {
        do {
             &lt;use devid&gt;
        } while (cyg_pci_find_next(devid, &amp;devid));
    }</PROGRAMLISTING>
<PARA>What happens is that the bus gets initialized and a scan is
started. <literal>CYG_PCI_NULL_DEVID</literal> causes <function>
cyg_pci_find_next()</function> to restart its scan. If the bus does not
contain any devices, the first call to <function>cyg_pci_find_next()</function>
will return <constant>false</constant>.</PARA>
<PARA>If the call returns <constant>true</constant>, a loop is entered where
the found devid is used. After devid processing has completed, the next device
on the bus is searched for; <function>cyg_pci_find_next()</function>
continues its scan from the current devid. The loop terminates when
no more devices are found on the bus.</PARA>
<PARA>This is the generic way of scanning the bus, enumerating all
the devices on the bus. But if the application is looking for a
device of a given device class (e.g., a SCSI controller), or a specific
vendor device, these functions simplify the task a bit:</PARA>
<PROGRAMLISTING>
cyg_bool cyg_pci_find_class(  cyg_uint32 dev_class,
                              cyg_pci_device_id *devid );
cyg_bool cyg_pci_find_device(  cyg_uint16 vendor, cyg_uint16 device,
                               cyg_pci_device_id *devid );</PROGRAMLISTING>
<PARA>They work just like <function>cyg_pci_find_next()</function>,
but only return true when the dev_class or vendor/device
qualifiers match those of a device on the bus. The devid serves
as both an input and an output operand: the scan starts at the given
device, and if a device is found devid is updated with the value
for the found device.</PARA>
<PARA>The <filename>&lt;cyg/io/pci_cfg.h&gt;</filename> header
file (included by <filename>pci.h</filename>) contains definitions for PCI 
class, vendor and device codes which can be used as arguments to the find
functions.
The list of vendor and device codes is not complete: add new codes
as necessary. If possible also register the codes at the PCI Code
List (<ulink url="http://www.yourvote.com/pci">http://www.yourvote.com/pci)
</ulink> which is where the eCos definitions are generated from.</PARA>
</SECT2>
<SECT2>
<TITLE>Generic config information</TITLE>
<PARA>When a valid device ID (devid) is found using one of the above
functions, the associated device can be queried and controlled using
the functions:</PARA>
<PROGRAMLISTING>
void cyg_pci_get_device_info (  cyg_pci_device_id devid, 
                                cyg_pci_device *dev_info );
void cyg_pci_set_device_info (  cyg_pci_device_id devid, 
                                cyg_pci_device *dev_info );</PROGRAMLISTING>
<PARA>The <structname>cyg_pci_device structure</structname> (defined in
<filename>pci.h</filename>) primarily holds information as described by the PCI
 specification <link linkend=pci-spec>[1]</link>.
The <filename>pci1</filename> test prints out some of this information:</PARA>
<PROGRAMLISTING>            // Get device info
            cyg_pci_get_device_info(devid, &amp;dev_info);
            diag_printf("\n Command   0x%04x, Status 0x%04x\n",
                        dev_info.command, dev_info.status);</PROGRAMLISTING>
<PARA>The command register can also be written to, controlling (among
other things) whether the device responds to IO and memory access
from the bus. </PARA>
</SECT2>
<SECT2>
<TITLE>Specific config information</TITLE>
<PARA>The above functions only allow access to generic PCI config
registers. A device can have extra config registers not specified
by the PCI specification. These can be accessed with these functions:</PARA>
<PROGRAMLISTING>
void cyg_pci_read_config_uint8(  cyg_pci_device_id devid,
                                 cyg_uint8 offset, cyg_uint8 *val);
void cyg_pci_read_config_uint16(  cyg_pci_device_id devid,
                                  cyg_uint8 offset, cyg_uint16 *val);
void cyg_pci_read_config_uint32(  cyg_pci_device_id devid,
                                  cyg_uint8 offset, cyg_uint32 *val);
void cyg_pci_write_config_uint8(  cyg_pci_device_id devid,
                                  cyg_uint8 offset, cyg_uint8 val);
void cyg_pci_write_config_uint16(  cyg_pci_device_id devid,
                                   cyg_uint8 offset, cyg_uint16 val);
void cyg_pci_write_config_uint32(  cyg_pci_device_id devid,
                                   cyg_uint8 offset, cyg_uint32 val);
</PROGRAMLISTING>
<PARA>The write functions should only be used for device-specific
config registers since using them on generic registers may invalidate
the contents of a previously fetched cyg_pci_device
structure.</PARA>
</SECT2>
<SECT2>
<TITLE>Allocating memory</TITLE>
<PARA>A PCI device ignores all IO and memory access from the PCI
bus until it has been activated. Activation cannot happen until
after device configuration. Configuration means telling the device
where it should map its IO and memory resources. This is done with
one of the following functions::</PARA>
<PROGRAMLISTING>cyg_bool cyg_pci_configure_device( cyg_pci_device *dev_info );
cyg_bool cyg_pci_configure_bus( cyg_uint8 bus, cyg_uint8 *next_bus );
</PROGRAMLISTING>
<PARA>The <function>cyg_pci_configure_device</function> handles all IO
and memory regions that need configuration on non-bridge devices. On
platforms with multiple busses connected by bridges, the <function>
cyg_pci_configure_bus</function> function should be used. It will recursively
configure all devices on the given <parameter>bus</parameter> and all
subordinate busses. <function>cyg_pci_configure_bus</function> will
use <function>cyg_pci_configure_device</function> to configure
individual non-bridge devices.
</PARA>
<PARA> Each region is represented in the PCI device's config space by BARs
(Base Address Registers) and is handled individually according to type
using these functions:</PARA>
<PROGRAMLISTING>cyg_bool cyg_pci_allocate_memory(  cyg_pci_device *dev_info,
                                   cyg_uint32 bar, 
                                   CYG_PCI_ADDRESS64 *base );
cyg_bool cyg_pci_allocate_io(  cyg_pci_device *dev_info,
                               cyg_uint32 bar,