ddi_devid_init(9F)

NAME | SYNOPSIS | PARAMETERS | DESCRIPTION | RETURN VALUES | CONTEXT | ATTRIBUTES | SEE ALSO

NAME

ddi_devid_compare, ddi_devid_free, ddi_devid_init, ddi_devid_register, ddi_devid_sizeof, ddi_devid_unregister, ddi_devid_valid– Kernel interfaces for device ids

SYNOPSIS

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 );
void ddi_devid_unregister(dev_info_t *dip);
int ddi_devid_valid(ddi_devid_t devid);

PARAMETERS

devid

The device id address.

devid1

The first of two device id addresses to be compared calling ddi_devid_compare().

devid2

The second of two device id addresses to be compared calling ddi_devid_compare().

dip

A dev_info pointer, which identifies the device.

devid_type

The following device id types may be accepted by the ddi_devid_init() function:

DEVID_SCSI3_WWN

World Wide Name associated 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 device. This is for layered device driver usage.

DEVID_FAB

Fabricated device ID.

nbytes

The length in bytes of device ID.

retdevid

The return address of the device ID created by ddi_devid_init().

DESCRIPTION

The following routines are used to provide unique identifiers, device IDs, for devices. Specifically, kernel modules use these interfaces to identify and locate devices, independent of the device's physical connection or its logical device name or number.

ddi_devid_compare() compares two device IDs byte-by-byte and determines both equality and sort order.

ddi_devid_sizeof() returns the number of bytes allocated for the passed in device ID (devid).

ddi_devid_init() 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 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. The fabricated 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.

ddi_devid_free() frees the memory allocated by the ddi_devid_init() function.

ddi_devid_register() registers the device ID address (devid) with the DDI framework, associating it with the dev_info passed in (dip). The drivers must register device IDs at attach time. See attach(9E).

ddi_devid_unregister() removes the device ID address from the dev_info 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 device ID. The driver must free the space allocated for the device ID, using the ddi_devid_free() function. See detach(9E).

ddi_devid_valid() 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.

RETURN VALUES

ddi_devid_init() returns the following values:

DDI_SUCCESS

Success.

DDI_FAILURE

Out of memory. An invalid devid_type was passed in.

ddi_devid_valid() returns the following values:

DDI_SUCCESS

Valid device ID.

DDI_FAILURE

Invalid device ID.

ddi_devid_register() returns the following values:

DDI_SUCCESS

Success.

DDI_FAILURE

Failure. The device ID is already registered or the device ID is invalid.

ddi_devid_valid() returns the following values:

DDI_SUCCESS

Valid device ID.

DDI_FAILURE

Invalid device ID.

ddi_devid_compare() returns the following values:

-1

The device ID pointed to by devid1 is less than the device ID pointed to by devid2.

0

The device ID pointed to by devid1 is equal to the device ID pointed to by devid2.

1

The device ID pointed to by devid1 is greater than the device ID pointed to by devid2.

ddi_devid_sizeof() returns the size of the devid in numbers of bytes.

CONTEXT

These functions can be called from a user context only.

ATTRIBUTES

See attributes(5) for a description of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
MT-Level	Safe

SEE ALSO

devid_compare(3DEVID), devid_deviceid_to_nmlist(3DEVID), devid_free(3DEVID), devid_free_nmlist(3DEVID), devid_get(3DEVID), devid_get_minor_name(3DEVID), devid_sizeof(3DEVID), libdevid(3LIB), attributes(5), attach(9E), detach(9E)

Writing Device Drivers

SunOS 5.8  Last Revised 26 Nov 1996

NAME | SYNOPSIS | PARAMETERS | DESCRIPTION | RETURN VALUES | CONTEXT | ATTRIBUTES | SEE ALSO