Kernel Functions for Drivers ddidevidcompare(9F)
NAME
ddidevidcompare, ddidevidfree, ddidevidinit,
ddidevidregister, ddidevidsizeof, ddidevidstrdecode,
ddidevidstrencode, ddidevidstrfree, ddidevidget,
ddidevidunregister, ddidevidvalid - kernel interfaces
for device ids
SYNOPSIS
int ddidevidcompare(ddidevidt devid1, ddidevidt devid2);
sizet ddidevidsizeof(ddidevidt devid);
int ddidevidinit(devinfot *dip, ushortt devidtype,
ushortt nbytes, void *id, ddidevidt *retdevid);
void ddidevidfree(ddidevidt devid);
int ddidevidregister(devinfot *dip, ddidevidt devid);
int ddidevidstrdecode(char *devidstr, ddidevidt *retdevid,
char **retminorname);
int ddidevidstrencode(ddidevidt devid, char *minorname);
int ddidevidstrfree(char *devidstr);
int ddidevidget(devinfot *dip, ddidevidt *retdevid);
void ddidevidunregister(devinfot *dip);
int ddidevidvalid(ddidevidt devid);
PARAMETERS
devid The device id address.
devidstr The devid and minorname represented as a
string.
SunOS 5.11 Last change: 18 Sep 2007 1
Kernel Functions for Drivers ddidevidcompare(9F)
devid1 The first of two device id addresses to be
compared calling ddidevidcompare().
devid2 The second of two device id addresses to be
compared calling ddidevidcompare().
dip A devinfo pointer, which identifies the dev-
ice.
devidtype The following device id types may be accepted
by the ddidevidinit() function:
DEVIDSCSI3WN World Wide Name associ-
ated with SCSI-3 devices.
DEVIDSCSISERIAL Vendor IDand serial
number associated with a
SCSI device. Note: This
may only be used if known
to be unique; otherwise a
fabricated device id must
be used.
DEVIDENCAP Device ID of another dev-
ice. This is for layered
device driver usage.
DEVIDFAB Fabricated device ID.
minorname The minor name to be encoded.
nbytes The length in bytes of device ID.
retdevid The return address of the device ID.
retminorname The return address of a minor name. Free
string with ddidevidstrfree().
INTERFACE LEVEL
SunOS 5.11 Last change: 18 Sep 2007 2
Kernel Functions for Drivers ddidevidcompare(9F)
Solaris DI specific (Solaris DI).
DESCRIPTION
The following routines are used to provide unique identif-
iers, device IDs, for devices. Specifically, kernel modules
use these interfaces to identify and locate devices,
independent of the device's physical connection or its logi-
cal device name or number.
ddidevidcompare() compares two device IDs byte-by-byte and
determines both equality and sort order.
ddidevidsizeof() returns the number of bytes allocated for
the passed in device ID (devid).
ddidevidinit() allocates memory and initializes the opaque
device ID structure. This function does not store the devid.
If the device id is not derived from the device's firmware,
it is the driver's responsibility to store the devid on some
reliable store. When a devidtype of either DEVIDSCSI3WN,
DEVIDSCSISERIAL, or DEVIDENCAP is accepted, an array of
bytes (id) must be passed in (nbytes).
When the devidtype DEVIDFAB is used, the array of bytes
(id) must be NUL and the length (nbytes) must be zero. The
fabricated device ids, DEVIDFAB will be initialized with
the machine's host id and a timestamp.
Drivers must free the memory allocated by this function,
using the ddidevidfree() function.
ddidevidfree() frees the memory allocated for the returned
devid by the ddidevidinit() and devidstrdecode() func-
tions.
ddidevidregister() registers the device ID address (devid)
with the DI framework, associating it with the devinfo
passed in (dip). The drivers must register device IDs at
attach time. See attach(9E).
ddidevidunregister() removes the device ID address from
the devinfo passed in (dip). Drivers must use this function
to unregister the device ID when devices are being detached.
This function does not free the space allocated for the
SunOS 5.11 Last change: 18 Sep 2007 3
Kernel Functions for Drivers ddidevidcompare(9F)
device ID. The driver must free the space allocated for the
device ID, using the ddidevidfree() function. See
detach(9E).
ddidevidvalid() validates the device ID (devid) passed in.
The driver must use this function to validate any fabricated
device ID that has been stored on a device.
ddidevidget() returns a pointer to the device ID structure
through retdevid if there is already a registered device ID
associated with the devinfo node. A driver can use this
interface to check and get the device ID associated with the
devinfo node. If no device ID is registered for the node
then it returns DIFAILURE.
The ddidevidstrencode() function encodes a devid and
minorname into a null-terminated ASCI string, returning a
pointer to that string. If both a devid and a minorname are
non-null, then a slash (/) is used to separate the devid
from the minorname in the encoded string. If minorname is
null, then only the devid is encoded. If the devid is null,
then the special string id0 is returned. Note that you can-
not compare the returned string against another string with
strcmp() to determine devid equality. The returned string
must be freed by calling devidstrfree().
The ddidevidstrdecode() function takes a string previ-
ously produced by the devidstrencode(3DEVID) or
ddidevidstrencode() function and decodes the contained
device ID and minorname, allocating and returning pointers
to the extracted parts through the retdevid and
retminorname arguments. If the special devidstr id0 was
specified then the returned device ID and minor name will
both be null. A non-null returned devid must be freed by the
caller through the ddidevidfree() function. A non-null
returned minor name must be freed by calling
ddidevidstrfree().
The ddidevidstrfree() function is used to free all
strings returned by the ddidevid functions (the
ddidevidstrencode() function return value and the
returned retminorname argument).
RETURN VALUES
ddidevidinit() returns the following values:
SunOS 5.11 Last change: 18 Sep 2007 4
Kernel Functions for Drivers ddidevidcompare(9F)
DISUCES Success.
DIFAILURE Out of memory. An invalid devidtype was
passed in.
ddidevidvalid() returns the following values:
DISUCES Valid device ID.
DIFAILURE Invalid device ID.
ddidevidregister() returns the following values:
DISUCES Success.
DIFAILURE Failure. The device ID is already
registered or the device ID is invalid.
ddidevidvalid() returns the following values:
DISUCES Valid device ID.
DIFAILURE Invalid device ID.
ddidevidget() returns the following values:
DISUCES Device ID is present and a pointer to it
is returned in retdevid.
DIFAILURE No device ID is defined for this
devinfo node.
SunOS 5.11 Last change: 18 Sep 2007 5
Kernel Functions for Drivers ddidevidcompare(9F)
ddidevidcompare() returns the following values:
-1 The first device ID is less than the second
device ID.
0 The first device ID is equal to the second
device ID.
1 The first device ID is greater than the second
device ID.
ddidevidsizeof() returns the size of the devid in bytes.
If called with a null, then the number of bytes that must be
allocated and initialized to determine the size of a com-
plete device ID is returned.
ddidevidstrencode() returns a value of null to indicate
failure. Failure can be caused by attempting to encode an
invalid devid. If the return value is non-null then the
caller must free the returned string by using the
devidstrfree() function.
ddidevidstrdecode() returns the following values:
DISUCES Success.
DIFAILURE Failure; the devidstr string was not
valid.
CONTEXT
These functions can be called from a user or kernel context.
SEE ALSO
devidget(3DEVID), , libdevid(3LIB), attributes(5),
attach(9E), detach(9E), kmemfree(9F)
Writing Device Drivers
SunOS 5.11 Last change: 18 Sep 2007 6
|
