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.Nd allocate resources from a parent bus 38.Sh SYNOPSIS 39.In sys/param.h 40.In sys/bus.h 41.Pp 42.In machine/bus.h 43.In sys/rman.h 44.In machine/resource.h 45.Ft struct resource * 46.Fo bus_alloc_resource 47.Fa "device_t dev" "int type" "int *rid" "rman_res_t start" "rman_res_t end" 48.Fa "rman_res_t count" "u_int flags" 49.Fc 50.Ft struct resource * 51.Fn bus_alloc_resource_any "device_t dev" "int type" "int *rid" "u_int flags" 52.Sh DESCRIPTION 53This is an easy interface to the resource-management functions. 54It hides the indirection through the parent's method table. 55This function generally should be called in attach, but (except in some 56rare cases) never earlier. 57.Pp 58The 59.Fn bus_alloc_resource_any 60function is a convenience wrapper for 61.Fn bus_alloc_resource . 62It sets the values for 63.Fa start , 64.Fa end , 65and 66.Fa count 67to the default resource (see description of 68.Fa start 69below). 70.Pp 71The arguments are as follows: 72.Bl -item 73.It 74.Fa dev 75is the device that requests ownership of the resource. 76Before allocation, the resource is owned by the parent bus. 77.It 78.Fa type 79is the type of resource you want to allocate. 80It is one of: 81.Bl -tag -width SYS_RES_MEMORY 82.It Dv SYS_RES_IRQ 83for IRQs 84.It Dv SYS_RES_DRQ 85for ISA DMA lines 86.It Dv SYS_RES_IOPORT 87for I/O ports 88.It Dv SYS_RES_MEMORY 89for I/O memory 90.El 91.It 92.Fa rid 93points to a bus specific handle that identifies the resource being allocated. 94For ISA this is an index into an array of resources that have been setup 95for this device by either the PnP mechanism, or via the hints mechanism. 96For PCCARD, this is an index into the array of resources described by the PC Card's 97CIS entry. 98For PCI, the offset into pci config space which has the BAR to use to access 99the resource. 100The bus methods are free to change the RIDs that they are given as a parameter. 101You must not depend on the value you gave it earlier. 102.It 103.Fa start 104and 105.Fa end 106are the start/end addresses of the resource. 107If you specify values of 0ul for 108.Fa start 109and ~0ul for 110.Fa end 111and 1 for 112.Fa count , 113the default values for the bus are calculated. 114.It 115.Fa count 116is the size of the resource. 117For example, the size of an I/O port is usually 1 byte (but some devices 118override this). 119If you specified the default values for 120.Fa start 121and 122.Fa end , 123then the default value of the bus is used if 124.Fa count 125is smaller than the default value and 126.Fa count 127is used, if it is bigger than the default value. 128.It 129.Fa flags 130sets the flags for the resource. 131You can set one or more of these flags: 132.Bl -tag -width RF_SHAREABLE 133.It Dv RF_ALLOCATED 134resource has been reserved. 135The resource still needs to be activated with 136.Xr bus_activate_resource 9 . 137.It Dv RF_ACTIVE 138activate resource atomically. 139.It Dv RF_SHAREABLE 140resource permits contemporaneous sharing. 141It should always be set unless you know that the resource cannot be shared. 142It is the bus driver's task to filter out the flag if the bus does not 143support sharing. 144For example, 145.Xr pccard 4 146cannot share IRQs while 147.Xr cardbus 4 148can. 149.It Dv RF_TIMESHARE 150resource permits time-division sharing. 151.El 152.El 153.Sh RETURN VALUES 154A pointer to 155.Va struct resource 156is returned on success, a null pointer otherwise. 157.Sh EXAMPLES 158This is some example code that allocates a 32 byte I/O port range and an IRQ. 159The values of 160.Va portid 161and 162.Va irqid 163should be saved in the softc of the device after these calls. 164.Bd -literal 165 struct resource *portres, *irqres; 166 int portid, irqid; 167 168 portid = 0; 169 irqid = 0; 170 portres = bus_alloc_resource(dev, SYS_RES_IOPORT, &portid, 171 0ul, ~0ul, 32, RF_ACTIVE); 172 irqres = bus_alloc_resource_any(dev, SYS_RES_IRQ, &irqid, 173 RF_ACTIVE | RF_SHAREABLE); 174.Ed 175.Sh SEE ALSO 176.Xr bus_activate_resource 9 , 177.Xr bus_adjust_resource 9 , 178.Xr bus_release_resource 9 , 179.Xr device 9 , 180.Xr driver 9 181.Sh AUTHORS 182.An -nosplit 183This manual page was written by 184.An Alexander Langer Aq Mt alex@big.endian.de 185with parts by 186.An Warner Losh Aq Mt imp@FreeBSD.org . 187