TABLE OF CONTENTS

netbuff.library
netbuff.library/AllocSegments()
netbuff.library/CompactNetBuff()
netbuff.library/CopyFromNetBuff()
netbuff.library/CopyNetBuff()
netbuff.library/CopyToNetBuff()
netbuff.library/FreeSegments()
netbuff.library/IntAllocSegments()
netbuff.library/IntFreeSegments()
netbuff.library/IsContiguous()
netbuff.library/NetBuffAppend()
netbuff.library/PrependNetBuff()
netbuff.library/ReadyNetBuff()
netbuff.library/ReclaimSegments()
netbuff.library/SplitNetBuff()
netbuff.library/TrimNetBuff()
netbuff.library                                               netbuff.library

	Netbuff.library maintains the free pool of NetBuffSegments for
	use by the various network modules. It also contains several
	utility functions for dealing with NetBuffs as a data
	structure for "holding" network packet data as well as
	allocators and deallocators for NetBuffSegments.

	The intent is for all of the network modules to use a common
	pool of buffers so as to reduce the memory requirements of the
	network software, and for the network modules to be able to
	pass network data (packets) with minimal copying.

   STRUCTURES
	A NetBuff is a data structure representing a logical array of
	of bytes.

	    struct NetBuff
	        {
	        struct MinList List;
	        ULONG Count;
	        };

	    List
	        List of NetBuffSegments.

	    Count
	        The number of bytes of data the NetBuff is said to
	        contain.


	A NetBuffSegment is a data structure used to store and keep
	track of all or part of the data in a NetBuff.

	    struct NetBuffSegment
	        {
	        struct MinNode Node;
	        ULONG PhysicalSize;
	        ULONG DataOffset;
	        ULONG DataCount;
	        UBYTE *Buffer;
	        };

	    Node
	        Node structure linking the NetBuffSegments together.

	    PhysicalSize
	        The size of the data area that Buffer points to. If
	        this field is zero, the actual size of the data area
	        unknown and it is managed (allocated and freed) by
	        some other entity. Only 'Count' bytes starting at
	        '(Buffer+Offset)' are known to be valid.

	    DataOffset
	        Offset into the Buffer where the data starts.

	    DataCount
	        Number of data bytes that this NetBuffSegment
	        contains.

	    Buffer
	        Pointer to the start of the data area for this
	        NetBuffSegment.

   PHYSICALSIZE ZERO SEGMENTS
	Any software making use of NetBuffs must correctly handle
	NetBuffs with PhysicalSize zero segments. The general rules to
	follow are as follows:

	+   "Send" NetBuffs, those NetBuffs where the data is created
	    and passed to a lower network layer, are returned to the
	    creator with the data intact. This class of NetBuffs may
	    have segments of PhysicalSize zero.

	+   "Receive" NetBuffs, those NetBuffs where the data is
	    created and passed to a higher network layer, are not
	    returned to the creator. This class of NetBuffs may not
	    have segments of PhysicalSize zero.

	+   Lower network layers will eventually return the actual
	    NetBuff structure (pointer) to the layer that created the
	    data.

	+   NetBuffs returned to higher layers from lower layers may
	    have the "physical" layout of the data changed. The layout
	    of the "logical" data will not have changed.

	+   Track NetBuff structures to know when it is safe to reuse/
	    deallocate storage for PhysicalSize zero segments.

	In to above, higher and lower network layers refers to the
	usual diagram of the OSI network layering model; where the
	application layer is at the top of the diagram and the
	physical layer is at the bottom.

	This model for handling PhysicalSize zero segments also has
	obvious advantages in situations where time-outs and
	retransmittions occure.

   CREDITS
	Raymond S. Brand   rsbx@cbmvax.commodore.com   (215) 431-9100
	Martin Hunt      martin@cbmvax.commodore.com   (215) 431-9100
	Perry Kivolowitz           ASDG Incorporated   (608) 273-6585

netbuff.library/AllocSegments()               netbuff.library/AllocSegments()

   NAME
	AllocSegments -- Get a list of NetBuffSegments.

   SYNOPSIS
	AllocSegments( Count, Segment_List )
	               D0     A0

	void AllocSegments( ULONG, struct List * );

   FUNCTION
	This function returns a list of NetBuffSegments sufficient to
	hold Count bytes.

   INPUTS
	Count           Numbers of bytes for which space is needed.
	Segment_List    Pointer to an empty (initialized) list to hold
	                    the allocated NetBuffSegments.

   RESULTS

   NOTES
	The function cannot be called from interrupts.

   SEE ALSO
	netbuff.library/IntAllocSegments(),
	netbuff.library/FreeSegments(),
	netbuff.library/ReadyNetBuff()

   BUGS

netbuff.library/CompactNetBuff()             netbuff.library/CompactNetBuff()

   NAME
	CompactNetBuff -- Optimize a NetBuff.

   SYNOPSIS
	error = CompactNetBuff( Netbuff )
	D0                      A0

	LONG CompactNetBuff( struct NetBuff * );

   FUNCTION
	This function optimizes a NetBuff by moving the data to fill
	each needed NetBuffSegment as much as possible and return
	unused NetBuffSegments to the free pool. This function will
	not modify NetBuffSegments of physical size zero.

   INPUTS
	Netbuff         Pointer to NetBuff structure to optimize.

   RESULTS
	error           Zero if successful; non-zero otherwise.

   NOTES
	This function consumes time.

   SEE ALSO

   BUGS

netbuff.library/CopyFromNetBuff()           netbuff.library/CopyFromNetBuff()

   NAME
	CopyFromNetBuff -- Copy data from a NetBuff to memory.

   SYNOPSIS
	error = CopyFromNetBuff( Netbuff, Offset, Data, Count )
	D0                       A0       D0      A1    D1

	LONG CopyFromNetBuff( struct NetBuff *, LONG, UBYTE *, ULONG );

   FUNCTION
	This function copies 'Count' bytes from a NetBuff to memory
	pointed to by Data. If Offset is non-negative, then the start
	of the data to copy is 'Offset' bytes from the start of the
	NetBuff. If Offset is negative, then the start of the data to
	copy is 'abs(Offset)' bytes from the end of the NetBuff.

   INPUTS
	NetBuff         Pointer to NetBuff structure with source data.
	Offset          Offset into Netbuff where data starts.
	Data            Pointer to area to store data in.
	Count           Number of bytes to copy.

   RESULTS
	error           Zero if successful; non-zero otherwise.

   NOTES
	This function may be called from interrupts.

	This function might be used by a network device driver to
	extract bytes from a NetBuff to fill hardware.

	This function might be used within a protocol stack to extract
	data structures from a NetBuff into local memory.

   SEE ALSO
	netbuff.library/CopyToNetBuff()

   BUGS

netbuff.library/CopyNetBuff()                   netbuff.library/CopyNetBuff()

   NAME
	CopyNetBuff -- Make a copy of a NetBuff.

   SYNOPSIS
	error = CopyNetBuff( Netbuff0, Netbuff1 )
	D0                   A0        A1

	LONG CopyNetBuff( struct NetBuff *, struct NetBuff * );

   FUNCTION
	This function makes NetBuff1 a logical clone of Netbuff0.
	Netbuff0 will be unmodified and Netbuff1 will be optimal.

	All data in Netbuff1 will be lost when this function is
	called.

   INPUTS
	Netbuff0        Pointer to source NetBuff structure.
	Netbuff1        Pointer to destination NetBuff structure.

   RESULTS
	error           Zero if successful; non-zero otherwise.

   NOTES
	This function may be called from interrupts.

	Only the first NetBuffSegment in NetBuff1 is guaranteed to
	still be in NetBuff1 when this function returns.

   SEE ALSO
	netbuff.library/CopyFromNetBuff(),
	netbuff.library/CopyToNetBuff()

   BUGS

netbuff.library/CopyToNetBuff()               netbuff.library/CopyToNetBuff()

   NAME
	CopyToNetBuff -- Replace data in a NetBuff.

   SYNOPSIS
	error = CopyToNetBuff( Netbuff, Offset, Data, Count )
	D0                     A0       D0      A1    D1

	LONG CopyToNetBuff( struct NetBuff *, LONG, UBYTE *, ULONG );

   FUNCTION
	This function replaces existing data in Netbuff with 'Count'
	bytes from those pointed to by Data. If Offset is
	non-negative, then the replacement starts 'Offset' bytes from
	the start of Netbuff. If Offset is negative, then the
	replacement starts 'abs(Offset)' from the end of Netbuff.

	This function will not change the amount of data that Netbuff
	contains; it will only replace parts of it.

   INPUTS
	Netbuff         Pointer to NetBuff structure to copy data to.
	Offset          Offset into NetBuff to place data.
	Data            Pointer to data to copy.
	Count           Number of bytes of data to copy.

   RESULTS
	error           Zero if successful; non-zero otherwise.

   NOTES
	This function may be called from interrupts.

	This function might be used within a network device driver to
	fill a NetBuff from bytes taken from the hardware. In this
	case, CopyToNetBuff()s would be preceded possibly by a call to
	ReadyNetBuff().

   SEE ALSO
	netbuff.library/CopyFromNetBuff(),
	netbuff.library/ReadyNetBuff()

   BUGS

netbuff.library/FreeSegments()                 netbuff.library/FreeSegments()

   NAME
	FreeSegments -- Return a list of NetBuffSegments.

   SYNOPSIS
	FreeSegments( Segment_list )
	              A0

	void FreeSegments( struct List * );

   FUNCTION
	This function gives a list of NetBuffSegments to the system
	free pool.

   INPUTS
	Segment_list    Pointer to the list of NetBuffSegments to add
	                    to the system free NetBuffSegment pool.

   NOTES
	When this routine encounters a NetBuffSegment with
	PhysicalSize of 0, the data area is left untouched but the
	NetBuffSegment structure which points to the data is freed
	using exec.library/FreeMem().

   SEE ALSO
	netbuff.library/IntFreeSegments(),
	netbuff.library/AllocSegments(),
	netbuff.library/ReadyNetBuff()

   BUGS

netbuff.library/IntAllocSegments()         netbuff.library/IntAllocSegments()

   NAME
	IntAllocSegments -- Get a list of NetBuffSegments.

   SYNOPSIS
	IntAllocSegments( Count, Segment_List )
	                  D0     A0

	void IntAllocSegments( ULONG, struct List * );

   FUNCTION
	This function returns a list of NetBuffSegments sufficient to
	hold Count bytes.

   INPUTS
	Count           Numbers of bytes for which space is needed.
	Segment_List    Pointer to an empty (initialized) list to hold
	                    the allocated NetBuffSegments.

   RESULTS

   NOTES
	The function should be called only from interrupts.

   SEE ALSO
	netbuff.library/AllocSegments(),
	netbuff.library/IntFreeSegments(),
	netbuff.library/ReadyNetBuff()

   BUGS
	Since this function may be called from interrupts, it can not
	actually allocate memory from the system. It, therefor, relies
	on a "friendly" task or process to add NetBuffSegments to the
	free pool via the netbuff.library/FreeSegments() function.

netbuff.library/IntFreeSegments()           netbuff.library/IntFreeSegments()

   NAME
	IntFreeSegments -- Return a list of NetBuffSegments.

   SYNOPSIS
	IntFreeSegments( Segment_list )
	                 A0

	void IntFreeSegments( struct List * );

   FUNCTION
	This function gives a list of NetBuffSegments to the system
	free pool.

   INPUTS
	Segment_list    Pointer to the list of NetBuffSegments to add
	                    to the system free NetBuffSegment pool.

   NOTES
	The function should be called only from interrupts.

	When this routine encounters a NetBuffSegment with
	PhysicalSize of 0, that data area is left untouched but the
	NetBuffSegment structure which points to the data is freed
	using exec.library/FreeMem().

   SEE ALSO
	netbuff.library/FreeSegments(),
	netbuff.library/IntAllocSegments(),
	netbuff.library/ReadyNetBuff()

   BUGS
	This function relies on the non-interrupt functions to perform
	garbage collection of segments of physical size zero.

netbuff.library/IsContiguous()                 netbuff.library/IsContiguous()

   NAME
	IsContiguous -- Checks if data in in contiguous memory.

   SYNOPSIS
	result = IsContiguous( Netbuff, Offset, Count )
	D0                     A0       D0      D1

	LONG IsContiguous( struct NetBuff *, LONG, ULONG );

   FUNCTION
	This function indicates whether or not Count bytes of data
	starting at Offset in NetBuff are in contiguous bytes. If
	Offset is non-negative, then the start of the data to check is
	'Offset' bytes from the start of the NetBuff. If Offset is
	negative, then the start of the data to check is 'abs(Offset)'
	bytes from the end of the NetBuff.

   INPUTS
	Netbuff         Pointer to NetBuff to check.
	Offset          Offset into NetBuff where to check.
	Count           Number of bytes that should be contiguous.

   RESULTS
	result          Zero if non-contiguous; non-zero otherwise.

   NOTES

   SEE ALSO

   BUGS

netbuff.library/NetBuffAppend()               netbuff.library/NetBuffAppend()

   NAME
	NetBuffAppend -- Append one NetBuff to then end of another.

   SYNOPSIS
	error = NetBuffAppend( Netbuff0, Netbuff1 )
	D0                     A0        A1

	LONG NetBuffAppend( struct NetBuff *, struct NetBuff * );

   FUNCTION
	This function appends the contents of Netbuff1 to the end of
	Netbuff0.

   INPUTS
	Netbuff0        NetBuff to be appended to.
	Netbuff1        NetBuff to append.

   RESULTS
	error           Zero if successful; non-zero otherwise.

   NOTES

   SEE ALSO
	netbuff.library/PrependNetBuff(),
	netbuff.library/SplitNetBuff()

   BUGS

netbuff.library/PrependNetBuff()             netbuff.library/PrependNetBuff()

   NAME
	PrependNetBuff -- Prepend one NetBuff to the front of another.

   SYNOPSIS
	error = PrependNetBuff( Netbuff0, Netbuff1 )
	D0                      A0        A1

	LONG PrependNetBuff( struct NetBuff *, struct NetBuff * );

   FUNCTION
	This function prepends the contents of Netbuff1 to the front
	of Netbuff0.

   INPUTS
	Netbuff0        NetBuff to be prepended to.
	Netbuff1        NetBuff to prepend.

   RESULTS
	error           Zero if successful; non-zero otherwise.

   NOTES

   SEE ALSO
	netbuff.library/NetBuffAppend(),
	netbuff.library/SplitNetBuff()

   BUGS

netbuff.library/ReadyNetBuff()                 netbuff.library/ReadyNetBuff()

   NAME
	ReadyNetBuff -- Ready a NetBuff for copying to.

   SYNOPSIS
	error = ReadyNetBuff( Netbuff, Count )
	D0                    A0       D0

	LONG ReadyNetBuff( struct NetBuff *, ULONG );

   FUNCTION
	This function sets the amount of data refered to by a NetBuff,
	and the associated NetBuffSegments, to Count bytes in
	preparation for a CopyToNetBuff() operation. It does not
	initialize the data in the NetBuff.

   INPUTS
	Netbuff         Pointer to NetBuff structure to initialize.
	Count           The number of bytes of data that the NetBuff
	                    is to refer to.

   RESULTS
	error           Zero if successful; non-zero otherwise.

   NOTES
	This function may be called from interrupts.

	This function will attempt to allocate NetBuffSegments as
	needed to make room for Count bytes available.

	Unneeded NetBuffSegments will be returned to the system free
	pool.

   SEE ALSO

   BUGS

netbuff.library/ReclaimSegments()           netbuff.library/ReclaimSegments()

   NAME
	ReclaimSegments -- Free all but first NetBuffSegment.

   SYNOPSIS
	error = ReclaimSegments( Netbuff )
	D0                       A0

	LONG ReclaimSegments( struct NetBuff * );

   FUNCTION
	This function frees all non-zero PhysicalSize NetBuffSegments
	except the first NetBuffSegment of the NetBuff.

   INPUTS
	Netbuff         Pointer to NetBuff to reclaim segments from.

   RESULTS
	error           Zero if successful; non-zero otherwise.

   NOTES
	This function may be called from interrupts.

	The intended use for this function is to encourage drivers or
	protocol stacks to free NetBuffSegments from NetBuffs in read
	queues.

   SEE ALSO

   BUGS

netbuff.library/SplitNetBuff()                 netbuff.library/SplitNetBuff()

   NAME
	SplitNetBuff -- Split a NetBuff in to two NetBuffs.

   SYNOPSIS
	error = SplitNetBuff( Netbuff0, Count, Netbuff1 )
	D0                    A0        D0     A1

	LONG SplitNetBuff( struct NetBuff *, LONG, struct NetBuff * );

   FUNCTION
	This function takes a NetBuff and splits it at the specified
	offset. The sign of Count determines which bytes will be
	removed from Netbuff0 and placed in Netbuff1. If Count is
	non-negative, the first 'Offset' bytes in Netbuff0 will be
	moved to Netbuff1. If Offset is negative, the last
	'abs(Offset)' bytes in Netbuff0 will be moved to Netbuff1.

	All data in Netbuff1 will be lost when this function is
	called.

   INPUTS
	Netbuff0        Pointer to NetBuff structure with data to
	                    split.
	Count           Number of bytes to split off.
	Netbuff1        Pointer to a NetBuff structure to receive
	                    split-off data.

   RESULTS
	error           Zero if successful; non-zero otherwise.

   NOTES
	This function might be used within a protocol stack to split
	a packet into smaller NetBuffs so as to fall below a specific
	transport medium's maximum transfer unit.
	
   SEE ALSO
	netbuff.library/TrimNetBuff(),
	netbuff.library/NetBuffAppend(),
	netbuff.library/PrependNetBuff()

   BUGS
	If the split point is in a NetBuffSegment of PhysicalSize
	zero, exec/AllocMem() will be called to create a new segment
	of PhysicalSize zero.

netbuff.library/TrimNetBuff()                   netbuff.library/TrimNetBuff()

   NAME
	TrimNetBuff -- Elliminate leading or trailing data.

   SYNOPSIS
	error = TrimNetBuff( Netbuff, Count )
	D0                   A0        D0

	LONG TrimNetBuff( struct NetBuff *, LONG );

   FUNCTION
	This function takes a NetBuff and elliminates 'abs(Count)'
	bytes of data from the first or last bytes of the NetBuff data
	depending on the sign of Count. If Count is positive, the
	first 'Count' bytes of data are elliminated. If Count is
	negative, the last 'abs(Count)' bytes are elliminated.

	Emptied NetBuffSegments (which may result) will be returned to
	the free pool.

   INPUTS
	Netbuff         Pointer to NetBuff to be trimmed.
	Count           Number of data bytes to remove.

   RESULTS
	error           Zero if successful; non-zero otherwise.

   NOTES
	This function might be used within a protocol stack to remove
	levels of protocol wrapping from either side of a packet.

   SEE ALSO
	netbuff.library/SplitNetBuff(),
	netbuff.library/NetBuffAppend(),
	netbuff.library/PrependNetBuff()

   BUGS