160 lines
4.9 KiB
Groff
160 lines
4.9 KiB
Groff
.\" -*- nroff -*-
|
|
.\"
|
|
.\" Copyright (c) 2000 Alexander Langer
|
|
.\"
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" This program is free software.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
|
|
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
|
|
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
|
|
.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
|
|
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
|
|
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
|
|
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
|
|
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
|
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
|
|
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd May 18, 2000
|
|
.Dt BUS_ALLOC_RESOURCE 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm bus_alloc_resource
|
|
.Nd alloc resources on a bus
|
|
.Sh SYNOPSIS
|
|
.Fd #include <sys/param.h>
|
|
.Fd #include <sys/bus.h>
|
|
.Pp
|
|
.Fd #include <machine/bus.h>
|
|
.Fd #include <sys/rman.h>
|
|
.Fd #include <machine/resource.h>
|
|
.Ft struct resource *
|
|
.Fn bus_alloc_resource "device_t dev" "int type" "int *rid" "u_long start" "u_long end" "u_long count" "u_int flags"
|
|
.Sh DESCRIPTION
|
|
This is an easy interface to the resource-management functions.
|
|
It hides the indirection through the parent's method table.
|
|
This function generally should be called in attach, but (except in some
|
|
race cases) never earlier.
|
|
.Pp
|
|
Its arguments are as follows:
|
|
.Bl -item
|
|
.It
|
|
.Fa dev
|
|
is the device that requests ownership of the resource.
|
|
Before allocation, the resource is owned by the parent bus.
|
|
.It
|
|
.Fa type
|
|
is the type of resource you want to allocate.
|
|
It is one of:
|
|
.Bl -tag -width SYS_RES_MEMORY
|
|
.It Dv SYS_RES_IRQ
|
|
for IRQs
|
|
.It Dv SYS_RES_DRQ
|
|
for ISA DMA lines
|
|
.It Dv SYS_RES_IOPORT
|
|
for I/O ports
|
|
.It Dv SYS_RES_MEMORY
|
|
for I/O memory
|
|
.El
|
|
.It
|
|
.Fa rid
|
|
points to a bus specific handle that identifies the resource being allocated.
|
|
For ISA this is an index into an array of resources that have been setup
|
|
for this device by either the PnP mechanism, or via the hints mechanism.
|
|
For PCCARD, similar things are used as of writing,
|
|
but that may change in the future with newcard.
|
|
For PCI it just happens to be the offset into pci config space which has
|
|
a word that describes the resource.
|
|
The bus methods are free to change the RIDs that they are given as a parameter.
|
|
You must not depend on the value you gave it earlier.
|
|
.It
|
|
.Fa start
|
|
and
|
|
.Fa end
|
|
are the start/end addresses of the resource.
|
|
If you specify values of
|
|
.Dv 0
|
|
for start and
|
|
.Dv ~0
|
|
for end, the default values for the bus are calculated.
|
|
.It
|
|
.Fa count
|
|
is the size of the resource, e.g. the size of an I/O port (often
|
|
.Dv 1
|
|
on PCI and device-dependent on ISA and PCCARD).
|
|
If you specified the default values for
|
|
.Fa start
|
|
and
|
|
.Fa end ,
|
|
then the default value of the bus is used if
|
|
.Fa count
|
|
is smaller than the default value and
|
|
.Fa count
|
|
is used, if it is bigger as the default value.
|
|
.It
|
|
.Fa flags
|
|
sets the flags for the resource.
|
|
You can set one or more of these flags:
|
|
.Bl -tag -width RF_SHAREABLE
|
|
.It Dv RF_ALLOCATED
|
|
resource has been reserved.
|
|
The resource still needs to be activated with
|
|
.Xr rman_activate_resource 9 .
|
|
.It Dv RF_ACTIVE
|
|
activate resource atomically.
|
|
.It Dv RF_SHAREABLE
|
|
resource permits contemporaneous sharing.
|
|
Should always be set unless you know, that the resource cannot be shared.
|
|
It is the bus-code's task to filter out the flag if the bus doesn't
|
|
support sharing, which is, for example, the case for pccard/cardbus,
|
|
which can or cannot share devices, depending on the bus.
|
|
.It Dv RF_TIMESHARE
|
|
resource permits time-division sharing.
|
|
.El
|
|
.El
|
|
.Sh RETURN VALUES
|
|
A pointer to
|
|
.Va struct res
|
|
is returned on success, a null pointer otherwise.
|
|
.Sh EXAMPLES
|
|
This is some example code.
|
|
The values of
|
|
.Va portid
|
|
and
|
|
.Va irqid
|
|
should be saved in the softc of the device after these calls.
|
|
.Bd -literal
|
|
struct resource *portres, irqres;
|
|
int portid, irqid;
|
|
|
|
portid = 0;
|
|
irqid = 0;
|
|
portres = bus_alloc_resource(dev, SYS_RES_IOPORT, &portid,
|
|
0ul, ~0ul, 32, RF_ACTIVE);
|
|
irqres = bus_alloc_resource(dev, SYS_RES_IRQ, &irqid,
|
|
0ul, ~0ul, 1, RF_ACTIVE | RF_SHAREABLE);
|
|
.Ed
|
|
.Sh SEE ALSO
|
|
.Xr bus_release_resource 9 ,
|
|
.Xr device 9 ,
|
|
.Xr driver 9
|
|
.Sh AUTHORS
|
|
.An -nosplit
|
|
This man page was written by
|
|
.An Alexander Langer Aq alex@big.endian.de
|
|
with parts by
|
|
.An Warner Losh Aq imp@FreeBSD.org .
|