KMEM_ALLOC

Section: Linux Fast-STREAMS DDI/DKI (9)
Updated: 2008-10-31
Index Return to Main Contents

NAME

kmem_alloc - allocate kernel memory

SYNOPSIS

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

void *kmem_alloc(size_t size, int flag);

ARGUMENTS

size: the size of the contiguous region of kernel memory to allocate.
flag: whether to sleep or not.

INTERFACE

DDI/DKI.

DESCRIPTION

Requests that the number of bytes of kernel memory specified by the argument size be allocated with the options specified by flag and returned as a void * to the allocated memory. flag can be one of the following values:

KM_SLEEP: can wait and reschedule, success guaranteed.
KM_NOSLEEP: cannot wait or reschedule, may fail and return NULL.
KM_PHYSCONTIG: allocate contiguous physical memory
KM_CACHEALIGN: allocate the requested memory starting at a cache line boundary and padded out to a full cache line
KM_DMA: allocate the requested memory as suitable for worst case DMA.

USAGE

kmem_alloc() allocates pinned kernel memory which is a precious kernel resource. Allocation of large blocks of pinned kernel memory can impair system performance.

kmem_alloc() should not be used to allocated memory that will not later be freed: doing so can have an impact on memory allocation algorithm performance. Static allocation should be used in this case wherever possible.

kmem_alloc() should not be used to allocated fundamental system data structures. Fundamental system data structures should always be allocated using that data structure's specific allocation function. For example, a queue(9) structure should be allocated using allocq(9):


queue_t *q;
q = allocq();

instead of kmem_alloc():


queue_t *q;
q = kmem_alloc(sizeof(*q), KM_SLEEP);

This is because sizes of fundamental system data structures may change and yet binary compatibility of STREAMS drivers and modules can be maintained. Also, the implementation of a fundamental structure might be larger than the public declaration of that structure: that is, there are additional fields hidden from the system programmer. Portable STREAMS drivers and modules will not allocate fundamental system datastructures using kmem_alloc(), but will instead use the system-provided structure-specific allocator.

RETURN

kmem_alloc() returns a pointer to the allocated memory on success. On failure, kmem_alloc() returns a NULL pointer.

ERRORS

When kmem_alloc() fails to allocate the requested memory, it returns a NULL pointer. kmem_alloc() should only fail and return NULL if flag was set to KM_NOSLEEP; however, if size is zero (0), then kmem_alloc() will fail and return NULL regardless of the value of flag.

CONTEXT

kmem_alloc() can be called from any context with flag KM_NOSLEEP. kmem_alloc() can only be called from user context with flag KM_SLEEP.

MP-STREAMS

kmem_alloc() is MP-safe.

NOTICES

kmem_alloc() will not allocate memory extents larger than 131072 bytes. To obtain larger memory extents, use __get_free_pages(9).

kmem_alloc() may allocate a larger extent of memory than is requested with the size argument. The Linux kernel memory allocator kmalloc(9) allocates to the enclosing power of two size. Also, kmalloc(9) will not allocate less than 32 bytes. Portable STREAMS drivers and modules will not make assuptions about the excess memory allocated by kmem_alloc().

kmem_alloc() uses the Linux memory allocator, kmalloc(9) to allocate memory. The Linux memory allocator will size the memory extent to the enclosing power of two size greater than or equal to 32, and this memory extent will be aligned to the enclosing power of two (minimum 32 byte) alignment boundary. So, for example, if a size of 120 bytes is requested, 128 bytes will be allocated and the 128 bytes will be aligned to a 128-byte boundary. This also means that a request of a cacheline or larger will always be cacheline aligned. Portable STREAMS drivers and modules, however, will make no assumptions about the excess or the alignment of the memory returned by kmem_alloc(), except that the STREAMS driver or module is assured that the alignment of the returned memory will be suitable for holding any basic data type or structure.

kmem_alloc() uses kmalloc(9) allocates memory in power of two chunks between 32 bytes and 131072 bytes. kmalloc(9) allocations are physically contiguous memory. Portable STREAMS drivers and modules make no assumptions about the physical contiguousness of memory allocated with kmem_alloc().

kmem_alloc() allocated memory contains random contents; however, these contents may contain secure kernel information that should not be exposed to users. When allocating datastructures that will be passed to users using, for example, copyout(9), the memory should be set to known contents or allocated using kmem_zalloc(9) instead. (Secure functions should know better than to deallocate memory without wiping it clean.) Portable STREAMS drivers and modules will always initialize the contents of the memory returned by kmem_alloc().

IMPLEMENTATION

kmem_alloc() is implemented as a function that calls kmalloc(9) with flags GFP_KERNEL or GFP_ATOMIC depending on the value of flag.

BUGS

kmem_alloc() has no known bugs.

COMPATIBILITY

kmem_alloc() is source-level compatible with SVR 4.2 MP DDI/DKI, and systems based on SVR with the following portability considerations exceptions:

---: AIX®, MacOT®, OSF/1®, SUPER-UX® and UXP/V® do not document this function[1..5]. OSF/1® indicates that the MALLOC macro should be called instead[2]. HP-UX®, IRIX®, OSF/1®, Solaris®, UnixWare® and LiS document this function[2, 6..10].
: Portable STREAMS drivers and modules may use kmem_alloc() for kernel memory allocation.
---: Solaris®, IRIX®, UnixWare®, document that kmem_alloc() returns NULL when size is zero[7..9]. HP-UX® and LiS try to allocate 32 bytes if the size argument is set to 0[6, 10].
: Portable STREAMS drivers and modules will not pass a size of zero (0) in the size argument to kmem_alloc().
---: IRIX® adds the KM_PHYSCONTIG and KM_CACHEALIGN flags[7]. No other implementation mentions these.
: Portable STREAMS drivers and modules will only use the flags KM_SLEEP and KM_NOSLEEP when calling kmem_alloc().
---: Linux Fast-STREAMS adds the KM_DMA flag. This is for internal use by pullupmsg(9) and should not be used by portable programs.
: Portable STREAMS drivers and modules will only use the flags KM_SLEEP and KM_NOSLEEP when calling kmem_alloc().
---: kmem_alloc() is not bug for bug compatible with LiS.
: Under LiS, kmem_alloc() ignores the flag argument and allocates memory using lis_malloc() which always calls kmalloc(9) with a general fault protection class of GFP_ATOMIC. This means that kmem_alloc() can fail and return NULL even if flag is set to KM_SLEEP. Also, this means that when flag is set to KM_SLEEP, the calling process will neither wait nor reschedule. These are LiS bugs. Under LiS, kmem_alloc() returns a pointer to zero-sized allocated memory when size is zero. This is incorrect behaviour and is an LiS bug. LiS destroys memory alignment by inserting hidden memory allocation management pointers at the beginningo of the kmalloc(9)'ed extent. kmem_alloc() is implemented as a function call. LiS implements kmem_alloc() as a macro.
: Portable STREAMS drivers and modules will use Linux Fast-STREAMS in place of LiS.
---: Binary compatibility is not guaranteed.

See STREAMS(9) for additional compatibility information.

CONFORMANCE

SVR 4.2 MP DDI/DKI[11].

HISTORY

kmem_alloc() first appeared in SVR 3[12].

REFERENCES

[1]: AIX® 5L Version 5.1, AIX 5L Version 5.1 Documentation, 2001, (Boulder, Colorado), Internatonal Business Machines Corp., IBM. <http://publibn.boulder.ibm.com/>
[2]: Digital® UNIX (OSF/1.2), Digital UNIX Documentation Library, 2003, (Palo Alto, California), Digital Equipment Corporation, Hewlett-Packard Company. <http://www.true64unix.compaq.com/docs/>
[3]: Mac OS 9, Open Transport Reference, 2003, (Cupertino, California), Apple Computer, Inc., Apple. <http://developer.apple.com/macros/opentransport/>
[4]: SUPER-UX® Release 9.2, SUPER-UX Release 9.2 Documentation, 1999, NEC Corporation, NEC.
[5]: UXP/V® V10L10, UXP/V V10L10 Documentation, 1997, Fujitsu Limited, Fujitsu.
[6]: HP-UX® 11i v2, HP-UX 11i v2 Documentation, 2001, (Palo Alto, California), Hewlett-Packard Company, HP. <http://docs.hp.com/>
[7]: IRIX® 6.5.17, IRIX 6.5 Manual Pages, 2003, (Mountainview, California), Silicon Graphics, Inc., SGI Technical Publications. <http://techpubs.sgi.com/>
[8]: Solaris® 8, Solaris 8 Docmentation, 2001, (Santa Clara, California), Sun Microsystems, Inc., Sun. <http://docs.sun.com/>
[9]: UnixWare® 7.1.3, UnixWare 7.1.3 (OpenUnix 8) Documentation, 2002, (Lindon, Utah), Caldera International, Inc., Caldera. <http://uw713doc.sco.com/>
[10]: LIS 2.18, Linux STREAMS (LiS) 2.18.6 Source Code, Brian Bidulock, ed., OpenSS7 Corporation. <http://www.openss7.org/>
[11]: USL DDI/DKI, Device Driver Interface/Driver-Kernel Interface (DDI/DKI) Reference Manual for Intel Processors, 1992, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[12]: SVR 3, UNIX® System V Release 3 Programmer's Manual, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.

TRADEMARKS

OpenSS7tm: is a trademark of OpenSS7 Corporation.
Linux®: is a registered trademark of Linus Torvalds.
UNIX®: is a registered trademark of The Open Group.
Solaris®: is a registered trademark of Sun Microsystems.

Other trademarks are the property of their respective owners.

IDENTIFICATION

Linux Fast-STREAMS: Package streams version 0.9.2.4 released 2008-10-31.

Index

NAME
SYNOPSIS
ARGUMENTS
INTERFACE
DESCRIPTION
USAGE
RETURN
ERRORS
CONTEXT
MP-STREAMS
NOTICES
IMPLEMENTATION
SEE ALSO
BUGS
COMPATIBILITY
CONFORMANCE
HISTORY
REFERENCES
TRADEMARKS
IDENTIFICATION

This document was created by man2html, using the manual pages.
Time: 09:26:16 GMT, June 19, 2013

Description: Manual Page

Keywords: ss7 ss7/ip ss7 over ip ss7 mtp ss7 sccp ss7 tcap sigtran mtp sccp tcap openss7 acb56 linux telephony pstn linux telephony linux nebs linux compactpci