Return to bus_alloc_resource.9 CVS log

Up to [DragonFly] / src / share / man / man9

Remove '-*- nroff -*-'.

Lets make a habit not to put editor-related magic into our base
files.  They are redundant and useless.

    1: .\" Copyright (c) 2000 Alexander Langer
    2: .\"
    3: .\" All rights reserved.
    4: .\"
    5: .\" This program is free software.
    6: .\"
    7: .\" Redistribution and use in source and binary forms, with or without
    8: .\" modification, are permitted provided that the following conditions
    9: .\" are met:
   10: .\" 1. Redistributions of source code must retain the above copyright
   11: .\"    notice, this list of conditions and the following disclaimer.
   12: .\" 2. Redistributions in binary form must reproduce the above copyright
   13: .\"    notice, this list of conditions and the following disclaimer in the
   14: .\"    documentation and/or other materials provided with the distribution.
   15: .\"
   16: .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
   17: .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
   18: .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
   19: .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
   20: .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
   21: .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
   22: .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
   23: .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
   24: .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
   25: .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
   26: .\"
   27: .\" $FreeBSD: src/share/man/man9/bus_alloc_resource.9,v 1.2.2.10 2004/03/17 17:54:24 njl Exp $
   28: .\" $DragonFly: src/share/man/man9/bus_alloc_resource.9,v 1.4 2004/06/01 11:36:53 hmp Exp $
   29: .\"
   30: .Dd May 18, 2000
   31: .Dt BUS_ALLOC_RESOURCE 9
   32: .Os
   33: .Sh NAME
   34: .Nm bus_alloc_resource ,
   35: .Nm bus_alloc_resource_any
   36: .Nd alloc resources on a 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: .Fn bus_alloc_resource "device_t dev" "int type" "int *rid" "u_long start" "u_long end" "u_long count" "u_int flags"
   46: .Ft struct resource *
   47: .Fn bus_alloc_resource_any "device_t dev" "int type" "int *rid" "u_int flags"
   48: .Sh DESCRIPTION
   49: This is an easy interface to the resource-management functions.
   50: It hides the indirection through the parent's method table.
   51: This function generally should be called in attach, but (except in some
   52: race cases) never earlier.
   53: .Pp
   54: The
   55: .Fn bus_alloc_resource_any
   56: function is a convenience wrapper for
   57: .Fn bus_alloc_resource .
   58: It sets the values for
   59: .Fa start ,
   60: .Fa end ,
   61: and
   62: .Fa count
   63: to the default resource (see description of
   64: .Fa start
   65: below).
   66: .Pp
   67: The arguments are as follows:
   68: .Bl -item
   69: .It
   70: .Fa dev
   71: is the device that requests ownership of the resource.
   72: Before allocation, the resource is owned by the parent bus.
   73: .It
   74: .Fa type
   75: is the type of resource you want to allocate.
   76: It is one of:
   77: .Bl -tag -width SYS_RES_MEMORY
   78: .It Dv SYS_RES_IRQ
   79: for IRQs
   80: .It Dv SYS_RES_DRQ
   81: for ISA DMA lines
   82: .It Dv SYS_RES_IOPORT
   83: for I/O ports
   84: .It Dv SYS_RES_MEMORY
   85: for I/O memory
   86: .El
   87: .It
   88: .Fa rid
   89: points to a bus specific handle that identifies the resource being allocated.
   90: For ISA this is an index into an array of resources that have been setup
   91: for this device by either the PnP mechanism, or via the hints mechanism.
   92: For PCCARD, similar things are used as of writing,
   93: but that may change in the future with newcard.
   94: For PCI it just happens to be the offset into pci config space which has
   95: a word that describes the resource.
   96: The bus methods are free to change the RIDs that they are given as a parameter.
   97: You must not depend on the value you gave it earlier.
   98: .It
   99: .Fa start
  100: and
  101: .Fa end
  102: are the start/end addresses of the resource.
  103: If you specify values of
  104: .Dv 0
  105: for start and
  106: .Dv ~0
  107: for end, the default values for the bus are calculated.
  108: .It
  109: .Fa count
  110: is the size of the resource, e.g. the size of an I/O port (often
  111: .Dv 1
  112: on PCI and device-dependent on ISA and PCCARD).
  113: If you specified the default values for
  114: .Fa start
  115: and
  116: .Fa end ,
  117: then the default value of the bus is used if
  118: .Fa count
  119: is smaller than the default value and
  120: .Fa count
  121: is used, if it is bigger as the default value.
  122: .It
  123: .Fa flags
  124: sets the flags for the resource.
  125: You can set one or more of these flags:
  126: .Bl -tag -width RF_SHAREABLE
  127: .It Dv RF_ALLOCATED
  128: resource has been reserved.
  129: The resource still needs to be activated with
  130: .Xr rman_activate_resource 9 .
  131: .It Dv RF_ACTIVE
  132: activate resource atomically.
  133: .It Dv RF_SHAREABLE
  134: resource permits contemporaneous sharing.
  135: Should always be set unless you know, that the resource cannot be shared.
  136: It is the bus-code's task to filter out the flag if the bus doesn't
  137: support sharing, which is, for example, the case for pccard/cardbus,
  138: which can or cannot share devices, depending on the bus.
  139: .It Dv RF_TIMESHARE
  140: resource permits time-division sharing.
  141: .El
  142: .El
  143: .Sh RETURN VALUES
  144: A pointer to
  145: .Va struct res
  146: is returned on success, a null pointer otherwise.
  147: .Sh EXAMPLES
  148: This is some example code.
  149: The values of
  150: .Va portid
  151: and
  152: .Va irqid
  153: should be saved in the softc of the device after these calls.
  154: .Bd -literal
  155: 	struct resource *portres, irqres;
  156: 	int portid, irqid;
  157: 
  158: 	portid = 0;
  159: 	irqid = 0;
  160: 	portres = bus_alloc_resource(dev, SYS_RES_IOPORT, &portid,
  161: 			0ul, ~0ul, 32, RF_ACTIVE);
  162: 	irqres = bus_alloc_resource_any(dev, SYS_RES_IRQ, &irqid,
  163: 			RF_ACTIVE | RF_SHAREABLE);
  164: .Ed
  165: .Sh SEE ALSO
  166: .Xr bus_release_resource 9 ,
  167: .Xr device 9 ,
  168: .Xr driver 9
  169: .Sh AUTHORS
  170: .An -nosplit
  171: This man page was written by
  172: .An Alexander Langer Aq alex@big.endian.de
  173: with parts by
  174: .An Warner Losh Aq imp@FreeBSD.org .