rsrcdbmgr_attach()

Reserve a system resource for a process

Synopsis:

#include <sys/rsrcdbmgr.h>
#include <sys/rsrcdbmsg.h>

int rsrcdbmgr_attach( rsrc_request_t * list,
                      int count );

Description:

Resource database manager

The resource database manager allocates and keeps track of system resources i.e. it manages these resources. The system resources currently tracked are:

memory
IRQs
DMA channels
I/O ports.

Major and minor device numbers are handled with separate rsrcdbmgr_devno_attach() and rsrcdbmgr_devno_detach() functions.

There are two main functions that drivers can use to communicate with the resource database:

rsrcdbmgr_attach()
rsrcdbmgr_detach()

The rsrcdbmgr_attach() function reserves a resource range(s) from the database of available resources for a process. Other processes won't be able to access this resource range until the resource is returned to the system (usually with the rsrcdbmgr_detach() call). The requested resources are returned in a list of _rsrc_request structures with the start and end fields filled in. The number of resources requested is specified in count.

The resource requests structure looks like this:

typedef struct _rsrc_request {
   uint64_t   length;    /* Length of resource desired */
   uint64_t   align;     /* Alignment of resource desired */
   uint64_t   start;     /* Start of resource range */
   uint64_t   end;       /* End of resource range */
   uint32_t   flags;     /* Resource type | Resource flags */
   uint32_t   zero[3];   /* Reserved */
} rsrc_request_t;

You must specify length and a resource type that's ORed into the flags field.

When you're finished with the resource, you must return it to the system. The easiest way to return the resource is to call rsrcdbmgr_detach() with the same start, end, and type (via the flags field) that was issued for the resource.

Resource types

The possible resource types (defined in <sys/rsrcdbmgr.h>) you can request are:

RSRCDBMGR_DMA_CHANNEL: DMA channel
RSRCDBMGR_IO_PORT: I/O port address
RSRCDBMGR_IRQ: Interrupt address
RSRCDBMGR_MEMORY: Memory address
RSRCDBMGR_PCI_MEMORY: PCI memory address

Flags

Valid flags (defined in <sys/rsrcdbmgr.h>) are:

RSRCDBMGR_FLAG_ALIGN: The contents of the align field are valid and the requested resource starts with the given alignment.
RSRCDBMGR_FLAG_RANGE: The contents of the start and end fields are valid and the requested resource is in the range start to end inclusive.
RSRCDBMGR_FLAG_SHARE: Allows other processes to have access to an allocated resource.
RSRCDBMGR_FLAG_TOPDOWN: Starts the search for a free resource block from end. If RSRCDBMGR_FLAG_RANGE is set, this flag starts the search from the end of the available range.

Returns:

EOK, or -1 if an error occurred (errno is set).

Errors:

EAGAIN: The resource request can't be filled.
EINVAL: Invalid argument.
ENOMEM: Insufficient memory to allocate internal data structures.

Examples:

The following examples don't seed the resource database with values, so they'll fail with EINVAL.

Example 1

/* 
 * Request one DMA Channel, with length 1, from the
 * entire range of available DMA channel resources.
 */
#include <stdio.h>
#include <sys/rsrcdbmgr.h>
#include <sys/rsrcdbmsg.h>

int main(int argc, char **argv) {
	int count;
	rsrc_request_t req;

	memset(&req, 0, sizeof(req));
	req.length = 1;
	req.flags = RSRCDBMGR_DMA_CHANNEL;
	count = 1;

	if (rsrcdbmgr_attach( &req, count) == -1) {
		perror("Problem attaching to resource ");
		exit(1);
	}

	printf("You can use DMA channel 0x%llx \n", 
		    req.start);

    ...
	/* Do something with the acquired resource */
    ...

	/* To return the resource to the database: */
	if (rsrcdbmgr_detach( &req, count) == -1) {
		perror("Problem detaching resource \n");
		exit(1);
	}

	return(0);
}

Example 2

/* 
 * Request memory that's 4 byte aligned
 * and has a length of 50.
 */

#include <stdio.h>
#include <sys/rsrcdbmgr.h>
#include <sys/rsrcdbmsg.h>

int main(int argc, char **argv) {
	int count;
	rsrc_request_t req;

	memset(&req, 0, sizeof(req));
	req.align = 4;
	req.length = 50;
	req.flags = RSRCDBMGR_FLAG_ALIGN | RSRCDBMGR_MEMORY;
	count = 1;

	if (rsrcdbmgr_attach(&req, count) == -1) {
		perror("Problem attaching to resource ");
		exit(1);
	}

	printf("You can use memory from 0x%llx 0x%llx inclusive. \n", 
			req.start, req.end );

    ...
	/* Do something with the acquired resource */
    ...

	/* To return the resource to the database: */
	if (rsrcdbmgr_detach( &req, count) == -1) {
		perror("Problem detaching resource \n");
		exit(1);
	}

	return(0);
}

Example 3

 
/* 
 * Request two resources:
 * I/O port 0 and an IRQ in the range 10-12
 * from the available resources.
 */
#include <stdio.h>
#include <sys/rsrcdbmgr.h>
#include <sys/rsrcdbmsg.h>

int main(int argc, char **argv) {
	int count;
	rsrc_request_t req[2];

	memset(req, 0, 2*sizeof(*req));
	req[0].start = 0;
	req[0].end = 0;
	req[0].length = 1; 
	req[0].flags = RSRCDBMGR_FLAG_RANGE | RSRCDBMGR_IO_PORT;

	req[1].start = 10;
	req[1].end = 12;
	req[1].length = 1; 
	req[1].flags = RSRCDBMGR_FLAG_RANGE | RSRCDBMGR_IRQ;
	count = 2;

	if (rsrcdbmgr_attach(req, count) == -1) {
		perror("Problem attaching to resource ");
		exit(1);
	}

	printf("You can use io-port 0x%llx \n",
			req[0].start);
	printf("You can use irq 0x%llx \n", 
			req[1].start);

    ...
	/* Do something with the acquired resource */
    ...

	/* To return the resource to the database: */
	if (rsrcdbmgr_detach(req, count) == -1) {
		perror("Problem detaching resource \n");
		exit(1);
	}

	return(0);
}

Classification:

QNX 6

Safety:
Cancellation point	Yes
Interrupt handler	No
Signal handler	Yes
Thread	Yes

rsrcdbmgr_attach()

Synopsis:

Library:

Description:

Resource database manager