diff options
Diffstat (limited to 'static/netbsd/man9/pci_msi.9 3.html')
| -rw-r--r-- | static/netbsd/man9/pci_msi.9 3.html | 296 |
1 files changed, 0 insertions, 296 deletions
diff --git a/static/netbsd/man9/pci_msi.9 3.html b/static/netbsd/man9/pci_msi.9 3.html deleted file mode 100644 index 1c2d0d0e..00000000 --- a/static/netbsd/man9/pci_msi.9 3.html +++ /dev/null @@ -1,296 +0,0 @@ -<table class="head"> - <tr> - <td class="head-ltitle">PCI_MSI(9)</td> - <td class="head-vol">Kernel Developer's Manual</td> - <td class="head-rtitle">PCI_MSI(9)</td> - </tr> -</table> -<div class="manual-text"> -<section class="Sh"> -<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1> -<p class="Pp"><code class="Nm">pci_msi</code>, <code class="Nm">pci_msix</code>, - <code class="Nm">pci_msi_count</code>, - <code class="Nm">pci_msi_alloc</code>, - <code class="Nm">pci_msi_alloc_exact</code>, - <code class="Nm">pci_msix_count</code>, - <code class="Nm">pci_msix_alloc</code>, - <code class="Nm">pci_msix_alloc_exact</code>, - <code class="Nm">pci_msix_alloc_map</code>, - <code class="Nm">pci_intx_alloc</code>, - <code class="Nm">pci_intr_alloc</code>, - <code class="Nm">pci_intr_release</code>, - <code class="Nm">pci_intr_type</code> — <span class="Nd">PCI MSI{,-X} - manipulation functions</span></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">pci_msi_count</code>(<var class="Fa" style="white-space: nowrap;">pci_chipset_tag_t - pc</var>, <var class="Fa" style="white-space: nowrap;">pcitag_t - tag</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">pci_msi_alloc</code>(<var class="Fa" style="white-space: nowrap;">const - struct pci_attach_args *pa</var>, - <var class="Fa" style="white-space: nowrap;">pci_intr_handle_t **ihps</var>, - <var class="Fa" style="white-space: nowrap;">int *count</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">pci_msi_alloc_exact</code>(<var class="Fa" style="white-space: nowrap;">const - struct pci_attach_args *pa</var>, - <var class="Fa" style="white-space: nowrap;">pci_intr_handle_t **ihps</var>, - <var class="Fa" style="white-space: nowrap;">int count</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">pci_msix_count</code>(<var class="Fa" style="white-space: nowrap;">pci_chipset_tag_t - pc</var>, <var class="Fa" style="white-space: nowrap;">pcitag_t - tag</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">pci_msix_alloc</code>(<var class="Fa" style="white-space: nowrap;">const - struct pci_attach_args *pa</var>, - <var class="Fa" style="white-space: nowrap;">pci_intr_handle_t **ihps</var>, - <var class="Fa" style="white-space: nowrap;">int *count</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">pci_msix_alloc_exact</code>(<var class="Fa" style="white-space: nowrap;">const - struct pci_attach_args *pa</var>, - <var class="Fa" style="white-space: nowrap;">pci_intr_handle_t **ihps</var>, - <var class="Fa" style="white-space: nowrap;">int count</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">pci_msix_alloc_map</code>(<var class="Fa" style="white-space: nowrap;">const - struct pci_attach_args *pa</var>, - <var class="Fa" style="white-space: nowrap;">pci_intr_handle_t **ihps</var>, - <var class="Fa" style="white-space: nowrap;">u_int *table_indexes</var>, - <var class="Fa" style="white-space: nowrap;">int count</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">pci_intx_alloc</code>(<var class="Fa" style="white-space: nowrap;">const - struct pci_attach_args *pa</var>, - <var class="Fa" style="white-space: nowrap;">pci_intr_handle_t - **ihp</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">pci_intr_alloc</code>(<var class="Fa" style="white-space: nowrap;">const - struct pci_attach_args *pa</var>, - <var class="Fa" style="white-space: nowrap;">pci_intr_handle_t **ihp</var>, - <var class="Fa" style="white-space: nowrap;">int *counts</var>, - <var class="Fa" style="white-space: nowrap;">pci_intr_type_t - max_type</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">pci_intr_release</code>(<var class="Fa" style="white-space: nowrap;">pci_chipset_tag_t - pc</var>, <var class="Fa" style="white-space: nowrap;">pci_intr_handle_t - *pih</var>, <var class="Fa" style="white-space: nowrap;">int - count</var>);</p> -<p class="Pp"><var class="Ft">pci_intr_type_t</var> - <br/> - <code class="Fn">pci_intr_type</code>(<var class="Fa" style="white-space: nowrap;">pci_chipset_tag_t - pc</var>, <var class="Fa" style="white-space: nowrap;">pci_intr_handle_t - ih</var>);</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> -<p class="Pp">The <code class="Nm">pci_msi</code> functions exist to allow - device drivers to use MSI/MSI-X. When the system uses MSI/MSI-X, it must - define the <code class="Dv">__HAVE_PCI_MSI_MSIX</code> build option.</p> -<p class="Pp" id="attach">Each driver has an - <a class="permalink" href="#attach"><code class="Fn">attach</code></a>() - function which has a bus-specific <var class="Ft">attach_args</var> - structure. Each driver for a PCI device is passed a pointer to an object of - type <var class="Ft">struct pci_attach_args</var> 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.</p> -<p class="Pp" id="pci_msi_count"><a class="permalink" href="#pci_msi_count"><code class="Fn">pci_msi_count</code></a>() - returns the max number of the device's MSI. If the device can not use MSI, - <code class="Fn">pci_msi_count</code>() returns zero. - <a class="permalink" href="#pci_msix_count"><code class="Fn" id="pci_msix_count">pci_msix_count</code></a>() - works in the same manner for MSI-X.</p> -<p class="Pp" id="pci_msi_alloc">If a driver wishes to establish an MSI handler - for the device, it should pass the <var class="Ft">struct pci_attach_args - *</var> and <var class="Fa">count</var> - <a class="permalink" href="#pci_msi_alloc"><code class="Fn">pci_msi_alloc</code></a>() - or - <a class="permalink" href="#pci_msi_alloc_exact"><code class="Fn" id="pci_msi_alloc_exact">pci_msi_alloc_exact</code></a>() - 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 <var class="Ft">pihs</var> whose size is - <var class="Ft">count</var> or less. The difference between - <code class="Fn">pci_msi_alloc</code>() and - <code class="Fn">pci_msi_alloc_exact</code>() is whether - <var class="Fa">count</var> can be decremented or not. - <code class="Fn">pci_msi_alloc</code>() can decrement - <var class="Fa">count</var>, and which is similar to - <span class="Ux">FreeBSD</span>'s - <a class="permalink" href="#pci_alloc_msi"><code class="Fn" id="pci_alloc_msi">pci_alloc_msi</code></a>(). - In contrast, <code class="Fn">pci_msi_alloc_exact</code>() can not decrement - <var class="Ft">count</var>.</p> -<p class="Pp" id="pci_intr_string">If the driver wishes to refer to the MSI - source in an attach or error message, it should use the value returned by - <a class="permalink" href="#pci_intr_string"><code class="Fn">pci_intr_string</code></a>() - the same as INTx. The buffer passed to - <code class="Fn">pci_intr_string</code>() should be at least - <code class="Dv">PCI_INTRSTR_LEN</code> bytes long.</p> -<p class="Pp" id="pci_intr_establish">Subsequently, when the driver is prepared - to receive MSIs, it should call - <a class="permalink" href="#pci_intr_establish"><code class="Fn">pci_intr_establish</code></a>() - the same as INTx to actually establish the handler; when the device - interrupts, <var class="Fa">intrhand</var> will be called with a single - argument <var class="Fa">intrarg</var>, and will run at the interrupt - priority level <var class="Fa">ipl</var>.</p> -<p class="Pp" id="pci_intr_establish~2">The return value of - <a class="permalink" href="#pci_intr_establish~2"><code class="Fn">pci_intr_establish</code></a>() - may be saved and passed to - <a class="permalink" href="#pci_intr_disestablish"><code class="Fn" id="pci_intr_disestablish">pci_intr_disestablish</code></a>() - 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 <code class="Fn">pci_intr_release</code>() to free resources about - MSI as well as INTx and MSI-X. If <var class="Fa">pih</var> is NULL, - <code class="Fn">pci_intr_release</code>() does nothing.</p> -<p class="Pp" id="pci_msix_alloc_map">If a driver wishes to establish an MSI-X - handler for the device, it is almost the same as MSI. The only differences - is - <a class="permalink" href="#pci_msix_alloc_map"><code class="Fn">pci_msix_alloc_map</code></a>(). - 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:</p> -<div class="Bd Pp Li"> -<pre> msix_handler0 => MSI-X table index: 4 - msix_handler1 => MSI-X table index: 5 - msix_handler2 => MSI-X table index: 0</pre> -</div> -the driver should set <var class="Fa">table_indexes</var> this way: -<div class="Bd Pp Li"> -<pre> table_indexes[0] = 4; - table_indexes[1] = 5; - table_indexes[2] = 0;</pre> -</div> -<p class="Pp" id="pci_intx_alloc">If the driver wants to fall back to INTx, the - driver should use - <a class="permalink" href="#pci_intx_alloc"><code class="Fn">pci_intx_alloc</code></a>() - and - <a class="permalink" href="#pci_intr_release"><code class="Fn" id="pci_intr_release">pci_intr_release</code></a>() - instead of - <a class="permalink" href="#pci_intr_map"><code class="Fn" id="pci_intr_map">pci_intr_map</code></a>() - to resolve contradiction of the interrupt handler ownership. I.e., - <code class="Fn">pci_intr_map</code>() does not have the ownership (the - function just calculates value), in contrast, - <code class="Fn">pci_msi_alloc</code>() and - <a class="permalink" href="#pci_msix_alloc"><code class="Fn" id="pci_msix_alloc">pci_msix_alloc</code></a>() - have (the functions allocate memory for interrupt handlers).</p> -<p class="Pp" id="pci_intr_alloc"><a class="permalink" href="#pci_intr_alloc"><code class="Fn">pci_intr_alloc</code></a>() - is wrapper function which select and automatically fallback allocation - functions according to the argument <var class="Fa">counts</var>. The - elements of <var class="Fa">counts</var> array means each required interrupt - count for INTx, MSI, and MSI-X. The index count of - <var class="Fa">counts</var> must be - <code class="Dv">PCI_INTR_TYPE_SIZE</code>. <var class="Fa">max_type</var> - must be <code class="Dv">PCI_INTR_TYPE_MSIX</code>, - <code class="Dv">PCI_INTR_TYPE_MSI</code>, or - <code class="Dv">PCI_INTR_TYPE_INTX</code>. The parameter does not mean - array index counts of <var class="Fa">counts</var>. The parameter means the - interrupt type which <code class="Fn">pci_intr_alloc</code>() tries to - allocate first. I.e., if the driver wants to allocate interrupts in the - following way:</p> -<div class="Bd Pp Li"> -<pre> 5 MSI-X - 1 MSI (if MSI-X allocation failed) - INTx (if MSI allocation failed either)</pre> -</div> -the driver should call <code class="Fn">pci_intr_alloc</code>() in the following - way: -<div class="Bd Pp Li"> -<pre> 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);</pre> -</div> -If the driver wants to allocate interrupts in the following way: -<div class="Bd Pp Li"> -<pre> hardware max number MSI-X - 1 MSI (if MSI-X allocation failed)</pre> -</div> -that is, the driver does not use INTx, the driver should call - <code class="Fn">pci_intr_alloc</code>() in the following way: -<div class="Bd Pp Li"> -<pre> 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);</pre> -</div> -If the driver wants to allocate interrupts in the following way: -<div class="Bd Pp Li"> -<pre> 3 MSI - INTx (if MSI allocation failed)</pre> -</div> -that is, the driver does not use MSI-X, the driver should call - <code class="Fn">pci_intr_alloc</code>() in the following way: -<div class="Bd Pp Li"> -<pre> 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);</pre> -</div> -If the driver wants to allocate interrupts in the following way: -<div class="Bd Pp Li"> -<pre> 1 MSI-X - 1 MSI - INTx (if MSI/MSI-X allocation failed)</pre> -</div> -that is, general usage, the driver should call simply - <code class="Fn">pci_intr_alloc</code>() in the following way: -<div class="Bd Pp Li"> -<pre> error = pci_intr_alloc(pa, ihps, NULL, 0);</pre> -</div> -<var class="Fa">max_type</var> is ignored in this case. - <code class="Fn">pci_intr_alloc</code>() returns zero on any allocation - function success, and non-zero on all allocation function failures. On - success, <var class="Fa">counts</var> is overwritten by a really allocated - count. I.e., if 5 MSI-X is allocated, <var class="Fa">counts</var> is -<div class="Bd Pp Li"> -<pre> counts[PCI_INTR_TYPE_MSIX] == 5 - counts[PCI_INTR_TYPE_MSI] == 0 - counts[PCI_INTR_TYPE_INTX] == 0</pre> -</div> -on return. -<p class="Pp" id="pci_intr_type"><a class="permalink" href="#pci_intr_type"><code class="Fn">pci_intr_type</code></a>() - returns the interrupt type of <var class="Fa">ih</var>. The return value is - <code class="Dv">PCI_INTR_TYPE_MSIX</code> for MSI-X, - <code class="Dv">PCI_INTR_TYPE_MSI</code> for MSI, and - <code class="Dv">PCI_INTR_TYPE_INTX</code> for others.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE - ALSO</a></h1> -<p class="Pp"><a class="Xr">pci_intr(9)</a></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> -<p class="Pp"><code class="Nm">pci_msi</code> support first appeared in - <span class="Ux">NetBSD 8.0</span>. Support is present on - <a class="permalink" href="#i386"><i class="Em" id="i386">i386</i></a>, - <a class="permalink" href="#amd64"><i class="Em" id="amd64">amd64</i></a> - and - <a class="permalink" href="#aarch64"><i class="Em" id="aarch64">aarch64</i></a> - architectures.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> -<p class="Pp">The <code class="Nm">pci_msi</code> interfaces were designed and - implemented by <span class="An">Kengo Nakahara</span> - <<a class="Mt" href="mailto:knakahara@NetBSD.org">knakahara@NetBSD.org</a>>.</p> -</section> -</div> -<table class="foot"> - <tr> - <td class="foot-date">January 12, 2021</td> - <td class="foot-os">NetBSD 10.1</td> - </tr> -</table> |