share/man/man9f/STRUCT_DECL.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 STRUCT_DECL 9F "May 20, 2006"
   7 .SH NAME
   8 STRUCT_DECL, SIZEOF_PTR, SIZEOF_STRUCT, STRUCT_BUF, STRUCT_FADDR, STRUCT_FGET,
   9 STRUCT_FGETP, STRUCT_FSET, STRUCT_FSETP, STRUCT_HANDLE, STRUCT_INIT,
  10 STRUCT_SIZE, STRUCT_SET_HANDLE \- 32-bit application data access macros
  11 .SH SYNOPSIS
  12 .LP
  13 .nf
  14 #include <sys/ddi.h>
  15 #include <sys/sunddi.h>
  16
  17
  18
  19 \fB\fR\fBSTRUCT_DECL\fR(\fB\fR\fIstructname\fR, \fB\fR \fIhandle\fR);
  20 .fi
  21
  22 .LP
  23 .nf
  24 \fB\fR\fBSTRUCT_HANDLE\fR(\fB\fR\fIstructname\fR, \fB\fR\fIhandle\fR);
  25 .fi
  26
  27 .LP
  28 .nf
  29 \fBvoid\fR \fBSTRUCT_INIT\fR(\fB\fR\fIhandle\fR, \fBmodel_t\fR \fIumodel\fR);
  30 .fi
  31
  32 .LP
  33 .nf
  34 \fBvoid\fR \fBSTRUCT_SET_HANDLE\fR(\fB\fR\fIhandle\fR, \fBmodel_t\fR \fIumodel\fR, \fBvoid\fR \fI*addr\fR);
  35 .fi
  36
  37 .LP
  38 .nf
  39 \fB\fR\fBSTRUCT_FGET\fR(\fB\fR\fIhandle\fR, \fB\fR\fIfield\fR);
  40 .fi
  41
  42 .LP
  43 .nf
  44 \fB\fR\fBSTRUCT_FGETP\fR(\fB\fR\fIhandle\fR, \fB\fR\fIfield\fR);
  45 .fi
  46
  47 .LP
  48 .nf
  49 \fB\fR\fBSTRUCT_FSET\fR(\fB\fR\fIhandle\fR, \fB\fR\fIfield\fR, \fB\fR\fIval\fR);
  50 .fi
  51
  52 .LP
  53 .nf
  54 \fB\fR\fBSTRUCT_FSETP\fR(\fB\fR\fIhandle\fR, \fB\fR\fIfield\fR, \fB\fR\fIval\fR);
  55 .fi
  56
  57 .LP
  58 .nf
  59 \fB<typeof field> *\fR\fBSTRUCT_FADDR\fR(\fB\fR\fIhandle\fR, \fB\fR\fIfield\fR);
  60 .fi
  61
  62 .LP
  63 .nf
  64 \fBstruct structname *\fR\fBSTRUCT_BUF\fR(\fB\fR\fIhandle\fR);
  65 .fi
  66
  67 .LP
  68 .nf
  69 \fBsize_t\fR \fBSIZEOF_STRUCT\fR(\fB\fR\fIstructname\fR, \fB\fR\fIumodel\fR);
  70 .fi
  71
  72 .LP
  73 .nf
  74 \fBsize_t\fR \fBSIZEOF_PTR\fR(\fB\fR\fIumodel\fR);
  75 .fi
  76
  77 .LP
  78 .nf
  79 \fBsize_t\fR \fBSTRUCT_SIZE\fR(\fB\fR\fIhandle\fR);
  80 .fi
  81
  82 .SH INTERFACE LEVEL
  83 .sp
  84 .LP
  85 Solaris DDI specific (Solaris DDI).
  86 .SH PARAMETERS
  87 .sp
  88 .LP
  89 The macros take the following parameters:
  90 .sp
  91 .ne 2
  92 .na
  93 \fB\fIstructname\fR\fR
  94 .ad
  95 .RS 14n
  96 The structure name that appears \fBafter\fR the \fBC\fR keyword struct of the
  97 native form.
  98 .RE
  99
 100 .sp
 101 .ne 2
 102 .na
 103 \fB\fIumodel\fR\fR
 104 .ad
 105 .RS 14n
 106  A bit field that contains either the \fBILP32\fR model bit
 107 (\fBDATAMODEL_ILP32\fR), or the \fBLP64\fR model bit (\fBDATAMODEL_LP64\fR). In
 108 an \fBioctl\fR(9E), these bits are present in the flag parameter. In a
 109 \fBdevmap\fR(9E), the bits are present in the model parameter \fBmmap\fR(9E).
 110 The \fBddi_mmap_get_model\fR(9F) can be called to get the data model of the
 111 current thread.
 112 .RE
 113
 114 .sp
 115 .ne 2
 116 .na
 117 \fB\fIhandle\fR\fR
 118 .ad
 119 .RS 14n
 120 The variable name used to refer to a particular instance of a structure which
 121 is handled by these macros.
 122 .RE
 123
 124 .sp
 125 .ne 2
 126 .na
 127 \fB\fIfield\fR\fR
 128 .ad
 129 .RS 14n
 130 The field name within the structure that can contain substructures. If the
 131 structures contain substructures, unions, or arrays, the \fIfield\fR can be
 132 whatever complex expression would naturally follow the first . or ->.
 133 .RE
 134
 135 .SH DESCRIPTION
 136 .sp
 137 .LP
 138 The above macros allow a device driver to access data consumed from a 32-bit
 139 application regardless whether the driver was compiled to the ILP32 or LP64
 140 data model. These macros effectively hide the difference between the data model
 141 of the user application and the driver.
 142 .sp
 143 .LP
 144 The macros can be broken up into two main categories described in the following
 145 sections.
 146 .SS "Declaration and Initialization Macros"
 147 .sp
 148 .LP
 149 The macros \fBSTRUCT_DECL()\fR and \fBSTRUCT_HANDLE()\fR declare structure
 150 handles on the stack, whereas the macros \fBSTRUCT_INIT()\fR and
 151 \fBSTRUCT_SET_HANDLE()\fR initialize the structure handles to point to an
 152 instance of the native form structure.
 153 .sp
 154 .LP
 155 The macros \fBSTRUCT_HANDLE()\fR and \fBSTRUCT_SET_HANDLE()\fR are used to
 156 declare and initialize a structure handle to an existing data structure, for
 157 example, ioctls within a STREAMS module.
 158 .sp
 159 .LP
 160 The macros \fBSTRUCT_DECL()\fR and \fBSTRUCT_INIT()\fR, on the other hand, are
 161 used in modules which declare and initialize a structure handle to a data
 162 structure allocated by \fBSTRUCT_DECL()\fR, that is, any standard character or
 163 block device driver \fBioctl\fR(9E) routine that needs to copy in data from a
 164 user-mode program.
 165 .sp
 166 .ne 2
 167 .na
 168 \fBSTRUCT_DECL(structname, handle)\fR
 169 .ad
 170 .sp .6
 171 .RS 4n
 172 Declares a structure handle for a struct and allocates an instance of its
 173 native form on the stack. It is assumed that the native form is larger than or
 174 equal to the ILP32 form. \fIhandle\fR is a variable name and is declared as a
 175 variable by this macro.
 176 .RE
 177
 178 .sp
 179 .ne 2
 180 .na
 181 \fBvoid STRUCT_INIT(handle, model_t umodel)\fR
 182 .ad
 183 .sp .6
 184 .RS 4n
 185 Initializes \fIhandle\fR to point to the instance allocated by
 186 \fBSTRUCT_DECL()\fR. It also sets data model for \fIhandle\fR to \fIumodel\fR
 187 and it must be called before any access is made through the macros that operate
 188 on these structures. When used in an \fBioctl\fR(9E) routine, \fIumodel\fR is
 189 the flag parameter. In a \fBdevmap\fR(9E) routine, \fIumodel\fR is the model
 190 parameter. In a \fBmmap\fR(9E) routine, \fIumodel\fR is the return value of
 191 \fBddi_mmap_get_model\fR(9F). This macro is intended only for handles created
 192 with \fBSTRUCT_DECL()\fR.
 193 .RE
 194
 195 .sp
 196 .ne 2
 197 .na
 198 \fBSTRUCT_HANDLE(structname, handle)\fR
 199 .ad
 200 .sp .6
 201 .RS 4n
 202 Declares a structure handle \fIhandle\fR but, unlike \fBSTRUCT_DECL()\fR, it
 203 does not allocate an instance of "struct".
 204 .RE
 205
 206 .sp
 207 .ne 2
 208 .na
 209 \fBvoid STRUCT_SET_HANDLE(handle, model_t umodel, void *addr)\fR
 210 .ad
 211 .sp .6
 212 .RS 4n
 213 Initializes handle to point to the native form instance at \fIaddr\fR. It also
 214 sets the data model for \fIhandle\fR to \fIumodel\fR. This is intended for
 215 handles created with \fBSTRUCT_HANDLE()\fR. Fields cannot be referenced via the
 216 \fIhandle\fR until this macro has been invoked. Typically, \fIaddr\fR is the
 217 address of the native form structure containing the user-mode programs data.
 218 When used in an \fBioctl\fR(9E), \fIumodel\fR is the flag parameter. In a
 219 \fBdevmap\fR(9E) routine, \fIumodel\fR is the model parameter. In an
 220 \fBmmap\fR(9E) routine, \fIumodel\fR is the return value of
 221 \fBddi_mmap_get_model\fR(9F).
 222 .RE
 223
 224 .SS "Operation Macros"
 225 .sp
 226 .ne 2
 227 .na
 228 \fBsize_t STRUCT_SIZE(handle)\fR
 229 .ad
 230 .sp .6
 231 .RS 4n
 232 Returns size of the structure referred to by \fIhandle\fR, depending on the
 233 data model associated with \fIhandle\fR. If the data model stored by
 234 \fBSTRUCT_INIT()\fR or \fBSTRUCT_SET_HANDLE()\fR is \fBDATAMODEL_ILP32\fR, the
 235 size of the \fBILP32\fR form is returned. Otherwise, the size of the native
 236 form is returned.
 237 .RE
 238
 239 .sp
 240 .ne 2
 241 .na
 242 \fBSTRUCT_FGET(handle, field)\fR
 243 .ad
 244 .sp .6
 245 .RS 4n
 246 Returns the contents of \fIfield\fR in the structure described by \fIhandle\fR
 247 according to the data model associated with \fIhandle\fR.
 248 .RE
 249
 250 .sp
 251 .ne 2
 252 .na
 253 \fBSTRUCT_FGETP(handle, field)\fR
 254 .ad
 255 .sp .6
 256 .RS 4n
 257 This is the same as \fBSTRUCT_FGET()\fR except that the \fIfield\fR in question
 258 is a pointer of some kind. This macro casts caddr32_t to a (void *) when it is
 259 accessed. Failure to use this macro for a pointer leads to compiler warnings or
 260 failures.
 261 .RE
 262
 263 .sp
 264 .ne 2
 265 .na
 266 \fBSTRUCT_FSET(handle, field, val)\fR
 267 .ad
 268 .sp .6
 269 .RS 4n
 270 Assigns \fIval\fR to the (non-pointer) in the structure described by
 271 \fIhandle\fR. It should not be used within another expression, but only as a
 272 statement.
 273 .RE
 274
 275 .sp
 276 .ne 2
 277 .na
 278 \fBSTRUCT_FSETP(handle, field, val)\fR
 279 .ad
 280 .sp .6
 281 .RS 4n
 282 This is the equivalent of STRUCT_FGETP() for STRUCT_FGET(), with the same
 283 exceptions. Like STRUCT_FSET, STRUCT_FSETP should not be used within another
 284 expression, but only as a statement.
 285 .RE
 286
 287 .sp
 288 .ne 2
 289 .na
 290 \fBstruct structname *STRUCT_BUF(handle)\fR
 291 .ad
 292 .sp .6
 293 .RS 4n
 294 Returns a pointer to the native mode instance of the structure described by
 295 \fIhandle\fR.
 296 .RE
 297
 298 .SS "Macros Not Using Handles"
 299 .sp
 300 .ne 2
 301 .na
 302 \fBsize_t SIZEOF_STRUCT(structname, umodel)\fR
 303 .ad
 304 .sp .6
 305 .RS 4n
 306 Returns size of \fIstructname\fR based on \fIumodel\fR.
 307 .RE
 308
 309 .sp
 310 .ne 2
 311 .na
 312 \fBsize_t SIZEOF_PTR(umodel)\fR
 313 .ad
 314 .sp .6
 315 .RS 4n
 316 Returns the size of a pointer based on \fIumodel\fR.
 317 .RE
 318
 319 .SH EXAMPLES
 320 .LP
 321 \fBExample 1 \fRCopying a Structure
 322 .sp
 323 .LP
 324 The following example uses an \fBioctl\fR(9E) on a regular character device
 325 that copies a data structure that looks like this into the kernel:
 326
 327 .sp
 328 .in +2
 329 .nf
 330 struct opdata {
 331     size_t  size;
 332     uint_t  flag;
 333 };
 334 .fi
 335 .in -2
 336
 337 .LP
 338 \fBExample 2 \fRDefining a Structure
 339 .sp
 340 .LP
 341 This data structure definition describes what the \fBioctl\fR(9E) would look
 342 like in a 32-bit application using fixed width types.
 343
 344 .sp
 345 .in +2
 346 .nf
 347 #if defined(_MULTI_DATAMODEL)
 348 struct opdata32 {
 349     size32_t    size;
 350     uint32_t    flag;
 351 };
 352 #endif
 353 .fi
 354 .in -2
 355
 356 .LP
 357 \fBExample 3 \fRUsing \fBSTRUCT_DECL()\fR and \fBSTRUCT_INIT()\fR
 358 .sp
 359 .LP
 360 Note: This example uses the \fBSTRUCT_DECL()\fR and \fBSTRUCT_INIT()\fR macros
 361 to declare and initialize the structure handle.
 362
 363 .sp
 364 .in +2
 365 .nf
 366 int
 367 xxioctl(dev_t dev, int cmd, intptr_t arg, int mode,
 368     cred_t *cr, int *rval_p);
 369 {
 370     STRUCT_DECL(opdata, op);
 371
 372     if (cmd != OPONE)
 373         return (ENOTTY);
 374
 375     STRUCT_INIT(op, mode);
 376
 377     if (copyin((void *)data,
 378         STRUCT_BUF(op), STRUCT_SIZE(op)))
 379         return (EFAULT);
 380
 381     if (STRUCT_FGET(op, flag) != FACTIVE ||
 382         STRUCT_FGET(op, size) > sizeof (device_state))
 383         return (EINVAL);
 384     xxdowork(device_state, STRUCT_FGET(op, size));
 385     return (0);
 386 }
 387 .fi
 388 .in -2
 389
 390 .sp
 391 .LP
 392 This piece of code is an excerpt from a STREAMS module that handles
 393 \fBioctl\fR(9E) data (M_IOCDATA) messages and uses the data structure defined
 394 above. This code has been written to run in the ILP32 environment only.
 395
 396 .LP
 397 \fBExample 4 \fRUsing \fBSTRUCT_HANDLE()\fR and \fBSTRUCT_SET_HANDLE()\fR
 398 .sp
 399 .LP
 400 The next example illustrates the use of the \fBSTRUCT_HANDLE()\fR and
 401 \fBSTRUCT_SET_HANDLE()\fR macros which declare and initialize the structure
 402 handle to point to an already existing instance of the structure.
 403
 404 .sp
 405 .LP
 406 The above code example can be converted to run in the LP64 environment using
 407 the \fBSTRUCT_HANDLE()\fR and \fBSTRUCT_SET_HANDLE()\fR as follows:
 408
 409 .sp
 410 .in +2
 411 .nf
 412 struct strbuf {
 413 int maxlen;     /* no. of bytes in buffer */
 414 int len;        /* no. of bytes returned */
 415 caddr_t buf;        /* pointer to data */
 416 };
 417 .fi
 418 .in -2
 419
 420 .sp
 421 .in +2
 422 .nf
 423 static void
 424 wput_iocdata(queue_t *q, mblk_t *msgp)
 425 {
 426         struct copyresp *cp = (struct copyresp *)msgp->b_rptr;
 427         STRUCT_HANDLE(strbuf, sb);
 428
 429         if (msgp->b_cont->b_cont != NULL) {
 430                 msgp->b_cont = msgpullup(msgp->b_cont, -1);
 431                 if (msgp->b_cont == NULL) {
 432                         miocnak(q, msgp, 0, ENOSR);
 433                         return;
 434                 }
 435         }
 436         STRUCT_SET_HANDLE(sb, cp->cp_flag, (void *)msgp->b_cont->b_rptr);
 437         if (STRUCT_FGET(sb, maxlen) < (int)sizeof (ipa_t)) {
 438                 miocnak(q, msgp, 0, ENOSR);
 439                 return;
 440         }
 441         ...
 442         miocack(q, msgp, 0, 0);
 443 }
 444 .fi
 445 .in -2
 446
 447 .SH ATTRIBUTES
 448 .sp
 449 .LP
 450 See \fBattributes\fR(5) for descriptions of the following attributes:
 451 .sp
 452
 453 .sp
 454 .TS
 455 box;
 456 c | c
 457 l | l .
 458 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 459 _
 460 Interface Stability     Evolving
 461 .TE
 462
 463 .SH SEE ALSO
 464 .sp
 465 .LP
 466 \fBdevmap\fR(9E), \fBioctl\fR(9E), \fBmmap\fR(9E), \fBddi_mmap_get_model\fR(9F)
 467 .sp
 468 .LP
 469 \fIWriting Device Drivers\fR
 470 .sp
 471 .LP
 472 \fISTREAMS Programming Guide\fR