zbuflib.c

VXWORKS源代码

*
* The location of insertion is specified by <zbufSeg> and <offset>.  See
* the zbufLib manual page for more information on specifying
* a byte location within a zbuf.  In particular, insertion within
* a zbuf occurs before the byte location specified by <zbufSeg> and <offset>.
* Additionally, <zbufSeg> and <offset> must be NULL and 0,
* respectively, when inserting into an empty zbuf.
*
* VXWORKS AE PROTECTION DOMAINS
* Under VxWorks AE, you can call this function from within the kernel 
* protection domain only.  In addition, all arguments to this function can  
* reference only that data which is valid in the kernel protection domain. 
* Likewise, the returned value is valid in the protection domain only.
* This restriction does not apply under non-AE versions of VxWorks.  
*
* RETURNS:
* The zbuf segment ID of the first inserted segment,
* or NULL if the operation fails.
*/

ZBUF_SEG zbufInsertCopy
    (
    ZBUF_ID		zbufId,		/* zbuf into which data is copied */
    ZBUF_SEG		zbufSeg,	/* zbuf segment base for <offset> */
    int			offset,		/* relative byte offset */
    caddr_t		buf,		/* buffer from which data is copied */
    int			len		/* number of bytes to copy */
    )
    {
    return ((pZbufFunc->insertCopyRtn == NULL) ? NULL :
        (ZBUF_SEG) (pZbufFunc->insertCopyRtn) (zbufId, zbufSeg,
	offset, buf, len));
    }

/*******************************************************************************
*
* zbufExtractCopy - copy data from a zbuf to a buffer
*
* This routine copies <len> bytes of data from <zbufId> to the application
* buffer <buf>.
*
* The starting location of the copy is specified by <zbufSeg> and <offset>.
* See the zbufLib manual page for more information on
* specifying a byte location within a zbuf.  In particular, the first
* byte copied is the exact byte specified by <zbufSeg> and <offset>.
*
* The number of bytes to copy is given by <len>.  If this parameter
* is negative, or is larger than the number of bytes in the zbuf after the
* specified byte location, the rest of the zbuf is copied.
* The bytes copied may span more than one segment.
* 
* VXWORKS AE PROTECTION DOMAINS
* Under VxWorks AE, you can call this function from within the kernel 
* protection domain only.  In addition, all arguments to this function can  
* reference only that data which is valid in the kernel protection domain. 
* This restriction does not apply under non-AE versions of VxWorks.  
*
* RETURNS:
* The number of bytes copied from the zbuf to the buffer,
* or ERROR if the operation fails.
*/

int zbufExtractCopy
    (
    ZBUF_ID		zbufId,		/* zbuf from which data is copied */
    ZBUF_SEG		zbufSeg,	/* zbuf segment base for <offset> */
    int			offset,		/* relative byte offset */
    caddr_t		buf,		/* buffer into which data is copied */
    int			len		/* number of bytes to copy */
    )
    {
    return ((pZbufFunc->extractCopyRtn == NULL) ? ERROR :
        (pZbufFunc->extractCopyRtn) (zbufId, zbufSeg, offset, buf, len));
    }

/*******************************************************************************
*
* zbufCut - delete bytes from a zbuf
*
* This routine deletes <len> bytes from <zbufId> starting at the specified
* byte location.
*
* The starting location of deletion is specified by <zbufSeg> and <offset>.
* See the zbufLib manual page for more information on
* specifying a byte location within a zbuf.  In particular, the first
* byte deleted is the exact byte specified by <zbufSeg> and <offset>.
*
* The number of bytes to delete is given by <len>.  If this parameter
* is negative, or is larger than the number of bytes in the zbuf after the
* specified byte location, the rest of the zbuf is deleted.
* The bytes deleted may span more than one segment.
*
* If all the bytes in any one segment are deleted, then the segment is
* deleted, and the data buffer that it referenced will be freed if no
* other zbuf segments reference it.  No segment may survive with zero bytes
* referenced.
* 
* Deleting bytes out of the middle of a segment splits the segment
* into two.  The first segment contains the portion of the data buffer
* before the deleted bytes, while the other segment contains the end
* portion that remains after deleting <len> bytes.
*
* This routine returns the zbuf segment ID of the segment just
* after the deleted bytes.  In the case where bytes are cut off the end
* of a zbuf, a value of ZBUF_NONE is returned.
*
* VXWORKS AE PROTECTION DOMAINS
* Under VxWorks AE, you can call this function from within the kernel 
* protection domain only.  In addition, all arguments to this function can  
* reference only that data which is valid in the kernel protection domain. 
* Likewise, the returned value is valid in the protection domain only.
* This restriction does not apply under non-AE versions of VxWorks.  
*
* RETURNS:
* The zbuf segment ID of the segment following the deleted bytes,
* or NULL if the operation fails.
*/

ZBUF_SEG zbufCut
    (
    ZBUF_ID		zbufId,		/* zbuf from which bytes are cut */
    ZBUF_SEG		zbufSeg,	/* zbuf segment base for <offset> */
    int			offset,		/* relative byte offset */
    int			len		/* number of bytes to cut */
    )
    {
    return ((pZbufFunc->cutRtn == NULL) ? NULL :
	(ZBUF_SEG) (pZbufFunc->cutRtn) (zbufId, zbufSeg, offset, len));
    }

/*******************************************************************************
*
* zbufSplit - split a zbuf into two separate zbufs
*
* This routine splits <zbufId> into two separate zbufs at the specified
* byte location.  The first portion remains in <zbufId>, while the end
* portion is returned in a newly created zbuf.
*
* The location of the split is specified by <zbufSeg> and <offset>.  See
* the zbufLib manual page for more information on specifying
* a byte location within a zbuf.  In particular, after the split
* operation, the first byte of the returned zbuf is the exact byte
* specified by <zbufSeg> and <offset>.
*
* VXWORKS AE PROTECTION DOMAINS
* Under VxWorks AE, you can call this function from within the kernel 
* protection domain only.  In addition, all arguments to this function can  
* reference only that data which is valid in the kernel protection domain. 
* Likewise, the returned value is valid in the protection domain only.
* This restriction does not apply under non-AE versions of VxWorks.  
*
* RETURNS:
* The zbuf ID of a newly created zbuf containing the end portion of <zbufId>,
* or NULL if the operation fails.
*/

ZBUF_ID zbufSplit
    (
    ZBUF_ID		zbufId,		/* zbuf to split into two */
    ZBUF_SEG		zbufSeg,	/* zbuf segment base for <offset> */
    int			offset		/* relative byte offset */
    )
    {
    return ((pZbufFunc->splitRtn == NULL) ? NULL :
	(ZBUF_ID) (pZbufFunc->splitRtn) (zbufId, zbufSeg, offset));
    }

/*******************************************************************************
*
* zbufDup - duplicate a zbuf
*
* This routine duplicates <len> bytes of <zbufId> starting at the specified
* byte location, and returns the zbuf ID of the newly created duplicate zbuf. 
*
* The starting location of duplication is specified by <zbufSeg> and <offset>.
* See the zbufLib manual page for more information on
* specifying a byte location within a zbuf.  In particular, the first
* byte duplicated is the exact byte specified by <zbufSeg> and <offset>.
*
* The number of bytes to duplicate is given by <len>.  If this parameter
* is negative, or is larger than the number of bytes in the zbuf after the
* specified byte location, the rest of the zbuf is duplicated.
* 
* Duplication of zbuf data does not usually involve copying of the data.
* Instead, the zbuf segment pointer information is duplicated, while the data
* is not, which means that the data is shared among all zbuf segments
* that reference the data.  See the zbufLib manual
* page for more information on copying and sharing zbuf data.
*
* RETURNS:
* The zbuf ID of a newly created duplicate zbuf,
* or NULL if the operation fails.
*/

ZBUF_ID zbufDup
    (
    ZBUF_ID		zbufId,		/* zbuf to duplicate */
    ZBUF_SEG		zbufSeg,	/* zbuf segment base for <offset> */
    int			offset,		/* relative byte offset */
    int			len		/* number of bytes to duplicate */
    )
    {
    return ((pZbufFunc->dupRtn == NULL) ? NULL :
	(ZBUF_ID) (pZbufFunc->dupRtn) (zbufId, zbufSeg, offset, len));
    }

/*******************************************************************************
*
* zbufLength - determine the length in bytes of a zbuf
*
* This routine returns the number of bytes in the zbuf <zbufId>.
*
* VXWORKS AE PROTECTION DOMAINS
* Under VxWorks AE, you can call this function from within the kernel 
* protection domain only.  In addition, all arguments to this function can  
* reference only that data which is valid in the kernel protection domain. 
* This restriction does not apply under non-AE versions of VxWorks.  
*
* RETURNS:
* The number of bytes in the zbuf,
* or ERROR if the operation fails.
*/

int zbufLength
    (
    ZBUF_ID		zbufId		/* zbuf to determine length */
    )
    {
    return ((pZbufFunc->lengthRtn == NULL) ? ERROR :
	(pZbufFunc->lengthRtn) (zbufId));
    }

/*******************************************************************************
*
* zbufSegFind - find the zbuf segment containing a specified byte location
*
* This routine translates an address within a zbuf to its most local
* formulation.  zbufSegFind() locates the zbuf segment in <zbufId>
* that contains the byte location specified by <zbufSeg> and *<pOffset>,
* then returns that zbuf segment, and writes in *<pOffset> the new offset
* relative to the returned segment.
*
* If the <zbufSeg>, *<pOffset> pair specify a byte location past the end
* of the zbuf, or before the first byte in the zbuf, zbufSegFind()
* returns NULL.
*
* See the zbufLib manual page for a full discussion of addressing zbufs
* by segment and offset.
*
* VXWORKS AE PROTECTION DOMAINS
* Under VxWorks AE, you can call this function from within the kernel 
* protection domain only.  In addition, all arguments to this function can  
* reference only that data which is valid in the kernel protection domain. 
* Likewise, the returned value is valid in the protection domain only.
* This restriction does not apply under non-AE versions of VxWorks.  
*
* RETURNS:
* The zbuf segment ID of the segment containing the specified byte,
* or NULL if the operation fails.
*/

ZBUF_SEG zbufSegFind
    (
    ZBUF_ID		zbufId,		/* zbuf to examine */
    ZBUF_SEG		zbufSeg,	/* zbuf segment base for <pOffset> */
    int *		pOffset		/* relative byte offset */
    )
    {
    return ((pZbufFunc->segFindRtn == NULL) ? NULL :
	(ZBUF_SEG) (pZbufFunc->segFindRtn) (zbufId, zbufSeg, pOffset));
    }

/*******************************************************************************
*
* zbufSegNext - get the next segment in a zbuf
*
* This routine finds the zbuf segment in <zbufId> that is just after
* the zbuf segment <zbufSeg>.  If <zbufSeg> is NULL, the segment after
* the first segment in <zbufId> is returned.  If <zbufSeg> is the last
* segment in <zbufId>, NULL is returned.
*
* RETURNS:
* The zbuf segment ID of the segment after <zbufSeg>,
* or NULL if the operation fails.
*/

ZBUF_SEG zbufSegNext
    (
    ZBUF_ID		zbufId,		/* zbuf to examine */
    ZBUF_SEG		zbufSeg		/* segment to get next segment */
    )
    {
    return ((pZbufFunc->segNextRtn == NULL) ? NULL :
        (ZBUF_SEG) (pZbufFunc->segNextRtn) (zbufId, zbufSeg));
    }

/*******************************************************************************
*
* zbufSegPrev - get the previous segment in a zbuf
*
* This routine finds the zbuf segment in <zbufId> that is just before the zbuf 
* segment <zbufSeg>. If <zbufSeg> is NULL, or is the first segment in <zbufId>,
* NULL is returned.
*
* VXWORKS AE PROTECTION DOMAINS
* Under VxWorks AE, you can call this function from within the kernel 
* protection domain only.  In addition, all arguments to this function can  
* reference only that data which is valid in the kernel protection domain. 
* Likewise, the returned value is valid in the protection domain only.
* This restriction does not apply under non-AE versions of VxWorks.  
*
* RETURNS:
* The zbuf segment ID of the segment before <zbufSeg>, or NULL if the 
* operation fails.
*/

ZBUF_SEG zbufSegPrev
    (
    ZBUF_ID		zbufId,		/* zbuf to examine */
    ZBUF_SEG		zbufSeg		/* segment to get previous segment */
    )
    {
    return ((pZbufFunc->segPrevRtn == NULL) ? NULL :
        (ZBUF_SEG) (pZbufFunc->segPrevRtn) (zbufId, zbufSeg));
    }

/*******************************************************************************
*
* zbufSegData - determine the location of data in a zbuf segment
*
* This routine returns the location of the first byte of data in the zbuf
* segment <zbufSeg>.  If <zbufSeg> is NULL, the location of data in the
* first segment in <zbufId> is returned.
* 
* VXWORKS AE PROTECTION DOMAINS
* Under VxWorks AE, you can call this function from within the kernel 
* protection domain only.  In addition, all arguments to this function can  
* reference only that data which is valid in the kernel protection domain. 
* Likewise, the returned value is valid in the protection domain only.
* This restriction does not apply under non-AE versions of VxWorks.  
*
* RETURNS:
* A pointer to the first byte of data in the specified zbuf segment,
* or NULL if the operation fails.
*
*/

caddr_t zbufSegData
    (
    ZBUF_ID		zbufId,		/* zbuf to examine */
    ZBUF_SEG		zbufSeg		/* segment to get pointer to data */
    )
    {
    return ((pZbufFunc->segDataRtn == NULL) ? NULL :
	(caddr_t) (pZbufFunc->segDataRtn) (zbufId, zbufSeg));
    }

/*******************************************************************************
*
* zbufSegLength - determine the length of a zbuf segment
*
* This routine returns the number of bytes in the zbuf segment <zbufSeg>.
* If <zbufSeg> is NULL, the length of the first segment in <zbufId> is
* returned.
*
* VXWORKS AE PROTECTION DOMAINS
* Under VxWorks AE, you can call this function from within the kernel 
* protection domain only.  In addition, all arguments to this function can  
* reference only that data which is valid in the kernel protection domain. 
* This restriction does not apply under non-AE versions of VxWorks.  
*
* RETURNS:
* The number of bytes in the specified zbuf segment,
* or ERROR if the operation fails.
*/

int zbufSegLength
    (
    ZBUF_ID		zbufId,		/* zbuf to examine */
    ZBUF_SEG		zbufSeg		/* segment to determine length of */
    )
    {
    return ((pZbufFunc->segLengthRtn == NULL) ? ERROR :
	(pZbufFunc->segLengthRtn) (zbufId, zbufSeg));
    }