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