Skip to content

M
Mock Turtle
Commit 3602f7ae authored by Federico Vaga's avatar Federico Vaga
Browse files
Options

doc: improve documentation 

Signed-off-by: 's avatarFederico Vaga <federico.vaga@gmail.com>
parent 4a593495
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 2935 additions and 32 deletions
doc/img/sw-drv-hier.eps 0 → 100644
View file @ 3602f7ae
This diff is collapsed.
doc/img/sw-drv-hier.graphml 0 → 100644
View file @ 3602f7ae
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<graphml xmlns="http://graphml.graphdrawing.org/xmlns" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:y="http://www.yworks.com/xml/graphml" xmlns:yed="http://www.yworks.com/xml/yed/3" xsi:schemaLocation="http://graphml.graphdrawing.org/xmlns http://www.yworks.com/xml/schema/graphml/1.1/ygraphml.xsd">
<!--Created by yEd 3.13-->
<key attr.name="Description" attr.type="string" for="graph" id="d0"/>
<key for="port" id="d1" yfiles.type="portgraphics"/>
<key for="port" id="d2" yfiles.type="portgeometry"/>
<key for="port" id="d3" yfiles.type="portuserdata"/>
<key attr.name="url" attr.type="string" for="node" id="d4"/>
<key attr.name="description" attr.type="string" for="node" id="d5"/>
<key for="node" id="d6" yfiles.type="nodegraphics"/>
<key for="graphml" id="d7" yfiles.type="resources"/>
<key attr.name="url" attr.type="string" for="edge" id="d8"/>
<key attr.name="description" attr.type="string" for="edge" id="d9"/>
<key for="edge" id="d10" yfiles.type="edgegraphics"/>
<graph edgedefault="directed" id="G">
<data key="d0"/>
<node id="n0">
<data key="d5"/>
<data key="d6">
<y:ShapeNode>
<y:Geometry height="30.0" width="387.0" x="379.0" y="328.0"/>
<y:Fill color="#888899" transparent="false"/>
<y:BorderStyle color="#333399" type="line" width="3.0"/>
<y:NodeLabel alignment="center" autoSizePolicy="content" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="17.96875" modelName="custom" textColor="#000000" visible="true" width="71.0546875" x="157.97265625" y="6.015625">wrnc-%04x<y:LabelModel>
<y:SmartNodeLabelModel distance="4.0"/>
</y:LabelModel>
<y:ModelParameter>
<y:SmartNodeLabelModelParameter labelRatioX="0.0" labelRatioY="0.0" nodeRatioX="0.0" nodeRatioY="0.0" offsetX="0.0" offsetY="0.0" upX="0.0" upY="-1.0"/>
</y:ModelParameter>
</y:NodeLabel>
<y:Shape type="rectangle"/>
</y:ShapeNode>
</data>
</node>
<node id="n1">
<data key="d5"/>
<data key="d6">
<y:ShapeNode>
<y:Geometry height="30.0" width="186.0" x="379.0" y="388.0"/>
<y:Fill color="#99CCFF" transparent="false"/>
<y:BorderStyle color="#3366FF" type="line" width="3.0"/>
<y:NodeLabel alignment="center" autoSizePolicy="content" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="17.96875" modelName="custom" textColor="#000000" visible="true" width="135.82421875" x="25.087890625" y="6.015625">wrnc-%04x-cpu-%02d<y:LabelModel>
<y:SmartNodeLabelModel distance="4.0"/>
</y:LabelModel>
<y:ModelParameter>
<y:SmartNodeLabelModelParameter labelRatioX="0.0" labelRatioY="0.0" nodeRatioX="0.0" nodeRatioY="0.0" offsetX="0.0" offsetY="0.0" upX="0.0" upY="-1.0"/>
</y:ModelParameter>
</y:NodeLabel>
<y:Shape type="rectangle"/>
</y:ShapeNode>
</data>
</node>
<node id="n2">
<data key="d5"/>
<data key="d6">
<y:ShapeNode>
<y:Geometry height="30.0" width="186.0" x="580.0" y="388.0"/>
<y:Fill color="#FFCC99" transparent="false"/>
<y:BorderStyle color="#FF9900" type="line" width="3.0"/>
<y:NodeLabel alignment="center" autoSizePolicy="content" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="17.96875" modelName="custom" textColor="#000000" visible="true" width="163.24609375" x="11.376953125" y="6.015625">wrnc-%04x-hmq-%c-%02d<y:LabelModel>
<y:SmartNodeLabelModel distance="4.0"/>
</y:LabelModel>
<y:ModelParameter>
<y:SmartNodeLabelModelParameter labelRatioX="0.0" labelRatioY="0.0" nodeRatioX="0.0" nodeRatioY="0.0" offsetX="0.0" offsetY="0.0" upX="0.0" upY="-1.0"/>
</y:ModelParameter>
</y:NodeLabel>
<y:Shape type="rectangle"/>
</y:ShapeNode>
</data>
</node>
<edge id="e0" source="n1" target="n0">
<data key="d9"/>
<data key="d10">
<y:PolyLineEdge>
<y:Path sx="0.0" sy="0.0" tx="-100.5" ty="3.0"/>
<y:LineStyle color="#000000" type="line" width="1.0"/>
<y:Arrows source="none" target="standard"/>
<y:BendStyle smoothed="false"/>
</y:PolyLineEdge>
</data>
</edge>
<edge id="e1" source="n2" target="n0">
<data key="d9"/>
<data key="d10">
<y:PolyLineEdge>
<y:Path sx="0.0" sy="0.0" tx="100.5" ty="14.9609375"/>
<y:LineStyle color="#000000" type="line" width="1.0"/>
<y:Arrows source="none" target="standard"/>
<y:BendStyle smoothed="false"/>
</y:PolyLineEdge>
</data>
</edge>
</graph>
<data key="d7">
<y:Resources/>
</data>
</graphml>
doc/img/sw-stack.graphml 0 → 100644
View file @ 3602f7ae
This diff is collapsed.
doc/wrnc.tex 100644 → 100755
View file @ 3602f7ae
......@@ -223,17 +223,102 @@ CPU\footnote{Internally, the White-Rabbit Node-Core has up to 8 CPUs.
Each CPU run independently a real-time application.}, and the Linux
driver.
The device hierarchy of the driver is shown in figure
\ref{fig:swdrvhier}; there is a main device and then sub-devices
according to the White-Rabbit Node-Core configuration.
\begin{figure}[ht]
\centering
\includegraphics[scale=0.5]{img/sw-drv-hier.eps}
\caption{White-Rabbit Node-Core Device Driver Hierarchy}
\label{fig:swdrvhier}
\end{figure}
The Linux device driver export two Interfaces: sysfs attributes and
char-devices.
\subsubsection{Char-Devices Interface}
All char-devices are available under the directory \texttt{/dev/}.
\begin{description}
\item['wrnc-\%04x', device\_id] it refers to the entire device
(\texttt{\%04x = device\_id}). It supports\texttt{read},
\texttt{write}, \texttt{seek} and \texttt{ioctl}. It allows users to
read/write the internal shared memory.
\item['wrnc-\%04x-cpu-\%02d', device\_id, cpu\_index] it refers to a
single CPU in the
White-Rabbit Node-Core. It supports \texttt{read}, \texttt{write} and
\texttt{seek}. It allows users to load or to dump CPU firmware.
\item['wrnc-\%04x-hmq-\%c-\%02d', device\_id, direction, hmq\_index]
it refers to a single HMQ slot in
the White-Rabbit Node-Core. Slot are splitted in two category: input
slots (\texttt{\%c = 'i'}) and output slots (\texttt{\%c = 'o'}). It
supports \texttt{read}\footnote{on output slots},
\texttt{write}\footnote{on input slots}, \texttt{seek} and
\texttt{poll}
\end{description}
\subsubsection{Sysfs Interface}
You can find all the sysfs attributes under the directory
\texttt{/sys/class/wr-node-core/}. Following a table of all sysfs
attributes available.
\renewcommand{\arraystretch}{1.8}
\begin{tabular}{c c c p{6cm}}
device & name & direction & description \\
\hline
wrnc & application\_id & RO & application identifier of the WRNC
bitstream \\
\hline
wrnc & n\_cpu & RO & get the number of CPUs \\
\hline
wrnc & enable\_mask & RW & it enable/disable CPUs. It's a bit mask.
Actually, it means that it runs or pauses the code \\
\hline
wrnc & reset\_mask & RW & it (de-)assert the CPUs' reset line. It's
a bit mask \\
\hline
wrnc & smem\_operation & RW & it set the default operation modo for
te access to the shared memory \\
\hline \hline
cpu & enable & RW & it enable/disable a CPU. Actually, it means
that it runs or pauses the code \\
\hline
cpu & reset & RW & it (de-)assert the CPU reset line \\
\hline \hline
hmq & count & RO & number of messages in the HMQ slot \\
\hline
hmq & empty & RO & the hardware status of the HMQ slot is empty \\
\hline
hmq & full & RO & the hardware status of the HMQ slot is full \\
\end{tabular}
\subsubsection{Load Real-Time Programs}%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
Without applications the White-Rabbit Node-Core does nothing. So, to
make it productive we must load a real-time application.
make it productive we must load a real-time application on the CPU.
For this purpose the driver offers a dedicated char device for each
CPU that allows you to load (dump) application to (from) the CPU
memory.
You can find these char-devices under \texttt{/dev/} with the
following patter \textit{wrnc-\%04x-cpu-\%02d}.
You can find these char-devices under the directory \texttt{/dev/}
with the following patter \textit{wrnc-\%04x-cpu-\%02d}.
You can load an application by writing to the char device. You can
dump an application by reading from the char device. With
......@@ -254,29 +339,23 @@ from/to these char-devices you can send/receive messages. Obviously,
the content of the message depends on the application running on the
White-Rabbit Node-Core CPUs.
You can find these char-devices under \texttt{/dev/}, its name has
following patter \textit{wrnc-\%04x-hmq-\%c-\%02d}.
You can find these char-devices under the directory \texttt{/dev/},
with following patter \textit{wrnc-\%04x-hmq-\%c-\%02d}.
Here the data structures involved in the communication:
Here the data structures\footnote{read the doxygen
documentation for details} involved in the communication:
\begin{lstlisting}
/**
* Messages descriptor
*/
struct wrnc_msg {
uint32_t datalen; /**< payload length*/
uint32_t data[WRNC_MAX_PAYLOAD_SIZE]; /**< payload */
uint32_t datalen;
uint32_t data[WRNC_MAX_PAYLOAD_SIZE];
};
/**
* Message descriptor used to send synchronous messages
*/
struct wrnc_msg_sync {
struct wrnc_msg msg; /**< the message to send. It will be overwritten by
the synchronous answer */
uint16_t index_in; /**< where write the message */
uint16_t index_out; /**< where we expect the synchronous answer */
unsigned int timeout_ms; /**< time to wait for an answer in ms */
struct wrnc_msg msg;
uint16_t index_in;
uint16_t index_out;
unsigned int timeout_ms;
};
\end{lstlisting}
......@@ -296,22 +375,28 @@ or \texttt{fseek(2)} the char-device you can point to a specific
memory offset.
The size of this Shared-Memory is 8192 bytes. The Shared-Memory
address space is divided by range; each range has an associated write
address space is divided by ranges; each range has an associated write
operation. The first offset range from 0 to 8192 allows you to
directly access the Shared-Memory without any operation. All the other
range perform atomic operations; the write operation is always
ranges perform atomic operations; the write operation is always
executed by using as argument the current content of the memory cell:
\begin{math}
cell = cell \left\{ \vee, \wedge, +, \dots \right\} value
\end{math}
Please, refer to the HDL documentation for details about ranges
and operations.
To keep consistency between documentations, please, refer to the HDL
documentation for details about ranges and operations.
You can find these char-devices under \texttt{/dev/} with the
following name patter \textit{wrnc-\%04x}.
The default operation of the char-device is a direct access to the
memory. You can change the default behaviour of the char-device by
writing on the sysfs attribute \texttt{smem\_operation}
\footnote{\texttt{/sys/class/wr-node-core/wrnc-\%04x/smem\_operation}}
The char-devices have also \texttt{ioctl(2)} capabilities:
\begin{description}
\item[smem\_io] allow to read/write a memory cell. The ioctl command
......@@ -320,19 +405,16 @@ The char-devices have also \texttt{ioctl(2)} capabilities:
value will be overwritten with the result of the write operation.
\end{description}
Here the data structures involved in the communication using
Here the data structures\footnote{read the doxygen documentation for
details} involved in the communication using
\texttt{ioctl(2)}:
\begin{lstlisting}
/**
* Descriptor of the IO operation on Shared Memory
*/
struct wrnc_smem_io {
uint32_t addr; /**< address to access */
uint32_t value; /**< value to write. After ioctl it will be overwritte
with the new value in the shared memory */
int is_input; /**< flag to determinte data direction */
enum wrnc_smem_modifier mod; /**< the kind of operation to do */
uint32_t addr;
uint32_t value;
int is_input;
enum wrnc_smem_modifier mod;
};
\end{lstlisting}
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment