zbuflib.c

vxworks的完整的源代码

/* zbufLib.c - zbuf interface library */

/* Copyright 1984 - 2001 Wind River Systems, Inc. */
#include "copyright_wrs.h"

/*
modification history
--------------------
01h,07may02,kbw  man page edits
01g,15oct01,rae  merge from truestack ver 01g, base 01f (AE / 5_X)
01f,26jan95,jdi  format tweak.
01e,24jan95,rhp  revisions based on jdi feedback
01d,16jan95,rhp  fix SEE ALSO subroutine ref format
01c,15nov94,dzb  doc tweaks.
01b,09nov94,rhp  library man page added, subroutine man pages edited.
01a,08nov94,dzb  written.
*/

/*
DESCRIPTION
This library contains routines to create, build, manipulate, and
delete zbufs.  Zbufs, also known as "zero copy buffers," are a data
abstraction designed to allow software modules to share buffers
without unnecessarily copying data.

To support the data abstraction, the subroutines in this library hide
the implementation details of zbufs.  This also maintains the
library's independence from any particular implementation mechanism,
thus permitting the zbuf interface to be used with other buffering schemes.

Zbufs have three essential properties.  First, a zbuf holds a
sequence of bytes.  Second, these bytes are organized into one or more
segments of contiguous data, although the successive segments
themselves are not usually contiguous.  Third, the data within a
segment may be shared with other segments; that is, the data may be in use
by more than one zbuf at a time.

ZBUF TYPES
The following data types are used in managing zbufs:
.iP ZBUF_ID 16 3
An arbitrary (but unique) integer that identifies a particular zbuf.
.iP ZBUF_SEG
An arbitrary (but unique within a single zbuf) integer that identifies
a segment within a zbuf.
.LP

ADDRESSING BYTES IN ZBUFS
The bytes in a zbuf are addressed by the combination <zbufSeg>,
<offset>.  The <offset> may be positive or negative, and is simply the
number of bytes from the beginning of the segment <zbufSeg>.

A <zbufSeg> can be specified as NULL, to identify the segment at the
beginning of a zbuf.  If <zbufseg> is NULL, <offset> is the
absolute offset to any byte in the zbuf.  However, it is more
efficient to identify a zbuf byte location relative to the <zbufSeg>
that contains it; see zbufSegFind() to convert any <zbufSeg>, <offset>
pair to the most efficient equivalent.

Negative <offset> values always refer to bytes before the
corresponding <zbufSeg>, and are not usually the most efficient
address formulation (though using them may save your
program other work in some cases).

The following special <offset> values, defined as constants,
allow you to specify the very beginning or the very end of an entire zbuf,
regardless of the <zbufSeg> value:
.iP ZBUF_BEGIN 16 3
The beginning of the entire zbuf.
.iP ZBUF_END
The end of the entire zbuf (useful for appending to a zbuf; see below).
.LP

INSERTION AND LIMITS ON OFFSETS
An <offset> is not valid if it points outside the zbuf.  Thus, to
address data currently within an N-byte zbuf, the valid offsets
relative to the first segment are 0 through N-1.

Insertion routines are a special case: they obey the usual
convention, but they use <offset> to specify where the new data
begins after the insertion is complete.  Therefore, the original
zbuf data is always inserted just before the byte
location addressed by the <offset> value.  The value of this
convention is that it permits inserting (or concatenating) data either
before or after the existing data.  To insert before all the data
currently in a zbuf segment, use 0 as <offset>.  To insert after all
the data in an N-byte segment, use N as <offset>. An <offset> of N-1
inserts the data just before the last byte in an N-byte segment.

An <offset> of 0 is always a valid insertion point; for an empty zbuf,
0 is the only valid <offset> (and NULL the only valid <zbufSeg>).

SHARING DATA
The routines in this library avoid copying segment data whenever
possible.  Thus, by passing and manipulating ZBUF_IDs rather than
copying data, multiple programs can communicate with greater
efficiency.  However, each program must be aware of data sharing:
changes to the data in a zbuf segment are visible to all zbuf segments
that reference the data.

To alter your own program's view of zbuf data without affecting other
programs, first use zbufDup() to make a new zbuf; then you can use an
insertion or deletion routine, such as zbufInsertBuf(), to add a
segment that only your program sees (until you pass a zbuf containing
it to another program).  It is safest to do all direct data
manipulation in a private buffer, before enrolling it in a zbuf: in
principle, you should regard all zbuf segment data as shared.

Once a data buffer is enrolled in a zbuf segment, the zbuf library is
responsible for noticing when the buffer is no longer in use by any
program, and freeing it.  To support this, zbufInsertBuf() requires
that you specify a callback to a free routine each time you build a
zbuf segment around an existing buffer.  You can use this callback to notify
your application when a data buffer is no longer in use.

VXWORKS AE PROTECTION DOMAINS
Under VxWorks AE, this feature is restricted to the kernel protection 
domain.  This restriction does not apply under non-AE versions of VxWorks.  

To use this feature, include the following component:
INCLUDE_ZBUF_SOCK

SEE ALSO
zbufSockLib

INTERNAL

Extensions:

zbufJoin (zbufId, zbufSeg) - coalesce two adjacent segment fragments
    This routine combines two or more contiguous zbuf segments into a single
    zbuf segment.  Such an operation is only feasible for joining segments
    that have the same freeRtn and freeArg, and that follow eachother in
    the zbuf.  This could be useful for coalescing zbuf segments fragmented
    by split operations.

zbufOwn (zbufId, zbufSeg, offset, len) - own a local copy of zbuf data
    This routine makes a local copy of a portion of a zbuf.  This
    is useful if you want to change the actual data in a zbuf, but want to
    make sure that you are not corrupting another zbuf that shares the
    same data.  If you are the only zbuf segment using a particular buffer,
    this routine does nothing.  If other zbufs reference the same data, this
    routine inserts a copy of the requested data, then deletes reference
    to the original data.
*/

/* includes */

#include "vxWorks.h"
#include "zbufLib.h"
#include "stdlib.h"
#include "memPartLib.h"

/* locals */

/*
 * N.B.
 * As other back-ends to zbuf are ever developed, and need to be run
 * concurrently with existing back-ends, the zbufFunc table needs to have
 * the back-end resident function table pointer in the ZBUF_ID.  This will
 * require a modification to the current method of simply passing through
 * the ZBUF_ID to the back-end.  Instead, the ZBUF_ID will have to point
 * to a structure, which would contain the back-end function table pointer
 * and a back-end-specific XX_ID pointer.
 */

LOCAL ZBUF_FUNC		zbufFuncNull =	/* null funcs for unconnected zbufs */
    {
    NULL,				/* zbufCreate()		*/
    NULL,				/* zbufDelete()		*/
    NULL,				/* zbufInsert()		*/
    NULL,				/* zbufInsertBuf()	*/
    NULL,				/* zbufInsertCopy()	*/
    NULL,				/* zbufExtractCopy()	*/
    NULL,				/* zbufCut()		*/
    NULL,				/* zbufSplit()		*/
    NULL,				/* zbufDup()		*/
    NULL,				/* zbufLength()		*/
    NULL,				/* zbufSegFind()	*/
    NULL,				/* zbufSegNext()	*/
    NULL,				/* zbufSegPrev()	*/
    NULL,				/* zbufSegData()	*/
    NULL				/* zbufSegLength()	*/
    };

LOCAL ZBUF_FUNC *	pZbufFunc = &zbufFuncNull;

/*******************************************************************************
*
* zbufLibInit - initialize the zbuf interface library
*
* This routine initializes the zbuf interface facility.  It
* must be called before any zbuf routines are used.  This routine is
* typically called during the initialization of a VxWorks facility which
* uses or extends the zbuf interface, although this is not a requirement.
* The zbuf library may be used on its own, provided an appropriate back-end
* buffer mechanism is available, and is specified by <libInitRtn>.
*
* RETURNS:
* OK, or ERROR if the zbuf interface cannot be initialized.
*
* NOMANUAL
*/

STATUS zbufLibInit
    (
    FUNCPTR		libInitRtn	/* back-end buffer mechanism init rtn */
    )
    {
    ZBUF_FUNC *		pZbufFuncTemp;	/* temp return of back-end func table */

    /* call the back-end initialization routine - watch for NULL func ptr */

    if ((libInitRtn == NULL) || ((pZbufFuncTemp =
	(ZBUF_FUNC *) (libInitRtn) ()) == NULL))
	return (ERROR);

    pZbufFunc = pZbufFuncTemp;			/* connect back-end func tbl */
    return (OK);
    }

#if	FALSE		/* Pool routines not in service yet */

/*******************************************************************************
*
* zbufSegPoolCreate - create an empty zbuf segment pool
*
* This routine creates a zbuf segment pool.  It remains empty (that is, does
* not contain any free segments) until segments are added by calling
* zbufSegPoolAdd().  Operations performed on zbuf segments pools require
* a zbuf segment pool ID, which is returned by this routine.
*
* RETURNS:
* A zbuf segment pool ID, or NULL if an ID cannot be created.
*
* SEE ALSO: zbufSegPoolDelete(), zbufSegPoolAdd()
*
* NOMANUAL
*/

ZBUF_POOL_ID zbufSegPoolCreate (void)
    {
    ZBUF_POOL_ID	zbufPoolId;		/* new ID */
    
    if ((zbufPoolId = (ZBUF_POOL_ID) KHEAP_ALLOC(sizeof(struct zbufPoolId))) ==
	NULL)
	return (NULL);				/* malloc pool ID struct */

    /* create mutex sem for guarding access to zbuf segment pool */

    if ((zbufPoolId->poolSem = semMCreate ((SEM_Q_PRIORITY |
	SEM_INVERSION_SAFE | SEM_DELETE_SAFE))) == ERROR)
	{
	KHEAP_FREE(zbufPoolId);			/* free resources */
	return (NULL);
	}

    /* create binary sem for waiting for free segments to come into pool */

    if ((zbufPoolId->waitSem = semBCreate (SEM_Q_PRIORITY, SEM_EMPTY)) == ERROR)
	{
        semDelete (zbufPoolId->poolSem);	/* free resources */
	KHEAP_FREE(zbufPoolId);
	return (NULL);
	}

    zbufPoolId->use = 0;			/* no loaned buffers yet */
    zbufPoolId->blockHead = NULL;		/* no blocks/segs yet */

    return (zbufPoolId);
    }

/*******************************************************************************
*
* zbufSegPoolDelete - delete a zbuf segment pool and free associated segments
*
* This routine will free any segments associated with <zbufPoolId>,
* then delete the zbuf segment pool ID itself.  To do this, all segments
* must be in the pool (that is, no segments may currently be part of a zbuf).
* <zbufPoolId> must not be used after this routine executes successfully.
*
* Associated segments will be returned to the system memory pool if they
* were allocated with zbufSegPoolAdd().  No action will be taken upon
* user segments added to the segment pool by specifying the segment block
* start address. These segments should be considered free after this
* routine executes successfully.
* 
* RETURNS:
* OK, or ERROR if the zbuf segment pool has outstanding segments.
*
* SEE ALSO: zbufSegPoolCreate(), zbufSegPoolAdd()
*
* NOMANUAL
*/

STATUS zbufSegPoolDelete
    (
    ZBUF_POOL_ID	zbufPoolId	/* zbuf segment pool to delete */
    )
    {
    ZBUF_BLOCK_ID	zbufBlock;		/* ptr to block headers */
    ZBUF_BLOCK_ID	zbufBlockTemp;		/* temp storage of block hdr */

    /* obtain exclusive access to zbuf segment pool structures */

    if ((semTake (zbufPoolId->poolSem, WAIT_FOREVER)) == ERROR)
	return (ERROR);

    if (zbufPoolId->use != 0)			/* any segments in use ? */
	{
	semGive (zbufPoolId->poolSem);		/* give up access */
	return (ERROR);				/* cannot feee if in use */
	}

    /* go through list of block headers, freein all alloc'ed mem */

    for (zbufBlock = zbufPoolId->blockHead; zbufBlock != NULL;)
	{
	zbufBlockTemp = zbufBlock->blockNext;	
	KHEAP_FREE(zbufBlock);			/* free each hdr & memory */
        zbufBlock = zbufBlockTemp;		/* bump to next block hdr */
        }

    semDelete (zbufPoolId->waitSem);		/* free wait binary sem */
    semDelete (zbufPoolId->poolSem);		/* free pool mutex sem */

    KHEAP_FREE(zbufPoolId);			/* free actual pool ID struct */

    return (OK);
    }

/*******************************************************************************
*
* zbufSegPoolAdd - add a block of zbuf segments to a zbuf segment pool
*
* This routine adds a block of zbuf segments to <zbufPoolId>.  This routine
* may be called multiple times to add segment blocks of different sizes and
* numbers.
*
* The segment size <segSise> will be rounded up to the memory allignment
* requirements of the target architecture.  The minimum size of a
* segment is the size of a void pointer.
*
* If system memory is to be used for the segment allocation, set <blockStart>
* to NULL, in which case <blockLength> parameter will be ignored.
* Otherwise, a block of memory to be used may be specified by <blockStart> and
* <blockLen>.  If a segment block is specified with <blockStart>, the
* <segNum> parameter is ignored.  Instead, the number of alligned segments
* that can be obtained from <memLength> are added to the pool.
* 
* If a zbuf segment pool is deleted with zbufSegPoolDelete(), any allocated
* segment blocks will be returned to the system memory pool.  Specific memory
* blocks obtained through <blockStart> should be considered free after
* zbufSegPoolDelete() executes successfully, but the user will not be
* given any further indication of the memory being released from the pool.
* 
* RETURNS:
* OK, or ERROR if the zbuf segment block cannot be added to the pool.
*
* SEE ALSO: zbufSegPoolDelete()
*
* NOMANUAL
*/

STATUS zbufSegPoolAdd
    (
    ZBUF_POOL_ID	zbufPoolId,	/* pool to add zbuf segments to */
    int			segSize,	/* size of new segments */
    int			segNum,		/* number of new segs (system memory) */
    caddr_t		blockStart,	/* start of seg block (user memory) */
    int			blockLen	/* length of seg block (user memory) */
    )
    {
    ZBUF_BLOCK_ID	zbufBlockNew;		/* new block header */
    ZBUF_BLOCK_ID 	zbufBlock = NULL;	/* location to insert new hdr */
    STATUS		status = ERROR;		/* return value */
    int			ix;			/* counter for block init */

    /* obtain exclusive access to zbuf segment pool structures */

    if ((semTake (zbufPoolId->poolSem, WAIT_FOREVER)) == ERROR)
	return (ERROR);

    /* adjust segSize for mem allign - must be at least void * (see below) */

    segSize = min (MEM_ROUND_UP(segSize), sizeof (void *));

    if (blockStart == NULL)			/* if allocating from system */
	{