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 cpuid);
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, device_t dev);
uint32_t
rman_make_alignment_flags(size_t size);

u_long
rman_get_start(struct resource *r);
u_long
rman_get_end(struct resource *r);
device_t
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 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 functions. 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 return 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 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 corresponding 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 setting 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 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 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 ALSO
bus_alloc_resource(9), bus_release_resource(9)

AUTHORS
-nosplit This manual page was written by Bruce M Simpson <bms@spc.org>, later revised by Hiten Pandya <hmp@backplane.com>.