nbuffer.c File Reference

Network buffer management: Implementation More...

#include "..\includes.h"
#include "nbuffer.h"

Macros
#define	MAX_NBUFFER_SIZE
#define	NBUFFER_NO_ERROR   NBufferMessages[0]
#define	NBUFFER_OUT_OF_MEMORY_ERROR   NBufferMessages[1]

Functions
char *	NBufferAcquireBuffer (SOCKET *so)
	acquire new buffer More...
int	NBufferFreeBuffer (SOCKET *so)
	free packet buffer More...

Variables
const char *	NBufferMessages []

Detailed Description

                          _         _             _
                       __| |    ___(_) ____ _ __ | |_
                      / _` |   / __| |/ _` | '_ \| __|
                     | (_| | _ \__ \ | (_| | | | | |_
                      \__,_|(_) ___/_|\__, |_| |_|\__|
                     Signalprocessing |___/ Technology

Author

D.SignT GmbH & Co. KG, Claus Hermbusche

Version

2.91

Date

2019-04-17

Network buffer management. This module simplifies the use of multiple data buffers for sockets. Each socket gets its own buffer control structure and multiple buffers (e.g. for ping-pong-buffering) organized as ring buffers.

The buffers can be allocated dynamically or defined statically. A define USE_STATIC_MEMORY forces this module to select the desired memory usage.

Per multi buffered socket two structures must be created in the user application. This is the main data buffer (NBuffer_t) and the buffer control structure (NBCtl_t).

E.g.:

#define MAX_NBUFFER_SIZE              1500
#include "..\..\..\Common\nbuffer.h"         // network buffer support

#define MAX_UDP_BUFFERS               4

// main data buffer
NBuffer_t udp_buffer[MAX_UDP_BUFFERS];           // buffers for UDP echo

// create and pre-initialize buffer control structure
NBCtl_t bcontrol =
{
   udp_buffer,                                 // buffers (defined before)
   sizeof(NBuffer_t),                          // size of NBuffer_t
   0,                                          // used buffers
   0,                                          // out of buffer memory
   BUFFER_EMPTY,                               // receive index
   BUFFER_EMPTY,                               // process index
   MAX_UDP_BUFFERS,                            // max buffers
   0                                           // use static memory
   MAX_NBUFFER_SIZE                            // NBuffer size limit
};

After allocating a socket with socket_open(), the buffer control structure must be assigned to this socket

udp_echo_so = socket_open (ANY_ADDRESS, ...

// *************************************************************************
// attach buffer control structure to socket
//  (required for NBufferAcquireBuffer() later)
// *************************************************************************
udp_echo_so-> user_pointer = &bcontrol;

Initially NBufferAcquireBuffer() must be called for this socket to get a new buffer assigned to this socket:

// *************************************************************************
// initially malloc space for data
// NBufferAcquireBuffer() allocates new buffer space and modifies the
// bcontrol structure
// *************************************************************************
if ( NBufferAcquireBuffer (udp_echo_so) == NULL )
{
    prg_exit("out of memory error");
} // if

After receiving new data (net_recv() returns a value > 0 or a callback function is called with new data), the user can decide if this buffer can be processed immediately and re-used for the next incoming data or if the packet must be processed later. In the latter case the current buffer index for later processing can be stored to

bctl-> pi

and a new function call to

NBufferAcquireBuffer(so)

will allocate and attach the next buffer.

If a buffer is waiting for processing, can be detected in you application by testing

NBCtl_t *bctl = (NBCtl_t *)so-> user_pointer;       // get buffer control
if ( bctl-> pi != BUFFER_EMPTY ) ...

After processing the cached data, this buffer must be freed with

NBufferFreeBuffer (so);

This function call maintains the process index pi and sets BUFFER_EMPTY, if process index points to receive index.

Error handling for UDP and for TCP is a bit different. For both protocols a flag OutOfBuffer must be set immediately when function NBufferAcquireBuffer() returns no buffer. For TCP additionally a zero window packet must be sent to avoid a buffer overrun when the peer sends the next packet

if ( NBufferAcquireBuffer (so) == NULL)
{
  // ***************************************************************
  //  allocation failed due to all buffers in use.
  //  this may happen when the receive task works faster than the
  //  signal processing task.
  //  send a zero window packet to the remote side to stop the TCP
  //  and set OutOfBuffer flag to handle this condition later
  // ***************************************************************
  bctl-> OutOfBuffer = TRUE;
  tcp_send_zero_window ( so );  // for TCP only
} // if

In the main network task (this is where your net_isq() is called frequently) check the OutOfBuffer condition and try to allocate a new buffer

if ( bctl-> OutOfBuffer )
{
  if ( NBufferAcquireBuffer (so) != NULL )
  {
    // *******************************************************************
    //  allocation successful,
    //  reset OutOfBuffer flag,
    //  send window update to start the TCP
    // *******************************************************************
    bctl-> OutOfBuffer = FALSE;
    tcp_send_window_update ( so );  // for TCP only
  } // if
} // if

Macro Definition Documentation

#define MAX_NBUFFER_SIZE

Examples:

Echo.c.

#define NBUFFER_NO_ERROR   NBufferMessages[0]

#define NBUFFER_OUT_OF_MEMORY_ERROR   NBufferMessages[1]

Function Documentation

char* NBufferAcquireBuffer

(

SOCKET *

so

)

[Network Buffer Control Structure]

Parameters

so	- socket to acquire new buffer for

Returns

buffer if successful, NULL if no buffer available

Note

Precondition is a valid user_pointer to a buffer control structure

{
    /***************************************************************************
     locals
    ***************************************************************************/
    NBCtl_t *bctl = (NBCtl_t *)so-> user_pointer;       /* get buffer control */
    size_t psize;
    char *pbuffer;

    if ( bctl == NULL )
    {
        /***********************************************************************
         no control structure available
        ***********************************************************************/
        return (NULL);
    } // if

    /***************************************************************************
     check used buffers
    ***************************************************************************/
    if ( bctl-> BuffersInUse >= bctl-> MaxBuffers )
    {
        /***********************************************************************
         all buffers in use
        ***********************************************************************/
        return (NULL);
    } // if

    /***************************************************************************
     check receive index range
    ***************************************************************************/
    if ( ++bctl-> ri >= bctl-> MaxBuffers )
    {
        /***********************************************************************
         wrap around ring buffer
        ***********************************************************************/
        bctl-> ri = 0;
    } // if

    /***************************************************************************
     depending on protocol allocate max packet size
    ***************************************************************************/
    psize = (so-> proto == IPT_TCP)? TCP_MAX_PACKET_SIZE* sizeof(char)
                                   : UDP_MAX_PACKET_SIZE* sizeof(char);

    /***************************************************************************
     limit to buffer size
    ***************************************************************************/
    if ( psize > bctl-> NBuffer_SizeLimit )
    {
        psize = bctl-> NBuffer_SizeLimit;
    } // if


    /***************************************************************************
     use dynamic memory?
    ***************************************************************************/
    if ( bctl-> UseDynMem )
    {
        /***********************************************************************
         allocate a new buffer
        ***********************************************************************/
        pbuffer = bctl-> Buf[bctl-> ri].Data = (char *) malloc (psize*2);
        if ( pbuffer == NULL )
        {
            prg_exit(NBUFFER_OUT_OF_MEMORY_ERROR);
        }
    }
    else
    {
        /***********************************************************************
         for static buffers determine next buffer offset
         from nubffer.c view NBuffer_t member Data is a simple char * not an
         array of char, because define USE_STATIC_MEMORY is undefined (defined
         in user application). Thus we cannot use bctl-> buf[bctl-> ri].Data
         here and have to calculate the new buffer offset manually
        ***********************************************************************/
        pbuffer = (char *)((uint32_t)(bctl-> Buf) + (bctl-> ri * bctl-> NBuffer_tsize));
    }

    /***************************************************************************
     assign new buffer to socket
      for TCP this buffer size (psize in this case) is offered to peer as
      TCP Window Size
    ***************************************************************************/
    set_recv_buffer (so, pbuffer, (uint16_t)psize );

    //~ CPrintf ("allocate: %08lx\r\n", buffer);

    /***************************************************************************
     maintain buffer counter
    ***************************************************************************/
    bctl-> BuffersInUse++;

    return (pbuffer);
}

int NBufferFreeBuffer

(

SOCKET *

so

)

Parameters

so	- socket to release old buffer

Returns

• 0 - success
• -1 - error

Note

Precondition is a valid user_pointer to a buffer control structure

{
    /***************************************************************************
     locals
    ***************************************************************************/
    NBCtl_t *bctl = (NBCtl_t *)so-> user_pointer;       /* get buffer control */
    char *pbuffer;

    if ( bctl == NULL )
    {
        /***********************************************************************
         no control structure available
        ***********************************************************************/
        return (-1);
    } // if

    /***************************************************************************
     range check
    ***************************************************************************/
    if (( bctl-> pi != BUFFER_EMPTY ) && ( bctl-> pi < bctl-> MaxBuffers ) )
    {
        /***********************************************************************
         use dynamic memory?
        ***********************************************************************/
        if ( bctl-> UseDynMem )
        {
             pbuffer = bctl-> Buf[bctl-> pi].Data;
             //~ CPrintf ("free: %08lx\r\n", buffer);

            /*******************************************************************
             free memory
            *******************************************************************/
            free ((void *)pbuffer );
        }
        else
        {
            /*******************************************************************
             for static buffers determine next buffer offset
             from nubffer.c view NBuffer_t member Data is a simple char * not an
             array of char, because define USE_STATIC_MEMORY is undefined (defined
             in user application). Thus we cannot use bctl-> Buf[bctl-> ri].Data
             here.
            *******************************************************************/
            pbuffer = (char *)((uint32_t)(bctl-> Buf) + (bctl-> pi * bctl-> NBuffer_tsize));
        }

        //~ CPrintf ("free: %08lx\r\n", buffer);

        /***********************************************************************
          maintain buffer counter
        ***********************************************************************/
        bctl-> BuffersInUse--;
    } // if

    /***************************************************************************
     maintain process index
    ***************************************************************************/
    if ( ++bctl-> pi >= bctl-> MaxBuffers )
    {
        /***********************************************************************
         wrap around ring buffer
        ***********************************************************************/
        bctl-> pi = 0;
    } // if

    /***************************************************************************
     was it the last buffer (process index points to receive index)?
    ***************************************************************************/
    if ( bctl-> pi == bctl-> ri )
    {
        /***********************************************************************
         yes, set buffer empty flag
        ***********************************************************************/
        bctl-> pi = BUFFER_EMPTY;
    } // if

    return (0);
}

Variable Documentation

const char* NBufferMessages[]

Initial value:

= {
    "",
#define NBUFFER_NO_ERROR
    "out of memory error"
#define NBUFFER_OUT_OF_MEMORY_ERROR

}