2000-06-08 21:00:12 +00:00
|
|
|
.\" -*- 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
|
2001-07-10 15:31:11 +00:00
|
|
|
.Os
|
2000-06-08 21:00:12 +00:00
|
|
|
.Sh NAME
|
2004-03-17 17:40:34 +00:00
|
|
|
.Nm bus_alloc_resource ,
|
|
|
|
.Nm bus_alloc_resource_any
|
2003-12-09 09:04:45 +00:00
|
|
|
.Nd allocate resources from a parent bus
|
2000-06-08 21:00:12 +00:00
|
|
|
.Sh SYNOPSIS
|
2001-10-01 16:09:29 +00:00
|
|
|
.In sys/param.h
|
|
|
|
.In sys/bus.h
|
2001-02-15 12:21:44 +00:00
|
|
|
.Pp
|
2001-10-01 16:09:29 +00:00
|
|
|
.In machine/bus.h
|
|
|
|
.In sys/rman.h
|
|
|
|
.In machine/resource.h
|
2000-06-08 21:00:12 +00:00
|
|
|
.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"
|
2004-03-17 17:40:34 +00:00
|
|
|
.Ft struct resource *
|
|
|
|
.Fn bus_alloc_resource_any "device_t dev" "int type" "int *rid" "u_int flags"
|
2000-06-08 21:00:12 +00:00
|
|
|
.Sh DESCRIPTION
|
|
|
|
This is an easy interface to the resource-management functions.
|
2001-07-14 19:41:16 +00:00
|
|
|
It hides the indirection through the parent's method table.
|
2000-06-08 21:00:12 +00:00
|
|
|
This function generally should be called in attach, but (except in some
|
2003-03-29 05:09:15 +00:00
|
|
|
rare cases) never earlier.
|
2000-06-08 21:00:12 +00:00
|
|
|
.Pp
|
2004-03-17 17:40:34 +00:00
|
|
|
The
|
|
|
|
.Fn bus_alloc_resource_any
|
|
|
|
function is a convenience wrapper for
|
|
|
|
.Fn bus_alloc_resource .
|
|
|
|
It sets the values for
|
|
|
|
.Fa start ,
|
|
|
|
.Fa end ,
|
|
|
|
and
|
|
|
|
.Fa count
|
|
|
|
to the default resource (see description of
|
|
|
|
.Fa start
|
|
|
|
below).
|
|
|
|
.Pp
|
|
|
|
The arguments are as follows:
|
2000-06-08 21:00:12 +00:00
|
|
|
.Bl -item
|
|
|
|
.It
|
|
|
|
.Fa dev
|
|
|
|
is the device that requests ownership of the resource.
|
2000-10-31 13:16:47 +00:00
|
|
|
Before allocation, the resource is owned by the parent bus.
|
2000-06-08 21:00:12 +00:00
|
|
|
.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.
|
2007-05-27 20:49:08 +00:00
|
|
|
For PCCARD, this is an index into the array of resources described by the PC Card's
|
|
|
|
CIS entry.
|
|
|
|
For PCI, the offset into pci config space which has the BAR to use to access
|
|
|
|
the resource.
|
2000-06-08 21:00:12 +00:00
|
|
|
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.
|
2004-01-27 06:04:15 +00:00
|
|
|
If you specify values of 0ul for
|
2003-03-29 05:09:15 +00:00
|
|
|
.Fa start
|
2004-01-27 06:04:15 +00:00
|
|
|
and ~0ul for
|
2003-03-29 05:09:15 +00:00
|
|
|
.Fa end
|
2003-05-21 15:49:01 +00:00
|
|
|
and 1 for
|
2003-03-29 05:09:15 +00:00
|
|
|
.Fa count ,
|
|
|
|
the default values for the bus are calculated.
|
2000-06-08 21:00:12 +00:00
|
|
|
.It
|
|
|
|
.Fa count
|
2004-01-27 06:04:15 +00:00
|
|
|
is the size of the resource.
|
|
|
|
For example, the size of an I/O port is usually 1 byte (but some devices
|
|
|
|
override this).
|
2000-06-20 15:05:06 +00:00
|
|
|
If you specified the default values for
|
2000-06-08 21:00:12 +00:00
|
|
|
.Fa start
|
|
|
|
and
|
|
|
|
.Fa end ,
|
2001-07-14 19:41:16 +00:00
|
|
|
then the default value of the bus is used if
|
2000-06-08 21:00:12 +00:00
|
|
|
.Fa count
|
|
|
|
is smaller than the default value and
|
|
|
|
.Fa count
|
2004-01-27 06:04:15 +00:00
|
|
|
is used, if it is bigger than the default value.
|
2000-06-08 21:00:12 +00:00
|
|
|
.It
|
|
|
|
.Fa flags
|
2000-06-20 15:05:06 +00:00
|
|
|
sets the flags for the resource.
|
|
|
|
You can set one or more of these flags:
|
2000-06-08 21:00:12 +00:00
|
|
|
.Bl -tag -width RF_SHAREABLE
|
|
|
|
.It Dv RF_ALLOCATED
|
|
|
|
resource has been reserved.
|
|
|
|
The resource still needs to be activated with
|
2003-03-29 05:09:15 +00:00
|
|
|
.Xr bus_activate_resource 9 .
|
2000-06-08 21:00:12 +00:00
|
|
|
.It Dv RF_ACTIVE
|
|
|
|
activate resource atomically.
|
|
|
|
.It Dv RF_SHAREABLE
|
|
|
|
resource permits contemporaneous sharing.
|
2004-01-27 06:04:15 +00:00
|
|
|
It should always be set unless you know that the resource cannot be shared.
|
2004-06-16 08:33:57 +00:00
|
|
|
It is the bus driver's task to filter out the flag if the bus does not
|
2004-01-27 06:04:15 +00:00
|
|
|
support sharing.
|
|
|
|
For example,
|
|
|
|
.Xr pccard 4
|
|
|
|
cannot share IRQs while
|
|
|
|
.Xr cardbus 4
|
|
|
|
can.
|
2000-06-08 21:00:12 +00:00
|
|
|
.It Dv RF_TIMESHARE
|
|
|
|
resource permits time-division sharing.
|
|
|
|
.El
|
|
|
|
.El
|
|
|
|
.Sh RETURN VALUES
|
|
|
|
A pointer to
|
2005-03-09 07:56:09 +00:00
|
|
|
.Va struct resource
|
2000-06-08 21:00:12 +00:00
|
|
|
is returned on success, a null pointer otherwise.
|
|
|
|
.Sh EXAMPLES
|
2004-01-27 16:16:31 +00:00
|
|
|
This is some example code that allocates a 32 byte I/O port range and an IRQ.
|
2000-06-20 15:05:06 +00:00
|
|
|
The values of
|
2000-06-08 21:00:12 +00:00
|
|
|
.Va portid
|
|
|
|
and
|
|
|
|
.Va irqid
|
|
|
|
should be saved in the softc of the device after these calls.
|
|
|
|
.Bd -literal
|
2005-08-09 11:55:18 +00:00
|
|
|
struct resource *portres, *irqres;
|
2000-06-08 21:00:12 +00:00
|
|
|
int portid, irqid;
|
|
|
|
|
|
|
|
portid = 0;
|
|
|
|
irqid = 0;
|
2001-07-14 19:41:16 +00:00
|
|
|
portres = bus_alloc_resource(dev, SYS_RES_IOPORT, &portid,
|
2004-01-27 16:16:31 +00:00
|
|
|
0ul, ~0ul, 32, RF_ACTIVE);
|
2004-03-17 17:40:34 +00:00
|
|
|
irqres = bus_alloc_resource_any(dev, SYS_RES_IRQ, &irqid,
|
|
|
|
RF_ACTIVE | RF_SHAREABLE);
|
2000-06-08 21:00:12 +00:00
|
|
|
.Ed
|
|
|
|
.Sh SEE ALSO
|
2003-03-29 05:09:15 +00:00
|
|
|
.Xr bus_activate_resource 9 ,
|
2011-04-29 21:36:45 +00:00
|
|
|
.Xr bus_adjust_resource 9 ,
|
2001-07-06 16:46:48 +00:00
|
|
|
.Xr bus_release_resource 9 ,
|
2000-06-08 21:00:12 +00:00
|
|
|
.Xr device 9 ,
|
2001-07-06 16:46:48 +00:00
|
|
|
.Xr driver 9
|
2000-06-08 21:00:12 +00:00
|
|
|
.Sh AUTHORS
|
2000-11-22 09:35:58 +00:00
|
|
|
.An -nosplit
|
2005-06-28 20:15:19 +00:00
|
|
|
This manual page was written by
|
2014-06-26 21:44:30 +00:00
|
|
|
.An Alexander Langer Aq Mt alex@big.endian.de
|
2000-06-08 21:00:12 +00:00
|
|
|
with parts by
|
2014-06-26 21:44:30 +00:00
|
|
|
.An Warner Losh Aq Mt imp@FreeBSD.org .
|