# HG changeset patch # User Florian Pose # Date 1215163459 0 # Node ID 722ead4ecc225d2d7fed9b301d462ffac702e6d8 # Parent c75cdcc5ce8764d772236db92597f9c8792fb17f Doc: Architecture, master module, system integration. diff -r c75cdcc5ce87 -r 722ead4ecc22 documentation/ethercat_doc.tex --- 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}`