This package contains the PCI Utilities, version @VERSION@.

Copyright (c) 1997--2024 Martin Mares <[email protected]>

All files in this package can be freely distributed and used according
to the terms of the GNU General Public License, either version 2 or
(at your opinion) any newer version. See https://www.gnu.org/ for details.

The author wants to clarify that he does not consider programs which link
dynamically to the libpci to be derived works of the library.


1. What's that?
~~~~~~~~~~~~~~~
The PCI Utilities package contains a library for portable access to PCI bus
configuration registers and several utilities based on this library.

In runs on the following systems:

	Linux		(via /sys/bus/pci, /proc/bus/pci or i386 ports)
	FreeBSD		(via /dev/pci)
	NetBSD		(via libpci)
	OpenBSD		(via /dev/pci or i386 ports)
	GNU/kFreeBSD	(via /dev/pci)
	Solaris/i386	(direct port access)
	Aix		(via /dev/pci and odmget)
	GNU Hurd	(direct port access)
	Windows		(via cfgmgr32 or direct port access, see README.Windows for caveats)
	CYGWIN		(direct port access)
	BeOS		(via syscalls)
	Haiku		(via /dev/misc/poke)
	Darwin		(via IOKit)
	DOS/DJGPP	(via i386 ports)
	SylixOS		(via /proc/pci)
	AmigaOS on PPC	(via Expansion library)

It should be very easy to add support for other systems as well (volunteers
wanted; if you want to try that, I'll be very glad to see the patches and
include them in the next version).

The utilities include:  (See manual pages for more details)

  - lspci: displays detailed information about all PCI buses and devices.

  - setpci: allows to read from and write to PCI device configuration
    registers. For example, you can adjust the latency timers with it.
    CAUTION: There is a couple of dangerous points and caveats, please read
    the manual page first!

  - update-pciids: download the current version of the pci.ids file.

  - pcilmr: performs margining on PCIe links.


2. Compiling and (un)installing
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Just run "make" to compile the package and then "make install" to install it.
Please note that a C compiler supporting the C99 standard is required.
Also, GNU make is needed on most platforms.

If you want to change the default installation location, please override
the PREFIX variable specified in the Makefile -- e.g., you can use
"make PREFIX=/opt/pciutils install" to create a separate installation
not interfering with the rest of your system.  Setting the DESTDIR variable
will allow you to install to a different directory from the one you intend
to eventually run it from.  This is useful for people who are packaging
pciutils to install on other computers.

There are several options which can be set in the Makefile or overridden
when running make:

  ZLIB=yes/no	Enable support for compressed pci.ids (requires zlib).
		If it is enabled, pciutils will use pci.ids.gz in preference to
		pci.ids, even if the pci.ids file is newer.  If the pci.ids.gz
		file is missing, it will use pci.ids instead.  If you do not
		specify this option, the configure script will try to guess
		automatically based on the presence of zlib.

  DNS=yes/no	Enable support for querying the central database of PCI IDs
		using DNS.  Requires libresolv (which is available on most
		systems as a part of the standard libraries) and tries to
		autodetect its presence if the option is not specified.

  SHARED=yes/	Build libpci as a shared library.  Requires GCC 4.0 or newer.
  no/local	The ABI of the shared library is intended to remain backward
		compatible for a long time (we use symbol versioning to achieve
		that, like GNU libc does).  The value `local' includes the
		right directory name in the binaries, so the utilities can be
		run without installation.  This is not recommended for any
		production builds.

"make install-lib" installs the library together with its header files
for use by other programs.

When you are bored of dumping PCI registers, just use "make uninstall".


3. Getting new IDs
~~~~~~~~~~~~~~~~~~~
The database of PCI IDs (the pci.ids file) gets out of date much faster
than I release new versions of this package, so it is maintained separately.

It lives at https://pci-ids.ucw.cz/, where you can browse the database,
download the most recent pci.ids file (e.g., by running the update-ids utility)
and also submit new entries.

Alternatively, you can use `lspci -q' to query the central database
for new entries via network.

The pci.ids file is also mirrored at https://github.com/pciutils/pciids.

On Linux systems with a recent enough version of libudev, UDEV's HWDB
database is consulted when pci.ids lacks the device.


4. Getting new versions
~~~~~~~~~~~~~~~~~~~~~~~
The current version of pciutils is available at:

	https://mj.ucw.cz/sw/pciutils/

The tarball can be downloaded at the following places:

	https://mj.ucw.cz/download/linux/pci/
	ftp://ftp.ucw.cz/pub/mj/linux/pci/
	https://www.kernel.org/pub/software/utils/pciutils/ (expect a couple of hours delay)

There is also a public GIT tree at:

	https://git.kernel.org/pub/scm/utils/pciutils/pciutils.git
	https://github.com/pciutils/pciutils


5. Using the library
~~~~~~~~~~~~~~~~~~~~
So far, there is only a little documentation for the library except for the
general introduction in the pcilib(7) man page. If you want to use the
library in your programs, please follow the comments in lib/pci.h and in
the example program example.c.


6. Feedback
~~~~~~~~~~~
If you have any bug reports or suggestions, send them to the author.

If you have any new IDs, I'll be very glad to add them to the database.
Just submit them at https://pci-ids.ucw.cz/.

Announcements of new versions are sent to [email protected]
(see http://vger.kernel.org/ for instructions).

					Have fun
							Martin

Since 2.1.99-test5, pciutils should also be compilable on Windows. Thanks
to Alexander Stock for contributing the port.

Updated after version 2.2.6 to compile again, and with MinGW, even (only?)
cross-compiling. (Hopefully it works with MSVC too.)

For simple listing PCI devices in system via win32-cfgmgr32 access method
which provides only basic information and emulated config space, there is no
special requirement. To list PCI resources on Windows 8 and higher versions,
it is necessary to have architecture-native version (e.g. AMD64 version on
AMD64 systems).

For config space access there are different windows specific access methods:
- win32-kldbg - Kernel Local Debugging Driver kldbgdrv.sys
- win32-sysdbg - NT SysDbg interface
- intel-conf1 - Direct hardware access via Intel configuration mechanism 1

The default access method is win32-cfgmgr32 and by default it tries to use
one of the above config access access method to provide as much as possible
information to application. More details about particular access method and
caveats are described in the pcilib(8) manual page.

The default access method for config space is win32-kldbg. It uses Microsoft's
Kernel Local Debugging Driver kldbgdrv.sys. This driver is not part of the
Windows system but is part of the Microsoft WinDbg tool. It is required to
have kldbgdrv.sys driver installed in the system32 directory or to have
windbg.exe or kd.exe binary in PATH. kldbgdrv.sys driver has some restrictions.
Process needs to have Debug privilege and Windows system has to be booted with
Debugging option. Debugging option can be enabled by calling (takes effect
after next boot): bcdedit /debug on

Download links for WinDbg 6.12.2.633 standalone installer from Microsoft:
https://download.microsoft.com/download/A/6/A/A6AC035D-DA3F-4F0C-ADA4-37C8E5D34E3D/setup/WinSDKDebuggingTools_amd64/dbg_amd64.msi
https://download.microsoft.com/download/A/6/A/A6AC035D-DA3F-4F0C-ADA4-37C8E5D34E3D/setup/WinSDKDebuggingTools/dbg_x86.msi

To access config space via intel-conf1 access method on NT-based systems via
NT ProcessUserModeIOPL system call, it is required to have SeTcbPrivilege
(Act as part of the operating system privilege), which can be enabled in User
Accounts settings (take effect after next login). By default this privilege is
not enabled for any non-system user. Or alternatively it is required to be in
local Administrators group and on Windows 2000 SP4 or higher systems to have
SeImpersonatePrivilege (Impersonate a client after authentication privilege)
which is by default enabled for all local Administrators accounts. There is no
special requirement for DOS-based systems. 64-bit systems do not have to allow
users to access config space even with SeTcbPrivilege.

To compile this port, run following command:

  make CROSS_COMPILE=i586-mingw32msvc- HOST=i586-windows ZLIB=no IDSDIR=""

To build 64-bit version, run:

  make CROSS_COMPILE=x86_64-w64-mingw32- HOST=x86_64-windows ZLIB=no IDSDIR=""

Sometimes compilation may fail due to broken or missing getopt implementation.
In this case try to compile with additional make option: COMPAT_GETOPT=yes

Building of shared DLL library libpci3.dll is supported too but needs to be
manually enabled by make option: SHARED=yes

This DLL library libpci3.dll has versioned symbols with stable ordinal numbers
which provides backward and forward compatibility. Every symbol in DLL library
has '@LIBPCI_3.<version>' suffix to achieve it. For linking application to
libpci3.dll it is possible to generate import library from libpci3.def file.
Such import library will provide import symbol names without versioned suffix
as an alias for the latest symbol version, which matches function name in pci.h
header file. The alias is resolved by the linker at linking time, so the final
application binary would always reference only versioned symbol. DLL library
libpci3.dll does not provide unversioned symbols, so for using GetProcAddress()
or dlsym() it is needed to specify full versioned symbol name.