1.\" $OpenBSD: intrmap_create.9,v 1.4 2022/07/31 12:55:31 denis Exp $ 2.\" 3.\" Copyright (c) 2020 David Gwynne <dlg@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: July 31 2022 $ 18.Dt INTRMAP_CREATE 9 19.Os 20.Sh NAME 21.Nm intrmap_create , 22.Nm intrmap_destroy , 23.Nm intrmap_count , 24.Nm intrmap_cpu 25.Nd interrupt to CPU mapping API 26.Sh SYNOPSIS 27.In sys/intrmap.h 28.Ft struct intrmap * 29.Fo intrmap_create 30.Fa "const struct device *dv" 31.Fa "unsigned int nintr" 32.Fa "unsigned int maxintr" 33.Fa "unsigned int flags" 34.Fc 35.Ft void 36.Fn intrmap_destroy "struct intrmap *im" 37.Ft unsigned int 38.Fn intrmap_count "struct intrmap *im" 39.Ft struct cpu_info * 40.Fn intrmap_cpu "struct intrmap *im" "unsigned int index" 41.Sh DESCRIPTION 42The interrupt to CPU mapping API supports the use of multiple CPUs 43by hardware drivers. 44Drivers that can use multiple interrupts use the API to request a 45set of CPUs that they can establish those interrupts on. 46The API limits the requested number of interrupts to what is available 47on the system, and attempts to distribute the requested interrupts 48over those CPUs. 49On some platforms the API will filter the set of available CPUs. 50.\" to avoid hyperthreads, basically. 51.Pp 52.Fn intrmap_create 53allocates an interrupt map data structure for use by the driver 54identified by 55.Fa dv . 56The number of interrupts the hardware supports is specified via the 57.Fa nintr 58argument. 59The driver supplies the maximum number of interrupts it can support 60via 61.Fa maxintr , 62which, along with the number of available CPUs at the time the 63function is called, is used as a constraint on the number of requested 64interrupts. 65.Fa nintr 66may be zero to use the driver limit as the number of requested 67interrupts. 68The 69.Fa flags 70argument may have the following defines OR'ed together: 71.Bl -tag -width xxx -offset indent 72.It Dv INTRMAP_POWEROF2 73The hardware only supports a power of 2 number of interrupts, so 74constrain the number of supplied interrupts after the system and 75driver limits are applied. 76.El 77.Pp 78.Fn intrmap_destroy 79frees the memory associated with the interrupt map data structure 80passed via 81.Fa im . 82.Pp 83.Fn intrmap_count 84returns the number of interrupts that the driver can establish 85according to the 86.Fa im 87interrupt map. 88.Pp 89.Fn intrmap_cpu 90returns which CPU the interrupt specified in 91.Fa index 92should be established on according to the 93.Fa im 94interrupt map. 95Interrupts are identified as a number from 0 to the value returned by 96.Fn intrmap_count . 97.Sh CONTEXT 98.Fn intrmap_create , 99.Fn intrmap_destroy , 100.Fn intrmap_count , 101and 102.Fn intrmap_cpu 103can be called during autoconf, or from process context. 104.Sh RETURN VALUES 105.Fn intrmap_create 106returns a pointer to an interrupt mapping structure on success, or 107.Dv NULL 108on failure. 109.Pp 110.Fn intrmap_count 111returns the number of interrupts that were allocated for the driver 112to use. 113.Pp 114.Fn intrmap_cpu 115returns a pointer to the cpu_info structure for the CPU that the 116interrupt should be established on. 117.\" .Sh SEE ALSO 118.\" .Xr pci_intr_establish_cpuid 9 119.Sh HISTORY 120The interrupt mapping API is based on the if_ringmap API in 121.Dx . 122It was ported to 123.Ox 6.8 124by 125.An David Gwynne Aq Mt dlg@openbsd.org . 126