share/man/man9/bus_alloc_resource.9

   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 April 28, 2016
  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 .Ft struct resource *
  54 .Fo bus_alloc_resource_anywhere
  55 .Fa "device_t dev" "int type" "int *rid" "rman_res_t count" "u_int flags"
  56 .Fc
  57 .Sh DESCRIPTION
  58 This is an easy interface to the resource-management functions.
  59 It hides the indirection through the parent's method table.
  60 This function generally should be called in attach, but (except in some
  61 rare cases) never earlier.
  62 .Pp
  63 The
  64 .Fn bus_alloc_resource_any
  65 and
  66 .Fn bus_alloc_resource_anywhere
  67 functions are convenience wrappers for
  68 .Fn bus_alloc_resource .
  69 .Fn bus_alloc_resource_any
  70 sets
  71 .Fa start ,
  72 .Fa end ,
  73 and
  74 .Fa count
  75 to the default resource (see description of
  76 .Fa start
  77 below).
  78 .Fn bus_alloc_resource_anywhere
  79 sets
  80 .Fa start
  81 and
  82 .Fa end
  83 to the default resource and uses the provided
  84 .Fa count
  85 argument.
  86 .Pp
  87 The arguments are as follows:
  88 .Bl -item
  89 .It
  90 .Fa dev
  91 is the device that requests ownership of the resource.
  92 Before allocation, the resource is owned by the parent bus.
  93 .It
  94 .Fa type
  95 is the type of resource you want to allocate.
  96 It is one of:
  97 .Bl -tag -width SYS_RES_MEMORY
  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_SHAREABLE
 156 resource permits contemporaneous sharing.
 157 It should always be set unless you know that the resource cannot be shared.
 158 It is the bus driver's task to filter out the flag if the bus does not
 159 support sharing.
 160 For example,
 161 .Xr pccard 4
 162 cannot share IRQs while
 163 .Xr cardbus 4
 164 can.
 165 .El
 166 .El
 167 .Sh RETURN VALUES
 168 A pointer to
 169 .Va struct resource
 170 is returned on success, a null pointer otherwise.
 171 .Sh EXAMPLES
 172 This is some example code that allocates a 32 byte I/O port range and an IRQ.
 173 The values of
 174 .Va portid
 175 and
 176 .Va irqid
 177 should be saved in the softc of the device after these calls.
 178 .Bd -literal
 179         struct resource *portres, *irqres;
 180         int portid, irqid;
 181
 182         portid = 0;
 183         irqid = 0;
 184         portres = bus_alloc_resource(dev, SYS_RES_IOPORT, &portid,
 185                         0ul, ~0ul, 32, RF_ACTIVE);
 186         irqres = bus_alloc_resource_any(dev, SYS_RES_IRQ, &irqid,
 187                         RF_ACTIVE | RF_SHAREABLE);
 188 .Ed
 189 .Sh SEE ALSO
 190 .Xr bus_activate_resource 9 ,
 191 .Xr bus_adjust_resource 9 ,
 192 .Xr bus_release_resource 9 ,
 193 .Xr device 9 ,
 194 .Xr driver 9
 195 .Sh AUTHORS
 196 .An -nosplit
 197 This manual page was written by
 198 .An Alexander Langer Aq Mt alex@big.endian.de
 199 with parts by
 200 .An Warner Losh Aq Mt imp@FreeBSD.org .