home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD v1.2 / amidev_cd_12.iso / devcon / milan_1991 / devcon91.2 / network / sana2 / netbuff.doc < prev    next >
Text File  |  1992-09-01  |  18KB  |  630 lines
  1. TABLE OF CONTENTS
  2.  
  3. netbuff.library
  4. netbuff.library/AllocSegments()
  5. netbuff.library/CompactNetBuff()
  6. netbuff.library/CopyFromNetBuff()
  7. netbuff.library/CopyNetBuff()
  8. netbuff.library/CopyToNetBuff()
  9. netbuff.library/FreeSegments()
  10. netbuff.library/IntAllocSegments()
  11. netbuff.library/IntFreeSegments()
  12. netbuff.library/IsContiguous()
  13. netbuff.library/NetBuffAppend()
  14. netbuff.library/PrependNetBuff()
  15. netbuff.library/ReadyNetBuff()
  16. netbuff.library/SplitNetBuff()
  17. netbuff.library/TrimNetBuff()
  18. netbuff.library                                               netbuff.library
  19.  
  20.     Netbuff.library maintains the free pool of NetBuffSegments for
  21.     use by the various network modules. It also contains several
  22.     utility functions for dealing with NetBuffs as a data
  23.     structure for "holding" network packet data as well as
  24.     allocators and deallocators for NetBuffSegments.
  25.  
  26.     The intent is for all of the network modules to use a common
  27.     pool of buffers so as to reduce the memory requirements of the
  28.     network software, and for the network modules to be able to
  29.     pass network data (packets) with minimal copying.
  30.  
  31.    STRUCTURES
  32.     A NetBuff is a data structure representing a logical array of
  33.     of bytes.
  34.  
  35.         struct NetBuff
  36.             {
  37.             struct MinList List;
  38.             ULONG Count;
  39.             };
  40.  
  41.         List
  42.             List of NetBuffSegments.
  43.  
  44.         Count
  45.             The number of bytes of data the NetBuff is said to
  46.             contain.
  47.  
  48.  
  49.     A NetBuffSegment is a data structure used to store and keep
  50.     track of all or part of the data in a NetBuff.
  51.  
  52.         struct NetBuffSegment
  53.             {
  54.             struct MinNode Node;
  55.             ULONG PhysicalSize;
  56.             ULONG DataOffset;
  57.             ULONG DataCount;
  58.             UBYTE *Buffer;
  59.             };
  60.  
  61.         Node
  62.             Node structure linking the NetBuffSegments together.
  63.  
  64.         PhysicalSize
  65.             The size of the data area that Buffer points to. If
  66.             this field is zero, the actual size of the data area
  67.             unknown and it is managed (allocated and freed) by
  68.             some other entity. Only 'Count' bytes starting at
  69.             '(Buffer+Offset)' are known to be valid.
  70.  
  71.         DataOffset
  72.             Offset into the Buffer where the data starts.
  73.  
  74.         DataCount
  75.             Number of data bytes that this NetBuffSegment
  76.             contains.
  77.  
  78.         Buffer
  79.             Pointer to the start of the data area for this
  80.             NetBuffSegment.
  81.  
  82.    PHYSICALSIZE ZERO SEGMENTS
  83.     Any software making use of NetBuffs must correctly handle
  84.     NetBuffs with PhysicalSize zero segments. The general rules to
  85.     follow are as follows:
  86.  
  87.     +   "Send" NetBuffs, those NetBuffs where the data is created
  88.         and passed to a lower network layer, are returned to the
  89.         creator with the data intact. This class of NetBuffs may
  90.         have segments of PhysicalSize zero.
  91.  
  92.     +   "Receive" NetBuffs, those NetBuffs where the data is
  93.         created and passed to a higher network layer, are not
  94.         returned to the creator. This class of NetBuffs may not
  95.         have segments of PhysicalSize zero.
  96.  
  97.     +   Lower network layers will eventually return the actual
  98.         NetBuff structure (pointer) to the layer that created the
  99.         data.
  100.  
  101.     +   NetBuffs returned to higher layers from lower layers may
  102.         have the "physical" layout of the data changed. The layout
  103.         of the "logical" data will not have changed.
  104.  
  105.     +   Track NetBuff structures to know when it is safe to reuse/
  106.         deallocate storage for PhysicalSize zero segments.
  107.  
  108.     In to above, higher and lower network layers refers to the
  109.     usual diagram of the OSI network layering model; where the
  110.     application layer is at the top of the diagram and the
  111.     physical layer is at the bottom.
  112.  
  113.     This model for handling PhysicalSize zero segments also has
  114.     obvious advantages in situations where time-outs and
  115.     retransmittions occure.
  116.  
  117.    CREDITS
  118.     Raymond S. Brand   rsbx@cbmvax.commodore.com   (215) 431-9100
  119.     Martin Hunt      martin@cbmvax.commodore.com   (215) 431-9100
  120.     Perry Kivolowitz           ASDG Incorporated   (608) 273-6585
  121.  
  122. netbuff.library/AllocSegments()               netbuff.library/AllocSegments()
  123.  
  124.    NAME
  125.     AllocSegments -- Get a list of NetBuffSegments.
  126.  
  127.    SYNOPSIS
  128.     AllocSegments( Count, Segment_List )
  129.                    D0     A0
  130.  
  131.     void AllocSegments( ULONG, struct List * );
  132.  
  133.    FUNCTION
  134.     This function returns a list of NetBuffSegments sufficient to
  135.     hold Count bytes.
  136.  
  137.    INPUTS
  138.     Count           Numbers of bytes for which space is needed.
  139.     Segment_List    Pointer to an empty (initialized) list to hold
  140.                         the allocated NetBuffSegments.
  141.  
  142.    RESULTS
  143.  
  144.    NOTES
  145.     The function cannot be called from interrupts.
  146.  
  147.    SEE ALSO
  148.     netbuff.library/IntAllocSegments(),
  149.     netbuff.library/FreeSegments(),
  150.     netbuff.library/ReadyNetBuff()
  151.  
  152.    BUGS
  153.  
  154. netbuff.library/CompactNetBuff()             netbuff.library/CompactNetBuff()
  155.  
  156.    NAME
  157.     CompactNetBuff -- Optimize a NetBuff.
  158.  
  159.    SYNOPSIS
  160.     error = CompactNetBuff( Netbuff )
  161.     D0                      A0
  162.  
  163.     LONG CompactNetBuff( struct NetBuff * );
  164.  
  165.    FUNCTION
  166.     This function optimizes a NetBuff by moving the data to fill
  167.     each needed NetBuffSegment as much as possible and return
  168.     unused NetBuffSegments to the free pool. This function will
  169.     not modify NetBuffSegments of physical size zero.
  170.  
  171.    INPUTS
  172.     Netbuff         Pointer to NetBuff structure to optimize.
  173.  
  174.    RESULTS
  175.     error           Zero if successful; non-zero otherwise.
  176.  
  177.    NOTES
  178.     This function consumes time.
  179.  
  180.    SEE ALSO
  181.  
  182.    BUGS
  183.  
  184. netbuff.library/CopyFromNetBuff()           netbuff.library/CopyFromNetBuff()
  185.  
  186.    NAME
  187.     CopyFromNetBuff -- Copy data from a NetBuff to memory.
  188.  
  189.    SYNOPSIS
  190.     error = CopyFromNetBuff( Netbuff, Offset, Data, Count )
  191.     D0                       A0       D0      A1    D1
  192.  
  193.     LONG CopyFromNetBuff( struct NetBuff *, LONG, UBYTE *, ULONG );
  194.  
  195.    FUNCTION
  196.     This function copies 'Count' bytes from a NetBuff to memory
  197.     pointed to by Data. If Offset is non-negative, then the start
  198.     of the data to copy is 'Offset' bytes from the start of the
  199.     NetBuff. If Offset is negative, then the start of the data to
  200.     copy is 'abs(Offset)' bytes from the end of the NetBuff.
  201.  
  202.    INPUTS
  203.     NetBuff         Pointer to NetBuff structure with source data.
  204.     Offset          Offset into Netbuff where data starts.
  205.     Data            Pointer to area to store data in.
  206.     Count           Number of bytes to copy.
  207.  
  208.    RESULTS
  209.     error           Zero if successful; non-zero otherwise.
  210.  
  211.    NOTES
  212.     This function may be called from interrupts.
  213.  
  214.     This function might be used by a network device driver to
  215.     extract bytes from a NetBuff to fill hardware.
  216.  
  217.     This function might be used within a protocol stack to extract
  218.     data structures from a NetBuff into local memory.
  219.  
  220.    SEE ALSO
  221.     netbuff.library/CopyToNetBuff()
  222.  
  223.    BUGS
  224.  
  225. netbuff.library/CopyNetBuff()                   netbuff.library/CopyNetBuff()
  226.  
  227.    NAME
  228.     CopyNetBuff -- Make a copy of a NetBuff.
  229.  
  230.    SYNOPSIS
  231.     error = CopyNetBuff( Netbuff0, Netbuff1 )
  232.     D0                   A0        A1
  233.  
  234.     LONG CopyNetBuff( struct NetBuff *, struct NetBuff * );
  235.  
  236.    FUNCTION
  237.     This function makes NetBuff1 a logical clone of Netbuff0.
  238.     Netbuff0 will be unmodified and Netbuff1 will be optimal.
  239.  
  240.     All data in Netbuff1 will be lost when this function is
  241.     called.
  242.  
  243.    INPUTS
  244.     Netbuff0        Pointer to source NetBuff structure.
  245.     Netbuff1        Pointer to destination NetBuff structure.
  246.  
  247.    RESULTS
  248.     error           Zero if successful; non-zero otherwise.
  249.  
  250.    NOTES
  251.     This function may be called from interrupts.
  252.  
  253.     Only the first NetBuffSegment in NetBuff1 is guaranteed to
  254.     still be in NetBuff1 when this function returns.
  255.  
  256.    SEE ALSO
  257.     netbuff.library/CopyFromNetBuff(),
  258.     netbuff.library/CopyToNetBuff()
  259.  
  260.    BUGS
  261.  
  262. netbuff.library/CopyToNetBuff()               netbuff.library/CopyToNetBuff()
  263.  
  264.    NAME
  265.     CopyToNetBuff -- Replace data in a NetBuff.
  266.  
  267.    SYNOPSIS
  268.     error = CopyToNetBuff( Netbuff, Offset, Data, Count )
  269.     D0                     A0       D0      A1    D1
  270.  
  271.     LONG CopyToNetBuff( struct NetBuff *, LONG, UBYTE *, ULONG );
  272.  
  273.    FUNCTION
  274.     This function replaces existing data in Netbuff with 'Count'
  275.     bytes from those pointed to by Data. If Offset is
  276.     non-negative, then the replacement starts 'Offset' bytes from
  277.     the start of Netbuff. If Offset is negative, then the
  278.     replacement starts 'abs(Offset)' from the end of Netbuff.
  279.  
  280.     This function will not change the amount of data that Netbuff
  281.     contains; it will only replace parts of it.
  282.  
  283.    INPUTS
  284.     Netbuff         Pointer to NetBuff structure to copy data to.
  285.     Offset          Offset into NetBuff to place data.
  286.     Data            Pointer to data to copy.
  287.     Count           Number of bytes of data to copy.
  288.  
  289.    RESULTS
  290.     error           Zero if successful; non-zero otherwise.
  291.  
  292.    NOTES
  293.     This function may be called from interrupts.
  294.  
  295.     This function might be used within a network device driver to
  296.     fill a NetBuff from bytes taken from the hardware. In this
  297.     case, CopyToNetBuff()s would be preceded possibly by a call to
  298.     ReadyNetBuff().
  299.  
  300.    SEE ALSO
  301.     netbuff.library/CopyFromNetBuff(),
  302.     netbuff.library/ReadyNetBuff()
  303.  
  304.    BUGS
  305.  
  306. netbuff.library/FreeSegments()                 netbuff.library/FreeSegments()
  307.  
  308.    NAME
  309.     FreeSegments -- Return a list of NetBuffSegments.
  310.  
  311.    SYNOPSIS
  312.     FreeSegments( Segment_list )
  313.                   A0
  314.  
  315.     void FreeSegments( struct List * );
  316.  
  317.    FUNCTION
  318.     This function gives a list of NetBuffSegments to the system
  319.     free pool.
  320.  
  321.    INPUTS
  322.     Segment_list    Pointer to the list of NetBuffSegments to add
  323.                         to the system free NetBuffSegment pool.
  324.  
  325.    NOTES
  326.     When this routine encounters a NetBuffSegment with
  327.     PhysicalSize of 0, the data area is left untouched but the
  328.     NetBuffSegment structure which points to the data is freed
  329.     using exec.library/FreeMem().
  330.  
  331.    SEE ALSO
  332.     netbuff.library/IntFreeSegments(),
  333.     netbuff.library/AllocSegments(),
  334.     netbuff.library/ReadyNetBuff()
  335.  
  336.    BUGS
  337.  
  338. netbuff.library/IntAllocSegments()         netbuff.library/IntAllocSegments()
  339.  
  340.    NAME
  341.     IntAllocSegments -- Get a list of NetBuffSegments.
  342.  
  343.    SYNOPSIS
  344.     IntAllocSegments( Count, Segment_List )
  345.                       D0     A0
  346.  
  347.     void IntAllocSegments( ULONG, struct List * );
  348.  
  349.    FUNCTION
  350.     This function returns a list of NetBuffSegments sufficient to
  351.     hold Count bytes.
  352.  
  353.    INPUTS
  354.     Count           Numbers of bytes for which space is needed.
  355.     Segment_List    Pointer to an empty (initialized) list to hold
  356.                         the allocated NetBuffSegments.
  357.  
  358.    RESULTS
  359.  
  360.    NOTES
  361.     The function should be called only from interrupts.
  362.  
  363.    SEE ALSO
  364.     netbuff.library/AllocSegments(),
  365.     netbuff.library/IntFreeSegments(),
  366.     netbuff.library/ReadyNetBuff()
  367.  
  368.    BUGS
  369.     Since this function may be called from interrupts, it can not
  370.     actually allocate memory from the system. It, therefor, relies
  371.     on a "friendly" task or process to add NetBuffSegments to the
  372.     free pool via the netbuff.library/FreeSegments() function.
  373.  
  374. netbuff.library/IntFreeSegments()           netbuff.library/IntFreeSegments()
  375.  
  376.    NAME
  377.     IntFreeSegments -- Return a list of NetBuffSegments.
  378.  
  379.    SYNOPSIS
  380.     IntFreeSegments( Segment_list )
  381.                      A0
  382.  
  383.     void IntFreeSegments( struct List * );
  384.  
  385.    FUNCTION
  386.     This function gives a list of NetBuffSegments to the system
  387.     free pool.
  388.  
  389.    INPUTS
  390.     Segment_list    Pointer to the list of NetBuffSegments to add
  391.                         to the system free NetBuffSegment pool.
  392.  
  393.    NOTES
  394.     The function should be called only from interrupts.
  395.  
  396.     When this routine encounters a NetBuffSegment with
  397.     PhysicalSize of 0, that data area is left untouched but the
  398.     NetBuffSegment structure which points to the data is freed
  399.     using exec.library/FreeMem().
  400.  
  401.    SEE ALSO
  402.     netbuff.library/FreeSegments(),
  403.     netbuff.library/IntAllocSegments(),
  404.     netbuff.library/ReadyNetBuff()
  405.  
  406.    BUGS
  407.     This function relies on the non-interrupt functions to perform
  408.     garbage collection of segments of physical size zero.
  409.  
  410. netbuff.library/IsContiguous()                 netbuff.library/IsContiguous()
  411.  
  412.    NAME
  413.     IsContiguous -- Checks if data in in contiguous memory.
  414.  
  415.    SYNOPSIS
  416.     result = IsContiguous( Netbuff, Offset, Count )
  417.     D0                     A0       D0      D1
  418.  
  419.     LONG IsContiguous( struct NetBuff *, LONG, ULONG );
  420.  
  421.    FUNCTION
  422.     This function indicates whether or not Count bytes of data
  423.     starting at Offset in NetBuff are in contiguous bytes. If
  424.     Offset is non-negative, then the start of the data to check is
  425.     'Offset' bytes from the start of the NetBuff. If Offset is
  426.     negative, then the start of the data to check is 'abs(Offset)'
  427.     bytes from the end of the NetBuff.
  428.  
  429.    INPUTS
  430.     Netbuff         Pointer to NetBuff to check.
  431.     Offset          Offset into NetBuff where to check.
  432.     Count           Number of bytes that should be contiguous.
  433.  
  434.    RESULTS
  435.     result          Zero if non-contiguous; non-zero otherwise.
  436.  
  437.    NOTES
  438.  
  439.    SEE ALSO
  440.  
  441.    BUGS
  442.  
  443. netbuff.library/NetBuffAppend()               netbuff.library/NetBuffAppend()
  444.  
  445.    NAME
  446.     NetBuffAppend -- Append one NetBuff to then end of another.
  447.  
  448.    SYNOPSIS
  449.     error = NetBuffAppend( Netbuff0, Netbuff1 )
  450.     D0                     A0        A1
  451.  
  452.     LONG NetBuffAppend( struct NetBuff *, struct NetBuff * );
  453.  
  454.    FUNCTION
  455.     This function appends the contents of Netbuff1 to the end of
  456.     Netbuff0.
  457.  
  458.    INPUTS
  459.     Netbuff0        NetBuff to be appended to.
  460.     Netbuff1        NetBuff to append.
  461.  
  462.    RESULTS
  463.     error           Zero if successful; non-zero otherwise.
  464.  
  465.    NOTES
  466.  
  467.    SEE ALSO
  468.     netbuff.library/PrependNetBuff(),
  469.     netbuff.library/SplitNetBuff()
  470.  
  471.    BUGS
  472.  
  473. netbuff.library/PrependNetBuff()             netbuff.library/PrependNetBuff()
  474.  
  475.    NAME
  476.     PrependNetBuff -- Prepend one NetBuff to the front of another.
  477.  
  478.    SYNOPSIS
  479.     error = PrependNetBuff( Netbuff0, Netbuff1 )
  480.     D0                      A0        A1
  481.  
  482.     LONG PrependNetBuff( struct NetBuff *, struct NetBuff * );
  483.  
  484.    FUNCTION
  485.     This function prepends the contents of Netbuff1 to the front
  486.     of Netbuff0.
  487.  
  488.    INPUTS
  489.     Netbuff0        NetBuff to be prepended to.
  490.     Netbuff1        NetBuff to prepend.
  491.  
  492.    RESULTS
  493.     error           Zero if successful; non-zero otherwise.
  494.  
  495.    NOTES
  496.  
  497.    SEE ALSO
  498.     netbuff.library/NetBuffAppend(),
  499.     netbuff.library/SplitNetBuff()
  500.  
  501.    BUGS
  502.  
  503. netbuff.library/ReadyNetBuff()                 netbuff.library/ReadyNetBuff()
  504.  
  505.    NAME
  506.     ReadyNetBuff -- Ready a NetBuff for copying to.
  507.  
  508.    SYNOPSIS
  509.     error = ReadyNetBuff( Netbuff, Count )
  510.     D0                    A0       D0
  511.  
  512.     LONG ReadyNetBuff( struct NetBuff *, ULONG );
  513.  
  514.    FUNCTION
  515.     This function sets the amount of data refered to by a NetBuff,
  516.     and the associated NetBuffSegments, to Count bytes in
  517.     preparation for a CopyToNetBuff() operation. It does not
  518.     initialize the data in the NetBuff.
  519.  
  520.    INPUTS
  521.     Netbuff         Pointer to NetBuff structure to initialize.
  522.     Count           The number of bytes of data that the NetBuff
  523.                         is to refer to.
  524.  
  525.    RESULTS
  526.     error           Zero if successful; non-zero otherwise.
  527.  
  528.    NOTES
  529.     This function may be called from interrupts.
  530.  
  531.     This function will attempt to allocate NetBuffSegments as
  532.     needed to make room for Count bytes available.
  533.  
  534.     Unneeded NetBuffSegments are returned to the system free pool.
  535.  
  536.     Calling this function with a Count of zero will return all of
  537.     NetBuffSegments in the NetBuff to the system free pool except
  538.     the first NetBuffSegment.
  539.  
  540.    SEE ALSO
  541.  
  542.    BUGS
  543.  
  544. netbuff.library/SplitNetBuff()                 netbuff.library/SplitNetBuff()
  545.  
  546.    NAME
  547.     SplitNetBuff -- Split a NetBuff in to two NetBuffs.
  548.  
  549.    SYNOPSIS
  550.     error = SplitNetBuff( Netbuff0, Count, Netbuff1 )
  551.     D0                    A0        D0     A1
  552.  
  553.     LONG SplitNetBuff( struct NetBuff *, LONG, struct NetBuff * );
  554.  
  555.    FUNCTION
  556.     This function takes a NetBuff and splits it at the specified
  557.     offset. The sign of Count determines which bytes will be
  558.     removed from Netbuff0 and placed in Netbuff1. If Count is
  559.     non-negative, the first 'Offset' bytes in Netbuff0 will be
  560.     moved to Netbuff1. If Offset is negative, the last
  561.     'abs(Offset)' bytes in Netbuff0 will be moved to Netbuff1.
  562.  
  563.     All data in Netbuff1 will be lost when this function is
  564.     called.
  565.  
  566.    INPUTS
  567.     Netbuff0        Pointer to NetBuff structure with data to
  568.                         split.
  569.     Count           Number of bytes to split off.
  570.     Netbuff1        Pointer to a NetBuff structure to receive
  571.                         split-off data.
  572.  
  573.    RESULTS
  574.     error           Zero if successful; non-zero otherwise.
  575.  
  576.    NOTES
  577.     This function might be used within a protocol stack to split
  578.     a packet into smaller NetBuffs so as to fall below a specific
  579.     transport medium's maximum transfer unit.
  580.     
  581.    SEE ALSO
  582.     netbuff.library/TrimNetBuff(),
  583.     netbuff.library/NetBuffAppend(),
  584.     netbuff.library/PrependNetBuff()
  585.  
  586.    BUGS
  587.     If the split point is in a NetBuffSegment of PhysicalSize
  588.     zero, exec/AllocMem() will be called to create a new segment
  589.     of PhysicalSize zero.
  590.  
  591. netbuff.library/TrimNetBuff()                   netbuff.library/TrimNetBuff()
  592.  
  593.    NAME
  594.     TrimNetBuff -- Elliminate leading or trailing data.
  595.  
  596.    SYNOPSIS
  597.     error = TrimNetBuff( Netbuff, Count )
  598.     D0                   A0        D0
  599.  
  600.     LONG TrimNetBuff( struct NetBuff *, LONG );
  601.  
  602.    FUNCTION
  603.     This function takes a NetBuff and elliminates 'abs(Count)'
  604.     bytes of data from the first or last bytes of the NetBuff data
  605.     depending on the sign of Count. If Count is positive, the
  606.     first 'Count' bytes of data are elliminated. If Count is
  607.     negative, the last 'abs(Count)' bytes are elliminated.
  608.  
  609.     Emptied NetBuffSegments (which may result) will be returned to
  610.     the free pool.
  611.  
  612.    INPUTS
  613.     Netbuff         Pointer to NetBuff to be trimmed.
  614.     Count           Number of data bytes to remove.
  615.  
  616.    RESULTS
  617.     error           Zero if successful; non-zero otherwise.
  618.  
  619.    NOTES
  620.     This function might be used within a protocol stack to remove
  621.     levels of protocol wrapping from either side of a packet.
  622.  
  623.    SEE ALSO
  624.     netbuff.library/SplitNetBuff(),
  625.     netbuff.library/NetBuffAppend(),
  626.     netbuff.library/PrependNetBuff()
  627.  
  628.    BUGS
  629.  
  630.