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.
19 June 2005
© 2005 The SCO Group, Inc. All rights reserved.
OpenServer 6 and UnixWare (SVR5) HDK - June 2005