---
name: "rman_await_resource"
section: "9"
platform: "linux"
package: "freebsd-manpages"
version: "6.0-5"
release: "Debian 4.0 (Etch)"
platforms: ["linux"]
url: "https://new.carta.tech/rman_await_resource"
---

# rman\_await\_resource(9)

resource management functions

## 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 management abstraction. It is 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\_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 alignment, 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 happen. 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 exists, the caller has its device added to the list of consumers.

The **rman\_reserve\_resource**() function is used to reserve resources within a previously established region. It is a simplified interface 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 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\_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 resource which can only be safely used by one thread at a time. The arguments *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 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\_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 device which reserved the resource *r*.

## SEE ALSO

[bus\_activate\_resource(9)](/bus_activate_resource/9.md), [bus\_alloc\_resource(9)](/bus_alloc_resource/9.md), [bus\_release\_resource(9)](/bus_release_resource/9.md), [bus\_set\_resource(9)](/bus_set_resource/9.md), [mutex(9)](/mutex/9.md)

## AUTHORS

This manual page was written by Bruce M Simpson ⟨bms@spc.org⟩.