.\" $NetBSD: pci_msi.9,v 1.17.2.1 2021/01/15 17:46:40 martin Exp $
.\"
.\" Copyright (c) 2015 Internet Initiative Japan Inc.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd January 12, 2021
.Dt PCI_MSI 9
.Os
.Sh NAME
.Nm pci_msi ,
.Nm pci_msix ,
.Nm pci_msi_count ,
.Nm pci_msi_alloc ,
.Nm pci_msi_alloc_exact ,
.Nm pci_msix_count ,
.Nm pci_msix_alloc ,
.Nm pci_msix_alloc_exact ,
.Nm pci_msix_alloc_map ,
.Nm pci_intx_alloc ,
.Nm pci_intr_alloc ,
.Nm pci_intr_release ,
.Nm pci_intr_type
.Nd PCI MSI{,-X} manipulation functions
.Sh SYNOPSIS
.Ft int
.Fn pci_msi_count "pci_chipset_tag_t pc" \
"pcitag_t tag"
.Ft int
.Fn pci_msi_alloc  "const struct pci_attach_args *pa" \
"pci_intr_handle_t **ihps" "int *count"
.Ft int
.Fn pci_msi_alloc_exact "const struct pci_attach_args *pa" \
"pci_intr_handle_t **ihps" "int count"
.Ft int
.Fn pci_msix_count "pci_chipset_tag_t pc" \
"pcitag_t tag"
.Ft int
.Fn pci_msix_alloc  "const struct pci_attach_args *pa" \
"pci_intr_handle_t **ihps" "int *count"
.Ft int
.Fn pci_msix_alloc_exact "const struct pci_attach_args *pa" \
"pci_intr_handle_t **ihps" "int count"
.Ft int
.Fn pci_msix_alloc_map "const struct pci_attach_args *pa" \
"pci_intr_handle_t **ihps" "u_int *table_indexes" "int count"
.Ft int
.Fn pci_intx_alloc  "const struct pci_attach_args *pa" \
"pci_intr_handle_t **ihp"
.Ft int
.Fn pci_intr_alloc  "const struct pci_attach_args *pa" \
"pci_intr_handle_t **ihp" "int *counts" \
"pci_intr_type_t max_type"
.Ft void
.Fn pci_intr_release "pci_chipset_tag_t pc" \
"pci_intr_handle_t *pih" "int count"
.Ft pci_intr_type_t
.Fn pci_intr_type "pci_chipset_tag_t pc" \
"pci_intr_handle_t ih"
.Sh DESCRIPTION
The
.Nm
functions exist to allow device drivers to use MSI/MSI-X.
When the system uses MSI/MSI-X, it must define the
.Dv __HAVE_PCI_MSI_MSIX
build option.
.Pp
Each driver has an
.Fn attach
function which has a bus-specific
.Ft attach_args
structure.
Each driver for a PCI device is passed a pointer to an object of type
.Ft struct pci_attach_args
which contains, among other things, information about the location
of the device in the PCI bus topology sufficient to allow interrupts
from the device to be handled.
.Pp
.Fn pci_msi_count
returns the max number of the device's MSI.
If the device can not use MSI,
.Fn pci_msi_count
returns zero.
.Fn pci_msix_count
works in the same manner for MSI-X.
.Pp
If a driver wishes to establish an MSI handler for the device,
it should pass the
.Ft struct pci_attach_args *
and
.Fa count
.Fn pci_msi_alloc
or
.Fn pci_msi_alloc_exact
functions, which return zero on success, and nonzero on failure.
When the functions are successful, they return the pointer to the
allocated handle array in
.Ft pihs
whose size is
.Ft count
or less.
The difference between
.Fn pci_msi_alloc
and
.Fn pci_msi_alloc_exact
is whether
.Fa count
can be decremented or not.
.Fn pci_msi_alloc
can decrement
.Fa count ,
and which is similar to
.Fx Ap s
.Fn pci_alloc_msi .
In contrast,
.Fn pci_msi_alloc_exact
can not decrement
.Ft count .
.Pp
If the driver wishes to refer to the MSI source in an attach or
error message, it should use the value returned by
.Fn pci_intr_string
the same as INTx.
The buffer passed to
.Fn pci_intr_string
should be at least
.Dv PCI_INTRSTR_LEN
bytes long.
.Pp
Subsequently, when the driver is prepared to receive MSIs, it
should call
.Fn pci_intr_establish
the same as INTx to actually establish the handler;
when the device interrupts,
.Fa intrhand
will be called with a single argument
.Fa intrarg ,
and will run at the interrupt priority level
.Fa ipl .
.Pp
The return value of
.Fn pci_intr_establish
may be saved and passed to
.Fn pci_intr_disestablish
to disable the interrupt handler the same as INTx
when the driver is no longer interested in MSIs from the device.
After that, the driver should also call
.Fn pci_intr_release
to free resources about MSI as well as INTx and MSI-X.
If
.Fa pih
is NULL,
.Fn pci_intr_release
does nothing.
.Pp
If a driver wishes to establish an MSI-X handler for the device,
it is almost the same as MSI.
The only differences is
.Fn pci_msix_alloc_map .
This function can assign separate handlers for each MSI-X table
entry.
I.e., if the driver wants to assign the handlers in the following way:
.Bd -literal
	msix_handler0 => MSI-X table index: 4
	msix_handler1 => MSI-X table index: 5
	msix_handler2 => MSI-X table index: 0
.Ed
the driver should set
.Fa table_indexes
this way:
.Bd -literal
	table_indexes[0] = 4;
	table_indexes[1] = 5;
	table_indexes[2] = 0;
.Ed
.Pp
If the driver wants to fall back to INTx, the driver should use
.Fn pci_intx_alloc
and
.Fn pci_intr_release
instead of
.Fn pci_intr_map
to resolve contradiction of the interrupt handler ownership.
I.e.,
.Fn pci_intr_map
does not have the ownership (the function just calculates value),
in contrast,
.Fn pci_msi_alloc
and
.Fn pci_msix_alloc
have (the functions allocate memory for interrupt handlers).
.Pp
.Fn pci_intr_alloc
is wrapper function which select and automatically fallback
allocation functions according to the argument
.Fa counts .
The elements of
.Fa counts
array means each required interrupt count for INTx, MSI, and MSI-X.
The index count of
.Fa counts
must be
.Dv PCI_INTR_TYPE_SIZE .
.Fa max_type
must be
.Dv PCI_INTR_TYPE_MSIX ,
.Dv PCI_INTR_TYPE_MSI ,
or
.Dv PCI_INTR_TYPE_INTX .
The parameter does not mean array index counts of
.Fa counts .
The parameter means the interrupt type which
.Fn pci_intr_alloc
tries to allocate first.
I.e., if the driver wants to allocate interrupts in the following way:
.Bd -literal
	5 MSI-X
	1 MSI (if MSI-X allocation failed)
	INTx (if MSI allocation failed either)
.Ed
the driver should call
.Fn pci_intr_alloc
in the following way:
.Bd -literal
	int counts[PCI_INTR_TYPE_SIZE];
	counts[PCI_INTR_TYPE_MSIX] = 5;
	counts[PCI_INTR_TYPE_MSI] = 1;
	counts[PCI_INTR_TYPE_INTX] = 1;
	error = pci_intr_alloc(pa, ihps, counts,
			       PCI_INTR_TYPE_MSIX);
.Ed
If the driver wants to allocate interrupts in the following way:
.Bd -literal
	hardware max number MSI-X
	1 MSI (if MSI-X allocation failed)
.Ed
that is, the driver does not use INTx, the driver should call
.Fn pci_intr_alloc
in the following way:
.Bd -literal
	int counts[PCI_INTR_TYPE_SIZE];
	counts[PCI_INTR_TYPE_MSIX] = -1; /* -1 means max */
	counts[PCI_INTR_TYPE_MSI] = 1;
	counts[PCI_INTR_TYPE_INTX] = 0; /* 0 means not use */
	error = pci_intr_alloc(pa, ihps, counts,
			       PCI_INTR_TYPE_MSIX);
.Ed
If the driver wants to allocate interrupts in the following way:
.Bd -literal
	3 MSI
	INTx (if MSI allocation failed)
.Ed
that is, the driver does not use MSI-X, the driver should call
.Fn pci_intr_alloc
in the following way:
.Bd -literal
	int counts[PCI_INTR_TYPE_SIZE];
	counts[PCI_INTR_TYPE_MSIX] = 0; /* 0 means not use */
	counts[PCI_INTR_TYPE_MSI] = 3;
	counts[PCI_INTR_TYPE_INTX] = 1;
	error = pci_intr_alloc(pa, ihps, counts,
			       PCI_INTR_TYPE_MSI);
.Ed
If the driver wants to allocate interrupts in the following way:
.Bd -literal
	1 MSI-X
	1 MSI
	INTx (if MSI/MSI-X allocation failed)
.Ed
that is, general usage, the driver should call simply
.Fn pci_intr_alloc
in the following way:
.Bd -literal
	error = pci_intr_alloc(pa, ihps, NULL, 0);
.Ed
.Fa max_type
is ignored in this case.
.Fn pci_intr_alloc
returns zero on any allocation function success, and non-zero on
all allocation function failures.
On success,
.Fa counts
is overwritten by a really allocated count.
I.e., if 5 MSI-X is allocated,
.Fa counts
is
.Bd -literal
	counts[PCI_INTR_TYPE_MSIX] == 5
	counts[PCI_INTR_TYPE_MSI] == 0
	counts[PCI_INTR_TYPE_INTX] == 0
.Ed
on return.
.Pp
.Fn pci_intr_type
returns the interrupt type of
.Fa ih .
The return value is
.Dv PCI_INTR_TYPE_MSIX
for MSI-X,
.Dv PCI_INTR_TYPE_MSI
for MSI, and
.Dv PCI_INTR_TYPE_INTX
for others.
.Sh SEE ALSO
.Xr pci_intr 9
.Sh HISTORY
.Nm
support first appeared in
.Nx 8.0 .
Support is present on
.Em i386 ,
.Em amd64
and
.Em aarch64
architectures.
.Sh AUTHORS
The
.Nm
interfaces were designed and implemented by
.An Kengo Nakahara
.Aq Mt knakahara@NetBSD.org .