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 >PCI Library reference</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
22 TITLE="The eCos PCI Library"
23 HREF="ecos-pci-library.html"><LINK
25 TITLE="The eCos PCI Library"
26 HREF="ecos-pci-library.html"><LINK
28 TITLE="eCos POSIX compatibility layer"
29 HREF="posix-compatibility.html"></HEAD
40 SUMMARY="Header navigation table"
49 >eCos Reference Manual</TH
57 HREF="ecos-pci-library.html"
65 >Chapter 30. The eCos PCI Library</TD
71 HREF="posix-compatibility.html"
85 NAME="PCI-LIBRARY-REFERENCE">PCI Library reference</H1
87 >This document defines the PCI Support Library for eCos.</P
89 >The PCI support library provides a set of routines for accessing
90 the PCI bus configuration space in a portable manner. This is provided
91 by two APIs. The high level API is used by device drivers, or other
92 code, to access the PCI configuration space portably. The low level
93 API is used by the PCI library itself to access the hardware in
94 a platform-specific manner, and may also be used by device drivers
95 to access the PCI configuration space directly.</P
97 >Underlying the low-level API is HAL support for the basic
98 configuration space operations. These should not generally be used
99 by any code other than the PCI library, and are present in the HAL
100 to allow low level initialization of the PCI bus and devices to
101 take place if necessary.</P
107 NAME="AEN12801">PCI Library API</H2
109 >The PCI library provides the following routines and types
110 for accessing the PCI configuration space.</P
112 >The API for the PCI library is found in the header file
115 ><cyg/io/pci.h></TT
123 NAME="AEN12806">Definitions</H2
125 >The header file contains definitions for the common configuration
126 structure offsets and specimen values for device, vendor and class
134 NAME="AEN12809">Types and data structures</H2
136 >The following types are defined:</P
144 CLASS="PROGRAMLISTING"
145 >typedef CYG_WORD32 cyg_pci_device_id;</PRE
150 >This is comprised of the bus number, device number and functional
151 unit numbers packed into a single word. The macro <TT
153 >CYG_PCI_DEV_MAKE_ID()</TT
154 >, in conjunction with the <TT
156 >CYG_PCI_DEV_MAKE_DEVFN()</TT
158 macro, may be used to construct a device id from the bus, device and functional
159 unit numbers. Similarly the macros <TT
161 >CYG_PCI_DEV_GET_BUS()</TT
165 >CYG_PCI_DEV_GET_DEVFN()</TT
169 >CYG_PCI_DEV_GET_DEV()</TT
173 >CYG_PCI_DEV_GET_FN()</TT
174 > may be used to extract the
175 constituent parts of a device id. It should not be necessary to use these
176 macros under normal circumstances. The following code fragment demonstrates
177 how these macros may be used:</P
185 CLASS="PROGRAMLISTING"
186 > // Create a packed representation of device 1, function 0
187 cyg_uint8 devfn = CYG_PCI_DEV_MAKE_DEVFN(1,0);
189 // Create a packed devid for that device on bus 2
190 cyg_pci_device_id devid = CYG_PCI_DEV_MAKE_ID(2, devfn);
192 diag_printf("bus %d, dev %d, func %d\n",
193 CYG_PCI_DEV_GET_BUS(devid),
194 CYG_PCI_DEV_GET_DEV(CYG_PCI_DEV_GET_DEVFN(devid)),
195 CYG_PCI_DEV_GET_FN(CYG_PCI_DEV_GET_DEVFN(devid));</PRE
206 CLASS="PROGRAMLISTING"
207 >typedef struct cyg_pci_device;</PRE
212 >This structure is used to contain data read from a PCI device's
213 configuration header by <TT
215 >cyg_pci_get_device_info()</TT
217 It is also used to record the resource allocations made to the device.</P
225 CLASS="PROGRAMLISTING"
226 >typedef CYG_WORD64 CYG_PCI_ADDRESS64;
227 typedef CYG_WORD32 CYG_PCI_ADDRESS32;</PRE
232 >Pointers in the PCI address space are 32 bit (IO space) or
233 32/64 bit (memory space). In most platform and device configurations
234 all of PCI memory will be linearly addressable using only 32 bit
235 pointers as read from <TT
240 >The 64 bit type is used to allow handling 64 bit devices in
241 the future, should it be necessary, without changing the library's
249 NAME="AEN12828">Functions</H2
257 CLASS="PROGRAMLISTING"
258 >void cyg_pci_init(void);</PRE
263 >Initialize the PCI library and establish contact with the
264 hardware. This function is idempotent and can be called either by
265 all drivers in the system, or just from an application initialization
274 CLASS="PROGRAMLISTING"
275 >cyg_bool cyg_pci_find_device( cyg_uint16 vendor,
277 cyg_pci_device_id *devid );</PRE
282 >Searches the PCI bus configuration space for a device with
294 ids. The search starts at the device pointed to by <TT
300 or at the first slot if it contains <TT
302 >CYG_PCI_NULL_DEVID</TT
309 > will be updated with the ID of the next device
313 > if one is found and <TT
324 CLASS="PROGRAMLISTING"
325 >cyg_bool cyg_pci_find_class( cyg_uint32 dev_class,
326 cyg_pci_device_id *devid );</PRE
331 >Searches the PCI bus configuration space for a device with
337 > class code. The search starts at the
338 device pointed to by <TT
343 >, or at the first slot if it
346 >CYG_PCI_NULL_DEVID</TT
354 > will be updated with the ID of the next
355 device found. Returns <TT
358 > if one is found and
370 CLASS="PROGRAMLISTING"
371 >cyg_bool cyg_pci_find_next( cyg_pci_device_id cur_devid,
372 cyg_pci_device_id *next_devid );</PRE
377 >Searches the PCI configuration space for the next valid device
389 is given the value <TT
391 >CYG_PCI_NULL_DEVID</TT
392 >, then the search starts
393 at the first slot. It is permitted for <TT
408 if another device is found and <TT
419 CLASS="PROGRAMLISTING"
420 >cyg_bool cyg_pci_find_matching( cyg_pci_match_func *matchp,
421 void * match_callback_data,
422 cyg_pci_device_id *devid );</PRE
427 >Searches the PCI bus configuration space for a device whose properties
428 match those required by the caller supplied <TT
431 >cyg_pci_match_func</I
434 The search starts at the device pointed to by <TT
440 at the first slot if it contains <TT
442 >CYG_PCI_NULL_DEVID</TT
449 > will be updated with the ID of the next device found.
450 This function returns <TT
453 > if a matching device is found
459 >The match_func has a type declared as:</P
467 CLASS="PROGRAMLISTING"
468 >typedef cyg_bool (cyg_pci_match_func)( cyg_uint16 vendor,
471 void * user_data);</PRE
492 > are from the device configuration space. The
498 > is the callback data passed to <TT
500 >cyg_pci_find_matching</TT
509 CLASS="PROGRAMLISTING"
510 >void cyg_pci_get_device_info ( cyg_pci_device_id devid,
511 cyg_pci_device *dev_info );</PRE
516 >This function gets the PCI configuration information for the
517 device indicated in <TT
522 >. The common fields of the
525 >cyg_pci_device</SPAN
526 > structure, and the appropriate fields
527 of the relevant header union member are filled in from the device's
529 If the device has not been enabled, then this function will also fetch
530 the size and type information from the base address registers and
542 CLASS="PROGRAMLISTING"
543 >void cyg_pci_set_device_info ( cyg_pci_device_id devid,
544 cyg_pci_device *dev_info );</PRE
549 >This function sets the PCI configuration information for the
550 device indicated in <TT
555 >. Only the configuration space
556 registers that are writable are actually written. Once all the fields have
557 been written, the device info will be read back into <TT
562 >, so that it reflects the true state of the hardware.</P
570 CLASS="PROGRAMLISTING"
571 >void cyg_pci_read_config_uint8( cyg_pci_device_id devid,
572 cyg_uint8 offset, cyg_uint8 *val );
573 void cyg_pci_read_config_uint16( cyg_pci_device_id devid,
574 cyg_uint8 offset, cyg_uint16 *val );
575 void cyg_pci_read_config_uint32( cyg_pci_device_id devid,
576 cyg_uint8 offset, cyg_uint32 *val );</PRE
581 >These functions read registers of the appropriate size from
582 the configuration space of the given device. They should mainly
583 be used to access registers that are device specific. General PCI
584 registers are best accessed through <TT
586 >cyg_pci_get_device_info()</TT
595 CLASS="PROGRAMLISTING"
596 >void cyg_pci_write_config_uint8( cyg_pci_device_id devid,
597 cyg_uint8 offset, cyg_uint8 val );
598 void cyg_pci_write_config_uint16( cyg_pci_device_id devid,
599 cyg_uint8 offset, cyg_uint16 val );
600 void cyg_pci_write_config_uint32( cyg_pci_device_id devid,
601 cyg_uint8 offset, cyg_uint32 val );</PRE
606 >These functions write registers of the appropriate size to
607 the configuration space of the given device. They should mainly
608 be used to access registers that are device specific. General PCI
609 registers are best accessed through <TT
611 >cyg_pci_get_device_info()</TT
612 >. Writing the general registers this way may render the contents of
615 >cyg_pci_device</SPAN
616 > structure invalid.</P
623 NAME="AEN12891">Resource allocation</H2
625 >These routines allocate memory and I/O space to PCI devices.</P
633 CLASS="PROGRAMLISTING"
634 >cyg_bool cyg_pci_configure_device( cyg_pci_device *dev_info )</PRE
639 >Allocate memory and IO space to all base address registers
640 using the current memory and IO base addresses in the library. The
641 allocated base addresses, translated into directly usable values,
642 will be put into the matching <TT
657 not contain valid <TT
660 > entries, then the result is
664 >. This function will also call <TT
666 >cyg_pci_translate_interrupt()</TT
667 > to put the interrupt vector into the
676 CLASS="PROGRAMLISTING"
677 >cyg_bool cyg_pci_configure_bus( cyg_uint8 bus, cyg_uint8 *next_bus )</PRE
682 >Allocate memory and IO space to all base address registers on all devices
683 on the given bus and all subordinate busses. If a PCI-PCI bridge is found on
689 >, this function will call itself recursively in order
690 to configure the bus on the other side of the bridge. Because of the nature of
691 bridge devices, all devices on the secondary side of a bridge must be allocated
692 memory and IO space before the memory and IO windows on the bridge device can be
693 properly configured. The <TT
698 > argument points to the
699 bus number to assign to the next subordinate bus found. The number will be
700 incremented as new busses are discovered. If successful, <TT
704 is returned. Otherwise, <TT
715 CLASS="PROGRAMLISTING"
716 >cyg_bool cyg_pci_translate_interrupt( cyg_pci_device *dev_info,
717 CYG_ADDRWORD *vec );</PRE
722 >Translate the device's PCI interrupt (INTA#-INTD#)
723 to the associated HAL vector. This may also depend on which slot
724 the device occupies. If the device may generate interrupts, the
725 translated vector number will be stored in <TT
734 >. Otherwise the result is <TT
745 CLASS="PROGRAMLISTING"
746 >cyg_bool cyg_pci_allocate_memory( cyg_pci_device *dev_info,
748 CYG_PCI_ADDRESS64 *base );
749 cyg_bool cyg_pci_allocate_io( cyg_pci_device *dev_info,
751 CYG_PCI_ADDRESS32 *base );</PRE
756 >These routines allocate memory or I/O space to the base address
757 register indicated by <TT
762 >. The base address in
768 > will be correctly aligned and the address of the
769 next free location will be written back into it if the allocation succeeds. If
770 the base address register is of the wrong type for this allocation, or
776 > does not contain valid <TT
779 > entries, the result is <TT
783 allow a device driver to set up its own mappings if it wants. Most devices
784 should probably use <TT
786 >cyg_pci_configure_device()</TT
795 CLASS="PROGRAMLISTING"
796 >void cyg_pci_set_memory_base( CYG_PCI_ADDRESS64 base );
797 void cyg_pci_set_io_base( CYG_PCI_ADDRESS32 base );</PRE
802 >These routines set the base addresses for memory and I/O mappings
803 to be used by the memory allocation routines. Normally these base
804 addresses will be set to default values based on the platform. These
805 routines allow these to be changed by application code if necessary.</P
812 NAME="AEN12923">PCI Library Hardware API</H2
814 >This API is used by the PCI library to access the PCI bus
815 configuration space. Although it should not normally be necessary,
816 this API may also be used by device driver or application code to
817 perform PCI bus operations not supported by the PCI library.</P
825 CLASS="PROGRAMLISTING"
826 >void cyg_pcihw_init(void);</PRE
831 >Initialize the PCI hardware so that the configuration space
840 CLASS="PROGRAMLISTING"
841 >void cyg_pcihw_read_config_uint8( cyg_uint8 bus,
842 cyg_uint8 devfn, cyg_uint8 offset, cyg_uint8 *val);
843 void cyg_pcihw_read_config_uint16( cyg_uint8 bus,
844 cyg_uint8 devfn, cyg_uint8 offset, cyg_uint16 *val);
845 void cyg_pcihw_read_config_uint32( cyg_uint8 bus,
846 cyg_uint8 devfn, cyg_uint8 offset, cyg_uint32 *val);</PRE
851 >These functions read a register of the appropriate size from
852 the PCI configuration space at an address composed from the <TT
876 CLASS="PROGRAMLISTING"
877 >void cyg_pcihw_write_config_uint8( cyg_uint8 bus,
878 cyg_uint8 devfn, cyg_uint8 offset, cyg_uint8 val);
879 void cyg_pcihw_write_config_uint16( cyg_uint8 bus,
880 cyg_uint8 devfn, cyg_uint8 offset, cyg_uint16 val);
881 void cyg_pcihw_write_config_uint32( cyg_uint8 bus,
882 cyg_uint8 devfn, cyg_uint8 offset, cyg_uint32 val);</PRE
887 >These functions write a register of the appropriate size to
888 the PCI configuration space at an address composed from the
913 CLASS="PROGRAMLISTING"
914 >cyg_bool cyg_pcihw_translate_interrupt( cyg_uint8 bus,
916 CYG_ADDRWORD *vec);</PRE
921 >This function interrogates the device and determines which
922 HAL interrupt vector it is connected to.</P
929 NAME="AEN12940">HAL PCI support</H2
931 >HAL support consists of a set of C macros that provide the
932 implementation of the low level PCI API.</P
940 CLASS="PROGRAMLISTING"
946 >Initialize the PCI bus.</P
954 CLASS="PROGRAMLISTING"
955 >HAL_PCI_READ_UINT8( bus, devfn, offset, val )
956 HAL_PCI_READ_UINT16( bus, devfn, offset, val )
957 HAL_PCI_READ_UINT32( bus, devfn, offset, val )</PRE
962 >Read a value from the PCI configuration space of the appropriate
963 size at an address composed from the <TT
986 CLASS="PROGRAMLISTING"
987 >HAL_PCI_WRITE_UINT8( bus, devfn, offset, val )
988 HAL_PCI_WRITE_UINT16( bus, devfn, offset, val )
989 HAL_PCI_WRITE_UINT32( bus, devfn, offset, val )</PRE
994 >Write a value to the PCI configuration space of the appropriate
995 size at an address composed from the <TT
1018 CLASS="PROGRAMLISTING"
1019 >HAL_PCI_TRANSLATE_INTERRUPT( bus, devfn, *vec, valid )</PRE
1024 >Translate the device's interrupt line into a HAL
1025 interrupt vector.</P
1033 CLASS="PROGRAMLISTING"
1034 >HAL_PCI_ALLOC_BASE_MEMORY
1035 HAL_PCI_ALLOC_BASE_IO</PRE
1040 >These macros define the default base addresses used to initialize
1041 the memory and I/O allocation pointers.</P
1049 CLASS="PROGRAMLISTING"
1050 >HAL_PCI_PHYSICAL_MEMORY_BASE
1051 HAL_PCI_PHYSICAL_IO_BASE</PRE
1056 >PCI memory and IO range do not always correspond directly
1057 to physical memory or IO addresses. Frequently the PCI address spaces
1058 are windowed into the processor's address range at some
1059 offset. These macros define offsets to be added to the PCI base
1060 addresses to translate PCI bus addresses into physical memory addresses
1061 that can be used to access the allocated memory or IO space.</P
1069 >The chunk of PCI memory space directly addressable though
1070 the window by the CPU may be smaller than the amount of PCI memory
1071 actually provided. In that case drivers will have to access PCI
1072 memory space in segments. Doing this will be platform specific and
1073 is currently beyond the scope of the HAL.</P
1083 CLASS="PROGRAMLISTING"
1084 >HAL_PCI_IGNORE_DEVICE( bus, dev, fn )</PRE
1089 >This macro, if defined, may be used to limit the devices which are
1090 found by the bus scanning functions. This is sometimes necessary for
1091 devices which need special handling. If this macro evaluates to <TT
1094 >, the given device will not be found by <TT
1096 >cyg_pci_find_next</TT
1097 > or other bus scanning functions.</P
1105 SUMMARY="Footer navigation table"
1116 HREF="ecos-pci-library.html"
1125 HREF="ecos-ref.html"
1134 HREF="posix-compatibility.html"
1144 >The eCos PCI Library</TD
1150 HREF="ecos-pci-library.html"
1158 >eCos POSIX compatibility layer</TD