| blob | 085d455a8d4cb1cd6d1e5d4029942ed9f620b393 |
1 '\" te
2 .\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved
3 .\" 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.
4 .\" 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
5 .\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH DDI_DEVID_COMPARE 9F "May 21, 2009"
7 .SH NAME
8 ddi_devid_compare, ddi_devid_free, ddi_devid_init, ddi_devid_register,
9 ddi_devid_sizeof, ddi_devid_str_decode, ddi_devid_str_encode,
10 ddi_devid_str_free, ddi_devid_get, ddi_devid_unregister, ddi_devid_valid \-
11 kernel interfaces for device ids
12 .SH SYNOPSIS
13 .LP
14 .nf
15 \fBint\fR \fBddi_devid_compare\fR(\fBddi_devid_t\fR \fIdevid1\fR, \fBddi_devid_t\fR \fIdevid2\fR);
16 .fi
18 .LP
19 .nf
20 \fBsize_t\fR \fBddi_devid_sizeof\fR(\fBddi_devid_t\fR \fIdevid\fR);
21 .fi
23 .LP
24 .nf
25 \fBint\fR \fBddi_devid_init\fR(\fBdev_info_t *\fR\fIdip\fR, \fBushort_t\fR \fIdevid_type\fR,
26 \fBushort_t\fR \fInbytes\fR, \fBvoid *\fR\fIid\fR, \fBddi_devid_t *\fR\fIretdevid\fR);
27 .fi
29 .LP
30 .nf
31 \fBvoid\fR \fBddi_devid_free\fR(\fBddi_devid_t\fR \fIdevid\fR);
32 .fi
34 .LP
35 .nf
36 \fBint\fR \fBddi_devid_register\fR(\fBdev_info_t *\fR\fIdip\fR, \fBddi_devid_t\fR \fIdevid\fR);
37 .fi
39 .LP
40 .nf
41 \fBint\fR \fBddi_devid_str_decode\fR(\fBchar *\fR\fIdevidstr\fR, \fBddi_devid_t *\fR\fIretdevid\fR,
42 \fBchar **\fR\fIretminor_name\fR);
43 .fi
45 .LP
46 .nf
47 \fBint\fR \fBddi_devid_str_encode\fR(\fBddi_devid_t\fR \fIdevid\fR, \fBchar *\fR\fIminor_name\fR);
48 .fi
50 .LP
51 .nf
52 \fBint\fR \fBddi_devid_str_free\fR(\fBchar *\fR\fIdevidstr\fR);
53 .fi
55 .LP
56 .nf
57 \fBint\fR \fBddi_devid_get\fR(\fBdev_info_t *\fR\fIdip\fR, \fBddi_devid_t *\fR\fIretdevid\fR);
58 .fi
60 .LP
61 .nf
62 \fBvoid\fR \fBddi_devid_unregister\fR(\fBdev_info_t *\fR\fIdip\fR);
63 .fi
65 .LP
66 .nf
67 \fBint\fR \fBddi_devid_valid\fR(\fBddi_devid_t\fR \fIdevid\fR);
68 .fi
70 .SH PARAMETERS
71 .sp
72 .ne 2
73 .na
74 \fB\fIdevid\fR\fR
75 .ad
76 .RS 14n
77 The device id address.
78 .RE
80 .sp
81 .ne 2
82 .na
83 \fB\fIdevidstr\fR\fR
84 .ad
85 .RS 14n
86 The \fIdevid\fR and \fIminor_name\fR represented as a string.
87 .RE
89 .sp
90 .ne 2
91 .na
92 \fB\fIdevid1\fR\fR
93 .ad
94 .RS 14n
95 The first of two device id addresses to be compared calling
96 \fBddi_devid_compare()\fR.
97 .RE
99 .sp
100 .ne 2
101 .na
102 \fB\fIdevid2\fR\fR
103 .ad
104 .RS 14n
105 The second of two device id addresses to be compared calling
106 \fBddi_devid_compare()\fR.
107 .RE
109 .sp
110 .ne 2
111 .na
112 \fB\fIdip\fR\fR
113 .ad
114 .RS 14n
115 A \fBdev_info\fR pointer, which identifies the device.
116 .RE
118 .sp
119 .ne 2
120 .na
121 \fB\fIdevid_type\fR\fR
122 .ad
123 .RS 14n
124 The following device id types may be accepted by the \fBddi_devid_init()\fR
125 function:
126 .sp
127 .ne 2
128 .na
129 \fB\fBDEVID_SCSI3_WWN\fR\fR
130 .ad
131 .RS 21n
132 World Wide Name associated with SCSI-3 devices.
133 .RE
135 .sp
136 .ne 2
137 .na
138 \fB\fBDEVID_SCSI_SERIAL\fR\fR
139 .ad
140 .RS 21n
141 Vendor \fBID\fRand serial number associated with a SCSI device. Note: This may
142 only be used if known to be unique; otherwise a fabricated device id must be
143 used.
144 .RE
146 .sp
147 .ne 2
148 .na
149 \fB\fBDEVID_ENCAP\fR\fR
150 .ad
151 .RS 21n
152 Device \fBID\fR of another device. This is for layered device driver usage.
153 .RE
155 .sp
156 .ne 2
157 .na
158 \fB\fBDEVID_FAB\fR\fR
159 .ad
160 .RS 21n
161 Fabricated device \fBID\fR.
162 .RE
164 .RE
166 .sp
167 .ne 2
168 .na
169 \fB\fIminor_name\fR\fR
170 .ad
171 .RS 17n
172 The minor name to be encoded.
173 .RE
175 .sp
176 .ne 2
177 .na
178 \fB\fInbytes\fR\fR
179 .ad
180 .RS 17n
181 The length in bytes of device \fBID\fR.
182 .RE
184 .sp
185 .ne 2
186 .na
187 \fB\fIretdevid\fR\fR
188 .ad
189 .RS 17n
190 The return address of the device \fBID\fR.
191 .RE
193 .sp
194 .ne 2
195 .na
196 \fB\fIretminor_name\fR\fR
197 .ad
198 .RS 17n
199 The return address of a minor name. Free string with
200 \fBddi_devid_str_free()\fR.
201 .RE
203 .SH INTERFACE LEVEL
204 .sp
205 .LP
206 Solaris DDI specific (Solaris DDI).
207 .SH DESCRIPTION
208 .sp
209 .LP
210 The following routines are used to provide unique identifiers, device
211 \fBID\fRs, for devices. Specifically, kernel modules use these interfaces to
212 identify and locate devices, independent of the device's physical connection or
213 its logical device name or number.
214 .sp
215 .LP
216 \fBddi_devid_compare()\fR compares two device \fBID\fRs byte-by-byte and
217 determines both equality and sort order.
218 .sp
219 .LP
220 \fBddi_devid_sizeof()\fR returns the number of bytes allocated for the passed
221 in device \fBID\fR (\fIdevid\fR).
222 .sp
223 .LP
224 \fBddi_devid_init()\fR allocates memory and initializes the opaque device
225 \fBID\fR structure. This function does not store the \fIdevid\fR. If the device
226 id is not derived from the device's firmware, it is the driver's responsibility
227 to store the \fIdevid\fR on some reliable store. When a \fIdevid_type\fR of
228 either \fBDEVID_SCSI3_WWN,\fR \fBDEVID_SCSI_SERIAL\fR, or \fBDEVID_ENCAP\fR is
229 accepted, an array of bytes (\fIid\fR) must be passed in (\fInbytes\fR).
230 .sp
231 .LP
232 When the \fIdevid_type\fR \fBDEVID_FAB\fR is used, the array of bytes
233 (\fIid\fR) must be \fBNULL\fR and the length (\fInbytes\fR) must be zero. The
234 fabricated device ids, \fBDEVID_FAB\fR will be initialized with the machine's
235 host id and a timestamp.
236 .sp
237 .LP
238 Drivers must free the memory allocated by this function, using the
239 \fBddi_devid_free()\fR function.
240 .sp
241 .LP
242 \fBddi_devid_free()\fR frees the memory allocated for the returned \fIdevid\fR
243 by the \fBddi_devid_init()\fR and \fBdevid_str_decode()\fR functions.
244 .sp
245 .LP
246 \fBddi_devid_register()\fR registers the device \fBID\fR address (\fIdevid\fR)
247 with the \fBDDI\fR framework, associating it with the \fBdev_info\fR passed in
248 (\fIdip\fR). The drivers must register device \fBID\fRs at attach time. See
249 \fBattach\fR(9E).
250 .sp
251 .LP
252 \fBddi_devid_unregister()\fR removes the device \fBID\fR address from the
253 \fBdev_info\fR passed in (\fIdip\fR). Drivers must use this function to
254 unregister the device \fBID\fR when devices are being detached. This function
255 does not free the space allocated for the device \fBID\fR. The driver must free
256 the space allocated for the device \fBID\fR, using the \fBddi_devid_free()\fR
257 function. See \fBdetach\fR(9E).
258 .sp
259 .LP
260 \fBddi_devid_valid()\fR validates the device \fBID\fR (\fIdevid\fR) passed in.
261 The driver must use this function to validate any fabricated device \fBID\fR
262 that has been stored on a device.
263 .sp
264 .LP
265 The \fBddi_devid_get()\fR function returns a pointer to the device ID structure
266 through \fIretdevid\fR if there is already a registered device ID associated
267 with the \fBdev_info\fR node. A driver can use this interface to check and get
268 the device ID associated with the \fBdev_info\fR node. It returns
269 \fBDDI_FAILURE\fR if no device ID is registered for the node.
270 .sp
271 .LP
272 The \fBddi_devid_get()\fR function allocates memory for the opaque device ID
273 structure and initializes it with the associated device ID and returns the
274 pointer to it. The driver must free the memory allocated by this function using
275 the \fBddi_devid_free()\fR function.
276 .sp
277 .LP
278 The \fBddi_devid_str_encode()\fR function encodes a \fIdevid\fR and minor_name
279 into a null-terminated ASCII string, returning a pointer to that string. If
280 both a \fIdevid\fR and a \fIminor_name\fR are non-null, then a slash (\fB/\fR)
281 is used to separate the \fIdevid\fR from the \fIminor_name\fR in the encoded
282 string. If \fIminor_name\fR is null, then only the \fIdevid\fR is encoded. If
283 the \fIdevid\fR is null, then the special string \fBid0\fR is returned. Note
284 that you cannot compare the returned string against another string with
285 \fBstrcmp()\fR to determine \fIdevid\fR equality. The returned string must be
286 freed by calling \fBdevid_str_free()\fR.
287 .sp
288 .LP
289 The \fBddi_devid_str_decode()\fR function takes a string previously produced by
290 the \fBdevid_str_encode\fR(3DEVID) or \fBddi_devid_str_encode()\fR function and
291 decodes the contained device ID and minor_name, allocating and returning
292 pointers to the extracted parts through the \fIretdevid\fR and
293 \fIretminor_name\fR arguments. If the special \fIdevidstr\fR \fBid0\fR was
294 specified then the returned device ID and minor name will both be null. A
295 non-null returned \fIdevid\fR must be freed by the caller through the
296 \fBddi_devid_free()\fR function. A non-null returned minor name must be freed
297 by calling \fBddi_devid_str_free()\fR.
298 .sp
299 .LP
300 The \fBddi_devid_str_free()\fR function is used to free all strings returned by
301 the \fBddi_devid\fR functions (the \fBddi_devid_str_encode()\fR function return
302 value and the returned \fIretminor_name\fR argument).
303 .SH RETURN VALUES
304 .sp
305 .LP
306 \fBddi_devid_init()\fR returns the following values:
307 .sp
308 .ne 2
309 .na
310 \fB \fR
311 .ad
312 .RS 5n
313 .sp
314 .ne 2
315 .na
316 \fB\fBDDI_SUCCESS\fR\fR
317 .ad
318 .RS 15n
319 Success.
320 .RE
322 .sp
323 .ne 2
324 .na
325 \fB\fBDDI_FAILURE\fR\fR
326 .ad
327 .RS 15n
328 Out of memory. An invalid \fIdevid_type\fR was passed in.
329 .RE
331 .RE
333 .sp
334 .LP
335 \fBddi_devid_valid()\fR returns the following values:
336 .sp
337 .ne 2
338 .na
339 \fB \fR
340 .ad
341 .RS 5n
342 .sp
343 .ne 2
344 .na
345 \fB\fBDDI_SUCCESS\fR\fR
346 .ad
347 .RS 15n
348 Valid device \fBID\fR.
349 .RE
351 .sp
352 .ne 2
353 .na
354 \fB\fBDDI_FAILURE\fR\fR
355 .ad
356 .RS 15n
357 Invalid device \fBID\fR.
358 .RE
360 .RE
362 .sp
363 .LP
364 \fBddi_devid_register()\fR returns the following values:
365 .sp
366 .ne 2
367 .na
368 \fB \fR
369 .ad
370 .RS 5n
371 .sp
372 .ne 2
373 .na
374 \fB\fBDDI_SUCCESS\fR\fR
375 .ad
376 .RS 15n
377 Success.
378 .RE
380 .sp
381 .ne 2
382 .na
383 \fB\fBDDI_FAILURE\fR\fR
384 .ad
385 .RS 15n
386 Failure. The device \fBID\fR is already registered or the device \fBID\fR is
387 invalid.
388 .RE
390 .RE
392 .sp
393 .LP
394 \fBddi_devid_valid()\fR returns the following values:
395 .sp
396 .ne 2
397 .na
398 \fB \fR
399 .ad
400 .RS 5n
401 .sp
402 .ne 2
403 .na
404 \fB\fBDDI_SUCCESS\fR\fR
405 .ad
406 .RS 15n
407 Valid device \fBID\fR.
408 .RE
410 .sp
411 .ne 2
412 .na
413 \fB\fBDDI_FAILURE\fR\fR
414 .ad
415 .RS 15n
416 Invalid device \fBID\fR.
417 .RE
419 .RE
421 .sp
422 .LP
423 \fBddi_devid_get()\fR returns the following values:
424 .sp
425 .ne 2
426 .na
427 \fB \fR
428 .ad
429 .RS 5n
430 .sp
431 .ne 2
432 .na
433 \fB\fBDDI_SUCCESS\fR\fR
434 .ad
435 .RS 15n
436 Device \fBID\fR is present and a pointer to it is returned in \fIretdevid\fR.
437 .RE
439 .sp
440 .ne 2
441 .na
442 \fB\fBDDI_FAILURE\fR\fR
443 .ad
444 .RS 15n
445 No device \fBID\fR is defined for this \fBdev_info\fR node.
446 .RE
448 .RE
450 .sp
451 .LP
452 \fBddi_devid_compare()\fR returns the following values:
453 .sp
454 .ne 2
455 .na
456 \fB \fR
457 .ad
458 .RS 5n
459 .sp
460 .ne 2
461 .na
462 \fB\fB\(mi1\fR\fR
463 .ad
464 .RS 9n
465 The first device ID is less than the second device ID.
466 .RE
468 .sp
469 .ne 2
470 .na
471 \fB\fB0\fR\fR
472 .ad
473 .RS 9n
474 The first device ID is equal to the second device ID.
475 .RE
477 .sp
478 .ne 2
479 .na
480 \fB\fB1\fR\fR
481 .ad
482 .RS 9n
483 The first device ID is greater than the second device ID.
484 .RE
486 .RE
488 .sp
489 .LP
490 \fBddi_devid_sizeof()\fR returns the size of the \fIdevid\fR in bytes. If
491 called with a null, then the number of bytes that must be allocated and
492 initialized to determine the size of a complete device ID is returned.
493 .sp
494 .LP
495 \fBddi_devid_str_encode()\fR returns a value of null to indicate failure.
496 Failure can be caused by attempting to encode an invalid \fIdevid\fR. If the
497 return value is non-null then the caller must free the returned string by using
498 the \fBdevid_str_free()\fR function.
499 .sp
500 .LP
501 \fBddi_devid_str_decode()\fR returns the following values:
502 .sp
503 .ne 2
504 .na
505 \fB \fR
506 .ad
507 .RS 5n
508 .sp
509 .ne 2
510 .na
511 \fB\fBDDI_SUCCESS\fR\fR
512 .ad
513 .RS 15n
514 Success.
515 .RE
517 .sp
518 .ne 2
519 .na
520 \fB\fBDDI_FAILURE\fR\fR
521 .ad
522 .RS 15n
523 Failure; the \fIdevidstr\fR string was not valid.
524 .RE
526 .RE
528 .SH CONTEXT
529 .sp
530 .LP
531 These functions can be called from a user or kernel context.
532 .SH SEE ALSO
533 .sp
534 .LP
535 \fBdevid_get\fR(3DEVID), , \fBlibdevid\fR(3LIB), \fBattributes\fR(5),
536 \fBattach\fR(9E), \fBdetach\fR(9E), \fBkmem_free\fR(9F)
537 .sp
538 .LP
539 \fIWriting Device Drivers\fR