SVR5

cm_getval(D3)

cm_getval -- retrieve an entry from the resource manager database

Synopsis

   #include <sys/confmgr.h>
   #include <sys/ddi.h>
   
   int cm_getval(cm_args_t *args);

Description

cm_getval( ) retrieves the n-th value associated with a (key, param) pair from the resource manager database.

Arguments

args: Structure containing request arguments.

Return values

cm_getval( ) returns 0 for success. The following errnos are returned for failure:

EINVAL: if args is NULL, cm_param is NULL, or cm_key is invalid.
ENOSPC: if cm_vallen is less than the actual size of the value.
ENOENT: if there is no value for the n-th param.

Usage

The cm_key and cm_param elements of the args structure should be set to select the (key, param) pair whose value is to be retrieved. The cm_n args element should be set to select which instance of the value is to be returned. Value instances are numbered from 0 consecutively up to the last instance stored in the resource manager's database. Thus, all values associated with a (key, param) pair can be retrieved by looping through cm_getval calls starting with a cm_n of zero and continuing with incremented cm_n until cm_getval returns an ENOENT. If ENOSPC or success is returned, cm_vallen will be updated with the actual length of the stored value.

cm_getval( ) must be called as part of a read/write transaction, between calls to cm_begin_trans(D3) and cm_end_trans(D3).

Context and synchronization

User or blockable context.

Hardware applicability

All

Version applicability

ddi: 5, 5mp, 6, 6mp, 7, 7mp, 7.1, 7.1mp, 8, 8mp

Differences between versions

In DDI versions prior to version 8, cm_begin_trans(D3) and cm_end_trans(D3) are not supported. Calls to cm_getval( ) are only atomic with respect to other simultaneous resource manager database accesses.

References

cm_args(D4), cm_begin_trans(D3), cm_end_trans(D3), cm_params(D5), errnos(D5)

``Autoconfiguration'' in HDK Technical Reference

Examples

The following code fragment from a DDI 8 driver illustrates how to use the cm_getval( ) function to access the I/O address.

 1 int xxconfig( .....) {
 2         ...
 3         cm_args_t cmargs;
 4         RAMDDEVEXT *devext = (RAMDDEVEXT *)idata;

 5         switch (func) {
 6                 case CFG_ADD:
 7                         devext = kmem_alloc(sizeof(*devext), KM_NOSLEEP);
 8                         if  (devext == NULL)
 9                                {                    
10                                rc = ENOMEM;
11                                cmn_err(CE_NOTE, "kmem_alloc failed");
12                                break;
13                         }

14                 cm_begin_trans(key, RM_READ);
15                 cmargs.cm_key = key;
16                 cmargs.cm_param = CM_IOADDR;
17                 cmargs.cm_val = &devext->ioaddr;
18                 cmargs.cm_vallen = sizeof(devext->ioaddr);
19                 cmargs.cm_n = 0;
20                 rc = cm_getval(&cmargs);
21                 if (rc !=0 )
22                         {

23                         cm_end_trans(key);
24                         break;
25                         }
26                 *(void **)idata = devext;
27                 cm_end_trans(key);

28                  ...

Lines 7-13

Allocate memory for the devext structure (named RAMDDEVEXT in line 4) that represents the instance (idata ) structure for this device. Each time a device is opened, a new instance of the opened device is created. See ``Device instance'' in HDK Technical Reference.

Line 14

Call cm_begin_trans(D3) to begin the resource manager transaction. key is the parameter passed to the config(D2) entry point routine. This is the key that is associated with the device in the resource manager database. When the device is opened, the resource manager is checked to find the 'key' for the device. This code only needs to query the resource manager for information, so the mode is set to RM_READ (read only access).

Lines 15-26

Populate the cm_args(D4) structure for the CM_IOADDR parameter which identifies the start and end I/O address for the device. cmargs.cm_val is the buffer for this value and cmargs.cm_vallen is the length of this buffer. Any of the parameters documented on the cm_params(D5) manual page can be accessed in the same way.

cmargs.cm_n effectively terminates access to the resource database.

Line 20 then calls cm_getval( ), to retrieve the entry from the resource manager database, with the populated cm_args structure as an argument. The values to be retrieved are the ones that have been set up in the cm_args structure.

If the call to cm_getval( ) fails, the transaction is ended with a call to the cm_end_trans(D3) function. This code is simplified; a real driver should test for the various error conditions that are documented on the cm_getval( ) manual page and perhaps take additional actions.

Line 26

Pass the contents of the idata instance data structure back to the kernel. This value will be used by other entry point routines to identiy this particular device.

Line 27

Call cm_end_trans(D3) to close the resource manager transaction.