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

   1 '\" te
   2 .\" Copyright (c) 2006, Sun Microsystems, Inc.
   3 .\" All Rights Reserved
   4 .\" 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.
   5 .\" 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.
   6 .\" 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]
   7 .TH DDI_SOFT_STATE 9F "Jan 16, 2006"
   8 .SH NAME
   9 ddi_soft_state, ddi_get_soft_state, ddi_soft_state_fini, ddi_soft_state_free,
  10 ddi_soft_state_init, ddi_soft_state_zalloc \- driver soft state utility
  11 routines
  12 .SH SYNOPSIS
  13 .LP
  14 .nf
  15 #include <sys/ddi.h>
  16 #include <sys/sunddi.h>
  17
  18
  19
  20 \fBvoid *\fR\fBddi_get_soft_state\fR(\fBvoid\fR \fI*state\fR, \fBint\fR \fIitem\fR);
  21 .fi
  22
  23 .LP
  24 .nf
  25 \fBvoid\fR \fBddi_soft_state_fini\fR(\fBvoid\fR \fI**state_p\fR);
  26 .fi
  27
  28 .LP
  29 .nf
  30 \fBvoid\fR \fBddi_soft_state_free\fR(\fBvoid\fR \fI*state\fR, \fBint\fR \fIitem\fR);
  31 .fi
  32
  33 .LP
  34 .nf
  35 \fBint\fR \fBddi_soft_state_init\fR(\fBvoid\fR \fI**state_p\fR, \fBsize_t\fR \fIsize\fR, \fBsize_t\fR \fIn_items\fR);
  36 .fi
  37
  38 .LP
  39 .nf
  40 \fBint\fR \fBddi_soft_state_zalloc\fR(\fBvoid\fR \fI*state\fR, \fBint\fR \fIitem\fR);
  41 .fi
  42
  43 .SH INTERFACE LEVEL
  44 .sp
  45 .LP
  46 Solaris DDI specific (Solaris DDI).
  47 .SH PARAMETERS
  48 .sp
  49 .ne 2
  50 .na
  51 \fB\fIstate_p\fR\fR
  52 .ad
  53 .RS 11n
  54 Address of the opaque state pointer which will be initialized by
  55 \fBddi_soft_state_init()\fR to point to implementation dependent data.
  56 .RE
  57
  58 .sp
  59 .ne 2
  60 .na
  61 \fB\fIsize\fR\fR
  62 .ad
  63 .RS 11n
  64 Size of the item which will be allocated by subsequent calls to
  65 \fBddi_soft_state_zalloc()\fR.
  66 .RE
  67
  68 .sp
  69 .ne 2
  70 .na
  71 \fB\fIn_items\fR\fR
  72 .ad
  73 .RS 11n
  74 A hint of the number of items which will be preallocated; zero is allowed.
  75 .RE
  76
  77 .sp
  78 .ne 2
  79 .na
  80 \fB\fIstate\fR\fR
  81 .ad
  82 .RS 11n
  83 An opaque pointer to implementation-dependent data that describes the soft
  84 state.
  85 .RE
  86
  87 .sp
  88 .ne 2
  89 .na
  90 \fB\fIitem\fR\fR
  91 .ad
  92 .RS 11n
  93 The item number for the state structure; usually the instance number of the
  94 associated devinfo node.
  95 .RE
  96
  97 .SH DESCRIPTION
  98 .sp
  99 .LP
 100 Most device drivers maintain state information with each instance of the device
 101 they control; for example, a soft copy of a device control register, a mutex
 102 that must be held while accessing a piece of hardware, a partition table, or a
 103 unit structure. These utility routines are intended to help device drivers
 104 manage the space used by the driver to hold such state information.
 105 .sp
 106 .LP
 107 For example, if the driver holds the state of each instance in a single state
 108 structure, these routines can be used to dynamically allocate and deallocate a
 109 separate structure for each instance of the driver as the instance is attached
 110 and detached.
 111 .sp
 112 .LP
 113 To use the routines, the driver writer needs to declare a state pointer,
 114 \fIstate_p\fR, which the implementation uses as a place to hang a set of
 115 per-driver structures; everything else is managed by these routines.
 116 .sp
 117 .LP
 118 The routine \fBddi_soft_state_init()\fR is usually called in the driver's
 119 \fB_init\fR(9E) routine to initialize the state pointer, set the size of the
 120 soft state structure, and to allow the driver to pre-allocate a given number of
 121 such structures if required.
 122 .sp
 123 .LP
 124 The routine \fBddi_soft_state_zalloc()\fR is usually called in the driver's
 125 \fBattach\fR(9E) routine.  The routine is passed an item number which is used
 126 to refer to the structure in subsequent calls to \fBddi_get_soft_state()\fR and
 127 \fBddi_soft_state_free()\fR. The item number is usually just the instance
 128 number of the \fBdevinfo\fR node, obtained with \fBddi_get_instance\fR(9F). The
 129 routine attempts to allocate space for the new structure, and if the space
 130 allocation was successful, \fBDDI_SUCCESS\fR is returned to the caller.
 131 Returned memory is zeroed.
 132 .sp
 133 .LP
 134 A pointer to the space previously allocated for a soft state structure can be
 135 obtained by calling \fBddi_get_soft_state()\fR with the appropriate item
 136 number.
 137 .sp
 138 .LP
 139 The space used by a given soft state structure can be returned to the system
 140 using \fBddi_soft_state_free()\fR. This routine is usually called from the
 141 driver's \fBdetach\fR(9E) entry point.
 142 .sp
 143 .LP
 144 The space used by all the soft state structures allocated on a given state
 145 pointer, together with the housekeeping information used by the implementation
 146 can be returned to the system using \fBddi_soft_state_fini()\fR. This routine
 147 can be called from the driver's \fB_fini\fR(9E) routine.
 148 .sp
 149 .LP
 150 The \fBddi_soft_state_zalloc()\fR, \fBddi_soft_state_free()\fR and
 151 \fBddi_get_soft_state()\fR routines coordinate access to the underlying data
 152 structures in an MT-safe fashion, thus no additional locks should be necessary.
 153 .SH RETURN VALUES
 154 .sp
 155 .LP
 156 \fBddi_get_soft_state()\fR
 157 .sp
 158 .ne 2
 159 .na
 160 \fB\fINULL\fR\fR
 161 .ad
 162 .RS 11n
 163 The requested state structure was not allocated at the time of the call.
 164 .RE
 165
 166 .sp
 167 .ne 2
 168 .na
 169 \fB\fIpointer\fR\fR
 170 .ad
 171 .RS 11n
 172 The pointer to the state structure.
 173 .RE
 174
 175 .sp
 176 .LP
 177 \fBddi_soft_state_init()\fR
 178 .sp
 179 .ne 2
 180 .na
 181 \fB\fB0\fR\fR
 182 .ad
 183 .RS 10n
 184 The allocation was successful.
 185 .RE
 186
 187 .sp
 188 .ne 2
 189 .na
 190 \fB\fBEINVAL\fR\fR
 191 .ad
 192 .RS 10n
 193 Either the \fBsize\fR parameter was zero, or the \fIstate_p\fR parameter was
 194 invalid.
 195 .RE
 196
 197 .sp
 198 .LP
 199 \fBddi_soft_state_zalloc()\fR
 200 .sp
 201 .ne 2
 202 .na
 203 \fB\fBDDI_SUCCESS\fR\fR
 204 .ad
 205 .RS 15n
 206 The allocation was successful.
 207 .RE
 208
 209 .sp
 210 .ne 2
 211 .na
 212 \fB\fBDDI_FAILURE\fR\fR
 213 .ad
 214 .RS 15n
 215 The routine failed to allocate the storage required; either the \fIstate\fR
 216 parameter was invalid, the item number was negative, or an attempt was made to
 217 allocate an item number that was already allocated.
 218 .RE
 219
 220 .SH CONTEXT
 221 .sp
 222 .LP
 223 The \fBddi_soft_state_init()\fR and \fBddi_soft_state_alloc()\fR functions can
 224 be called from user or kernel context only, since they may internally call
 225 \fBkmem_zalloc\fR(9F) with the \fBKM_SLEEP\fR flag.
 226 .sp
 227 .LP
 228 The \fBddi_soft_state_fini()\fR, \fBddi_soft_state_free()\fR and
 229 \fBddi_get_soft_state()\fR routines can be called from any driver context.
 230 .SH EXAMPLES
 231 .LP
 232 \fBExample 1 \fRCreating and Removing Data Structures
 233 .sp
 234 .LP
 235 The following example shows how the routines described above can be used in
 236 terms of the driver entry points of a character-only driver. The example
 237 concentrates on the portions of the code that deal with creating and removing
 238 the driver's data structures.
 239
 240 .sp
 241 .in +2
 242 .nf
 243 typedef struct {
 244    volatile caddr_t *csr;        /* device registers */
 245    kmutex_t         csr_mutex;   /* protects 'csr' field */
 246    unsigned int     state;
 247    dev_info_t       *dip;        /* back pointer to devinfo */
 248 } devstate_t;
 249 static void *statep;
 250
 251 int
 252 _init(void)
 253 {
 254    int error;
 255
 256    error = ddi_soft_state_init(&statep, sizeof (devstate_t), 0);
 257    if (error != 0)
 258                    return (error);
 259    if ((error = mod_install(&modlinkage)) != 0)
 260                    ddi_soft_state_fini(&statep);
 261    return (error);
 262 }
 263
 264 int
 265 _fini(void)
 266 {
 267    int error;
 268
 269    if ((error = mod_remove(&modlinkage)) != 0)
 270                    return (error);
 271    ddi_soft_state_fini(&statep);
 272    return (0);
 273 }
 274
 275 static int
 276 xxattach(dev_info_t *dip, ddi_attach_cmd_t cmd)
 277 {
 278    int instance;
 279    devstate_t *softc;
 280
 281    switch (cmd) {
 282    case DDI_ATTACH:
 283               instance = ddi_get_instance(dip);
 284       if (ddi_soft_state_zalloc(statep, instance) != DDI_SUCCESS)
 285                  return (DDI_FAILURE);
 286               softc = ddi_get_soft_state(statep, instance);
 287               softc->dip = dip;
 288               ...
 289               return (DDI_SUCCESS);
 290    default:
 291               return (DDI_FAILURE);
 292    }
 293 }
 294
 295 static int
 296 xxdetach(dev_info_t *dip, ddi_detach_cmd_t cmd)
 297 {
 298    int instance;
 299
 300    switch (cmd) {
 301
 302    case DDI_DETACH:
 303               instance = ddi_get_instance(dip);
 304               ...
 305       ddi_soft_state_free(statep, instance);
 306       return (DDI_SUCCESS);
 307
 308    default:
 309       return (DDI_FAILURE);
 310    }
 311 }
 312
 313 static int
 314 xxopen(dev_t *devp, int flag, int otyp, cred_t *cred_p)
 315 {
 316    devstate_t *softc;
 317    int   instance;
 318
 319    instance = getminor(*devp);
 320    if ((softc = ddi_get_soft_state(statep, instance)) == NULL)
 321               return (ENXIO);
 322    ...
 323    softc->state |= XX_IN_USE;
 324    ...
 325    return (0);
 326 }
 327 .fi
 328 .in -2
 329
 330 .SH SEE ALSO
 331 .sp
 332 .LP
 333 \fB_fini\fR(9E), \fB_init\fR(9E), \fBattach\fR(9E), \fBdetach\fR(9E),
 334 \fBddi_get_instance\fR(9F), \fBgetminor\fR(9F), \fBkmem_zalloc\fR(9F)
 335 .sp
 336 .LP
 337 \fIWriting Device Drivers\fR
 338 .SH WARNINGS
 339 .sp
 340 .LP
 341 There is no attempt to validate the \fBitem\fR parameter given to
 342 \fBddi_soft_state_zalloc()\fR other than it must be a positive signed integer.
 343 Therefore very large item numbers may cause the driver to hang forever waiting
 344 for virtual memory resources that can never be satisfied.
 345 .SH NOTES
 346 .sp
 347 .LP
 348 If necessary, a hierarchy of state structures can be constructed by embedding
 349 state pointers in higher order state structures.
 350 .SH DIAGNOSTICS
 351 .sp
 352 .LP
 353 All of the messages described below usually indicate bugs in the driver and
 354 should not appear in normal operation of the system.
 355 .sp
 356 .in +2
 357 .nf
 358 WARNING: ddi_soft_state_zalloc: bad handle
 359 WARNING: ddi_soft_state_free: bad handle
 360 WARNING: ddi_soft_state_fini: bad handle
 361 .fi
 362 .in -2
 363
 364 .sp
 365 .LP
 366 The implementation-dependent information kept in the state variable is corrupt.
 367 .sp
 368 .in +2
 369 .nf
 370 WARNING: ddi_soft_state_free: null handle
 371 WARNING: ddi_soft_state_fini: null handle
 372 .fi
 373 .in -2
 374
 375 .sp
 376 .LP
 377 The routine has been passed a null or corrupt state pointer.  Check that
 378 \fBddi_soft_state_init()\fR has been called.
 379 .sp
 380 .in +2
 381 .nf
 382 WARNING: ddi_soft_state_free: item %d not in range [0..%d]
 383 .fi
 384 .in -2
 385
 386 .sp
 387 .LP
 388 The routine has been asked to free an item which was never allocated. The
 389 message prints out the invalid item number and the acceptable range.