File:  [DragonFly] / src / share / man / man9 / bus_alloc_resource.9
Revision 1.3: download - view: text, annotated - select for diffs
Wed May 5 16:57:11 2004 UTC (10 years, 3 months ago) by hmp
Branches: MAIN
CVS tags: HEAD
Add bus_alloc_resource_any(9).

Obtained-from:	FreeBSD-4

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