etherlabmaster: comparison documentation/ethercat

equal deleted inserted replaced

-:de3fcbb6773e
+:a27c839d043b
 The EtherCAT master is integrated into the Linux 2.6 kernel. This was
 an early design decision, which has been made for several reasons:
 \begin{itemize}
-\item Kernel code has significantly better realtime characteristics,
+\item Kernel code has significantly better realtime characteristics, i.\,e.\
-i.\,e.~less latency than userspace code. It was foreseeable, that a fieldbus
+less latency than userspace code. It was foreseeable, that a fieldbus master
-master has a lot of cyclic work to do. Cyclic work is usually triggered by
+has a lot of cyclic work to do. Cyclic work is usually triggered by timer
-timer interrupts inside the kernel. The execution delay of a function that
+interrupts inside the kernel. The execution delay of a function that processes
-processes timer interrupts is less, when it resides in kernelspace, because
+timer interrupts is less, when it resides in kernelspace, because there is no
-there is no need of time-consuming context switches to a userspace process.
+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
 anyway (through network device drivers), which is one more reason for the
 master code being in kernelspace.
 \end{description}
 %------------------------------------------------------------------------------
-\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
 \includegraphics[width=.9\textwidth]{images/phases}
 \caption{Master phases and transitions}
 \item[Operation phase]\index{Operation phase} The master is requested by an
 application that can provide a bus configuration and exchange process data.
 \end{description}
-%------------------------------------------------------------------------------
-\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}
 application. The state of a slave configuration can either be queried via the
 application interface or via the command-line tool (see
 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}).
 Table~\ref{tab:slaveposition} shows, how the values are interpreted.
 \item[\usebox\boxopen] This function is called when network communication has
 to be started, for example after a command \lstinline+ip link set ethX up+
 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
 \lstinline+sk_buff+ structure (``socket buffer''\index{Socket buffer}, see
 below), which has to be freed after sending.
 The below sections describe every state machine used in the EtherCAT master.
 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.
 %------------------------------------------------------------------------------
 \section{The Master State Machine}
 \item[Pdo Sync Manager Configuration] If any Pdo sync managers exist, they are
 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.
 If this is the requested state, the state machine is finished.
 \end{figure}
 \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
 is issued again, until it is acknowledged.
 \section{Ethernet-over-EtherCAT (EoE)}
 \label{sec:eoe}
 \index{EoE}
-The EtherCAT master implements the Ethernet-over-EtherCAT mailbox protocol to
+The EtherCAT master implements the
-enable the tunneling of Ethernet frames to special slaves, that can either
+Ethernet-over-EtherCAT\nomenclature{EoE}{Ethernet-over-EtherCAT, Mailbox
-have physical Ethernet ports to forward the frames to, or have an own IP stack
+Protocol} mailbox protocol~\cite[sec.~5.7]{alspec} to enable the tunneling of
-to receive the frames.
+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}
 The master creates a virtual EoE network interface for every EoE-capable
 slave. These interfaces are called either
 \section{CANopen-over-EtherCAT (CoE)}
 \label{sec:coe}
 \index{CoE}
-The CANopen-over-EtherCAT protocol \cite[sec.~5.6]{alspec} is used to
+The CANopen-over-EtherCAT\nomenclature{CoE}{CANopen-over-EtherCAT, Mailbox
-configure slaves and exchange data objects on application level.
+Protocol} protocol~\cite[sec.~5.6]{alspec} is used to configure slaves and
+exchange data objects on application level.
 % TODO
 %
 % Download / Upload
 % Expedited / Normal
 copied (or better: linked) to the appropriate location (see
 sec.~\ref{sec:installation}), before the master can be inserted as a service.
 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
+To provide service dependencies (i.\,e.\ which services have to be started
-others) inside the init script code, LSB defines a special comment block.
+before others) inside the init script code, LSB defines a special comment
-System tools can extract this information to insert the EtherCAT init script at
+block. System tools can extract this information to insert the EtherCAT init
-the correct place in the startup sequence:
+script at the correct place in the startup sequence:
 \lstinputlisting[firstline=38,lastline=48]
 {../script/init.d/ethercat}
 \subsection{Sysconfig File}
 \section{Monitoring and Debugging}
 \label{sec:debug}
 \index{Monitoring}
-% FIXME
+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
-For debugging purposes, every EtherCAT master registers a read-only network
+Wireshark~\cite{wireshark}, for example.
-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
+For convenience, so-called ``debug interfaces'' are supported. Debug interfaces
-received to this interface.
+allow to monitor EtherCAT traffic with a network monitor (like Wireshark or
+tcpdump) running on the same machine. To use this functionality, the master
-This makes it possible to connect an network monitor (like Wireshark or
+sources have to be configured with the \lstinline+--enable-debug-if+ switch
-tcpdump) to the debug interface and monitor the EtherCAT frames.
+(see sec.~\ref{sec:installation}).
-% FIXME schedule()
+Every EtherCAT master registers two read-only network interfaces. These are
-It has to be considered, that can be frame rate can be very high. The master
+named \textit{ecdbgmX} (main device) and \textit{ecdbgbX} (backup device for
-state machine usually runs every kernel timer interrupt (usually up to
+future use), where X is the master index. The debug interfaces are listed in
-\unit{1}{\kilo\hertz}) and with a connected application, the rate can be even
+the below output:
-higher.
+\begin{lstlisting}
-\paragraph{Attention:} The socket buffers needed for the operation of
+# `\textbf{ip link}`
-the debugging interface have to be allocated dynamically. Some Linux
+1: lo: <LOOPBACK,UP> mtu 16436 qdisc noqueue
-realtime extensions do not allow this in realtime context!
+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!
 %------------------------------------------------------------------------------
 \chapter{Timing Aspects}
 \label{sec:timing}
 \end{lstlisting}
 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}
 \bibitem{etherlab} Ingenieurgemeinschaft IgH: EtherLab -- Open Source Toolkit
 \bibitem{lgpl} GNU Lesser General Public License, Version 2.1.
 \url{http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html}. October~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.
 \bibitem{rtai} RTAI. The RealTime Application Interface for Linux from DIAPM.
 \url{http://www.rtai.org}, 2006.

changeset 1306	a27c839d043b
parent 1299	dd8e55d97280
child 1307	45a82ad140f8