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 March 10, 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 .Fn bus_alloc_resource_anywhere "device_t dev" "int type" "int *rid" "rman_res_t count" "u_int flags"
  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 SYS_RES_IRQ
  97 for IRQs
  98 .It Dv SYS_RES_DRQ
  99 for ISA DMA lines
 100 .It Dv SYS_RES_IOPORT
 101 for I/O ports
 102 .It Dv SYS_RES_MEMORY
 103 for I/O memory
 104 .El
 105 .It
 106 .Fa rid
 107 points to a bus specific handle that identifies the resource being allocated.
 108 For ISA this is an index into an array of resources that have been setup
 109 for this device by either the PnP mechanism, or via the hints mechanism.
 110 For PCCARD, this is an index into the array of resources described by the PC Card's
 111 CIS entry.
 112 For PCI, the offset into pci config space which has the BAR to use to access
 113 the resource.
 114 The bus methods are free to change the RIDs that they are given as a parameter.
 115 You must not depend on the value you gave it earlier.
 116 .It
 117 .Fa start
 118 and
 119 .Fa end
 120 are the start/end addresses of the resource.
 121 If you specify values of 0ul for
 122 .Fa start
 123 and ~0ul for
 124 .Fa end
 125 and 1 for
 126 .Fa count ,
 127 the default values for the bus are calculated.
 128 .It
 129 .Fa count
 130 is the size of the resource.
 131 For example, the size of an I/O port is usually 1 byte (but some devices
 132 override this).
 133 If you specified the default values for
 134 .Fa start
 135 and
 136 .Fa end ,
 137 then the default value of the bus is used if
 138 .Fa count
 139 is smaller than the default value and
 140 .Fa count
 141 is used, if it is bigger than the default value.
 142 .It
 143 .Fa flags
 144 sets the flags for the resource.
 145 You can set one or more of these flags:
 146 .Bl -tag -width RF_SHAREABLE
 147 .It Dv RF_ALLOCATED
 148 resource has been reserved.
 149 The resource still needs to be activated with
 150 .Xr bus_activate_resource 9 .
 151 .It Dv RF_ACTIVE
 152 activate resource atomically.
 153 .It Dv RF_SHAREABLE
 154 resource permits contemporaneous sharing.
 155 It should always be set unless you know that the resource cannot be shared.
 156 It is the bus driver's task to filter out the flag if the bus does not
 157 support sharing.
 158 For example,
 159 .Xr pccard 4
 160 cannot share IRQs while
 161 .Xr cardbus 4
 162 can.
 163 .It Dv RF_TIMESHARE
 164 resource permits time-division sharing.
 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 .