usr/src/man/man9f/ddi_prop_create.9f

   1 '\" te
   2 .\" Copyright (c) 2006, 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH DDI_PROP_CREATE 9F "Jan 16, 2006"
   7 .SH NAME
   8 ddi_prop_create, ddi_prop_modify, ddi_prop_remove, ddi_prop_remove_all,
   9 ddi_prop_undefine \- create, remove, or modify properties for leaf device
  10 drivers
  11 .SH SYNOPSIS
  12 .LP
  13 .nf
  14 #include <sys/conf.h>
  15 #include <sys/ddi.h>
  16 #include <sys/sunddi.h>
  17
  18 \fBint\fR \fBddi_prop_create\fR(\fBdev_t\fR \fIdev\fR, \fBdev_info_t *\fR\fIdip\fR, \fBint\fR \fIflags\fR,
  19      \fBchar *\fR\fIname\fR, \fBcaddr_t\fR \fIvaluep\fR, \fBint\fR \fIlength\fR);
  20 .fi
  21
  22 .LP
  23 .nf
  24 \fBint\fR \fBddi_prop_undefine\fR(\fBdev_t\fR \fIdev\fR, \fBdev_info_t *\fR\fIdip\fR, \fBint\fR \fIflags\fR,
  25      \fBchar *\fR\fIname\fR);
  26 .fi
  27
  28 .LP
  29 .nf
  30 \fBint\fR \fBddi_prop_modify\fR(\fBdev_t\fR \fIdev\fR, \fBdev_info_t *\fR\fIdip\fR, \fBint\fR \fIflags\fR,
  31      \fBchar *\fR\fIname\fR, \fBcaddr_t\fR \fIvaluep\fR, \fBint\fR \fIlength\fR);
  32 .fi
  33
  34 .LP
  35 .nf
  36 \fBint\fR \fBddi_prop_remove\fR(\fBdev_t\fR \fIdev\fR, \fBdev_info_t *\fR\fIdip\fR, \fBchar *\fR\fIname\fR);
  37 .fi
  38
  39 .LP
  40 .nf
  41 \fBvoid\fR \fBddi_prop_remove_all\fR(\fBdev_info_t *\fR\fIdip\fR);
  42 .fi
  43
  44 .SH INTERFACE LEVEL
  45 .sp
  46 .LP
  47 Solaris DDI specific (Solaris DDI). The \fBddi_prop_create()\fR and
  48 \fBddi_prop_modify()\fR functions are obsolete. Use \fBddi_prop_update\fR(9F)
  49 instead of these functions.
  50 .SH PARAMETERS
  51 .sp
  52 .LP
  53 \fBddi_prop_create()\fR
  54 .sp
  55 .ne 2
  56 .na
  57 \fB\fIdev\fR\fR
  58 .ad
  59 .RS 10n
  60 \fBdev_t\fR of the device.
  61 .RE
  62
  63 .sp
  64 .ne 2
  65 .na
  66 \fB\fIdip\fR\fR
  67 .ad
  68 .RS 10n
  69 \fBdev_info_t\fR pointer of the device.
  70 .RE
  71
  72 .sp
  73 .ne 2
  74 .na
  75 \fB\fIflags\fR\fR
  76 .ad
  77 .RS 10n
  78 \fIflag\fR modifiers. The only possible flag value is \fBDDI_PROP_CANSLEEP\fR:
  79 Memory allocation may sleep.
  80 .RE
  81
  82 .sp
  83 .ne 2
  84 .na
  85 \fB\fIname\fR\fR
  86 .ad
  87 .RS 10n
  88 name of property.
  89 .RE
  90
  91 .sp
  92 .ne 2
  93 .na
  94 \fB\fIvaluep\fR\fR
  95 .ad
  96 .RS 10n
  97 pointer to property value.
  98 .RE
  99
 100 .sp
 101 .ne 2
 102 .na
 103 \fB\fIlength\fR\fR
 104 .ad
 105 .RS 10n
 106 property length.
 107 .RE
 108
 109 .sp
 110 .LP
 111 \fBddi_prop_undefine()\fR
 112 .sp
 113 .ne 2
 114 .na
 115 \fB\fIdev\fR\fR
 116 .ad
 117 .RS 9n
 118 \fBdev_t\fR of the device.
 119 .RE
 120
 121 .sp
 122 .ne 2
 123 .na
 124 \fB\fIdip\fR\fR
 125 .ad
 126 .RS 9n
 127 \fBdev_info_t\fR pointer of the device.
 128 .RE
 129
 130 .sp
 131 .ne 2
 132 .na
 133 \fB\fIflags\fR\fR
 134 .ad
 135 .RS 9n
 136 flag modifiers. The only possible flag value is \fBDDI_PROP_CANSLEEP\fR: Memory
 137 allocation may sleep.
 138 .RE
 139
 140 .sp
 141 .ne 2
 142 .na
 143 \fB\fIname\fR\fR
 144 .ad
 145 .RS 9n
 146 name of property.
 147 .RE
 148
 149 .sp
 150 .LP
 151 \fBddi_prop_modify()\fR
 152 .sp
 153 .ne 2
 154 .na
 155 \fB\fIdev\fR\fR
 156 .ad
 157 .RS 10n
 158 \fBdev_t\fR of the device.
 159 .RE
 160
 161 .sp
 162 .ne 2
 163 .na
 164 \fB\fIdip\fR\fR
 165 .ad
 166 .RS 10n
 167 \fBdev_info_t\fR pointer of the device.
 168 .RE
 169
 170 .sp
 171 .ne 2
 172 .na
 173 \fB\fIflags\fR\fR
 174 .ad
 175 .RS 10n
 176 flag modifiers. The only possible flag value is \fBDDI_PROP_CANSLEEP\fR: Memory
 177 allocation may sleep.
 178 .RE
 179
 180 .sp
 181 .ne 2
 182 .na
 183 \fB\fIname\fR\fR
 184 .ad
 185 .RS 10n
 186 name of property.
 187 .RE
 188
 189 .sp
 190 .ne 2
 191 .na
 192 \fB\fIvaluep\fR\fR
 193 .ad
 194 .RS 10n
 195 pointer to property value.
 196 .RE
 197
 198 .sp
 199 .ne 2
 200 .na
 201 \fB\fIlength\fR\fR
 202 .ad
 203 .RS 10n
 204 property length.
 205 .RE
 206
 207 .sp
 208 .LP
 209 \fBddi_prop_remove()\fR
 210 .sp
 211 .ne 2
 212 .na
 213 \fB\fIdev\fR\fR
 214 .ad
 215 .RS 8n
 216 \fBdev_t\fR of the device.
 217 .RE
 218
 219 .sp
 220 .ne 2
 221 .na
 222 \fB\fIdip\fR\fR
 223 .ad
 224 .RS 8n
 225 \fBdev_info_t\fR pointer of the device.
 226 .RE
 227
 228 .sp
 229 .ne 2
 230 .na
 231 \fB\fIname\fR\fR
 232 .ad
 233 .RS 8n
 234 name of property.
 235 .RE
 236
 237 .sp
 238 .LP
 239 \fBddi_prop_remove_all()\fR
 240 .sp
 241 .ne 2
 242 .na
 243 \fB\fIdip\fR\fR
 244 .ad
 245 .RS 7n
 246 \fBdev_info_t\fR pointer of the device.
 247 .RE
 248
 249 .SH DESCRIPTION
 250 .sp
 251 .LP
 252 Device drivers have the ability to create and manage their own properties as
 253 well as gain access to properties that the system creates on behalf of the
 254 driver. A driver uses \fBddi_getproplen\fR(9F) to query whether or not a
 255 specific property exists.
 256 .sp
 257 .LP
 258 Property creation is done by creating a new property definition in the driver's
 259 property list associated with \fIdip\fR.
 260 .sp
 261 .LP
 262 Property definitions are stacked; they are added to the beginning of the
 263 driver's property list when created. Thus, when searched for, the most recent
 264 matching property definition will be found and its value will be return to the
 265 caller.
 266 .sp
 267 .LP
 268 The individual functions are described as follows:
 269 .sp
 270 .ne 2
 271 .na
 272 \fB\fBddi_prop_create()\fR\fR
 273 .ad
 274 .RS 25n
 275 \fBddi_prop_create()\fR adds a property to the device's property list. If the
 276 property is not associated with any particular \fIdev\fR but is associated with
 277 the physical device itself, then the argument \fIdev\fR should be the special
 278 device \fBDDI_DEV_T_NONE\fR. If you do not have a \fIdev\fR for your device
 279 (for example during \fBattach\fR(9E) time), you can create one using
 280 \fBmakedevice\fR(9F) with a major number of \fBDDI_MAJOR_T_UNKNOWN.\fR
 281 \fBddi_prop_create()\fR will then make the correct \fIdev\fR for your device.
 282 .sp
 283 For boolean properties, you must set \fIlength\fR to \fB0\fR. For all other
 284 properties, the \fIlength\fR argument must be set to the number of bytes used
 285 by the data structure representing the property being created.
 286 .sp
 287 Note that creating a property involves allocating memory for the property list,
 288 the property name and the property value. If \fIflags\fR does not contain
 289 \fBDDI_PROP_CANSLEEP\fR, \fBddi_prop_create()\fR returns
 290 \fBDDI_PROP_NO_MEMORY\fR on memory allocation failure or \fBDDI_PROP_SUCCESS\fR
 291 if the allocation succeeded. If \fBDDI_PROP_CANSLEEP\fR was set, the caller may
 292 sleep until memory becomes available.
 293 .RE
 294
 295 .sp
 296 .ne 2
 297 .na
 298 \fB\fBddi_prop_undefine()\fR\fR
 299 .ad
 300 .RS 25n
 301 \fBddi_prop_undefine()\fR is a special case of property creation where the
 302 value of the property is set to undefined. This property has the effect of
 303 terminating a property search at the current devinfo node, rather than allowing
 304 the search to proceed up to ancestor devinfo nodes. However,
 305 \fBddi_prop_undefine()\fR will not terminate a search when the
 306 \fBddi_prop_get_int\fR(9F) or \fBddi_prop_lookup\fR(9F) routines are used for
 307 lookup of 64-bit property value. See \fBddi_prop_op\fR(9F).
 308 .sp
 309 Note that undefining properties does involve memory allocation, and therefore,
 310 is subject to the same memory allocation constraints as
 311 \fBddi_prop_create()\fR.
 312 .RE
 313
 314 .sp
 315 .ne 2
 316 .na
 317 \fB\fBddi_prop_modify()\fR\fR
 318 .ad
 319 .RS 25n
 320 \fBddi_prop_modify()\fR modifies the length and the value of a property. If
 321 \fBddi_prop_modify()\fR finds the property in the driver's property list,
 322 allocates memory for the property value and returns \fBDDI_PROP_SUCCESS\fR. If
 323 the property was not found, the function returns \fBDDI_PROP_NOT_FOUND\fR.
 324 .sp
 325 Note that modifying properties does involve memory allocation, and therefore,
 326 is subject to the same memory allocation constraints as
 327 \fBddi_prop_create()\fR.
 328 .RE
 329
 330 .sp
 331 .ne 2
 332 .na
 333 \fB\fBddi_prop_remove()\fR\fR
 334 .ad
 335 .RS 25n
 336 \fBddi_prop_remove()\fR unlinks a property from the device's property list. If
 337 \fBddi_prop_remove()\fR finds the property (an exact match of both
 338 \fIname\fRand \fIdev\fR), it unlinks the property, frees its memory, and
 339 returns \fBDDI_PROP_SUCCESS,\fR otherwise, it returns \fBDDI_PROP_NOT_FOUND\fR.
 340 .RE
 341
 342 .sp
 343 .ne 2
 344 .na
 345 \fB\fBddi_prop_remove_all()\fR\fR
 346 .ad
 347 .RS 25n
 348 \fBddi_prop_remove_all()\fR removes the properties of all the \fBdev_t\fR's
 349 associated with the \fIdip\fR. It is called before unloading a driver.
 350 .RE
 351
 352 .SH RETURN VALUES
 353 .sp
 354 .LP
 355 The \fBddi_prop_create()\fR function returns the following values:
 356 .sp
 357 .ne 2
 358 .na
 359 \fB\fBDDI_PROP_SUCCESS\fR\fR
 360 .ad
 361 .RS 22n
 362 On success.
 363 .RE
 364
 365 .sp
 366 .ne 2
 367 .na
 368 \fB\fBDDI_PROP_NO_MEMORY\fR\fR
 369 .ad
 370 .RS 22n
 371 On memory allocation failure.
 372 .RE
 373
 374 .sp
 375 .ne 2
 376 .na
 377 \fB\fBDDI_PROP_INVAL_ARG\fR\fR
 378 .ad
 379 .RS 22n
 380 If an attempt is made to create a property with \fIdev\fR equal to
 381 \fBDDI_DEV_T_ANY\fR or if \fIname\fR is \fINULL\fR or \fIname\fR is the
 382 \fINULL\fR string.
 383 .RE
 384
 385 .sp
 386 .LP
 387 The \fBddi_prop_ undefine()\fR function returns the following values:
 388 .sp
 389 .ne 2
 390 .na
 391 \fB\fBDDI_PROP_SUCCESS\fR\fR
 392 .ad
 393 .RS 22n
 394 On success.
 395 .RE
 396
 397 .sp
 398 .ne 2
 399 .na
 400 \fB\fBDDI_PROP_NO_MEMORY\fR\fR
 401 .ad
 402 .RS 22n
 403 On memory allocation failure.
 404 .RE
 405
 406 .sp
 407 .ne 2
 408 .na
 409 \fB\fBDDI_PROP_INVAL_ARG\fR\fR
 410 .ad
 411 .RS 22n
 412 If an attempt is made to create a property with \fIdev\fR \fBDDI_DEV_T_ANY\fR
 413 or if \fIname\fR is \fINULL\fR or \fIname\fR is the \fINULL\fR string.
 414 .RE
 415
 416 .sp
 417 .LP
 418 The \fBddi_prop_modify()\fR function returns the following values:
 419 .sp
 420 .ne 2
 421 .na
 422 \fB\fBDDI_PROP_SUCCESS\fR\fR
 423 .ad
 424 .RS 22n
 425 On success.
 426 .RE
 427
 428 .sp
 429 .ne 2
 430 .na
 431 \fB\fBDDI_PROP_NO_MEMORY\fR\fR
 432 .ad
 433 .RS 22n
 434 On memory allocation failure.
 435 .RE
 436
 437 .sp
 438 .ne 2
 439 .na
 440 \fB\fBDDI_PROP_INVAL_ARG\fR\fR
 441 .ad
 442 .RS 22n
 443 If an attempt is made to create a property with \fIdev\fR equal to
 444 \fBDDI_DEV_T_ANY\fR or if \fIname\fR is \fINULL\fR or \fIname\fR is the
 445 \fINULL\fR string.
 446 .RE
 447
 448 .sp
 449 .ne 2
 450 .na
 451 \fB\fBDDI_PROP_NOT_FOUND\fR\fR
 452 .ad
 453 .RS 22n
 454 On property search failure.
 455 .RE
 456
 457 .sp
 458 .LP
 459 The \fBddi_prop_remove()\fR function returns the following values:
 460 .sp
 461 .ne 2
 462 .na
 463 \fB\fBDDI_PROP_SUCCESS\fR\fR
 464 .ad
 465 .RS 22n
 466 On success.
 467 .RE
 468
 469 .sp
 470 .ne 2
 471 .na
 472 \fB\fBDDI_PROP_INVAL_ARG\fR\fR
 473 .ad
 474 .RS 22n
 475 If an attempt is made to create a property with \fIdev\fR equal to
 476 \fBDDI_DEV_T_ANY\fR or if \fIname\fR is \fINULL\fR or \fIname\fR is the
 477 \fINULL\fR string.
 478 .RE
 479
 480 .sp
 481 .ne 2
 482 .na
 483 \fB\fBDDI_PROP_NOT_FOUND\fR\fR
 484 .ad
 485 .RS 22n
 486 On property search failure.
 487 .RE
 488
 489 .SH CONTEXT
 490 .sp
 491 .LP
 492 If \fBDDI_PROP_CANSLEEP\fR is set, these functions can cannot be called from
 493 interrupt context. Otherwise, they can be called from user, interrupt, or
 494 kernel context.
 495 .SH EXAMPLES
 496 .LP
 497 \fBExample 1 \fRCreating a Property
 498 .sp
 499 .LP
 500 The following example creates a property called \fInblocks\fR for each
 501 partition on a disk.
 502
 503 .sp
 504 .in +2
 505 .nf
 506 int propval = 8192;
 507
 508 for (minor = 0; minor < 8; minor ++) {
 509            (void) ddi_prop_create(makedevice(DDI_MAJOR_T_UNKNOWN, minor),
 510                dev, DDI_PROP_CANSLEEP, "nblocks", (caddr_t) &propval,
 511             sizeof (int));
 512                \&.\|.\|.
 513 }
 514 .fi
 515 .in -2
 516
 517 .SH ATTRIBUTES
 518 .sp
 519 .LP
 520 See \fBattributes\fR(5) for a description of the following attributes:
 521 .sp
 522
 523 .sp
 524 .TS
 525 box;
 526 c | c
 527 l | l .
 528 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 529 _
 530 Stability Level T{
 531 \fBddi_prop_create()\fR and \fBddi_prop_modify()\fR are Obsolete
 532 T}
 533 .TE
 534
 535 .SH SEE ALSO
 536 .sp
 537 .LP
 538 \fBdriver.conf\fR(4), \fBattributes\fR(5), \fBattach\fR(9E),
 539 \fBddi_getproplen\fR(9F), \fBddi_prop_op\fR(9F), \fBddi_prop_update\fR(9F),
 540 \fBmakedevice\fR(9F)
 541 .sp
 542 .LP
 543 \fIWriting Device Drivers\fR