Current File : //usr/share/man/man9f/id32_alloc.9f

'\" te
.\" Copyright (c) 2001, Sun Microsystems, Inc. All Rights Reserved
.TH id32_alloc 9F "12 Dec 2001" "SunOS 5.11" "Kernel Functions for Drivers"
.SH NAME
id32_alloc, id32_free, id32_lookup \- 32-bit driver ID management routines
.SH SYNOPSIS
.LP
.nf
#include <sys/ddi.h>
#include <sys/id32.h>

\fBuint32_t\fR \fBid32_alloc\fR(\fBvoid *\fR\fIptr\fR, \fBint\fR \fIflag\fR);
.fi

.LP
.nf
\fBvoid\fR \fBid32_free\fR(\fBuint32_t\fR \fItoken\fR);
.fi

.LP
.nf
\fBvoid *\fR\fBid32_lookup\fR(\fBuint32_t\fR \fItoken\fR);
.fi

.SH INTERFACE LEVEL
.sp
.LP
Solaris architecture specific (Solaris DDI).
.SH PARAMETERS
.sp
.ne 2
.mk
.na
\fB\fIptr\fR\fR
.ad
.RS 9n
.rt  
any valid 32- or 64-bit pointer
.RE

.sp
.ne 2
.mk
.na
\fB\fIflag\fR \fR
.ad
.RS 9n
.rt  
determines whether caller can sleep for memory (see \fBkmem_alloc\fR(9F) for a description)
.RE

.SH DESCRIPTION
.sp
.LP
These routines were originally developed so that device drivers could manage 64-bit pointers on devices that save space only for 32-bit pointers.
.sp
.LP
Many device drivers need to pass a 32-bit value to the hardware when attempting I/O.  Later, when that I/O completes, the only way the driver has to identify the request that generated that I/O is via a "token". When the I/O is initiated, the driver passes this token to the hardware. When the I/O completes the hardware passes back this 32-bit token.
.sp
.LP
Before Solaris supported 64-bit pointers, device drivers just passed a raw 32-bit pointer to the hardware. When pointers grew to be 64 bits this was no longer possible. The \fBid32_*()\fR routines were created to help drivers translate between 64-bit pointers and a 32-bit token.
.sp
.LP
Given a 32- or 64-bit pointer, the routine \fBid32_alloc()\fR allocates a 32-bit token, returning 0 if \fBKM_NOSLEEP\fR was specified and memory could not be allocated. The allocated token is passed back to \fBid32_lookup()\fR to obtain the original 32- or 64-bit pointer.
.sp
.LP
The routine \fBid32_free()\fR is used to free an allocated token. Once \fBid32_free()\fR is called, the supplied token is no longer valid.
.sp
.LP
Note that these routines have some degree of error checking. This is done so that an invalid token passed to \fBid32_lookup()\fR will not be accepted as valid. When \fBid32_lookup()\fR detects an invalid token it returns NULL. Calling routines should check for this return value so that they do not try to dereference a NULL pointer.
.SH CONTEXT
.sp
.LP
These functions can be called from user or interrupt context. The routine \fBid32_alloc()\fR should not be called from interrupt context when the \fBKM_SLEEP\fR flag is passed in. All other routines can be called from interrupt or kernel context.
.SH SEE ALSO
.sp
.LP
\fBkmem_alloc\fR(9F)
.sp
.LP
\fIWriting Device Drivers for Oracle Solaris 11.2\fR