1ddi_devid_compare(9F)    Kernel Functions for Drivers    ddi_devid_compare(9F)
2
3
4

NAME

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

SYNOPSIS

12       int ddi_devid_compare(ddi_devid_t devid1, ddi_devid_t devid2);
13
14
15       size_t ddi_devid_sizeof(ddi_devid_t devid);
16
17
18       int ddi_devid_init(dev_info_t *dip, ushort_t devid_type,
19            ushort_t nbytes, void *id, ddi_devid_t *retdevid);
20
21
22       void ddi_devid_free(ddi_devid_t devid);
23
24
25       int ddi_devid_register(dev_info_t *dip, ddi_devid_t devid);
26
27
28       int ddi_devid_str_decode(char *devidstr, ddi_devid_t *retdevid,
29            char **retminor_name);
30
31
32       int ddi_devid_str_encode(ddi_devid_t devid, char *minor_name);
33
34
35       int ddi_devid_str_free(char *devidstr);
36
37
38       int ddi_devid_get(dev_info_t *dip, ddi_devid_t *retdevid);
39
40
41       void ddi_devid_unregister(dev_info_t *dip);
42
43
44       int ddi_devid_valid(ddi_devid_t devid);
45
46

PARAMETERS

48       devid         The device id address.
49
50
51       devidstr      The devid and minor_name represented as a string.
52
53
54       devid1        The first of two device id addresses to be compared call‐
55                     ing ddi_devid_compare().
56
57
58       devid2        The  second  of  two  device  id addresses to be compared
59                     calling ddi_devid_compare().
60
61
62       dip           A dev_info pointer, which identifies the device.
63
64
65       devid_type    The following device id types  may  be  accepted  by  the
66                     ddi_devid_init() function:
67
68                     DEVID_SCSI3_WWN      World   Wide  Name  associated  with
69                                          SCSI-3 devices.
70
71
72                     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
78
79                     DEVID_ENCAP          Device ID of another device. This is
80                                          for layered device driver usage.
81
82
83                     DEVID_FAB            Fabricated device ID.
84
85
86
87       minor_name       The minor name to be encoded.
88
89
90       nbytes           The length in bytes of device ID.
91
92
93       retdevid         The return address of the device ID.
94
95
96       retminor_name    The  return  address of a minor name. Free string with
97                        ddi_devid_str_free().
98
99

INTERFACE LEVEL

101       Solaris DDI specific (Solaris DDI).
102

DESCRIPTION

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
109
110       ddi_devid_compare() compares two device IDs byte-by-byte and determines
111       both equality and sort order.
112
113
114       ddi_devid_sizeof() returns the number of bytes allocated for the passed
115       in device ID (devid).
116
117
118       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
125
126       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
131
132       Drivers  must  free  the  memory  allocated by this function, using the
133       ddi_devid_free() function.
134
135
136       ddi_devid_free() frees the memory allocated for the returned  devid  by
137       the ddi_devid_init() and devid_str_decode() functions.
138
139
140       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
144
145       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
152
153       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
157
158       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
164
165       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
170
171       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
181
182       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
192
193       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

RETURN VALUES

198       ddi_devid_init() returns the following values:
199
200
201            DDI_SUCCESS    Success.
202
203
204            DDI_FAILURE    Out of memory. An invalid devid_type was passed in.
205
206
207
208
209       ddi_devid_valid() returns the following values:
210
211
212            DDI_SUCCESS    Valid device ID.
213
214
215            DDI_FAILURE    Invalid device ID.
216
217
218
219
220       ddi_devid_register() returns the following values:
221
222
223            DDI_SUCCESS    Success.
224
225
226            DDI_FAILURE    Failure. The device ID is already registered or the
227                           device ID is invalid.
228
229
230
231
232       ddi_devid_valid() returns the following values:
233
234
235            DDI_SUCCESS    Valid device ID.
236
237
238            DDI_FAILURE    Invalid device ID.
239
240
241
242
243       ddi_devid_get() returns the following values:
244
245
246            DDI_SUCCESS    Device ID  is  present  and  a  pointer  to  it  is
247                           returned in retdevid.
248
249
250            DDI_FAILURE    No device ID is defined for this dev_info node.
251
252
253
254
255       ddi_devid_compare() returns the following values:
256
257
258            −1       The first device ID is less than the second device ID.
259
260
261            0        The first device ID is equal to the second device ID.
262
263
264            1        The first device ID is greater than the second device ID.
265
266
267
268
269       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
273
274       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
279
280       ddi_devid_str_decode() returns the following values:
281
282
283            DDI_SUCCESS    Success.
284
285
286            DDI_FAILURE    Failure; the devidstr string was not valid.
287
288
289

CONTEXT

291       These functions can be called from a user or kernel context.
292

SEE ALSO

294       devid_get(3DEVID),   ,   libdevid(3LIB),   attributes(5),   attach(9E),
295       detach(9E), kmem_free(9F)
296
297
298       Writing Device Drivers
299
300
301
302SunOS 5.11                        21 May 2009            ddi_devid_compare(9F)
Impressum