xref: /openbsd-src/share/man/man9/pci_conf_read.9 (revision dcfa02decca60af1dbca1fd44b07ff8408537481)
1.\"	$OpenBSD: pci_conf_read.9,v 1.14 2024/11/13 10:56:18 jsg Exp $
2.\"
3.\" Copyright (c) 2005 Michael Shalayeff
4.\" All rights reserved.
5.\"
6.\" Permission to use, copy, modify, and distribute this software for any
7.\" purpose with or without fee is hereby granted, provided that the above
8.\" copyright notice and this permission notice appear in all copies.
9.\"
10.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
11.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
13.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17.\"
18.Dd $Mdocdate: November 13 2024 $
19.Dt PCI_CONF_READ 9
20.Os
21.Sh NAME
22.Nm pci_make_tag ,
23.Nm pci_decompose_tag ,
24.Nm pci_conf_read ,
25.Nm pci_conf_write
26.Nd PCI config space manipulation functions
27.Sh SYNOPSIS
28.In alpha/pci/pci_machdep.h
29.In i386/pci/pci_machdep.h
30.In machine/pci_machdep.h
31.Ft pcitag_t
32.Fn pci_make_tag "pci_chipset_tag_t pc" "int bus" "int dev" "int func"
33.Ft void
34.Fn pci_decompose_tag "pci_chipset_tag_t pc" "pcitag_t tag" "int *busp" \
35"int *devp" "int *funcp"
36.Ft pcireg_t
37.Fn pci_conf_read "pci_chipset_tag_t pc" "pcitag_t tag" "int reg"
38.Ft void
39.Fn pci_conf_write "pci_chipset_tag_t pc" "pcitag_t tag" "int reg" \
40"pcireg_t val"
41.Sh DESCRIPTION
42These functions provide a way to access PCI configuration space.
43.Pp
44The following types are defined in the machine dependent include file
45.In pci_machdep.h .
46.Pp
47.Bl -tag -width pci_chipset_tag_t -offset indent -compact
48.It pci_chipset_tag_t
49a PCI chipset descriptor;
50.It pcitag_t
51a PCI device tag;
52.It pcireg_t
53a PCI register datum.
54.El
55.Pp
56In order to access PCI configuration space, a device tag shall be made using
57.Nm pci_make_tag
58given the PCI chipset tag
59.Ar pc
60and the device specification in a tuple of
61.Ar bus ,
62.Ar device ,
63.Ar function .
64The PCI tag composition is a PCI chipset dependent operation
65although often as simple as a shift and logical OR combination.
66.Pp
67The
68.Nm pci_decompose_tag
69provides a reverse operation.
70Once a tag is composed, it is possible to perform configuration
71space read and write with
72.Nm pci_conf_read
73and
74.Nm pci_conf_write ,
75respectively.
76Access to PCI configuration space is only provided for whole
77.Nm pcireg_t
78items, which is usually a 32-bit integer.
79Access to non-existent PCI devices do not (or should not) generate
80any kinds of faults or interruptions and thus allow for an easy device
81scanning by cycling through all possible device and function numbers
82for a given bus.
83.Pp
84Below is an overview of defined PCI configuration space registers for
85devices:
86.Bl -tag -width 0xff -offset indent
87.It 0x00
88Vendor (lower word) and Product (higher word) identification
89(see
90.Pa /sys/dev/pci/pcidevs
91for a comprehensive list).
92.It 0x04
93Commands and Status register.
94.It 0x08
95PCI device's class and subclass IDs.
96See
97.Pa /sys/dev/pci/pcireg.h
98for PCI_CLASS_* and PCI_SUBCLASS_* definitions.
99.It 0x0c
100Specify (low byte to high): cache line size, PCI latency timer, header type,
101and BIST.
102.It 0x10 - 0x28
103Base address registers for I/O and memory space mapped registers.
104.It 0x28
105CardBus CIS register.
106.It 0x2c
107Similar to 0x00 register's definitions for a subsystem identification.
108.It 0x34
109A pointer to the capabilities list.
110Each item is an offset in the configuration space itself.
111.It 0x3c
112Interrupt line and pin numbers.
113.El
114.Sh SEE ALSO
115.Xr cardbus 4 ,
116.Xr pci 4 ,
117.Xr pci_intr_map 9
118.Sh HISTORY
119These functions first appeared in
120.Ox 1.2 .
121.\" .Sh AUTHORS
122