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