id32_free(9f) [opensolaris man page]

id32_alloc(9F)						   Kernel Functions for Drivers 					    id32_alloc(9F)

NAME

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

SYNOPSIS

       #include <sys/ddi.h>
       #include <sys/id32.h>

       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  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.

       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.

       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. Calling 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 context. 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 context.

SEE ALSO

       kmem_alloc(9F)

       Writing Device Drivers

SunOS 5.11							    12 Dec 2001 						    id32_alloc(9F)

kmem_alloc(9F)						   Kernel Functions for Drivers 					    kmem_alloc(9F)

NAME

       kmem_alloc, kmem_zalloc, kmem_free - allocate kernel memory

SYNOPSIS

       #include <sys/types.h>
       #include <sys/kmem.h>

       void *kmem_alloc(size_t size, int flag);

       void *kmem_zalloc(size_t size, int flag);

       void kmem_free(void*buf, size_t size);

INTERFACE LEVEL

       Architecture independent level 1 (DDI/DKI).

PARAMETERS

       size    Number of bytes to allocate.

       flag    Determines  whether  caller  can  sleep	for  memory.  Possible flags are  KM_SLEEP to allow sleeping until memory is available, or
	       KM_NOSLEEP to return NULL immediately if memory is not available.

       buf     Pointer to allocated memory.

DESCRIPTION

       The kmem_alloc() function allocates size bytes of kernel memory and returns a pointer to the allocated memory. The allocated memory  is	at
       least double-word aligned, so it can hold any C data structure. No greater alignment can be assumed. flag determines whether the caller can
       sleep for memory. KM_SLEEP allocations may sleep but are guaranteed to succeed. KM_NOSLEEP allocations are guaranteed not to sleep but  may
       fail (return NULL) if no memory is currently available. The initial contents of memory allocated using kmem_alloc() are random garbage.

       The kmem_zalloc() function is like kmem_alloc() but returns zero-filled memory.

       The  kmem_free() function frees previously allocated kernel memory. The buffer address and size must exactly match the original allocation.
       Memory cannot be returned piecemeal.

RETURN VALUES

       If successful, kmem_alloc() and kmem_zalloc() return a pointer to the allocated memory. If KM_NOSLEEP is set and memory cannot be allocated
       without sleeping, kmem_alloc() and kmem_zalloc() return NULL.

CONTEXT

       The  kmem_alloc()  and  kmem_zalloc() functions can be called from interrupt context only if the KM_NOSLEEP flag is set. They can be called
       from user context with any valid flag. The kmem_free() function can be called from from user, interrupt, or kernel context.

SEE ALSO

       copyout(9F), freerbuf(9F), getrbuf(9F)

       Writing Device Drivers

WARNINGS

       Memory allocated using kmem_alloc() is not paged. Available memory is therefore limited by the total physical memory on the system.  It	is
       also limited by the available kernel virtual address space, which is often the more restrictive constraint on large-memory configurations.

       Excessive  use  of  kernel  memory is likely to affect overall system performance. Overcommitment of kernel memory will cause the system to
       hang or panic.

       Misuse of the kernel memory allocator, such as writing past the end of a buffer, using a buffer after freeing it, freeing a  buffer  twice,
       or freeing a null or invalid pointer, will corrupt the kernel heap and may cause the system to corrupt data or panic.

       The  initial contents of memory allocated using kmem_alloc() are random garbage. This random garbage may include secure kernel data. There-
       fore, uninitialized kernel memory should be handled carefully. For example, never copyout(9F) a potentially uninitialized buffer.

NOTES

       kmem_alloc(0, flag) always returns NULL. kmem_free(NULL, 0) is legal.

SunOS 5.11							    16 Jan 2006 						    kmem_alloc(9F)