Manual Pages for UNIX Operating System command usage for man id32_lookup

Kernel Functions for Drivers                       id32_alloc(9F)



NAME
     id32_alloc,  id32_free,  id32_lookup  -  32-bit  driver   ID
     management routines

SYNOPSIS
     #include 
     #include 



     uint32_t id32_alloc(void *ptr, int flag);


     void id32_free(uint32_t token);


     void *id32_lookup(uint32_t token);


INTERFACE LEVEL
     Solaris architecture specific (Solaris DDI).

PARAMETERS
     ptr      any valid 32- or 64-bit pointer


     flag     determines whether caller can sleep for memory (see
              kmem_alloc(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                       id32_alloc(9F)



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


     The routine id32_free() is used to free an allocated  token.
     Once  id32_free() 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
     id32_lookup()  will  not  be   accepted   as   valid.   When
     id32_lookup() detects an invalid token it returns NULL. Cal-
     ling routines should check for this  return  value  so  that
     they do not try to dereference a NULL pointer.

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

SEE ALSO
     kmem_alloc(9F)


     Writing Device Drivers
























SunOS 5.11          Last change: 12 Dec 2001                    2