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

   1 '\" te
   2 .\" Copyright (c) 2001, 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 ID32_ALLOC 9F "Dec 12, 2001"
   7 .SH NAME
   8 id32_alloc, id32_free, id32_lookup \- 32-bit driver ID management routines
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/ddi.h>
  13 #include <sys/id32.h>
  14
  15
  16
  17 \fBuint32_t\fR \fBid32_alloc\fR(\fBvoid *\fR\fIptr\fR, \fBint\fR \fIflag\fR);
  18 .fi
  19
  20 .LP
  21 .nf
  22 \fBvoid\fR \fBid32_free\fR(\fBuint32_t\fR \fItoken\fR);
  23 .fi
  24
  25 .LP
  26 .nf
  27 \fBvoid *\fR\fBid32_lookup\fR(\fBuint32_t\fR \fItoken\fR);
  28 .fi
  29
  30 .SH INTERFACE LEVEL
  31 .sp
  32 .LP
  33 Solaris architecture specific (Solaris DDI).
  34 .SH PARAMETERS
  35 .sp
  36 .ne 2
  37 .na
  38 \fB\fIptr\fR\fR
  39 .ad
  40 .RS 9n
  41 any valid 32- or 64-bit pointer
  42 .RE
  43
  44 .sp
  45 .ne 2
  46 .na
  47 \fB\fIflag\fR \fR
  48 .ad
  49 .RS 9n
  50 determines whether caller can sleep for memory (see \fBkmem_alloc\fR(9F) for a
  51 description)
  52 .RE
  53
  54 .SH DESCRIPTION
  55 .sp
  56 .LP
  57 These routines were originally developed so that device drivers could manage
  58 64-bit pointers on devices that save space only for 32-bit pointers.
  59 .sp
  60 .LP
  61 Many device drivers need to pass a 32-bit value to the hardware when attempting
  62 I/O.  Later, when that I/O completes, the only way the driver has to identify
  63 the request that generated that I/O is via a "token". When the I/O is
  64 initiated, the driver passes this token to the hardware. When the I/O completes
  65 the hardware passes back this 32-bit token.
  66 .sp
  67 .LP
  68 Before Solaris supported 64-bit pointers, device drivers just passed a raw
  69 32-bit pointer to the hardware. When pointers grew to be 64 bits this was no
  70 longer possible. The \fBid32_*()\fR routines were created to help drivers
  71 translate between 64-bit pointers and a 32-bit token.
  72 .sp
  73 .LP
  74 Given a 32- or 64-bit pointer, the routine \fBid32_alloc()\fR allocates a
  75 32-bit token, returning 0 if \fBKM_NOSLEEP\fR was specified and memory could
  76 not be allocated. The allocated token is passed back to \fBid32_lookup()\fR to
  77 obtain the original 32- or 64-bit pointer.
  78 .sp
  79 .LP
  80 The routine \fBid32_free()\fR is used to free an allocated token. Once
  81 \fBid32_free()\fR is called, the supplied token is no longer valid.
  82 .sp
  83 .LP
  84 Note that these routines have some degree of error checking. This is done so
  85 that an invalid token passed to \fBid32_lookup()\fR will not be accepted as
  86 valid. When \fBid32_lookup()\fR detects an invalid token it returns NULL.
  87 Calling routines should check for this return value so that they do not try to
  88 dereference a NULL pointer.
  89 .SH CONTEXT
  90 .sp
  91 .LP
  92 These functions can be called from user or interrupt context. The routine
  93 \fBid32_alloc()\fR should not be called from interrupt context when the
  94 \fBKM_SLEEP\fR flag is passed in. All other routines can be called from
  95 interrupt or kernel context.
  96 .SH SEE ALSO
  97 .sp
  98 .LP
  99 \fBkmem_alloc\fR(9F)
 100 .sp
 101 .LP
 102 \fIWriting Device Drivers\fR