\hypertarget{LCBB_8c}{ \section{LCBB.c File Reference} \label{LCBB_8c}\index{LCBB.c@{LCBB.c}} } LCB polled mode interface routines. {\tt \#include $<$string.h$>$}\par {\tt \#include \char`\"{}PBS/SPIN.h\char`\"{}}\par {\tt \#include \char`\"{}PBS/SPIN.ih\char`\"{}}\par {\tt \#include \char`\"{}PBS/BSWP.ih\char`\"{}}\par {\tt \#include \char`\"{}LCBD/LCBB.h\char`\"{}}\par {\tt \#include \char`\"{}LCBD/LATP.h\char`\"{}}\par {\tt \#include \char`\"{}LCBD/LCBB\_\-msgs.h\char`\"{}}\par {\tt \#include \char`\"{}LCBD/LCB\_\-cr.h\char`\"{}}\par \subsection*{Classes} \begin{CompactItemize} \item struct \hyperlink{struct__LCBB__err__rst__maps}{\_\-LCBB\_\-err\_\-rst\_\-maps} \begin{CompactList}\small\item\em Maps to take a result transfer/receive error/status value, into a standard message code. \item\end{CompactList}\item struct \hyperlink{struct__LCBB__err__evt__maps}{\_\-LCBB\_\-err\_\-evt\_\-maps} \begin{CompactList}\small\item\em Maps to take an event transfer/receive error/status value, into a standard message code. \item\end{CompactList}\item struct \hyperlink{struct__LCBB__err__maps}{\_\-LCBB\_\-err\_\-maps} \begin{CompactList}\small\item\em Provides mapping arrays to take an LCB hardware error code into a LCB message code. \item\end{CompactList}\end{CompactItemize} \subsection*{Defines} \begin{CompactItemize} \item \#define \hyperlink{LCBB_8c_233151eb5f4af741bbaa1b8b8e7aaaae}{CHECK\_\-EQ}(n, a, b)~struct Check\_\- \#\# n \{ int x\mbox{[}1 / (a == b) \mbox{]}; \} \begin{CompactList}\small\item\em Checks is a = b, and if not the compiler will issue an error. \item\end{CompactList}\item \hypertarget{LCBB_8c_f37040b347566bf5a9a6896219789de1}{ \#define \hyperlink{LCBB_8c_f37040b347566bf5a9a6896219789de1}{LCBB\_\-XTIME\_\-REGISTER}~10000} \label{LCBB_8c_f37040b347566bf5a9a6896219789de1} \begin{CompactList}\small\item\em Estimate of a register access time, in nanoseconds. \item\end{CompactList}\item \hypertarget{LCBB_8c_9b7416db50ad84f60c42123e8f10519a}{ \#define \hyperlink{LCBB_8c_9b7416db50ad84f60c42123e8f10519a}{LCBB\_\-XTIME\_\-FUNCTION}~10000} \label{LCBB_8c_9b7416db50ad84f60c42123e8f10519a} \begin{CompactList}\small\item\em Estimate of a function execution time, in nanoseconds. \item\end{CompactList}\item \hypertarget{LCBB_8c_bab17062a296dacbc088515ab50d20f8}{ \#define \hyperlink{LCBB_8c_bab17062a296dacbc088515ab50d20f8}{LCBB\_\-XTIME\_\-EVENT\_\-TRANSFER}~10000} \label{LCBB_8c_bab17062a296dacbc088515ab50d20f8} \begin{CompactList}\small\item\em Estimate of a event transfer overhead, in nanoseconds. \item\end{CompactList}\item \hypertarget{LCBB_8c_9bf48f0d85da988787db3e62ae698fc9}{ \#define \hyperlink{LCBB_8c_9bf48f0d85da988787db3e62ae698fc9}{LCBB\_\-XTIME\_\-TIMEOUT}~60000000} \label{LCBB_8c_9bf48f0d85da988787db3e62ae698fc9} \begin{CompactList}\small\item\em Estimate of LCB event transfer timeout period. \item\end{CompactList}\item \hypertarget{LCBB_8c_aa70dd0a8684faf15a7a264303936e75}{ \#define \hyperlink{LCBB_8c_aa70dd0a8684faf15a7a264303936e75}{LCBB\_\-CLK\_\-FREQ}~20000000} \label{LCBB_8c_aa70dd0a8684faf15a7a264303936e75} \begin{CompactList}\small\item\em The default LCB LATp clock frequency (nominally 20MHz). \item\end{CompactList}\item \hypertarget{LCBB_8c_857ae1cae2d3a54d079621f484a1f941}{ \#define \hyperlink{LCBB_8c_857ae1cae2d3a54d079621f484a1f941}{LCBB\_\-NSECS\_\-PER\_\-TICK}~50} \label{LCBB_8c_857ae1cae2d3a54d079621f484a1f941} \begin{CompactList}\small\item\em The default LCB LATp clock speed (nominally 20MHz = 50nsec/tick). \item\end{CompactList}\item \hypertarget{LCBB_8c_db1ff086be2bf45ff1dfbc561e8cc09c}{ \#define \hyperlink{LCBB_8c_db1ff086be2bf45ff1dfbc561e8cc09c}{LCBB\_\-BITS\_\-PER\_\-TICK}~1} \label{LCBB_8c_db1ff086be2bf45ff1dfbc561e8cc09c} \begin{CompactList}\small\item\em The default LCB DMA output transfer speed. This is always 1 bit/tick (20Mbits/sec) independent of the bit/byte of the input interface. \item\end{CompactList}\item \hypertarget{LCBB_8c_12652916fca1d5266304bf37d52fd9c9}{ \#define \hyperlink{LCBB_8c_12652916fca1d5266304bf37d52fd9c9}{LCBB\_\-RST\_\-DRAIN\_\-TIMEOUT}~((unsigned int)(3 $\ast$ LCBB\_\-CLK\_\-FREQ))} \label{LCBB_8c_12652916fca1d5266304bf37d52fd9c9} \begin{CompactList}\small\item\em The result drain timeout period, in units of LCBB clock ticks. This is the maximum time that the function will wait for the sweeping transaction to be returned. \item\end{CompactList}\item \#define \hyperlink{LCBB_8c_21b00b1e2872c2c88e6980208268d664}{LCBB\_\-XTIME\_\-EVENT\_\-TRANSFER\_\-BY\_\-INTS}(\_\-nints) \begin{CompactList}\small\item\em Estimates the time to get submit and get the result descriptor back for an event transfer of {\em \_\-nints\/}. \item\end{CompactList}\end{CompactItemize} \subsection*{Typedefs} \begin{CompactItemize} \item \hypertarget{LCBB_8c_c7cf3aabc757dcc5ca543dd4f71210bd}{ typedef struct \hyperlink{struct__LCBB__err__rst__maps}{\_\-LCBB\_\-err\_\-rst\_\-maps} \hyperlink{LCBB_8c_c7cf3aabc757dcc5ca543dd4f71210bd}{LCBB\_\-err\_\-rst\_\-maps}} \label{LCBB_8c_c7cf3aabc757dcc5ca543dd4f71210bd} \begin{CompactList}\small\item\em Typedef for struct {\em \hyperlink{struct__LCBB__err__rst__maps}{\_\-LCBB\_\-err\_\-rst\_\-maps}\/}. \item\end{CompactList}\item \hypertarget{LCBB_8c_60826aa02ec2586e7c4e81c36865e944}{ typedef struct \hyperlink{struct__LCBB__err__evt__maps}{\_\-LCBB\_\-err\_\-evt\_\-maps} \hyperlink{LCBB_8c_60826aa02ec2586e7c4e81c36865e944}{LCBB\_\-err\_\-evt\_\-maps}} \label{LCBB_8c_60826aa02ec2586e7c4e81c36865e944} \begin{CompactList}\small\item\em Typedef for struct {\em \hyperlink{struct__LCBB__err__evt__maps}{\_\-LCBB\_\-err\_\-evt\_\-maps}\/}. \item\end{CompactList}\item typedef struct \hyperlink{struct__LCBB__err__maps}{\_\-LCBB\_\-err\_\-maps} \hyperlink{LCBB_8c_eb66392c345cc8681eb22853e3250df7}{LCBB\_\-err\_\-maps} \begin{CompactList}\small\item\em Typedef for struct {\em \hyperlink{struct__LCBB__err__maps}{\_\-LCBB\_\-err\_\-maps}\/}. \item\end{CompactList}\end{CompactItemize} \subsection*{Functions} \begin{CompactItemize} \item static \_\-\_\-inline void \hyperlink{LCBB_8c_22c86496f160ebc87f14583736324ee9}{pciStore32} (volatile unsigned int $\ast$dst, unsigned int w) \begin{CompactList}\small\item\em Write a 32-bit integer to PCI Memory. \item\end{CompactList}\item static \_\-\_\-inline unsigned int \hyperlink{LCBB_8c_24006b0f3ad5623b41e0487be99becb5}{pciLoad32} (volatile unsigned int $\ast$src) \begin{CompactList}\small\item\em Read a 32-bit integer from PCI Memory. \item\end{CompactList}\item static \_\-\_\-inline unsigned int \hyperlink{LCBB_8c_7872fe38b4f816efbfd3d4c936437233}{clear\_\-faults} (\hyperlink{struct__LCBB}{LCBB} lcb, unsigned short timeout) \begin{CompactList}\small\item\em Clears the FIFO faults register. \item\end{CompactList}\item static unsigned int \hyperlink{LCBB_8c_e84804dd1fc3dadc0f258d19055a6afd}{access\_\-function} (\hyperlink{struct__LCBB}{LCBB} lcb, unsigned short stall, unsigned int header, unsigned int poll\_\-timeout) \begin{CompactList}\small\item\em Performs an access to the specified LCB slave-side LATP function. \item\end{CompactList}\item static unsigned int \hyperlink{LCBB_8c_3856c5c8f105268f69e27edeef794412}{access\_\-reg} (\hyperlink{struct__LCBB}{LCBB} lcb, unsigned int value, unsigned int field\_\-select, unsigned short int stall, unsigned int $\ast$prv, unsigned int $\ast$cur, unsigned int header, unsigned int poll\_\-timeout) \begin{CompactList}\small\item\em Performs an access to the specified LCB slave-side LATP register. \item\end{CompactList}\item static unsigned int \hyperlink{LCBB_8c_ba641905848700c4f0b0d42512624c31}{poll} (\hyperlink{struct__LCBB}{LCBB} lcb, unsigned int poll\_\-period, unsigned int timeout, unsigned short int op\_\-len, const void $\ast$result, const \hyperlink{union__LCB__ri__err}{LCB\_\-ri\_\-err} $\ast$ri\_\-err) \begin{CompactList}\small\item\em Polls the RESULT FIFO every {\em nsecs\/} for @ iterations. \item\end{CompactList}\item static \_\-\_\-inline unsigned int \hyperlink{LCBB_8c_c8e6fb49f15305c0099deda634594ec1}{submit} (\hyperlink{struct__LCBB}{LCBB} lcb, unsigned int request) \begin{CompactList}\small\item\em Submits the specified request list to the LCB for execution. \item\end{CompactList}\item static unsigned int \hyperlink{LCBB_8c_5d19762d461213e3d7eb9fb42423d908}{execute} (\hyperlink{struct__LCBB}{LCBB} lcb, unsigned int request, unsigned int xtime, unsigned int timeout, unsigned short int op\_\-len, void $\ast$result, \hyperlink{union__LCB__ri__err}{LCB\_\-ri\_\-err} $\ast$ri\_\-err) \begin{CompactList}\small\item\em Has the LCB's command execution routine execute the specified single item request. The result list and result item is checked for successful completion. \item\end{CompactList}\item static unsigned int \hyperlink{LCBB_8c_a88d21b146a806e92e37d2df73aa9758}{init\_\-pci} (\hyperlink{struct__LCBB}{LCBB} lcb) \begin{CompactList}\small\item\em Initializes the LCB structure -- probes the PCI bus. \item\end{CompactList}\item static unsigned int \hyperlink{LCBB_8c_49a381c3e3b445cd75b0eeda2c1b0cfd}{init\_\-latp} (\hyperlink{struct__LCBB}{LCBB} lcb) \begin{CompactList}\small\item\em Laundry list of LCB initializations to do on the LATp side. \item\end{CompactList}\item static void \hyperlink{LCBB_8c_c72af620b4dbede22dacb4397af0b8e0}{init\_\-circ} (\hyperlink{struct__LCBB}{LCBB} lcb) \begin{CompactList}\small\item\em Allocates memory for and sets it up to be used as the circular buffer. \item\end{CompactList}\item static unsigned int \hyperlink{LCBB_8c_7493e5c6d6c92fdafd0efa90f268d0ca}{drain\_\-result} (\hyperlink{struct__LCBB}{LCBB} lcb) \begin{CompactList}\small\item\em Drains the result FIFOs. \item\end{CompactList}\item static unsigned int \hyperlink{LCBB_8c_a1ce5f13daec65571e07e61e1ce5c6e6}{drain\_\-event} (\hyperlink{struct__LCBB}{LCBB} lcb) \begin{CompactList}\small\item\em Drains the event FIFOs. \item\end{CompactList}\item static \_\-\_\-inline unsigned int \hyperlink{LCBB_8c_617fb732602d0c570bc5a7eb330d17c4}{mapXfrErr} (const \hyperlink{struct__LCBB__err__rst__maps}{LCBB\_\-err\_\-rst\_\-maps} $\ast$maps, unsigned int err) \begin{CompactList}\small\item\em Maps a result descriptor status into an error code. \item\end{CompactList}\item static \_\-\_\-inline unsigned int \hyperlink{LCBB_8c_9b1780d2fe1aca60226dac3b5ad92bd7}{mapRcvErr} (const \hyperlink{struct__LCBB__err__rst__maps}{LCBB\_\-err\_\-rst\_\-maps} $\ast$maps, unsigned int err) \begin{CompactList}\small\item\em Maps a result item status into an error code. \item\end{CompactList}\item \hyperlink{struct__LCBB}{LCBB} \hyperlink{LCBB_8c_814d9a6e7c203340dfd8ffd736788949}{LCBB\_\-configure} (unsigned int latp, void $\ast$requestList, void $\ast$resultList, void $\ast$circBuffer) \begin{CompactList}\small\item\em Returns a pointer to the LCB control structure, with the specified configuration parameters. \item\end{CompactList}\item unsigned int \hyperlink{LCBB_8c_274bbba0ccab6e57d6118d529686a18b}{LCBB\_\-init} (\hyperlink{struct__LCBB}{LCBB} lcb) \begin{CompactList}\small\item\em Initializes the LCB structure for polled mode. \item\end{CompactList}\item unsigned int \hyperlink{LCBB_8c_9aeac0985e57b03bee8105fa728bdaf0}{LCBB\_\-check} (\hyperlink{struct__LCBB}{LCBB} lcb, \hyperlink{struct__LCBB__msg}{LCBB\_\-msg} $\ast$msg) \begin{CompactList}\small\item\em Maps the LCB error codes to a LCB message code. \item\end{CompactList}\item unsigned int \hyperlink{LCBB_8c_297245fb70e13fdcc6e67cfd2ab278d7}{LCBB\_\-free} (\hyperlink{struct__LCBB}{LCBB} lcb, \hyperlink{struct__LCBB__msg}{LCBB\_\-msg} $\ast$msg) \item unsigned char $\ast$ \hyperlink{LCBB_8c_f30a0e6e8f1373b7a4c6171a093e16c6}{LCBB\_\-locate} (\hyperlink{struct__LCBB}{LCBB} lcb) \begin{CompactList}\small\item\em Returns a pointer to payload. \item\end{CompactList}\item \hyperlink{struct__LCBB__msg}{LCBB\_\-msg} $\ast$ \hyperlink{LCBB_8c_63ad41af674f118d25a69927cb6b578d}{LCBB\_\-receive} (\hyperlink{struct__LCBB}{LCBB} lcb) \begin{CompactList}\small\item\em Reads the event FIFO for descriptors. \item\end{CompactList}\item unsigned int \hyperlink{LCBB_8c_4191806e8b3d12bae7317ff0e3488e89}{LCBB\_\-send} (\hyperlink{struct__LCBB}{LCBB} lcb, unsigned int dst, unsigned int proto, int nbytes) \begin{CompactList}\small\item\em Sends the data. \item\end{CompactList}\item unsigned int \hyperlink{LCBB_8c_f8cdc8ade2d6c7300c9dd84a808a2485}{LCBB\_\-start} (\hyperlink{struct__LCBB}{LCBB} lcb) \begin{CompactList}\small\item\em Enables the LCB for taking event data. \item\end{CompactList}\item unsigned int \hyperlink{LCBB_8c_77a4ad4a617f3e2c156a8783a9de2304}{LCBB\_\-mark\_\-time} (\hyperlink{struct__LCBB}{LCBB} lcb, unsigned short int stall) \begin{CompactList}\small\item\em Issues a Mark Time command to the LCB. \item\end{CompactList}\item unsigned int \hyperlink{LCBB_8c_bdc54b261314c032000fe07fe17f3b52}{LCBB\_\-lat\_\-reset} (\hyperlink{struct__LCBB}{LCBB} lcb, unsigned short int stall) \begin{CompactList}\small\item\em Issues a LAT reset. \item\end{CompactList}\item unsigned int \hyperlink{LCBB_8c_97e836cc02dc9d240a69e25b5c461836}{LCBB\_\-csr\_\-access} (\hyperlink{struct__LCBB}{LCBB} lcb, unsigned int value, unsigned int field\_\-select, unsigned short int timeout, unsigned int $\ast$prv, unsigned int $\ast$cur) \begin{CompactList}\small\item\em Does an access of the LATp CSR register. \item\end{CompactList}\item unsigned int \hyperlink{LCBB_8c_a7ae90cfc3015d65a4b20335970c2822}{LCBB\_\-faults\_\-access} (\hyperlink{struct__LCBB}{LCBB} lcb, unsigned int value, unsigned int field\_\-select, unsigned short int timeout, unsigned int $\ast$prv, unsigned int $\ast$cur) \begin{CompactList}\small\item\em Does an access of the LATp CSR register. \item\end{CompactList}\item unsigned int \hyperlink{LCBB_8c_308d7b59876efb9e784ed4f15616b065}{LCBB\_\-rxstats\_\-access} (\hyperlink{struct__LCBB}{LCBB} lcb, unsigned int value, unsigned int field\_\-select, unsigned short int timeout, unsigned int $\ast$prv, unsigned int $\ast$cur) \begin{CompactList}\small\item\em Does an access of the LATp Receive Statistics/Status register. \item\end{CompactList}\end{CompactItemize} \subsection*{Variables} \begin{CompactItemize} \item \hypertarget{LCBB_8c_f46d454e0f9f1c0da0095ab19348a3f0}{ static const \hyperlink{struct__LCBB__err__maps}{LCBB\_\-err\_\-maps} \hyperlink{LCBB_8c_f46d454e0f9f1c0da0095ab19348a3f0}{LcbbErrMaps}} \label{LCBB_8c_f46d454e0f9f1c0da0095ab19348a3f0} \begin{CompactList}\small\item\em Realization of the LCB error to message code mapping arrays. \item\end{CompactList}\item \hypertarget{LCBB_8c_759625111ff66d491d3f0dafcfdb02c1}{ struct \hyperlink{struct__LCBB}{\_\-LCBB} \hyperlink{LCBB_8c_759625111ff66d491d3f0dafcfdb02c1}{Lcbb}} \label{LCBB_8c_759625111ff66d491d3f0dafcfdb02c1} \begin{CompactList}\small\item\em The LCB driver control block. \item\end{CompactList}\end{CompactItemize} \subsection{Detailed Description} LCB polled mode interface routines. \begin{Desc} \item[Author:]Curt Brune -- \href{mailto:curt@slac.stanford.edu}{\tt curt@slac.stanford.edu} JJRussell -- \href{mailto:russell@slac.stanford.edu}{\tt russell@slac.stanford.edu}\end{Desc} \footnotesize\begin{verbatim} CVS $Id \end{verbatim} \normalsize \begin{Desc} \item[Overview]This one file is the total implementation of the boot mode driver.\end{Desc} \begin{Desc} \item[]This driver implements only enough of the LCB functionality to perform the boot phase. As one expects in a boot mode driver, it is a completely synchronous version of the driver. In addition, or perhaps one should say, in subtraction, it does not provide any help in building command lists or parsing the corresponding result lists. Of course, nothing precludes the user from doing this, and, it is in fact, quite easy to do, see \hyperlink{LCB__cr_8h}{LCB\_\-cr.h} for all the relevant definitions.\end{Desc} \begin{Desc} \item[Anticipated Usage]Except for the initialization phase, the only anticipated functionality is to send and receive bulk messages over the event fabric. While not precluded, the boot code likley has no desire or need to use the command/response fabric nor even the internal registers after the initialization phase. However, given that these are used internally, an interface to a limited set of the LATp side functionality and registers is provided.\end{Desc} \begin{Desc} \item[Modularity Requirements]Given that there is only one customer for this code (the EPU boot code) and given that this code is directly linked into the boot code, the modularity requirements are greatly lessened. To this end, the LCBB control block is exposed, allowing the user to access its members. In particular items that may be of interest are\end{Desc} \begin{itemize} \item The PCI side FPGA version number (lcb\_\-rev)\item The LATp side FPGA version number (latp\_\-rev)\item The memory map to the LCB PCI side registers\item Transaction type counters and a trace buffer\end{itemize} \begin{Desc} \item[Warning:]Using the memory map, one can directly access the PCI side registers. Please to use this capability in a read-only fashion. Although the driver is currently stateless, future versions may not be. If writes are performed to the PCI registers outside the context of the driver, a mismatch between the hardware and software can occur.\end{Desc} \begin{Desc} \item[]Please also note that one should exercise caution when reading the various queues, since the act of reading removes an item on the queue that the driver may have reason to believe is there. Again this can cause an inconsistency between the hardware and the software.\end{Desc} \begin{Desc} \item[Warning:]These is one feature of the initialization sequence that may be an issue. When draining the result queue, any rogue and NULL descriptor transactions are somewhat quietly dismissed. The drain function does counts such transactions,lcbb-$>$rogue\_\-count and lcbb-$>$null\_\-count and stores them (at least the most recent 8) in its transaction trace (history) buffer.\end{Desc} \begin{Desc} \item[]The cause of concern is that the poll loop times-out after a fixed amount of time. If the loop expends this time servicing a large number of NULL or rogue descriptors, this could leave the transaction used to sweep any stale transactions left lingering in the result queue, itself becoming a stale transaction. While in principle this is a problem (since NULL descriptors are the end-product of unsolicited and externally issued LAM commands, see the next paragraph for more information on NULL descriptors) in practice, this can only be a problem if the\begin{enumerate} \item The source issuing these LAMs is out of control\item The LCB hardware is broken \end{enumerate} \end{Desc} \begin{Desc} \item[]So far, all proposed solutions to this problem appear to be worse than the disease.\end{Desc} \begin{Desc} \item[NULL Descriptors]NULL descriptors are the result of a LAM message being sent to the LCB by another CPU. As long as the sender does not send continuous LAMs, the NULL descriptors will eventually drain. The most probable cause of them not draining is broken hardware. Given that this code executes in the boot phase, there is little one can do to recover. Checking the counters and the history buffers can help in diagnosing the root cause.\end{Desc} \begin{Desc} \item[Rogue Descriptors]Rogue Descriptors are result descriptors that the code is not expecting. Rogue descriptors do not lead to the same problems as NULL descriptors. Such descriptors are the result of commands issued by the host CPU, but which software has lost track of, likely because of a reboot being issued between the time they were submitted to the hardware and the time the hardware returned them in the result que. Because such commands are knowingly issued by the host CPU and because the LCB hardware itself has a limit of approximately 10-13 transaction that it can internally hold, the drain time of such transaction is finite and more under the control of the host CPU.\end{Desc} \begin{Desc} \item[Trace History Buffer]In order to keep aid in diagnostics and debugging, the LCBB driver maintains a trace buffer of the last 8 (or so) non-timeout result descriptors returned. While, in principle, each transaction should produce only one such trace record, in practice the driver must be handle, the case where the expected result descriptor is not the first non-timeout descriptor received. It may instead find either a NULL descriptor or a rogue descriptor. Each trace record includes a transaction sequence number. The rare case where multiple descriptors are encountered while polling for a result can be recognized because all will have the same transaction sequence number. \end{Desc} \subsection{Define Documentation} \hypertarget{LCBB_8c_233151eb5f4af741bbaa1b8b8e7aaaae}{ \index{LCBB.c@{LCBB.c}!CHECK_EQ@{CHECK\_\-EQ}} \index{CHECK_EQ@{CHECK\_\-EQ}!LCBB.c@{LCBB.c}} \subsubsection{\setlength{\rightskip}{0pt plus 5cm}\#define CHECK\_\-EQ(n, a, b)~struct Check\_\- \#\# n \{ int x\mbox{[}1 / (a == b) \mbox{]}; \}}} \label{LCBB_8c_233151eb5f4af741bbaa1b8b8e7aaaae} Checks is a = b, and if not the compiler will issue an error. \begin{Desc} \item[Parameters:] \begin{description} \item[{\em n}]Unique identifying string (helps isolate the error) \item[{\em a}]The value to check \item[{\em b}]The value to check\end{description} \end{Desc} \begin{Desc} \item[]This is a trick used to generate a compile time error when a compile time assumption has been violated. \end{Desc} \hypertarget{LCBB_8c_21b00b1e2872c2c88e6980208268d664}{ \index{LCBB.c@{LCBB.c}!LCBB_XTIME_EVENT_TRANSFER_BY_INTS@{LCBB\_\-XTIME\_\-EVENT\_\-TRANSFER\_\-BY\_\-INTS}} \index{LCBB_XTIME_EVENT_TRANSFER_BY_INTS@{LCBB\_\-XTIME\_\-EVENT\_\-TRANSFER\_\-BY\_\-INTS}!LCBB.c@{LCBB.c}} \subsubsection{\setlength{\rightskip}{0pt plus 5cm}\#define LCBB\_\-XTIME\_\-EVENT\_\-TRANSFER\_\-BY\_\-INTS(\_\-nints)}} \label{LCBB_8c_21b00b1e2872c2c88e6980208268d664} \textbf{Value:} \begin{Code}\begin{verbatim}(LCBB_XTIME_EVENT_TRANSFER \ + (((_nints) * 32) * LCBB_NSECS_PER_TICK) / LCBB_BITS_PER_TICK); \end{verbatim} \end{Code} Estimates the time to get submit and get the result descriptor back for an event transfer of {\em \_\-nints\/}. \begin{Desc} \item[]The time for the result descriptor to be returned is \footnotesize\begin{verbatim} time = Submit_Time + Pci_Dma_Time + Lat_Dma_Time + Lcb_timeout + Lat_Result_Dsc_Write + Pci_Result_Dsc_Write \end{verbatim} \normalsize \end{Desc} \begin{Desc} \item[]This breaks into 2 pieces, a fixed piece and a piece proportional to the amount of data being sent. \footnotesize\begin{verbatim} Fixed_Time = Submit_Time + Lat_Result_Dsc_Write + Pci_Result_Dsc_Write Dma_Time = Pci_Dma_Time + Lat_Dma_Time \end{verbatim} \normalsize \end{Desc} \begin{Desc} \item[]The PCI DMA term will be ignore since it is so much faster (about a factor of 50) that, for purposes of this estimate it will be ignored. \end{Desc} \subsection{Typedef Documentation} \hypertarget{LCBB_8c_eb66392c345cc8681eb22853e3250df7}{ \index{LCBB.c@{LCBB.c}!LCBB_err_maps@{LCBB\_\-err\_\-maps}} \index{LCBB_err_maps@{LCBB\_\-err\_\-maps}!LCBB.c@{LCBB.c}} \subsubsection{\setlength{\rightskip}{0pt plus 5cm}{\bf LCBB\_\-err\_\-maps}}} \label{LCBB_8c_eb66392c345cc8681eb22853e3250df7} Typedef for struct {\em \hyperlink{struct__LCBB__err__maps}{\_\-LCBB\_\-err\_\-maps}\/}. Combines the {\em Result\/} and {\em Event\/} mapping data structures \subsection{Function Documentation} \hypertarget{LCBB_8c_e84804dd1fc3dadc0f258d19055a6afd}{ \index{LCBB.c@{LCBB.c}!access_function@{access\_\-function}} \index{access_function@{access\_\-function}!LCBB.c@{LCBB.c}} \subsubsection{\setlength{\rightskip}{0pt plus 5cm}static unsigned int access\_\-function ({\bf LCBB} {\em lcb}, unsigned short {\em stall}, unsigned int {\em header}, unsigned int {\em poll\_\-timeout})\hspace{0.3cm}{\tt \mbox{[}static\mbox{]}}}} \label{LCBB_8c_e84804dd1fc3dadc0f258d19055a6afd} Performs an access to the specified LCB slave-side LATP function. \begin{Desc} \item[Returns:]Status\end{Desc} \begin{Desc} \item[Parameters:] \begin{description} \item[{\em lcb}]The LCB driver handle \item[{\em stall}]The stall time, in units of LATp clocks \item[{\em header}]The header word, giving the length and opcode \item[{\em poll\_\-timeout}]The poll loop timeout value, in units of nanoseconds\end{description} \end{Desc} \begin{Desc} \item[]The poll loop timeout value is a timeout value that is added to an internal estimate of how long the transaction will take. This is usually specified as 0, unless on suspects that there are pending transactions ahead of one in the que. \end{Desc} \hypertarget{LCBB_8c_3856c5c8f105268f69e27edeef794412}{ \index{LCBB.c@{LCBB.c}!access_reg@{access\_\-reg}} \index{access_reg@{access\_\-reg}!LCBB.c@{LCBB.c}} \subsubsection{\setlength{\rightskip}{0pt plus 5cm}static unsigned int access\_\-reg ({\bf LCBB} {\em lcb}, unsigned int {\em value}, unsigned int {\em field\_\-select}, unsigned short int {\em stall}, unsigned int $\ast$ {\em prv}, unsigned int $\ast$ {\em cur}, unsigned int {\em header}, unsigned int {\em poll\_\-timeout})\hspace{0.3cm}{\tt \mbox{[}static\mbox{]}}}} \label{LCBB_8c_3856c5c8f105268f69e27edeef794412} Performs an access to the specified LCB slave-side LATP register. \begin{Desc} \item[Returns:]Status\end{Desc} \begin{Desc} \item[Parameters:] \begin{description} \item[{\em lcb}]The LCB driver handle \item[{\em value}]The 32-bit value to write \item[{\em field\_\-select}]A bit mask indicating which fields should be written \item[{\em stall}]A stall or timeout value (in units of LATp clocks) \item[{\em prv}]Pointer to return the previous value of the register \item[{\em cur}]Pointer to return the current value of the register \item[{\em header}]The header word \item[{\em poll\_\-timeout}]The poll loop timeout value, in units of nanoseconds\end{description} \end{Desc} \begin{Desc} \item[]Note that the parameters {\em prv\/} and {\em cur\/} refer to the values of the register prior to writing and after writing, respectively.\end{Desc} \begin{Desc} \item[]The poll loop timeout value is a timeout value that is added to an internal estimate of how long the transaction will take. This is usually specified as 0, unless on suspects that there are pending transactions ahead of one in the que. \end{Desc} \hypertarget{LCBB_8c_7872fe38b4f816efbfd3d4c936437233}{ \index{LCBB.c@{LCBB.c}!clear_faults@{clear\_\-faults}} \index{clear_faults@{clear\_\-faults}!LCBB.c@{LCBB.c}} \subsubsection{\setlength{\rightskip}{0pt plus 5cm}unsigned int clear\_\-faults ({\bf LCBB} {\em lcb}, unsigned short {\em timeout})\hspace{0.3cm}{\tt \mbox{[}static\mbox{]}}}} \label{LCBB_8c_7872fe38b4f816efbfd3d4c936437233} Clears the FIFO faults register. \begin{Desc} \item[Returns:]Status\end{Desc} \begin{Desc} \item[Parameters:] \begin{description} \item[{\em lcb}]The LCB driver handle \item[{\em timeout}]A timeout value (in units of LATp clocks) \end{description} \end{Desc} \hypertarget{LCBB_8c_a1ce5f13daec65571e07e61e1ce5c6e6}{ \index{LCBB.c@{LCBB.c}!drain_event@{drain\_\-event}} \index{drain_event@{drain\_\-event}!LCBB.c@{LCBB.c}} \subsubsection{\setlength{\rightskip}{0pt plus 5cm}static unsigned int drain\_\-event ({\bf LCBB} {\em lcb})\hspace{0.3cm}{\tt \mbox{[}static\mbox{]}}}} \label{LCBB_8c_a1ce5f13daec65571e07e61e1ce5c6e6} Drains the event FIFOs. \begin{Desc} \item[Return values:] \begin{description} \item[{\em 0,if}]successfully drained \item[{\em LCB}]message code it had errors\end{description} \end{Desc} \begin{Desc} \item[Parameters:] \begin{description} \item[{\em lcb}]Initialized LCBB handle\end{description} \end{Desc} \begin{Desc} \item[Overview]The EVENT FIFO is drained by reading it until dry or for a maximum of 1024. Note that, as opposed to the RESULT FIFO where no transactions are being launched (they are all solicited, except for the BOARD ID transaction and that is just a fly-in-the-ointment), the EVENT FIFO can be continually filled by external agents. This why the loop is capped. \end{Desc} \hypertarget{LCBB_8c_7493e5c6d6c92fdafd0efa90f268d0ca}{ \index{LCBB.c@{LCBB.c}!drain_result@{drain\_\-result}} \index{drain_result@{drain\_\-result}!LCBB.c@{LCBB.c}} \subsubsection{\setlength{\rightskip}{0pt plus 5cm}static unsigned int drain\_\-result ({\bf LCBB} {\em lcb})\hspace{0.3cm}{\tt \mbox{[}static\mbox{]}}}} \label{LCBB_8c_7493e5c6d6c92fdafd0efa90f268d0ca} Drains the result FIFOs. \begin{Desc} \item[Return values:] \begin{description} \item[{\em 0,if}]successfully drained \item[{\em LCB}]message code it had errors\end{description} \end{Desc} \begin{Desc} \item[Parameters:] \begin{description} \item[{\em lcb}]Initialized LCBB handle\end{description} \end{Desc} \begin{Desc} \item[Overview]The result buffer is drained by launching an internal command and waiting for the transaction to arrive back in the result FIFO. This routine uses the same underlying submission/poll routines as the user callable routines eventually call. The only difference is that the absolute poll timeout time is set to be very high under the assumption that there could be other 'things' lingering in the result queue. These other 'things' could be stale transactions leftover from a previous boot or could be NULL descriptors from externally issued LAM commnands.\end{Desc} \begin{Desc} \item[Side Effects]The drain function uses an access of the LATp CSR register as its sweeping transaction. This access has the side effect of setting the fields as specified in the LCBB\_\-cfg\_\-latp structure.\end{Desc} \begin{Desc} \item[Return Values]The drain function returns an error if it encountered any rogue transactions during the drain operation. NULL descriptors are quietly ignored, but their existence may be noted by looking at the NULL descriptor counter (lcb-$>$null\_\-counts) in the LCBB control structure as while as by pawing through the history buffer (presuming that it is deep enough to contain such them.) \end{Desc} \hypertarget{LCBB_8c_5d19762d461213e3d7eb9fb42423d908}{ \index{LCBB.c@{LCBB.c}!execute@{execute}} \index{execute@{execute}!LCBB.c@{LCBB.c}} \subsubsection{\setlength{\rightskip}{0pt plus 5cm}static unsigned int execute ({\bf LCBB} {\em lcb}, unsigned int {\em request}, unsigned int {\em xtime}, unsigned int {\em timeout}, unsigned short int {\em op\_\-len}, void $\ast$ {\em result}, {\bf LCB\_\-ri\_\-err} $\ast$ {\em ri\_\-err})\hspace{0.3cm}{\tt \mbox{[}static\mbox{]}}}} \label{LCBB_8c_5d19762d461213e3d7eb9fb42423d908} Has the LCB's command execution routine execute the specified single item request. The result list and result item is checked for successful completion. \begin{Desc} \item[Return values:] \begin{description} \item[{\em LCBB\_\-OK,if}]okay \item[{\em LCBB\_\-REQFULL,if}]the transaction could not submitted to the LCB because the request queue is full \item[{\em LCBB\_\-NULLDSC,if,when}]polling for the result, the NULL descriptor was the only transaction found \item[{\em LCBB\_\-ROGUE,if,when}]polling for the result, a ROGUE transaction was the only transaction found. \end{description} \end{Desc} \begin{Desc} \item[Returns:]Any of the result list or result item error codes.\end{Desc} \begin{Desc} \item[Parameters:] \begin{description} \item[{\em lcb}]The LCBB driver handle \item[{\em request}]A pointer to a properly built (address $|$ length) request. The transformation for local to PCI space is done in this routine. \item[{\em xtime}]The estimate time to do the transaction, in nanoseconds \item[{\em timeout}]An additional timeout period to be added to the transaction time, in nanoseconds \item[{\em op\_\-len}]Opcode and length piece of the {\em ols\/} field \item[{\em result}]Address of the expected result list. \item[{\em ri\_\-err}]Pointer to the result item's error field.\end{description} \end{Desc} \begin{Desc} \item[]This is just a convenience function, combining the submission, polling and checking of a single item command list.\end{Desc} \begin{Desc} \item[]The somewhat awkward call (passing a pointer to the result item's error field is purely for expediency, making it easier to implement this routine. In principle, this field could be decoded translated by backtracking the pointer to the command list buried in the result list back to the command's opcode and then translating the opcode into a result item length, thus locating the result item's error field. Passing it in just seemed a lot simpler. \end{Desc} \hypertarget{LCBB_8c_c72af620b4dbede22dacb4397af0b8e0}{ \index{LCBB.c@{LCBB.c}!init_circ@{init\_\-circ}} \index{init_circ@{init\_\-circ}!LCBB.c@{LCBB.c}} \subsubsection{\setlength{\rightskip}{0pt plus 5cm}static void init\_\-circ ({\bf LCBB} {\em lcb})\hspace{0.3cm}{\tt \mbox{[}static\mbox{]}}}} \label{LCBB_8c_c72af620b4dbede22dacb4397af0b8e0} Allocates memory for and sets it up to be used as the circular buffer. \begin{Desc} \item[Parameters:] \begin{description} \item[{\em lcb}]The lcb handle \end{description} \end{Desc} \hypertarget{LCBB_8c_49a381c3e3b445cd75b0eeda2c1b0cfd}{ \index{LCBB.c@{LCBB.c}!init_latp@{init\_\-latp}} \index{init_latp@{init\_\-latp}!LCBB.c@{LCBB.c}} \subsubsection{\setlength{\rightskip}{0pt plus 5cm}static unsigned int init\_\-latp ({\bf LCBB} {\em lcb})\hspace{0.3cm}{\tt \mbox{[}static\mbox{]}}}} \label{LCBB_8c_49a381c3e3b445cd75b0eeda2c1b0cfd} Laundry list of LCB initializations to do on the LATp side. \begin{Desc} \item[Parameters:] \begin{description} \item[{\em lcb}]A previously PCI initialized LCBB handle \end{description} \end{Desc} \begin{Desc} \item[Returns:]LCBB\_\-OK or a status code \end{Desc} \begin{Desc} \item[]To be successful, the clocks on the LATp need to be running. \end{Desc} \hypertarget{LCBB_8c_a88d21b146a806e92e37d2df73aa9758}{ \index{LCBB.c@{LCBB.c}!init_pci@{init\_\-pci}} \index{init_pci@{init\_\-pci}!LCBB.c@{LCBB.c}} \subsubsection{\setlength{\rightskip}{0pt plus 5cm}static unsigned int init\_\-pci ({\bf LCBB} {\em lcb})\hspace{0.3cm}{\tt \mbox{[}static\mbox{]}}}} \label{LCBB_8c_a88d21b146a806e92e37d2df73aa9758} Initializes the LCB structure -- probes the PCI bus. \begin{Desc} \item[Parameters:] \begin{description} \item[{\em lcb}]Pointer to the private LCBB structure \end{description} \end{Desc} \begin{Desc} \item[Return values:] \begin{description} \item[{\em LCBB\_\-OK}]for success, \item[{\em LCBB\_\-PCIFAIL,if}]the board cannot be found. \item[{\em LCBB\_\-PCIMAPPL,if}]the translation of local address to PCI address fails \item[{\em LCBB\_\-PCIMAPLP,if}]the address mapping fails\end{description} \end{Desc} \begin{Desc} \item[]This routine initializes the PCI portion of the {\em lcb\/} handle. If the {\em lcb\/} handle is specified as NULL, the internal handle available by calling \end{Desc} \begin{Desc} \item[See also:]\hyperlink{LCBB_8c_814d9a6e7c203340dfd8ffd736788949}{LCBB\_\-configure()}, is used.\end{Desc} \begin{Desc} \item[]The steps are\begin{enumerate} \item Probe the PCI bus, looking for the LCB.\item When the board is found, store the mapping for the PCI memory space. Both the mapping LOCAL -$>$ PCI and PCI -$>$ LOCAL are stored.\item Disable interrupts \end{enumerate} \end{Desc} \hypertarget{LCBB_8c_9aeac0985e57b03bee8105fa728bdaf0}{ \index{LCBB.c@{LCBB.c}!LCBB_check@{LCBB\_\-check}} \index{LCBB_check@{LCBB\_\-check}!LCBB.c@{LCBB.c}} \subsubsection{\setlength{\rightskip}{0pt plus 5cm}unsigned int LCBB\_\-check ({\bf LCBB} {\em lcb}, {\bf LCBB\_\-msg} $\ast$ {\em msg})}} \label{LCBB_8c_9aeac0985e57b03bee8105fa728bdaf0} Maps the LCB error codes to a LCB message code. \begin{Desc} \item[Return values:] \begin{description} \item[{\em LCBB\_\-OK}]if message is okay \item[{\em LCB}]message code if not\end{description} \end{Desc} \begin{Desc} \item[Parameters:] \begin{description} \item[{\em lcb}]Pointer to private LCB structure \item[{\em msg}]The LCB message\end{description} \end{Desc} \begin{Desc} \item[]This maps the LCB transfer and receive errors into standard LCBB message codes. If there are no transfer or receive errors, LCBB\_\-OK is returned. \end{Desc} \hypertarget{LCBB_8c_814d9a6e7c203340dfd8ffd736788949}{ \index{LCBB.c@{LCBB.c}!LCBB_configure@{LCBB\_\-configure}} \index{LCBB_configure@{LCBB\_\-configure}!LCBB.c@{LCBB.c}} \subsubsection{\setlength{\rightskip}{0pt plus 5cm}LCB LCBB\_\-configure (unsigned int {\em latp}, void $\ast$ {\em requestList}, void $\ast$ {\em resultList}, void $\ast$ {\em circBuffer})}} \label{LCBB_8c_814d9a6e7c203340dfd8ffd736788949} Returns a pointer to the LCB control structure, with the specified configuration parameters. \begin{Desc} \item[Returns:]A pointer to the LCB control structure\end{Desc} \begin{Desc} \item[Parameters:] \begin{description} \item[{\em latp}]The LATp configuration information presented as 16 select bits and 16 value bits. Only those bits with their corresponding select bits set will be altered. \item[{\em requestList}]An array of 4096 bytes aligned on a 512 byte boundary. This memory will be used to construct request lists. It is from this memory that space for LCB-to-LCB traffic, \end{description} \end{Desc} \begin{Desc} \item[See also:]\hyperlink{LCBB_8h_4191806e8b3d12bae7317ff0e3488e89}{LCBB\_\-send}, is carved. \end{Desc} \begin{Desc} \item[Parameters:] \begin{description} \item[{\em resultList}]As array of 4096 bytes aligned on a 16 byte boundary. This memory will be used to hold result lists. \item[{\em circBuffer}]An array of LCB\_\-CIRC\_\-BUFFER\_\-TOTAL (640Kbytes) align on a LCB\_\-CIRC\_\-BUFFER\_\-ALIGN (1Mbyte) boundary. This memory will be used to hold incoming 'event' traffic.\end{description} \end{Desc} \begin{Desc} \item[]The last three parameters are self-explanatory. The {\em latp\/} parameter deserves some special attention. There are a number of values that configure the LATp side behaviour of the LCB. The {\em latp\/} parameter provides a method of altering only those values that the caller wishes. It does this by defining the lower 16 bits as the value bits and the upper 16 bits as the selection bits. Only value bits with corresponding field selection bits set will be altered.\end{Desc} \begin{Desc} \item[]The set-up of this parameter is largely determined by whether the LCB is acting as a commander (SIU) or a responder (EPU). A typical configuration might be\end{Desc} \begin{Code}\begin{verbatim} SIU EPU commander 1 - evt_path - - cmd_path - - hdr_parity - - payload_parity - - pause_test - - pause_stick - - board_id v - byte_wide v - \end{verbatim} \end{Code} \begin{Desc} \item[]Where the {\em v's\/} represent a configurable value and the @ -'s represent bits that should not be altered. The corresponding code would look like for an SIU would look like\end{Desc} \begin{Code}\begin{verbatim} LCBB_latp_cfg latp; latp.ui = 0; latp.sv.value.command = 1; latp.sv.value.board_id = board_id; latp.sv.value.byte_wide = 1; latp.sv.select.command = LCBB_LATP_SELECT; latp.sv.select.board_id = LCBB_LATP_SELECT; latp.sv.select.byte_wide = LCBB_LATP_SELECT; LCBB_configure (latp.ui, requestList, resultList, circBuffer); \end{verbatim} \end{Code} \begin{Desc} \item[]The EPU would simple passs a 0, since it does wish to alter any fields.\end{Desc} \begin{Desc} \item[Note:]For the most current usage of these bits, see the corresponding fields in the LCB\_\-csr definitions (\hyperlink{LCB__cr_8h}{LCB\_\-cr.h}). Some of these bits have only have meaning in on the SIU or EPU and some only have meaning when not in a system with a GASU. An example of the latter is the commander select. In a GASU based system, this functionality is set on the \end{Desc} \hypertarget{LCBB_8c_97e836cc02dc9d240a69e25b5c461836}{ \index{LCBB.c@{LCBB.c}!LCBB_csr_access@{LCBB\_\-csr\_\-access}} \index{LCBB_csr_access@{LCBB\_\-csr\_\-access}!LCBB.c@{LCBB.c}} \subsubsection{\setlength{\rightskip}{0pt plus 5cm}unsigned int LCBB\_\-csr\_\-access ({\bf LCBB} {\em lcb}, unsigned int {\em value}, unsigned int {\em field\_\-select}, unsigned short int {\em timeout}, unsigned int $\ast$ {\em prv}, unsigned int $\ast$ {\em cur})}} \label{LCBB_8c_97e836cc02dc9d240a69e25b5c461836} Does an access of the LATp CSR register. \begin{Desc} \item[Returns:]Status\end{Desc} \begin{Desc} \item[Parameters:] \begin{description} \item[{\em lcb}]Pointer to the LCBB control structure \item[{\em value}]The value to write to the register \item[{\em field\_\-select}]A bit map indicating which fields of {\em value\/} should be written to the register. \item[{\em timeout}]The number of 20MHz ticks that the LCB should wait for a response before timing out. \item[{\em prv}]A pointer to receive the previous value \item[{\em cur}]A pointer to receive the current value \end{description} \end{Desc} \hypertarget{LCBB_8c_a7ae90cfc3015d65a4b20335970c2822}{ \index{LCBB.c@{LCBB.c}!LCBB_faults_access@{LCBB\_\-faults\_\-access}} \index{LCBB_faults_access@{LCBB\_\-faults\_\-access}!LCBB.c@{LCBB.c}} \subsubsection{\setlength{\rightskip}{0pt plus 5cm}unsigned int LCBB\_\-faults\_\-access ({\bf LCBB} {\em lcb}, unsigned int {\em value}, unsigned int {\em field\_\-select}, unsigned short int {\em timeout}, unsigned int $\ast$ {\em prv}, unsigned int $\ast$ {\em cur})}} \label{LCBB_8c_a7ae90cfc3015d65a4b20335970c2822} Does an access of the LATp CSR register. \begin{Desc} \item[Returns:]Status\end{Desc} \begin{Desc} \item[Parameters:] \begin{description} \item[{\em lcb}]Pointer to the LCBB control structure \item[{\em value}]The value to write to the register \item[{\em field\_\-select}]A bit map indicating which fields of {\em value\/} should be written to the register. \item[{\em timeout}]The number of 20MHz ticks that the LCB should wait for a response before timing out. \item[{\em prv}]A pointer to receive the previous value \item[{\em cur}]A pointer to receive the current value \end{description} \end{Desc} \hypertarget{LCBB_8c_297245fb70e13fdcc6e67cfd2ab278d7}{ \index{LCBB.c@{LCBB.c}!LCBB_free@{LCBB\_\-free}} \index{LCBB_free@{LCBB\_\-free}!LCBB.c@{LCBB.c}} \subsubsection{\setlength{\rightskip}{0pt plus 5cm}unsigned int LCBB\_\-free ({\bf LCBB} {\em lcb}, {\bf LCBB\_\-msg} $\ast$ {\em msg})}} \label{LCBB_8c_297245fb70e13fdcc6e67cfd2ab278d7} \begin{Desc} \item[Parameters:] \begin{description} \item[{\em lcb}]Pointer to private LCB structure \item[{\em msg}]Pointer to a pointer to a message \end{description} \end{Desc} \hypertarget{LCBB_8c_274bbba0ccab6e57d6118d529686a18b}{ \index{LCBB.c@{LCBB.c}!LCBB_init@{LCBB\_\-init}} \index{LCBB_init@{LCBB\_\-init}!LCBB.c@{LCBB.c}} \subsubsection{\setlength{\rightskip}{0pt plus 5cm}unsigned int LCBB\_\-init ({\bf LCBB} {\em lcb})}} \label{LCBB_8c_274bbba0ccab6e57d6118d529686a18b} Initializes the LCB structure for polled mode. \begin{Desc} \item[Parameters:] \begin{description} \item[{\em lcb}]Pointer to private LCB structure \end{description} \end{Desc} \begin{Desc} \item[Returns:]LCBB\_\-OK for success\end{Desc} \begin{Desc} \item[]Probe the PCI bus looking for the LCB. When the board is found store the mapping for the PCI I/O space and PCI Memory space. \end{Desc} \hypertarget{LCBB_8c_bdc54b261314c032000fe07fe17f3b52}{ \index{LCBB.c@{LCBB.c}!LCBB_lat_reset@{LCBB\_\-lat\_\-reset}} \index{LCBB_lat_reset@{LCBB\_\-lat\_\-reset}!LCBB.c@{LCBB.c}} \subsubsection{\setlength{\rightskip}{0pt plus 5cm}unsigned int LCBB\_\-lat\_\-reset ({\bf LCBB} {\em lcb}, unsigned short int {\em stall})}} \label{LCBB_8c_bdc54b261314c032000fe07fe17f3b52} Issues a LAT reset. \begin{Desc} \item[Parameters:] \begin{description} \item[{\em lcb}]Pointer to the LCBB control structure \item[{\em stall}]The stall time, in units of 20MHz ticks until the next command can be issued.\end{description} \end{Desc} \begin{Desc} \item[]It would be rare to issue a LAT reset in the context of the boot code, but it has been included for completeness. \end{Desc} \hypertarget{LCBB_8c_f30a0e6e8f1373b7a4c6171a093e16c6}{ \index{LCBB.c@{LCBB.c}!LCBB_locate@{LCBB\_\-locate}} \index{LCBB_locate@{LCBB\_\-locate}!LCBB.c@{LCBB.c}} \subsubsection{\setlength{\rightskip}{0pt plus 5cm}unsigned char $\ast$ LCBB\_\-locate ({\bf LCBB} {\em lcb})}} \label{LCBB_8c_f30a0e6e8f1373b7a4c6171a093e16c6} Returns a pointer to payload. \begin{Desc} \item[Parameters:] \begin{description} \item[{\em lcb}]Pointer to private LCB structure \end{description} \end{Desc} \begin{Desc} \item[Returns:]Pointer to store the payload\end{Desc} The pointer is guaranteed to be 32-bit aligned. \begin{Desc} \item[Warning:]It is the user responsibility to limit the transfer to LCB\_\-TRANSFER\_\-MAX bytes. \end{Desc} \hypertarget{LCBB_8c_77a4ad4a617f3e2c156a8783a9de2304}{ \index{LCBB.c@{LCBB.c}!LCBB_mark_time@{LCBB\_\-mark\_\-time}} \index{LCBB_mark_time@{LCBB\_\-mark\_\-time}!LCBB.c@{LCBB.c}} \subsubsection{\setlength{\rightskip}{0pt plus 5cm}unsigned int LCBB\_\-mark\_\-time ({\bf LCBB} {\em lcb}, unsigned short int {\em stall})}} \label{LCBB_8c_77a4ad4a617f3e2c156a8783a9de2304} Issues a Mark Time command to the LCB. \begin{Desc} \item[Returns:]Status\end{Desc} \begin{Desc} \item[Parameters:] \begin{description} \item[{\em lcb}]Pointer to the LCBB control structure \item[{\em stall}]The amount of time to stall, in units of 20MHz ticks\end{description} \end{Desc} \begin{Desc} \item[]It would be rare that a mark time command would be issued in the boot code environment. Mainly, this is a command to meter out items in a command list. The one possible use is as a 'innocous' command to see if the LATp side of the LCB is alive; {\em i.e\/}. a probe usage. \end{Desc} \hypertarget{LCBB_8c_63ad41af674f118d25a69927cb6b578d}{ \index{LCBB.c@{LCBB.c}!LCBB_receive@{LCBB\_\-receive}} \index{LCBB_receive@{LCBB\_\-receive}!LCBB.c@{LCBB.c}} \subsubsection{\setlength{\rightskip}{0pt plus 5cm}{\bf LCBB\_\-msg} $\ast$ LCBB\_\-receive ({\bf LCBB} {\em lcb})}} \label{LCBB_8c_63ad41af674f118d25a69927cb6b578d} Reads the event FIFO for descriptors. \begin{Desc} \item[Parameters:] \begin{description} \item[{\em lcb}]Pointer to private LCBB structure \end{description} \end{Desc} \begin{Desc} \item[Return values:] \begin{description} \item[{\em If}]there is a message, a pointer to the received message \item[{\em If}]these is no message, NUL,\end{description} \end{Desc} \begin{Desc} \item[]Call this function to check if any event data has been received. When a descriptor is found the LCBB\_\-msg pointer is initialized and the event descriptor read from the FIFO is returned. Since this is a non-blocking routine, it is meant to be used in a polling mode style, returning a non-NULL LCBB\_\-msg pointer only when there is a message available. Note that the user data starts {\em after\/} the pad area, defined bu LCB\_\-msg\_\-hdr.\end{Desc} \begin{Desc} \item[]The caller of this function {\em must\/} absolutely check the event descriptor for errors before trying to use the LCBB\_\-msg pointer. This can be done either by the user directly accessing the status fields in the event descriptor (stored in the LCBB\_\-msg itself) or by using the LCBB\_\-check function. \end{Desc} \hypertarget{LCBB_8c_308d7b59876efb9e784ed4f15616b065}{ \index{LCBB.c@{LCBB.c}!LCBB_rxstats_access@{LCBB\_\-rxstats\_\-access}} \index{LCBB_rxstats_access@{LCBB\_\-rxstats\_\-access}!LCBB.c@{LCBB.c}} \subsubsection{\setlength{\rightskip}{0pt plus 5cm}unsigned int LCBB\_\-rxstats\_\-access ({\bf LCBB} {\em lcb}, unsigned int {\em value}, unsigned int {\em field\_\-select}, unsigned short int {\em timeout}, unsigned int $\ast$ {\em prv}, unsigned int $\ast$ {\em cur})}} \label{LCBB_8c_308d7b59876efb9e784ed4f15616b065} Does an access of the LATp Receive Statistics/Status register. \begin{Desc} \item[Returns:]Status\end{Desc} \begin{Desc} \item[Parameters:] \begin{description} \item[{\em lcb}]Pointer to the LCBB control structure \item[{\em value}]The value to write to the register \item[{\em field\_\-select}]A bit map indicating which fields of {\em value\/} should be written to the register. \item[{\em timeout}]The number of 20MHz ticks that the LCB should wait for a response before timing out. \item[{\em prv}]A pointer to receive the previous value \item[{\em cur}]A pointer to receive the current value \end{description} \end{Desc} \hypertarget{LCBB_8c_4191806e8b3d12bae7317ff0e3488e89}{ \index{LCBB.c@{LCBB.c}!LCBB_send@{LCBB\_\-send}} \index{LCBB_send@{LCBB\_\-send}!LCBB.c@{LCBB.c}} \subsubsection{\setlength{\rightskip}{0pt plus 5cm}unsigned int LCBB\_\-send ({\bf LCBB} {\em lcb}, unsigned int {\em dst}, unsigned int {\em proto}, int {\em nbytes})}} \label{LCBB_8c_4191806e8b3d12bae7317ff0e3488e89} Sends the data. \begin{Desc} \item[Parameters:] \begin{description} \item[{\em lcb}]Pointer to private LCBB structure \item[{\em dst}]LATp destination fabric address, physical \item[{\em proto}]2-bit LATp protocol to use when sending bulk data \item[{\em nbytes}]The number of bytes to send. Note that this length must include the 4 bytes of the LATP packet header \end{description} \end{Desc} \begin{Desc} \item[Returns:]LCBB\_\-OK for success\end{Desc} \begin{Desc} \item[Warning:]Make sure the {\em nbytes\/} parameter includes the length of the data plus the 4 bytes of the LATP packet header word. This was a struggle, trying to define whether the length word should be only the length of what has traditionally been called the user data (excludes the the LATp header and the word that the EBM would fill) or whether it should include the 4 bytes of the LATp and EBM word. In the end, the decision was driven by the fact that the numbers floating around describing the limits on the data transfer size have been quoted as including the 4 bytes. \end{Desc} \hypertarget{LCBB_8c_f8cdc8ade2d6c7300c9dd84a808a2485}{ \index{LCBB.c@{LCBB.c}!LCBB_start@{LCBB\_\-start}} \index{LCBB_start@{LCBB\_\-start}!LCBB.c@{LCBB.c}} \subsubsection{\setlength{\rightskip}{0pt plus 5cm}unsigned int LCBB\_\-start ({\bf LCBB} {\em lcb})}} \label{LCBB_8c_f8cdc8ade2d6c7300c9dd84a808a2485} Enables the LCB for taking event data. \begin{Desc} \item[Parameters:] \begin{description} \item[{\em lcb}]Pointer to private LCBB structure \end{description} \end{Desc} \begin{Desc} \item[Returns:]LCBB\_\-OK for success \end{Desc} \hypertarget{LCBB_8c_9b1780d2fe1aca60226dac3b5ad92bd7}{ \index{LCBB.c@{LCBB.c}!mapRcvErr@{mapRcvErr}} \index{mapRcvErr@{mapRcvErr}!LCBB.c@{LCBB.c}} \subsubsection{\setlength{\rightskip}{0pt plus 5cm}static \_\-\_\-inline unsigned int mapRcvErr (const {\bf LCBB\_\-err\_\-rst\_\-maps} $\ast$ {\em maps}, unsigned int {\em err})\hspace{0.3cm}{\tt \mbox{[}static\mbox{]}}}} \label{LCBB_8c_9b1780d2fe1aca60226dac3b5ad92bd7} Maps a result item status into an error code. \begin{Desc} \item[Parameters:] \begin{description} \item[{\em maps}]The error maps for result codes \item[{\em err}]The error (status) code to map \end{description} \end{Desc} \hypertarget{LCBB_8c_617fb732602d0c570bc5a7eb330d17c4}{ \index{LCBB.c@{LCBB.c}!mapXfrErr@{mapXfrErr}} \index{mapXfrErr@{mapXfrErr}!LCBB.c@{LCBB.c}} \subsubsection{\setlength{\rightskip}{0pt plus 5cm}static \_\-\_\-inline unsigned int mapXfrErr (const {\bf LCBB\_\-err\_\-rst\_\-maps} $\ast$ {\em maps}, unsigned int {\em err})\hspace{0.3cm}{\tt \mbox{[}static\mbox{]}}}} \label{LCBB_8c_617fb732602d0c570bc5a7eb330d17c4} Maps a result descriptor status into an error code. \begin{Desc} \item[Parameters:] \begin{description} \item[{\em maps}]The error maps for result codes \item[{\em err}]The error (status) code to map \end{description} \end{Desc} \hypertarget{LCBB_8c_24006b0f3ad5623b41e0487be99becb5}{ \index{LCBB.c@{LCBB.c}!pciLoad32@{pciLoad32}} \index{pciLoad32@{pciLoad32}!LCBB.c@{LCBB.c}} \subsubsection{\setlength{\rightskip}{0pt plus 5cm}unsigned int pciLoad32 (volatile unsigned int $\ast$ {\em src})\hspace{0.3cm}{\tt \mbox{[}static\mbox{]}}}} \label{LCBB_8c_24006b0f3ad5623b41e0487be99becb5} Read a 32-bit integer from PCI Memory. \begin{Desc} \item[Parameters:] \begin{description} \item[{\em src}]Pointer source memory location \end{description} \end{Desc} \begin{Desc} \item[Returns:]value at memory location pointed to be {\em src\/} \end{Desc} \begin{Desc} \item[See also:]\hyperlink{LCBB_8c_22c86496f160ebc87f14583736324ee9}{pciStore32()}\end{Desc} This function performs the necessary byte swapping when reading PCI Memory (PCI bus is inherently little-endian). \hypertarget{LCBB_8c_22c86496f160ebc87f14583736324ee9}{ \index{LCBB.c@{LCBB.c}!pciStore32@{pciStore32}} \index{pciStore32@{pciStore32}!LCBB.c@{LCBB.c}} \subsubsection{\setlength{\rightskip}{0pt plus 5cm}void pciStore32 (volatile unsigned int $\ast$ {\em dst}, unsigned int {\em w})\hspace{0.3cm}{\tt \mbox{[}static\mbox{]}}}} \label{LCBB_8c_22c86496f160ebc87f14583736324ee9} Write a 32-bit integer to PCI Memory. \begin{Desc} \item[Parameters:] \begin{description} \item[{\em dst}]Pointer destination memory \item[{\em w}]32-bit value to store \end{description} \end{Desc} \begin{Desc} \item[Returns:]LCBB\_\-OK on success\end{Desc} This function performs the necessary byte swapping when writing PCI Memory (PCI bus is inherently little-endian). For the PowerPC the function also issues an \char`\"{}eieio\char`\"{} instruction to insure the write instruction complete before other loads and stores. \hypertarget{LCBB_8c_ba641905848700c4f0b0d42512624c31}{ \index{LCBB.c@{LCBB.c}!poll@{poll}} \index{poll@{poll}!LCBB.c@{LCBB.c}} \subsubsection{\setlength{\rightskip}{0pt plus 5cm}static unsigned int poll ({\bf LCBB} {\em lcb}, unsigned int {\em poll\_\-period}, unsigned int {\em timeout}, unsigned short int {\em op\_\-len}, const void $\ast$ {\em result}, const {\bf LCB\_\-ri\_\-err} $\ast$ {\em ri\_\-err})\hspace{0.3cm}{\tt \mbox{[}static\mbox{]}}}} \label{LCBB_8c_ba641905848700c4f0b0d42512624c31} Polls the RESULT FIFO every {\em nsecs\/} for @ iterations. \begin{Desc} \item[Returns:]The status of the transaction\end{Desc} \begin{Desc} \item[Parameters:] \begin{description} \item[{\em lcb}]The LCBB driver handle \item[{\em poll\_\-period}]The polling period, in nanoseconds \item[{\em timeout}]The timeout period, in nanoseconds \item[{\em op\_\-len}]The opcode and length of the transaction \item[{\em result}]Address of the expected result list. \item[{\em ri\_\-err}]Pointer to the result item's error field. s\end{description} \end{Desc} Routine polls on the result descriptor que until either\begin{enumerate} \item A result descriptor comes back\item The timeout period is reached\end{enumerate} Even a list of up to 3 seconds is possible (pretty bizarre), can be covered by the range of the SPIN counter. The smallest range is \footnotesize\begin{verbatim} MV2304, MCP750: 2**32 * 60 nsecs ~= 240 seconds RAD750 : 2**32 * 120 nsecs ~= 480 seconds \end{verbatim} \normalsize \hypertarget{LCBB_8c_c8e6fb49f15305c0099deda634594ec1}{ \index{LCBB.c@{LCBB.c}!submit@{submit}} \index{submit@{submit}!LCBB.c@{LCBB.c}} \subsubsection{\setlength{\rightskip}{0pt plus 5cm}static unsigned int submit ({\bf LCBB} {\em lcb}, unsigned int {\em request})\hspace{0.3cm}{\tt \mbox{[}static\mbox{]}}}} \label{LCBB_8c_c8e6fb49f15305c0099deda634594ec1} Submits the specified request list to the LCB for execution. \begin{Desc} \item[Return values:] \begin{description} \item[{\em LCBB\_\-OK,if}]the transaction was successfully submitted \item[{\em LCBB\_\-REQFULL,if}]the transaction could not be submitted because the request queue was full.\end{description} \end{Desc} \begin{Desc} \item[Parameters:] \begin{description} \item[{\em lcb}]The LCBB driver handle \item[{\em request}]A pointer to a properly built (address $|$ length) request. The transformation for local to PCI space is done in this routine. \end{description} \end{Desc}