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 May 20, 2016 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 109points to 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. 116The bus methods are free to change the RIDs that they are given as a parameter. 117You must not depend on the value you gave it earlier. 118.It 119.Fa start 120and 121.Fa end 122are the start/end addresses of the resource. 123If you specify values of 0ul for 124.Fa start 125and ~0ul for 126.Fa end 127and 1 for 128.Fa count , 129the default values for the bus are calculated. 130.It 131.Fa count 132is the size of the resource. 133For example, the size of an I/O port is usually 1 byte (but some devices 134override this). 135If you specified the default values for 136.Fa start 137and 138.Fa end , 139then the default value of the bus is used if 140.Fa count 141is smaller than the default value and 142.Fa count 143is used, if it is bigger than the default value. 144.It 145.Fa flags 146sets the flags for the resource. 147You can set one or more of these flags: 148.Bl -tag -width RF_SHAREABLE 149.It Dv RF_ALLOCATED 150resource has been reserved. 151The resource still needs to be activated with 152.Xr bus_activate_resource 9 . 153.It Dv RF_ACTIVE 154activate resource atomically. 155.It Dv RF_PREFETCHABLE 156resource is prefetchable. 157.It Dv RF_SHAREABLE 158resource permits contemporaneous sharing. 159It should always be set unless you know that the resource cannot be shared. 160It is the bus driver's task to filter out the flag if the bus does not 161support sharing. 162For example, 163.Xr pccard 4 164cannot share IRQs while 165.Xr cardbus 4 166can. 167.It Dv RF_UNMAPPED 168do not establish implicit mapping when activated via 169.Xr bus_activate_resource 9 . 170.El 171.El 172.Sh RETURN VALUES 173A pointer to 174.Va struct resource 175is returned on success, a null pointer otherwise. 176.Sh EXAMPLES 177This is some example code that allocates a 32 byte I/O port range and an IRQ. 178The values of 179.Va portid 180and 181.Va irqid 182should be saved in the softc of the device after these calls. 183.Bd -literal 184 struct resource *portres, *irqres; 185 int portid, irqid; 186 187 portid = 0; 188 irqid = 0; 189 portres = bus_alloc_resource(dev, SYS_RES_IOPORT, &portid, 190 0ul, ~0ul, 32, RF_ACTIVE); 191 irqres = bus_alloc_resource_any(dev, SYS_RES_IRQ, &irqid, 192 RF_ACTIVE | RF_SHAREABLE); 193.Ed 194.Sh SEE ALSO 195.Xr bus_activate_resource 9 , 196.Xr bus_adjust_resource 9 , 197.Xr bus_map_resource 9 , 198.Xr bus_release_resource 9 , 199.Xr device 9 , 200.Xr driver 9 201.Sh AUTHORS 202.An -nosplit 203This manual page was written by 204.An Alexander Langer Aq Mt alex@big.endian.de 205with parts by 206.An Warner Losh Aq Mt imp@FreeBSD.org . 207