URL
https://opencores.org/ocsvn/openrisc/openrisc/trunk
Subversion Repositories openrisc
[/] [openrisc/] [trunk/] [rtos/] [ecos-2.0/] [doc/] [html/] [ref/] [ecos-pci-library.html] - Rev 174
Compare with Previous | Blame | View Log
<!-- Copyright (C) 2003 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 is obtained from the copyright holder. -->
<HTML
><HEAD
><TITLE
>The eCos PCI Library</TITLE
><meta name="MSSmartTagsPreventParsing" content="TRUE">
<META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
"><LINK
REL="HOME"
TITLE="eCos Reference Manual"
HREF="ecos-ref.html"><LINK
REL="UP"
TITLE="PCI Library"
HREF="io-pci.html"><LINK
REL="PREVIOUS"
TITLE="PCI Library"
HREF="io-pci.html"><LINK
REL="NEXT"
TITLE="PCI Library reference"
HREF="pci-library-reference.html"></HEAD
><BODY
CLASS="CHAPTER"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>eCos Reference Manual</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="io-pci.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="pci-library-reference.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="CHAPTER"
><H1
><A
NAME="ECOS-PCI-LIBRARY">Chapter 30. The eCos PCI Library</H1
><DIV
CLASS="TOC"
><DL
><DT
><B
>Table of Contents</B
></DT
><DT
><A
HREF="ecos-pci-library.html#PCI-LIBRARY"
>PCI Library</A
></DT
><DT
><A
HREF="pci-library-reference.html"
>PCI Library reference</A
></DT
></DL
></DIV
><P
>The PCI library is an optional part of eCos, and is only
applicable to some platforms.</P
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="PCI-LIBRARY">PCI Library</H1
><P
>The eCos PCI library provides the following functionality:</P
><P
></P
><OL
TYPE="1"
><LI
><P
>Scan the PCI bus for specific devices or devices of a certain
class.</P
></LI
><LI
><P
>Read and change generic PCI information.</P
></LI
><LI
><P
>Read and change device-specific PCI information.</P
></LI
><LI
><P
>Allocate PCI memory and IO space to devices.</P
></LI
><LI
><P
>Translate a device's PCI interrupts to equivalent HAL
vectors.</P
></LI
></OL
><P
>Example code fragments are from the pci1 test (see <TT
CLASS="FILENAME"
>io/pci/<release>/tests/pci1.c</TT
>).</P
><P
>All of the functions described below are declared in the header
file <TT
CLASS="FILENAME"
><cyg/io/pci.h></TT
> which all
clients of the PCI library should include.</P
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN12691">PCI Overview</H2
><P
>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.</P
><P
>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.</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN12695">Initializing the bus</H2
><P
>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:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>void cyg_pci_init( void );</PRE
></TD
></TR
></TABLE
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN12699">Scanning for devices</H2
><P
>After the bus has been initialized, it is possible to scan
it for devices. This is done using the function:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>cyg_bool cyg_pci_find_next( cyg_pci_device_id cur_devid,
cyg_pci_device_id *next_devid );</PRE
></TD
></TR
></TABLE
><P
>It will scan the bus for devices starting at <TT
CLASS="PARAMETER"
><I
>cur_devid</I
></TT
>. If a device is found, its devid is stored in <TT
CLASS="PARAMETER"
><I
>next_devid</I
></TT
> and the function returns <TT
CLASS="CONSTANT"
>true</TT
>.</P
><P
>The <TT
CLASS="FILENAME"
>pci1</TT
> test's outer loop looks like:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
> cyg_pci_init();
if (cyg_pci_find_next(CYG_PCI_NULL_DEVID, &devid)) {
do {
<use devid>
} while (cyg_pci_find_next(devid, &devid));
}</PRE
></TD
></TR
></TABLE
><P
>What happens is that the bus gets initialized and a scan is
started. <TT
CLASS="LITERAL"
>CYG_PCI_NULL_DEVID</TT
> causes <TT
CLASS="FUNCTION"
>cyg_pci_find_next()</TT
> to restart its scan. If the bus does not
contain any devices, the first call to <TT
CLASS="FUNCTION"
>cyg_pci_find_next()</TT
>
will return <TT
CLASS="CONSTANT"
>false</TT
>.</P
><P
>If the call returns <TT
CLASS="CONSTANT"
>true</TT
>, a loop is entered where
the found devid is used. After devid processing has completed, the next device
on the bus is searched for; <TT
CLASS="FUNCTION"
>cyg_pci_find_next()</TT
>
continues its scan from the current devid. The loop terminates when
no more devices are found on the bus.</P
><P
>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:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="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 );</PRE
></TD
></TR
></TABLE
><P
>They work just like <TT
CLASS="FUNCTION"
>cyg_pci_find_next()</TT
>,
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.</P
><P
>The <TT
CLASS="FILENAME"
><cyg/io/pci_cfg.h></TT
> header
file (included by <TT
CLASS="FILENAME"
>pci.h</TT
>) 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 (<A
HREF="http://www.yourvote.com/pci"
TARGET="_top"
>http://www.yourvote.com/pci)</A
> which is where the eCos definitions are generated from.</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN12726">Generic config information</H2
><P
>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:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="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 );</PRE
></TD
></TR
></TABLE
><P
>The <SPAN
CLASS="STRUCTNAME"
>cyg_pci_device structure</SPAN
> (defined in
<TT
CLASS="FILENAME"
>pci.h</TT
>) primarily holds information as described by the PCI
specification <A
HREF="ecos-pci-library.html#PCI-SPEC"
>[1]</A
>.
The <TT
CLASS="FILENAME"
>pci1</TT
> test prints out some of this information:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
> // Get device info
cyg_pci_get_device_info(devid, &dev_info);
diag_printf("\n Command 0x%04x, Status 0x%04x\n",
dev_info.command, dev_info.status);</PRE
></TD
></TR
></TABLE
><P
>The command register can also be written to, controlling (among
other things) whether the device responds to IO and memory access
from the bus. </P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN12737">Specific config information</H2
><P
>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:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="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);</PRE
></TD
></TR
></TABLE
><P
>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.</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN12742">Allocating memory</H2
><P
>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::</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="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 );</PRE
></TD
></TR
></TABLE
><P
>The <TT
CLASS="FUNCTION"
>cyg_pci_configure_device</TT
> handles all IO
and memory regions that need configuration on non-bridge devices. On
platforms with multiple busses connected by bridges, the <TT
CLASS="FUNCTION"
>cyg_pci_configure_bus</TT
> function should be used. It will recursively
configure all devices on the given <TT
CLASS="PARAMETER"
><I
>bus</I
></TT
> and all
subordinate busses. <TT
CLASS="FUNCTION"
>cyg_pci_configure_bus</TT
> will
use <TT
CLASS="FUNCTION"
>cyg_pci_configure_device</TT
> to configure
individual non-bridge devices.</P
><P
> 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:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="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,
CYG_PCI_ADDRESS32 *base );</PRE
></TD
></TR
></TABLE
><P
>The memory bases (in two distinct address spaces) are increased
as memory regions are allocated to devices. Allocation will fail
(the function returns false) if the base exceeds the limits of the
address space (IO is 1MB, memory is 2^32 or 2^64 bytes).</P
><P
>These functions can also be called directly by the application/driver
if necessary, but this should not be necessary.</P
><P
>The bases are initialized with default values provided by
the HAL. It is possible for an application to override these using
the following functions: </P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>void cyg_pci_set_memory_base( CYG_PCI_ADDRESS64 base );
void cyg_pci_set_io_base( CYG_PCI_ADDRESS32 base );</PRE
></TD
></TR
></TABLE
><P
>When a device has been configured, the cyg_pci_device
structure will contain the physical address in the CPU's
address space where the device's memory regions can be
accessed. </P
><P
>This information is provided in <TT
CLASS="VARNAME"
>base_map[]</TT
> -
there is a 32 bit word for each of the device's BARs. For
32 bit PCI memory regions, each 32 bit word will be an actual pointer
that can be used immediately by the driver: the memory space will normally
be linearly addressable by the CPU.</P
><P
>However, for 64 bit PCI memory regions, some (or all) of the
region may be outside of the CPUs address space. In this case the
driver will need to know how to access the region in segments. This
functionality may be adopted by the eCos HAL if deemed useful in
the future. The 2GB available on many systems should suffice though.</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="PCI-INTERRUPTS">Interrupts</H2
><P
>A device may generate interrupts. The HAL vector associated
with a given device on the bus is platform specific. This function
allows a driver to find the actual interrupt vector for a given
device:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>cyg_bool cyg_pci_translate_interrupt( cyg_pci_device *dev_info,
CYG_ADDRWORD *vec );</PRE
></TD
></TR
></TABLE
><P
>If the function returns false, no interrupts will be generated
by the device. If it returns true, the CYG_ADDRWORD pointed
to by vec is updated with the HAL interrupt vector the device will
be using. This is how the function is used in the <TT
CLASS="FILENAME"
>pci1</TT
>
test:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
> if (cyg_pci_translate_interrupt(&dev_info, &irq))
diag_printf(" Wired to HAL vector %d\n", irq);
else
diag_printf(" Does not generate interrupts.\n");</PRE
></TD
></TR
></TABLE
><P
>The application/drive should attach an interrupt
handler to a device's interrupt before activating the device.</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN12770">Activating a device</H2
><P
>When the device has been allocated memory space it can be
activated. This is not done by the library since a driver may have
to initialize more state on the device before it can be safely activated.</P
><P
>Activating the device is done by enabling flags in its command
word. As an example, see the <TT
CLASS="FILENAME"
>pci1</TT
> test which can be
configured to enable the devices it finds. This allows these to be accessed from
GDB (if a breakpoint is set on <TT
CLASS="FUNCTION"
>cyg_test_exit</TT
>):</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>#ifdef ENABLE_PCI_DEVICES
{
cyg_uint16 cmd;
// Don't use cyg_pci_set_device_info since it clears
// some of the fields we want to print out below.
cyg_pci_read_config_uint16(dev_info.devid,
CYG_PCI_CFG_COMMAND, &cmd);
cmd |= CYG_PCI_CFG_COMMAND_IO|CYG_PCI_CFG_COMMAND_MEMORY;
cyg_pci_write_config_uint16(dev_info.devid,
CYG_PCI_CFG_COMMAND, cmd);
}
diag_printf(" **** Device IO and MEM access enabled\n");
#endif</PRE
></TD
></TR
></TABLE
><DIV
CLASS="NOTE"
><BLOCKQUOTE
CLASS="NOTE"
><P
><B
>Note: </B
>The best way to activate a device is actually
through <TT
CLASS="FUNCTION"
>cyg_pci_set_device_info()</TT
>,
but in this particular case the <SPAN
CLASS="STRUCTNAME"
>cyg_pci_device</SPAN
>
structure contents from before the activation is required for printout
further down in the code.</P
></BLOCKQUOTE
></DIV
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN12782">Links</H2
><P
>See these links for more information about PCI:</P
><P
></P
><OL
TYPE="1"
><LI
><P
><A
NAME="PCI-SPEC"
></A
><A
HREF="http://www.pcisig.com/"
TARGET="_top"
>http://www.pcisig.com/</A
> - information on the PCI specifications</P
></LI
><LI
><P
><A
HREF="http://www.yourvote.com/pci/"
TARGET="_top"
>http://www.yourvote.com/pci/</A
> - list of vendor and device IDs</P
></LI
><LI
><P
><A
HREF="http://www.picmg.org/"
TARGET="_top"
>http://www.picmg.org/</A
> - PCI Industrial Computer Manufacturers Group</P
></LI
></OL
></DIV
></DIV
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="io-pci.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="ecos-ref.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="pci-library-reference.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>PCI Library</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="io-pci.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>PCI Library reference</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>