rman(9)

NAME

rman, rman_activate_resource, rman_await_resource, rman_deactivate_resource, rman_fini, rman_init,
rman_manage_region,
rman_release_resource, rman_reserve_resource, rman_reserve_resource_bound, rman_make_alignment_flags,
rman_get_start,
rman_get_end, rman_get_device, rman_get_size,
rman_get_flags,
rman_set_virtual, rman_get_virtual, rman_set_bustag,
rman_get_bustag,
rman_set_bushandle, rman_get_bushandle, rman_set_rid,
rman_get_rid resource management functions

SYNOPSIS

#include <sys/rman.h>
int
rman_activate_resource(struct resource *r);
int
rman_await_resource(struct resource *r, int pri2, int timo);
int
rman_deactivate_resource(struct resource *r);
int
rman_fini(struct rman *rm);
int
rman_init(struct rman *rm);
int
rman_manage_region(struct rman  *rm,  u_long  start,  u_long
end);
int
rman_release_resource(struct resource *r);
struct resource *
rman_reserve_resource(struct  rman *rm, u_long start, u_long
end,
        u_long count, u_int flags, struct device *dev);
struct resource *
rman_reserve_resource_bound(struct rman *rm,  u_long  start,
u_long end,
        u_long  count,  u_long  bound,  u_int  flags, struct
device *dev);
uint32_t
rman_make_alignment_flags(uint32_t size);
u_long
rman_get_start(struct resource *r);
u_long
rman_get_end(struct resource *r);
struct device *
rman_get_device(struct resource *r);
u_long
rman_get_size(struct resource *r);
u_int
rman_get_flags(struct resource *r);
void
rman_set_virtual(struct resource *r, void *v);
void *
rman_get_virtual(struct resource *r);
void
rman_set_bustag(struct resource *r, bus_space_tag_t t);
bus_space_tag_t
rman_get_bustag(struct resource *r);
void
rman_set_bushandle(struct  resource  *r,  bus_space_handle_t
h);
bus_space_handle_t
rman_get_bushandle(struct resource *r);
void
rman_set_rid(struct resource *r, int rid);
int
rman_get_rid(struct resource *r);

DESCRIPTION

The rman set of functions provides a flexible resource man
agement abstraction. It is used extensively by the bus management
code. It implements the abstractions of region and resource. A re
gion descriptor is used to manage a region; this could be memory or some
other form of bus space.
Each region has a set of bounds. Within these bounds, allo
cated segments may reside. Each segment, termed a resource, has several
properties which are represented by a 16-bit flag register, as follows.
#define RF_ALLOCATED 0x0001 /* resource has been reserved
*/ #define RF_ACTIVE 0x0002 /* resource allocation has
been activated */ #define RF_SHAREABLE 0x0004 /* resource permits contempo
raneous sharing */ #define RF_TIMESHARE 0x0008 /* resource permits time-di
vision sharing */ #define RF_WANTED 0x0010 /* somebody is waiting for
this resource */ #define RF_FIRSTSHARE 0x0020 /* first in sharing list */ #define RF_PREFETCHABLE 0x0040 /* resource is prefetchable
*/
The remainder of the flag bits are used to represent the de
sired alignment of the resource within the region.
The rman_init() function initializes the region descriptor,
pointed to by the rm argument, for use with the resource management func
tions. It also initializes any mutexes associated with the structure.
The rman_fini() function frees any structures associated
with the structure pointed to by the rm argument. If any of the resources
within the managed region have the RF_ALLOCATED flag set, it will re
turn EBUSY; otherwise, any mutexes associated with the structure will be
released and destroyed, and the function will return 0.
The rman_manage_region() function establishes the concept of
a region
which is under rman control. The rman argument points to
the region descriptor. The start and end arguments specify the bounds
of the region.
NOTE: This interface is not robust against programming er
rors which add multiple copies of the same region.
The rman_reserve_resource_bound() function is where the bulk
of the rman
logic is located. It attempts to reserve a contiguous range
in the specified region rm for the use of the device dev. The caller
can specify the start and end of an acceptable range, as well as align
ment, and the code will attempt to find a free segment which fits. The
start argument is the lowest acceptable starting value of the resource.
The end argument is the highest acceptable ending value of the resource.
Therefore, start + count - 1 must be <= end for any allocation to hap
pen. The default behavior is to allocate an exclusive segment, unless
the RF_SHAREABLE or RF_TIMESHARE flags are set, in which case a
shared segment will be allocated. If this shared segment already ex
ists, the caller has its device added to the list of consumers.
The rman_reserve_resource() function is used to reserve re
sources within a previously established region. It is a simplified inter
face to
rman_reserve_resource_bound() which passes 0 for the flags
argument.
The rman_make_alignment_flags() function returns the flag
mask corresponding to the desired alignment size. This should be used
when calling
rman_reserve_resource_bound().
The rman_release_resource() function releases the reserved
resource r. It may attempt to merge adjacent free resources.
The rman_activate_resource() function marks a resource as
active, by setting the RF_ACTIVE flag. If this is a time shared resource,
and the caller has not yet acquired the resource, the function re
turns EBUSY.
The rman_deactivate_resource() function marks a resource r
as inactive, by clearing the RF_ACTIVE flag. If other consumers are
waiting for this range, it will wakeup their threads.
The rman_await_resource() function performs an asynchronous
wait for a resource r to become inactive, that is, for the RF_ACTIVE
flag to be cleared. It is used to enable cooperative sharing of a re
source which can only be safely used by one thread at a time. The argu
ments pri and
timo are passed to the rman_await_resource() function.
The rman_get_start(), rman_get_end(), rman_get_size(), and rman_get_flags() functions return the bounds, size and flags
of the previously reserved resource r.
The rman_set_bustag() function associates a bus_space_tag_t
t with the
resource r. The rman_get_bustag() function is used to re
trieve this tag once set.
The rman_set_bushandle() function associates a
bus_space_handle_t h with
the resource r. The rman_get_bushandle() function is used
to retrieve this handle once set.
The rman_set_virtual() function is used to associate a ker
nel virtual
address with a resource r. The rman_get_virtual() function
can be used to retrieve the KVA once set.
The rman_set_rid() function associates a resource identifier
with a
resource r. The rman_get_rid() function retrieves this RID.
The rman_get_device() function returns a pointer to the de
vice which reserved the resource r.

AUTHORS

This manual page was written by Bruce M Simpson
<bms@spc.org>.
BSD March 15, 2005

docs.sk

comprehensive documentation repository

In section

See also

rman(9)

NAME

SYNOPSIS

DESCRIPTION

SEE ALSO

AUTHORS