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