379 The EtherCAT master mainly consists of the master module, containing one or

   381 Kernel module containing one or more EtherCAT master instances (see

   380 more EtherCAT masters (section~\ref{sec:mastermod}), the ``Device Interface''

   382 section~\ref{sec:mastermod}), the ``Device Interface'' (see

   381 (section~\ref{sec:ecdev}) and the ``Realtime Interface''

   383 section~\ref{sec:ecdev}) and the ``Realtime Interface'' (see

   382 (section~\ref{sec:ecrt}).

   384 section~\ref{sec:ecrt}).

   387 Furthermore there are EtherCAT-capable network device driver

   389 EtherCAT-capable Ethernet device driver modules\index{Device modules}, that

   388 modules\index{Device modules}, that connect to the EtherCAT master via the

   390 offer their devices to the EtherCAT master via the device interface (see

   389 device interface. These modified network drivers can handle both network

   391 section~\ref{sec:ecdev}). These modified network drivers can handle network

   390 devices used for EtherCAT operation and ``normal'' Ethernet devices. The

   392 devices used for EtherCAT operation and ``normal'' Ethernet devices in

   391 common case is, that the master module offers a single EtherCAT master: An

   393 parallel. A master can accept a certain device and then is able to send and

   392 EtherCAT-capable network device driver module connects one network device to

   394 receive EtherCAT frames. Ethernet devices declined by the master module are

   393 this master, that is now able to send and receive EtherCAT frames, while all

   395 connected to the kernel's network stack as usual.

   394 other network devices handled by the network driver get connected to the

   395 kernel's network stack as usual.

   398 

   398 \index{Application module}

   399 An application module''\index{Application module} is a kernel module, that

   399 

   400 uses the EtherCAT master (usually for cyclic exchange of process data with

   400 Kernel modules, that use the EtherCAT master (usually for cyclic exchange of

   401 EtherCAT slaves). These modules are not part of the EtherCAT master

   401 process data with EtherCAT slaves). These modules are not part of the EtherCAT

   402 code\footnote{Although there are some examples provided in the

   402 master code\footnote{Although there are some examples provided in the

   403 \textit{examples} directory, see chapter~\ref{chapter:usage}}, but have to be

   403 \textit{examples} directory, see chapter~\ref{chapter:examples}}, but have to

   404 generated or written by the application engineer. An application module can

   404 be generated or written by the user. An application module can ``request'' a

   405 ``request'' a master through the realtime interface (see

   405 master through the realtime interface (see section~\ref{sec:ecrt}). If this

   406 section~\ref{sec:ecrt}). If this succeeds, the module has the control over the

   406 succeeds, the module has the control over the master: It can provide a bus

   407 master: It can provide a bus configuration and exchange process data.

   407 configuration and exchange process data.

   414 The EtherCAT master has several phases (see fig.~\ref{fig:phases}):

   414 The EtherCAT master runs through several phases (see fig.~\ref{fig:phases}):

   425 master has no Ethernet device connected. No bus communication is possible.

   425 master still waits for its Ethernet device to connect. No bus communication is

   426 

   426 possible until then.

   427 \item[Idle phase]\index{Idle phase} takes effect when the master has an

   427 

   428 Ethernet device connected, but is not requested by any application. The master

   428 \item[Idle phase]\index{Idle phase} takes effect when the master has accepted

   429 an Ethernet device, but is not requested by any application yet. The master

   449 \section{The Master Module} % FIXME

   450 \section{Master Module}

   450 \label{sec:mastermod}

   451 \label{sec:mastermodule}

   453 The EtherCAT master is designed to run as a kernel module. Moreover

   454 The EtherCAT master kernel module \textit{ec\_master} can contain multiple

   454 the master kernel module \textit{ec\_master} can handle multiple

   455 master instances. Each master waits for a certain Ethernet device identified

   455 masters at the same time: The number of masters has to be passed to

   456 by its MAC address\index{MAC address}. These addresses have to be specified on

   456 the module with the parameter \textit{ec\_master\_count}, that

   457 module loading via the \textit{main\_devices} module parameter. The number of

   457 defaults to $1$. A certain master can later be addressed by its index.

   458 master instances to initialize is taken from the number of MAC addresses

   458 For example, if the master module has been loaded with the command

   459 given.

   459 

   460 

   460 \begin{lstlisting}[gobble=2]

   461 The below command loads the master module with a single master instance that

   461   # `\textbf{modprobe ec\_master ec\_master\_count=2}`

   462 waits for the Ethernet device with the MAC address

   462 \end{lstlisting}

   463 \lstinline+00:0E:0C:DA:A2:20+. The master will be accessible via index $0$.

   463 

   464 

   464 the two masters can be addressed by their indices 0 and 1 respectively

   465 \begin{lstlisting}

   465 (see figure~\ref{fig:masters}). This master index mandatory for

   466 # `\textbf{modprobe ec\_master main\_devices=00:0E:0C:DA:A2:20}`

   466 certain functions of the master interfaces.

   467 \end{lstlisting}

   468 

   469 MAC addresses for multiple masters have to be separated by commas:

   470 

   471 \begin{lstlisting}

   472 # `\textbf{modprobe ec\_master main\_devices=00:0E:0C:DA:A2:20,00:e0:81:71:d5:1c}`

   473 \end{lstlisting}

   474 

   475 The two masters can be addressed by their indices 0 and 1 respectively (see

   476 figure~\ref{fig:masters}). The master index is needed for the

   477 \lstinline+ecrt_master_request()+ function of the realtime interface (see

   478 section~\ref{sec:ecrt}) and the \lstinline+--master+ option of the

   479 \textit{ethercat} command-line tool (see section~\ref{sec:ethercat}), which

   480 defaults to $0$.

   475 \paragraph{Master Log Messages}

   489 \paragraph{Init script}

   476 

   490 \index{Init script}

   477 The master module gives information about it's state and events via

   491 

   478 the Syslog interface. The module loading command above should result

   492 Most probably you won't want to load the master module and the Ethernet driver

   479 in the Syslog messages below (or similar):

   493 modules manually, but start the master as a service. See

   480 

   494 section~\ref{sec:system} on how to do this.

   481 \begin{lstlisting}[gobble=2]

   495 

   482   EtherCAT: Master driver, 1.1 (stable) - rev. 513,

   496 \paragraph{Syslog}

   483             compiled by fp at Aug  09 2006 09:43:50

   497 

   484   EtherCAT: Initializing 2 EtherCAT master(s)...

   498 The master module outputs information about it's state and events to the

   485   EtherCAT: Initializing master 0.

   499 kernel ring buffer. These also end up in the system logs.  The above module

   486   EtherCAT: Initializing master 1.

   500 loading command should result in the messages below:

   487   EtherCAT: Master driver initialized.

   501 

   488 \end{lstlisting}

   502 \begin{lstlisting}

   489 

   503 # `\textbf{dmesg | tail -2}`

   490 The master provides information about it's version number, subversion

   504 EtherCAT: Master driver `\masterversion`

   491 revision number and compile information, like the date of compilation

   505 EtherCAT: 2 masters waiting for devices.

   492 and the user, who compiled. All messages are prefixed either with

   506 

   493 \texttt{EtherCAT:}, \texttt{EtherCAT WARNING:} or \texttt{EtherCAT

   507 # `\textbf{tail -2 /var/log/messages}`

   494   ERROR:}, which makes searching the logs easier.

   508 Jul  4 10:22:45 ethercat kernel: EtherCAT: Master driver `\masterversion`

   509 Jul  4 10:22:45 ethercat kernel: EtherCAT: 2 masters waiting

   510                                  for devices.

   511 \end{lstlisting}

   512 

   513 All EtherCAT master output is prefixed with \lstinline+EtherCAT+ which makes

   514 searching the logs easier.

  3351 To integrate the EtherCAT master into a running system, it has to be

  3371 To integrate the EtherCAT master as a service into a running system, it comes

  3352 guaranteed, that it is started on system startup. In addition, there has

  3372 with an init script and a sysconfig file, that are described below.

  3353 to be a persistent configuration, that is also applied on startup.

  3373 

  3354 

  3374 \subsection{Init Script}

  3355 \subsubsection{The EtherCAT Init Script}

  3359 The EtherCAT master provides an ``init script'', that conforms to the

  3378 The EtherCAT master init script conforms to the requirements of the ``Linux

  3360 requirements of the ``Linux Standard Base'' (LSB\index{LSB},

  3379 Standard Base'' (LSB\index{LSB}, \cite{lsb}). The script is installed to

  3361 \cite{lsb}). The script is installed to \textit{etc/init.d/ethercat}

  3380 \textit{etc/init.d/ethercat} below the installation prefix and has to be copied

  3362 below the installation prefix and has to be copied to the appropriate

  3381 (or better: linked) to the appropriate location (see

  3363 location (see section~\ref{sec:make}), before the master can be

  3382 section~\ref{sec:install}), before the master can be inserted as a service.

  3364 inserted as a service. The different Linux distributions offer

  3383 Please note, that the init script depends on the sysconfig file described

  3365 different ways to mark the service for starting and stopping in

  3384 below.

  3366 certain runlevels (for example, SUSE Linux provides the

  3385 

  3367 \textit{insserv} command).

  3386 To provide service dependencies (i.~e. which services have to be started before

  3368 

  3387 others) inside the init script code, LSB defines a special comment block.

  3369 To provide service dependencies (i.~e. which services have to be

  3388 System tools can extract this information to insert the EtherCAT init script at

  3370 started before) right inside the init script code, LSB defines a

  3389 the correct place in the startup sequence:

  3371 special comment block. System tools can extract this information to

  3390 

  3372 insert the EtherCAT init script at the correct place in the startup

  3391 \lstinputlisting[firstline=38,lastline=48]

  3373 sequence:

  3392     {../script/init.d/ethercat}

  3374 

  3393 

  3375 \begin{lstlisting}[gobble=2]

  3394 \subsection{Sysconfig}

  3376   ### BEGIN INIT INFO

  3395 \label{sec:sysconfig}

  3377   # Provides:          ethercat

  3396 \index{Sysconfig file}

  3378   # Required-Start:    $local_fs $syslog $network

  3397 

  3379   # Should-Start:      $time

  3398 For persistent configuration, the init script uses a sysconfig file installed

  3380   # Required-Stop:     $local_fs $syslog $network

  3399 to \textit{etc/sysconfig/ethercat} (below the installation prefix), that is

  3381   # Should-Stop:       $time

  3400 mandatory for the init script. The sysconfig file contains all configuration

  3382   # Default-Start:     3 5

  3401 variables needed to operate one or more masters. The documentation is inside

  3383   # Default-Stop:      0 1 2 6

  3402 the file and included below:

  3384   # Short-Description: EtherCAT master modules

  3403 

  3385   # Description:

  3404 \lstinputlisting[numbers=left,firstline=9,basicstyle=\ttfamily\scriptsize]

  3386   ### END INIT INFO

  3405     {../script/sysconfig/ethercat}

  3406 

  3407 \subsection{Service}

  3408 \label{sec:service}

  3409 \index{Service}

  3410 

  3411 After the init script and the sysconfig file are placed into the right

  3412 location, the EtherCAT master can be inserted as a service. The different Linux

  3413 distributions offer different ways to mark a service for starting and stopping

  3414 in certain runlevels. For example, SUSE Linux provides the \textit{insserv}

  3415 command:

  3416 

  3417 \begin{lstlisting}

  3418 # `\textbf{insserv ethercat}`

  3709 recommended for manual (un-)loading.}, the init script and the sysconfig file

  3702 recommended for manual (un-)loading.} (see section~\ref{sec:system}), the init

  3710 have to be copied (or linked) to the appropriate locations. The below example

  3703 script and the sysconfig file have to be copied (or linked) to the appropriate

  3711 is suitable for SUSE Linux. It may vary for other distributions.

  3704 locations. The below example is suitable for SUSE Linux. It may vary for other

  3705 distributions.