--- a/documentation/ethercat_doc.tex Thu Jul 03 15:17:51 2008 +0000
+++ b/documentation/ethercat_doc.tex Fri Jul 04 09:24:19 2008 +0000
@@ -218,6 +218,8 @@
\item Designed as a kernel module for Linux 2.6.
+\item Implemented according to IEC 61158-12 \cite{dlspec} \cite{alspec}.
+
\item Comes with EtherCAT-capable drivers for several common Ethernet devices.
\begin{itemize}
@@ -376,42 +378,40 @@
\paragraph{Master Module}
\index{Master module}
-The EtherCAT master mainly consists of the master module, containing one or
-more EtherCAT masters (section~\ref{sec:mastermod}), the ``Device Interface''
-(section~\ref{sec:ecdev}) and the ``Realtime Interface''
-(section~\ref{sec:ecrt}).
+Kernel module containing one or more EtherCAT master instances (see
+section~\ref{sec:mastermod}), the ``Device Interface'' (see
+section~\ref{sec:ecdev}) and the ``Realtime Interface'' (see
+section~\ref{sec:ecrt}).
\paragraph{Device Modules}
\index{Device modules}
-Furthermore there are EtherCAT-capable network device driver
-modules\index{Device modules}, that connect to the EtherCAT master via the
-device interface. These modified network drivers can handle both network
-devices used for EtherCAT operation and ``normal'' Ethernet devices. The
-common case is, that the master module offers a single EtherCAT master: An
-EtherCAT-capable network device driver module connects one network device to
-this master, that is now able to send and receive EtherCAT frames, while all
-other network devices handled by the network driver get connected to the
-kernel's network stack as usual.
+EtherCAT-capable Ethernet device driver modules\index{Device modules}, that
+offer their devices to the EtherCAT master via the device interface (see
+section~\ref{sec:ecdev}). These modified network drivers can handle network
+devices used for EtherCAT operation and ``normal'' Ethernet devices in
+parallel. A master can accept a certain device and then is able to send and
+receive EtherCAT frames. Ethernet devices declined by the master module are
+connected to the kernel's network stack as usual.
\paragraph{Application Modules}
-
-An application module''\index{Application module} is a kernel module, that
-uses the EtherCAT master (usually for cyclic exchange of process data with
-EtherCAT slaves). These modules are not part of the EtherCAT master
-code\footnote{Although there are some examples provided in the
-\textit{examples} directory, see chapter~\ref{chapter:usage}}, but have to be
-generated or written by the application engineer. An application module can
-``request'' a master through the realtime interface (see
-section~\ref{sec:ecrt}). If this succeeds, the module has the control over the
-master: It can provide a bus configuration and exchange process data.
+\index{Application module}
+
+Kernel modules, that use the EtherCAT master (usually for cyclic exchange of
+process data with EtherCAT slaves). These modules are not part of the EtherCAT
+master code\footnote{Although there are some examples provided in the
+\textit{examples} directory, see chapter~\ref{chapter:examples}}, but have to
+be generated or written by the user. An application module can ``request'' a
+master through the realtime interface (see section~\ref{sec:ecrt}). If this
+succeeds, the module has the control over the master: It can provide a bus
+configuration and exchange process data.
%------------------------------------------------------------------------------
\section{Phases}
\index{Master phases}
-The EtherCAT master has several phases (see fig.~\ref{fig:phases}):
+The EtherCAT master runs through several phases (see fig.~\ref{fig:phases}):
\begin{figure}[htbp]
\centering
@@ -422,10 +422,11 @@
\begin{description}
\item[Orphaned phase]\index{Orphaned phase} This mode takes effect, when the
-master has no Ethernet device connected. No bus communication is possible.
-
-\item[Idle phase]\index{Idle phase} takes effect when the master has an
-Ethernet device connected, but is not requested by any application. The master
+master still waits for its Ethernet device to connect. No bus communication is
+possible until then.
+
+\item[Idle phase]\index{Idle phase} takes effect when the master has accepted
+an Ethernet device, but is not requested by any application yet. The master
runs its state machine (see section~\ref{sec:fsm-master}), that automatically
scans the bus for slaves and executes pending operations from the user space
interface (for example Sdo access). The command-line tool can be used to access
@@ -446,24 +447,37 @@
%------------------------------------------------------------------------------
-\section{The Master Module} % FIXME
-\label{sec:mastermod}
+\section{Master Module}
+\label{sec:mastermodule}
\index{Master module}
-The EtherCAT master is designed to run as a kernel module. Moreover
-the master kernel module \textit{ec\_master} can handle multiple
-masters at the same time: The number of masters has to be passed to
-the module with the parameter \textit{ec\_master\_count}, that
-defaults to $1$. A certain master can later be addressed by its index.
-For example, if the master module has been loaded with the command
-
-\begin{lstlisting}[gobble=2]
- # `\textbf{modprobe ec\_master ec\_master\_count=2}`
-\end{lstlisting}
-
-the two masters can be addressed by their indices 0 and 1 respectively
-(see figure~\ref{fig:masters}). This master index mandatory for
-certain functions of the master interfaces.
+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 realtime interface (see
+section~\ref{sec:ecrt}) and the \lstinline+--master+ option of the
+\textit{ethercat} command-line tool (see section~\ref{sec:ethercat}), which
+defaults to $0$.
\begin{figure}[htbp]
\centering
@@ -472,26 +486,32 @@
\label{fig:masters}
\end{figure}
-\paragraph{Master Log Messages}
-
-The master module gives information about it's state and events via
-the Syslog interface. The module loading command above should result
-in the Syslog messages below (or similar):
-
-\begin{lstlisting}[gobble=2]
- EtherCAT: Master driver, 1.1 (stable) - rev. 513,
- compiled by fp at Aug 09 2006 09:43:50
- EtherCAT: Initializing 2 EtherCAT master(s)...
- EtherCAT: Initializing master 0.
- EtherCAT: Initializing master 1.
- EtherCAT: Master driver initialized.
-\end{lstlisting}
-
-The master provides information about it's version number, subversion
-revision number and compile information, like the date of compilation
-and the user, who compiled. All messages are prefixed either with
-\texttt{EtherCAT:}, \texttt{EtherCAT WARNING:} or \texttt{EtherCAT
- ERROR:}, which makes searching the logs easier.
+\paragraph{Init script}
+\index{Init script}
+
+Most probably you won't want to load the master module and the Ethernet driver
+modules manually, but start the master as a service. See
+section~\ref{sec:system} on how to do this.
+
+\paragraph{Syslog}
+
+The master module outputs information about it's 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.
%------------------------------------------------------------------------------
@@ -3348,42 +3368,54 @@
\section{System Integration}
\label{sec:system}
-To integrate the EtherCAT master into a running system, it has to be
-guaranteed, that it is started on system startup. In addition, there has
-to be a persistent configuration, that is also applied on startup.
-
-\subsubsection{The EtherCAT Init Script}
+To integrate the EtherCAT master as a service into a running system, it comes
+with an init script and a sysconfig file, that are described below.
+
+\subsection{Init Script}
\label{sec:init}
\index{Init script}
-The EtherCAT master provides an ``init script'', that conforms to the
-requirements of the ``Linux Standard Base'' (LSB\index{LSB},
-\cite{lsb}). The script is installed to \textit{etc/init.d/ethercat}
-below the installation prefix and has to be copied to the appropriate
-location (see section~\ref{sec:make}), before the master can be
-inserted as a service. The different Linux distributions offer
-different ways to mark the service for starting and stopping in
-certain runlevels (for example, SUSE Linux provides the
-\textit{insserv} command).
-
-To provide service dependencies (i.~e. which services have to be
-started before) right 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:
-
-\begin{lstlisting}[gobble=2]
- ### BEGIN INIT INFO
- # Provides: ethercat
- # Required-Start: $local_fs $syslog $network
- # Should-Start: $time
- # Required-Stop: $local_fs $syslog $network
- # Should-Stop: $time
- # Default-Start: 3 5
- # Default-Stop: 0 1 2 6
- # Short-Description: EtherCAT master modules
- # Description:
- ### END INIT INFO
+The EtherCAT master init script conforms to the requirements of the ``Linux
+Standard Base'' (LSB\index{LSB}, \cite{lsb}). The script is installed to
+\textit{etc/init.d/ethercat} below the installation prefix and has to be copied
+(or better: linked) to the appropriate location (see
+section~\ref{sec:install}), 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
+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}
+
+\subsection{Sysconfig}
+\label{sec:sysconfig}
+\index{Sysconfig file}
+
+For persistent configuration, the init script uses a sysconfig file installed
+to \textit{etc/sysconfig/ethercat} (below the installation prefix), that is
+mandatory for the init script. The sysconfig file contains all configuration
+variables needed to operate one or more masters. The documentation is inside
+the file and included below:
+
+\lstinputlisting[numbers=left,firstline=9,basicstyle=\ttfamily\scriptsize]
+ {../script/sysconfig/ethercat}
+
+\subsection{Service}
+\label{sec:service}
+\index{Service}
+
+After the init script and the sysconfig file are placed into the right
+location, the EtherCAT master can be inserted as a service. The different Linux
+distributions offer different ways to mark a service for starting and stopping
+in certain runlevels. For example, SUSE Linux provides the \textit{insserv}
+command:
+
+\begin{lstlisting}
+# `\textbf{insserv ethercat}`
\end{lstlisting}
The init script can also be used for manually starting and stopping
@@ -3396,45 +3428,6 @@
Starting EtherCAT master done
\end{lstlisting}
-\subsubsection{Sysconfig} % FIXME
-\label{sec:sysconfig}
-\index{Sysconfig file}
-
-For persistent configuration, the init script uses a sysconfig file
-installed to \textit{etc/sysconfig/ethercat} (below the installation
-prefix), that is mandatory for the init script. The sysconfig file
-contains all configuration variables needed to operate a master:
-
-\begin{description}
-\item[DEVICE\_INDEX] This variable must contain the PCI index of the
- EtherCAT device. Setting this is mandatory for the EtherCAT init
- script. Default: $-1$
-\item[EOE\_INTERFACES] The number of virtual Ethernet-over-EtherCAT
- interfaces, every master creates on startup. See
- section~\ref{sec:eoeimp}. Default: $0$
-\item[EOE\_BRIDGE] If this variable is set, all EoE interfaces will be
- added to a network bridge according to IEEE 802.1D after master
- startup. The variable must contain the name of the bridge. To use
- this functionality, the kernel must be configured with the
- CONFIG\_BRIDGE option and the \textit{bridge-utils} package must be
- installed (i.~e. the \textit{brctl} command is needed).
-\item[EOE\_IP\_ADDRESS] The IP address of the EoE bridge. Setting this
- together with \$EOE\_IP\_NETMASK will let the local host communicate
- with devices on the EoE bridge.
-\item[EOE\_IP\_NETMASK] IP netmask of the EoE bridge.
-\item[EOE\_EXTRA\_INTERFACES] The list of extra interfaces to include
- in the EoE brid\-ge. Set this to interconnect the EoE bridge with
- other local interfaces. If \$EOE\_\-BRIDGE is empty or undefined,
- setting this variable has no effect. Important: The IP address of
- the listed interfaces will be cleared. Setting
- \$EOE\_\-IP\_\-ADDRESS and \$EOE\_IP\_NETMASK will re-enable them
- for IP traffic.
-\item[EOE\_GATEWAY] The IP address of the default gateway. If this
- variable is set, the gateway will be renewed after bridge
- installation. This is necessary, if the default gateway's interface
- is one of the \$EOE\_EXTRA\_INTERFACES.
-\end{description}
-
%------------------------------------------------------------------------------
\section{Monitoring and Debugging}
@@ -3706,9 +3699,10 @@
If the EtherCAT master shall be run as a service\footnote{Even if the EtherCAT
master shall not be loaded on system startup, the use of the init script is
-recommended for manual (un-)loading.}, the init script and the sysconfig file
-have to be copied (or linked) to the appropriate locations. The below example
-is suitable for SUSE Linux. It may vary for other distributions.
+recommended for manual (un-)loading.} (see section~\ref{sec:system}), the init
+script and the sysconfig file have to be copied (or linked) to the appropriate
+locations. The below example is suitable for SUSE Linux. It may vary for other
+distributions.
\begin{lstlisting}[gobble=2]
# `\textbf{cd /opt/etherlab}`