RMAN(9) BSD Kernel Developer's Manual RMAN(9)NAME
rman, rman_activate_resource, rman_deactivate_resource, rman_fini,
rman_init, rman_manage_region, rman_release_resource,
rman_reserve_resource, 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, — resource management functions
SYNOPSIS
#include <sys/param.h>
#include <sys/rman.h>
int
rman_activate_resource(struct resource *r);
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);
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);
DESCRIPTION
The rman set of functions provides a flexible resource management
abstraction, they are used extensively by the bus management code. It
implements the abstractions of region and resource. A region 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, allocated 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 contemporaneous sharing */
#define RF_TIMESHARE 0x0008 /* resource permits time-division 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 desired align‐
ment 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 functions. It also
initializes any mutexes associated with the structure.
The rman_fini() function frees any structures associated with the struc‐
ture pointed to by the rm argument. If any of the resources within the
managed region have the RF_ALLOCATED flag set, it will return EBUSY; oth‐
erwise, 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 errors which add
multiple copies of the same region.
The rman_reserve_resource() function is used to reserve resources within
a previously established region.
The rman_make_alignment_flags() function returns the flag mask corre‐
sponding to the desired alignment size.
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 set‐
ting the RF_ACTIVE flag. If this is a time shared resource, and the
caller has not yet acquired the resource, the function returns 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_get_start(), rman_get_end(), rman_get_size(), and
rman_get_flags() functions return the bounds, size and flags of the pre‐
viously 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 retrieve 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 kernel virtual
address with a resource r. The rman_get_virtual() function can be used
to retrieve the KVA once set.
The rman_get_device() function returns a pointer to the device which
reserved the resource r.
SEE ALSObus_alloc_resource(9), bus_release_resource(9)AUTHORS
This manual page was written by Bruce M Simpson ⟨bms@spc.org⟩, later
revised by Hiten Pandya ⟨hmp@backplane.com⟩.
BSD May 12, 2003 BSD
