'\" te
.\"  Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
.\"  See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with
.\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH DDI_DEVID_COMPARE 9F "May 21, 2009"
.SH 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 ids
.SH SYNOPSIS
.LP
.nf
\fBint\fR \fBddi_devid_compare\fR(\fBddi_devid_t\fR \fIdevid1\fR, \fBddi_devid_t\fR \fIdevid2\fR);
.fi

.LP
.nf
\fBsize_t\fR \fBddi_devid_sizeof\fR(\fBddi_devid_t\fR \fIdevid\fR);
.fi

.LP
.nf
\fBint\fR \fBddi_devid_init\fR(\fBdev_info_t *\fR\fIdip\fR, \fBushort_t\fR \fIdevid_type\fR,
     \fBushort_t\fR \fInbytes\fR, \fBvoid *\fR\fIid\fR, \fBddi_devid_t *\fR\fIretdevid\fR);
.fi

.LP
.nf
\fBvoid\fR \fBddi_devid_free\fR(\fBddi_devid_t\fR \fIdevid\fR);
.fi

.LP
.nf
\fBint\fR \fBddi_devid_register\fR(\fBdev_info_t *\fR\fIdip\fR, \fBddi_devid_t\fR \fIdevid\fR);
.fi

.LP
.nf
\fBint\fR \fBddi_devid_str_decode\fR(\fBchar *\fR\fIdevidstr\fR, \fBddi_devid_t *\fR\fIretdevid\fR,
     \fBchar **\fR\fIretminor_name\fR);
.fi

.LP
.nf
\fBint\fR \fBddi_devid_str_encode\fR(\fBddi_devid_t\fR \fIdevid\fR, \fBchar *\fR\fIminor_name\fR);
.fi

.LP
.nf
\fBint\fR \fBddi_devid_str_free\fR(\fBchar *\fR\fIdevidstr\fR);
.fi

.LP
.nf
\fBint\fR \fBddi_devid_get\fR(\fBdev_info_t *\fR\fIdip\fR, \fBddi_devid_t *\fR\fIretdevid\fR);
.fi

.LP
.nf
\fBvoid\fR \fBddi_devid_unregister\fR(\fBdev_info_t *\fR\fIdip\fR);
.fi

.LP
.nf
\fBint\fR \fBddi_devid_valid\fR(\fBddi_devid_t\fR \fIdevid\fR);
.fi

.SH PARAMETERS
.sp
.ne 2
.na
\fB\fIdevid\fR\fR
.ad
.RS 14n
The device id address.
.RE

.sp
.ne 2
.na
\fB\fIdevidstr\fR\fR
.ad
.RS 14n
The \fIdevid\fR and \fIminor_name\fR represented as a string.
.RE

.sp
.ne 2
.na
\fB\fIdevid1\fR\fR
.ad
.RS 14n
The first of two device id addresses to be compared calling
\fBddi_devid_compare()\fR.
.RE

.sp
.ne 2
.na
\fB\fIdevid2\fR\fR
.ad
.RS 14n
The second of two device id addresses to be compared calling
\fBddi_devid_compare()\fR.
.RE

.sp
.ne 2
.na
\fB\fIdip\fR\fR
.ad
.RS 14n
A \fBdev_info\fR pointer, which identifies the device.
.RE

.sp
.ne 2
.na
\fB\fIdevid_type\fR\fR
.ad
.RS 14n
The following device id types may be accepted by the \fBddi_devid_init()\fR
function:
.sp
.ne 2
.na
\fB\fBDEVID_SCSI3_WWN\fR\fR
.ad
.RS 21n
World Wide Name associated with SCSI-3 devices.
.RE

.sp
.ne 2
.na
\fB\fBDEVID_SCSI_SERIAL\fR\fR
.ad
.RS 21n
Vendor \fBID\fRand 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.
.RE

.sp
.ne 2
.na
\fB\fBDEVID_ENCAP\fR\fR
.ad
.RS 21n
Device \fBID\fR of another device. This is for layered device driver usage.
.RE

.sp
.ne 2
.na
\fB\fBDEVID_FAB\fR\fR
.ad
.RS 21n
Fabricated device \fBID\fR.
.RE

.RE

.sp
.ne 2
.na
\fB\fIminor_name\fR\fR
.ad
.RS 17n
The minor name to be encoded.
.RE

.sp
.ne 2
.na
\fB\fInbytes\fR\fR
.ad
.RS 17n
The length in bytes of device \fBID\fR.
.RE

.sp
.ne 2
.na
\fB\fIretdevid\fR\fR
.ad
.RS 17n
The return address of the device \fBID\fR.
.RE

.sp
.ne 2
.na
\fB\fIretminor_name\fR\fR
.ad
.RS 17n
The return address of a minor name. Free string with
\fBddi_devid_str_free()\fR.
.RE

.SH INTERFACE LEVEL
.sp
.LP
Solaris DDI specific (Solaris DDI).
.SH DESCRIPTION
.sp
.LP
The following routines are used to provide unique identifiers, device
\fBID\fRs, 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.
.sp
.LP
\fBddi_devid_compare()\fR compares two device \fBID\fRs byte-by-byte and
determines both equality and sort order.
.sp
.LP
\fBddi_devid_sizeof()\fR returns the number of bytes allocated for the passed
in device \fBID\fR (\fIdevid\fR).
.sp
.LP
\fBddi_devid_init()\fR allocates memory and initializes the opaque device
\fBID\fR structure. This function does not store the \fIdevid\fR. If the device
id is not derived from the device's firmware, it is the driver's responsibility
to store the \fIdevid\fR on some reliable store. When a \fIdevid_type\fR of
either \fBDEVID_SCSI3_WWN,\fR \fBDEVID_SCSI_SERIAL\fR, or \fBDEVID_ENCAP\fR is
accepted, an array of bytes (\fIid\fR) must be passed in (\fInbytes\fR).
.sp
.LP
When the \fIdevid_type\fR \fBDEVID_FAB\fR is used, the array of bytes
(\fIid\fR) must be \fBNULL\fR and the length (\fInbytes\fR) must be zero. The
fabricated device ids, \fBDEVID_FAB\fR will be initialized with the machine's
host id and a timestamp.
.sp
.LP
Drivers must free the memory allocated by this function, using the
\fBddi_devid_free()\fR function.
.sp
.LP
\fBddi_devid_free()\fR frees the memory allocated for the returned \fIdevid\fR
by the \fBddi_devid_init()\fR and \fBdevid_str_decode()\fR functions.
.sp
.LP
\fBddi_devid_register()\fR registers the device \fBID\fR address (\fIdevid\fR)
with the \fBDDI\fR framework, associating it with the \fBdev_info\fR passed in
(\fIdip\fR). The drivers must register device \fBID\fRs at attach time. See
\fBattach\fR(9E).
.sp
.LP
\fBddi_devid_unregister()\fR removes the device \fBID\fR address from the
\fBdev_info\fR passed in (\fIdip\fR). Drivers must use this function to
unregister the device \fBID\fR when devices are being detached. This function
does not free the space allocated for the device \fBID\fR. The driver must free
the space allocated for the device \fBID\fR, using the \fBddi_devid_free()\fR
function. See \fBdetach\fR(9E).
.sp
.LP
\fBddi_devid_valid()\fR validates the device \fBID\fR (\fIdevid\fR) passed in.
The driver must use this function to validate any fabricated device \fBID\fR
that has been stored on a device.
.sp
.LP
The \fBddi_devid_get()\fR function returns a pointer to the device ID structure
through \fIretdevid\fR if there is already a registered device ID associated
with the \fBdev_info\fR node. A driver can use this interface to check and get
the device ID associated with the \fBdev_info\fR node. It returns
\fBDDI_FAILURE\fR if no device ID is registered for the node.
.sp
.LP
The \fBddi_devid_get()\fR 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
the \fBddi_devid_free()\fR function.
.sp
.LP
The \fBddi_devid_str_encode()\fR function encodes a \fIdevid\fR and minor_name
into a null-terminated ASCII string, returning a pointer to that string. If
both a \fIdevid\fR and a \fIminor_name\fR are non-null, then a slash (\fB/\fR)
is used to separate the \fIdevid\fR from the \fIminor_name\fR in the encoded
string. If \fIminor_name\fR is null, then only the \fIdevid\fR is encoded. If
the \fIdevid\fR is null, then the special string \fBid0\fR is returned. Note
that you cannot compare the returned string against another string with
\fBstrcmp()\fR to determine \fIdevid\fR equality. The returned string must be
freed by calling \fBdevid_str_free()\fR.
.sp
.LP
The \fBddi_devid_str_decode()\fR function takes a string previously produced by
the \fBdevid_str_encode\fR(3DEVID) or \fBddi_devid_str_encode()\fR function and
decodes the contained device ID and minor_name, allocating and returning
pointers to the extracted parts through the \fIretdevid\fR and
\fIretminor_name\fR arguments. If the special \fIdevidstr\fR \fBid0\fR was
specified then the returned device ID and minor name will both be null. A
non-null returned \fIdevid\fR must be freed by the caller through the
\fBddi_devid_free()\fR function. A non-null returned minor name must be freed
by calling \fBddi_devid_str_free()\fR.
.sp
.LP
The \fBddi_devid_str_free()\fR function is used to free all strings returned by
the \fBddi_devid\fR functions (the \fBddi_devid_str_encode()\fR function return
value and the returned \fIretminor_name\fR argument).
.SH RETURN VALUES
.sp
.LP
\fBddi_devid_init()\fR returns the following values:
.sp
.ne 2
.na
\fB \fR
.ad
.RS 5n
.sp
.ne 2
.na
\fB\fBDDI_SUCCESS\fR\fR
.ad
.RS 15n
Success.
.RE

.sp
.ne 2
.na
\fB\fBDDI_FAILURE\fR\fR
.ad
.RS 15n
Out of memory. An invalid \fIdevid_type\fR was passed in.
.RE

.RE

.sp
.LP
\fBddi_devid_valid()\fR returns the following values:
.sp
.ne 2
.na
\fB \fR
.ad
.RS 5n
.sp
.ne 2
.na
\fB\fBDDI_SUCCESS\fR\fR
.ad
.RS 15n
Valid device \fBID\fR.
.RE

.sp
.ne 2
.na
\fB\fBDDI_FAILURE\fR\fR
.ad
.RS 15n
Invalid device \fBID\fR.
.RE

.RE

.sp
.LP
\fBddi_devid_register()\fR returns the following values:
.sp
.ne 2
.na
\fB \fR
.ad
.RS 5n
.sp
.ne 2
.na
\fB\fBDDI_SUCCESS\fR\fR
.ad
.RS 15n
Success.
.RE

.sp
.ne 2
.na
\fB\fBDDI_FAILURE\fR\fR
.ad
.RS 15n
Failure. The device \fBID\fR is already registered or the device \fBID\fR is
invalid.
.RE

.RE

.sp
.LP
\fBddi_devid_valid()\fR returns the following values:
.sp
.ne 2
.na
\fB \fR
.ad
.RS 5n
.sp
.ne 2
.na
\fB\fBDDI_SUCCESS\fR\fR
.ad
.RS 15n
Valid device \fBID\fR.
.RE

.sp
.ne 2
.na
\fB\fBDDI_FAILURE\fR\fR
.ad
.RS 15n
Invalid device \fBID\fR.
.RE

.RE

.sp
.LP
\fBddi_devid_get()\fR returns the following values:
.sp
.ne 2
.na
\fB \fR
.ad
.RS 5n
.sp
.ne 2
.na
\fB\fBDDI_SUCCESS\fR\fR
.ad
.RS 15n
Device \fBID\fR is present and a pointer to it is returned in \fIretdevid\fR.
.RE

.sp
.ne 2
.na
\fB\fBDDI_FAILURE\fR\fR
.ad
.RS 15n
No device \fBID\fR is defined for this \fBdev_info\fR node.
.RE

.RE

.sp
.LP
\fBddi_devid_compare()\fR returns the following values:
.sp
.ne 2
.na
\fB \fR
.ad
.RS 5n
.sp
.ne 2
.na
\fB\fB\(mi1\fR\fR
.ad
.RS 9n
The first device ID is less than the second device ID.
.RE

.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.RS 9n
The first device ID is equal to the second device ID.
.RE

.sp
.ne 2
.na
\fB\fB1\fR\fR
.ad
.RS 9n
The first device ID is greater than the second device ID.
.RE

.RE

.sp
.LP
\fBddi_devid_sizeof()\fR returns the size of the \fIdevid\fR 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.
.sp
.LP
\fBddi_devid_str_encode()\fR returns a value of null to indicate failure.
Failure can be caused by attempting to encode an invalid \fIdevid\fR. If the
return value is non-null then the caller must free the returned string by using
the \fBdevid_str_free()\fR function.
.sp
.LP
\fBddi_devid_str_decode()\fR returns the following values:
.sp
.ne 2
.na
\fB \fR
.ad
.RS 5n
.sp
.ne 2
.na
\fB\fBDDI_SUCCESS\fR\fR
.ad
.RS 15n
Success.
.RE

.sp
.ne 2
.na
\fB\fBDDI_FAILURE\fR\fR
.ad
.RS 15n
Failure; the \fIdevidstr\fR string was not valid.
.RE

.RE

.SH CONTEXT
.sp
.LP
These functions can be called from a user or kernel context.
.SH SEE ALSO
.sp
.LP
\fBdevid_get\fR(3DEVID), , \fBlibdevid\fR(3LIB), \fBattributes\fR(5),
\fBattach\fR(9E), \fBdetach\fR(9E), \fBkmem_free\fR(9F)
.sp
.LP
\fIWriting Device Drivers\fR