xref: /freebsd/share/man/man9/pci.9 (revision 4ce386ff25d77954b8cfa11534f632172e848244)
1.\"
2.\" Copyright (c) 2005 Bruce M Simpson <bms@FreeBSD.org>
3.\" All rights reserved.
4.\"
5.\" Redistribution and use in source and binary forms, with or without
6.\" modification, are permitted provided that the following conditions
7.\" are met:
8.\" 1. Redistributions of source code must retain the above copyright
9.\"    notice, this list of conditions and the following disclaimer.
10.\" 2. Redistributions in binary form must reproduce the above copyright
11.\"    notice, this list of conditions and the following disclaimer in the
12.\"    documentation and/or other materials provided with the distribution.
13.\"
14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24.\" SUCH DAMAGE.
25.\"
26.\" $FreeBSD$
27.\"
28.Dd May 24, 2014
29.Dt PCI 9
30.Os
31.Sh NAME
32.Nm pci ,
33.Nm pci_alloc_msi ,
34.Nm pci_alloc_msix ,
35.Nm pci_disable_busmaster ,
36.Nm pci_disable_io ,
37.Nm pci_enable_busmaster ,
38.Nm pci_enable_io ,
39.Nm pci_find_bsf ,
40.Nm pci_find_cap ,
41.Nm pci_find_dbsf ,
42.Nm pci_find_device ,
43.Nm pci_find_extcap ,
44.Nm pci_find_htcap ,
45.Nm pci_get_max_read_req ,
46.Nm pci_get_powerstate ,
47.Nm pci_get_vpd_ident ,
48.Nm pci_get_vpd_readonly ,
49.Nm pci_iov_attach ,
50.Nm pci_iov_detach ,
51.Nm pci_msi_count ,
52.Nm pci_msix_count ,
53.Nm pci_pending_msix ,
54.Nm pci_read_config ,
55.Nm pci_release_msi ,
56.Nm pci_remap_msix ,
57.Nm pci_restore_state ,
58.Nm pci_save_state ,
59.Nm pci_set_max_read_req ,
60.Nm pci_set_powerstate ,
61.Nm pci_write_config
62.Nd PCI bus interface
63.Sh SYNOPSIS
64.In sys/bus.h
65.In dev/pci/pcireg.h
66.In dev/pci/pcivar.h
67.Ft int
68.Fn pci_alloc_msi "device_t dev" "int *count"
69.Ft int
70.Fn pci_alloc_msix "device_t dev" "int *count"
71.Ft int
72.Fn pci_disable_busmaster "device_t dev"
73.Ft int
74.Fn pci_disable_io "device_t dev" "int space"
75.Ft int
76.Fn pci_enable_busmaster "device_t dev"
77.Ft int
78.Fn pci_enable_io "device_t dev" "int space"
79.Ft device_t
80.Fn pci_find_bsf "uint8_t bus" "uint8_t slot" "uint8_t func"
81.Ft int
82.Fn pci_find_cap "device_t dev" "int capability" "int *capreg"
83.Ft device_t
84.Fn pci_find_dbsf "uint32_t domain" "uint8_t bus" "uint8_t slot" "uint8_t func"
85.Ft device_t
86.Fn pci_find_device "uint16_t vendor" "uint16_t device"
87.Ft int
88.Fn pci_find_extcap "device_t dev" "int capability" "int *capreg"
89.Ft int
90.Fn pci_find_htcap "device_t dev" "int capability" "int *capreg"
91.Ft int
92.Fn pci_get_max_read_req "device_t dev"
93.Ft int
94.Fn pci_get_powerstate "device_t dev"
95.Ft int
96.Fn pci_get_vpd_ident "device_t dev" "const char **identptr"
97.Ft int
98.Fn pci_get_vpd_readonly "device_t dev" "const char *kw" "const char **vptr"
99.Ft int
100.Fn pci_iov_attach "device_t dev" "nvlist_t *pf_schema" "nvlist_t *vf_schema"
101.Ft int
102.Fn pci_iov_detach "device_t dev"
103.Ft int
104.Fn pci_msi_count "device_t dev"
105.Ft int
106.Fn pci_msix_count "device_t dev"
107.Ft int
108.Fn pci_pending_msix "device_t dev" "u_int index"
109.Ft uint32_t
110.Fn pci_read_config "device_t dev" "int reg" "int width"
111.Ft int
112.Fn pci_release_msi "device_t dev"
113.Ft int
114.Fn pci_remap_msix "device_t dev" "int count" "const u_int *vectors"
115.Ft void
116.Fn pci_restore_state "device_t dev"
117.Ft void
118.Fn pci_save_state "device_t dev"
119.Ft int
120.Fn pci_set_max_read_req "device_t dev" "int size"
121.Ft int
122.Fn pci_set_powerstate "device_t dev" "int state"
123.Ft void
124.Fn pci_write_config "device_t dev" "int reg" "uint32_t val" "int width"
125.Sh DESCRIPTION
126The
127.Nm
128set of functions are used for managing PCI devices.
129The functions are split into several groups:
130raw configuration access,
131locating devices,
132device information,
133device configuration,
134and
135message signaled interrupts.
136.Ss Raw Configuration Access
137The
138.Fn pci_read_config
139function is used to read data from the PCI configuration
140space of the device
141.Fa dev ,
142at offset
143.Fa reg ,
144with
145.Fa width
146specifying the size of the access.
147.Pp
148The
149.Fn pci_write_config
150function is used to write the value
151.Fa val
152to the PCI configuration
153space of the device
154.Fa dev ,
155at offset
156.Fa reg ,
157with
158.Fa width
159specifying the size of the access.
160.Pp
161.Em NOTE :
162Device drivers should only use these functions for functionality that
163is not available via another
164.Fn pci
165function.
166.Ss Locating Devices
167The
168.Fn pci_find_bsf
169function looks up the
170.Vt device_t
171of a PCI device, given its
172.Fa bus ,
173.Fa slot ,
174and
175.Fa func .
176The
177.Fa slot
178number actually refers to the number of the device on the bus,
179which does not necessarily indicate its geographic location
180in terms of a physical slot.
181Note that in case the system has multiple PCI domains,
182the
183.Fn pci_find_bsf
184function only searches the first one.
185Actually, it is equivalent to:
186.Bd -literal -offset indent
187pci_find_dbsf(0, bus, slot, func);
188.Ed
189.Pp
190The
191.Fn pci_find_dbsf
192function looks up the
193.Vt device_t
194of a PCI device, given its
195.Fa domain ,
196.Fa bus ,
197.Fa slot ,
198and
199.Fa func .
200The
201.Fa slot
202number actually refers to the number of the device on the bus,
203which does not necessarily indicate its geographic location
204in terms of a physical slot.
205.Pp
206The
207.Fn pci_find_device
208function looks up the
209.Vt device_t
210of a PCI device, given its
211.Fa vendor
212and
213.Fa device
214IDs.
215Note that there can be multiple matches for this search; this function
216only returns the first matching device.
217.Ss Device Information
218The
219.Fn pci_find_cap
220function is used to locate the first instance of a PCI capability
221register set for the device
222.Fa dev .
223The capability to locate is specified by ID via
224.Fa capability .
225Constant macros of the form
226.Dv PCIY_xxx
227for standard capability IDs are defined in
228.In dev/pci/pcireg.h .
229If the capability is found, then
230.Fa *capreg
231is set to the offset in configuration space of the capability register set,
232and
233.Fn pci_find_cap
234returns zero.
235If the capability is not found or the device does not support capabilities,
236.Fn pci_find_cap
237returns an error.
238.Pp
239The
240.Fn pci_find_extcap
241function is used to locate the first instance of a PCI-express
242extended capability register set for the device
243.Fa dev .
244The extended capability to locate is specified by ID via
245.Fa capability .
246Constant macros of the form
247.Dv PCIZ_xxx
248for standard extended capability IDs are defined in
249.In dev/pci/pcireg.h .
250If the extended capability is found, then
251.Fa *capreg
252is set to the offset in configuration space of the extended capability
253register set, and
254.Fn pci_find_extcap
255returns zero.
256If the extended capability is not found or the device is not a
257PCI-express device,
258.Fn pci_find_extcap
259returns an error.
260.Pp
261The
262.Fn pci_find_htcap
263function is used to locate the first instance of a HyperTransport capability
264register set for the device
265.Fa dev .
266The capability to locate is specified by type via
267.Fa capability .
268Constant macros of the form
269.Dv PCIM_HTCAP_xxx
270for standard HyperTransport capability types are defined in
271.In dev/pci/pcireg.h .
272If the capability is found, then
273.Fa *capreg
274is set to the offset in configuration space of the capability register set,
275and
276.Fn pci_find_htcap
277returns zero.
278If the capability is not found or the device is not a HyperTransport device,
279.Fn pci_find_htcap
280returns an error.
281.Pp
282The
283.Fn pci_get_vpd_ident
284function is used to fetch a device's Vital Product Data
285.Pq VPD
286identifier string.
287If the device
288.Fa dev
289supports VPD and provides an identifier string,
290then
291.Fa *identptr
292is set to point at a read-only, null-terminated copy of the identifier
293string,
294and
295.Fn pci_get_vpd_ident
296returns zero.
297If the device does not support VPD or does not provide an identifier
298string,
299then
300.Fn pci_get_vpd_ident
301returns an error.
302.Pp
303The
304.Fn pci_get_vpd_readonly
305function is used to fetch the value of a single VPD read-only keyword
306for the device
307.Fa dev .
308The keyword to fetch is identified by the two character string
309.Fa kw .
310If the device supports VPD and provides a read-only value for the
311requested keyword,
312then
313.Fa *vptr
314is set to point at a read-only, null-terminated copy of the value,
315and
316.Fn pci_get_vpd_readonly
317returns zero.
318If the device does not support VPD or does not provide the requested
319keyword,
320then
321.Fn pci_get_vpd_readonly
322returns an error.
323.Ss Device Configuration
324The
325.Fn pci_enable_busmaster
326function enables PCI bus mastering for the device
327.Fa dev ,
328by setting the
329.Dv PCIM_CMD_BUSMASTEREN
330bit in the
331.Dv PCIR_COMMAND
332register.
333The
334.Fn pci_disable_busmaster
335function clears this bit.
336.Pp
337The
338.Fn pci_enable_io
339function enables memory or I/O port address decoding for the device
340.Fa dev ,
341by setting the
342.Dv PCIM_CMD_MEMEN
343or
344.Dv PCIM_CMD_PORTEN
345bit in the
346.Dv PCIR_COMMAND
347register appropriately.
348The
349.Fn pci_disable_io
350function clears the appropriate bit.
351The
352.Fa space
353argument specifies which resource is affected; this can be either
354.Dv SYS_RES_MEMORY
355or
356.Dv SYS_RES_IOPORT
357as appropriate.
358Device drivers should generally not use these routines directly.
359The PCI bus will enable decoding automatically when a
360.Dv SYS_RES_MEMORY
361or
362.Dv SYS_RES_IOPORT
363resource is activated via
364.Xr bus_alloc_resource 9
365or
366.Xr bus_activate_resource 9 .
367.Pp
368The
369.Fn pci_get_max_read_req
370function returns the current maximum read request size in bytes for a
371PCI-express device.
372If the
373.Fa dev
374device is not a PCI-express device,
375.Fn pci_get_max_read_req
376returns zero.
377.Pp
378The
379.Fn pci_set_max_read_req
380sets the PCI-express maximum read request size for
381.Fa dev .
382The requested
383.Fa size
384may be adjusted,
385and
386.Fn pci_set_max_read_req
387returns the actual size set in bytes.
388If the
389.Fa dev
390device is not a PCI-express device,
391.Fn pci_set_max_read_req
392returns zero.
393.Pp
394The
395.Fn pci_get_powerstate
396function returns the current power state of the device
397.Fa dev .
398If the device does not support power management capabilities, then the default
399state of
400.Dv PCI_POWERSTATE_D0
401is returned.
402The following power states are defined by PCI:
403.Bl -hang -width ".Dv PCI_POWERSTATE_UNKNOWN"
404.It Dv PCI_POWERSTATE_D0
405State in which device is on and running.
406It is receiving full power from the system and delivering
407full functionality to the user.
408.It Dv PCI_POWERSTATE_D1
409Class-specific low-power state in which device context may or
410may not be lost.
411Busses in this state cannot do anything to the bus, to
412force devices to lose context.
413.It Dv PCI_POWERSTATE_D2
414Class-specific low-power state in which device context may or
415may not be lost.
416Attains greater power savings than
417.Dv PCI_POWERSTATE_D1 .
418Busses in this state can cause devices to lose some context.
419Devices
420.Em must
421be prepared for the bus to be in this state or higher.
422.It Dv PCI_POWERSTATE_D3
423State in which the device is off and not running.
424Device context is lost, and power from the device can
425be removed.
426.It Dv PCI_POWERSTATE_UNKNOWN
427State of the device is unknown.
428.El
429.Pp
430The
431.Fn pci_set_powerstate
432function is used to transition the device
433.Fa dev
434to the PCI power state
435.Fa state .
436If the device does not support power management capabilities or
437it does not support the specific power state
438.Fa state ,
439then the function will fail with
440.Er EOPNOTSUPP .
441.Pp
442The
443.Fn pci_iov_attach
444function is used to advertise that the given device
445.Pq and associated device driver
446supports PCI Single-Root I/O Virtualization
447.Po SR-IOV Pc .
448A driver that supports SR-IOV must implement the
449.Xr PCI_INIT_IOV 9 ,
450.Xr PCI_ADD_VF 9
451and
452.Xr PCI_UNIT_IOV 9
453methods.
454This function should be called during the
455.Xr DEVICE_ATTACH 9
456method.
457If this function returns an error, it is recommended that the device driver
458still successfully attaches, but runs with SR-IOV disabled.
459The
460.Fa pf_schema
461and
462.Fa vf_schema
463parameters are used to define what device-specific configuration parameters the
464device driver accepts when SR-IOV is enabled for the Physical Function
465.Pq PF
466and for individual Virtual Functions
467.Pq VFs
468respectively.
469See
470.Xr pci_iov_schema 9
471for details on how to construct the schema.
472If either the
473.Pa pf_schema
474or
475.Pa vf_schema
476is invalid or specifies parameter names that conflict with parameter names that
477are already in use,
478.Fn pci_iov_attach
479will return an error and SR-IOV will not be available on the PF device.
480If a driver does not accept configuration parameters for either the PF device
481or the VF devices, the driver must pass an empty schema for that device.
482The SR-IOV infrastructure takes ownership of the
483.Fa pf_schema
484and
485.Fa vf_schema
486and is responsible for freeing them.
487The driver must never free the schemas itself.
488.Pp
489The
490.Fn pci_iov_detach
491function is used to advise the SR-IOV infrastructure that the driver for the
492given device is attempting to detach and that all SR-IOV resources for the
493device must be released.
494This function must be called during the
495.Xr DEVICE_DETACH 9
496method if
497.Fn pci_iov_attach
498was successfully called on the device and
499.Fn pci_iov_detach
500has not subsequently been called on the device and returned no error.
501If this function returns an error, the
502.Xr DEVICE_DETACH 9
503method must fail and return an error, as detaching the PF driver while VF
504devices are active would cause system instability.
505This function is safe to call and will always succeed if
506.Fn pci_iov_attach
507previously failed with an error on the given device, or if
508.Fn pci_iov_attach
509was never called on the device.
510.Pp
511The
512.Fn pci_save_state
513and
514.Fn pci_restore_state
515functions can be used by a device driver to save and restore standard PCI
516config registers.
517The
518.Fn pci_save_state
519function must be invoked while the device has valid state before
520.Fn pci_restore_state
521can be used.
522If the device is not in the fully-powered state
523.Pq Dv PCI_POWERSTATE_D0
524when
525.Fn pci_restore_state
526is invoked,
527then the device will be transitioned to
528.Dv PCI_POWERSTATE_D0
529before any config registers are restored.
530.Ss Message Signaled Interrupts
531Message Signaled Interrupts
532.Pq MSI
533and
534Enhanced Message Signaled Interrupts
535.Pq MSI-X
536are PCI capabilities that provide an alternate method for PCI
537devices to signal interrupts.
538The legacy INTx interrupt is available to PCI devices as a
539.Dv SYS_RES_IRQ
540resource with a resource ID of zero.
541MSI and MSI-X interrupts are available to PCI devices as one or more
542.Dv SYS_RES_IRQ
543resources with resource IDs greater than zero.
544A driver must ask the PCI bus to allocate MSI or MSI-X interrupts
545using
546.Fn pci_alloc_msi
547or
548.Fn pci_alloc_msix
549before it can use MSI or MSI-X
550.Dv SYS_RES_IRQ
551resources.
552A driver is not allowed to use the legacy INTx
553.Dv SYS_RES_IRQ
554resource if MSI or MSI-X interrupts have been allocated,
555and attempts to allocate MSI or MSI-X interrupts will fail if the
556driver is currently using the legacy INTx
557.Dv SYS_RES_IRQ
558resource.
559A driver is only allowed to use either MSI or MSI-X,
560but not both.
561.Pp
562The
563.Fn pci_msi_count
564function returns the maximum number of MSI messages supported by the
565device
566.Fa dev .
567If the device does not support MSI,
568then
569.Fn pci_msi_count
570returns zero.
571.Pp
572The
573.Fn pci_alloc_msi
574function attempts to allocate
575.Fa *count
576MSI messages for the device
577.Fa dev .
578The
579.Fn pci_alloc_msi
580function may allocate fewer messages than requested for various
581reasons including requests for more messages than the device
582.Fa dev
583supports,
584or if the system has a shortage of available MSI messages.
585On success,
586.Fa *count
587is set to the number of messages allocated and
588.Fn pci_alloc_msi
589returns zero.
590The
591.Dv SYS_RES_IRQ
592resources for the allocated messages will be available at consecutive
593resource IDs beginning with one.
594If
595.Fn pci_alloc_msi
596is not able to allocate any messages,
597it returns an error.
598Note that MSI only supports message counts that are powers of two;
599requests to allocate a non-power of two count of messages will fail.
600.Pp
601The
602.Fn pci_release_msi
603function is used to release any allocated MSI or MSI-X messages back
604to the system.
605If any MSI or MSI-X
606.Dv SYS_RES_IRQ
607resources are allocated by the driver or have a configured interrupt
608handler,
609this function will fail with
610.Er EBUSY .
611The
612.Fn pci_release_msi
613function returns zero on success and an error on failure.
614.Pp
615The
616.Fn pci_msix_count
617function returns the maximum number of MSI-X messages supported by the
618device
619.Fa dev .
620If the device does not support MSI-X,
621then
622.Fn pci_msix_count
623returns zero.
624.Pp
625The
626.Fn pci_alloc_msix
627function attempts to allocate
628.Fa *count
629MSI-X messages for the device
630.Fa dev .
631The
632.Fn pci_alloc_msix
633function may allocate fewer messages than requested for various
634reasons including requests for more messages than the device
635.Fa dev
636supports,
637or if the system has a shortage of available MSI-X messages.
638On success,
639.Fa *count
640is set to the number of messages allocated and
641.Fn pci_alloc_msix
642returns zero.
643For MSI-X messages,
644the resource ID for each
645.Dv SYS_RES_IRQ
646resource identifies the index in the MSI-X table of the
647corresponding message.
648A resource ID of one maps to the first index of the MSI-X table;
649a resource ID two identifies the second index in the table, etc.
650The
651.Fn pci_alloc_msix
652function assigns the
653.Fa *count
654messages allocated to the first
655.Fa *count
656table indicies.
657If
658.Fn pci_alloc_msix
659is not able to allocate any messages,
660it returns an error.
661Unlike MSI,
662MSI-X does not require message counts that are powers of two.
663.Pp
664The
665.Fn pci_pending_msix
666function examines the
667.Fa dev
668device's Pending Bit Array
669.Pq PBA
670to determine the pending status of the MSI-X message at table index
671.Fa index .
672If the indicated message is pending,
673this function returns a non-zero value;
674otherwise,
675it returns zero.
676Passing an invalid
677.Fa index
678to this function will result in undefined behavior.
679.Pp
680As mentioned in the description of
681.Fn pci_alloc_msix ,
682MSI-X messages are initially assigned to the first N table entries.
683A driver may use a different distribution of available messages to
684table entries via the
685.Fn pci_remap_msix
686function.
687Note that this function must be called after a successful call to
688.Fn pci_alloc_msix
689but before any of the
690.Dv SYS_RES_IRQ
691resources are allocated.
692The
693.Fn pci_remap_msix
694function returns zero on success,
695or an error on failure.
696.Pp
697The
698.Fa vectors
699array should contain
700.Fa count
701message vectors.
702The array maps directly to the MSI-X table in that the first entry in
703the array specifies the message used for the first entry in the MSI-X
704table,
705the second entry in the array corresponds to the second entry in the
706MSI-X table,
707etc.
708The vector value in each array index can either be zero to indicate
709that no message should be assigned to the corresponding MSI-X table entry,
710or it can be a number from one to N
711.Po
712where N is the count returned from the previous call to
713.Fn pci_alloc_msix
714.Pc
715to indicate which of the allocated messages should be assigned to the
716corresponding MSI-X table entry.
717.Pp
718If
719.Fn pci_remap_msix
720succeeds,
721each MSI-X table entry with a non-zero vector will have an associated
722.Dv SYS_RES_IRQ
723resource whose resource ID corresponds to the table index as described
724above for
725.Fn pci_alloc_msix .
726MSI-X table entries that with a vector of zero will not have an
727associated
728.Dv SYS_RES_IRQ
729resource.
730Additionally,
731if any of the original messages allocated by
732.Fn pci_alloc_msix
733are not used in the new distribution of messages in the MSI-X table,
734they will be released automatically.
735Note that if a driver wishes to use fewer messages than were allocated by
736.Fn pci_alloc_msix ,
737the driver must use a single, contiguous range of messages beginning
738with one in the new distribution.
739The
740.Fn pci_remap_msix
741function will fail if this condition is not met.
742.Sh IMPLEMENTATION NOTES
743The
744.Vt pci_addr_t
745type varies according to the size of the PCI bus address
746space on the target architecture.
747.Sh SEE ALSO
748.Xr pci 4 ,
749.Xr pciconf 8 ,
750.Xr bus_alloc_resource 9 ,
751.Xr bus_dma 9 ,
752.Xr bus_release_resource 9 ,
753.Xr bus_setup_intr 9 ,
754.Xr bus_teardown_intr 9 ,
755.Xr devclass 9 ,
756.Xr device 9 ,
757.Xr driver 9 ,
758.Xr rman 9
759.Rs
760.%B FreeBSD Developers' Handbook
761.%T NewBus
762.%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/
763.Re
764.Rs
765.%A Shanley
766.%A Anderson
767.%B PCI System Architecture
768.%N 2nd Edition
769.%I Addison-Wesley
770.%O ISBN 0-201-30974-2
771.Re
772.Sh AUTHORS
773.An -nosplit
774This manual page was written by
775.An Bruce M Simpson Aq Mt bms@FreeBSD.org
776and
777.An John Baldwin Aq Mt jhb@FreeBSD.org .
778.Sh BUGS
779The kernel PCI code has a number of references to
780.Dq "slot numbers" .
781These do not refer to the geographic location of PCI devices,
782but to the device number assigned by the combination of the PCI IDSEL
783mechanism and the platform firmware.
784This should be taken note of when working with the kernel PCI code.
785