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