Kernel Functions for Drivers                       id32alloc(9F)



NAME
     id32alloc,  id32free,  id32lookup  -  32-bit  driver   ID
     management routines

SYNOPSIS
     #include 
     #include 



     uint32t id32alloc(void *ptr, int flag);


     void id32free(uint32t token);


     void *id32lookup(uint32t token);


INTERFACE LEVEL
     Solaris architecture specific (Solaris DI).

PARAMETERS
     ptr      any valid 32- or 64-bit pointer


     flag     determines whether caller can sleep for memory (see
              kmemalloc(9F) for a description)


DESCRIPTION
     These routines were  originally  developed  so  that  device
     drivers  could  manage  64-bit pointers on devices that save
     space only for 32-bit pointers.


     Many device drivers need to  pass  a  32-bit  value  to  the
     hardware  when  attempting  I/O.   Later, when that I/O com-
     pletes, 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.


     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
     id32*()  routines  were  created  to help drivers translate
     between 64-bit pointers and a 32-bit token.





SunOS 5.11          Last change: 12 Dec 2001                    1






Kernel Functions for Drivers                       id32alloc(9F)



     Given a 32- or  64-bit  pointer,  the  routine  id32alloc()
     allocates  a  32-bit  token,  returning  0 if KMNOSLEP was
     specified and memory could not be allocated.  The  allocated
     token is passed back to id32lookup() to obtain the original
     32- or 64-bit pointer.


     The routine id32free() is used to free an allocated  token.
     Once  id32free() is called, the supplied token is no longer
     valid.


     Note that these routines have some degree of error checking.
     This   is   done   so   that  an  invalid  token  passed  to
     id32lookup()  will  not  be   accepted   as   valid.   When
     id32lookup() detects an invalid token it returns NUL. Cal-
     ling routines should check for this  return  value  so  that
     they do not try to dereference a NUL pointer.

CONTEXT
     These functions can be called from user  or  interrupt  con-
     text.  The  routine  id32alloc()  should not be called from
     interrupt context when the KMSLEP flag is passed  in.  All
     other  routines  can be called from interrupt or kernel con-
     text.

SEE ALSO
     kmemalloc(9F)


     Writing Device Drivers
























SunOS 5.11          Last change: 12 Dec 2001                    2