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