1.\" -*- nroff -*- 2.\" 3.\" Copyright (c) 2000 Alexander Langer 4.\" 5.\" All rights reserved. 6.\" 7.\" This program is free software. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR 19.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 20.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 21.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, 22.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 23.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 24.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 25.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 26.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 27.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 28.\" 29.Dd October 30, 2025 30.Dt BUS_ALLOC_RESOURCE 9 31.Os 32.Sh NAME 33.Nm bus_alloc_resource , 34.Nm bus_alloc_resource_any , 35.Nm bus_alloc_resource_anywhere 36.Nd allocate resources from a parent bus 37.Sh SYNOPSIS 38.In sys/param.h 39.In sys/bus.h 40.Pp 41.In machine/bus.h 42.In sys/rman.h 43.In machine/resource.h 44.Ft struct resource * 45.Fo bus_alloc_resource 46.Fa "device_t dev" "int type" "int rid" "rman_res_t start" "rman_res_t end" 47.Fa "rman_res_t count" "u_int flags" 48.Fc 49.Ft struct resource * 50.Fn bus_alloc_resource_any "device_t dev" "int type" "int rid" "u_int flags" 51.Ft struct resource * 52.Fo bus_alloc_resource_anywhere 53.Fa "device_t dev" "int type" "int rid" "rman_res_t count" "u_int flags" 54.Fc 55.Sh DESCRIPTION 56This is an easy interface to the resource-management functions. 57It hides the indirection through the parent's method table. 58This function generally should be called in attach, but (except in some 59rare cases) never earlier. 60.Pp 61The 62.Fn bus_alloc_resource_any 63and 64.Fn bus_alloc_resource_anywhere 65functions are convenience wrappers for 66.Fn bus_alloc_resource . 67.Fn bus_alloc_resource_any 68sets 69.Fa start , 70.Fa end , 71and 72.Fa count 73to the default resource (see description of 74.Fa start 75below). 76.Fn bus_alloc_resource_anywhere 77sets 78.Fa start 79and 80.Fa end 81to the default resource and uses the provided 82.Fa count 83argument. 84.Pp 85The arguments are as follows: 86.Bl -item 87.It 88.Fa dev 89is the device that requests ownership of the resource. 90Before allocation, the resource is owned by the parent bus. 91.It 92.Fa type 93is the type of resource you want to allocate. 94It is one of: 95.Bl -tag -width SYS_RES_MEMORY 96.It Dv PCI_RES_BUS 97for PCI bus numbers 98.It Dv SYS_RES_IRQ 99for IRQs 100.It Dv SYS_RES_DRQ 101for ISA DMA lines 102.It Dv SYS_RES_IOPORT 103for I/O ports 104.It Dv SYS_RES_MEMORY 105for I/O memory 106.El 107.It 108.Fa rid 109is a bus specific handle that identifies the resource being allocated. 110For ISA this is an index into an array of resources that have been setup 111for this device by either the PnP mechanism, or via the hints mechanism. 112For PCCARD, this is an index into the array of resources described by the PC Card's 113CIS entry. 114For PCI, the offset into PCI config space which has the BAR to use to access 115the resource. 116.It 117.Fa start 118and 119.Fa end 120are the start/end addresses of the resource. 121If you specify values of 0ul for 122.Fa start 123and ~0ul for 124.Fa end 125and 1 for 126.Fa count , 127the default values for the bus are calculated. 128.It 129.Fa count 130is the size of the resource. 131For example, the size of an I/O port is usually 1 byte (but some devices 132override this). 133If you specified the default values for 134.Fa start 135and 136.Fa end , 137then the default value of the bus is used if 138.Fa count 139is smaller than the default value and 140.Fa count 141is used, if it is bigger than the default value. 142.It 143.Fa flags 144sets the flags for the resource. 145You can set one or more of these flags: 146.Bl -tag -width RF_SHAREABLE 147.It Dv RF_ALLOCATED 148resource has been reserved. 149The resource still needs to be activated with 150.Xr bus_activate_resource 9 . 151.It Dv RF_ACTIVE 152activate resource atomically. 153.It Dv RF_PREFETCHABLE 154resource is prefetchable. 155.It Dv RF_SHAREABLE 156resource permits contemporaneous sharing. 157It should always be set unless you know that the resource cannot be shared. 158It is the bus driver's task to filter out the flag if the bus does not 159support sharing. 160.It Dv RF_UNMAPPED 161do not establish implicit mapping when activated via 162.Xr bus_activate_resource 9 . 163.El 164.El 165.Sh RETURN VALUES 166A pointer to 167.Va struct resource 168is returned on success, a null pointer otherwise. 169.Sh EXAMPLES 170This is some example code that allocates a 32 byte I/O port range and an IRQ. 171.Bd -literal 172 struct resource *portres, *irqres; 173 174 portres = bus_alloc_resource(dev, SYS_RES_IOPORT, 0, 175 0ul, ~0ul, 32, RF_ACTIVE); 176 irqres = bus_alloc_resource_any(dev, SYS_RES_IRQ, 0, 177 RF_ACTIVE | RF_SHAREABLE); 178.Ed 179.Sh SEE ALSO 180.Xr bus_activate_resource 9 , 181.Xr bus_adjust_resource 9 , 182.Xr bus_map_resource 9 , 183.Xr bus_release_resource 9 , 184.Xr device 9 , 185.Xr driver 9 186.Sh AUTHORS 187.An -nosplit 188This manual page was written by 189.An Alexander Langer Aq Mt alex@big.endian.de 190with parts by 191.An Warner Losh Aq Mt imp@FreeBSD.org . 192