\hypertarget{A-Users-Guide_8Dox}{ \section{A-Users-Guide.Dox File Reference} \label{A-Users-Guide_8Dox}\index{A-Users-Guide.Dox@{A-Users-Guide.Dox}} } Overview of the LCBD Driver. \subsection{Detailed Description} Overview of the LCBD Driver. \begin{Desc} \item[Author:]JJRussell -- \href{mailto:russell@slac.stanford.edu}{\tt russell@slac.stanford.edu}\end{Desc} \hypertarget{A-Users-Guide_8Dox_LCBD_Overview}{}\subsection{Overview of the LCBD Driver}\label{A-Users-Guide_8Dox_LCBD_Overview} The API presented by the driver tries to maintain the view of the LCB as three distinct units. These are\begin{itemize} \item Clock unit, handling clock transitions\item Event unit, handling traffic on the event fabric\item Command/Result unit, handling incoming traffic on the result fabric and submitting commnads on the command fabric\end{itemize} Inevitably there are rough spots where these three units are not completely orthogonal. Ideally one could choose to independently load any combination of these, ignoring the others. The rough spots surface when ensuring that units not of interest are in a quiet state.\hypertarget{A-Users-Guide_8Dox_File_Organization}{}\subsection{File Organization}\label{A-Users-Guide_8Dox_File_Organization} The main files the user will deal with are the header files describing the interface and data structures of these three units plus the header file describing the global properties of the LCB driver. In addition there are number of support files. A brief summary of these files is presented in the following table. They are presented roughly in order of usage and importance. \begin{table}[h]\begin{TabularC}{4} \hline Functional Unit &What it does &Header Files &Source Files \\\hline {\tt \hyperlink{A-Users-Guide_8Dox_LCBD_drv_h}{Driver}} &{\tt Driver load/unload plus interrupt connection and enables} &{\tt \hyperlink{LCBD__drv_8h}{LCBD\_\-drv.h}} &{\tt \hyperlink{LCBD__drv_8c}{LCBD\_\-drv.c}} \\\hline {\tt \hyperlink{A-Users-Guide_8Dox_LCBD_clk_h}{Clock}} &{\tt Signals transitions of the 20MHz LATp-side clock} &{\tt \hyperlink{LCBD__clk_8h}{LCBD\_\-clk.h}} &{\tt \hyperlink{LCBD__clk_8c}{LCBD\_\-clk.c}} \\\hline {\tt \hyperlink{A-Users-Guide_8Dox_LCBD_nut_h}{Notification}} &{\tt Asynchronous notification of driver state transitions} &{\tt \hyperlink{LCBD__nut_8h}{LCBD\_\-nut.h}} &{\tt \hyperlink{LCBD__nut_8c}{LCBD\_\-nut.c}} \\\hline {\tt \hyperlink{A-Users-Guide_8Dox_LCBD_rst_h}{Command/Response}} &{\tt Submits command lists and handles result lists} &{\tt \hyperlink{LCBD__rst_8h}{LCBD\_\-rst.h}} &{\tt \hyperlink{LCBD__rst_8c}{LCBD\_\-rst.c}} \\\hline {\tt \hyperlink{A-Users-Guide_8Dox_LCBD_evt_h}{Event}} &{\tt Handles incoming traffic on the event fabric} &{\tt \hyperlink{LCBD__evt_8h}{LCBD\_\-evt.h}} &{\tt \hyperlink{LCBD__evt_8c}{LCBD\_\-evt.c}} \\\hline {\tt \hyperlink{A-Users-Guide_8Dox_LCBD_stats_h}{Statistics}} &{\tt Fetching and displaying of driver statistics} &{\tt \hyperlink{LCBD__stats_8h}{LCBD\_\-stats.h}} &{\tt \hyperlink{LCBD__stats_8c}{LCBD\_\-stats.c}} \\\hline {\tt \hyperlink{A-Users-Guide_8Dox_LCBD_cr_h}{Driver Command/Result Lists}} &{\tt Lays out LCBD structure for both command \& result lists} &{\tt \hyperlink{LCBD__cr_8h}{LCBD\_\-cr.h}} &{\tt - none - } \\\hline {\tt \hyperlink{A-Users-Guide_8Dox_LCBC_h}{Command Utilities}} &{\tt Simple filling, parsing and synchronous execution of command lists and items} &{\tt \hyperlink{LCBC_8h}{LCBC.h}} &{\tt \hyperlink{LCBC_8c}{LCBC.c}} \\\hline {\tt \hyperlink{A-Users-Guide_8Dox_LCBR_h}{Result Utilities}} &{\tt Parsing and traversing of result lists and items} &{\tt \hyperlink{LCBR_8h}{LCBR.h}} &{\tt \hyperlink{LCBR_8c}{LCBR.c}} \\\hline {\tt \hyperlink{A-Users-Guide_8Dox_LCBD_msgs_h}{MSG Codes}} &{\tt MSG message code definitions} &{\tt \hyperlink{LCBD__msgs_8h}{LCBD\_\-msgs.h}} &{\tt - none - } \\\hline \end{TabularC} \centering \caption{LCBD Driver Files} \end{table} \begin{table}[h]\begin{TabularC}{3} \hline Hardware Unit &What it does &Header Files \\\hline {\tt \hyperlink{A-Users-Guide_8Dox_LCB_h}{LCB Definitions}} &{\tt Defines global LCB hardware properties} &{\tt \hyperlink{LCB_8h}{LCB.h}} \\\hline {\tt \hyperlink{A-Users-Guide_8Dox_LCB_cr_h}{LCB Command/Result List \& Items}} &{\tt Defines command and result lists and items plus opcodes} &{\tt \hyperlink{LCB__cr_8h}{LCB\_\-cr.h}} \\\hline {\tt \hyperlink{A-Users-Guide_8Dox_LATP_h}{LATP}} &{\tt LAT protocal definitions} &{\tt \hyperlink{LATP_8h}{LATP.h}} \\\hline \end{TabularC} \centering \caption{LCB Hardware Definitions} \end{table} \hypertarget{A-Users-Guide_8Dox_LCBD_drv_h}{}\subsection{Driver}\label{A-Users-Guide_8Dox_LCBD_drv_h} LCBD\_\-drv defines and implements global properties and functions of the driver \begin{table}[h]\begin{TabularC}{2} \hline Function &Description \\\hline {\tt \hyperlink{LCBD__drv_8h_82b1b9563fc8eb0153dffd6bbc371133}{LCBD\_\-allow}} &Allows one to add additional PCI/LATp FPGA versions. Mainly used in testing new versions of the FPGAs were being developed \\\hline {\tt \hyperlink{LCBD__drv_8h_948da99905a36d2a8e0cb829fe22ca0a}{LCBD\_\-create}} &Creation and software pre-initialization of the drive handle, one-time only call \\\hline {\tt \hyperlink{LCBD__drv_8h_9377d3dfe7ede4e45919e83716a5b309}{LCBD\_\-get}} &Returns a pointer to the driver handle \\\hline {\tt \hyperlink{LCBD__drv_8h_a007af86d8751872e265c04c77fa798c}{LCBD\_\-load}} &Loads the driver \\\hline {\tt \hyperlink{LCBD__drv_8h_ec756312347c462f2b4bc2ab9a8bf6f7}{LCBD\_\-unload}} &Unloads the driver \\\hline {\tt \hyperlink{LCBD__drv_8h_a4951a52f989f0b8b2dd2214a476b5cd}{LCBD\_\-enable}} &Enables/Disables the various interrupt sources \\\hline {\tt \hyperlink{LCBD__drv_8h_e23b2e62f16f809c1def60533095d44e}{LCBD\_\-state\_\-get}} &Gets the current state of the driver \\\hline {\tt \hyperlink{LCBD__drv_8h_1466f01906775c5b35adde38a6d5bad0}{LCBD\_\-drain}} &Drains the result and/or event queues (non-interrupt mode) \\\hline {\tt \hyperlink{LCBD__drv_8h_cfcdfd3ab943ed3828360475fbc7e4c2}{LCBD\_\-pci\_\-cfg\_\-status\_\-clear}} &Clears the status bits in the PCI configuration status register \\\hline {\tt \hyperlink{LCBD__drv_8h_7b7d58beaec3b80d8d4d96bb1d690fd8}{LCBD\_\-dib\_\-locate}} &Returns a pointer to the Device Information Block \\\hline {\tt \hyperlink{LCBD__drv_8h_f16924372f3feb49242fdcdcc978572f}{LCBD\_\-dib\_\-show}} &Displays the contents of the Device Information Block \\\hline \end{TabularC} \centering \caption{Driver Routines} \end{table} \hypertarget{A-Users-Guide_8Dox_LCBD_clk_h}{}\subsection{Clock Transition Unit}\label{A-Users-Guide_8Dox_LCBD_clk_h} LCBD\_\-clk unit is primarily of concern to the system programmer. The {\em clock\/} here is the 20MHz LAT system wide clock, not the 33MHz PCI clock. Without this clock, the LCB cannot access most of its LATp side functionality. The LCB hardware contains two related interrupts, one indicating the transition from the clock being off to the clock being on, and one indicating the opposite transition from the clock being on to the clock being on. It is expected that the system will install appropriate callback routines to handle these transitions. But these callback routines are very primitive, really meant for debugging and development purposes. A higher level facility based on the clock interrupts is provided, the Notification of the User of state Transitions (\hyperlink{A-Users-Guide_8Dox_LCBD_nut_h}{NUT}) facility. \begin{table}[h]\begin{TabularC}{2} \hline Function &Description \\\hline {\tt \hyperlink{LCBD__clk_8h_cb454c400eff609a5a57fafb5668b346}{LCBD\_\-clk\_\-off\_\-cb\_\-set}} &Seeds the clock off callback routine + parameter \\\hline {\tt \hyperlink{LCBD__clk_8h_94047dcbc0e02a558349653a59b1485c}{LCBD\_\-clk\_\-off\_\-cbp\_\-get}} &Returns the clock off callback routine + parameter \\\hline {\tt \hyperlink{LCBD__clk_8h_c567673be94f9389ec0a56ba8ff2de3d}{LCBD\_\-clk\_\-on\_\-cb\_\-set}} &Seeds the clock on callback routine + parameter \\\hline {\tt \hyperlink{LCBD__clk_8h_94047dcbc0e02a558349653a59b1485c}{LCBD\_\-clk\_\-off\_\-cbp\_\-get}} &Returns the clock on callback routine + parameter \\\hline \end{TabularC} \centering \caption{Clock Routines} \end{table} \hypertarget{A-Users-Guide_8Dox_LCBD_nut_h}{}\subsection{Notification of the User of State Transitions}\label{A-Users-Guide_8Dox_LCBD_nut_h} The LCBD\_\-nut facility provides the user with a means of being asynchonously notified when the state of the driver reaches a target state specified by the user. For example, the user may wish to know when the driver goes ONLINE. Using the LCBD\_\-nut facility, the user would register a notification callback routine to be called when the driver goes ONLINE. \begin{table}[h]\begin{TabularC}{2} \hline Function &Description \\\hline {\tt \hyperlink{LCBD__nut_8h_4c1c54d46d04024b02bc879ef4454a0e}{LCBD\_\-nut\_\-handler\_\-create}} &Convenience routine to create the NUT service task and set the FORK\_\-que \\\hline {\tt \hyperlink{LCBD__nut_8h_6b62379d8729c283c4316cf6b8e2831c}{LCBD\_\-nut\_\-que\_\-install}} &Installs the NUT FORK que \\\hline {\tt \hyperlink{LCBD__nut_8h_68a3785fd197be0045c4ab9899edc3c0}{LCBD\_\-\_\-nut\_\-fill}} &Convenience routine to fill a notification request \\\hline {\tt \hyperlink{LCBD__nut_8h_7cdc8191c41ecdf62bd283ce39a378f8}{LCBD\_\-nut\_\-notify}} &Ques a notification request \\\hline {\tt \hyperlink{LCBD__nut_8h_d97d3a1c5270cc61617eabdffdde4b59}{LCBD\_\-nut\_\-cancel}} &Cancels a notification request \\\hline \end{TabularC} \centering \caption{NUT Basic Routines} \end{table} \begin{table}[h]\begin{TabularC}{2} \hline Function &Description \\\hline {\tt \hyperlink{LCBD__nut_8h_8b491f5b379e0e5e32107def66bb95b9}{LCBD\_\-nut\_\-notifyW}} &Ques a notification request and waits for till it is satisfied \\\hline {\tt \hyperlink{LCBD__nut_8h_c6d156036e5031e4eb07d386f150a5d3}{LCBD\_\-nut\_\-head\_\-create}} &Creates a pending list head to use with \hyperlink{LCBD__nut_8h_c64dcf6cb098d2f9163e4fa21f13e409}{LCBD\_\-nut\_\-post} and \hyperlink{LCBD__nut_8h_365c0236aa17363376202f92597662b6}{LCBD\_\-nut\_\-pendW} \\\hline {\tt \hyperlink{LCBD__nut_8h_6ebf148d09753ba31264ebb88b5d138e}{LCBD\_\-nut\_\-head\_\-destroy}} &Destroys the specified nut post head created with \hyperlink{LCBD__nut_8h_c6d156036e5031e4eb07d386f150a5d3}{LCBD\_\-nut\_\-head\_\-create} \\\hline {\tt \hyperlink{LCBD__nut_8h_c64dcf6cb098d2f9163e4fa21f13e409}{LCBD\_\-nut\_\-post}} &Ques a notification request and ques the satisfied request to the specified posting head \\\hline {\tt \hyperlink{LCBD__nut_8h_365c0236aa17363376202f92597662b6}{LCBD\_\-nut\_\-pendW}} &Pends of a NUT post head for the next satisfied notification request \\\hline {\tt \hyperlink{LCBD__nut_8h_1a4af14ac9db0c85b7437d569ee2e732}{LCBD\_\-nut\_\-fork}} &Ques a notification request and ques the satisfied request to the specified FORK que \\\hline \end{TabularC} \centering \caption{NUT pre-canned notification callback/synchronization routines } \end{table} \hypertarget{A-Users-Guide_8Dox_LCBD_rst_h}{}\subsection{Command/Response Unit}\label{A-Users-Guide_8Dox_LCBD_rst_h} LCBD\_\-rst is the main unit that the application programmer interacts with. It is really two units, one used to submit command lists to the LCB for execution and one to field the responses/results. Because the transactions are tied together, in the sense that the LCB will not execute a new command list until it completely services prior lists, the driver also ties these two units together, using this First In First Out processing of command lists and reception of result lists as an integrity check on the transactions. For those truly interested, while the LCB obeys a FIFO principle of operations, it is highly buffered and pipelined. The LCB can have operations pending in a variety of states within it. While the counting is not exact, the LCB could have on the order of 8-10 command lists in or waiting for execution. One of the simplications of the LCB hardware was to not provide a {\em cancel\/} function. Once an operation has been successfully submitted to the LCB hardware, it cannot be recalled.\hypertarget{A-Users-Guide_8Dox_CR_Principles}{}\subsection{Command and Result Lists, General Principles}\label{A-Users-Guide_8Dox_CR_Principles} Command lists and result lists must be allocated in very specialized ways. There are two reasons for this\begin{enumerate} \item The LCB hardware demands the lists be aligned on specific boundaries. The compile-time constants \hyperlink{LCBD__rst_8h_3a938c2526cc39291e72d2fb36cc9996}{LCBD\_\-CL\_\-ALIGN} and \hyperlink{LCBD__rst_8h_13994b2aede6d96588a73efbca075567}{LCBD\_\-RL\_\-ALIGN} captures these values.\item Due to a hardware error in the RAD750 bridge chip, accessing memory anywhere in or in close proximity to the command or result lists during the LCB operation, may cause the bridge chip to hang. The proximity is defined by the compile-time constants \hyperlink{LCBD__rst_8h_a43ef4df3d7db3e69c024071cc4ad6c6}{LCBD\_\-CL\_\-PAD} and \hyperlink{LCBD__rst_8h_a0f0f2e9fa0ff6c2c93075b63ea2c4fe}{LCBD\_\-RL\_\-MIN}. As the names suggest, the rules are different for command lists and result lists. The next \hyperlink{A-Users-Guide_8Dox_Bridge_Chip_Problem}{section}, goes into gory detail of the origins and work-around to this problem.\end{enumerate} \hypertarget{A-Users-Guide_8Dox_Bridge_Chip_Problem}{}\subsubsection{The Bridge Chip Problem}\label{A-Users-Guide_8Dox_Bridge_Chip_Problem} There is a known problem with the RAD750s bridge chip which acts as the memory controller. This is the infamous Erratum 15. If one accesses, from the CPU, any address in the same cache line that the bridge chip may be snooping, then the bridge chip can hang, resulting in the so-called watchdog in a watchdog timeout. To understand the importance of the above statement it necessary to know\begin{enumerate} \item Under what conditions the bus is being snooped\item What addresses are being snooped\end{enumerate} The answer to the first is straight-forward. The bus will be snooped during any read operation to ensure that the data being read is in memory and not in the CPU cache. The answer to the second is not straight-forward and the detailed answer is dependent on whether on is talking about a command list or a result list. It is clear that when the LCB DMAs a command list from memory into its internal buffers, read operations, and, therefore, bus snoops are occuring. What is not as clear is\begin{enumerate} \item Why, since the result list is being DMA back into memory from the LCB, seemingly a write operation with no associated bus snoops, does the result list needs protecting?\item How much memory is being snooped?\end{enumerate} The reason the result list needs protecting can be traced back to the need and method used to flush the bridge chips internal buffers. Whether by design or due to an error, any DMA transfer that writes data back into the memory that is not a integral multiple of cache lines, needs a dummy read operation to flush the partial cache line remnant back into memory. It is this read operation that generates a bus snoop and, therefore, makes the result list vulnerable to the bus hang. Also the partial flush itself generates a bus snoop since it must snoop the bus to cast out any dirty copy of the cache line it is about to partially write. The definition of the vulnerable memory is also tricky. When this problem was first encountered and addressed, the answer seemed straight-forward. It is the memory occupied by the command or result lists rounded up to the nearest cache line boundary. This turned out to be only partially correct. For efficiency reasons, the bridge chip attempts to keep a buffer of 6 cache lines filled at all times. Effectively as soon as one or more cache lines are consumed, the bridge chip fetches enough data to replace it. This means that the vulnerable area is much larger than one naively would think.\hypertarget{A-Users-Guide_8Dox_Command_List_Vulnerability}{}\subsubsection{Command List Vulnerability}\label{A-Users-Guide_8Dox_Command_List_Vulnerability} Because of this prefetching, the vulnerable area of a command list extends in the addresses 5 cache lines past the last cache line occupied by the command list list. Therefore, no memory addresses in the command list and 5 cache lines past the end of the command list can be accessed during the LCB operation. (The reason it is 5 and not 6 is that the last cache line in the command list counts as one of the 6. Said another way, if the command list was exhausted, then there would be no reason to perform another read.) Therefore, the allocation strategy for command lists is allocate an additional 5 cache lines after the end of the last cache line in the command list.\hypertarget{A-Users-Guide_8Dox_Result_List_Vulnerability}{}\subsubsection{Result List Vulnerability}\label{A-Users-Guide_8Dox_Result_List_Vulnerability} Since the only read access being performed is the read to flush the partial cache line, the vulnerable area of the result list is the 6 cache lines from the target address of the dummy read, {\em i.e.\/} the first address of the result list. Therefore, no memory addresses within the first 6 cache lines from the beginning of the result list can be accessed during the LCB operation. Therefore, the allocation strategy for result lists to be rounded {\em up\/} to a cache line boundary and to always ensure that a minimum of 6 cache lines are allocated. Note that when allocating LCBD result lists, these include the driver defined and mandated structure \hyperlink{LCBD__rst_8h_8c2828a3356c18ec0a75d5fa735d0c45}{LCBD\_\-xcb}, so the size of this structure must added to the minimum hardware size. This means the minimum size of a DMA-safe \hyperlink{LCBD__cr_8h_0b7cd591e3c4383c5386e4c1abf99993}{LCBD\_\-rl} is the sizeof its \hyperlink{LCBD__rst_8h_8c2828a3356c18ec0a75d5fa735d0c45}{LCBD\_\-xcb} plus its \hyperlink{LCB__cr_8h_163e6417f44170f9ec07348c16e77e5d}{LCB\_\-rl\_\-hdr} + its items.\hypertarget{A-Users-Guide_8Dox_Sizing_and_allocation_strategies}{}\subsubsection{Sizing and allocation strategies}\label{A-Users-Guide_8Dox_Sizing_and_allocation_strategies} The LCBD software provides routines to safely size and allocate memory,\begin{itemize} \item \hyperlink{LCBD__rst_8c_881654c635e270f3d6b5b83f30389a53}{LCBD\_\-cl\_\-size}\item \hyperlink{LCBD__rst_8c_49ee7d07e1549bfcd14b2a88decf514b}{LCBD\_\-rl\_\-size}\item \hyperlink{LCBD__rst_8c_8de7a45ea676c90de5c77399049e2874}{LCBD\_\-cl\_\-alloc}, \hyperlink{LCBD__rst_8c_a31fec85476ca1c0ccc6e64a16038c26}{LCBD\_\-cl\_\-alloc8}\item \hyperlink{LCBD__rst_8c_9704eca6166fbe162ba8bb13492ecb33}{LCBD\_\-rl\_\-alloc}, \hyperlink{LCBD__rst_8c_563d4505b5dac79fa0c458a48e4b3054}{LCBD\_\-rl\_\-alloc8}\end{itemize} In addition, if the user truly needs to size the list at compile-time, two macros are provided\begin{itemize} \item \hyperlink{LCBD__rst_8h_ab2ebe12aecbba34449c35b0d6dd4a37}{LCBD\_\-CL\_\-SIZE} (nbytes)\item \hyperlink{LCBD__rst_8h_70aa9a34d397125d56cb73a0e4e174fb}{LCBD\_\-RL\_\-SIZE} (nbytes)\end{itemize} However, where, possible, the user is encouraged to use the run-time routines, as these provide protection if there is yet another change in what constitutes a safe allocation.\hypertarget{A-Users-Guide_8Dox_Custom_Allocation}{}\subsubsection{Custom Allocation}\label{A-Users-Guide_8Dox_Custom_Allocation} There are circumstances where the user may not wish to pay the price in terms of the extra memory needed to make the lists safe. For example, because of the details of the code, one may know that these vulnerable locations cannot be accessed when the LCB operation involving these lists is in progress. Under these circumstances, the user may do his own sizing and allocations. As previously alluded to, there are \hyperlink{A-Users-Guide_8Dox_Sizing_Assist_Macros}{macros} and \hyperlink{A-Users-Guide_8Dox_Allocation_Assist_Routines}{routines} that define the alignment and padding necessary for the user to size and allocate custom lists. These, in fact, are the ingredients that the LCBD software itself uses, so there is nothing it can do that a user of the software cannot recreate. Having said that, the downside of {\em doing it yourself\/} is that policy is moved from the centralized LCBD software out into the wild of many packages. The result is that code is vulnerable if the details of how to produce safe lists changes. Note that there are, in general, three kinds of safety\begin{itemize} \item Using the run-time routines provides the maximum safety. If the policy changes, assuming the interface is correct, then only LCBD needs to be changed to reflect that.\item Compile time safety is achieved if one uses the higher-level macros such as LCBD\_\-CL\_\-SIZE and LCBD\_\-RL\_\-SIZE. If the policy chnages, code using these macros only needs to be recompiled, not rewritten.\item \end{itemize} \hypertarget{A-Users-Guide_8Dox_DMA_Safe_Command_Lists}{}\subsubsection{DMA-Safe Command Lists}\label{A-Users-Guide_8Dox_DMA_Safe_Command_Lists} Currently DMA-safe command list allocations are ones that\begin{itemize} \item Are allocated on \hyperlink{LCBD__rst_8h_3a938c2526cc39291e72d2fb36cc9996}{LCBD\_\-CL\_\-ALIGN} memory boundaries\item Are extended \hyperlink{LCBD__rst_8h_a43ef4df3d7db3e69c024071cc4ad6c6}{LCBD\_\-CL\_\-PAD} bytes beyond the end of the last cache line.\end{itemize} \hypertarget{A-Users-Guide_8Dox_DMA_Safe_Result_Lists}{}\subsubsection{DMA-Safe Result Lists}\label{A-Users-Guide_8Dox_DMA_Safe_Result_Lists} Currently DMA-safe result list allocations do are ones that\begin{itemize} \item Are allocated on \hyperlink{LCBD__rst_8h_13994b2aede6d96588a73efbca075567}{LCBD\_\-RL\_\-ALIGN} memory boundaries\item Are rounded out to an even cache line boundary and have a length of at least \hyperlink{LCBD__rst_8h_a0f0f2e9fa0ff6c2c93075b63ea2c4fe}{LCBD\_\-RL\_\-MIN} bytes.\end{itemize} \begin{table}[h]\begin{TabularC}{2} \hline Function &Description \\\hline {\tt \hyperlink{LCBD__rst_8c_af50b3db3fceac150936c308eecf68f1}{LCBD\_\-rst\_\-handler\_\-create}} &Convenience routine to create the RST service task and set the FORK\_\-que \\\hline {\tt \hyperlink{LCBD__rst_8c_54a429c5dc8ec725179f6636ec2fa312}{LCBD\_\-rst\_\-que\_\-install}} &Installs the RST FORK que \\\hline {\tt \hyperlink{LCBD__rst_8c_f15cf2ba2bc7d2f3bbc794dc7fdebba4}{LCBD\_\-rst\_\-null\_\-cb\_\-set}} &Seeds the NULL result descriptor handler + parameter \\\hline {\tt \hyperlink{LCBD__rst_8c_2172fa21b2207fecb42aa5642c350c11}{LCBD\_\-rst\_\-null\_\-cbp\_\-get}} &Returns the NULL result descriptor handler + parameter \\\hline {\tt \hyperlink{LCBD__rst_8c_d1223a179857b03331dfccb46c7563b5}{LCBD\_\-bind}} &Binds the parameters of an \hyperlink{LCBD__rst_8h_8c2828a3356c18ec0a75d5fa735d0c45}{LCBD\_\-xcb} to the XCB \\\hline {\tt \hyperlink{LCBD__rst_8c_769c0c3100d3ca3936596c5305f373b8}{LCBD\_\-submit}} &Submits a bound \hyperlink{LCBD__rst_8h_8c2828a3356c18ec0a75d5fa735d0c45}{LCBD\_\-xcb} to the LCB for execution \\\hline \end{TabularC} \centering \caption{RST Basic Routines} \end{table} \begin{table}[h]\begin{TabularC}{2} \hline Function &Description \\\hline {\tt \hyperlink{LCBD__rst_8c_881654c635e270f3d6b5b83f30389a53}{LCBD\_\-cl\_\-size}} &DMA-safe command list size determination \\\hline {\tt \hyperlink{LCBD__rst_8c_49ee7d07e1549bfcd14b2a88decf514b}{LCBD\_\-rl\_\-size}} &DMA-safe result list size determination \\\hline {\tt \hyperlink{LCBD__rst_8c_8de7a45ea676c90de5c77399049e2874}{LCBD\_\-cl\_\-alloc}} &DMA-safe command list allocator, by bytes \\\hline {\tt \hyperlink{LCBD__rst_8c_9704eca6166fbe162ba8bb13492ecb33}{LCBD\_\-rl\_\-alloc}} &DMA-safe result list allocator, by bytes \\\hline {\tt \hyperlink{LCBD__rst_8c_a31fec85476ca1c0ccc6e64a16038c26}{LCBD\_\-cl\_\-alloc8}} &DMA-safe command list allocator, by 8 byte cells \\\hline {\tt \hyperlink{LCBD__rst_8c_563d4505b5dac79fa0c458a48e4b3054}{LCBD\_\-rl\_\-alloc8}} &DMA-safe result list allocator, by 8 byte cells \label{A-Users-Guide_8Dox_Allocation_Assist_Routines} \hypertarget{A-Users-Guide_8Dox_Allocation_Assist_Routines}{} \\\hline {\tt \hyperlink{LCBD__rst_8c_337811895d2170c3559332ab527881da}{LCBD\_\-cl\_\-alloc\_\-unprotected}} &Unprotected command list allocator, by bytes \\\hline {\tt \hyperlink{LCBD__rst_8c_40ae977d6361341bacd8431100b5b6a8}{LCBD\_\-rl\_\-alloc\_\-unprotected}} &Unprotected result list allocator, by bytes \\\hline {\tt \hyperlink{LCBD__rst_8c_362d0d7908b57ad0274a874301f18435}{LCBD\_\-cl\_\-alloc8\_\-unprotected}} &Unprotected command list allocator, by 8 byte cells \\\hline {\tt \hyperlink{LCBD__rst_8c_7e655293070c6cc44023df677f17091b}{LCBD\_\-rl\_\-alloc8\_\-unprotected}} &Unprotected result list allocator, by 8 byte cells \\\hline {\tt \hyperlink{LCBD__rst_8h_06ffe5965670a3194234de9e201b2130}{LCBD\_\-\_\-cl\_\-len}} &Converts a command list length in bytes to 8-byte cells, {\em i.e.\/} something suitable to passing to one of the LCBD\_\-bind routines \\\hline {\tt \hyperlink{LCBD__rst_8h_48de38d66c9712dd327c24ba658b1657}{LCBD\_\-\_\-cl\_\-dlen}} &Converts a command list specified by it's beginning and ending pointers to 8-byte cells, {\em i.e.\/} something suitable to passing to one of the LCBD\_\-bind routines \\\hline {\tt \hyperlink{LCBD__rst_8h_019a98ed66fe8342dddee5459390217d}{LCBD\_\-\_\-rl\_\-len}} &Converts a result list length in bytes to 8-byte cells, {\em i.e.\/} something suitable to passing to one of the LCBD\_\-bind routines \\\hline {\tt \hyperlink{LCBD__rst_8h_b89b2dff26d0514ddbe41abf574d94b6}{LCBD\_\-\_\-rl\_\-dlen}} &Converts a result list specified by it's beginning and ending pointers to 8-byte cells, {\em i.e.\/} something suitable to passing to one of the LCBD\_\-bind routines \\\hline {\tt \hyperlink{LCBD__rst_8c_5cc25b16e8911e3e530c18c13c2d81e4}{LCBD\_\-rst\_\-rcv\_\-err\_\-map}} &Translates a result list receive error code to a standard MSG code \\\hline {\tt \hyperlink{LCBD__rst_8c_7859e72ed2c77c7d862d182cc2ff7341}{LCBD\_\-rst\_\-xfr\_\-err\_\-map}} &Translates a result list transfer error code to a standard MSG code \\\hline \end{TabularC} \centering \caption{RST Utility Routines} \end{table} \begin{table}[h]\begin{TabularC}{2} \hline Function &Description \\\hline {\tt \hyperlink{LCBD__rst_8c_6d5ad89ddb13494116328b28be763e9c}{LCBD\_\-qioW}} &Convenience routine to que a command list to the LCB and wait for its completion, combines \hyperlink{LCBD__rst_8c_d1223a179857b03331dfccb46c7563b5}{LCBD\_\-bind} and \hyperlink{LCBD__rst_8c_d42d6e7cac68564c91daeec88fbbdd3b}{LCBD\_\-submitW} \\\hline {\tt \hyperlink{LCBD__rst_8c_d42d6e7cac68564c91daeec88fbbdd3b}{LCBD\_\-submitW}} &Submits a bound \hyperlink{LCBD__rst_8h_8c2828a3356c18ec0a75d5fa735d0c45}{LCBD\_\-xcb} to the LCB and waits for its completed execution \\\hline {\tt \hyperlink{LCBD__rst_8c_02ec0116959aeebf06b47a9c70d25bae}{LCBD\_\-fork\_\-bind}} &Binds the parameters to an \hyperlink{LCBD__rst_8h_8c2828a3356c18ec0a75d5fa735d0c45}{LCBD\_\-xcb} using a dispatch to a FORK que as its synchronization method. \\\hline {\tt \hyperlink{LCBD__rst_8c_5c10b1b5f985698c6b955ce7a37300f7}{LCBD\_\-post\_\-create}} &Creates a posting list head that can be used by \hyperlink{LCBD__rst_8c_278cd2c726b6e30f578e21599ac49dfc}{LCBD\_\-post\_\-bind} and \hyperlink{LCBD__rst_8c_c2076ee10488f19be9435fd82e6a1d68}{LCBD\_\-post\_\-pendW} \\\hline {\tt \hyperlink{LCBD__rst_8c_2ed8730ded29c43d2ab942270b0b32cd}{LCBD\_\-post\_\-destroy}} &Destroys the posting list head created by \hyperlink{LCBD__rst_8c_5c10b1b5f985698c6b955ce7a37300f7}{LCBD\_\-post\_\-create} \\\hline {\tt \hyperlink{LCBD__rst_8c_278cd2c726b6e30f578e21599ac49dfc}{LCBD\_\-post\_\-bind}} &Binds the parameters of the \hyperlink{LCBD__rst_8h_8c2828a3356c18ec0a75d5fa735d0c45}{LCBD\_\-xcb} to an XCB using a dispatch to a posting list head as its synchronization method. \\\hline {\tt \hyperlink{LCBD__rst_8c_c2076ee10488f19be9435fd82e6a1d68}{LCBD\_\-post\_\-pendW}} &Waits for the next completed \hyperlink{LCBD__rst_8h_8c2828a3356c18ec0a75d5fa735d0c45}{LCBD\_\-xcb} on the specified posting list head \\\hline \end{TabularC} \centering \caption{RST Pre-canned Callback/Sychronization Routines} \end{table} \begin{table}[h]\begin{TabularC}{2} \hline Macro &Description \label{A-Users-Guide_8Dox_Sizing_Assist_Macros} \hypertarget{A-Users-Guide_8Dox_Sizing_Assist_Macros}{} \\\hline {\tt \hyperlink{LCBD__rst_8h_3a938c2526cc39291e72d2fb36cc9996}{LCBD\_\-CL\_\-ALIGN}} &The byte alignment requirement for command lists. This can be used as the first argument to MBA\_\-align. \\\hline {\tt \hyperlink{LCBD__rst_8h_13994b2aede6d96588a73efbca075567}{LCBD\_\-RL\_\-ALIGN}} &The byte alignment requirement for result lists This can be used as the first argument to MBA\_\-align. \\\hline {\tt \hyperlink{LCBD__rst_8h_a43ef4df3d7db3e69c024071cc4ad6c6}{LCBD\_\-CL\_\-PAD}} &The size, in bytes, of the padding needed after the last cache line of a command list. \\\hline {\tt \hyperlink{LCBD__rst_8h_a0f0f2e9fa0ff6c2c93075b63ea2c4fe}{LCBD\_\-RL\_\-MIN}} &The minimum size, in bytes, of result list. \\\hline {\tt \hyperlink{LCBD__rst_8h_c5a0470c4279a00709fc4e286b4e3930}{LCBD\_\-RNDUP\_\-TO\_\-CACHELINE}} &Rounds a specfied number of bytes {\em up\/} to the nearest cache line boundary. \\\hline {\tt \hyperlink{LCBD__rst_8h_d7377a2acddcd70eb050d1f5cfbdfa95}{LCBD\_\-RNDDOWN\_\-TO\_\-CACHELINE}} &Rounds a specfied number of bytes {\em down\/} to the nearest cache line boundary. \\\hline {\tt \hyperlink{LCBD__rst_8h_cc34628c28569639ae2c6ccff58f5851}{LCBD\_\-EXP\_\-DSC\_\-COMPOSE}} &Composes a complete command export descriptor \\\hline {\tt \hyperlink{LCBD__rst_8h_c5b8f4e9c2e3f759cd3c2b4653d64065}{LCBD\_\-EXP\_\-DSC\_\-REPLACE\_\-LEN}} &Replaces only the length field of a command export descriptor \\\hline \end{TabularC} \centering \caption{RST Macros} \end{table} \hypertarget{A-Users-Guide_8Dox_LCBD_evt_h}{}\subsection{Event}\label{A-Users-Guide_8Dox_LCBD_evt_h} LCBD\_\-evt controls and services traffic of the event fabric. The architecture of the transactions on the LATp event fabric is such that most users view traffic on this fabric as simply data that arrives asynchronously into a user provided callback. In this model, the application programmer has little interaction with the driver itself. He may install callback routines to service the four LCB provided protocols, but beyond that he is limited to perhaps calling some convenience service routines to help in packet reassembly and packet freeing. Outbound traffic, {\em e.g.\/} a LCB-to-LCB message, is really part of the command/response unit, not the event unit. To the receiver, such transactions are a part of the event unit, but to the transmitter they are handled by the command/response unit. \begin{table}[h]\begin{TabularC}{2} \hline Function &Description \\\hline {\tt \hyperlink{LCBD__evt_8h_f089f5e6eb311c3eb5d2aec3a48a65a0}{LCBD\_\-evt\_\-handler\_\-create}} &Convenience routine to create the EVT service task and set the FORK\_\-que \\\hline {\tt \hyperlink{LCBD__evt_8h_9cc1430459be9d0da97c762fb56a7661}{LCBD\_\-evt\_\-que\_\-install}} &Installs the EVT FORK que \\\hline {\tt \hyperlink{LCBD__evt_8h_270c14134ae98cfd79519e16b093b30f}{LCBD\_\-evt\_\-cb\_\-set}} &Seeds the event callback handler + parameter for a specified protocol \\\hline {\tt \hyperlink{LCBD__evt_8h_51757c5ab17888f2b129cc6dfa5eeace}{LCBD\_\-evt\_\-cbp\_\-get}} &Returns the event callback handler + parameter for a specified protocol \\\hline {\tt \hyperlink{LCBD__evt_8h_f7e234602dd30fa80f422c4b22d3821b}{LCBD\_\-evt\_\-err\_\-cb\_\-set}} &Seeds the event error handler + parameter for a specified \\\hline {\tt \hyperlink{LCBD__evt_8h_1d04649563275cb158dca9a7fa5131da}{LCBD\_\-evt\_\-err\_\-cbp\_\-get}} &Returns the event error handler + parameter \\\hline {\tt \hyperlink{LCBD__evt_8h_c75355ca8c4b0689698ca5a90ace1b3d}{LCBD\_\-evt\_\-conds\_\-set}} &Sets the event que and event buffer interrupt conditions, returning the old ones, see \hyperlink{LCBD__evt_8h_7c480b0088928f3e909984b5b3e129a1}{LCBD\_\-EVT\_\-COND} \\\hline {\tt \hyperlink{LCBD__evt_8h_d5ee4abc6e7be61ebc65267a84ac5c0f}{LCBD\_\-evt\_\-enable}} &Enables the flow of events into the event circular buffer, returns the original flow state \\\hline {\tt \hyperlink{LCBD__evt_8h_4e30ca85da04c27be7817b73ea4b66a1}{LCBD\_\-evt\_\-tickle}} &Tickles the event handler to check if there are any events to be serviced. \\\hline {\tt \hyperlink{LCBD__evt_8h_46faa0c9be1b6c413d5484170434fad8}{LCBD\_\-evt\_\-free}} &Frees the specified event \\\hline {\tt \hyperlink{LCBD__evt_8h_0664abbdc8356474573b15ca2e7b10b2}{LCBD\_\-evt\_\-rcv\_\-err\_\-map}} &Translates a event receive error code to a standard MSG code \\\hline {\tt \hyperlink{LCBD__evt_8h_8f63f25994e1e6a552d28060b7772ef4}{LCBD\_\-evt\_\-xfr\_\-err\_\-map}} &Translates a event transfer error code to a standard MSG code \\\hline \end{TabularC} \centering \caption{EVT Routines} \end{table} \hypertarget{A-Users-Guide_8Dox_Loading_Initializing_the_Driver}{}\subsection{Loading/Initializing the Driver}\label{A-Users-Guide_8Dox_Loading_Initializing_the_Driver} A lot of work has gone into eliminating driver configuration constants and simplying the loading of the driver. There are only two configuration constants that absolulted must be specified to load the driver\begin{itemize} \item Fabric Selection (defaults to primary)\item Interrupt Source Selection (defaults to PCI interrupt)\item Event Base setting (no default)\end{itemize} Special sentinel values allow both parameters to be ignored, that is the LCB will not attempt to set them. Correct use of the {\em fabric select\/} parameter is highly dependent on whether the LCB is residing in a SIU or EPU crate.\hypertarget{A-Users-Guide_8Dox_SIU_Fabric_Selection}{}\subsubsection{SIU Fabric Selection}\label{A-Users-Guide_8Dox_SIU_Fabric_Selection} Fabric selection on the SIU should be done by specifying the appropriate path,\begin{itemize} \item \hyperlink{LCBD__drv_8h_5b058182c8b91d3638b871b55448045947ee9a617aec5b3b63c4f06083e3f25a}{LCBD\_\-LOAD\_\-OPTIONS\_\-M\_\-FABRIC\_\-PRIMARY}\item \hyperlink{LCBD__drv_8h_5b058182c8b91d3638b871b554480459e10d2f14ec6e26bbaf74ed0c01eeb3a1}{LCBD\_\-LOAD\_\-OPTIONS\_\-M\_\-FABRIC\_\-REDUNDANT}\end{itemize} to LCBD\_\-load. Because the primary boot code does not use the LCB, this value is not needed until secondary boot. The secondary boot code should use the EEPROM to store this value. If fail-over is needed, then a 1553 command will be issued to change it.\hypertarget{A-Users-Guide_8Dox_EPU_Fabric_Selection}{}\subsubsection{EPU Fabric Selection}\label{A-Users-Guide_8Dox_EPU_Fabric_Selection} Fabric selection on the EPU cannot use this method because it needs the LCB, and hence the path selection, during primary boot. (There is no method of passing parameters to the primary boot code.) The EPU depends on the SIU to remotely set this value by assessing the EPU's LATp-side CSR as a slave register on the command/response fabric and setting the path selection bit there to the desired value. Consequently EPU code will always specify \begin{itemize} \item \hyperlink{LCBD__drv_8h_5b058182c8b91d3638b871b554480459cfaca9e044b926c912d05577a5960409}{LCBD\_\-LOAD\_\-OPTIONS\_\-M\_\-FABRIC\_\-ASIS}\end{itemize} \hypertarget{A-Users-Guide_8Dox_Event_Base}{}\subsubsection{Event Base}\label{A-Users-Guide_8Dox_Event_Base} This parameter allows the system architect to set the address of the event fabric's circular buffer. Two sentinel values are defined\begin{itemize} \item \hyperlink{LCBD__drv_8h_eb7576aee76cad9adc30e4b15019f6a1}{LCBD\_\-K\_\-EVENT\_\-BASE\_\-IGNORE}\item \hyperlink{LCBD__drv_8h_cfd287007148e6d3ec649afb5ad53c2f}{LCBD\_\-K\_\-EVENT\_\-BASE\_\-ALLOCATE}\end{itemize} The former instructs LCBD\_\-load to leave the event base register as is. This may be valuable in test code. The latter instructs LCBD\_\-load to internally allocate a buffer and use its address as the event base. Buffers automatically allocated will be freed when the driver is unloaded. Clean-up of user specificed buffers is the responsibility of the user.\hypertarget{A-Users-Guide_8Dox_Other_parameters}{}\subsubsection{Other parameters}\label{A-Users-Guide_8Dox_Other_parameters} There are 4 other parameters that can be specified by the {\em options\/} of LCBD\_\-load. They are\begin{itemize} \item The incoming clock edge strobe (leading/trailing)\item The outgoing clock edge strobe (leading/trailing)\item The board identification (board number)\item The width of the event data path (bit/byte)\end{itemize} See the enum LCBD\_\-LOAD\_\-OPTIONS\_\-M and the macro LCBD\_\-LOAD\_\-OPTIONS\_\-M\_\-BOARD\_\-ID\_\-N for details. Specifying these parameters in this way is only a convenience. The loading of the does not depend on these parameters in any way. Because it is not absolutely necessary to load these parameters at this time and because it is possible that the application does not know the value of these parameters at LCBD\_\-load time, they can be set at anytime before they are needed (general rule here is before any external LCBD operations are attempted such as issuing a message to another CPU or talking to a TEM), there are convenience routines to set them at a later point. These are \begin{itemize} \item LCBD\_\-clk\_\-edge\_\-set\item LCBD\_\-board\_\-id\_\-set \_\- LCBD\_\-width\_\-set\end{itemize} \begin{Desc} \item[Note:]These really are merely convenience routines. For the bit-twiddlers, one can set all these parameters by specifying the appropriate arguments to LCBD\_\-csr\_\-access.\end{Desc} \hypertarget{A-Users-Guide_8Dox_DS_Overview}{}\subsubsection{Driver Simplification - Overview}\label{A-Users-Guide_8Dox_DS_Overview} In trying to simplify driver loading, LCBD separate its clients into two classes \begin{enumerate} \item Users who just want to get the driver loaded and get going\item Users who operate in a very formal environment where complete control is paramount.\end{enumerate} The first class of users are test code writers and prototypers. The second class of users are those installing the driver in a deliverable product. Needlessly to say, satisfying both groups simoultaneously is difficult.\hypertarget{A-Users-Guide_8Dox_DS_Service_Tasks_and_Ques}{}\subsubsection{Driver Simplification - Service Tasks and Ques}\label{A-Users-Guide_8Dox_DS_Service_Tasks_and_Ques} One of the big steps in removing configuration constants from the driver was in the divorcing of the service task management. Properly speaking, the LCBD driver is not concerned with service tasks; all it really needs to know is the FORK que associated with each of the three handlers (notification, result and event). For user's in the second class, LCBD provides three routines to register these ques with the driver\begin{itemize} \item \hyperlink{LCBD__nut_8h_6b62379d8729c283c4316cf6b8e2831c}{LCBD\_\-nut\_\-que\_\-install} (lcb, nut\_\-que)\item \hyperlink{LCBD__rst_8c_54a429c5dc8ec725179f6636ec2fa312}{LCBD\_\-rst\_\-que\_\-install} (lcb, rst\_\-que)\item \hyperlink{LCBD__evt_8h_9cc1430459be9d0da97c762fb56a7661}{LCBD\_\-evt\_\-que\_\-install} (lcb, evt\_\-que)\end{itemize} Naturally, the user is responsible for creating the FORK task and identifying the target que. With this responsibility comes the freedom to do almost anything one pleases. For example, one could create one FORK task with 3 ques, handing a different que to each installation routine. (Would not recommend this.) For user's in the first class, a simplified set of routines to create a FORK task and install a FORK que are provided. (These routines may be stripped from the final production driver; they consume are fair amount of code space.) These routines are\begin{itemize} \item \hyperlink{LCBD__evt_8h_f089f5e6eb311c3eb5d2aec3a48a65a0}{LCBD\_\-evt\_\-handler\_\-create} (lcb, evt\_\-priority)\item \hyperlink{LCBD__nut_8h_4c1c54d46d04024b02bc879ef4454a0e}{LCBD\_\-nut\_\-handler\_\-create} (lcb, nut\_\-priority)\item \hyperlink{LCBD__rst_8c_af50b3db3fceac150936c308eecf68f1}{LCBD\_\-rst\_\-handler\_\-create} (lcb, rst\_\-priority)\end{itemize} The priority can be specified with a sentinel values\begin{itemize} \item \hyperlink{LCBD__evt_8h_2937d58aaf4533c551cb88c1acbadc8a}{LCBD\_\-EVT\_\-K\_\-DEFAULT\_\-PRIORITY}\item \hyperlink{LCBD__nut_8h_2b152abd3acf8fd4f5ca3d96c1c32203}{LCBD\_\-NUT\_\-K\_\-DEFAULT\_\-PRIORITY}\item \hyperlink{LCBD__rst_8h_6002597b069c3d184f0abdc591f02ff0}{LCBD\_\-RST\_\-K\_\-DEFAULT\_\-PRIORITY}\end{itemize} If so, LCBD will assign a handler specific priority to each FORK task. With this simplication, one loses control of almost every parameter of the FORK task (except the priority). If special attributes, such as a larger stack, the floating point unit, more ques, etc, are needed, the user must create the FORK task and install the que using the previously described method.\hypertarget{A-Users-Guide_8Dox_Unloading_the_Driver}{}\subsubsection{Unloading the Driver}\label{A-Users-Guide_8Dox_Unloading_the_Driver} For debugging and development purposes, the driver is built so that it can be unloaded (see LCBD\_\-unload). The NUT facility allows user code to be notified of this rather jarring event. It is up to the user to clean-up his own house first, for example, by stopping the submission of new requests to LCBD and servicing all currently outstanding requests. The unload process will \begin{enumerate} \item Disable all the interrupt sources\item Disconnect the driver from the PCI interrupt itself\item Return all resources it garnered during the load phase\end{enumerate} As a convenience to the user, any service tasks created using convenience routines ({\em e.g\/}. LCBD\_\-rst\_\-handler\_\-create) will be destroyed. It is the user's responsibility to manage the tasks associated with, {\em e.g\/}. LCBD\_\-rst\_\-que\_\-install; afterall the LCBD que may be only one of many ques associated with this task. As mentioned before, if the event circular buffer is allocated by the driver, it will also be freed by LCBD\_\-unload operation.\hypertarget{A-Users-Guide_8Dox_Initialization_Example_1}{}\subsubsection{Initialization Example 1}\label{A-Users-Guide_8Dox_Initialization_Example_1} A typical initialization sequence for users in the first class goes like \begin{Code}\begin{verbatim} unsigned int startLcbd (unsigned int options, unsigned int *circularBuffer) { // Get pre-initialized driver handle lcb = LCBD_create (NULL); // Load the driver, // Options is used to select the path and the interrupt source // See LCBD_LOAD_OPTIONS_M for details status = LCBD_load (lcb, options, circularBuffer); // Install the result, event and notification service tasks // using the default priorities status = LCBD_rst_handler_create (lcb, LCBD_RST_K_DEFAULT_PRIORITY); status = LCBD_evt_handler_create (lcb, LCBD_EVT_K_DEFAULT_PRIORITY); status = LCBD_nut_handler_create (lcb, LCBD_NUT_K_DEFAULT_PRIORITY); // Set the callback handler for the protocol #1 status = LCBD_evt_cb_set (lcb, 1, eventHander, eventParameter); // Set event interrupt conditions 25% on FIFO LCBD_evt_conds_set (lcb, LCBD_EVT_COND_25_FULL); // Enable the result and event interrupts status = LCBD_enable (lcb, LCBD_M_ENABLE_EVENT | LCBD_M_ENABLE_RESULT)); // Enable the event flow into the LCB's circular buffer status = LCBD_evt_enable (lcb, 1); return status; } \end{verbatim} \end{Code} \hypertarget{A-Users-Guide_8Dox_Initialization_Example_2}{}\subsubsection{Initialization Example 2}\label{A-Users-Guide_8Dox_Initialization_Example_2} A formal initialization sequence for users is presented here. It is not meant to be complete, but gives you the rough idea of how one would go about starting the driver up in a bullet-proof fashion \begin{Code}\begin{verbatim} unsigned int startLcbd (unsigned int options, unsigned int *circularBuffer, FORK_que *evt_que, FORK_que *nut_que, FORK_que *rst_que) { // Get pre-initialized driver handle lcb = LCBD_create (NULL); // Load the driver // Options is used to select the path and the interrupt source // See LCBD_LOAD_OPTIONS_M for details init_status = LCBD_load (lcb, options, circularBuffer); // Check for success errors if (_msg_error (init_status) return init_status; // Install the result, event and notification ques status = LCBD_rst_que_install (lcb, rst_que); status = LCBD_evt_que_install (lcb, evt_que); status = LCBD_nut_que_install (lcb, nut_que); // Enable the clock on interrupt // The only possible error is if one tries to simoultaneously set // both the ENABLE and DISABLEs, clearly not happening here LCBD_enable (lcb, LCBD_M_ENABLE_CLK_ON); // Check if possibly have no clock if (init_status == LCBD_NOCLK) { LCBD_state state; // Wait for the driver to come online // Once ONLINE the driver has been successfully initialized // Keep in mind it may on OFFLINE at any time in the future, // but in terms of initialization, it's done. state = LCBD_nut_notifyW (lcb, LCBD_STATE_M_ONLINE); } // Set the callback handler for the protocol #1 status = LCBD_evt_cb_set (lcb, 1, eventHander, eventParameter); // Set event interrupt conditions 25% on FIFO full LCBD_evt_conds_set (lcb, LCBD_EVT_COND_25_FULL); // Enable the result and event interrupts status = LCBD_enable (lcb, LCBD_M_ENABLE_EVENT | LCBD_M_ENABLE_RESULT)); // Enable the event flow into the LCB's circular buffer status = LCBD_evt_enable (lcb, 1); // Check driver state, not necessary, but just to illustrate return (LCBD_state_get (lcb) == LCBD_STATE_ONLINE) ? status : ERROR; } \end{verbatim} \end{Code} \hypertarget{A-Users-Guide_8Dox_Command_Response_Usage}{}\subsubsection{Command/Response Design Usage}\label{A-Users-Guide_8Dox_Command_Response_Usage} Once past this menagerie of setup and initialization routines. the user's primary interaction with the LCB using this version of the driver is through the {\em transaction control block\/}, called an {\em LCBD\_\-xcb\/}. LCBD\_\-xcb is described in detail below.\hypertarget{A-Users-Guide_8Dox_LCBD_xcb_Overview}{}\subsubsection{LCBD\_\-xcb - Overview}\label{A-Users-Guide_8Dox_LCBD_xcb_Overview} The driver main interaction with the user is filling and managing the XCB as it moves from one queue to another. The XCB contains all the necessary information needed to describe the transaction, {\em e.g\/}. the addresses and lengths of the command lists and result lists, plus bookkeeping information to manage the transaction once it has been submitted to the hardware. Given that the LCB is an asynchronous device, with the queing of the IO occuring in one thread of execution and the servicing of the results possibly happening in another thread of execution, the XCB acts as the communication vehicle between these two threads.\hypertarget{A-Users-Guide_8Dox_Command_Response_Goals}{}\subsubsection{Command / Response - Goals}\label{A-Users-Guide_8Dox_Command_Response_Goals} The design goals of the Command / Response portion of the driver were\begin{enumerate} \item Limit the driver's scope to submitting command lists and managing responses\item Allow the users to construct, allocate and fill command lists at compile time or run time\end{enumerate} The second item is a corollary of the first. Here is an example of a statically defining the command list and dynamically allocating and filling it. Note that many of the intermediary structures are unnecessary, but the example wishes to illustrate, in a very pedantic fashion, how fully specify command and result lists are built from the available components.\hypertarget{A-Users-Guide_8Dox_LCBD_xcb_Example}{}\subsubsection{Example}\label{A-Users-Guide_8Dox_LCBD_xcb_Example} \begin{Code}\begin{verbatim} // Define the command items typedef struct _MyCmdItems { LCB_ci_mark_time mark1; // Issue a mark time command LCB_ci_csr csr; // Read the LATp-side CSR LCB_ci_mark_time mark2; // Issue another mark time command LCB_ci_faults faults; // Read the LATp-side FAULTs register } MyCmdItems; // Assemble into a command list typedef struct _MyCmdList { LCB_rl_hdr *hdr; // Reserved for the result list address MyCmdItems ci; // The command items } MyCmdList; // Define the corresponding result items typedef struct _MyRstItems { LCB_ri_mark_time mark1; // Result item for mark time command 1 LCB_ri_csr csr; // Result item for CSR access LCB_ci_mark_time mark2; // Result item for mark time command 2 LCB_ci_faults faults; // Result item for FAULTS register access } MyRstItems; // Assemble into a hardward result list typedef struct _LcbRstList { LCB_rl_hdr hdr; // LCB result list header MyRstItems ri; // The result items } LcbRstList; // Tack on the XCB that the driver needs typedef struct MyRstList { LCBD_xcb xcb; // The XCB control structure LcbRstList rl; // The LCB result list } MyRstList; LCBD_post_head head; // Synchronizing que head LCBD_xcb *xcb; // Allocate these // This could also be done off the stack (obeying proper alignment) MyCmdList *cl = LCBD_cl_alloc (sizeof (MyCmdList)); MyRstList *rl = LCBD_rl_alloc (sizeof (MyRstList)); // Use the inlines to fill the commands although the structures of // each command are exposed, so you could 'do it yourself' LCBC__mark_time_fill (&cl.ci.mark1, 200); LCBC__csr_access_fill (&cl.ci.csr, val, select, timeout); LCBC__mark_time_fill (&cl.ci.mark2, 400); LCBC__faults_access_fill (&cl.ci.cfaults, 0, -1, timeout); LCBD_post_create (lcb, &head) // Bind these parameters to a posting que synchronization method xcb = LCBD_post_bind (lcb, LCBD__cl_len (sizeof (*cl)), cl, LCBD__rl_len (sizeof (&rl->rl)), rl, &head, 0, 0, 0, 0); // Submit the transaction // Of course once the XCB transaction has been built, it can // be submitted at any later time. LCBD_submit (lcb, &xcb); // Wait for completion... // Again, there could be an arbitrary amount of code between the // LCBD_submit and the pending. (Warning, at least in this example // this memory for head is allocated on the stack, so the submission // and wait must be in this routine.) xcb = LCBD_post_pendW (lcb, &head); \end{verbatim} \end{Code} \hypertarget{A-Users-Guide_8Dox_LCBD_stats_h}{}\subsection{Statistics}\label{A-Users-Guide_8Dox_LCBD_stats_h} LCBD\_\-stats is the facitlity the LCBD driver uses to keep track of various counters in each of three major sections\begin{itemize} \item Interrupt Service Routine\item Event Handler\item Result Handler\end{itemize} The nature of the statistics is explained in detail in \hyperlink{LCBD__stats_8h}{LCBD\_\-stats.h}. From a more global perspective, the statistics are almost completely interlocked. That is, almos all consistency checks that can be performed without shutting down the driver. For example, without any special care, one can get a checksum over the number of transaction\begin{enumerate} \item Submitted\item Outstanding\item Completed along with details on how they were submitted (immediately or pended in the driver because the LCB's internal buffers were full) and the status of those completed.\end{enumerate} \begin{table}[h]\begin{TabularC}{2} \hline Function &Description \\\hline {\tt \hyperlink{LCBD__stats_8c_f4777e221cdf33e75db1e9b4099d5029}{LCBD\_\-stats\_\-clr}} &Clears the statistics counters \\\hline {\tt \hyperlink{LCBD__stats_8c_817583cd1a9a5b9e8217270c725f123d}{LCBD\_\-stats\_\-get}} &Gets a copy of the statistics counters \\\hline {\tt \hyperlink{LCBD__stats_8c_776a0354b23ceb1e331290f75e5cef0d}{LCBD\_\-stats\_\-sub}} &Subtracts two sets of statistics counters \\\hline {\tt \hyperlink{LCBD__stats_8c_7e7c6a4d5d9fa6a9f6eb67fab5e23678}{LCBD\_\-stats\_\-isr\_\-show}} &Displays the ISR statistics counters \\\hline {\tt \hyperlink{LCBD__stats_8c_eebbcc05387fd9e4ad1fcc1c1b4496e8}{LCBD\_\-stats\_\-evt\_\-show}} &Displays the EVENT statistics counters \\\hline {\tt \hyperlink{LCBD__stats_8c_b6030509e42c2a56333923a88822076e}{LCBD\_\-stats\_\-rst\_\-show}} &Displays the RESULT statistics counters \\\hline {\tt \hyperlink{LCBD__stats_8c_df2fd040f091a89fd7eb6a075b9c64dc}{LCBD\_\-stats\_\-show}} &Displays the all the statistics counters \\\hline \end{TabularC} \centering \caption{Statistics Routines} \end{table} \hypertarget{A-Users-Guide_8Dox_LCBD_cr_h}{}\subsection{Driver Specific Definitions of Command/Result Lists \& Items}\label{A-Users-Guide_8Dox_LCBD_cr_h} LCBD\_\-cr contains command and result list definitions and information that is dependent of the incarnation of the driver. Because of the way the LCB works, any driver must make available some additional information that is used to keep track of the command and result lists from the time the command list is submitted to the LCB hardware until the time the result list is returned to the CPU. More than anything else, the method of tying this information with a command/result list pair is what distinguishes one driver implementation from another. The method chosen in this version of the driver is the \hyperlink{A-Users-Guide_8Dox_LCBD_xcb_Overview}{LCBD\_\-xcb} structure mandated by driver to precede the result list.\hypertarget{A-Users-Guide_8Dox_LCBC_h}{}\subsection{Command Utilities}\label{A-Users-Guide_8Dox_LCBC_h} LCBC contains the prototypes and inline functions used to build individual command items and assemble them into command lists. It also contains aids in parsing both command items and command lists. From a purist's viewpoint, this should not be part of the driver, but, to avoid a small shareable containing only this and the related material in \hyperlink{LCBR_8h}{LCBR.h}, it has been included with LCBD. There are four groups of routines\begin{itemize} \item Command Parsing\item Synchronous Command Execution\item Command Item Filling, Callable Version\item Command Item Filling, Inline Version\end{itemize} \begin{table}[h]\begin{TabularC}{2} \hline Function &Description \\\hline {\tt \hyperlink{LCBC_8h_3c66ca243001e425ede57ad59291b21b}{LCBC\_\-process}} &Convenience routine to execute a user callback routine for each command item \\\hline {\tt \hyperlink{LCBC_8h_447fd073cae5c7da2991522fbe9a71e2}{LCBC\_\-show}} &Convenience routine to display each command item \\\hline \end{TabularC} \centering \caption{LCBC Command Routines, Command Parsing} \end{table} \begin{table}[h]\begin{TabularC}{3} \hline Function &Description \\\hline {\tt \hyperlink{LCBC_8h_4d554def122f3124e95e937af878b7fc}{LCBC\_\-mark\_\-time}} &Convenience routine to fill a {\em mark time\/} command item \\\hline {\tt \hyperlink{LCBC_8h_a704be79bb1a26274afad6913ed177b0}{LCBC\_\-cmd\_\-xmit}} &Convenience routine to fill a {\em LAT reset\/} command item& \\\hline {\tt \hyperlink{LCBC_8h_77e9ca256b3b39efdc4f709597777fdb}{LCBC\_\-lat\_\-reset}} &Convenience routine to fill a {\em command transmit with no response\/} command item \\\hline {\tt \hyperlink{LCBC_8h_7884b766c7567245e382832de1ff1748}{LCBC\_\-cmdr\_\-xmit}} &Convenience routine to fill a {\em command transmit with response\/} command item \\\hline {\tt \hyperlink{LCBC_8h_aac498e7073290eb1d41f7839cfed172}{LCBC\_\-csr\_\-access}} &Convenience routine to fill a {\em LATp-side CSR access\/} command item \\\hline {\tt \hyperlink{LCBC_8h_96383bdcc4e763e7d95dd45f419702c1}{LCBC\_\-faults\_\-access}} &Convenience routine to fill a {\em LATp-side FAULTS register access\/} command item \\\hline \end{TabularC} \centering \caption{LCBC Command Routines, Synchronous Execution} \end{table} \begin{table}[h]\begin{TabularC}{2} \hline Function &Description \\\hline {\tt \hyperlink{LCBC_8h_6137c799cdfe0026c3281bfd3adb1151}{LCBC\_\-mark\_\-time\_\-fill}} &Convenience routine to fill a {\em mark time\/} command item \\\hline {\tt \hyperlink{LCBC_8h_bfe481af7624fbab0bb29545a61939ba}{LCBC\_\-event\_\-fill}} &Convenience routine to fill a {\em event transmit\/} command item \\\hline {\tt \hyperlink{LCBC_8c_8ba9e7828ca4802c595cbf34c121eff2}{LCBC\_\-cmd\_\-xmit\_\-fill}} &Convenience routine to fill a {\em LAT reset\/} command item \\\hline {\tt \hyperlink{LCBC_8h_1197946ca13d186f2a8979030f4dc0df}{LCBC\_\-lat\_\-reset\_\-fill}} &Convenience routine to fill a {\em command transmit with no response\/} command item \\\hline {\tt \hyperlink{LCBC_8c_a4fe16396ac33a9544311c54f2da7dfd}{LCBC\_\-cmdr\_\-xmit\_\-fill}} &Convenience routine to fill a {\em command transmit with response\/} command item \\\hline {\tt \hyperlink{LCBC_8h_e033a01143b30a39a59d7b656c29e0e0}{LCBC\_\-csr\_\-access\_\-fill}} &Convenience routine to fill a {\em LATp-side CSR access\/} command item \\\hline {\tt \hyperlink{LCBC_8h_a424953e74e1b5fa792b74b0671c3543}{LCBC\_\-faults\_\-access\_\-fill}} &Convenience routine to fill a {\em LATp-side FAULTS register access\/} command item \\\hline \end{TabularC} \centering \caption{LCBC Command Fill Routines, Callable versions} \end{table} \begin{table}[h]\begin{TabularC}{2} \hline Function &Description \\\hline {\tt \hyperlink{LCBC_8h_60790d4e49af08627b8e7b6923e8b9d0}{LCBC\_\-\_\-mark\_\-time\_\-fill}} &Convenience routine to fill a {\em mark time\/} command item \\\hline {\tt \hyperlink{LCBC_8h_780ae4e530ed696d107bbf2f5142ad10}{LCBC\_\-\_\-event\_\-fill}} &Convenience routine to fill a {\em event transmit\/} command item \\\hline {\tt \hyperlink{LCBC_8h_544302cdc1988a3f278229a0625cfc2a}{LCBC\_\-\_\-cmd\_\-xmit\_\-fill}} &Convenience routine to fill a {\em LAT reset\/} command item \\\hline {\tt \hyperlink{LCBC_8h_fc933926749589ca672bf87d0bab9453}{LCBC\_\-\_\-lat\_\-reset\_\-fill}} &Convenience routine to fill a {\em command transmit with no response\/} command item \\\hline {\tt \hyperlink{LCBC_8h_0cea906097f5c4723cccd3eaed0a0bf4}{LCBC\_\-\_\-cmdr\_\-xmit\_\-fill}} &Convenience routine to fill a {\em command transmit with response\/} command item \\\hline {\tt \hyperlink{LCBC_8h_a159639af224de4a8ee59ca322bc4997}{LCBC\_\-\_\-csr\_\-access\_\-fill}} &Convenience routine to fill a {\em LATp-side CSR access\/} command item \\\hline {\tt \hyperlink{LCBC_8h_11709af9d2e139dea734dd670a270fa1}{LCBC\_\-\_\-faults\_\-access\_\-fill}} &Convenience routine to fill a {\em LATp-side FAULTS register access\/} command item \\\hline \end{TabularC} \centering \caption{LCBC Command Fill Routines, Inline versions} \end{table} \hypertarget{A-Users-Guide_8Dox_LCBC_Macros}{}\subsubsection{LCBC Macros}\label{A-Users-Guide_8Dox_LCBC_Macros} LCBC contains a number of macros useful in transversing and interpreting the command items in a command list. Mainly these map an OPCODE into\begin{itemize} \item Command type (simple, register access, command with response etc)\end{itemize} Note that one of the command types is \hyperlink{LCBC_8h_035efbb61caed515b3964429e00a355206d4826a9b0c1c9658e68013483144d6}{LCBC\_\-TYPE\_\-UNDEFINED}. This can be used to validate the opcode. Since the length is explicitly stored in a command item, there are no macros to translate an OPCODE to a length. The mapping macros come in two flavors, depending on whether one explicitly specifies the mapping word or lets the macro implicitly reference it. The latter is more efficient when the mapping word is used many times, saves reloading it each time, the former is just more convenient. Note that one must use LCBC in relation to command items, not result items. The type or length of a command item is not necessarily the same as the type or length of its corresponding result item. \begin{table}[h]\begin{TabularC}{2} \hline Macro &Description \\\hline {\tt \hyperlink{LCBC_8h_4588c05b2c5e0718e7eb003a26a802c2}{LCBC\_\-TYPE\_\-BY\_\-OPCODE\_\-FULL}} &Translates an opcode to a command item type, mapping word is explicitly specified \\\hline {\tt \hyperlink{LCBC_8h_4694ec607ca844589742f473ae636c16}{LCBC\_\-TYPE\_\-BY\_\-OPCODE}} &Translates an opcode to a command item type, mapping word is implicit \\\hline \end{TabularC} \centering \caption{LCBC Macros} \end{table} \hypertarget{A-Users-Guide_8Dox_LCBR_h}{}\subsection{Result (Response) Utilities}\label{A-Users-Guide_8Dox_LCBR_h} LCBR is a collection of utilities to aid in the construction and parsing of the result lists and result items. These are really just convenience routines. The user has enough information to write these himself. The driver wishes to maintain its distance from dealing with the individual result items. The routines in LCBR were written because they provide functionality of widespread interest. They were bundled in with the LCBD package for lack of a better place. (They are really not part of the driver, but they have no other good home.) Note that one must use LCBR in relation to result items, not command items. The type or length of a result item is not necessarily the same as the type or length of its corresponding command item. \begin{table}[h]\begin{TabularC}{2} \hline Function &Description \\\hline {\tt \hyperlink{LCBR_8c_cc2afe46c148553746441e098f3544f7}{LCBR\_\-check}} &Convenience routine to check each result item for errors \\\hline {\tt \hyperlink{LCBR_8c_778cc23a80af140c22f7d20e8f0e6ffb}{LCBR\_\-error\_\-get}} &Convenience routine to get the error word for a result item \\\hline {\tt \hyperlink{LCBR_8c_da0bf9551035dfd00933eaf3e7a314c4}{LCBR\_\-process}} &Convenience routine to execute a user callback routine for each result item \\\hline {\tt \hyperlink{LCBR_8c_f2e1ea7c3b83f0da926a5ca308df98ea}{LCBR\_\-show}} &Convenience routine to display each result item \\\hline \end{TabularC} \centering \caption{LCBR Result Routines, Result List/Item Parsing} \end{table} \hypertarget{A-Users-Guide_8Dox_LCBR_Macros}{}\subsection{LCBR Macros}\label{A-Users-Guide_8Dox_LCBR_Macros} LCBR contains a number of macros useful in transversing and interpreting the result items in a result list. Mainly these map an OPCODE into\begin{itemize} \item Result type (simple, register access, command with response etc)\item Length in cells\end{itemize} Note that one of the result types is LCBR\_\-TYPE\_\-UNDEFINED. This can be used to validate the opcode. The mapping macros come in two flavors, depending on whether on explicitly specifies the mapping word or lets the macro implicitly reference it. The latter is more efficient when the mapping word is used many times, saves reloading it each time, the former is just more convenient. \begin{table}[h]\begin{TabularC}{2} \hline Macro &Description \\\hline {\tt \hyperlink{LCBR_8h_0fdff35b4725726cd666b5d366c7867b}{LCBR\_\-TYPE\_\-BY\_\-OPCODE\_\-FULL}} &Translates an opcode to a command item type, mapping word specified \\\hline {\tt \hyperlink{LCBR_8h_0fdff35b4725726cd666b5d366c7867b}{LCBR\_\-TYPE\_\-BY\_\-OPCODE\_\-FULL}} &Translates an opcode to a result item type, mapping word is implicit \\\hline {\tt \hyperlink{LCBR_8h_b96a237c0b8efd8630684893dfa28013}{LCBR\_\-N8BYTES\_\-BY\_\-OPCODE\_\-FULL}} &Translates an opcode to a result item length in 8-byte cells, mapping word is specified \\\hline {\tt \hyperlink{LCBR_8h_c6cb154868cae947d37bc5c4e9012afc}{LCBR\_\-N8BYTES\_\-BY\_\-OPCODE}} &Translates an opcode to a result item length in 8-byte cells, mapping word is implicit \\\hline \end{TabularC} \centering \caption{LCBR Macros} \end{table} \hypertarget{A-Users-Guide_8Dox_LCBD_msgs_h}{}\subsection{MSG codes}\label{A-Users-Guide_8Dox_LCBD_msgs_h} LCBD\_\-msgs is the standard include generated by the MSG utility containing all the LCBD return code values.\hypertarget{A-Users-Guide_8Dox_LCB_h}{}\subsection{LCB Definitions}\label{A-Users-Guide_8Dox_LCB_h} \hyperlink{LCB_8h}{LCB.h} is almost a 'C' transcription of Mike Huffer's LCB document, LAT-TD-0860. Details of the command/response unit have been isolated to LCB\_\-cr because of their shear size.\hypertarget{A-Users-Guide_8Dox_LCB_cr_h}{}\subsection{Command \& Result Lists and Item LCB Definitions}\label{A-Users-Guide_8Dox_LCB_cr_h} LCB\_\-cr contains the hardware ddefinitions of all command items/lists and result items/lists. It also contains macros that can be used to build your own command export descriptors and initialize command items. It is split off from \hyperlink{LCB_8h}{LCB.h} simply because of shear size, the combination of the two is fairly massive. \begin{table}[h]\begin{TabularC}{2} \hline Macro &Description \\\hline {\tt \hyperlink{LCB__cr_8h_b01395d17daade51ec676ad22abdaac9}{LCB\_\-CI\_\-HDR}} &Composes the command item header word \\\hline {\tt \hyperlink{LCB__cr_8h_f7c010b4885ca21a864d1f3757e08fbd}{LCB\_\-CI\_\-CMD}} &Composes the a transmit command item initializing data statement \\\hline {\tt \hyperlink{LCB__cr_8h_6f409e2c231447e7c1e736bbf0df5401}{LCB\_\-CI\_\-MARK\_\-TIME}} &Composes the a mark command item initializing data statement \\\hline {\tt \hyperlink{LCB__cr_8h_f1d03161e2801db127ba0fda9f804c71}{LCB\_\-CI\_\-LAT\_\-RESET}} &Composes the a lat reset command item initializing data statement \\\hline {\tt \hyperlink{LCB__cr_8h_993f110b29d0a5cdba76cfb58cefe686}{LCB\_\-CI\_\-CSR}} &Composes the a csr access command item data statement \\\hline {\tt \hyperlink{LCB__cr_8h_cd3db732b2ced64cb885b870bf74d5c6}{LCB\_\-CI\_\-FAULTS}} &Composes the a faults command item data statement \\\hline {\tt \hyperlink{LCB__cr_8h_6571097f95f93f3fa87be32deeaae0cb}{LCB\_\-CI\_\-EVENT\_\-LEN\_\-32}} &Rounds a specified number of integers to the next highest LATP number of cells, returning the answer in integers. Useful for specifying the length to a Event Transfer Command \\\hline \end{TabularC} \centering \caption{LCB\_\-cr Macros} \end{table} \hypertarget{A-Users-Guide_8Dox_LATP_h}{}\subsection{LAT Protocol Definitions}\label{A-Users-Guide_8Dox_LATP_h} LATP contains the various LATp definitions. This is almost a 'C' transcription from the hardware documentation.