GLAST/LAT > DAQ and FSW > FSW > Doxygen Index > IPBS / V0-0-1

Constituent: pbs     Tag: i845e


Interface   Data Structures   File List   Data Fields   Globals  

FPA.c File Reference

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

#include "IPBS/FPA.h"
#include "IPBS/LI.h"
#include "IPBS/LI.ih"

Include dependency graph for FPA.c:


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...

Functions

static __inline FPA_pcballocate (FPA_fcb *fcb, int offset)
 Basic non-interlocked version of the routine to allocate a packet from the free list.
int FPA_fcb_sizeof ()
 Returns the size of the Fixed Packet Allocator control block.
int FPA_init (FPA_fcb *fcb, FPA_type type, void *buffer, int buf_size, int packet_size, int pcb_offset, FPA_init_cb 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.
int FPA_destroy (FPA_fcb *fcb)
 Releases any resources gathered at initialization time.
void __inline * FPA_get (FPA_fcb *fcb)
 Get or allocate a packet from the free list.
void * FPA_getW (FPA_fcb *fcb)
 Get or allocate a packet from the free list with a indefinite blocking.
void * FPA_getW_toc (FPA_fcb *fcb, const TOC *toc)
 Get or allocate a packet from the free list using the timeout specified by TOC.
int FPA_free (FPA_fcb *fcb, void *packet)
 Returns a previously allocated packet to the free list.

Detailed Description

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

Author:
JJRussell - russell@slac.stanford.edu
   CVS $Id: FPA.c,v 1.1.1.1 2006/02/10 21:45:33 saxton Exp $
   

Function Documentation

FPA_pcb * allocate FPA_fcb fcb,
int  offset
[static]
 

Basic non-interlocked version of the routine to allocate a packet from the free list.

Return values:
NULL,on failure (empty free list)
Pointer to the allocated packet, on success
Parameters:
fcb The FPA handle
offset Byte offset from the node links to the top of the packet.

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 MBA_alloc().

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 laid 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:
The number of outstanding packets
This routine frees, or returns a previously allocated packet to the free list.

void __inline* 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  ) 
 

Get or allocate a packet from the free list with a indefinite blocking.

Parameters:
fcb The handle of the Fixed Packet Allocator
Returns:
If successful, the address of the allocated packet. NULL is returned on error.
This is a blocking allocation, ie if the pool is exhausted, then the routine blocks indefinitely.

void* FPA_getW_toc FPA_fcb fcb,
const TOC toc
 

Get or allocate a packet from the free list using the timeout specified by TOC.

Parameters:
fcb The handle of the Fixed Packet Allocator.
toc The timeout control structute.
Returns:
If successful, the address of the allocated packet. NULL is returned on error or timeout.
This is a blocking allocation, ie if the pool is exhausted, then the routine blocks until a packet becomes available or the timeout period expires.

int FPA_init FPA_fcb fcb,
FPA_type  type,
void *  buffer,
int  buf_size,
int  packet_size,
int  pcb_offset,
FPA_init_cb  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.
type The type of blocking to be used
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.
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_init_cb 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 most 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.


Generated on Fri Feb 10 20:21:16 2006 by  doxygen 1.4.4