---

FPA.c File Reference

Utility for configuring and allocating a pool of Fixed Sized Packets. More...

#include "BBC/FPA.h"
#include "BBC/LLI_protos.h"
#include "BBC/LLI.ih"

Data Structures
struct	_FPA_fcb
	Layouts the control structure for managing the list of free packets. This structure is private to the FPA utility. More...
struct	_FPA_pcb
	Layouts the control structure used by each packet on the free list This structure is private to the FPA utility. More...
Functions
int	FPA_fcb_sizeof ()
	Returns the size of the Fixed Packet Allocator control block. More...
int	FPA_pcb_sizeof ()
	Returns the size of the Packet control block. More...
int	FPA_init (FPA_fcb *fcb, char *buffer, int buf_size, int packet_size, int pcb_offset, FPA_type type, FPA_cb_init init_routine, void *init_parameter)
	Configures a user supplied piece of memory as a collection of fixed size packets which can be allocated and deallocated. More...
int	FPA_destroy (FPA_fcb *fcb)
	Releases any resources gathered at initialization time. More...
void *	FPA_get (FPA_fcb *fcb)
	Get or allocate a packet from the free list. More...
void *	FPA_getW (FPA_fcb *fcb, int timeout)
	Get or allocate a packet from the free list with a blocking. More...
int	FPA_free (FPA_fcb *fcb, void *packet)
	Returns a previously allocated packet to the free list. More...

---

Detailed Description

Utility for configuring and allocating a pool of Fixed Sized Packets.

Author:

JJRussell - russell@slac.stanford.edu

This utility allows one to configure a pool of memory as a collection of fixed sized packets. The allocation and deallocation is interlocked, making it safe to use in a multi-threaded environment.

The behaviour when the pool is exhausted is configurable to be either blocking or non-blocking. If blocking is choose, then the blocking can be in either FIFO or PRIORITY ordering.

A design choice was to hide both the control structure for the pool and the packet management structure. The former is an easy decision, the latter causes some awkward programming at times, but greatly increases modularity. The pain is almost exclusively limited to initialization. This is kind of an experiment to see if this works. If not, it will get changed.

USAGE/EXAMPLE
Here is how one would typically use this facility. Suppose one wished to manage a pool of packets which contained data which was to be read from an external source. Further suppose that each packet was to be have a fixed header describing the data type and that this type never changes.

    FPA_fcb         *fcb;
    int         pcb_size;
    char   *buffer[1000];
    struct MyPacket { int data_type, char buf[46] };

    fcb = malloc (FPA_fcb_sizeofb ());   / * Allocate the control block * /
    FPA_init (fcb,                      / * FPA control block          * /
              buffer,                   / * Memory pool to manage      * /
              sizeof(buffer),           / * Size of the memory pool    * /
              sizeof(struct MyPacket),  / * Size of each packet        * /
              -1,                       / * Place PCB at the bottom    * /
              FPA_K_TYPE_FIFO_BLOCKING, / * Allow FIFO style blocking  * /
              (FPA_cb_init)initializer, / * Initialization routine     * /
              (void *)data_type);       / * Data type of each packet   * /
    .
    .
    .
    while (ptr = isDataReady ())
    {
        packet = FPA_getW (fcb, FPA_K_WTO_WAIT_FOREVER);
        copy (ptr, packet, packet_size);
    }
              
    return;
    }

    / * Callback routine to initialize each packet * /
    void initializer (int data_type,
                      struct MyPacket *packet,
                      int packet_size,
                      int pcb_offset)
    {
        packet.data_type = data_type;
    }

   

---

Function Documentation

int FPA_destroy (  FPA_fcb *    fcb )

Releases any resources gathered at initialization time. Parameters: fcb  The handle of the Fixed Packet Allocator Returns: Status Releases any resources gathered at initialization time. Note that this does not include either releasing the user supplied memory buffer or the control structure itself. Both of those are property of the user and are the responsibility of the user to release them as appropriate.

int FPA_fcb_sizeof (  void    )

Returns the size of the Fixed Packet Allocator control block. Returns: The size, in bytes of a Fixed Packet Allocator control block. This routine is the first step in creating a FPA pool. The user first enquires about the size of the control block and then allocates it either from existing piece of memory or from some other allocator like malloc. This call is for modularity reasons. The user can learn the size of memory needed by the FPA utility to manage a pool of packets without needing to know the details of how it is layed out. This could have also been achieved by having the FPA initialization routine allocate the control block, but this takes away the freedom of the user to control his own allocation and deallocation

int FPA_free (  FPA_fcb *    fcb, void *    packet )

Returns a previously allocated packet to the free list. Parameters: fcb  The handle of the Fixed Packet Allocator. packet  The packet to be freed. Returns: Status. This routine frees, or returns a previously allocated packet to the free list.

void * FPA_get (  FPA_fcb *    fcb )

Get or allocate a packet from the free list. Parameters: fcb  The handle of the Fixed Packet Allocator Returns: If successful, the address of the allocated packet, else NULL if no packets where available. This is a non-blocking allocation. See FPA_getW() for a blocking version. While this call is non-blocking, the allocation is fully interlocked.

void * FPA_getW (  FPA_fcb *    fcb, int    timeout )

Get or allocate a packet from the free list with a blocking. Parameters: fcb  The handle of the Fixed Packet Allocator. timeout  Controls the blocking time. Currently only FPA_K_WTO_NO_WAIT (0) and FPA_K_WTO_WAIT_FOREVER (-1) are supported. Returns: If successful, the address of the allocated packet. If the timeout period expires before a packet becomes available, NULL is returned. This is a blocking allocation, ie if the pool is exhausted, then the routine blocks for the specified time, as determined by the timeout parameter.

int FPA_init (  FPA_fcb *    fcb, char *    buffer, int    buf_size, int    pckt_size, int    pcb_offset, FPA_type    type, FPA_cb_init    init_routine, void *    init_parameter )

Configures a user supplied piece of memory as a collection of fixed size packets which can be allocated and deallocated. Parameters: fcb  The handle of the Fixed Packet Allocator to be initialized. The user is responsible for supplying the memory for the control structure. buffer  A pointer to the user-supplied buffer. This buffer must be 32-bit aligned. The packets will be carved from this memory. buf_size  The size, in bytes, of the user-supplied buffer. packet_size  The size, in bytes, of the packets. This number must be an integral number of 32-bit words. This ensures that all packets will be properly aligned. pcb_offset  Offset, in bytes, to the packet control block. This block is necessary for managing the packet while it is on in the free pool, but is free for the user to do with as he wishes when once the packet has been allocated. This parameter allows the user to control the placement of the control block. This offset is generally specified as 0, in which case the control structure is at the top of the packet, or -1, in which case the links are at the bottom of the packet. The latter case is especially useful if one wishes to initialize the top portion of the packet with a static header of some sort, while the bottom of the packet contains data to be filled in later when the packet is allocated. type  The type of blocking to be used init_routine  The address of the entry point of a user supplied routine which is called as each new packet is placed on the free list. This parameter may be NULL if no initialization routine is needed. It is the user's responsibility not so use the control area. This is possible, since the user knows the size and controls its placement in the packet. Set FPA_cb_init for the definition of the callback signature. init_parameter  A user supplied parameter which is passed to the callback routine. This routine is responsible for configuring a user-supplied piece of memory for use as a source of fixed sized packets. As each packet is placed on the free list, an optionally supplied user callback routine allows user initialization of the packets. Various options allow the user to place where the control structure lives within the packet and determine the blocking style. The must usual choice for the placement of the packet control structure is at the beginning pcb_offset = 0, or at the end pcb_offset = -1, although the user is allowed to specify any offset, provided it is within the packet. The usual blocking style is FPA_K_TYPE_FIFO_BLOCKING. Warning: Note that while this Packet Control Block offset pcb_offset is specified in bytes it must be 4 byte aligned.

int FPA_pcb_sizeof (  void    )

Returns the size of the Packet control block. Returns: The size, in bytes, of the Packet control block. This value sets the minimum size of a packet which can be managed by the Fixed Packet Allocator. It is also useful when the user wishes to pre-initialize the packets before use. When the packet is on the internal free list, the space allocated to the control block will be overwritten. By knowing the size and having the ability to position the control block anywhere within the packet, the user should be able to avoid contention.

---