Kernel Functions for Drivers ddi_devid_compare(9F)
NAME
ddi_devid_compare, ddi_devid_free, ddi_devid_init,
ddi_devid_register, ddi_devid_sizeof, ddi_devid_str_decode,
ddi_devid_str_encode, ddi_devid_str_free, ddi_devid_get,
ddi_devid_unregister, ddi_devid_valid - kernel interfaces
for device idsSYNOPSIS
int ddi_devid_compare(ddi_devid_t devid1, ddi_devid_t devid2);
size_t ddi_devid_sizeof(ddi_devid_t devid);
int ddi_devid_init(dev_info_t *dip, ushort_t devid_type,
ushort_t nbytes, void *id, ddi_devid_t *retdevid);
void ddi_devid_free(ddi_devid_t devid);
int ddi_devid_register(dev_info_t *dip, ddi_devid_t devid);
int ddi_devid_str_decode(char *devidstr, ddi_devid_t *retdevid,
char **retminor_name);
int ddi_devid_str_encode(ddi_devid_t devid, char *minor_name);
int ddi_devid_str_free(char *devidstr);
int ddi_devid_get(dev_info_t *dip, ddi_devid_t *retdevid);
void ddi_devid_unregister(dev_info_t *dip);
int ddi_devid_valid(ddi_devid_t devid);
PARAMETERS
devid The device id address.devidstr The devid and minor_name represented as a
string.SunOS 5.11 Last change: 22 Jun 2010 1
Kernel Functions for Drivers ddi_devid_compare(9F)
devid1 The first of two device id addresses to becompared calling ddi_devid_compare().
devid2 The second of two device id addresses to becompared calling ddi_devid_compare().
dip A dev_info pointer, which identifies the dev-
ice.devid_type The following device id types may be accepted
by the ddi_devid_init() function:
DEVID_SCSI3_WWN World Wide Name associ-
ated with SCSI-3 devices.
DEVID_SCSI_SERIAL 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.DEVID_ENCAP Device ID of another dev-
ice. This is for layered device driver usage.DEVID_FAB Fabricated device ID.
minor_name The minor name to be encoded.
nbytes The length in bytes of device ID. retdevid The return address of the device ID.retminor_name The return address of a minor name. Free
string with ddi_devid_str_free().
INTERFACE LEVEL
SunOS 5.11 Last change: 22 Jun 2010 2
Kernel Functions for Drivers ddi_devid_compare(9F)
Solaris DDI specific (Solaris DDI).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.The ddi_devid_compare() function compares two device IDs
byte-by-byte and determines both equality and sort order.
The ddi_devid_sizeof() function returns the number of bytes
allocated for the passed in device ID (devid).The ddi_devid_init() function allocates memory and initial-
izes 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 tostore the devid on some reliable store. When a devid_type of
either DEVID_SCSI3_WWN, DEVID_SCSI_SERIAL, or DEVID_ENCAP is
accepted, an array of bytes (id) must be passed in (nbytes).When the devid_type DEVID_FAB is used, the array of bytes
(id) must be NULL and the length (nbytes) must be zero. Thefabricated device ids, DEVID_FAB will be initialized with
the machine's host id and a timestamp. Drivers must free the memory allocated by this function,using the ddi_devid_free() function.
The ddi_devid_free() function frees the memory allocated for
the returned devid by the ddi_devid_init() and
devid_str_decode() functions.
The ddi_devid_register() function registers the device ID
address (devid) with the DDI framework, associating it withthe dev_info passed in (dip). The drivers must register dev-
ice IDs at attach time. See attach(9E).A driver that calls ddi_devid_register() should place the
following line in its driver.conf(4) file. The presence ofthis property informs the system that this driver may regis-
ter a devid for a device when device discovery is necessary.SunOS 5.11 Last change: 22 Jun 2010 3
Kernel Functions for Drivers ddi_devid_compare(9F)
ddi-devid-registrant=1;
The ddi_devid_unregister() function removes the device ID
address from the dev_info passed in (dip). Drivers must use
this function to unregister the device ID when devices arebeing detached. This function does not free the space allo-
cated for the device ID. The driver must free the spaceallocated for the device ID, using the ddi_devid_free()
function. See detach(9E).The ddi_devid_valid() function 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.The ddi_devid_get() function returns a pointer to the device
ID structure through retdevid if there is already aregistered device ID associated with the dev_info node. A
driver can use this interface to check and get the device IDassociated with the dev_info node. It returns DDI_FAILURE if
no device ID is registered for the node.The ddi_devid_get() function allocates memory for the opaque
device ID structure and initializes it with the associated device ID and returns the pointer to it. The driver must free the memory allocated by this function using theddi_devid_free() function.
The ddi_devid_str_encode() function encodes a devid and
minor_name into a null-terminated ASCII string, returning a
pointer to that string. If both a devid and a minor_name are
non-null, then a slash (/) is used to separate the devid
from the minor_name in the encoded string. If minor_name 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 stringmust be freed by calling devid_str_free().
The ddi_devid_str_decode() function takes a string previ-
ously produced by the devid_str_encode(3DEVID) or
ddi_devid_str_encode() function and decodes the contained
device ID and minor_name, allocating and returning pointers
to the extracted parts through the retdevid andSunOS 5.11 Last change: 22 Jun 2010 4
Kernel Functions for Drivers ddi_devid_compare(9F)
retminor_name arguments. If the special devidstr id0 was
specified then the returned device ID and minor name willboth be null. A non-null returned devid must be freed by the
caller through the ddi_devid_free() function. A non-null
returned minor name must be freed by callingddi_devid_str_free().
The ddi_devid_str_free() function is used to free all
strings returned by the ddi_devid functions (the
ddi_devid_str_encode() function return value and the
returned retminor_name argument).
RETURN VALUES
The ddi_devid_init() function returns the following values:
DDI_SUCCESS Success.
DDI_FAILURE Out of memory. An invalid devid_type was
passed in.The ddi_devid_valid() function returns the following values:
DDI_SUCCESS Valid device ID.
DDI_FAILURE Invalid device ID.
The ddi_devid_register() function returns the following
values:DDI_SUCCESS Success.
DDI_FAILURE Failure. The device ID is already
registered or the device ID is invalid.The ddi_devid_valid() function returns the following values:
SunOS 5.11 Last change: 22 Jun 2010 5
Kernel Functions for Drivers ddi_devid_compare(9F)
DDI_SUCCESS Valid device ID.
DDI_FAILURE Invalid device ID.
The ddi_devid_get() function returns the following values:
DDI_SUCCESS Device ID is present and a pointer to it
is returned in retdevid.DDI_FAILURE No device ID is defined for this
dev_info node.
The ddi_devid_compare() function 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.The ddi_devid_sizeof() function 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 complete device ID is returned.The ddi_devid_str_encode() function returns a value of null
to indicate failure. Failure can be caused by attempting toencode an invalid devid. If the return value is non-null
then the caller must free the returned string by using thedevid_str_free() function.
SunOS 5.11 Last change: 22 Jun 2010 6
Kernel Functions for Drivers ddi_devid_compare(9F)
The ddi_devid_str_decode() function returns the following
values:DDI_SUCCESS Success.
DDI_FAILURE Failure; the devidstr string was not
valid.CONTEXT
These functions can be called from a user or kernel context.SEE ALSO
devid_get(3DEVID), , libdevid(3LIB), driver.conf(4),
attach(9E), detach(9E), kmem_free(9F)
Writing Device DriversSunOS 5.11 Last change: 22 Jun 2010 7