1.\" Copyright (c) 2000 Alexander Langer 2.\" 3.\" All rights reserved. 4.\" 5.\" This program is free software. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR 17.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 18.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 19.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, 20.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 21.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 22.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 23.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 24.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 25.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 26.\" 27.\" $FreeBSD: src/share/man/man9/bus_alloc_resource.9,v 1.2.2.10 2004/03/17 17:54:24 njl Exp $ 28.\" $DragonFly: src/share/man/man9/bus_alloc_resource.9,v 1.5 2004/07/16 10:38:01 joerg Exp $ 29.\" 30.Dd May 18, 2000 31.Dt BUS_ALLOC_RESOURCE 9 32.Os 33.Sh NAME 34.Nm bus_alloc_resource , 35.Nm bus_alloc_resource_any 36.Nd alloc resources on a 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.Fn bus_alloc_resource "device_t dev" "int type" "int *rid" "u_long start" "u_long end" "u_long count" "u_int flags" 46.Ft struct resource * 47.Fn bus_alloc_resource_any "device_t dev" "int type" "int *rid" "u_int flags" 48.Sh DESCRIPTION 49This is an easy interface to the resource-management functions. 50It hides the indirection through the parent's method table. 51This function generally should be called in attach, but (except in some 52race cases) never earlier. 53.Pp 54The 55.Fn bus_alloc_resource_any 56function is a convenience wrapper for 57.Fn bus_alloc_resource . 58It sets the values for 59.Fa start , 60.Fa end , 61and 62.Fa count 63to the default resource (see description of 64.Fa start 65below). 66.Pp 67The arguments are as follows: 68.Bl -item 69.It 70.Fa dev 71is the device that requests ownership of the resource. 72Before allocation, the resource is owned by the parent bus. 73.It 74.Fa type 75is the type of resource you want to allocate. 76It is one of: 77.Bl -tag -width SYS_RES_MEMORY 78.It Dv SYS_RES_IRQ 79for IRQs 80.It Dv SYS_RES_DRQ 81for ISA DMA lines 82.It Dv SYS_RES_IOPORT 83for I/O ports 84.It Dv SYS_RES_MEMORY 85for I/O memory 86.El 87.It 88.Fa rid 89points to a bus specific handle that identifies the resource being allocated. 90For ISA this is an index into an array of resources that have been setup 91for this device by either the PnP mechanism, or via the hints mechanism. 92For PCCARD, similar things are used as of writing, 93but that may change in the future with newcard. 94For PCI it just happens to be the offset into pci config space which has 95a word that describes the resource. 96The bus methods are free to change the RIDs that they are given as a parameter. 97You must not depend on the value you gave it earlier. 98.It 99.Fa start 100and 101.Fa end 102are the start/end addresses of the resource. 103If you specify values of 104.Dv 0 105for start and 106.Dv ~0 107for end, the default values for the bus are calculated. 108.It 109.Fa count 110is the size of the resource, e.g. the size of an I/O port (often 111.Dv 1 112on PCI and device-dependent on ISA and PCCARD). 113If you specified the default values for 114.Fa start 115and 116.Fa end , 117then the default value of the bus is used if 118.Fa count 119is smaller than the default value and 120.Fa count 121is used, if it is bigger than the default value. 122.It 123.Fa flags 124sets the flags for the resource. 125You can set one or more of these flags: 126.Bl -tag -width RF_SHAREABLE 127.It Dv RF_ALLOCATED 128resource has been reserved. 129The resource still needs to be activated with 130.Xr rman_activate_resource 9 . 131.It Dv RF_ACTIVE 132activate resource atomically. 133.It Dv RF_SHAREABLE 134resource permits contemporaneous sharing. 135Should always be set unless you know, that the resource cannot be shared. 136It is the bus-code's task to filter out the flag if the bus doesn't 137support sharing, which is, for example, the case for pccard/cardbus, 138which can or cannot share devices, depending on the bus. 139.It Dv RF_TIMESHARE 140resource permits time-division sharing. 141.El 142.El 143.Sh RETURN VALUES 144A pointer to 145.Va struct res 146is returned on success, a null pointer otherwise. 147.Sh EXAMPLES 148This is some example code. 149The values of 150.Va portid 151and 152.Va irqid 153should be saved in the softc of the device after these calls. 154.Bd -literal 155 struct resource *portres, irqres; 156 int portid, irqid; 157 158 portid = 0; 159 irqid = 0; 160 portres = bus_alloc_resource(dev, SYS_RES_IOPORT, &portid, 161 0ul, ~0ul, 32, RF_ACTIVE); 162 irqres = bus_alloc_resource_any(dev, SYS_RES_IRQ, &irqid, 163 RF_ACTIVE | RF_SHAREABLE); 164.Ed 165.Sh SEE ALSO 166.Xr bus_release_resource 9 , 167.Xr device 9 , 168.Xr driver 9 169.Sh AUTHORS 170.An -nosplit 171This man page was written by 172.An Alexander Langer Aq alex@big.endian.de 173with parts by 174.An Warner Losh Aq imp@FreeBSD.org . 175