\hypertarget{FPA_8h}{ \section{FPA.h File Reference} \label{FPA_8h}\index{FPA.h@{FPA.h}} } Utility for configuring and allocating a pool of Fixed Sized Packets. {\tt \#include \char`\"{}BBC/LLI\_\-type.h\char`\"{}}\par \subsection*{Defines} \begin{CompactItemize} \item \hypertarget{FPA_8h_a0}{ \index{FPA_K_WTO_NO_WAIT@{FPA\_\-K\_\-WTO\_\-NO\_\-WAIT}!FPA.h@{FPA.h}}\index{FPA.h@{FPA.h}!FPA_K_WTO_NO_WAIT@{FPA\_\-K\_\-WTO\_\-NO\_\-WAIT}} \#define \hyperlink{FPA_8h_a0}{FPA\_\-K\_\-WTO\_\-NO\_\-WAIT}\ (0)} \label{FPA_8h_a0} \begin{CompactList}\small\item\em Timeout = 0, ie do not wait.\item\end{CompactList}\item \hypertarget{FPA_8h_a1}{ \index{FPA_K_WTO_FOREVER@{FPA\_\-K\_\-WTO\_\-FOREVER}!FPA.h@{FPA.h}}\index{FPA.h@{FPA.h}!FPA_K_WTO_FOREVER@{FPA\_\-K\_\-WTO\_\-FOREVER}} \#define \hyperlink{FPA_8h_a1}{FPA\_\-K\_\-WTO\_\-FOREVER}\ (-1)} \label{FPA_8h_a1} \begin{CompactList}\small\item\em Wait forever.\item\end{CompactList}\end{CompactItemize} \subsection*{Typedefs} \begin{CompactItemize} \item \hypertarget{FPA_8h_a2}{ \index{FPA_type@{FPA\_\-type}!FPA.h@{FPA.h}}\index{FPA.h@{FPA.h}!FPA_type@{FPA\_\-type}} typedef enum \hyperlink{FPA_8h_a16}{\_\-FPA\_\-type} \hyperlink{FPA_8h_a2}{FPA\_\-type}} \label{FPA_8h_a2} \begin{CompactList}\small\item\em Typedef of the enumeration \_\-FPA\_\-type.\item\end{CompactList}\item typedef void($\ast$ \hyperlink{FPA_8h_a3}{FPA\_\-cb\_\-init} )(void $\ast$parameter, void $\ast$packet, int packet\_\-size, int pcb\_\-offset) \begin{CompactList}\small\item\em Initialization Call back signature.\item\end{CompactList}\item \hypertarget{FPA_8h_a4}{ \index{FPA_fcb@{FPA\_\-fcb}!FPA.h@{FPA.h}}\index{FPA.h@{FPA.h}!FPA_fcb@{FPA\_\-fcb}} 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}\item \hypertarget{FPA_8h_a5}{ \index{FPA_pcb@{FPA\_\-pcb}!FPA.h@{FPA.h}}\index{FPA.h@{FPA.h}!FPA_pcb@{FPA\_\-pcb}} typedef \hyperlink{struct__FPA__pcb}{\_\-FPA\_\-pcb} \hyperlink{FPA_8h_a5}{FPA\_\-pcb}} \label{FPA_8h_a5} \begin{CompactList}\small\item\em Typedef for struct \hyperlink{struct__FPA__pcb}{\_\-FPA\_\-pcb}.\item\end{CompactList}\end{CompactItemize} \subsection*{Enumerations} \begin{CompactItemize} \item enum \hyperlink{FPA_8h_a16}{\_\-FPA\_\-type} \{ \hyperlink{FPA_8h_a16a6}{FPA\_\-K\_\-TYPE\_\-NON\_\-BLOCKING} = LLI\_\-K\_\-TYPE\_\-NON\_\-BLOCKING, \hyperlink{FPA_8h_a16a7}{FPA\_\-K\_\-TYPE\_\-FIFO\_\-BLOCKING} = LLI\_\-K\_\-TYPE\_\-FIFO\_\-BLOCKING, \hyperlink{FPA_8h_a16a8}{FPA\_\-K\_\-TYPE\_\-PRIORITY\_\-BLOCKING} = LLI\_\-K\_\-TYPE\_\-PRIORITY\_\-BLOCKING \} \begin{CompactList}\small\item\em The type of blocking to use when an allocation is attempted on an empty pool.\item\end{CompactList}\end{CompactItemize} \subsection*{Functions} \begin{CompactItemize} \item int \hyperlink{FPA_8h_a9}{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_a10}{FPA\_\-pcb\_\-sizeof} (void) \begin{CompactList}\small\item\em Returns the size of the Packet control block.\item\end{CompactList}\item int \hyperlink{FPA_8h_a11}{FPA\_\-init} (\hyperlink{FPA_8h_a4}{FPA\_\-fcb} $\ast$fcb, char $\ast$buffer, int buf\_\-size, int packet\_\-size, int pcb\_\-offset, \hyperlink{FPA_8h_a2}{FPA\_\-type} blocking, \hyperlink{FPA_8h_a3}{FPA\_\-cb\_\-init} 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_a12}{FPA\_\-get} (\hyperlink{FPA_8h_a4}{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_a13}{FPA\_\-get\-W} (\hyperlink{FPA_8h_a4}{FPA\_\-fcb} $\ast$fcb, int timeout) \begin{CompactList}\small\item\em Get or allocate a packet from the free list with a blocking.\item\end{CompactList}\item int \hyperlink{FPA_8h_a14}{FPA\_\-free} (\hyperlink{FPA_8h_a4}{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_a15}{FPA\_\-destroy} (\hyperlink{FPA_8h_a4}{FPA\_\-fcb} $\ast$fcb) \begin{CompactList}\small\item\em Releases any resources gathered at initialization time.\item\end{CompactList}\end{CompactItemize} \subsection{Detailed Description} Utility for configuring and allocating a pool of Fixed Sized Packets. \begin{Desc} \item[Author: ]\par JJRussell - \href{mailto:russell@slac.stanford.edu}{\tt russell@slac.stanford.edu}\end{Desc} \subsection{Typedef Documentation} \hypertarget{FPA_8h_a3}{ \index{FPA.h@{FPA.h}!FPA_cb_init@{FPA\_\-cb\_\-init}} \index{FPA_cb_init@{FPA\_\-cb\_\-init}!FPA.h@{FPA.h}} \subsubsection[FPA\_\-cb\_\-init]{\setlength{\rightskip}{0pt plus 5cm}FPA\_\-cb\_\-init}} \label{FPA_8h_a3} Initialization Call back signature. The initialization callback signature is \par \par \footnotesize\begin{verbatim} void (*initialize)(void *usr_parameter, void *packet, int packet_size, int pcb_offset) where usr_parameter: A user parameter passed transparently to the callback packet: The packet to initialize packet_size: The size of the packet pcb_offset: Offset, in bytes to the Packet Control Block \end{verbatim}\normalsize 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 \hyperlink{FPA_8h_a10}{FPA\_\-pcb\_\-sizeof}(), all the user to determine exactly what memory the packet control block occupies so that this memory can be avoided. \subsection{Enumeration Type Documentation} \hypertarget{FPA_8h_a16}{ \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 \_\-FPA\_\-type}} \label{FPA_8h_a16} The type of blocking to use when an allocation is attempted on an empty pool. This determines how the \hyperlink{FPA_8h_a13}{FPA\_\-get\-W}() call will behave when an allocation is attempted on an empty pool. One can specify non-blocking or two types of blocking, either blocking in FIFO order or PRIORITY order. If a non- blocking type is requested, common practice would be to use the simpler \hyperlink{FPA_8h_a12}{FPA\_\-get}() routine, since it never waits. \begin{Desc} \item[Enumeration values:]\par \begin{description} \index{FPA_K_TYPE_NON_BLOCKING@{FPA\_\-K\_\-TYPE\_\-NON\_\-BLOCKING}!FPA.h@{FPA.h}}\index{FPA.h@{FPA.h}!FPA_K_TYPE_NON_BLOCKING@{FPA\_\-K\_\-TYPE\_\-NON\_\-BLOCKING}}\item[{\em \hypertarget{FPA_8h_a16a6}{ {\em FPA\_\-K\_\-TYPE\_\-NON\_\-BLOCKING}} \label{FPA_8h_a16a6} }]No Blocking when the pool is exhausted \index{FPA_K_TYPE_FIFO_BLOCKING@{FPA\_\-K\_\-TYPE\_\-FIFO\_\-BLOCKING}!FPA.h@{FPA.h}}\index{FPA.h@{FPA.h}!FPA_K_TYPE_FIFO_BLOCKING@{FPA\_\-K\_\-TYPE\_\-FIFO\_\-BLOCKING}}\item[{\em \hypertarget{FPA_8h_a16a7}{ {\em FPA\_\-K\_\-TYPE\_\-FIFO\_\-BLOCKING}} \label{FPA_8h_a16a7} }]FIFO Blocking when the pool is exhausted \index{FPA_K_TYPE_PRIORITY_BLOCKING@{FPA\_\-K\_\-TYPE\_\-PRIORITY\_\-BLOCKING}!FPA.h@{FPA.h}}\index{FPA.h@{FPA.h}!FPA_K_TYPE_PRIORITY_BLOCKING@{FPA\_\-K\_\-TYPE\_\-PRIORITY\_\-BLOCKING}}\item[{\em \hypertarget{FPA_8h_a16a8}{ {\em FPA\_\-K\_\-TYPE\_\-PRIORITY\_\-BLOCKING}} \label{FPA_8h_a16a8} }]PRIORITY blocking when the pool is exhausted \end{description} \end{Desc} \subsection{Function Documentation} \hypertarget{FPA_8h_a15}{ \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{FPA_8h_a4}{FPA\_\-fcb} $\ast$ {\em fcb})}} \label{FPA_8h_a15} Releases any resources gathered at initialization time. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em fcb}]The handle of the Fixed Packet Allocator \end{description} \end{Desc} \begin{Desc} \item[Returns: ]\par 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_a9}{ \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_a9} Returns the size of the Fixed Packet Allocator control block. \begin{Desc} \item[Returns: ]\par 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 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 \hypertarget{FPA_8h_a14}{ \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{FPA_8h_a4}{FPA\_\-fcb} $\ast$ {\em fcb}, void $\ast$ {\em packet})}} \label{FPA_8h_a14} Returns a previously allocated packet to the free list. \begin{Desc} \item[Parameters: ]\par \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: ]\par Status.\end{Desc} This routine frees, or returns a previously allocated packet to the free list. \hypertarget{FPA_8h_a12}{ \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{FPA_8h_a4}{FPA\_\-fcb} $\ast$ {\em fcb})}} \label{FPA_8h_a12} Get or allocate a packet from the free list. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em fcb}]The handle of the Fixed Packet Allocator \end{description} \end{Desc} \begin{Desc} \item[Returns: ]\par 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_a13}{FPA\_\-get\-W}() for a blocking version. While this call is non-blocking, the allocation is fully interlocked. \hypertarget{FPA_8h_a13}{ \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{FPA_8h_a4}{FPA\_\-fcb} $\ast$ {\em fcb}, int {\em timeout})}} \label{FPA_8h_a13} Get or allocate a packet from the free list with a blocking. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em fcb}]The handle of the Fixed Packet Allocator. \item[{\em timeout}]Controls the blocking time. Currently only FPA\_\-K\_\-WTO\_\-NO\_\-WAIT (0) and FPA\_\-K\_\-WTO\_\-WAIT\_\-FOREVER (-1) are supported. \end{description} \end{Desc} \begin{Desc} \item[Returns: ]\par If successful, the address of the allocated packet. If the timeout period expires before a packet becomes available, NULL is returned.\end{Desc} 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. \hypertarget{FPA_8h_a11}{ \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{FPA_8h_a4}{FPA\_\-fcb} $\ast$ {\em fcb}, char $\ast$ {\em buffer}, int {\em buf\_\-size}, int {\em packet\_\-size}, int {\em pcb\_\-offset}, \hyperlink{FPA_8h_a2}{FPA\_\-type} {\em type}, \hyperlink{FPA_8h_a3}{FPA\_\-cb\_\-init} {\em init\_\-routine}, void $\ast$ {\em init\_\-parameter})}} \label{FPA_8h_a11} Configures a user supplied piece of memory as a collection of fixed size packets which can be allocated and deallocated. \begin{Desc} \item[Parameters: ]\par \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 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 type}]The type of blocking to be used\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\_\-cb\_\-init 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 must 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: ]\par 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} \hypertarget{FPA_8h_a10}{ \index{FPA.h@{FPA.h}!FPA_pcb_sizeof@{FPA\_\-pcb\_\-sizeof}} \index{FPA_pcb_sizeof@{FPA\_\-pcb\_\-sizeof}!FPA.h@{FPA.h}} \subsubsection[FPA\_\-pcb\_\-sizeof]{\setlength{\rightskip}{0pt plus 5cm}int FPA\_\-pcb\_\-sizeof (void)}} \label{FPA_8h_a10} Returns the size of the Packet control block. \begin{Desc} \item[Returns: ]\par The size, in bytes, of the Packet control block.\end{Desc} 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.