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.\" $FreeBSD$ 30.\" 31.Dd May 18, 2000 32.Dt BUS_ALLOC_RESOURCE 9 33.Os 34.Sh NAME 35.Nm bus_alloc_resource , 36.Nm bus_alloc_resource_any 37.Nm bus_alloc_resource_anywhere 38.Nd allocate resources from a parent bus 39.Sh SYNOPSIS 40.In sys/param.h 41.In sys/bus.h 42.Pp 43.In machine/bus.h 44.In sys/rman.h 45.In machine/resource.h 46.Ft struct resource * 47.Fo bus_alloc_resource 48.Fa "device_t dev" "int type" "int *rid" "rman_res_t start" "rman_res_t end" 49.Fa "rman_res_t count" "u_int flags" 50.Fc 51.Ft struct resource * 52.Fn bus_alloc_resource_any "device_t dev" "int type" "int *rid" "u_int flags" 53.Fc 54.Ft struct resource * 55.Fn bus_alloc_resource_anywhere 56.Fa "device_t dev" "int type" "int *rid" "rman_res_t count" "u_int flags" 57.Sh DESCRIPTION 58This is an easy interface to the resource-management functions. 59It hides the indirection through the parent's method table. 60This function generally should be called in attach, but (except in some 61rare cases) never earlier. 62.Pp 63The 64.Fn bus_alloc_resource_any 65and 66.Fn bus_alloc_resource_anywhere 67functions are convenience wrappers for 68.Fn bus_alloc_resource . 69.Fn bus_alloc_resource_any 70sets 71.Fa start , 72.Fa end , 73and 74.Fa count 75to the default resource (see description of 76.Fa start 77below). 78.Fn bus_alloc_resource_anywhere 79sets 80.Fa start 81and 82.Fa end 83to the default resource and uses the provided 84.Fa count 85argument. 86.Pp 87The arguments are as follows: 88.Bl -item 89.It 90.Fa dev 91is the device that requests ownership of the resource. 92Before allocation, the resource is owned by the parent bus. 93.It 94.Fa type 95is the type of resource you want to allocate. 96It is one of: 97.Bl -tag -width SYS_RES_MEMORY 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_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. 160For example, 161.Xr pccard 4 162cannot share IRQs while 163.Xr cardbus 4 164can. 165.It Dv RF_TIMESHARE 166resource permits time-division sharing. 167.El 168.El 169.Sh RETURN VALUES 170A pointer to 171.Va struct resource 172is returned on success, a null pointer otherwise. 173.Sh EXAMPLES 174This is some example code that allocates a 32 byte I/O port range and an IRQ. 175The values of 176.Va portid 177and 178.Va irqid 179should be saved in the softc of the device after these calls. 180.Bd -literal 181 struct resource *portres, *irqres; 182 int portid, irqid; 183 184 portid = 0; 185 irqid = 0; 186 portres = bus_alloc_resource(dev, SYS_RES_IOPORT, &portid, 187 0ul, ~0ul, 32, RF_ACTIVE); 188 irqres = bus_alloc_resource_any(dev, SYS_RES_IRQ, &irqid, 189 RF_ACTIVE | RF_SHAREABLE); 190.Ed 191.Sh SEE ALSO 192.Xr bus_activate_resource 9 , 193.Xr bus_adjust_resource 9 , 194.Xr bus_release_resource 9 , 195.Xr device 9 , 196.Xr driver 9 197.Sh AUTHORS 198.An -nosplit 199This manual page was written by 200.An Alexander Langer Aq Mt alex@big.endian.de 201with parts by 202.An Warner Losh Aq Mt imp@FreeBSD.org . 203