Links

GitHub

Open HUB

Quick Links

Download

STREAMS

SIGTRAN

SS7

Hardware

SCTP

Man Pages

Applications

SS7 Stack

ISDN Stack

SIGTRAN Stack

VoIP Stack

MG Stack

SS7/ISDN Devices

IP Transport

Embedded Systems

OS

Documentation

FAQ

SIGTRAN

Design

Conformance

Performance

References

Man Pages

Manuals

Papers

Home

Overview

Status

Documentation

Resources

About

News

Manpage of ESBALLOC

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


ESBALLOC

Section: The OpenSS7 Project DDI/DKI (9)
Updated: Sat, 01 Nov 2014 12:16:40 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).

SEE ALSO

freeb(9), freemsg(9), bufcall(9), and esbbcall(9).

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 Sat, 01 Nov 2014 12:16:40 GMT.

Copyright©1997-2008OpenSS7 Corp.
All Rights Reserved.
(See roff source for permission notice.)



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: 12:16:40 GMT, November 01, 2014
Last modified: Mon, 28 Apr 2008 12:53:49 GMT  
Copyright © 2014 OpenSS7 Corporation All Rights Reserved.