Manpage of ESBALLOC

ESBALLOC

Section: The OpenSS7 Project DDI/DKI (9)
Updated: Sun, 26 May 2013 09:14:07 GMT
Index Return to Main Contents

NAME

esballoc - allocate a STREAMS message and data block with a caller supplied data buffer

SYNOPSIS

#include <sys/stream.h>

mblk_t *esballoc(unsigned char *base, int size,, int priority, frtn_t *freeinfo);

ARGUMENTS

base: the base of the user supplied message buffer.
size: the size of the user supplied message buffer.
priority: the priority of the request.
freeinfo: a pointer to a free routine description structure.

INTERFACE

STREAMS.

DESCRIPTION

esballoc() is used where the STREAMS driver needs control over the location, allocation and deallocation of data buffers. This may be because the data buffers are subject to some physical contraints (e.g. must be allocated in DMA-able memory, or must exist in dual-ported RAM or in a descriptor ring). This may also be because some other mechanism outside of STREAMS has already allocated and passed the data buffer to a STREAMS driver.

Where it is not necessary that the caller provide the data buffer, allocb(9) is more appropriate.

esballoc() allocates a message block and a data block using the caller supplied data buffer at base of the specified size and priority.

The priority can be one of the following values:

BPRI_LO: The caller requests a low priority message buffer.
BPRI_MED: The caller requests a medium priority message buffer.
BPRI_HI: The caller requests a high priority message buffer.
BPRI_WAITOK: The caller requests a low priority message buffer and can block.

If esballoc() is called with a priority other than BPRI_LO, BPRI_MED, BPRI_HI or BPRI_WAITOK, the request will be treated as BPRI_LO.

The priority argument is ignored by SVR 4[1] and later implementations.

The data buffer of length size and with the necessary physical memory type has already been allocated by the caller and is pointed to by the argument base. In addition, esballoc() accepts a pointer to a free_rtn structure that contains the following elements:

void (*free_func)(char *): A function pointer free_func to a function returning void and taking a single character pointer argument. This function should perform whatever actions are necessary to free the buffer pointed to by base in the call to esballoc().
char *free_arg: A character pointer argument free_arg that will be passed to a call to free_func when the message block returned by esballoc() is freed with freeb(9) or freemsg(9).

The allocated message block will have a data block type of M_DATA(9).

USAGE

Priority BPRI_WAITOK is added for OSF/1®[2] compatibility and should not be used by portable STREAMS drivers or modules.

Portable STREAMS drivers and modules should not rely on any setting of priority and should assume that the implementation ignores the priority argument.

RETURN

Upon success, esballoc() returns a pointer to the allocated message block.

Upon failure, esballoc() returns a NULL message pointer.

ERRORS

When esballoc() fails to allocate a message or data block, it returns NULL. Failure to allocate a message block will typically be followed by a call to esbbcall(9).

esballoc() will always fail to allocate a message block when the number of outstanding combined message data blocks allocated by the system exceeds the system control sysctl_str_nstrmsgs. esballoc() will also fail if size is greater than system control sysctl_str_strmsgsz, the maximum STREAMS message size.

CONTEXT

esballoc() can be called from any context, including user context, module procedures, callouts, callbacks, soft interrupts (tasklets and bottom halves), and interrupt service routines. The priority BPRI_WAITOK must only be used from a blocking context.

MP-STREAMS

esballoc() is MP-safe. The caller has exclusive access to the returned message.

NOTICES

Many post-SVR 4.2[3] compliant STREAMS implementations ignore the priority argument to esballoc(). The message block priority was an SVR 3[4] concept which was found not to be useful, primarily due to priority inversion. For a history of the priority mechanism and a discussion as to why the mechanism was abandoned in SVR 4.2[3], see ``The Magic Garden'' section 7.2.2[5].

Linux Fast-STREAMS keeps two stores for combined message data blocks (mdbblocks): a per-CPU free block list that is maintained during the runqueues(9) pass to hold freed message blocks (but freed to the memory cache at the end of the pass), and an mdbblock memory cache.

In consideration of priority, esballoc() uses the following allocation differences based on the value of priority:

BPRI_LO: The message block will be allocated from the STREAMS mdbblock memory cache. kmem_cache_alloc(9) will not be permitted to grow the mdbblock memory cache to meet the request. When speed is not critical and a lower degree of immediate success is acceptable, use BPRI_LO.
BPRI_MED: The message block will be allocated from the STREAMS mdbblock memory cache. kmem_cache_alloc(9) will be permitted to grow the mdbblock memory cache as necessary to allocate the block. Where speed is not so critical, but a higher probability of immediate success is needed, use BPRI_MED.
BPRI_HI: The message block will be allocated from the per-CPU STREAMS scheduler fast free chain, or if there is no message block in the fast free chain, it will be allocated from the mdbblock memory cache. kmem_cache_alloc(9) will be permitted to grow the mdbblock memory cache as necessary to allocate the block. Where speed is critical, and a high degree of immediate success is also needed, use BPRI_HI. When esballoc(9) is called immediately following freeb(9), use BPRI_HI to obtain the same block that was freed.
BPRI_WAITOK: The buffer allocation will be treated as BPRI_LO, but the caller will block waiting to obtain a buffer.

In this way, the priority argument determines the delay in satisfying the request rather than the ultimate probability of success, permitting low latency tasks to specify BPRI_HI and high-latency tasks to specify BPRI_LO.

esballoc() presents challenges when used from within Linux kernel modules. Particularly when the free_func function pointer references a function which is resident only within the kernel module. Care must be taken that the kernel module containing the free_func does not get unloaded from the system before all message blocks referencing free_func are freed.

Under Linux 2.4 kernels, and kernels that do not provide the module_text_address() symbol, module reference counting is the caller's responsibility and Linux Fast-STREAMS provides no automatic facility for this purpose. If a kernel module contains the free_func that is passed to esballoc(), the caller should increment the kernel module use count with MOD_INC_USE_COUNT prior to the allocation, and decrement the module use count with MOD_DEC_USE_COUNT within the function referenced by free_func. See ``EXAMPLES'' below.

Under Linux 2.6 kernels, and kernels that provide the module_text_address() symbol, Linux Fast-STREAMS will perform the module reference counting automatically.

EXAMPLES

The following examples shows how a data buffer suitable for use by Direct Memory Access is allocated:


  1  #ifndef MOD_INC_USE_COUNT
  2  #define MOD_INC_USE_COUNT do { } while (0)
  3  #define MOD_DEC_USE_COUNT do { } while (0)
  4  #endif
  5  
  6  void
  7  xxx_free_func(char *buf)
  8  {
  9      kfree(buf);
 10      MOD_DEC_USE_COUNT;
 11  }
 12  
 13  mblk_t *
 14  xxx_alloc_dma_buf(size_t bufsize)
 15  {
 16      unsigned char *buf;
 17  
 18      MOD_INC_USE_COUNT;
 19      if ((buf = kmalloc(bufsize,
 20                         GFP_ATOMIC | GFP_DMA))) {
 21          mblk_t *mp;
 22          frtn_t freertn = {
 23              free_func:&xxx_free_func,
 24              free_arg:(char *) buf,
 25          };
 26  
 27          if (!(mp = esballoc(buf, bufsize,
 28                              BPRI_MED, &freertn)))
 29              xxx_free_func(buf);
 30          return (mp);
 31      }
 32      MOD_DEC_USE_COUNT;
 33      return (NULL);
 34  }

The example, above, also shows the technique for keeping the current kernel module from unloading before the free function is called for all outstanding message blocks that reference the free function. See ``NOTICES'', above. MOD_INC_USE_COUNT and MOD_DEC_USE_COUNT in the example code is only necessary for Linux 2.4 kernels and can be defined as shown for Linux 2.6 kernels (where reference counting is performed automatically).

BUGS

esballoc() has no known bugs.

COMPATIBILITY

esballoc() is compatible with SVR 4.2 MP DDI/DKI[6], and implementations based on SVR 4, with the following portability considerations:

---: esballoc() uses the priority mechanism described above under ``NOTICES'', above. SVR 4.2 MP DDI/DKI, AIX®[7], Solaris®[8] and LiS[9] ignore the priority argument as also described above under ``NOTICES''. Portable STREAMS drivers and modules will not rely upon the response of esballoc() to any given value of the priority argument.
---: esballoc() will return NULL only if the allocation fails. Under LiS, esballoc() will return NULL if base or freeinfo is NULL. esballoc() will panic when base or freeinfo are NULL. Under LiS, the same conditions will return NULL. Portable STREAMS drivers and modules will not pass invalid or NULL arguments to esballoc().
---: esballoc() accepts the priority BPRI_WAITOK, which is OSF/1®-specific[2] and non-portable. BPRI_WAITOK will block the calling thread if a message block is not immediately available, and is only intended to be called from a blocking context (e.g. from the qi_qopen(9) and qi_qclose(9) procedures). Portable STREAMS drivers and modules will only use the priority values of BPRI_LO, BPRI_MED and BPRI_HI.
---: Binary compatibility is not guaranteed.

See STREAMS(9) for additional compatibility information.

CONFORMANCE

SVR 4.2 MP DDI/DKI[6].

HISTORY

esballoc() appears as part of SVR 4.0 STREAMS [1].

esballoc() first appeared in SVR 3[10].

REFERENCES

[1]: SVR 4, UNIX® System V Release 4 STREAMS Programmer's Guide, 1990, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[2]: Digital® UNIX (OSF/1.2), Digital UNIX: Network Programmers Guide, 1996, (Palo Alto, California), Digital Equipment Corporation, Hewlett-Packard Company. <http://www.true64unix.compaq.com/docs/>
[3]: SVR 4.2, UNIX® System V Release 4.2 Programmer's Manual, 1992, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[4]: SVR 3, UNIX® System V Release 3 Programmer's Manual, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[5]: Magic Garden, The Magic Garden Explained: The Internals of UNIX® System V Release 4 / An Open Systems Design, 1994, (Australia), B. Goodheart, J. Cox, Prentice Hall. [ISBN 0-13-098138-9] Section 7.2.2.
[6]: 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.
[7]: AIX® 5L Version 5.1, AIX STREAMS Programmers Guide, 2001, (Boulder, Colorado), Internatonal Business Machines Corp., IBM. <http://publibn.boulder.ibm.com/>
[8]: Solaris® 8, STREAMS Programming Guide, August 1999, (Palo Alto, California), Sun Microsystems, Inc., Sun. [Part No: 805-7478-05] <http://docs-pdf.sun.com/>
[9]: LIS 2.18, Linux STREAMS (LiS) 2.18.6 Source Code, Brian Bidulock, ed., OpenSS7 Corporation. <http://www.openss7.org/>
[10]: SVR 3, UNIX® System V Release 3 STREAMS Programmer's Guide, (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

The OpenSS7 Project: Package OpenSS7 version 0.9.2 released Sun, 26 May 2013 09:14:07 GMT.

Index

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

This document was created by man2html, using the manual pages.
Time: 09:14:07 GMT, May 26, 2013