--- a/documentation/ethercat_doc.tex Wed Nov 05 15:05:40 2008 +0000
+++ b/documentation/ethercat_doc.tex Wed Nov 05 15:13:55 2008 +0000
@@ -308,12 +308,12 @@
\begin{itemize}
-\item Kernel code has significantly better realtime characteristics,
-i.\,e.~less latency than userspace code. It was foreseeable, that a fieldbus
-master has a lot of cyclic work to do. Cyclic work is usually triggered by
-timer interrupts inside the kernel. The execution delay of a function that
-processes timer interrupts is less, when it resides in kernelspace, because
-there is no need of time-consuming context switches to a userspace process.
+\item Kernel code has significantly better realtime characteristics, i.\,e.\
+less latency than userspace code. It was foreseeable, that a fieldbus master
+has a lot of cyclic work to do. Cyclic work is usually triggered by timer
+interrupts inside the kernel. The execution delay of a function that processes
+timer interrupts is less, when it resides in kernelspace, because there is no
+need of time-consuming context switches to a userspace process.
\item It was also foreseeable, that the master code has to directly
communicate with the Ethernet hardware. This has to be done in the kernel
@@ -365,10 +365,80 @@
%------------------------------------------------------------------------------
-\section{Phases}
+\section{Master Module}
+\label{sec:mastermod}
+\index{Master module}
+
+The EtherCAT master kernel module \textit{ec\_master} can contain multiple
+master instances. Each master waits for a certain Ethernet device identified
+by its MAC address\index{MAC address}. These addresses have to be specified on
+module loading via the \textit{main\_devices} module parameter. The number of
+master instances to initialize is taken from the number of MAC addresses
+given.
+
+The below command loads the master module with a single master instance that
+waits for the Ethernet device with the MAC address
+\lstinline+00:0E:0C:DA:A2:20+. The master will be accessible via index $0$.
+
+\begin{lstlisting}
+# `\textbf{modprobe ec\_master main\_devices=00:0E:0C:DA:A2:20}`
+\end{lstlisting}
+
+MAC addresses for multiple masters have to be separated by commas:
+
+\begin{lstlisting}
+# `\textbf{modprobe ec\_master main\_devices=00:0E:0C:DA:A2:20,00:e0:81:71:d5:1c}`
+\end{lstlisting}
+
+The two masters can be addressed by their indices 0 and 1 respectively (see
+figure~\ref{fig:masters}). The master index is needed for the
+\lstinline+ecrt_master_request()+ function of the application interface (see
+chap.~\ref{chap:api}) and the \lstinline+--master+ option of the
+\textit{ethercat} command-line tool (see sec.~\ref{sec:tool}), which defaults
+to $0$.
+
+\begin{figure}[htbp]
+ \centering
+ \includegraphics[width=.5\textwidth]{images/masters}
+ \caption{Multiple masters in one module}
+ \label{fig:masters}
+\end{figure}
+
+\paragraph{Init Script}
+\index{Init script}
+
+In most cases it is not necessary to load the master module and the Ethernet
+driver modules manually. There is an init script available, so the master can
+be started as a service (see sec.~\ref{sec:system}).
+
+\paragraph{Syslog}
+
+The master module outputs information about its state and events to the kernel
+ring buffer. These also end up in the system logs. The above module loading
+command should result in the messages below:
+
+\begin{lstlisting}
+# `\textbf{dmesg | tail -2}`
+EtherCAT: Master driver `\masterversion`
+EtherCAT: 2 masters waiting for devices.
+
+# `\textbf{tail -2 /var/log/messages}`
+Jul 4 10:22:45 ethercat kernel: EtherCAT: Master driver `\masterversion`
+Jul 4 10:22:45 ethercat kernel: EtherCAT: 2 masters waiting
+ for devices.
+\end{lstlisting}
+
+All EtherCAT master output is prefixed with \lstinline+EtherCAT+ which makes
+searching the logs easier.
+
+%------------------------------------------------------------------------------
+
+\section{Master Phases}
\index{Master phases}
-The EtherCAT master runs through several phases (see fig.~\ref{fig:phases}):
+Every EtherCAT master provided by the master module (see
+sec.~\ref{sec:mastermod}) runs through several phases (see
+fig.~\ref{fig:phases}):
\begin{figure}[htbp]
\centering
@@ -398,83 +468,6 @@
%------------------------------------------------------------------------------
-\section{General Behavior}
-\index{Master behavior}
-
-\ldots
-
-% TODO Behavior (Scanning)
-
-%------------------------------------------------------------------------------
-
-\section{Master Module}
-\label{sec:mastermod}
-\index{Master module}
-
-The EtherCAT master kernel module \textit{ec\_master} can contain multiple
-master instances. Each master waits for a certain Ethernet device identified
-by its MAC address\index{MAC address}. These addresses have to be specified on
-module loading via the \textit{main\_devices} module parameter. The number of
-master instances to initialize is taken from the number of MAC addresses
-given.
-
-The below command loads the master module with a single master instance that
-waits for the Ethernet device with the MAC address
-\lstinline+00:0E:0C:DA:A2:20+. The master will be accessible via index $0$.
-
-\begin{lstlisting}
-# `\textbf{modprobe ec\_master main\_devices=00:0E:0C:DA:A2:20}`
-\end{lstlisting}
-
-MAC addresses for multiple masters have to be separated by commas:
-
-\begin{lstlisting}
-# `\textbf{modprobe ec\_master main\_devices=00:0E:0C:DA:A2:20,00:e0:81:71:d5:1c}`
-\end{lstlisting}
-
-The two masters can be addressed by their indices 0 and 1 respectively (see
-figure~\ref{fig:masters}). The master index is needed for the
-\lstinline+ecrt_master_request()+ function of the application interface (see
-chap.~\ref{chap:api}) and the \lstinline+--master+ option of the
-\textit{ethercat} command-line tool (see sec.~\ref{sec:tool}), which defaults
-to $0$.
-
-\begin{figure}[htbp]
- \centering
- \includegraphics[width=.5\textwidth]{images/masters}
- \caption{Multiple masters in one module}
- \label{fig:masters}
-\end{figure}
-
-\paragraph{Init Script}
-\index{Init script}
-
-In most cases it is not necessary to load the master module and the Ethernet
-driver modules manually. There is an init script available, so the master can
-be started as a service (see sec.~\ref{sec:system}).
-
-\paragraph{Syslog}
-
-The master module outputs information about its state and events to the kernel
-ring buffer. These also end up in the system logs. The above module loading
-command should result in the messages below:
-
-\begin{lstlisting}
-# `\textbf{dmesg | tail -2}`
-EtherCAT: Master driver `\masterversion`
-EtherCAT: 2 masters waiting for devices.
-
-# `\textbf{tail -2 /var/log/messages}`
-Jul 4 10:22:45 ethercat kernel: EtherCAT: Master driver `\masterversion`
-Jul 4 10:22:45 ethercat kernel: EtherCAT: 2 masters waiting
- for devices.
-\end{lstlisting}
-
-All EtherCAT master output is prefixed with \lstinline+EtherCAT+ which makes
-searching the logs easier.
-
-%------------------------------------------------------------------------------
-
\section{Process Data}
\label{sec:processdata}
@@ -631,7 +624,7 @@
sec.~\ref{sec:ethercat-config}).
\paragraph{Slave Position} The slave position has to be specified as a tuple
-of ``alias`` and ``position''. This allows addressing slaves either via an
+of ``alias'' and ``position''. This allows addressing slaves either via an
absolute bus position, or a stored identifier called ``alias'', or a mixture
of both. The alias is a 16-bit value stored in the slave's E$^2$PROM. It can
be modified via the command-line tool (see sec.~\ref{sec:ethercat-alias}).
@@ -861,7 +854,7 @@
from userspace. Frame reception has to be enabled by the driver.
\item[\usebox\boxstop] The purpose of this callback is to ``close'' the
-device, i.~e. make the hardware stop receiving frames.
+device, i.\,e.\ make the hardware stop receiving frames.
\item[\usebox\boxxmit] This function is called for each frame that has to be
transmitted. The network stack passes the frame as a pointer to an
@@ -1447,7 +1440,7 @@
The textual descriptions of the state machines contain references to the
transitions in the corresponding state transition diagrams, that are marked
with an arrow followed by the name of the successive state. Transitions caused
-by trivial error cases (i.~e. no response from slave) are not described
+by trivial error cases (i.\,e.\ no response from slave) are not described
explicitly. These transitions are drawn as dashed arrows in the diagrams.
%------------------------------------------------------------------------------
@@ -1572,7 +1565,7 @@
configured.
\item[FMMU Configuration] If there are FMMUs configurations supplied by the
-application (i.~e. if the application registered Pdo entries), they are
+application (i.\,e.\ if the application registered Pdo entries), they are
applied.
\item[SAFEOP] The state change FSM is used to bring the slave to SAFEOP state.
@@ -1604,7 +1597,7 @@
\begin{description}
\item[Start] The new application-layer state is requested via the ``AL Control
-Request'' register (see ~\cite[sec. 5.3.1]{alspec}).
+Request'' register (see~\cite[sec. 5.3.1]{alspec}).
\item[Check for Response] Some slave need some time to respond to an AL state
change command, and do not respond for some time. For this case, the command
@@ -1755,10 +1748,11 @@
\label{sec:eoe}
\index{EoE}
-The EtherCAT master implements the Ethernet-over-EtherCAT mailbox protocol to
-enable the tunneling of Ethernet frames to special slaves, that can either
-have physical Ethernet ports to forward the frames to, or have an own IP stack
-to receive the frames.
+The EtherCAT master implements the
+Ethernet-over-EtherCAT\nomenclature{EoE}{Ethernet-over-EtherCAT, Mailbox
+Protocol} mailbox protocol~\cite[sec.~5.7]{alspec} to enable the tunneling of
+Ethernet frames to special slaves, that can either have physical Ethernet
+ports to forward the frames to, or have an own IP stack to receive the frames.
\paragraph{Virtual Network Interfaces}
@@ -1913,8 +1907,9 @@
\label{sec:coe}
\index{CoE}
-The CANopen-over-EtherCAT protocol \cite[sec.~5.6]{alspec} is used to
-configure slaves and exchange data objects on application level.
+The CANopen-over-EtherCAT\nomenclature{CoE}{CANopen-over-EtherCAT, Mailbox
+Protocol} protocol~\cite[sec.~5.6]{alspec} is used to configure slaves and
+exchange data objects on application level.
% TODO
%
@@ -2358,10 +2353,10 @@
Please note, that the init script depends on the sysconfig file described
below.
-To provide service dependencies (i.~e. which services have to be started before
-others) inside the init script code, LSB defines a special comment block.
-System tools can extract this information to insert the EtherCAT init script at
-the correct place in the startup sequence:
+To provide service dependencies (i.\,e.\ which services have to be started
+before others) inside the init script code, LSB defines a special comment
+block. System tools can extract this information to insert the EtherCAT init
+script at the correct place in the startup sequence:
\lstinputlisting[firstline=38,lastline=48]
{../script/init.d/ethercat}
@@ -2409,25 +2404,48 @@
\label{sec:debug}
\index{Monitoring}
-% FIXME
-
-For debugging purposes, every EtherCAT master registers a read-only network
-interface \textit{ecX}, where X is a number, provided by the kernel on device
-registration. While it is ``up'', the master forwards every frame sent and
-received to this interface.
-
-This makes it possible to connect an network monitor (like Wireshark or
-tcpdump) to the debug interface and monitor the EtherCAT frames.
-
-% FIXME schedule()
-It has to be considered, that can be frame rate can be very high. The master
-state machine usually runs every kernel timer interrupt (usually up to
-\unit{1}{\kilo\hertz}) and with a connected application, the rate can be even
-higher.
-
-\paragraph{Attention:} The socket buffers needed for the operation of
-the debugging interface have to be allocated dynamically. Some Linux
-realtime extensions do not allow this in realtime context!
+EtherCAT buses can always be monitored by inserting a switch between master
+and slaves. This allows to connect another PC with a network monitor like
+Wireshark~\cite{wireshark}, for example.
+
+For convenience, so-called ``debug interfaces'' are supported. Debug interfaces
+allow to monitor EtherCAT traffic with a network monitor (like Wireshark or
+tcpdump) running on the same machine. To use this functionality, the master
+sources have to be configured with the \lstinline+--enable-debug-if+ switch
+(see sec.~\ref{sec:installation}).
+
+Every EtherCAT master registers two read-only network interfaces. These are
+named \textit{ecdbgmX} (main device) and \textit{ecdbgbX} (backup device for
+future use), where X is the master index. The debug interfaces are listed in
+the below output:
+
+\begin{lstlisting}
+# `\textbf{ip link}`
+1: lo: <LOOPBACK,UP> mtu 16436 qdisc noqueue
+ link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
+4: eth0: <BROADCAST,MULTICAST> mtu 1500 qdisc noop qlen 1000
+ link/ether 00:04:61:03:d1:01 brd ff:ff:ff:ff:ff:ff
+8: ecdbgm0: <BROADCAST,MULTICAST> mtu 1500 qdisc pfifo_fast
+ qlen 1000
+ link/ether 00:00:00:00:00:00 brd ff:ff:ff:ff:ff:ff
+9: ecdbgb0: <BROADCAST,MULTICAST> mtu 1500 qdisc noop qlen 1000
+ link/ether 00:00:00:00:00:00 brd ff:ff:ff:ff:ff:ff
+\end{lstlisting}
+
+While a debug interface is enabled, the corresponding master forwards all
+frames sent and received to or from the bus to that interface. Interfaces can
+be enabled for example with the command:
+
+\begin{lstlisting}
+# `\textbf{ip link set dev ecdbgm0 up}`
+\end{lstlisting}
+
+Please note, that the frame rate can be very high. With an application
+connected, the debug interface can produce thousands of frames per second.
+
+\paragraph{Attention} The socket buffers needed for the operation of the
+debugging interface have to be allocated dynamically. Some Linux realtime
+extensions do not allow this in realtime context!
%------------------------------------------------------------------------------
@@ -2789,6 +2807,13 @@
Now, the \lstinline+ethercat+ tool can be used (see sec.~\ref{sec:tool}) even
as a non-root user.
+If non-root users shall have writing access, the following udev rule can be
+used instead:
+
+\begin{lstlisting}
+KERNEL=="EtherCAT[0-9]*", MODE="0664", GROUP="users"
+\end{lstlisting}
+
%------------------------------------------------------------------------------
\begin{thebibliography}{99}
@@ -2811,15 +2836,15 @@
2008.
\bibitem{lsb} Linux Standard Base.
-\url{http://www.linuxfoundation.org/en/LSB}. August~9, 2006.
+\url{http://www.linuxfoundation.org/en/LSB}. August~9, 2006.
\bibitem{wireshark} Wireshark. \url{http://www.wireshark.org}. 2008.
-\bibitem{automata} {\it Hopcroft, J.~E. / Ullman, J.~D.}: Introduction to
+\bibitem{automata} {\it Hopcroft, J.\,E.\ / Ullman, J.\,D.}: Introduction to
Automata Theory, Languages and Computation. Adison-Wesley, Reading,
Mass.~1979.
-\bibitem{fsmmis} {\it Wagner, F. / Wolstenholme, P.}: State machine
+\bibitem{fsmmis} {\it Wagner, F.\ / Wolstenholme, P.}: State machine
misunderstandings. In: IEE journal ``Computing and Control Engineering'',
2004.