1 <!-- Copyright (C) 2003 Red Hat, Inc. -->
2 <!-- This material may be distributed only subject to the terms -->
3 <!-- and conditions set forth in the Open Publication License, v1.0 -->
4 <!-- or later (the latest version is presently available at -->
5 <!-- http://www.opencontent.org/openpub/). -->
6 <!-- Distribution of the work or derivative of the work in any -->
7 <!-- standard (paper) book form is prohibited unless prior -->
8 <!-- permission is obtained from the copyright holder. -->
12 >The eCos PCI Library</TITLE
13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
19 TITLE="eCos Reference Manual"
20 HREF="ecos-ref.html"><LINK
23 HREF="io-pci.html"><LINK
26 HREF="io-pci.html"><LINK
28 TITLE="PCI Library reference"
29 HREF="pci-library-reference.html"></HEAD
40 SUMMARY="Header navigation table"
49 >eCos Reference Manual</TH
71 HREF="pci-library-reference.html"
84 NAME="ECOS-PCI-LIBRARY">Chapter 30. The eCos PCI Library</H1
94 HREF="ecos-pci-library.html#PCI-LIBRARY"
99 HREF="pci-library-reference.html"
100 >PCI Library reference</A
105 >The PCI library is an optional part of eCos, and is only
106 applicable to some platforms.</P
112 NAME="PCI-LIBRARY">PCI Library</H1
114 >The eCos PCI library provides the following functionality:</P
121 >Scan the PCI bus for specific devices or devices of a certain
126 >Read and change generic PCI information.</P
130 >Read and change device-specific PCI information.</P
134 >Allocate PCI memory and IO space to devices.</P
138 >Translate a device's PCI interrupts to equivalent HAL
143 >Example code fragments are from the pci1 test (see <TT
145 >io/pci/<release>/tests/pci1.c</TT
148 >All of the functions described below are declared in the header
151 ><cyg/io/pci.h></TT
153 clients of the PCI library should include.</P
159 NAME="AEN12691">PCI Overview</H2
161 >The PCI bus supports several address spaces: memory, IO, and configuration. All PCI
162 devices must support mandatory configuration space registers. Some devices may also present
163 IO mapped and/or memory mapped resources. Before devices on the bus can be used, they must
164 be configured. Basically, configuration will assign PCI IO and/or memory address ranges to
165 each device and then enable that device. All PCI devices have a unique address in
166 configuration space. This address is comprised of a bus number, a device number, and a
167 function number. Special devices called bridges are used to connect two PCI busses together.
168 The PCI standard supports up to 255 busses with each bus having up to 32 devices and each
169 device having up to 8 functions.</P
171 >The environment in which a platform operates will dictate if and how eCos should
172 configure devices on the PCI bus. If the platform acts as a host on a single PCI bus,
173 then devices may be configured individually from the relevant device driver. If the
174 platform is not the primary host, such as a PCI card plugged into a PC, configuration
175 of PCI devices may be left to the PC BIOS. If PCI-PCI bridges are involved, configuration
176 of all devices is best done all at once early in the boot process. This is because all
177 devices on the secondary side of a bridge must be evaluated for their IO and memory space
178 requirements before the bridge can be configured.</P
185 NAME="AEN12695">Initializing the bus</H2
187 >The PCI bus needs to be initialized before it can be used.
188 This only needs to be done once - some HALs may do it as part of
189 the platform initialization procedure, other HALs may leave it to
190 the application or device drivers to do it. The following function
191 will do the initialization only once, so it's safe to call from
200 CLASS="PROGRAMLISTING"
201 >void cyg_pci_init( void );</PRE
211 NAME="AEN12699">Scanning for devices</H2
213 >After the bus has been initialized, it is possible to scan
214 it for devices. This is done using the function:</P
222 CLASS="PROGRAMLISTING"
223 >cyg_bool cyg_pci_find_next( cyg_pci_device_id cur_devid,
224 cyg_pci_device_id *next_devid );</PRE
229 >It will scan the bus for devices starting at <TT
234 >. If a device is found, its devid is stored in <TT
239 > and the function returns <TT
247 > test's outer loop looks like:</P
255 CLASS="PROGRAMLISTING"
257 if (cyg_pci_find_next(CYG_PCI_NULL_DEVID, &devid)) {
260 } while (cyg_pci_find_next(devid, &devid));
266 >What happens is that the bus gets initialized and a scan is
269 >CYG_PCI_NULL_DEVID</TT
272 >cyg_pci_find_next()</TT
273 > to restart its scan. If the bus does not
274 contain any devices, the first call to <TT
276 >cyg_pci_find_next()</TT
283 >If the call returns <TT
286 >, a loop is entered where
287 the found devid is used. After devid processing has completed, the next device
288 on the bus is searched for; <TT
290 >cyg_pci_find_next()</TT
292 continues its scan from the current devid. The loop terminates when
293 no more devices are found on the bus.</P
295 >This is the generic way of scanning the bus, enumerating all
296 the devices on the bus. But if the application is looking for a
297 device of a given device class (e.g., a SCSI controller), or a specific
298 vendor device, these functions simplify the task a bit:</P
306 CLASS="PROGRAMLISTING"
307 >cyg_bool cyg_pci_find_class( cyg_uint32 dev_class,
308 cyg_pci_device_id *devid );
309 cyg_bool cyg_pci_find_device( cyg_uint16 vendor, cyg_uint16 device,
310 cyg_pci_device_id *devid );</PRE
315 >They work just like <TT
317 >cyg_pci_find_next()</TT
319 but only return true when the dev_class or vendor/device
320 qualifiers match those of a device on the bus. The devid serves
321 as both an input and an output operand: the scan starts at the given
322 device, and if a device is found devid is updated with the value
323 for the found device.</P
327 ><cyg/io/pci_cfg.h></TT
329 file (included by <TT
332 >) contains definitions for PCI
333 class, vendor and device codes which can be used as arguments to the find
335 The list of vendor and device codes is not complete: add new codes
336 as necessary. If possible also register the codes at the PCI Code
338 HREF="http://www.yourvote.com/pci"
340 >http://www.yourvote.com/pci)</A
341 > which is where the eCos definitions are generated from.</P
348 NAME="AEN12726">Generic config information</H2
350 >When a valid device ID (devid) is found using one of the above
351 functions, the associated device can be queried and controlled using
360 CLASS="PROGRAMLISTING"
361 >void cyg_pci_get_device_info ( cyg_pci_device_id devid,
362 cyg_pci_device *dev_info );
363 void cyg_pci_set_device_info ( cyg_pci_device_id devid,
364 cyg_pci_device *dev_info );</PRE
371 >cyg_pci_device structure</SPAN
376 >) primarily holds information as described by the PCI
378 HREF="ecos-pci-library.html#PCI-SPEC"
384 > test prints out some of this information:</P
392 CLASS="PROGRAMLISTING"
394 cyg_pci_get_device_info(devid, &dev_info);
395 diag_printf("\n Command 0x%04x, Status 0x%04x\n",
396 dev_info.command, dev_info.status);</PRE
401 >The command register can also be written to, controlling (among
402 other things) whether the device responds to IO and memory access
410 NAME="AEN12737">Specific config information</H2
412 >The above functions only allow access to generic PCI config
413 registers. A device can have extra config registers not specified
414 by the PCI specification. These can be accessed with these functions:</P
422 CLASS="PROGRAMLISTING"
423 >void cyg_pci_read_config_uint8( cyg_pci_device_id devid,
424 cyg_uint8 offset, cyg_uint8 *val);
425 void cyg_pci_read_config_uint16( cyg_pci_device_id devid,
426 cyg_uint8 offset, cyg_uint16 *val);
427 void cyg_pci_read_config_uint32( cyg_pci_device_id devid,
428 cyg_uint8 offset, cyg_uint32 *val);
429 void cyg_pci_write_config_uint8( cyg_pci_device_id devid,
430 cyg_uint8 offset, cyg_uint8 val);
431 void cyg_pci_write_config_uint16( cyg_pci_device_id devid,
432 cyg_uint8 offset, cyg_uint16 val);
433 void cyg_pci_write_config_uint32( cyg_pci_device_id devid,
434 cyg_uint8 offset, cyg_uint32 val);</PRE
439 >The write functions should only be used for device-specific
440 config registers since using them on generic registers may invalidate
441 the contents of a previously fetched cyg_pci_device
449 NAME="AEN12742">Allocating memory</H2
451 >A PCI device ignores all IO and memory access from the PCI
452 bus until it has been activated. Activation cannot happen until
453 after device configuration. Configuration means telling the device
454 where it should map its IO and memory resources. This is done with
455 one of the following functions::</P
463 CLASS="PROGRAMLISTING"
464 >cyg_bool cyg_pci_configure_device( cyg_pci_device *dev_info );
465 cyg_bool cyg_pci_configure_bus( cyg_uint8 bus, cyg_uint8 *next_bus );</PRE
472 >cyg_pci_configure_device</TT
474 and memory regions that need configuration on non-bridge devices. On
475 platforms with multiple busses connected by bridges, the <TT
477 >cyg_pci_configure_bus</TT
478 > function should be used. It will recursively
479 configure all devices on the given <TT
485 subordinate busses. <TT
487 >cyg_pci_configure_bus</TT
491 >cyg_pci_configure_device</TT
493 individual non-bridge devices.</P
495 > Each region is represented in the PCI device's config space by BARs
496 (Base Address Registers) and is handled individually according to type
497 using these functions:</P
505 CLASS="PROGRAMLISTING"
506 >cyg_bool cyg_pci_allocate_memory( cyg_pci_device *dev_info,
508 CYG_PCI_ADDRESS64 *base );
509 cyg_bool cyg_pci_allocate_io( cyg_pci_device *dev_info,
511 CYG_PCI_ADDRESS32 *base );</PRE
516 >The memory bases (in two distinct address spaces) are increased
517 as memory regions are allocated to devices. Allocation will fail
518 (the function returns false) if the base exceeds the limits of the
519 address space (IO is 1MB, memory is 2^32 or 2^64 bytes).</P
521 >These functions can also be called directly by the application/driver
522 if necessary, but this should not be necessary.</P
524 >The bases are initialized with default values provided by
525 the HAL. It is possible for an application to override these using
526 the following functions: </P
534 CLASS="PROGRAMLISTING"
535 >void cyg_pci_set_memory_base( CYG_PCI_ADDRESS64 base );
536 void cyg_pci_set_io_base( CYG_PCI_ADDRESS32 base );</PRE
541 >When a device has been configured, the cyg_pci_device
542 structure will contain the physical address in the CPU's
543 address space where the device's memory regions can be
546 >This information is provided in <TT
550 there is a 32 bit word for each of the device's BARs. For
551 32 bit PCI memory regions, each 32 bit word will be an actual pointer
552 that can be used immediately by the driver: the memory space will normally
553 be linearly addressable by the CPU.</P
555 >However, for 64 bit PCI memory regions, some (or all) of the
556 region may be outside of the CPUs address space. In this case the
557 driver will need to know how to access the region in segments. This
558 functionality may be adopted by the eCos HAL if deemed useful in
559 the future. The 2GB available on many systems should suffice though.</P
566 NAME="PCI-INTERRUPTS">Interrupts</H2
568 >A device may generate interrupts. The HAL vector associated
569 with a given device on the bus is platform specific. This function
570 allows a driver to find the actual interrupt vector for a given
579 CLASS="PROGRAMLISTING"
580 >cyg_bool cyg_pci_translate_interrupt( cyg_pci_device *dev_info,
581 CYG_ADDRWORD *vec );</PRE
586 >If the function returns false, no interrupts will be generated
587 by the device. If it returns true, the CYG_ADDRWORD pointed
588 to by vec is updated with the HAL interrupt vector the device will
589 be using. This is how the function is used in the <TT
601 CLASS="PROGRAMLISTING"
602 > if (cyg_pci_translate_interrupt(&dev_info, &irq))
603 diag_printf(" Wired to HAL vector %d\n", irq);
605 diag_printf(" Does not generate interrupts.\n");</PRE
610 >The application/drive should attach an interrupt
611 handler to a device's interrupt before activating the device.</P
618 NAME="AEN12770">Activating a device</H2
620 >When the device has been allocated memory space it can be
621 activated. This is not done by the library since a driver may have
622 to initialize more state on the device before it can be safely activated.</P
624 >Activating the device is done by enabling flags in its command
625 word. As an example, see the <TT
629 configured to enable the devices it finds. This allows these to be accessed from
630 GDB (if a breakpoint is set on <TT
641 CLASS="PROGRAMLISTING"
642 >#ifdef ENABLE_PCI_DEVICES
646 // Don't use cyg_pci_set_device_info since it clears
647 // some of the fields we want to print out below.
648 cyg_pci_read_config_uint16(dev_info.devid,
649 CYG_PCI_CFG_COMMAND, &cmd);
650 cmd |= CYG_PCI_CFG_COMMAND_IO|CYG_PCI_CFG_COMMAND_MEMORY;
651 cyg_pci_write_config_uint16(dev_info.devid,
652 CYG_PCI_CFG_COMMAND, cmd);
654 diag_printf(" **** Device IO and MEM access enabled\n");
666 >The best way to activate a device is actually
669 >cyg_pci_set_device_info()</TT
671 but in this particular case the <SPAN
673 >cyg_pci_device</SPAN
675 structure contents from before the activation is required for printout
676 further down in the code.</P
685 NAME="AEN12782">Links</H2
687 >See these links for more information about PCI:</P
698 HREF="http://www.pcisig.com/"
700 >http://www.pcisig.com/</A
701 > - information on the PCI specifications</P
706 HREF="http://www.yourvote.com/pci/"
708 >http://www.yourvote.com/pci/</A
709 > - list of vendor and device IDs</P
714 HREF="http://www.picmg.org/"
716 >http://www.picmg.org/</A
717 > - PCI Industrial Computer Manufacturers Group</P
728 SUMMARY="Footer navigation table"
757 HREF="pci-library-reference.html"
781 >PCI Library reference</TD