\hypertarget{FPA_8h}{ \section{FPA.h File Reference} \label{FPA_8h}\index{FPA.h@{FPA.h}} } Fixed Packet Allocator, memory manager that configures and manages a pool of fixed sized packets. {\tt \#include \char`\"{}IPBS/L\_\-pubdefs.h\char`\"{}}\par {\tt \#include \char`\"{}IPBS/LI\_\-type.h\char`\"{}}\par {\tt \#include \char`\"{}IPBS/LI\_\-comdefs.h\char`\"{}}\par {\tt \#include \char`\"{}IPBS/TOC\_\-comdefs.h\char`\"{}}\par Include dependency graph for FPA.h:\begin{figure}[H] \begin{center} \leavevmode \includegraphics[width=259pt]{FPA_8h__incl} \end{center} \end{figure} This graph shows which files directly or indirectly include this file:\begin{figure}[H] \begin{center} \leavevmode \includegraphics[width=87pt]{FPA_8h__dep__incl} \end{center} \end{figure} \subsection*{Data Structures} \begin{CompactItemize} \item struct \hyperlink{struct__FPA__pcb}{\_\-FPA\_\-pcb} \begin{CompactList}\small\item\em Layouts the control structure used by each packet while it is on the free list. \item\end{CompactList}\end{CompactItemize} \subsection*{Defines} \begin{CompactItemize} \item \hypertarget{FPA_8h_a0}{ \#define \hyperlink{FPA_8h_a0}{FPA\_\-K\_\-PCB\_\-AT\_\-EOP}~(-1)} \label{FPA_8h_a0} \begin{CompactList}\small\item\em Convenience symbol indicating that the packet control block, the {\em FORK\_\-pcb\/}, should be placed at the end of the packet (EOP). \item\end{CompactList}\end{CompactItemize} \subsection*{Typedefs} \begin{CompactItemize} \item typedef enum \hyperlink{FPA_8h_a19}{\_\-FPA\_\-type} \hyperlink{FPA_8h_a1}{FPA\_\-type} \begin{CompactList}\small\item\em Typedef for enum \_\-FPA\_\-type. \item\end{CompactList}\item typedef \hyperlink{struct__FPA__pcb}{\_\-FPA\_\-pcb} \hyperlink{FPA_8h_a2}{FPA\_\-pcb} \begin{CompactList}\small\item\em Typedef for struct \hyperlink{struct__FPA__pcb}{\_\-FPA\_\-pcb}. \item\end{CompactList}\item typedef void($\ast$ \hyperlink{FPA_8h_a3}{FPA\_\-init\_\-cb} )(void $\ast$parameter, void $\ast$packet, int packet\_\-size, int pcb\_\-offset) \begin{CompactList}\small\item\em Function signature for the packet initialization callback routine. \item\end{CompactList}\item \hypertarget{FPA_8h_a4}{ typedef \hyperlink{struct__FPA__fcb}{\_\-FPA\_\-fcb} \hyperlink{FPA_8h_a4}{FPA\_\-fcb}} \label{FPA_8h_a4} \begin{CompactList}\small\item\em Typedef for struct \hyperlink{struct__FPA__fcb}{\_\-FPA\_\-fcb}. \item\end{CompactList}\end{CompactItemize} \subsection*{Enumerations} \begin{CompactItemize} \item enum \hyperlink{FPA_8h_a19}{\_\-FPA\_\-type} \{ \par \hyperlink{FPA_8h_a19a5}{FPA\_\-K\_\-TYPE\_\-LOCKING\_\-ONLY} = RW\_\-K\_\-TYPE\_\-LOCKING\_\-ONLY, \par \hyperlink{FPA_8h_a19a6}{FPA\_\-K\_\-TYPE\_\-PENDING} = RW\_\-K\_\-TYPE\_\-PENDING, \par \hyperlink{FPA_8h_a19a7}{FPA\_\-K\_\-TYPE\_\-PENDING\_\-WTO} = RW\_\-K\_\-TYPE\_\-PENDING\_\-WTO, \par \hyperlink{FPA_8h_a19a8}{FPA\_\-K\_\-TYPE\_\-PENDING\_\-FIFO} = RW\_\-K\_\-TYPE\_\-PENDING\_\-FIFO, \par \hyperlink{FPA_8h_a19a9}{FPA\_\-K\_\-TYPE\_\-PENDING\_\-FIFO\_\-WTO} = RW\_\-K\_\-TYPE\_\-PENDING\_\-FIFO\_\-WTO, \par \hyperlink{FPA_8h_a19a10}{FPA\_\-K\_\-TYPE\_\-PENDING\_\-PRIORITY} = RW\_\-K\_\-TYPE\_\-PENDING\_\-PRIORITY, \par \hyperlink{FPA_8h_a19a11}{FPA\_\-K\_\-TYPE\_\-PENDING\_\-PRIORITY\_\-WTO} = RW\_\-K\_\-TYPE\_\-PENDING\_\-PRIORITY\_\-WTO \} \begin{CompactList}\small\item\em Enumerates the FPA types available. \item\end{CompactList}\end{CompactItemize} \subsection*{Functions} \begin{CompactItemize} \item int \hyperlink{FPA_8h_a12}{FPA\_\-fcb\_\-sizeof} (void) \begin{CompactList}\small\item\em Returns the size of the Fixed Packet Allocator control block. \item\end{CompactList}\item int \hyperlink{FPA_8h_a13}{FPA\_\-init} (\hyperlink{struct__FPA__fcb}{FPA\_\-fcb} $\ast$fcb, \hyperlink{FPA_8h_a1}{FPA\_\-type} blocking, void $\ast$buffer, int buf\_\-size, int packet\_\-size, int pcb\_\-offset, \hyperlink{FPA_8h_a3}{FPA\_\-init\_\-cb} init\_\-routine, void $\ast$init\_\-parameter) \begin{CompactList}\small\item\em Configures a user supplied piece of memory as a collection of fixed size packets which can be allocated and deallocated. \item\end{CompactList}\item void $\ast$ \hyperlink{FPA_8h_a14}{FPA\_\-get} (\hyperlink{struct__FPA__fcb}{FPA\_\-fcb} $\ast$fcb) \begin{CompactList}\small\item\em Get or allocate a packet from the free list. \item\end{CompactList}\item void $\ast$ \hyperlink{FPA_8h_a15}{FPA\_\-get\-W} (\hyperlink{struct__FPA__fcb}{FPA\_\-fcb} $\ast$fcb) \begin{CompactList}\small\item\em Get or allocate a packet from the free list with a indefinite blocking. \item\end{CompactList}\item void $\ast$ \hyperlink{FPA_8h_a16}{FPA\_\-get\-W\_\-toc} (\hyperlink{struct__FPA__fcb}{FPA\_\-fcb} $\ast$fcb, const \hyperlink{struct__TOC}{TOC} $\ast$toc) \begin{CompactList}\small\item\em Get or allocate a packet from the free list using the timeout specified by TOC. \item\end{CompactList}\item int \hyperlink{FPA_8h_a17}{FPA\_\-free} (\hyperlink{struct__FPA__fcb}{FPA\_\-fcb} $\ast$fcb, void $\ast$packet) \begin{CompactList}\small\item\em Returns a previously allocated packet to the free list. \item\end{CompactList}\item int \hyperlink{FPA_8h_a18}{FPA\_\-destroy} (\hyperlink{struct__FPA__fcb}{FPA\_\-fcb} $\ast$fcb) \begin{CompactList}\small\item\em Releases any resources gathered at initialization time. \item\end{CompactList}\end{CompactItemize} \subsection{Detailed Description} Fixed Packet Allocator, memory manager that configures and manages a pool of fixed sized packets. \begin{Desc} \item[Author:]JJRussell - \href{mailto:russell@slac.stanford.edu}{\tt russell@slac.stanford.edu}\end{Desc} \footnotesize\begin{verbatim} CVS $Id: FPA.h,v 1.1.1.1 2006/02/10 21:45:35 saxton Exp $ \end{verbatim} \normalsize {\bf SYNOPSIS} \par 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 chosen, then the blocking can be in either FIFO or PRIORITY ordering. This is relevant only when multiple allocators use the pool. An initial 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 caused awkward programming at times, but would increase modularity. The pain is almost exclusively limited to initialization. It was an experiment to see if this worked, but given the rather limited exposure (the packet management structure is currently only LI\_\-node structure, a single 4-byte word), it was decided to keep the FPA control structure hidden, but expose the FPA packet control structure. {\bf USAGE/EXAMPLE} \par 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 constrained to be the first word of the data packet describing the data type and that this type never changes. This makes the {\em data\_\-type\/} field a candidate for one-time initialization. Since the {\em initializer\/} routine writes the {\em data\_\-type\/} field, the packet control block used to manage the packet when it is on the FPA freelist must not be allowed to occupy the first word. Since, presumably, the body of the structure is filled with fresh data each time, the packet control block can be located anywhere within that section. The choice in the example is to locate it as the first word of the data field. \footnotesize\begin{verbatim} struct _MyPacket { / * Packet consists of a header ... * / int data_type; / * Header gives the data type * / union _MyData / * and a body * / { FPA_pcb pcb; / * Management when packet is not allocated * / char buf[60]; // * Holds the data when allocated * / } body; }; FPA_fcb *fcb; char *buffer[1000]; fcb = MBA_alloc (FPA_fcb_sizeof ());/ * 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 * / OFFSET_OF(_struct _MyPacket, body.pcb), / * Byte offset of PCB * / FPA_K_TYPE_BLOCKING, , / * Blocking, single allocator * / (FPA_init_cb)initializer, / * Initialization routine * / (void *)data_type); / * Data type of each packet * / . . . while (ptr = isDataReady ()) { struct _MyPacket *packet = FPA_getW (fcb); copy (packet->body.buf, ptr, sizeof (packet->body.buf)); } 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; } \end{verbatim} \normalsize \subsection{Typedef Documentation} \hypertarget{FPA_8h_a3}{ \index{FPA.h@{FPA.h}!FPA_init_cb@{FPA\_\-init\_\-cb}} \index{FPA_init_cb@{FPA\_\-init\_\-cb}!FPA.h@{FPA.h}} \subsubsection[FPA\_\-init\_\-cb]{\setlength{\rightskip}{0pt plus 5cm}\hyperlink{FPA_8h_a3}{FPA\_\-init\_\-cb}}} \label{FPA_8h_a3} Function signature for the packet initialization callback routine. \begin{Desc} \item[Parameters:] \begin{description} \item[{\em parameter}]A user provided context parameter \item[{\em packet}]The packet being initialized \item[{\em packet\_\-size}]The size, in bytes, of the packet. \item[{\em pcb\_\-offset}]The offset, in bytes, to the packets management links\end{description} \end{Desc} The callback routine must take care not to write in the area reserved for the Packet Control Block. The last parameter of the callback {\em pcb\_\-offset\/} and the routine FPA\_\-pcb\_\-sizeof(), allowing the user to determine exactly what memory the packet control block occupies so that this memory can be avoided.\hypertarget{FPA_8h_a2}{ \index{FPA.h@{FPA.h}!FPA_pcb@{FPA\_\-pcb}} \index{FPA_pcb@{FPA\_\-pcb}!FPA.h@{FPA.h}} \subsubsection[FPA\_\-pcb]{\setlength{\rightskip}{0pt plus 5cm}\hyperlink{struct__FPA__pcb}{FPA\_\-pcb}}} \label{FPA_8h_a2} Typedef for struct \hyperlink{struct__FPA__pcb}{\_\-FPA\_\-pcb}. The FPA routines require some storage to manage each packet on the free list. This memory is only used while on the free list and, therefore is available to the user after it a packet has been allocated. Every attempt was made to keep this overhead as small as possible. Currently, this requires only a single 4-byte word. \begin{Desc} \item[Warning:]This location is not available to be written by the initialization routine. Technically, the packet's state during hte initialization routine is 'on the free list', so it is unavailable. The FPA creation routine {\em FPA\_\-create()\/} gives the user the flexibility of locating the FORK\_\-pcb anywhere within the packet.\end{Desc} \hypertarget{FPA_8h_a1}{ \index{FPA.h@{FPA.h}!FPA_type@{FPA\_\-type}} \index{FPA_type@{FPA\_\-type}!FPA.h@{FPA.h}} \subsubsection[FPA\_\-type]{\setlength{\rightskip}{0pt plus 5cm}\hyperlink{FPA_8h_a1}{FPA\_\-type}}} \label{FPA_8h_a1} Typedef for enum \_\-FPA\_\-type. This determines how the \hyperlink{FPA_8h_a15}{FPA\_\-get\-W()} and \hyperlink{FPA_8h_a16}{FPA\_\-get\-W\_\-toc()} calls will behave when an allocation is attempted on an empty pool. One can specify non-blocking or two types of blocking, \begin{itemize} \item FIFO blocking order, first come, first serve\item PRIORITY blocking order, by task priority\end{itemize} If a non-blocking type is requested only \hyperlink{FPA_8h_a14}{FPA\_\-get()} routine can be called. \begin{Desc} \item[Note:]While the current implementation does not make use of whether the one specifies that timeouts be supported, future implementations may, so it is requested that one specifies whether timeouts are to be used or not.\end{Desc} \subsection{Enumeration Type Documentation} \hypertarget{FPA_8h_a19}{ \index{FPA.h@{FPA.h}!_FPA_type@{\_\-FPA\_\-type}} \index{_FPA_type@{\_\-FPA\_\-type}!FPA.h@{FPA.h}} \subsubsection[\_\-FPA\_\-type]{\setlength{\rightskip}{0pt plus 5cm}enum \hyperlink{FPA_8h_a19}{\_\-FPA\_\-type}}} \label{FPA_8h_a19} Enumerates the FPA types available. \begin{Desc} \item[Enumerator: ]\par \begin{description} \index{FPA_K_TYPE_LOCKING_ONLY@{FPA\_\-K\_\-TYPE\_\-LOCKING\_\-ONLY}!FPA.h@{FPA.h}}\index{FPA.h@{FPA.h}!FPA_K_TYPE_LOCKING_ONLY@{FPA\_\-K\_\-TYPE\_\-LOCKING\_\-ONLY}}\item[{\em \hypertarget{FPA_8h_a19a5}{ FPA\_\-K\_\-TYPE\_\-LOCKING\_\-ONLY} \label{FPA_8h_a19a5} }]Locking mechanism only, no pending mechanism available \index{FPA_K_TYPE_PENDING@{FPA\_\-K\_\-TYPE\_\-PENDING}!FPA.h@{FPA.h}}\index{FPA.h@{FPA.h}!FPA_K_TYPE_PENDING@{FPA\_\-K\_\-TYPE\_\-PENDING}}\item[{\em \hypertarget{FPA_8h_a19a6}{ FPA\_\-K\_\-TYPE\_\-PENDING} \label{FPA_8h_a19a6} }]Pending mechanism available, single pender/reader only \index{FPA_K_TYPE_PENDING_WTO@{FPA\_\-K\_\-TYPE\_\-PENDING\_\-WTO}!FPA.h@{FPA.h}}\index{FPA.h@{FPA.h}!FPA_K_TYPE_PENDING_WTO@{FPA\_\-K\_\-TYPE\_\-PENDING\_\-WTO}}\item[{\em \hypertarget{FPA_8h_a19a7}{ FPA\_\-K\_\-TYPE\_\-PENDING\_\-WTO} \label{FPA_8h_a19a7} }]Pending with timeouts, single pender/reader only \index{FPA_K_TYPE_PENDING_FIFO@{FPA\_\-K\_\-TYPE\_\-PENDING\_\-FIFO}!FPA.h@{FPA.h}}\index{FPA.h@{FPA.h}!FPA_K_TYPE_PENDING_FIFO@{FPA\_\-K\_\-TYPE\_\-PENDING\_\-FIFO}}\item[{\em \hypertarget{FPA_8h_a19a8}{ FPA\_\-K\_\-TYPE\_\-PENDING\_\-FIFO} \label{FPA_8h_a19a8} }]Use FIFO pending order \index{FPA_K_TYPE_PENDING_FIFO_WTO@{FPA\_\-K\_\-TYPE\_\-PENDING\_\-FIFO\_\-WTO}!FPA.h@{FPA.h}}\index{FPA.h@{FPA.h}!FPA_K_TYPE_PENDING_FIFO_WTO@{FPA\_\-K\_\-TYPE\_\-PENDING\_\-FIFO\_\-WTO}}\item[{\em \hypertarget{FPA_8h_a19a9}{ FPA\_\-K\_\-TYPE\_\-PENDING\_\-FIFO\_\-WTO} \label{FPA_8h_a19a9} }]Use FIFO pending order with timeouts available \index{FPA_K_TYPE_PENDING_PRIORITY@{FPA\_\-K\_\-TYPE\_\-PENDING\_\-PRIORITY}!FPA.h@{FPA.h}}\index{FPA.h@{FPA.h}!FPA_K_TYPE_PENDING_PRIORITY@{FPA\_\-K\_\-TYPE\_\-PENDING\_\-PRIORITY}}\item[{\em \hypertarget{FPA_8h_a19a10}{ FPA\_\-K\_\-TYPE\_\-PENDING\_\-PRIORITY} \label{FPA_8h_a19a10} }]Use PRIORITY pending order \index{FPA_K_TYPE_PENDING_PRIORITY_WTO@{FPA\_\-K\_\-TYPE\_\-PENDING\_\-PRIORITY\_\-WTO}!FPA.h@{FPA.h}}\index{FPA.h@{FPA.h}!FPA_K_TYPE_PENDING_PRIORITY_WTO@{FPA\_\-K\_\-TYPE\_\-PENDING\_\-PRIORITY\_\-WTO}}\item[{\em \hypertarget{FPA_8h_a19a11}{ FPA\_\-K\_\-TYPE\_\-PENDING\_\-PRIORITY\_\-WTO} \label{FPA_8h_a19a11} }]Use PRIORITY pending order with timeouts available \end{description} \end{Desc} \subsection{Function Documentation} \hypertarget{FPA_8h_a18}{ \index{FPA.h@{FPA.h}!FPA_destroy@{FPA\_\-destroy}} \index{FPA_destroy@{FPA\_\-destroy}!FPA.h@{FPA.h}} \subsubsection[FPA\_\-destroy]{\setlength{\rightskip}{0pt plus 5cm}int FPA\_\-destroy (\hyperlink{struct__FPA__fcb}{FPA\_\-fcb} $\ast$ {\em fcb})}} \label{FPA_8h_a18} Releases any resources gathered at initialization time. \begin{Desc} \item[Parameters:] \begin{description} \item[{\em fcb}]The handle of the Fixed Packet Allocator \end{description} \end{Desc} \begin{Desc} \item[Returns:]Status\end{Desc} 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.\hypertarget{FPA_8h_a12}{ \index{FPA.h@{FPA.h}!FPA_fcb_sizeof@{FPA\_\-fcb\_\-sizeof}} \index{FPA_fcb_sizeof@{FPA\_\-fcb\_\-sizeof}!FPA.h@{FPA.h}} \subsubsection[FPA\_\-fcb\_\-sizeof]{\setlength{\rightskip}{0pt plus 5cm}int FPA\_\-fcb\_\-sizeof (void)}} \label{FPA_8h_a12} Returns the size of the Fixed Packet Allocator control block. \begin{Desc} \item[Returns:]The size, in bytes of a Fixed Packet Allocator control block.\end{Desc} 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 {\em \hyperlink{MBA_8h_a3}{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\hypertarget{FPA_8h_a17}{ \index{FPA.h@{FPA.h}!FPA_free@{FPA\_\-free}} \index{FPA_free@{FPA\_\-free}!FPA.h@{FPA.h}} \subsubsection[FPA\_\-free]{\setlength{\rightskip}{0pt plus 5cm}int FPA\_\-free (\hyperlink{struct__FPA__fcb}{FPA\_\-fcb} $\ast$ {\em fcb}, void $\ast$ {\em packet})}} \label{FPA_8h_a17} Returns a previously allocated packet to the free list. \begin{Desc} \item[Parameters:] \begin{description} \item[{\em fcb}]The handle of the Fixed Packet Allocator. \item[{\em packet}]The packet to be freed. \end{description} \end{Desc} \begin{Desc} \item[Returns:]The number of outstanding packets\end{Desc} This routine frees, or returns a previously allocated packet to the free list.\hypertarget{FPA_8h_a14}{ \index{FPA.h@{FPA.h}!FPA_get@{FPA\_\-get}} \index{FPA_get@{FPA\_\-get}!FPA.h@{FPA.h}} \subsubsection[FPA\_\-get]{\setlength{\rightskip}{0pt plus 5cm}void $\ast$ FPA\_\-get (\hyperlink{struct__FPA__fcb}{FPA\_\-fcb} $\ast$ {\em fcb})}} \label{FPA_8h_a14} Get or allocate a packet from the free list. \begin{Desc} \item[Parameters:] \begin{description} \item[{\em fcb}]The handle of the Fixed Packet Allocator \end{description} \end{Desc} \begin{Desc} \item[Returns:]If successful, the address of the allocated packet, else NULL if no packets where available.\end{Desc} This is a non-blocking allocation. See \hyperlink{FPA_8h_a15}{FPA\_\-get\-W()} for a blocking version. While this call is non-blocking, the allocation is fully interlocked.\hypertarget{FPA_8h_a15}{ \index{FPA.h@{FPA.h}!FPA_getW@{FPA\_\-getW}} \index{FPA_getW@{FPA\_\-getW}!FPA.h@{FPA.h}} \subsubsection[FPA\_\-getW]{\setlength{\rightskip}{0pt plus 5cm}void $\ast$ FPA\_\-get\-W (\hyperlink{struct__FPA__fcb}{FPA\_\-fcb} $\ast$ {\em fcb})}} \label{FPA_8h_a15} Get or allocate a packet from the free list with a indefinite blocking. \begin{Desc} \item[Parameters:] \begin{description} \item[{\em fcb}]The handle of the Fixed Packet Allocator \end{description} \end{Desc} \begin{Desc} \item[Returns:]If successful, the address of the allocated packet. NULL is returned on error.\end{Desc} This is a blocking allocation, ie if the pool is exhausted, then the routine blocks indefinitely.\hypertarget{FPA_8h_a16}{ \index{FPA.h@{FPA.h}!FPA_getW_toc@{FPA\_\-getW\_\-toc}} \index{FPA_getW_toc@{FPA\_\-getW\_\-toc}!FPA.h@{FPA.h}} \subsubsection[FPA\_\-getW\_\-toc]{\setlength{\rightskip}{0pt plus 5cm}void $\ast$ FPA\_\-get\-W\_\-toc (\hyperlink{struct__FPA__fcb}{FPA\_\-fcb} $\ast$ {\em fcb}, const \hyperlink{struct__TOC}{TOC} $\ast$ {\em toc})}} \label{FPA_8h_a16} Get or allocate a packet from the free list using the timeout specified by TOC. \begin{Desc} \item[Parameters:] \begin{description} \item[{\em fcb}]The handle of the Fixed Packet Allocator. \item[{\em toc}]The timeout control structute. \end{description} \end{Desc} \begin{Desc} \item[Returns:]If successful, the address of the allocated packet. NULL is returned on error or timeout.\end{Desc} 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.\hypertarget{FPA_8h_a13}{ \index{FPA.h@{FPA.h}!FPA_init@{FPA\_\-init}} \index{FPA_init@{FPA\_\-init}!FPA.h@{FPA.h}} \subsubsection[FPA\_\-init]{\setlength{\rightskip}{0pt plus 5cm}int FPA\_\-init (\hyperlink{struct__FPA__fcb}{FPA\_\-fcb} $\ast$ {\em fcb}, \hyperlink{FPA_8h_a1}{FPA\_\-type} {\em type}, void $\ast$ {\em buffer}, int {\em buf\_\-size}, int {\em packet\_\-size}, int {\em pcb\_\-offset}, \hyperlink{FPA_8h_a3}{FPA\_\-init\_\-cb} {\em init\_\-routine}, void $\ast$ {\em init\_\-parameter})}} \label{FPA_8h_a13} Configures a user supplied piece of memory as a collection of fixed size packets which can be allocated and deallocated. \begin{Desc} \item[Parameters:] \begin{description} \item[{\em fcb}]The handle of the Fixed Packet Allocator to be initialized. The user is responsible for supplying the memory for the control structure.\item[{\em type}]The type of blocking to be used\item[{\em buffer}]A pointer to the user-supplied buffer. This buffer must be 32-bit aligned. The packets will be carved from this memory.\item[{\em buf\_\-size}]The size, in bytes, of the user-supplied buffer.\item[{\em 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.\item[{\em 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.\item[{\em 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.\item[{\em init\_\-parameter}]A user supplied parameter which is passed to the callback routine.\end{description} \end{Desc} 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 {\em pcb\_\-offset\/} = 0, or at the end {\em 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. \begin{Desc} \item[Warning:]Note that while this Packet Control Block offset {\em pcb\_\-offset\/} is specified in bytes it {\em must\/} {\em be\/} 4 byte aligned.\end{Desc}