# HG changeset patch
# User Florian Pose <fp@igh-essen.com>
# Date 1225885867 0
# Node ID 704811cb6404c839516e4d02680578f89289049b
# Parent  50d6e13984b646c185b43fe3db3f2562f0f578dd
Debug interfaces.

diff -r 50d6e13984b6 -r 704811cb6404 documentation/ethercat_doc.tex
--- a/documentation/ethercat_doc.tex	Wed Nov 05 11:16:12 2008 +0000
+++ b/documentation/ethercat_doc.tex	Wed Nov 05 11:51:07 2008 +0000
@@ -2205,25 +2205,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!
 
 %------------------------------------------------------------------------------