1ddi_devid_compare(9F) Kernel Functions for Drivers ddi_devid_compare(9F)
2
6 ddi_devid_compare, ddi_devid_free, ddi_devid_init, ddi_devid_register,
7 ddi_devid_sizeof, ddi_devid_str_decode, ddi_devid_str_encode,
8 ddi_devid_str_free, ddi_devid_get, ddi_devid_unregister,
9 ddi_devid_valid - kernel interfaces for device ids
10
12 int ddi_devid_compare(ddi_devid_t devid1, ddi_devid_t devid2);
13 size_t ddi_devid_sizeof(ddi_devid_t devid);
16 int ddi_devid_init(dev_info_t *dip, ushort_t devid_type,
19 ushort_t nbytes, void *id, ddi_devid_t *retdevid);
20 void ddi_devid_free(ddi_devid_t devid);
23 int ddi_devid_register(dev_info_t *dip, ddi_devid_t devid);
26 int ddi_devid_str_decode(char *devidstr, ddi_devid_t *retdevid,
29 char **retminor_name);
30 int ddi_devid_str_encode(ddi_devid_t devid, char *minor_name);
33 int ddi_devid_str_free(char *devidstr);
36 int ddi_devid_get(dev_info_t *dip, ddi_devid_t *retdevid);
39 void ddi_devid_unregister(dev_info_t *dip);
42 int ddi_devid_valid(ddi_devid_t devid);
45
48 devid The device id address.
49 devidstr The devid and minor_name represented as a string.
52 devid1 The first of two device id addresses to be compared call‐
55 ing ddi_devid_compare().
56 devid2 The second of two device id addresses to be compared
59 calling ddi_devid_compare().
60 dip A dev_info pointer, which identifies the device.
63 devid_type The following device id types may be accepted by the
66 ddi_devid_init() function:
67 DEVID_SCSI3_WWN World Wide Name associated with
69 SCSI-3 devices.
70 DEVID_SCSI_SERIAL Vendor IDand serial number associ‐
73 ated with a SCSI device. Note: This
74 may only be used if known to be
75 unique; otherwise a fabricated
76 device id must be used.
77 DEVID_ENCAP Device ID of another device. This is
80 for layered device driver usage.
81 DEVID_FAB Fabricated device ID.
84 minor_name The minor name to be encoded.
88 nbytes The length in bytes of device ID.
91 retdevid The return address of the device ID.
94 retminor_name The return address of a minor name. Free string with
97 ddi_devid_str_free().
98
101 Solaris DDI specific (Solaris DDI).
102
104 The following routines are used to provide unique identifiers, device
105 IDs, for devices. Specifically, kernel modules use these interfaces to
106 identify and locate devices, independent of the device's physical con‐
107 nection or its logical device name or number.
108 ddi_devid_compare() compares two device IDs byte-by-byte and determines
111 both equality and sort order.
112 ddi_devid_sizeof() returns the number of bytes allocated for the passed
115 in device ID (devid).
116 ddi_devid_init() allocates memory and initializes the opaque device ID
119 structure. This function does not store the devid. If the device id is
120 not derived from the device's firmware, it is the driver's responsibil‐
121 ity to store the devid on some reliable store. When a devid_type of
122 either DEVID_SCSI3_WWN, DEVID_SCSI_SERIAL, or DEVID_ENCAP is accepted,
123 an array of bytes (id) must be passed in (nbytes).
124 When the devid_type DEVID_FAB is used, the array of bytes (id) must be
127 NULL and the length (nbytes) must be zero. The fabricated device ids,
128 DEVID_FAB will be initialized with the machine's host id and a time‐
129 stamp.
130 Drivers must free the memory allocated by this function, using the
133 ddi_devid_free() function.
134 ddi_devid_free() frees the memory allocated for the returned devid by
137 the ddi_devid_init() and devid_str_decode() functions.
138 ddi_devid_register() registers the device ID address (devid) with the
141 DDI framework, associating it with the dev_info passed in (dip). The
142 drivers must register device IDs at attach time. See attach(9E).
143 ddi_devid_unregister() removes the device ID address from the dev_info
146 passed in (dip). Drivers must use this function to unregister the
147 device ID when devices are being detached. This function does not free
148 the space allocated for the device ID. The driver must free the space
149 allocated for the device ID, using the ddi_devid_free() function. See
150 detach(9E).
151 ddi_devid_valid() validates the device ID (devid) passed in. The driver
154 must use this function to validate any fabricated device ID that has
155 been stored on a device.
156 The ddi_devid_get() function returns a pointer to the device ID struc‐
159 ture through retdevid if there is already a registered device ID asso‐
160 ciated with the dev_info node. A driver can use this interface to check
161 and get the device ID associated with the dev_info node. It returns
162 DDI_FAILURE if no device ID is registered for the node.
163 The ddi_devid_get() function allocates memory for the opaque device ID
166 structure and initializes it with the associated device ID and returns
167 the pointer to it. The driver must free the memory allocated by this
168 function using the ddi_devid_free() function.
169 The ddi_devid_str_encode() function encodes a devid and minor_name into
172 a null-terminated ASCII string, returning a pointer to that string. If
173 both a devid and a minor_name are non-null, then a slash (/) is used to
174 separate the devid from the minor_name in the encoded string. If
175 minor_name is null, then only the devid is encoded. If the devid is
176 null, then the special string id0 is returned. Note that you cannot
177 compare the returned string against another string with strcmp() to
178 determine devid equality. The returned string must be freed by calling
179 devid_str_free().
180 The ddi_devid_str_decode() function takes a string previously produced
183 by the devid_str_encode(3DEVID) or ddi_devid_str_encode() function and
184 decodes the contained device ID and minor_name, allocating and return‐
185 ing pointers to the extracted parts through the retdevid and retmi‐
186 nor_name arguments. If the special devidstr id0 was specified then the
187 returned device ID and minor name will both be null. A non-null
188 returned devid must be freed by the caller through the ddi_devid_free()
189 function. A non-null returned minor name must be freed by calling
190 ddi_devid_str_free().
191 The ddi_devid_str_free() function is used to free all strings returned
194 by the ddi_devid functions (the ddi_devid_str_encode() function return
195 value and the returned retminor_name argument).
196
198 ddi_devid_init() returns the following values:
199 DDI_SUCCESS Success.
202 DDI_FAILURE Out of memory. An invalid devid_type was passed in.
205 ddi_devid_valid() returns the following values:
210 DDI_SUCCESS Valid device ID.
213 DDI_FAILURE Invalid device ID.
216 ddi_devid_register() returns the following values:
221 DDI_SUCCESS Success.
224 DDI_FAILURE Failure. The device ID is already registered or the
227 device ID is invalid.
228 ddi_devid_valid() returns the following values:
233 DDI_SUCCESS Valid device ID.
236 DDI_FAILURE Invalid device ID.
239 ddi_devid_get() returns the following values:
244 DDI_SUCCESS Device ID is present and a pointer to it is
247 returned in retdevid.
248 DDI_FAILURE No device ID is defined for this dev_info node.
251 ddi_devid_compare() returns the following values:
256 −1 The first device ID is less than the second device ID.
259 0 The first device ID is equal to the second device ID.
262 1 The first device ID is greater than the second device ID.
265 ddi_devid_sizeof() returns the size of the devid in bytes. If called
270 with a null, then the number of bytes that must be allocated and ini‐
271 tialized to determine the size of a complete device ID is returned.
272 ddi_devid_str_encode() returns a value of null to indicate failure.
275 Failure can be caused by attempting to encode an invalid devid. If the
276 return value is non-null then the caller must free the returned string
277 by using the devid_str_free() function.
278 ddi_devid_str_decode() returns the following values:
281 DDI_SUCCESS Success.
284 DDI_FAILURE Failure; the devidstr string was not valid.
287
291 These functions can be called from a user or kernel context.
292
294 devid_get(3DEVID), , libdevid(3LIB), attributes(5), attach(9E),
295 detach(9E), kmem_free(9F)
296 Writing Device Drivers
299SunOS 5.11 21 May 2009 ddi_devid_compare(9F)