
fp@369: %------------------------------------------------------------------------------
fp@369: %
fp@369: %  IgH EtherCAT Master Documentation
fp@369: %
fp@369: %  $Id$
fp@369: %
fp@1202: %  vi: spell spelllang=en tw=78
fp@1095: % 
fp@369: %------------------------------------------------------------------------------
fp@369: 
fp@369: \documentclass[a4paper,12pt,BCOR6mm,bibtotoc,idxtotoc]{scrbook}
fp@369: 
fp@369: \usepackage[latin1]{inputenc}
fp@369: \usepackage[automark,headsepline]{scrpage2}
fp@369: \usepackage{graphicx}
fp@369: \usepackage{makeidx}
fp@369: \usepackage[refpage]{nomencl}
fp@369: \usepackage{listings}
fp@369: \usepackage{svn}
fp@1085: \usepackage{SIunits}
fp@1275: \usepackage{hyperref}
fp@1275: 
fp@1275: \hypersetup{pdfpagelabels,plainpages=false}
fp@1275: \hypersetup{linkcolor=blue,colorlinks=true,urlcolor=blue}
fp@369: 
fp@369: \setlength{\parskip}{0.8ex plus 0.8ex minus 0.5ex}
fp@369: \setlength{\parindent}{0mm}
fp@369: 
fp@369: \setcounter{secnumdepth}{\subsubsectionlevel}
fp@369: 
fp@369: \DeclareFontShape{OT1}{cmtt}{bx}{n}
fp@369: {
fp@369:   <5><6><7><8><9><10><10.95><12><14.4><17.28><20.74><24.88>cmttb10
fp@369: }{}
fp@369: 
fp@369: \lstset{basicstyle=\ttfamily\small,numberstyle=\tiny,aboveskip=4mm,
fp@1085:   belowskip=2mm,escapechar=`}
fp@369: \renewcommand\lstlistlistingname{List of Listings}
fp@369: 
fp@917: % Workaround for lstlistoflistings bug
fp@917: \makeatletter% --> De-TeX-FAQ
fp@917: \renewcommand*{\lstlistoflistings}{%
fp@917:   \begingroup
fp@917:     \if@twocolumn
fp@917:       \@restonecoltrue\onecolumn
fp@917:     \else
fp@917:       \@restonecolfalse
fp@917:     \fi
fp@917:     \lol@heading
fp@917:     \setlength{\parskip}{\z@}%
fp@917:     \setlength{\parindent}{\z@}%
fp@917:     \setlength{\parfillskip}{\z@ \@plus 1fil}%
fp@917:     \@starttoc{lol}%
fp@917:     \if@restonecol\twocolumn\fi
fp@917:   \endgroup
fp@917: }
fp@917: \makeatother% --> \makeatletter
fp@917: 
fp@369: \renewcommand\nomname{Glossary}
fp@369: 
fp@369: \newcommand{\IgH}{\raisebox{-0.7667ex}
fp@369:   {\includegraphics[height=2.2ex]{images/ighsign}}}
fp@369: 
fp@369: \SVN $Date$
fp@369: \SVN $Revision$
fp@369: 
fp@1270: \newcommand{\masterversion}{1.5.0}
fp@1085: \newcommand{\linenum}[1]{\normalfont\textcircled{\tiny #1}}
fp@487: 
fp@369: \makeindex
fp@917: \makenomenclature
fp@369: 
fp@369: %------------------------------------------------------------------------------
fp@369: 
fp@369: \begin{document}
fp@369: 
fp@369: \pagenumbering{roman}
fp@369: \pagestyle{empty}
fp@369: 
fp@369: \begin{titlepage}
fp@369:   \begin{center}
fp@369:     \rule{\textwidth}{1.5mm}
fp@369: 
fp@369:     {\Huge\bf IgH \includegraphics[height=2.4ex]{images/ethercat}
fp@487:       Master \masterversion\\[1ex]
fp@1204:       Preliminary Documentation}
fp@369: 
fp@369:     \vspace{1ex}
fp@369:     \rule{\textwidth}{1.5mm}
fp@369: 
fp@1204:     \vspace{\fill} {\Large Dipl.-Ing. (FH) Florian Pose,
fp@1204:     \url{fp@igh-essen.com}\\[1ex] Ingenieurgemeinschaft \IgH}
fp@369: 
fp@369:     \vspace{\fill}
fp@369:     {\Large Essen, \SVNDate\\[1ex]
fp@369:       Revision \SVNRevision}
fp@369:   \end{center}
fp@369: \end{titlepage}
fp@369: 
fp@369: %------------------------------------------------------------------------------
fp@369: 
fp@369: \tableofcontents
fp@369: \listoftables
fp@369: \listoffigures
fp@1204: %\lstlistoflistings
fp@369: 
fp@369: %------------------------------------------------------------------------------
fp@369: 
fp@369: \newpage
fp@369: \pagestyle{scrheadings}
fp@369: 
fp@369: \section*{Conventions}
fp@369: \addcontentsline{toc}{section}{Conventions}
fp@369: \markleft{Conventions}
fp@369: 
fp@369: The following typographic conventions are used:
fp@369: 
fp@369: \begin{itemize}
fp@1085: 
fp@1085: \item \textit{Italic face} is used for newly introduced terms and file names.
fp@1085: 
fp@1085: \item \texttt{Typewriter face} is used for code examples and command line
fp@1085: output.
fp@1085: 
fp@1085: \item \texttt{\textbf{Bold typewriter face}} is used for user input in command
fp@1085: lines.
fp@1085: 
fp@369: \end{itemize}
fp@369: 
fp@1085: Data values and addresses are usually specified as hexadecimal values. These
fp@1085: are marked in the \textit{C} programming language style with the prefix
fp@1085: \lstinline+0x+ (example: \lstinline+0x88A4+). Unless otherwise noted, address
fp@1085: values are specified as byte addresses.
fp@369: 
fp@369: Function names are always printed with parentheses, but without
fp@1085: parameters. So, if a function \lstinline+ecrt_request_master()+ has
fp@1085: empty parentheses, this shall not imply that it has no parameters.
fp@1085: 
fp@1085: If shell commands have to be entered, this is marked by a dollar prompt:
fp@1085: 
fp@1085: \begin{lstlisting}
fp@1085: $
fp@369: \end{lstlisting}
fp@369: 
fp@369: Further, if a shell command has to be entered as the superuser, the
fp@1085: prompt is a mesh:
fp@1085: 
fp@1085: \begin{lstlisting}
fp@1085: #
fp@369: \end{lstlisting}
fp@369: 
fp@369: %------------------------------------------------------------------------------
fp@369: 
fp@369: \chapter{The IgH EtherCAT Master}
fp@369: \label{chapter:master}
fp@369: \pagenumbering{arabic}
fp@369: 
fp@1085: This chapter covers some general information about the EtherCAT master.
fp@369: 
fp@369: %------------------------------------------------------------------------------
fp@369: 
fp@369: \section{Feature Summary}
fp@369: \label{sec:summary}
fp@369: \index{Master!Features}
fp@369: 
fp@1085: The list below gives a short summary of the master features.
fp@369: 
fp@369: \begin{itemize}
fp@1085: 
fp@1085: \item Designed as a kernel module for Linux 2.6.
fp@1085: 
fp@1086: \item Implemented according to IEC 61158-12 \cite{dlspec} \cite{alspec}.
fp@1086: 
fp@1085: \item Comes with EtherCAT-capable drivers for several common Ethernet devices.
fp@1085: 
fp@369:   \begin{itemize}
fp@1085: 
fp@369:   \item The Ethernet hardware is operated without interrupts.
fp@1085: 
fp@1085:   \item Drivers for additional Ethernet hardware can easily be implemented
fp@1289:   using the common device interface (see sec.~\ref{sec:ecdev}) provided by the
fp@1289:   master module.
fp@1085: 
fp@369:   \end{itemize}
fp@1085: 
fp@1085: \item The master module supports multiple EtherCAT masters running in
fp@1085: parallel.
fp@1085: 
fp@1085: \item The master code supports any Linux realtime extension through its
fp@1085: independent architecture.
fp@1085: 
fp@369:   \begin{itemize}
fp@1085: 
fp@1085:   \item RTAI\nomenclature{RTAI}{Realtime Application Interface},
fp@1085:   ADEOS\nomenclature{ADEOS}{Adaptive Domain Environment for Operating
fp@1085:   Systems}, etc.
fp@1085: 
fp@369:   \item It runs well even without realtime extensions.
fp@1085: 
fp@369:   \end{itemize}
fp@1085: 
fp@1204: \item Common ``Application Interface'' for applications, that want to use
fp@1289: EtherCAT functionality (see chap.~\ref{chap:api}).
fp@1085: 
fp@1085: \item \textit{Domains} are introduced, to allow grouping of process
fp@1085:   data transfers with different slave groups and task periods.
fp@1085: 
fp@369:   \begin{itemize}
fp@1085: 
fp@1085:   \item Handling of multiple domains with different task periods.
fp@1085: 
fp@1085:   \item Automatic calculation of process data mapping, FMMU and sync manager
fp@1085:   configuration within each domain.
fp@1085: 
fp@369:   \end{itemize}
fp@1085: 
fp@1085: \item Communication through several finite state machines.
fp@1085: 
fp@369:   \begin{itemize}
fp@1085: 
fp@1085:   \item Automatic bus scanning after topology changes.
fp@1085: 
fp@1085:   \item Bus monitoring during operation.
fp@1085: 
fp@1085:   \item Automatic reconfiguration of slaves (for example after power failure)
fp@1085:   during operation.
fp@1085: 
fp@369:   \end{itemize}
fp@1085: 
fp@1085: \item CANopen-over-EtherCAT (CoE)
fp@1085: 
fp@369:   \begin{itemize}
fp@1085: 
fp@1085:   \item Sdo upload, download and information service.
fp@1085: 
fp@1085:   \item Slave configuration via Sdos.
fp@1085: 
fp@1275:   \item Sdo access from userspace and from the application.
fp@1085: 
fp@369:   \end{itemize}
fp@1085: 
fp@1085: \item Ethernet-over-EtherCAT (EoE)
fp@1085: 
fp@369:   \begin{itemize}
fp@1085: 
fp@1085:   \item Transparent use of EoE slaves via virtual network interfaces.
fp@1085: 
fp@1085:   \item Natively supports either a switched or a routed EoE network
fp@1085:   architecture.
fp@1085: 
fp@369:   \end{itemize}
fp@1085: 
fp@1289: \item Userspace command-line-tool ``ethercat`` (see sec.~\ref{sec:tool})
fp@1085: 
fp@369:   \begin{itemize}
fp@1085: 
fp@1085:   \item Showing the current bus with slaves, Pdos and Sdos.
fp@1085:   \item Showing the bus configuration.
fp@1085:   \item Showing domains and process data.
fp@1085:   \item Setting the master's debug level.
fp@1085:   \item Writing alias addresses.
fp@1085:   \item Sdo uploading/downloading.
fp@1085:   \item Reading/writing a slave's SII.
fp@1085:   \item Setting slave states.
fp@1085:   \item Generate slave description XML.
fp@1085: 
fp@369:   \end{itemize}
fp@1085: 
fp@369: \item Seamless system integration though LSB\nomenclature{LSB}{Linux
fp@369:     Standard Base} compliance.
fp@1085: 
fp@369:   \begin{itemize}
fp@1085: 
fp@1095:   \item Master and network device configuration via sysconfig files.
fp@1085: 
fp@1085:   \item Init script for master control.
fp@1085: 
fp@369:   \end{itemize}
fp@1085: 
fp@369: \item Virtual read-only network interface for monitoring and debugging
fp@369:   purposes.
fp@1085: 
fp@369: \end{itemize}
fp@369: 
fp@369: %------------------------------------------------------------------------------
fp@369: 
fp@369: \section{License}
fp@369: \label{sec:license}
fp@369: 
fp@1275: The master code is released under the terms and conditions of the GNU General
fp@1275: Public License (GPL \cite{gpl})\index{GPL}, version 2. Other developers, that
fp@1275: want to use EtherCAT with Linux systems, are invited to use the master code or
fp@1275: even participate on development.
fp@1275: 
fp@1275: To allow static linking of userspace application against the master's
fp@1289: application interface (see chap.~\ref{chap:api}), the userspace library (see
fp@1275: sec.~\ref{sec:userlib}) is licensed under the terms and conditions of the GNU
fp@1275: Lesser General Public License (LGPL \cite{lgpl})\index{LGPL}, version 2.1.
fp@369: 
fp@369: %------------------------------------------------------------------------------
fp@369: 
fp@1085: \chapter{Architecture}
fp@1299: \label{chap:arch}
fp@369: \index{Master!Architecture}
fp@369: 
fp@369: The EtherCAT master is integrated into the Linux 2.6 kernel. This was
fp@1085: an early design decision, which has been made for several reasons:
fp@369: 
fp@369: \begin{itemize}
fp@1085: 
fp@1306: \item Kernel code has significantly better realtime characteristics, i.\,e.\
fp@1306: less latency than userspace code. It was foreseeable, that a fieldbus master
fp@1306: has a lot of cyclic work to do. Cyclic work is usually triggered by timer
fp@1306: interrupts inside the kernel. The execution delay of a function that processes
fp@1306: timer interrupts is less, when it resides in kernelspace, because there is no
fp@1306: need of time-consuming context switches to a userspace process.
fp@1085: 
fp@369: \item It was also foreseeable, that the master code has to directly
fp@1085: communicate with the Ethernet hardware. This has to be done in the kernel
fp@1085: anyway (through network device drivers), which is one more reason for the
fp@1275: master code being in kernelspace.
fp@1085: 
fp@369: \end{itemize}
fp@369: 
fp@1085: Figure~\ref{fig:arch} gives a general overview of the master architecture.
fp@369: 
fp@369: \begin{figure}[htbp]
fp@369:   \centering
fp@1085:   \includegraphics[width=.9\textwidth]{images/architecture}
fp@1291:   \caption{Master Architecture}
fp@1085:   \label{fig:arch}
fp@369: \end{figure}
fp@369: 
fp@1291: The components of the master environment are described below:
fp@1291: 
fp@1291: \begin{description}
fp@1291: 
fp@1291: \item[Master Module]\index{Master Module} Kernel module containing one or more
fp@1291: EtherCAT master instances (see sec.~\ref{sec:mastermod}), the ``Device
fp@1291: Interface'' (see sec.~\ref{sec:ecdev}) and the ``Application Interface'' (see
fp@1291: chap.~\ref{chap:api}).
fp@1291: 
fp@1291: \item[Device Modules]\index{Device modules} EtherCAT-capable Ethernet device
fp@1291: driver modules\index{Device modules}, that offer their devices to the EtherCAT
fp@1291: master via the device interface (see sec.~\ref{sec:ecdev}). These modified
fp@1291: network drivers can handle network devices used for EtherCAT operation and
fp@1291: ``normal'' Ethernet devices in parallel. A master can accept a certain device
fp@1291: and then is able to send and receive EtherCAT frames. Ethernet devices
fp@1291: declined by the master module are connected to the kernel's network stack as
fp@1291: usual.
fp@1291: 
fp@1291: \item[Application]\index{Application} A program that uses the EtherCAT master
fp@1291: (usually for cyclic exchange of process data with EtherCAT slaves). These
fp@1291: programs are not part of the EtherCAT master code\footnote{Although there are
fp@1291: some examples provided in the \textit{examples/} directory.}, but have to be
fp@1291: generated or written by the user. An application can ``request'' a master
fp@1291: through the application interface (see chap.~\ref{chap:api}). If this
fp@1291: succeeds, it has the control over the master: It can provide a bus
fp@1291: configuration and exchange process data.  Applications can be kernel modules
fp@1291: (that use the kernel application interface directly) or userspace programs,
fp@1291: that use the application interface via the EtherCAT library (see
fp@1291: sec.~\ref{sec:userlib}).
fp@1291: 
fp@1291: \end{description}
fp@1085: 
fp@1085: %------------------------------------------------------------------------------
fp@1085: 
fp@1306: \section{Master Module}
fp@1306: \label{sec:mastermod}
fp@1306: \index{Master module}
fp@1306: 
fp@1306: The EtherCAT master kernel module \textit{ec\_master} can contain multiple
fp@1306: master instances. Each master waits for a certain Ethernet device identified
fp@1306: by its MAC address\index{MAC address}. These addresses have to be specified on
fp@1306: module loading via the \textit{main\_devices} module parameter. The number of
fp@1306: master instances to initialize is taken from the number of MAC addresses
fp@1306: given.
fp@1306: 
fp@1306: The below command loads the master module with a single master instance that
fp@1306: waits for the Ethernet device with the MAC address
fp@1306: \lstinline+00:0E:0C:DA:A2:20+. The master will be accessible via index $0$.
fp@1306: 
fp@1306: \begin{lstlisting}
fp@1306: # `\textbf{modprobe ec\_master main\_devices=00:0E:0C:DA:A2:20}`
fp@1306: \end{lstlisting}
fp@1306: 
fp@1306: MAC addresses for multiple masters have to be separated by commas:
fp@1306: 
fp@1306: \begin{lstlisting}
fp@1306: # `\textbf{modprobe ec\_master main\_devices=00:0E:0C:DA:A2:20,00:e0:81:71:d5:1c}`
fp@1306: \end{lstlisting}
fp@1306: 
fp@1306: The two masters can be addressed by their indices 0 and 1 respectively (see
fp@1306: figure~\ref{fig:masters}). The master index is needed for the
fp@1306: \lstinline+ecrt_master_request()+ function of the application interface (see
fp@1306: chap.~\ref{chap:api}) and the \lstinline+--master+ option of the
fp@1306: \textit{ethercat} command-line tool (see sec.~\ref{sec:tool}), which defaults
fp@1306: to $0$.
fp@1306: 
fp@1306: \begin{figure}[htbp]
fp@1306:   \centering
fp@1306:   \includegraphics[width=.5\textwidth]{images/masters}
fp@1306:   \caption{Multiple masters in one module}
fp@1306:   \label{fig:masters}
fp@1306: \end{figure}
fp@1306: 
fp@1306: \paragraph{Init Script}
fp@1306: \index{Init script}
fp@1306: 
fp@1306: In most cases it is not necessary to load the master module and the Ethernet
fp@1306: driver modules manually. There is an init script available, so the master can
fp@1306: be started as a service (see sec.~\ref{sec:system}).
fp@1306: 
fp@1306: \paragraph{Syslog}
fp@1306: 
fp@1306: The master module outputs information about its state and events to the kernel
fp@1306: ring buffer. These also end up in the system logs.  The above module loading
fp@1306: command should result in the messages below:
fp@1306: 
fp@1306: \begin{lstlisting}
fp@1306: # `\textbf{dmesg | tail -2}`
fp@1306: EtherCAT: Master driver `\masterversion`
fp@1306: EtherCAT: 2 masters waiting for devices.
fp@1306: 
fp@1306: # `\textbf{tail -2 /var/log/messages}`
fp@1306: Jul  4 10:22:45 ethercat kernel: EtherCAT: Master driver `\masterversion`
fp@1306: Jul  4 10:22:45 ethercat kernel: EtherCAT: 2 masters waiting
fp@1306:                                  for devices.
fp@1306: \end{lstlisting}
fp@1306: 
fp@1306: All EtherCAT master output is prefixed with \lstinline+EtherCAT+ which makes
fp@1306: searching the logs easier.
fp@1306: 
fp@1306: %------------------------------------------------------------------------------
fp@1306: 
fp@1306: \section{Master Phases}
fp@1085: \index{Master phases}
fp@1085: 
fp@1306: Every EtherCAT master provided by the master module (see
fp@1306: sec.~\ref{sec:mastermod}) runs through several phases (see
fp@1306: fig.~\ref{fig:phases}):
fp@1085: 
fp@1085: \begin{figure}[htbp]
fp@1085:   \centering
fp@1085:   \includegraphics[width=.9\textwidth]{images/phases}
fp@1085:   \caption{Master phases and transitions}
fp@1085:   \label{fig:phases}
fp@1085: \end{figure}
fp@1291: 
fp@1085: \begin{description}
fp@1085: 
fp@1085: \item[Orphaned phase]\index{Orphaned phase} This mode takes effect, when the
fp@1086: master still waits for its Ethernet device to connect. No bus communication is
fp@1086: possible until then.
fp@1086: 
fp@1086: \item[Idle phase]\index{Idle phase} takes effect when the master has accepted
fp@1086: an Ethernet device, but is not requested by any application yet. The master
fp@1289: runs its state machine (see sec.~\ref{sec:fsm-master}), that automatically
fp@1275: scans the bus for slaves and executes pending operations from the userspace
fp@1275: interface (for example Sdo access). The command-line tool can be used to
fp@1275: access the bus, but there is no process data exchange because of the missing
fp@1275: bus configuration.
fp@1085: 
fp@1085: \item[Operation phase]\index{Operation phase} The master is requested by an
fp@1085: application that can provide a bus configuration and exchange process data.
fp@1085: 
fp@1085: \end{description}
fp@1085: 
fp@1085: %------------------------------------------------------------------------------
fp@1085: 
fp@1293: \section{Process Data}
fp@369: \label{sec:processdata}
fp@369: 
fp@1293: This section shall introduce a few terms and ideas how the master handles
fp@1293: process data.
fp@1085: 
fp@369: \paragraph{Process Data Image}
fp@369: \index{Process data}
fp@369: 
fp@1293: Slaves offer their inputs and outputs by presenting the master so-called
fp@1293: ``Process Data Objects'' (Pdos\index{Pdo}). The available Pdos can be either
fp@1293: determined by reading out the slave's TXPDO and RXPDO SII categories from the
fp@1293: E$^2$PROM (in case of fixed Pdos) or by reading out the appropriate CoE
fp@1293: objects (see sec.~\ref{sec:coe}), if available.  The application can register
fp@1293: the Pdos' entries for exchange during cyclic operation. The sum of all
fp@1293: registered Pdo entries defines the ``process data image'', which is exchanged
fp@1293: via datagrams with ``logical'' memory access (like LWR, LRD or LRW) introduced
fp@1293: in~\cite[sec.~5.4]{dlspec}.
fp@369: 
fp@369: \paragraph{Process Data Domains}
fp@369: \index{Domain}
fp@369: 
fp@1085: The process data image can be easily managed by creating so-called
fp@1293: ``domains'', which allow grouped Pdo exchange. They also take care of managing
fp@1293: the datagram structures needed to exchange the Pdos. Domains are mandatory for
fp@1293: process data exchange, so there has to be at least one. They were introduced
fp@1293: for the following reasons:
fp@369: 
fp@369: \begin{itemize}
fp@1293: 
fp@1293: \item The maximum size of a datagram is limited due to the limited size of an
fp@1293: Ethernet frame: The maximum data size is the Ethernet data field size minus
fp@1293: the EtherCAT frame header, EtherCAT datagram header and EtherCAT datagram
fp@1293: footer: $1500 - 2 - 12 - 2 = 1484$ octets. If the size of the process data
fp@1293: image exceeds this limit, multiple frames have to be sent, and the image has
fp@1293: to be partitioned for the use of multiple datagrams. A domain manages this
fp@1293: automatically.
fp@1293: 
fp@1293: \item Not every Pdo has to be exchanged with the same frequency: The values of
fp@1293: Pdos can vary slowly over time (for example temperature values), so exchanging
fp@1293: them with a high frequency would just waste bus bandwidth. For this reason,
fp@1293: multiple domains can be created, to group different Pdos and so allow separate
fp@1293: exchange.
fp@1293: 
fp@369: \end{itemize}
fp@369: 
fp@1293: There is no upper limit for the number of domains, but each domain occupies
fp@1293: one FMMU in each slave involved, so the maximum number of domains is de facto
fp@1293: limited by the slaves.
fp@369: 
fp@369: \paragraph{FMMU Configuration}
fp@369: \index{FMMU!Configuration}
fp@369: 
fp@1293: An application can register Pdo entries for exchange. Every Pdo entry and its
fp@1293: parent Pdo is part of a memory area in the slave's physical memory, that is
fp@1293: protected by a sync manager \cite[sec.~6.7]{dlspec} for synchronized access.
fp@1293: In order to make a sync manager react on a datagram accessing its memory, it
fp@1293: is necessary to access the last byte covered by the sync manager. Otherwise
fp@1293: the sync manager will not react on the datagram and no data will be exchanged.
fp@1293: That is why the whole synchronized memory area has to be included into the
fp@1293: process data image: For example, if a certain Pdo entry of a slave is
fp@1293: registered for exchange with a certain domain, one FMMU will be configured to
fp@1293: map the complete sync-manager-protected memory, the Pdo entry resides in. If a
fp@1293: second Pdo entry of the same slave is registered for process data exchange
fp@1293: within the same domain, and it resides in the same sync-manager-protected
fp@1293: memory as the first one, the FMMU configuration is not altered, because the
fp@1293: desired memory is already part of the domain's process data image. If the
fp@1293: second Pdo entry would belong to another sync-manager-protected area, this
fp@1293: complete area would also be included into the domains process data image.
fp@1293: 
fp@1293: Figure~\ref{fig:fmmus} gives an overview, how FMMUs are configured to map
fp@1293: physical memory to logical process data images.
fp@369: 
fp@369: \begin{figure}[htbp]
fp@369:   \centering
fp@369:   \includegraphics[width=\textwidth]{images/fmmus}
fp@1293:   \caption{FMMU Configuration}
fp@369:   \label{fig:fmmus}
fp@369: \end{figure}
fp@369: 
fp@1085: %------------------------------------------------------------------------------
fp@1085: 
fp@1085: \chapter{Application Interface}
fp@1289: \label{chap:api}
fp@1085: \index{Application interface}
fp@1085: 
fp@1297: % TODO
fp@1297: %
fp@1297: % Interface version
fp@1297: % Master Requesting and Releasing
fp@1297: % Master Locking
fp@1297: % Configuring Pdo assignment and mapping
fp@1297: % Domains (memory)
fp@1297: % Pdo entry registration
fp@1297: % Sdo configuration
fp@1297: % Sdo access
fp@1202: 
fp@1094: The application interface provides functions and data structures for
fp@1292: applications to access an EtherCAT master. The complete documentation of the
fp@1292: interface is included as Doxygen~\cite{doxygen} comments in the header file
fp@1292: \textit{include/ecrt.h}. It can either be read directly from the file
fp@1293: comments, or as a more comfortable HTML documentation. The HTML generation is
fp@1292: described in sec.~\ref{sec:gendoc}.
fp@1094: 
fp@1094: The following sections cover a general description of the application
fp@1094: interface.
fp@1094: 
fp@1094: Every application should use the master in two steps:
fp@1094: 
fp@1094: \begin{description}
fp@1094: 
fp@1094: \item[Configuration] The master is requested and the configuration is applied.
fp@1293: For example, domains are created, slaves are configured and Pdo entries are
fp@1293: registered (see sec.~\ref{sec:masterconfig}).
fp@1293: 
fp@1293: \item[Operation] Cyclic code is run and process data are exchanged (see
fp@1293: sec.~\ref{sec:cyclic}).
fp@1094: 
fp@1094: \end{description}
fp@1094: 
fp@1293: \paragraph{Example Applications}\index{Example Applications} There are a few
fp@1204: example applications in the \textit{examples/} subdirectory of the master
fp@1204: code. They are documented in the source code.
fp@1204: 
fp@1094: %------------------------------------------------------------------------------
fp@1094: 
fp@1094: \section{Master Configuration}
fp@1094: \label{sec:masterconfig}
fp@1094: 
fp@1293: The bus configuration is supplied via the application interface.
fp@1293: Figure~\ref{fig:app-config} gives an overview of the objects, that can be
fp@1293: configured by the application.
fp@1094: 
fp@1094: \begin{figure}[htbp]
fp@1094:   \centering
fp@1094:   \includegraphics[width=.8\textwidth]{images/app-config}
fp@1203:   \caption{Master Configuration}
fp@1094:   \label{fig:app-config}
fp@1094: \end{figure}
fp@1094: 
fp@1293: \subsection{Slave Configuration}
fp@1293: 
fp@1293: The application has to tell the master about the expected bus topology. This
fp@1293: can be done by creating ``slave configurations''. A slave configuration can be
fp@1293: seen as an expected slave. When a slave configuration is created, the
fp@1293: application provides the bus position (see below), vendor id and product code.
fp@1293: 
fp@1293: When the bus configuration is applied, the master checks, if there is a slave
fp@1293: with the given vendor id and product code at the given position. If this is
fp@1293: the case, the slave configuration is ``attached'' to the real slave on the bus
fp@1293: and the slave is configured according to the settings provided by the
fp@1293: application. The state of a slave configuration can either be queried via the
fp@1293: application interface or via the command-line tool (see
fp@1293: sec.~\ref{sec:ethercat-config}).
fp@1293: 
fp@1293: \paragraph{Slave Position} The slave position has to be specified as a tuple
fp@1306: of ``alias'' and ``position''. This allows addressing slaves either via an
fp@1293: absolute bus position, or a stored identifier called ``alias'', or a mixture
fp@1293: of both. The alias is a 16-bit value stored in the slave's E$^2$PROM. It can
fp@1293: be modified via the command-line tool (see sec.~\ref{sec:ethercat-alias}).
fp@1293: Table~\ref{tab:slaveposition} shows, how the values are interpreted.
fp@1293: 
fp@1293: \begin{table}[htbp]
fp@1293:   \centering
fp@1293:   \caption{Specifying a Slave Position}
fp@1293:   \label{tab:slaveposition}
fp@1293:   \vspace{2mm}
fp@1293:   \begin{tabular}{c|c|p{70mm}}
fp@1293:     Alias & Position & Interpretation\\
fp@1293:     \hline
fp@1293: 
fp@1293:     \lstinline+0+ & \lstinline+0+ -- \lstinline+65535+ &
fp@1293: 
fp@1293:     Position addressing. The position parameter is interpreted as the absolute
fp@1293:     ring position in the bus.\\ \hline
fp@1293: 
fp@1293:     \lstinline+1+ -- \lstinline+65535+ & \lstinline+0+ -- \lstinline+65535+ &
fp@1293: 
fp@1293:     Alias addressing. The position parameter is interpreted as relative
fp@1293:     position after the first slave with the given alias address. \\ \hline
fp@1293: 
fp@1293:   \end{tabular}
fp@1293: \end{table}
fp@1293: 
fp@1293: Figure~\ref{fig:attach} shows an example of how slave configurations are
fp@1293: attached. Some of the configurations were attached, while others remain
fp@1293: detached. The below lists gives the reasons beginning with the top slave
fp@1293: configuration.
fp@1293: 
fp@1293: \begin{figure}[htbp]
fp@1293:   \centering
fp@1293:   \includegraphics[width=.7\textwidth]{images/attach}
fp@1293:   \caption{Slave Configuration Attachment}
fp@1293:   \label{fig:attach}
fp@1293: \end{figure}
fp@1293: 
fp@1293: \begin{enumerate}
fp@1293: 
fp@1293: \item A zero alias means to use simple position addressing. Slave 1 exists and
fp@1293: vendor id and product code match the expected values.
fp@1293: 
fp@1293: \item Although the slave with position 0 is found, the product code does not
fp@1293: match, so the configuration is not attached.
fp@1293: 
fp@1293: \item The alias is non-zero, so alias addressing is used. Slave 2 is the first
fp@1293: slave with alias \lstinline+0x2000+. Because the position value is zero, the
fp@1293: same slave is used.
fp@1293: 
fp@1293: \item There is no slave with the given alias, so the configuration can not be
fp@1293: attached.
fp@1293: 
fp@1293: \item Slave 2 is again the first slave with the alias \lstinline+0x2000+, but
fp@1293: position is now 1, so slave 3 is attached.
fp@1293: 
fp@1293: \end{enumerate}
fp@1293: 
fp@1094: %------------------------------------------------------------------------------
fp@1094: 
fp@1094: \section{Cyclic Operation}
fp@1094: \label{sec:cyclic}
fp@1094: 
fp@1293: 
fp@1293: To enter cyclic operation mode, the master has to be ``activated'' to
fp@1293: calculate the process data image and apply the bus configuration for the first
fp@1293: time. After activation, the application is in charge to send and receive
fp@1293: frames.
fp@1293: 
fp@1297: % TODO
fp@1297: %
fp@1297: % PDO endianess
fp@1297: % Datagram injection
fp@1094: 
fp@1094: %------------------------------------------------------------------------------
fp@1094: 
fp@1298: \section{VoE Handlers}
fp@1298: \label{sec:api-voe}
fp@1298: 
fp@1298: During the configuration phase, the application can create handlers for the
fp@1298: VoE mailbox protocol described in sec.~\ref{sec:voe}. One VoE handler always
fp@1298: belongs to a certain slave configuration, so the creation function is a method
fp@1298: of the slave configuration.
fp@1298: 
fp@1298: A VoE handler manages the VoE data and the datagram used to transmit and
fp@1298: receive VoE messages. Is contains the state machine necessary to transfer VoE
fp@1298: messages.
fp@1298: 
fp@1298: The VoE state machine can only process one operation at a time. As a result,
fp@1298: either a read or write operation may be issued at a time\footnote{If
fp@1298: simultaneous sending and receiving is desired, two VoE handlers can be created
fp@1298: for the slave configuration.}. After the operation is initiated, the handler
fp@1298: must be executed cyclically until it is finished. After that, the results of
fp@1298: the operation can be retrieved.
fp@1298: 
fp@1298: A VoE handler has an own datagram structure, that is marked for exchange after
fp@1298: each execution step. So the application can decide, how many handlers to
fp@1298: execute before sending the corresponding EtherCAT frame(s).
fp@1298: 
fp@1298: For more information about the use of VoE handlers see the documentation of
fp@1298: the application interface functions and the example applications provided in
fp@1298: the \textit{examples/} directory.
fp@1298: 
fp@1298: %------------------------------------------------------------------------------
fp@1298: 
fp@1294: \section{Concurrent Master Access}
fp@1085: \label{sec:concurr}
fp@1085: \index{Concurrency}
fp@1085: 
fp@1085: In some cases, one master is used by several instances, for example when an
fp@1289: application does cyclic process data exchange, and there are EoE-capable
fp@1289: slaves that require to exchange Ethernet data with the kernel (see
fp@1289: sec.~\ref{sec:eoe}). For this reason, the master is a shared resource, and
fp@1289: access to it has to be sequentialized. This is usually done by locking with
fp@1085: semaphores, or other methods to protect critical sections.
fp@1085: 
fp@1085: The master itself can not provide locking mechanisms, because it has no chance
fp@1291: to know the appropriate kind of lock. For example if the application is in
fp@1291: kernelspace and uses RTAI functionality, ordinary kernel semaphores would not
fp@1291: be sufficient. For that, an important design decision was made: The
fp@1291: application that reserved a master must have the total control, therefore it
fp@1291: has to take responsibility for providing the appropriate locking mechanisms.
fp@1291: If another instance wants to access the master, it has to request the master
fp@1291: lock by callbacks, that have to be set by the application. Moreover the
fp@1291: application can deny access to the master if it considers it to be awkward at
fp@1291: the moment.
fp@369: 
fp@369: \begin{figure}[htbp]
fp@369:   \centering
fp@1085:   \includegraphics[width=.6\textwidth]{images/master-locks}
fp@1295:   \caption{Concurrent Master Access}
fp@1085:   \label{fig:locks}
fp@369: \end{figure}
fp@369: 
fp@1204: Figure~\ref{fig:locks} exemplary shows, how two processes share one master:
fp@1204: The application's cyclic task uses the master for process data exchange, while
fp@1204: the master-internal EoE process uses it to communicate with EoE-capable
fp@1204: slaves.  Both have to acquire the master lock before access: The application
fp@1204: task can access the lock natively, while the EoE process has to use the
fp@1294: callbacks. See the application interface documentation (chap.~\ref{chap:api})
fp@1294: for how to use the locking callbacks.
fp@1085: 
fp@1085: %------------------------------------------------------------------------------
fp@1085: 
fp@1202: \chapter{Ethernet Devices}
fp@1085: \label{sec:devices}
fp@1085: 
fp@1203: The EtherCAT protocol is based on the Ethernet standard, so a master relies on
fp@1203: standard Ethernet hardware to communicate with the bus.
fp@1085: 
fp@1085: The term \textit{device} is used as a synonym for Ethernet network interface
fp@1085: hardware. There are device driver modules that handle Ethernet hardware, which
fp@1203: a master can use to connect to an EtherCAT bus.
fp@369: 
fp@369: %------------------------------------------------------------------------------
fp@369: 
fp@1085: \section{Network Driver Basics}
fp@369: \label{sec:networkdrivers}
fp@369: \index{Network drivers}
fp@369: 
fp@369: EtherCAT relies on Ethernet hardware and the master needs a physical
fp@369: Ethernet device to communicate with the bus. Therefore it is necessary
fp@369: to understand how Linux handles network devices and their drivers,
fp@369: respectively.
fp@369: 
fp@369: \paragraph{Tasks of a Network Driver}
fp@369: 
fp@1095: Network device drivers usually handle the lower two layers of the OSI model,
fp@1095: that is the physical layer and the data-link layer. A network device itself
fp@1095: natively handles the physical layer issues: It represents the hardware to
fp@1095: connect to the medium and to send and receive data in the way, the physical
fp@1095: layer protocol describes. The network device driver is responsible for getting
fp@1095: data from the kernel's networking stack and forwarding it to the hardware,
fp@1095: that does the physical transmission.  If data is received by the hardware
fp@1095: respectively, the driver is notified (usually by means of an interrupt) and
fp@1095: has to read the data from the hardware memory and forward it to the network
fp@1095: stack. There are a few more tasks, a network device driver has to handle,
fp@1095: including queue control, statistics and device dependent features.
fp@369: 
fp@369: \paragraph{Driver Startup}
fp@369: 
fp@369: Usually, a driver searches for compatible devices on module loading.
fp@369: For PCI drivers, this is done by scanning the PCI bus and checking for
fp@369: known device IDs. If a device is found, data structures are allocated
fp@369: and the device is taken into operation.
fp@369: 
fp@369: \paragraph{Interrupt Operation}
fp@369: \index{Interrupt}
fp@369: 
fp@369: A network device usually provides a hardware interrupt that is used to
fp@1085: notify the driver of received frames and success of transmission, or
fp@369: errors, respectively. The driver has to register an interrupt service
fp@369: routine (ISR\index{ISR}\nomenclature{ISR}{Interrupt Service Routine}),
fp@369: that is executed each time, the hardware signals such an event. If the
fp@369: interrupt was thrown by the own device (multiple devices can share one
fp@369: hardware interrupt), the reason for the interrupt has to be determined
fp@369: by reading the device's interrupt register. For example, if the flag
fp@369: for received frames is set, frame data has to be copied from hardware
fp@369: to kernel memory and passed to the network stack.
fp@369: 
fp@1203: \paragraph{The \lstinline+net_device+ Structure}
fp@369: \index{net\_device}
fp@369: 
fp@1202: The driver registers a \lstinline+net_device+ structure for each device to
fp@1202: communicate with the network stack and to create a ``network interface''. In
fp@1275: case of an Ethernet driver, this interface appears as \textit{ethX}, where X
fp@1275: is a number assigned by the kernel on registration. The \lstinline+net_device+
fp@1275: structure receives events (either from userspace or from the network stack)
fp@1202: via several callbacks, which have to be set before registration. Not every
fp@1202: callback is mandatory, but for reasonable operation the ones below are needed
fp@1202: in any case:
fp@1202: 
fp@1202: \newsavebox\boxopen
fp@1202: \sbox\boxopen{\lstinline+open()+}
fp@1202: \newsavebox\boxstop
fp@1202: \sbox\boxstop{\lstinline+stop()+}
fp@1202: \newsavebox\boxxmit
fp@1202: \sbox\boxxmit{\lstinline+hard_start_xmit()+}
fp@1202: \newsavebox\boxstats
fp@1202: \sbox\boxstats{\lstinline+get_stats()+}
fp@369: 
fp@369: \begin{description}
fp@1095: 
fp@1202: \item[\usebox\boxopen] This function is called when network communication has
fp@1275: to be started, for example after a command \lstinline+ip link set ethX up+
fp@1275: from userspace. Frame reception has to be enabled by the driver.
fp@1202: 
fp@1297: \item[\usebox\boxstop] The purpose of this callback is to ``close'' the
fp@1306: device, i.\,e.\ make the hardware stop receiving frames.
fp@1202: 
fp@1202: \item[\usebox\boxxmit] This function is called for each frame that has to be
fp@1202: transmitted. The network stack passes the frame as a pointer to an
fp@1202: \lstinline+sk_buff+ structure (``socket buffer''\index{Socket buffer}, see
fp@1095: below), which has to be freed after sending.
fp@1095: 
fp@1202: \item[\usebox\boxstats] This call has to return a pointer to the device's
fp@1202: \lstinline+net_device_stats+ structure, which permanently has to be filled with
fp@1095: frame statistics. This means, that every time a frame is received, sent, or an
fp@1095: error happened, the appropriate counter in this structure has to be increased.
fp@1095: 
fp@1095: \end{description}
fp@1095: 
fp@1095: The actual registration is done with the \lstinline+register_netdev()+ call,
fp@1095: unregistering is done with \lstinline+unregister_netdev()+.
fp@369: 
fp@1203: \paragraph{The \lstinline+netif+ Interface}
fp@369: \index{netif}
fp@369: 
fp@1085: All other communication in the direction interface $\to$ network stack is done
fp@1202: via the \lstinline+netif_*()+ calls. For example, on successful device opening,
fp@1202: the network stack has to be notified, that it can now pass frames to the
fp@1202: interface. This is done by calling \lstinline+netif_start_queue()+. After this
fp@1202: call, the \lstinline+hard_start_xmit()+ callback can be called by the network
fp@1202: stack. Furthermore a network driver usually manages a frame transmission queue.
fp@1202: If this gets filled up, the network stack has to be told to stop passing
fp@1202: further frames for a while. This happens with a call to
fp@1202: \lstinline+netif_stop_queue()+. If some frames have been sent, and there is
fp@1095: enough space again to queue new frames, this can be notified with
fp@1095: \lstinline+netif_wake_queue()+. Another important call is
fp@1095: \lstinline+netif_receive_skb()+\footnote{This function is part of the NAPI
fp@1095: (``New API''), that replaces the kernel 2.4 technique for interfacing to the
fp@1095: network stack (with \lstinline+netif_rx()+). NAPI is a technique to improve
fp@1095: network performance on Linux. Read more in
fp@1095: \url{http://www.cyberus.ca/~hadi/usenix-paper.tgz}.}: It passes a frame to the
fp@1095: network stack, that was just received by the device. Frame data has to be
fp@1202: included in a so-called ``socket buffer'' for that (see below).
fp@369: 
fp@369: \paragraph{Socket Buffers}
fp@369: \index{Socket buffer}
fp@369: 
fp@1202: Socket buffers are the basic data type for the whole network stack. They serve
fp@1202: as containers for network data and are able to quickly add data headers and
fp@1202: footers, or strip them off again. Therefore a socket buffer consists of an
fp@1095: allocated buffer and several pointers that mark beginning of the buffer
fp@1202: (\lstinline+head+), beginning of data (\lstinline+data+), end of data
fp@1202: (\lstinline+tail+) and end of buffer (\lstinline+end+). In addition, a socket
fp@1202: buffer holds network header information and (in case of received data) a
fp@1202: pointer to the \lstinline+net_device+, it was received on. There exist
fp@1202: functions that create a socket buffer (\lstinline+dev_alloc_skb()+), add data
fp@1202: either from front (\lstinline+skb_push()+) or back (\lstinline+skb_put()+),
fp@1202: remove data from front (\lstinline+skb_pull()+) or back
fp@1202: (\lstinline+skb_trim()+), or delete the buffer (\lstinline+kfree_skb()+).  A
fp@1202: socket buffer is passed from layer to layer, and is freed by the layer that
fp@1202: uses it the last time. In case of sending, freeing has to be done by the
fp@1202: network driver.
fp@369: 
fp@369: %------------------------------------------------------------------------------
fp@369: 
fp@1085: \section{EtherCAT Device Drivers}
fp@1289: \label{sec:drivers}
fp@369: 
fp@1095: There are a few requirements for Ethernet network devices to function as
fp@1095: EtherCAT devices, when connected to an EtherCAT bus.
fp@369: 
fp@369: \paragraph{Dedicated Interfaces}
fp@369: 
fp@1095: For performance and realtime purposes, the EtherCAT master needs direct and
fp@1202: exclusive access to the Ethernet hardware. This implies that the network device
fp@1202: must not be connected to the kernel's network stack as usual, because the
fp@1202: kernel would try to use it as an ordinary Ethernet device.
fp@369: 
fp@369: \paragraph{Interrupt-less Operation}
fp@369: \index{Interrupt}
fp@369: 
fp@1202: EtherCAT frames travel through the logical EtherCAT ring and are then sent back
fp@1202: to the master. Communication is highly deterministic: A frame is sent and will
fp@1202: be received again after a constant time, so there is no need to notify the
fp@1202: driver about frame reception: The master can instead query the hardware for
fp@1202: received frames, if it expects them to be already received.
fp@1095: 
fp@1095: Figure~\ref{fig:interrupt} shows two workflows for cyclic frame transmission
fp@1095: and reception with and without interrupts.
fp@369: 
fp@369: \begin{figure}[htbp]
fp@369:   \centering
fp@1202:   \includegraphics[width=.9\textwidth]{images/interrupt}
fp@369:   \caption{Interrupt Operation versus Interrupt-less Operation}
fp@369:   \label{fig:interrupt}
fp@369: \end{figure}
fp@369: 
fp@1095: In the left workflow ``Interrupt Operation'', the data from the last cycle is
fp@1095: first processed and a new frame is assembled with new datagrams, which is then
fp@1095: sent.  The cyclic work is done for now.  Later, when the frame is received
fp@1095: again by the hardware, an interrupt is triggered and the ISR is executed. The
fp@1095: ISR will fetch the frame data from the hardware and initiate the frame
fp@1095: dissection: The datagrams will be processed, so that the data is ready for
fp@1095: processing in the next cycle.
fp@1095: 
fp@1095: In the right workflow ``Interrupt-less Operation'', there is no hardware
fp@1095: interrupt enabled.  Instead, the hardware will be polled by the master by
fp@1095: executing the ISR. If the frame has been received in the meantime, it will be
fp@1095: dissected. The situation is now the same as at the beginning of the left
fp@1095: workflow: The received data is processed and a new frame is assembled and
fp@1095: sent. There is nothing to do for the rest of the cycle.
fp@1095: 
fp@1202: The interrupt-less operation is desirable, because hardware interrupts are not
fp@1202: conducive in improving the driver's realtime behaviour: Their indeterministic
fp@1202: incidences contribute to increasing the jitter. Besides, if a realtime
fp@1202: extension (like RTAI) is used, some additional effort would have to be made to
fp@1202: prioritize interrupts.
fp@369: 
fp@369: \paragraph{Ethernet and EtherCAT Devices}
fp@369: 
fp@1095: Another issue lies in the way Linux handles devices of the same type.  For
fp@1095: example, a PCI\nomenclature{PCI}{Peripheral Component Interconnect, Computer
fp@1095: Bus} driver scans the PCI bus for devices it can handle. Then it registers
fp@1095: itself as the responsible driver for all of the devices found. The problem is,
fp@1095: that an unmodified driver can not be told to ignore a device because it will
fp@1095: be used for EtherCAT later. There must be a way to handle multiple devices of
fp@1095: the same type, where one is reserved for EtherCAT, while the other is treated
fp@369: as an ordinary Ethernet device.
fp@369: 
fp@1095: For all this reasons, the author decided that the only acceptable solution is
fp@1095: to modify standard Ethernet drivers in a way that they keep their normal
fp@1095: functionality, but gain the ability to treat one or more of the devices as
fp@1095: EtherCAT-capable.
fp@369: 
fp@369: Below are the advantages of this solution:
fp@369: 
fp@369: \begin{itemize}
fp@369: \item No need to tell the standard drivers to ignore certain devices.
fp@369: \item One networking driver for EtherCAT and non-EtherCAT devices.
fp@369: \item No need to implement a network driver from scratch and running
fp@369:   into issues, the former developers already solved.
fp@369: \end{itemize}
fp@369: 
fp@369: The chosen approach has the following disadvantages:
fp@369: 
fp@369: \begin{itemize}
fp@369: \item The modified driver gets more complicated, as it must handle
fp@369:   EtherCAT and non-EtherCAT devices.
fp@369: \item Many additional case differentiations in the driver code.
fp@1085: \item Changes and bug fixes on the standard drivers have to be ported
fp@369:   to the Ether\-CAT-capable versions from time to time.
fp@369: \end{itemize}
fp@369: 
fp@369: %------------------------------------------------------------------------------
fp@369: 
fp@1085: \section{Device Selection}
fp@1085: \label{sec:deviceselection}
fp@369: 
fp@1202: After loading the master module, at least one EtherCAT-capable network driver
fp@1202: module has to be loaded, that offers its devices to the master (see
fp@1289: sec.~\ref{sec:ecdev}. The master module knows the devices to choose from the
fp@1289: module parameters (see sec.~\ref{sec:mastermod}). If the init script is used
fp@1202: to start the master, the drivers and devices to use can be specified in the
fp@1289: sysconfig file (see sec.~\ref{sec:sysconfig}).
fp@369: 
fp@369: %------------------------------------------------------------------------------
fp@369: 
fp@1203: \section{EtherCAT Device Interface}
fp@369: \label{sec:ecdev}
fp@369: \index{Device interface}
fp@369: 
fp@369: An anticipation to the section about the master module
fp@1289: (sec.~\ref{sec:mastermod}) has to be made in order to understand the way, a
fp@1289: network device driver module can connect a device to a specific EtherCAT
fp@1289: master.
fp@369: 
fp@1202: The master module provides a ``device interface'' for network device drivers.
fp@1202: To use this interface, a network device driver module must include the header
fp@1202: \textit{devices/ecdev.h}\nomenclature{ecdev}{EtherCAT Device}, coming with the
fp@1202: EtherCAT master code. This header offers a function interface for EtherCAT
fp@1202: devices. All functions of the device interface are named with the prefix
fp@1202: \lstinline+ecdev+.
fp@1202: 
fp@1289: The documentation of the device interface can be found in the header file or
fp@1289: in the appropriate module of the interface documentation (see
fp@1289: sec.~\ref{sec:gendoc} for generation instructions).
fp@1202: 
fp@1296: % TODO general description of the device interface
fp@369: 
fp@369: %------------------------------------------------------------------------------
fp@369: 
fp@1085: \section{Patching Network Drivers}
fp@369: \label{sec:patching}
fp@369: \index{Network drivers}
fp@369: 
fp@1202: This section will describe, how to make a standard Ethernet driver
fp@1202: EtherCAT-capable. Unfortunately, there is no standard procedure to enable an
fp@1202: Ethernet driver for use with the EtherCAT master, but there are a few common
fp@1202: techniques.
fp@369: 
fp@369: \begin{enumerate}
fp@1202: 
fp@1202: \item A first simple rule is, that \lstinline+netif_*()+ calls must be avoided
fp@1202: for all EtherCAT devices. As mentioned before, EtherCAT devices have no
fp@1202: connection to the network stack, and therefore must not call its interface
fp@1202: functions.
fp@1202: 
fp@1202: \item Another important thing is, that EtherCAT devices should be operated
fp@1202: without interrupts. So any calls of registering interrupt handlers and enabling
fp@1202: interrupts at hardware level must be avoided, too.
fp@1202: 
fp@1202: \item The master does not use a new socket buffer for each send operation:
fp@1202: Instead there is a fix one allocated on master initialization. This socket
fp@1202: buffer is filled with an EtherCAT frame with every send operation and passed to
fp@1202: the \lstinline+hard_start_xmit()+ callback. For that it is necessary, that the
fp@1202: socket buffer is not be freed by the network driver as usual.
fp@1202: 
fp@369: \end{enumerate}
fp@369: 
fp@1202: An Ethernet driver usually handles several Ethernet devices, each described by
fp@1202: a \lstinline+net_device+ structure with a \lstinline+priv_data+ field to
fp@1202: attach driver-dependent data to the structure. To distinguish between normal
fp@1202: Ethernet devices and the ones used by EtherCAT masters, the private data
fp@1202: structure used by the driver could be extended by a pointer, that points to an
fp@1202: \lstinline+ec_device_t+ object returned by \lstinline+ecdev_offer()+ (see
fp@1289: sec.~\ref{sec:ecdev}) if the device is used by a master and otherwise is zero.
fp@1202: 
fp@1202: The RealTek RTL-8139 Fast Ethernet driver is a ``simple'' Ethernet driver and
fp@1202: can be taken as an example to patch new drivers. The interesting sections can
fp@1202: be found by searching the string ``ecdev" in the file
fp@1202: \textit{devices/8139too-2.6.24-ethercat.c}.
fp@369: 
fp@369: %------------------------------------------------------------------------------
fp@369: 
fp@1085: \chapter{State Machines}
fp@369: \label{sec:fsm}
fp@369: \index{FSM}
fp@369: 
fp@1085: Many parts of the EtherCAT master are implemented as \textit{finite state
fp@1085: machines} (FSMs\nomenclature{FSM}{Finite State Machine}). Though this leads
fp@1085: to a higher grade of complexity in some aspects, is opens many new
fp@1085: possibilities.
fp@369: 
fp@369: The below short code example exemplary shows how to read all slave
fp@369: states and moreover illustrates the restrictions of ``sequential''
fp@369: coding:
fp@369: 
fp@1085: \begin{lstlisting}[gobble=2,language=C,numbers=left]
fp@369:   ec_datagram_brd(datagram, 0x0130, 2); // prepare datagram
fp@369:   if (ec_master_simple_io(master, datagram)) return -1;
fp@369:   slave_states = EC_READ_U8(datagram->data); // process datagram
fp@369: \end{lstlisting}
fp@369: 
fp@1085: The \textit{ec\_master\_simple\_io()} function provides a simple interface for
fp@1085: synchronously sending a single datagram and receiving the result\footnote{For
fp@1085: all communication issues have been meanwhile sourced out into state machines,
fp@1085: the function is deprecated and stopped existing. Nevertheless it is adequate
fp@1085: for showing it's own restrictions.}. Internally, it queues the specified
fp@1085: datagram, invokes the \textit{ec\_master\_send\_datagrams()} function to send
fp@1085: a frame with the queued datagram and then waits actively for its reception.
fp@369: 
fp@1289: This sequential approach is very simple, reflecting in only three lines of
fp@1289: code. The disadvantage is, that the master is blocked for the time it waits
fp@1289: for datagram reception. There is no difficulty when only one instance is using
fp@1289: the master, but if more instances want to (synchronously\footnote{At this
fp@1289: time, synchronous master access will be adequate to show the advantages of an
fp@1289: FSM. The asynchronous approach will be discussed in sec.~\ref{sec:eoe}}) use
fp@1289: the master, it is inevitable to think about an alternative to the sequential
fp@1289: model.
fp@369: 
fp@369: Master access has to be sequentialized for more than one instance
fp@369: wanting to send and receive datagrams synchronously. With the present
fp@369: approach, this would result in having one phase of active waiting for
fp@369: each instance, which would be non-acceptable especially in realtime
fp@369: circumstances, because of the huge time overhead.
fp@369: 
fp@369: A possible solution is, that all instances would be executed
fp@369: sequentially to queue their datagrams, then give the control to the
fp@369: next instance instead of waiting for the datagram reception. Finally,
fp@369: bus IO is done by a higher instance, which means that all queued
fp@369: datagrams are sent and received. The next step is to execute all
fp@369: instances again, which then process their received datagrams and issue
fp@369: new ones.
fp@369: 
fp@369: This approach results in all instances having to retain their state,
fp@369: when giving the control back to the higher instance. It is quite
fp@369: obvious to use a \textit{finite state machine} model in this case.
fp@369: Section~\ref{sec:fsmtheory} will introduce some of the theory used,
fp@369: while the listings below show the basic approach by coding the example
fp@369: from above as a state machine:
fp@369: 
fp@1085: \begin{lstlisting}[gobble=2,language=C,numbers=left]
fp@369:   // state 1
fp@369:   ec_datagram_brd(datagram, 0x0130, 2); // prepare datagram
fp@369:   ec_master_queue(master, datagram); // queue datagram
fp@369:   next_state = state_2;
fp@369:   // state processing finished
fp@369: \end{lstlisting}
fp@369: 
fp@369: After all instances executed their current state and queued their
fp@369: datagrams, these are sent and received. Then the respective next
fp@369: states are executed:
fp@369: 
fp@1085: \begin{lstlisting}[gobble=2,language=C,numbers=left]
fp@369:   // state 2
fp@369:   if (datagram->state != EC_DGRAM_STATE_RECEIVED) {
fp@369:           next_state = state_error;
fp@369:           return; // state processing finished
fp@369:   }
fp@369:   slave_states = EC_READ_U8(datagram->data); // process datagram
fp@369:   // state processing finished.
fp@369: \end{lstlisting}
fp@369: 
fp@1289: See sec.~\ref{sec:statemodel} for an introduction to the state machine
fp@1289: programming concept used in the master code.
fp@369: 
fp@369: %------------------------------------------------------------------------------
fp@369: 
fp@1085: \section{State Machine Theory}
fp@369: \label{sec:fsmtheory}
fp@369: \index{FSM!Theory}
fp@369: 
fp@369: A finite state machine \cite{automata} is a model of behavior with
fp@369: inputs and outputs, where the outputs not only depend on the inputs,
fp@369: but the history of inputs. The mathematical definition of a finite
fp@369: state machine (or finite automaton) is a six-tuple $(\Sigma, \Gamma,
fp@369: S, s_0, \delta, \omega)$, with
fp@369: 
fp@369: \begin{itemize}
fp@369: \item the input alphabet $\Sigma$, with $\Sigma \neq
fp@369:   \emptyset$, containing all input symbols,
fp@369: \item the output alphabet $\Gamma$, with $\Gamma \neq
fp@369:   \emptyset$, containing all output symbols,
fp@369: \item the set of states $S$, with $S \neq \emptyset$,
fp@369: \item the set of initial states $s_0$ with $s_0 \subseteq S, s_0 \neq
fp@369:   \emptyset$
fp@369: \item the transition function $\delta: S \times \Sigma \rightarrow S
fp@369:   \times \Gamma$
fp@369: \item the output function $\omega$.
fp@369: \end{itemize}
fp@369: 
fp@369: The state transition function $\delta$ is often specified by a
fp@369: \textit{state transition table}, or by a \textit{state transition
fp@369:   diagram}. The transition table offers a matrix view of the state
fp@369: machine behavior (see table~\ref{tab:statetrans}). The matrix rows
fp@369: correspond to the states ($S = \{s_0, s_1, s_2\}$) and the columns
fp@369: correspond to the input symbols ($\Gamma = \{a, b, \varepsilon\}$).
fp@369: The table contents in a certain row $i$ and column $j$ then represent
fp@369: the next state (and possibly the output) for the case, that a certain
fp@369: input symbol $\sigma_j$ is read in the state $s_i$.
fp@369: 
fp@369: \begin{table}[htbp]
fp@369:   \caption{A typical state transition table}
fp@369:   \label{tab:statetrans}
fp@369:   \vspace{2mm}
fp@369:   \centering
fp@369:   \begin{tabular}{l|ccc}
fp@369:     & $a$ & $b$ & $\varepsilon$\\ \hline
fp@369:     $s_0$ & $s_1$ & $s_1$ & $s_2$\\
fp@369:     $s_1$ & $s_2$ & $s_1$ & $s_0$\\
fp@369:     $s_2$ & $s_0$ & $s_0$ & $s_0$\\ \hline
fp@369:   \end{tabular}
fp@369: \end{table}
fp@369: 
fp@369: The state diagram for the same example looks like the one in
fp@369: figure~\ref{fig:statetrans}. The states are represented as circles or
fp@369: ellipses and the transitions are drawn as arrows between them. Close
fp@369: to a transition arrow can be the condition that must be fulfilled to
fp@369: allow the transition. The initial state is marked by a filled black
fp@369: circle with an arrow pointing to the respective state.
fp@369: 
fp@369: \begin{figure}[htbp]
fp@369:   \centering
fp@369:   \includegraphics[width=.5\textwidth]{images/statetrans}
fp@369:   \caption{A typical state transition diagram}
fp@369:   \label{fig:statetrans}
fp@369: \end{figure}
fp@369: 
fp@369: \paragraph{Deterministic and non-deterministic state machines}
fp@369: 
fp@369: A state machine can be deterministic, meaning that for one state and
fp@369: input, there is one (and only one) following state. In this case, the
fp@369: state machine has exactly one starting state. Non-deterministic state
fp@369: machines can have more than one transitions for a single state-input
fp@369: combination. There is a set of starting states in the latter case.
fp@369: 
fp@369: \paragraph{Moore and Mealy machines}
fp@369: 
fp@369: There is a distinction between so-called \textit{Moore machines}, and
fp@369: \textit{Mealy machines}. Mathematically spoken, the distinction lies
fp@369: in the output function $\omega$: If it only depends on the current
fp@369: state ($\omega: S \rightarrow \Gamma$), the machine corresponds to the
fp@369: ``Moore Model''. Otherwise, if $\omega$ is a function of a state and
fp@369: the input alphabet ($\omega: S \times \Sigma \rightarrow \Gamma$) the
fp@369: state machine corresponds to the ``Mealy model''. Mealy machines are
fp@369: the more practical solution in most cases, because their design allows
fp@369: machines with a minimum number of states. In practice, a mixture of
fp@369: both models is often used.
fp@369: 
fp@369: \paragraph{Misunderstandings about state machines}
fp@369: 
fp@1085: There is a phenomenon called ``state explosion'', that is often taken as a
fp@1085: counter-argument against general use of state machines in complex environments.
fp@1085: It has to be mentioned, that this point is misleading~\cite{fsmmis}. State
fp@1085: explosions happen usually as a result of a bad state machine design: Common
fp@1085: mistakes are storing the present values of all inputs in a state, or not
fp@1085: dividing a complex state machine into simpler sub state machines. The EtherCAT
fp@1085: master uses several state machines, that are executed hierarchically and so
fp@1085: serve as sub state machines. These are also described below.
fp@1085: 
fp@1085: %------------------------------------------------------------------------------
fp@1085: 
fp@1085: \section{The Master's State Model}
fp@369: \label{sec:statemodel}
fp@369: 
fp@369: This section will introduce the techniques used in the master to
fp@369: implement state machines.
fp@369: 
fp@369: \paragraph{State Machine Programming}
fp@369: 
fp@369: There are certain ways to implement a state machine in \textit{C}
fp@369: code. An obvious way is to implement the different states and actions
fp@369: by one big case differentiation:
fp@369: 
fp@1085: \begin{lstlisting}[gobble=2,language=C,numbers=left]
fp@369:   enum {STATE_1, STATE_2, STATE_3};
fp@369:   int state = STATE_1;
fp@369: 
fp@369:   void state_machine_run(void *priv_data) {
fp@369:           switch (state) {
fp@369:                   case STATE_1:
fp@369:                           action_1();
fp@369:                           state = STATE_2;
fp@369:                           break;
fp@369:                   case STATE_2:
fp@369:                           action_2()
fp@369:                           if (some_condition) state = STATE_1;
fp@369:                           else state = STATE_3;
fp@369:                           break;
fp@369:                   case STATE_3:
fp@369:                           action_3();
fp@369:                           state = STATE_1;
fp@369:                           break;
fp@369:           }
fp@369:   }
fp@369: \end{lstlisting}
fp@369: 
fp@369: For small state machines, this is an option. The disadvantage is, that
fp@369: with an increasing number of states the code soon gets complex and an
fp@369: additional case differentiation is executed each run. Besides, lots of
fp@369: indentation is wasted.
fp@369: 
fp@369: The method used in the master is to implement every state in an own
fp@369: function and to store the current state function with a function
fp@369: pointer:
fp@369: 
fp@1085: \begin{lstlisting}[gobble=2,language=C,numbers=left]
fp@369:   void (*state)(void *) = state1;
fp@369: 
fp@369:   void state_machine_run(void *priv_data) {
fp@369:           state(priv_data);
fp@369:   }
fp@369: 
fp@369:   void state1(void *priv_data) {
fp@369:           action_1();
fp@369:           state = state2;
fp@369:   }
fp@369: 
fp@369:   void state2(void *priv_data) {
fp@369:           action_2();
fp@369:           if (some_condition) state = state1;
fp@369:           else state = state2;
fp@369:   }
fp@369: 
fp@369:   void state3(void *priv_data) {
fp@369:           action_3();
fp@369:           state = state1;
fp@369:   }
fp@369: \end{lstlisting}
fp@369: 
fp@1085: In the master code, state pointers of all state machines\footnote{All except
fp@1085: for the EoE state machine, because multiple EoE slaves have to be handled in
fp@1085: parallel. For this reason each EoE handler object has its own state pointer.}
fp@1202: are gathered in a single object of the \lstinline+ec_fsm_master_t+ class. This
fp@1202: is advantageous, because there is always one instance of every state machine
fp@1085: available and can be started on demand.
fp@369: 
fp@369: \paragraph{Mealy and Moore}
fp@369: 
fp@1202: If a closer look is taken to the above listing, it can be seen that the
fp@1202: actions executed (the ``outputs'' of the state machine) only depend on the
fp@1202: current state. This accords to the ``Moore'' model introduced in
fp@1289: sec.~\ref{sec:fsmtheory}. As mentioned, the ``Mealy'' model offers a higher
fp@1202: flexibility, which can be seen in the listing below:
fp@369: 
fp@1085: \begin{lstlisting}[gobble=2,language=C,numbers=left]
fp@369:   void state7(void *priv_data) {
fp@369:           if (some_condition) {
fp@369:                   action_7a();
fp@369:                   state = state1;
fp@369:           }
fp@369:           else {
fp@369:                   action_7b();
fp@369:                   state = state8;
fp@369:           }
fp@369:   }
fp@369: \end{lstlisting}
fp@369: 
fp@369: \begin{description}
fp@1202: 
fp@1202: \item[\linenum{3} + \linenum{7}] The state function executes the actions
fp@1202: depending on the state transition, that is about to be done.
fp@1202: 
fp@369: \end{description}
fp@369: 
fp@369: The most flexible alternative is to execute certain actions depending
fp@369: on the state, followed by some actions dependent on the state
fp@369: transition:
fp@369: 
fp@1085: \begin{lstlisting}[gobble=2,language=C,numbers=left]
fp@369:   void state9(void *priv_data) {
fp@369:           action_9();
fp@369:           if (some_condition) {
fp@369:                   action_9a();
fp@369:                   state = state7;
fp@369:           }
fp@369:           else {
fp@369:                   action_9b();
fp@369:                   state = state10;
fp@369:           }
fp@369:   }
fp@369: \end{lstlisting}
fp@369: 
fp@1202: This model is often used in the master. It combines the best aspects of both
fp@1202: approaches.
fp@369: 
fp@369: \paragraph{Using Sub State Machines}
fp@369: 
fp@1202: To avoid having too much states, certain functions of the EtherCAT master
fp@1202: state machine have been sourced out into sub state machines.  This helps to
fp@1085: encapsulate the related workflows and moreover avoids the ``state explosion''
fp@1289: phenomenon described in sec.~\ref{sec:fsmtheory}. If the master would instead
fp@1289: use one big state machine, the number of states would be a multiple of the
fp@1289: actual number. This would increase the level of complexity to a non-manageable
fp@1289: grade.
fp@369: 
fp@369: \paragraph{Executing Sub State Machines}
fp@369: 
fp@369: If a state machine starts to execute a sub state machine, it usually
fp@369: remains in one state until the sub state machine terminates. This is
fp@369: usually done like in the listing below, which is taken out of the
fp@369: slave configuration state machine code:
fp@369: 
fp@1085: \begin{lstlisting}[gobble=2,language=C,numbers=left]
fp@813:   void ec_fsm_slaveconf_safeop(ec_fsm_t *fsm)
fp@369:   {
fp@369:           fsm->change_state(fsm); // execute state change
fp@369:                                   // sub state machine
fp@369: 
fp@369:           if (fsm->change_state == ec_fsm_error) {
fp@369:                   fsm->slave_state = ec_fsm_end;
fp@369:                   return;
fp@369:           }
fp@369: 
fp@369:           if (fsm->change_state != ec_fsm_end) return;
fp@369: 
fp@369:           // continue state processing
fp@369:           ...
fp@369: \end{lstlisting}
fp@369: 
fp@369: \begin{description}
fp@1202: 
fp@1202: \item[\linenum{3}] \lstinline+change_state+ is the state pointer of the state
fp@1202: change state machine. The state function, the pointer points on, is
fp@1202: executed\ldots
fp@1202: 
fp@1202: \item[\linenum{6}] \ldots either until the state machine terminates with the
fp@1202: error state \ldots
fp@1202: 
fp@1202: \item[\linenum{11}] \ldots or until the state machine terminates in the end
fp@1202: state. Until then, the ``higher'' state machine remains in the current state
fp@1202: and executes the sub state machine again in the next cycle.
fp@1202: 
fp@369: \end{description}
fp@369: 
fp@369: \paragraph{State Machine Descriptions}
fp@369: 
fp@1202: The below sections describe every state machine used in the EtherCAT master.
fp@1202: The textual descriptions of the state machines contain references to the
fp@1202: transitions in the corresponding state transition diagrams, that are marked
fp@1202: with an arrow followed by the name of the successive state. Transitions caused
fp@1306: by trivial error cases (i.\,e.\ no response from slave) are not described
fp@1202: explicitly. These transitions are drawn as dashed arrows in the diagrams.
fp@1202: 
fp@1202: %------------------------------------------------------------------------------
fp@1202: 
fp@1202: \section{The Master State Machine}
fp@1202: \label{sec:fsm-master}
fp@1202: \index{FSM!Master}
fp@1202: 
fp@1202: The master state machine is executed in the context of the master thread.
fp@1202: Figure~\ref{fig:fsm-master} shows its transition diagram. Its purposes are:
fp@369: 
fp@369: \begin{figure}[htbp]
fp@369:   \centering
fp@1202:   \includegraphics[width=\textwidth]{graphs/fsm_master}
fp@1202:   \caption{Transition diagram of the master state machine}
fp@1202:   \label{fig:fsm-master}
fp@369: \end{figure}
fp@369: 
fp@369: \begin{description}
fp@1202: 
fp@1202: \item[Bus monitoring] The bus topology is monitored. If it changes, the bus is
fp@1202: (re-)scanned.
fp@1202: 
fp@1202: \item[Slave configuration] The application-layer states of the slaves are
fp@1202: monitored. If a slave is not in the state it supposed to be, the slave is
fp@1202: (re-)configured.
fp@1202: 
fp@1202: \item[Request handling] Requests (either originating from the application or
fp@1203: from external sources) are handled. A request is a job that the master shall
fp@1203: process asynchronously, for example an SII access, Sdo access, or similar.
fp@369: 
fp@369: \end{description}
fp@369: 
fp@369: %------------------------------------------------------------------------------
fp@369: 
fp@1085: \section{The Slave Scan State Machine}
fp@369: \label{sec:fsm-scan}
fp@369: \index{FSM!Slave Scan}
fp@369: 
fp@369: The slave scan state machine, which can be seen in
fp@1202: figure~\ref{fig:fsm-slavescan}, leads through the process of reading desired
fp@1202: slave information.
fp@369: 
fp@369: \begin{figure}[htbp]
fp@369:   \centering
fp@1202:   \includegraphics[height=.8\textheight]{graphs/fsm_slave_scan}
fp@369:   \caption{Transition diagram of the slave scan state machine}
fp@369:   \label{fig:fsm-slavescan}
fp@369: \end{figure}
fp@369: 
fp@1202: The scan process includes the following steps:
fp@1202: 
fp@369: \begin{description}
fp@1202: 
fp@1202: \item[Node Address] The node address is set for the slave, so that it can be
fp@1202: node-addressed for all following operations.
fp@1202: 
fp@1202: \item[AL State] The initial application-layer state is read.
fp@1202: 
fp@1202: \item[Base Information] Base information (like the number of supported FMMUs)
fp@1202: is read from the lower physical memory.
fp@1202: 
fp@1202: \item[Data Link] Information about the physical ports is read.
fp@1202: 
fp@1202: \item[SII Size] The size of the SII contents is determined to allocate SII
fp@1202: image memory.
fp@1202: 
fp@1202: \item[SII Data] The SII contents are read into the master's image.
fp@1202: 
fp@1202: \item[PREOP] If the slave supports CoE, it is set to PREOP state using the
fp@1289: State change FSM (see sec.~\ref{sec:fsm-change}) to enable mailbox
fp@1202: communication and read the Pdo configuration via CoE.
fp@1202: 
fp@1203: \item[Pdos] The Pdos are read via CoE (if supported) using the Pdo Reading FSM
fp@1289: (see sec.~\ref{sec:fsm-pdo}). If this is successful, the Pdo information from
fp@1289: the SII (if any) is overwritten.
fp@369: 
fp@369: \end{description}
fp@369: 
fp@369: %------------------------------------------------------------------------------
fp@369: 
fp@1085: \section{The Slave Configuration State Machine}
fp@369: \label{sec:fsm-conf}
fp@369: \index{FSM!Slave Configuration}
fp@369: 
fp@369: The slave configuration state machine, which can be seen in
fp@1202: figure~\ref{fig:fsm-slaveconf}, leads through the process of configuring a
fp@1202: slave and bringing it to a certain application-layer state.
fp@369: 
fp@369: \begin{figure}[htbp]
fp@369:   \centering
fp@1202:   \includegraphics[height=.9\textheight]{graphs/fsm_slave_conf}
fp@369:   \caption{Transition diagram of the slave configuration state
fp@369:     machine}
fp@369:   \label{fig:fsm-slaveconf}
fp@369: \end{figure}
fp@369: 
fp@369: \begin{description}
fp@1202: 
fp@1202: \item[INIT] The state change FSM is used to bring the slave to the INIT state.
fp@1202: 
fp@1202: \item[FMMU Clearing] To avoid that the slave reacts on any process data, the
fp@1202: FMMU configuration are cleared. If the slave does not support FMMUs, this
fp@1202: state is skipped. If INIT is the requested state, the state machine is
fp@1202: finished.
fp@1202: 
fp@1202: \item[Mailbox Sync Manager Configuration] If the slaves support mailbox
fp@1202: communication, the mailbox sync managers are configured. Otherwise this state
fp@1202: is skipped.
fp@1202: 
fp@1202: \item[PREOP] The state change FSM is used to bring the slave to PREOP state.
fp@1202: If this is the requested state, the state machine is finished.
fp@1202: 
fp@1204: \item[Sdo Configuration] If there is a slave configuration attached (see
fp@1289: sec.~\ref{sec:masterconfig}), and there are any Sdo configurations are
fp@1202: provided by the application, these are sent to the slave.
fp@1202: 
fp@1202: \item[Pdo Configuration] The Pdo configuration state machine is executed to
fp@1202: apply all necessary Pdo configurations.
fp@1202: 
fp@1202: \item[Pdo Sync Manager Configuration] If any Pdo sync managers exist, they are
fp@1202: configured.
fp@1202: 
fp@1202: \item[FMMU Configuration] If there are FMMUs configurations supplied by the
fp@1306: application (i.\,e.\ if the application registered Pdo entries), they are
fp@1202: applied. 
fp@1202: 
fp@1202: \item[SAFEOP] The state change FSM is used to bring the slave to SAFEOP state.
fp@1202: If this is the requested state, the state machine is finished.
fp@1202: 
fp@1202: \item[OP] The state change FSM is used to bring the slave to OP state.
fp@1202: If this is the requested state, the state machine is finished.
fp@369: 
fp@369: \end{description}
fp@369: 
fp@369: %------------------------------------------------------------------------------
fp@369: 
fp@1085: \section{The State Change State Machine}
fp@369: \label{sec:fsm-change}
fp@369: \index{FSM!State Change}
fp@369: 
fp@369: The state change state machine, which can be seen in
fp@1202: figure~\ref{fig:fsm-change}, leads through the process of changing a slave's
fp@1202: application-layer state. This implements the states and transitions described
fp@1289: in \cite[sec.~6.4.1]{alspec}.
fp@369: 
fp@369: \begin{figure}[htbp]
fp@369:   \centering
fp@1203:   \includegraphics[width=.6\textwidth]{graphs/fsm_change}
fp@1202:   \caption{Transition Diagram of the State Change State Machine}
fp@369:   \label{fig:fsm-change}
fp@369: \end{figure}
fp@369: 
fp@369: \begin{description}
fp@1203: 
fp@1203: \item[Start] The new application-layer state is requested via the ``AL Control
fp@1306: Request'' register (see~\cite[sec. 5.3.1]{alspec}).
fp@1203: 
fp@1203: \item[Check for Response] Some slave need some time to respond to an AL state
fp@1203: change command, and do not respond for some time. For this case, the command
fp@1203: is issued again, until it is acknowledged.
fp@1203: 
fp@1203: \item[Check AL Status] If the AL State change datagram was acknowledged, the
fp@1289: ``AL Control Response'' register (see~\cite[sec. 5.3.2]{alspec}) must be read
fp@1289: out until the slave changes the AL state.
fp@1203: 
fp@1203: \item[AL Status Code] If the slave refused the state change command, the
fp@1203: reason can be read from the ``AL Status Code'' field in the ``AL State
fp@1289: Changed'' registers (see~\cite[sec. 5.3.3]{alspec}).
fp@1203: 
fp@1203: \item[Acknowledge State] If the state change was not successful, the master
fp@1203: has to acknowledge the old state by writing to the ``AL Control request''
fp@1203: register again.
fp@1203: 
fp@1203: \item[Check Acknowledge] After sending the acknowledge command, it has to read
fp@1203: out the ``AL Control Response'' register again.
fp@369: 
fp@369: \end{description}
fp@369: 
fp@1203: The ``start\_ack'' state is a shortcut in the state machine for the case, that
fp@1203: the master wants to acknowledge a spontaneous AL state change, that was not
fp@1203: requested.
fp@1203: 
fp@369: %------------------------------------------------------------------------------
fp@369: 
fp@1085: \section{The SII State Machine}
fp@369: \label{sec:fsm-sii}
fp@369: \index{FSM!SII}
fp@369: 
fp@369: The SII\index{SII} state machine (shown in figure~\ref{fig:fsm-sii})
fp@1289: implements the process of reading or writing SII data via the Slave
fp@1289: Information Interface described in \cite[sec.~6.4]{dlspec}.
fp@369: 
fp@369: \begin{figure}[htbp]
fp@369:   \centering
fp@1203:   \includegraphics[width=.5\textwidth]{graphs/fsm_sii}
fp@1202:   \caption{Transition Diagram of the SII State Machine}
fp@369:   \label{fig:fsm-sii}
fp@369: \end{figure}
fp@369: 
fp@1203: This is how the reading part of the state machine works:
fp@1202: 
fp@369: \begin{description}
fp@1203: 
fp@1203: \item[Start Reading] The read request and the requested word address are
fp@1203: written to the SII attribute.
fp@1203: 
fp@1203: \item[Check Read Command] If the SII read request command has been
fp@1203: acknowledged, a timer is started. A datagram is issued, that reads out the SII
fp@1203: attribute for state and data.
fp@1203: 
fp@1203: \item[Fetch Data] If the read operation is still busy (the SII is usually
fp@1203: implemented as an E$^2$PROM), the state is read again. Otherwise the data are
fp@1203: copied from the datagram.
fp@1203: 
fp@369: \end{description}
fp@369: 
fp@1203: The writing part works nearly similar:
fp@369: 
fp@369: \begin{description}
fp@1203: 
fp@1203: \item[Start Writing] A write request, the target address and the data word are
fp@1203: written to the SII attribute.
fp@1203: 
fp@1203: \item[Check Write Command] If the SII write request command has been
fp@1203: acknowledged, a timer is started. A datagram is issued, that reads out the SII
fp@1203: attribute for the state of the write operation.
fp@1203: 
fp@1203: \item[Wait while Busy] If the write operation is still busy (determined by a
fp@1203: minimum wait time and the state of the busy flag), the state machine remains in
fp@1203: this state to avoid that another write operation is issued too early.
fp@1203: 
fp@369: \end{description}
fp@369: 
fp@369: %------------------------------------------------------------------------------
fp@369: 
fp@1203: \section{The Pdo State Machines}
fp@1203: \label{sec:fsm-pdo}
fp@1203: \index{FSM!Pdo}
fp@1203: 
fp@1203: The Pdo state machines are a set of state machines that read or write the Pdo
fp@1203: assignment and the Pdo mapping via the ``CoE Communication Area'' described in
fp@1289: \cite[sec. 5.6.7.4]{alspec}. For the object access, the CANopen-over-EtherCAT
fp@1289: access primitives are used (see sec.~\ref{sec:coe}), so the slave must support
fp@1289: the CoE mailbox protocol.
fp@1203: 
fp@1203: \paragraph{Pdo Reading FSM} This state machine (fig.~\ref{fig:fsm-pdo-read})
fp@1203: has the purpose to read the complete Pdo configuration of a slave. It reads
fp@1203: the Pdo assignment for each Sync Manager and uses the Pdo Entry Reading FSM
fp@1204: (fig.~\ref{fig:fsm-pdo-entry-read}) to read the mapping for each assigned Pdo.
fp@1203: 
fp@1203: \begin{figure}[htbp]
fp@1203:   \centering
fp@1203:   \includegraphics[width=.4\textwidth]{graphs/fsm_pdo_read}
fp@1203:   \caption{Transition Diagram of the Pdo Reading State Machine}
fp@1203:   \label{fig:fsm-pdo-read}
fp@1203: \end{figure}
fp@1203: 
fp@1203: Basically it reads the every Sync manager's Pdo assignment Sdo's
fp@1203: (\lstinline+0x1C1x+) number of elements to determine the number of assigned
fp@1203: Pdos for this sync manager and then reads out the subindices of the Sdo to get
fp@1203: the assigned Pdo's indices. When a Pdo index is read, the Pdo Entry Reading
fp@1203: FSM is executed to read the Pdo's mapped Pdo entries.
fp@1203: 
fp@1203: \paragraph{Pdo Entry Reading FSM} This state machine
fp@1204: (fig.~\ref{fig:fsm-pdo-entry-read}) reads the Pdo mapping (the Pdo entries) of
fp@1293: a Pdo. It reads the respective mapping Sdo (\lstinline+0x1600+ --
fp@1293: \lstinline+0x17ff+, or \lstinline+0x1a00+ -- \lstinline+0x1bff+) for the given
fp@1203: Pdo by reading first the subindex zero (number of elements) to determine the
fp@1203: number of mapped Pdo entries. After that, each subindex is read to get the
fp@1203: mapped Pdo entry index, subindex and bit size.
fp@1203: 
fp@1203: \begin{figure}[htbp]
fp@1203:   \centering
fp@1203:   \includegraphics[width=.4\textwidth]{graphs/fsm_pdo_entry_read}
fp@1203:   \caption{Transition Diagram of the Pdo Entry Reading State Machine}
fp@1204:   \label{fig:fsm-pdo-entry-read}
fp@1203: \end{figure}
fp@1203: 
fp@1203: \begin{figure}[htbp]
fp@1203:   \centering
fp@1203:   \includegraphics[width=.9\textwidth]{graphs/fsm_pdo_conf}
fp@1203:   \caption{Transition Diagram of the Pdo Configuration State Machine}
fp@1204:   \label{fig:fsm-pdo-conf}
fp@1203: \end{figure}
fp@1203: 
fp@1203: \begin{figure}[htbp]
fp@1203:   \centering
fp@1203:   \includegraphics[width=.4\textwidth]{graphs/fsm_pdo_entry_conf}
fp@1203:   \caption{Transition Diagram of the Pdo Entry Configuration State Machine}
fp@1204:   \label{fig:fsm-pdo-entry-conf}
fp@1203: \end{figure}
fp@1203: 
fp@1203: %------------------------------------------------------------------------------
fp@1203: 
fp@1085: \chapter{Mailbox Protocol Implementations}
fp@369: \index{Mailbox}
fp@369: 
fp@369: The EtherCAT master implements the EoE and the CoE mailbox
fp@369: protocols. See the below section for details.
fp@369: 
fp@369: %------------------------------------------------------------------------------
fp@369: 
fp@1085: \section{Ethernet-over-EtherCAT (EoE)}
fp@1269: \label{sec:eoe}
fp@369: \index{EoE}
fp@369: 
fp@1306: The EtherCAT master implements the
fp@1306: Ethernet-over-EtherCAT\nomenclature{EoE}{Ethernet-over-EtherCAT, Mailbox
fp@1306: Protocol} mailbox protocol~\cite[sec.~5.7]{alspec} to enable the tunneling of
fp@1306: Ethernet frames to special slaves, that can either have physical Ethernet
fp@1306: ports to forward the frames to, or have an own IP stack to receive the frames.
fp@369: 
fp@369: \paragraph{Virtual Network Interfaces}
fp@369: 
fp@1202: The master creates a virtual EoE network interface for every EoE-capable
fp@1202: slave. These interfaces are called either
fp@1202: 
fp@1202: \begin{description}
fp@1202: 
fp@1293: \item[eoeXsY] for a slave without an alias address (see
fp@1293: sec.~\ref{sec:ethercat-alias}), where X is the master index and Y is the
fp@1293: slave's ring position, or
fp@1202: 
fp@1202: \item[eoeXaY] for a slave with a non-zero alias address, where X is the master
fp@1202: index and Y is the decimal alias address.
fp@1202: 
fp@1202: \end{description}
fp@1202: 
fp@1202: Frames sent to these interfaces are forwarded to the associated slaves by the
fp@1202: master. Frames, that are received by the slaves, are fetched by the master and
fp@1202: forwarded to the virtual interfaces.
fp@369: 
fp@369: This bears the following advantages:
fp@369: 
fp@369: \begin{itemize}
fp@1202: 
fp@369: \item Flexibility: The user can decide, how the EoE-capable slaves are
fp@1202: interconnected with the rest of the world.
fp@1202: 
fp@1202: \item Standard tools can be used to monitor the EoE activity and to configure
fp@1202: the EoE interfaces.
fp@1202: 
fp@1202: \item The Linux kernel's layer-2-bridging implementation (according to the
fp@1202: IEEE 802.1D MAC Bridging standard) can be used natively to bridge Ethernet
fp@1202: traffic between EoE-capable slaves.
fp@1202: 
fp@1202: \item The Linux kernel's network stack can be used to route packets between
fp@1202: EoE-capable slaves and to track security issues, just like having physical
fp@1202: network interfaces.
fp@1202: 
fp@369: \end{itemize}
fp@369: 
fp@369: \paragraph{EoE Handlers}
fp@369: 
fp@1202: The virtual EoE interfaces and the related functionality is encapsulated in
fp@1202: the \lstinline+ec_eoe_t+ class. An object of this class is called ``EoE
fp@1202: handler''. For example the master does not create the network interfaces
fp@1202: directly: This is done inside the constructor of an EoE handler. An EoE
fp@1202: handler additionally contains a frame queue. Each time, the kernel passes a
fp@1202: new socket buffer for sending via the interface's
fp@1202: \lstinline+hard_start_xmit()+ callback, the socket buffer is queued for
fp@1202: transmission by the EoE state machine (see below). If the queue gets filled
fp@1202: up, the passing of new socket buffers is suspended with a call to
fp@1202: \lstinline+netif_stop_queue()+.
fp@1202: 
fp@1202: \paragraph{Creation of EoE Handlers}
fp@1202: 
fp@1289: During bus scanning (see sec.~\ref{sec:fsm-scan}), the master determines the
fp@1289: supported mailbox protocols foe each slave. This is done by examining the
fp@1202: ``Supported Mailbox Protocols'' mask field at word address 0x001C of the
fp@1202: SII\index{SII}. If bit 1 is set, the slave supports the EoE protocol. In this
fp@1202: case, an EoE handler is created for that slave.
fp@369: 
fp@369: \paragraph{EoE State Machine}
fp@369: \index{FSM!EoE}
fp@369: 
fp@1202: Every EoE handler owns an EoE state machine, that is used to send frames to
fp@1202: the corresponding slave and receive frames from the it via the EoE
fp@369: communication primitives. This state machine is showed in
fp@369: figure~\ref{fig:fsm-eoe}.
fp@369: 
fp@369: \begin{figure}[htbp]
fp@369:   \centering
fp@1202:   \includegraphics[width=.7\textwidth]{images/fsm-eoe} % FIXME
fp@1202:   \caption{Transition Diagram of the EoE State Machine}
fp@369:   \label{fig:fsm-eoe}
fp@369: \end{figure}
fp@369: 
fp@1202: % FIXME
fp@1202: 
fp@369: \begin{description}
fp@369: \item[RX\_START] The beginning state of the EoE state machine. A
fp@369:   mailbox check datagram is sent, to query the slave's mailbox for new
fp@379:   frames. $\rightarrow$~RX\_CHECK
fp@369: 
fp@369: \item[RX\_CHECK] The mailbox check datagram is received. If the
fp@369:   slave's mailbox did not contain data, a transmit cycle is started.
fp@379:   $\rightarrow$~TX\_START
fp@369: 
fp@369:   If there are new data in the mailbox, a datagram is sent to fetch
fp@379:   the new data. $\rightarrow$~RX\_FETCH
fp@369: 
fp@369: \item[RX\_FETCH] The fetch datagram is received. If the mailbox data
fp@369:   do not contain a ``EoE Fragment request'' command, the data are
fp@369:   dropped and a transmit sequence is started.
fp@379:   $\rightarrow$~TX\_START
fp@369: 
fp@369:   If the received Ethernet frame fragment is the first fragment, a new
fp@369:   socket buffer is allocated. In either case, the data are copied into
fp@369:   the correct position of the socket buffer.
fp@369: 
fp@369:   If the fragment is the last fragment, the socket buffer is forwarded
fp@369:   to the network stack and a transmit sequence is started.
fp@379:   $\rightarrow$~TX\_START
fp@369: 
fp@369:   Otherwise, a new receive sequence is started to fetch the next
fp@379:   fragment. $\rightarrow$~RX\_\-START
fp@369: 
fp@369: \item[TX\_START] The beginning state of a transmit sequence. It is
fp@1085:   checked, if the transmission queue contains a frame to send. If not,
fp@379:   a receive sequence is started. $\rightarrow$~RX\_START
fp@369: 
fp@369:   If there is a frame to send, it is dequeued. If the queue was
fp@369:   inactive before (because it was full), the queue is woken up with a
fp@369:   call to \textit{netif\_wake\_queue()}. The first fragment of the
fp@379:   frame is sent. $\rightarrow$~TX\_SENT
fp@369: 
fp@369: \item[TX\_SENT] It is checked, if the first fragment was sent
fp@369:   successfully. If the current frame consists of further fragments,
fp@379:   the next one is sent. $\rightarrow$~TX\_SENT
fp@369: 
fp@369:   If the last fragment was sent, a new receive sequence is started.
fp@379:   $\rightarrow$~RX\_START
fp@369: \end{description}
fp@369: 
fp@369: \paragraph{EoE Processing}
fp@369: 
fp@1202: To execute the EoE state machine of every active EoE handler, there must be a
fp@1202: cyclic process. The easiest solution would be to execute the EoE state
fp@1202: machines synchronously with the master state machine (see
fp@1289: sec.~\ref{sec:fsm-master}). This approach has the following disadvantage:
fp@1202: 
fp@1202: Only one EoE fragment could be sent or received every few cycles. This
fp@1085: causes the data rate to be very low, because the EoE state machines are not
fp@1085: executed in the time between the application cycles. Moreover, the data rate
fp@1085: would be dependent on the period of the application task.
fp@1085: 
fp@1202: To overcome this problem, an own cyclic process is needed to asynchronously
fp@1202: execute the EoE state machines. For that, the master owns a kernel timer, that
fp@1202: is executed each timer interrupt. This guarantees a constant bandwidth, but
fp@1202: poses the new problem of concurrent access to the master. The locking
fp@1289: mechanisms needed for this are introduced in sec.~\ref{sec:concurr}.
fp@369: 
fp@369: \paragraph{Automatic Configuration}
fp@369: 
fp@1202: By default, slaves are left in PREOP state, if no configuration is applied. If
fp@1202: an EoE interface link is set to ``up'', the requested slave's
fp@1202: application-layer state is automatically set to OP.
fp@369: 
fp@369: %------------------------------------------------------------------------------
fp@369: 
fp@1085: \section{CANopen-over-EtherCAT (CoE)}
fp@1269: \label{sec:coe}
fp@369: \index{CoE}
fp@369: 
fp@1306: The CANopen-over-EtherCAT\nomenclature{CoE}{CANopen-over-EtherCAT, Mailbox
fp@1306: Protocol} protocol~\cite[sec.~5.6]{alspec} is used to configure slaves and
fp@1306: exchange data objects on application level.
fp@1202: 
fp@1297: % TODO
fp@1203: %
fp@1203: % Download / Upload
fp@1203: % Expedited / Normal
fp@1204: % Segmenting
fp@1203: % Sdo Info Services
fp@1203: %
fp@1203: 
fp@1203: \ldots
fp@369: 
fp@814: \paragraph{Sdo Download State Machine}
fp@814: 
fp@1289: The best time to apply Sdo configurations is during the slave's PREOP state,
fp@1289: because mailbox communication is already possible and slave's application will
fp@1289: start with updating input data in the succeeding SAFEOP state. Therefore the
fp@1289: Sdo configuration has to be part of the slave configuration state machine (see
fp@1289: sec.~\ref{sec:fsm-conf}): It is implemented via an Sdo download state machine,
fp@1289: that is executed just before entering the slave's SAFEOP state. In this way,
fp@1289: it is guaranteed that the Sdo configurations are applied each time, the slave
fp@1289: is reconfigured.
fp@369: 
fp@814: The transition diagram of the Sdo Download state machine can be seen
fp@369: in figure~\ref{fig:fsm-coedown}.
fp@369: 
fp@369: \begin{figure}[htbp]
fp@369:   \centering
fp@1202:   \includegraphics[width=.9\textwidth]{images/fsm-coedown} % FIXME
fp@369:   \caption{Transition diagram of the CoE download state machine}
fp@369:   \label{fig:fsm-coedown}
fp@369: \end{figure}
fp@369: 
fp@1202: % FIXME
fp@1202: 
fp@369: \begin{description}
fp@369: \item[START] The beginning state of the CoE download state
fp@814:   machine. The ``Sdo Download Normal Request'' mailbox command is
fp@379:   sent. $\rightarrow$~REQUEST
fp@369: 
fp@369: \item[REQUEST] It is checked, if the CoE download request has been
fp@369:   received by the slave. After that, a mailbox check command is issued
fp@379:   and a timer is started. $\rightarrow$~CHECK
fp@369: 
fp@369: \item[CHECK] If no mailbox data is available, the timer is checked.
fp@369:   \begin{itemize}
fp@814:   \item If it timed out, the Sdo download is aborted.
fp@379:     $\rightarrow$~ERROR
fp@369:   \item Otherwise, the mailbox is queried again.
fp@379:     $\rightarrow$~CHECK
fp@369:   \end{itemize}
fp@369: 
fp@369:   If the mailbox contains new data, the response is fetched.
fp@379:   $\rightarrow$~RESPONSE
fp@369: 
fp@369: \item[RESPONSE] If the mailbox response could not be fetched, the data
fp@814:   is invalid, the wrong protocol was received, or a ``Abort Sdo
fp@814:   Transfer Request'' was received, the Sdo download is aborted.
fp@379:   $\rightarrow$~ERROR
fp@369: 
fp@814:   If a ``Sdo Download Normal Response'' acknowledgement was received,
fp@814:   the Sdo download was successful. $\rightarrow$~END
fp@814: 
fp@814: \item[END] The Sdo download was successful.
fp@814: 
fp@814: \item[ERROR] The Sdo download was aborted due to an error.
fp@369: 
fp@369: \end{description}
fp@369: 
fp@369: %------------------------------------------------------------------------------
fp@369: 
fp@1270: \section{Vendor-specific-over-EtherCAT (VoE)}
fp@1270: \label{sec:voe}
fp@1270: \index{VoE}
fp@1270: 
fp@1270: The VoE protocol opens the possibility to implement a vendor-specific mailbox
fp@1270: communication protocol. VoE mailbox messages are prepended by a VoE header
fp@1270: containing a 32-bit vendor ID and a 16-bit vendor-type. There are no more
fp@1270: constraints regarding this protocol.
fp@1270: 
fp@1270: The EtherCAT master allows to create multiple VoE handlers per slave
fp@1289: configuration via the application interface (see chap.~\ref{chap:api}). These
fp@1270: handlers contain the state machine necessary for the communication via VoE.
fp@1298: 
fp@1298: For more information about using VoE handlers, see sec.~\ref{sec:api-voe} or
fp@1298: the example applications provided in the \textit{examples/} subdirectory.
fp@1270: 
fp@1270: %------------------------------------------------------------------------------
fp@1270: 
fp@1275: \chapter{Userspace Interfaces}
fp@369: \label{sec:user}
fp@1275: \index{Userspace}
fp@1202: 
fp@1203: For the master runs as a kernel module, accessing it is natively limited to
fp@1275: analyzing Syslog messages and controlling using \textit{modutils}.
fp@1275: 
fp@1275: It was necessary to implement further interfaces, that make it easier to access
fp@1275: the master from userspace and allow a finer influence. It should be possible
fp@1203: to view and to change special parameters at runtime.
fp@1203: 
fp@1275: Bus visualization is another point: For development and debugging purposes it
fp@1275: is necessary to show the connected slaves with a single command, for instance
fp@1289: (see sec.~\ref{sec:tool}).
fp@1275: 
fp@1275: The application interface has to be available in userspace, to allow userspace
fp@1275: programs to use EtherCAT master functionality. This was implemented via a
fp@1282: character device and a userspace library (see sec.~\ref{sec:userlib}).
fp@1275: 
fp@1275: Another aspect is automatic startup and configuration. The master must be able
fp@1275: to automatically start up with a persistent configuration (see
fp@1275: sec.~\ref{sec:system}).
fp@1203: 
fp@1203: A last thing is monitoring EtherCAT communication. For debugging purposes,
fp@1203: there had to be a way to analyze EtherCAT datagrams. The best way would be
fp@1203: with a popular network analyzer, like Wireshark \cite{wireshark} (the former
fp@1275: Ethereal) or others (see sec.~\ref{sec:debug}).
fp@1275: 
fp@1275: This chapter covers all these points and introduces the interfaces and tools
fp@1203: to make all that possible.
fp@369: 
fp@369: %------------------------------------------------------------------------------
fp@369: 
fp@1087: \section{Command-line Tool}
fp@1289: \label{sec:tool}
fp@1087: 
fp@1297: % TODO --master
fp@1087: 
fp@1202: \subsection{Character Devices}
fp@1087: \label{sec:cdev}
fp@1087: 
fp@1214: Each master instance will get a character device as a userspace interface.
fp@1214: The devices are named \textit{/dev/EtherCATx}, where $x \in \{0 \ldots n\}$ is
fp@1214: the index of the master.
fp@1214: 
fp@1214: \paragraph{Device Node Creation} The character device nodes are automatically
fp@1289: created, if the \lstinline+udev+ Package is installed. See
fp@1289: sec.~\ref{sec:autonode} for how to install and configure it.
fp@1087: 
fp@1087: %------------------------------------------------------------------------------
fp@1087: 
fp@1202: \subsection{Setting Alias Addresses}
fp@1293: \label{sec:ethercat-alias}
fp@1140: 
fp@1140: \lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_alias}
fp@1140: 
fp@1140: %------------------------------------------------------------------------------
fp@1140: 
fp@1202: \subsection{Displaying the Bus Configuration}
fp@1293: \label{sec:ethercat-config}
fp@1140: 
fp@1140: \lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_config}
fp@1140: 
fp@1140: %------------------------------------------------------------------------------
fp@1140: 
fp@1202: \subsection{Displaying Process Data}
fp@1140: 
fp@1140: \lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_data}
fp@1140: 
fp@1140: %------------------------------------------------------------------------------
fp@1140: 
fp@1202: \subsection{Setting a Master's Debug Level}
fp@1140: 
fp@1140: \lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_debug}
fp@1140: 
fp@1140: %------------------------------------------------------------------------------
fp@1140: 
fp@1202: \subsection{Configured Domains}
fp@1140: 
fp@1140: \lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_domains}
fp@1140: 
fp@1140: %------------------------------------------------------------------------------
fp@1140: 
fp@1202: \subsection{Master and Ethernet Devices}
fp@1140: 
fp@1140: \lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_master}
fp@1140: 
fp@1140: %------------------------------------------------------------------------------
fp@1140: 
fp@1202: \subsection{Sync Managers, Pdos and Pdo Entries}
fp@1140: 
fp@1140: \lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_pdos}
fp@1140: 
fp@1140: %------------------------------------------------------------------------------
fp@1140: 
fp@1202: \subsection{Sdo Dictionary}
fp@1140: 
fp@1140: \lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_sdos}
fp@1140: 
fp@1140: %------------------------------------------------------------------------------
fp@1140: 
fp@1202: \subsection{Sdo Access}
fp@1140: 
fp@1140: \lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_download}
fp@1140: 
fp@1140: \lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_upload}
fp@1140: 
fp@1140: %------------------------------------------------------------------------------
fp@1140: 
fp@1202: \subsection{Slaves on the Bus}
fp@1087: 
fp@1087: Slave information can be gathered with the subcommand \lstinline+slaves+:
fp@1087: 
fp@1140: \lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_slaves}
fp@1140: 
fp@1140: Below is a typical output:
fp@1140: 
fp@1087: \begin{lstlisting}
fp@1087: $ `\textbf{ethercat slaves}`
fp@1087: 0     0:0  PREOP  +  EK1100 Ethernet Kopplerklemme (2A E-Bus)
fp@1087: 1  5555:0  PREOP  +  EL3162 2K. Ana. Eingang 0-10V
fp@1087: 2  5555:1  PREOP  +  EL4102 2K. Ana. Ausgang 0-10V
fp@1087: 3  5555:2  PREOP  +  EL2004 4K. Dig. Ausgang 24V, 0,5A
fp@1087: \end{lstlisting}
fp@1087: 
fp@369: %------------------------------------------------------------------------------
fp@369: 
fp@1085: \subsection{SII Access}
fp@1085: \label{sec:siiaccess}
fp@1085: \index{SII!Access}
fp@369: 
fp@1087: It is possible to directly read or write the complete SII contents of the
fp@1087: slaves. This was introduced for the reasons below:
fp@369: 
fp@369: \begin{itemize}
fp@1087: 
fp@1087: \item The format of the SII data is still in development and categories can be
fp@1087: added in the future. With read and write access, the complete memory contents
fp@1087: can be easily backed up and restored.
fp@1087: 
fp@1087: \item Some SII data fields have to be altered (like the alias address). A quick
fp@1087: writing must be possible for that.
fp@1087: 
fp@1275: \item Through reading access, analyzing category data is possible from
fp@1275: userspace.
fp@1087: 
fp@369: \end{itemize}
fp@369: 
fp@1140: \lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_sii_read}
fp@1140: 
fp@1087: Reading out SII data is as easy as other commands. Though the data are in
fp@1087: binary format, analysis is easier with a tool like \textit{hexdump}:
fp@1087: 
fp@1087: \begin{lstlisting}
fp@1202: $ `\textbf{ethercat sii\_read --position 3 | hexdump}`
fp@1087: 0000000 0103 0000 0000 0000 0000 0000 0000 008c
fp@1087: 0000010 0002 0000 3052 07f0 0000 0000 0000 0000
fp@1087: 0000020 0000 0000 0000 0000 0000 0000 0000 0000
fp@1087: ...
fp@1087: \end{lstlisting}
fp@1087: 
fp@1087: Backing up SII contents can easily done with a redirection:
fp@1087: 
fp@1087: \begin{lstlisting}
fp@1202: $ `\textbf{ethercat sii\_read --position 3 > sii-of-slave3.bin}`
fp@1087: \end{lstlisting}
fp@1087: 
fp@1087: To download SII contents to a slave, writing access to the master's character
fp@1289: device is necessary (see sec.~\ref{sec:cdev}).
fp@1087: 
fp@1140: \lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_sii_write}
fp@1140: 
fp@1087: \begin{lstlisting}
fp@1202: # `\textbf{ethercat sii\_write --position 3 sii-of-slave3.bin}`
fp@1087: \end{lstlisting}
fp@1087: 
fp@1087: The SII contents will be checked for validity and then sent to the slave. The
fp@1087: write operation may take a few seconds.
fp@369: 
fp@369: %------------------------------------------------------------------------------
fp@369: 
fp@1202: \subsection{Requesting Application-Layer States}
fp@1140: 
fp@1140: \lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_states}
fp@1140: 
fp@1140: %------------------------------------------------------------------------------
fp@1140: 
fp@1202: \subsection{Generating Slave Description XML}
fp@1140: 
fp@1140: \lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_xml}
fp@1140: 
fp@1140: %------------------------------------------------------------------------------
fp@1140: 
fp@1275: \section{Userspace Library}
fp@1275: \label{sec:userlib}
fp@1275: 
fp@1289: The native application interface (see chap.~\ref{chap:api}) resides in
fp@1282: kernelspace and hence is only accessible from inside the kernel. To make the
fp@1282: application interface available from userspace programs, a userspace library
fp@1282: has been created, that can be linked to programs under the terms and
fp@1282: conditions of the LGPL, version 2 \cite{lgpl}.
fp@1282: 
fp@1282: The library is named \textit{libethercat}. Its sources reside in the
fp@1282: \textit{lib/} subdirectory and are build by default when using
fp@1282: \lstinline+make+. It is installed in the \textit{lib/} path below the
fp@1282: installation prefix as \textit{libethercat.a} (for static linking),
fp@1282: \textit{libethercat.la} (for the use with \textit{libtool}) and
fp@1282: \textit{libethercat.so} (for dynamic linking).
fp@1282: 
fp@1299: \subsection{Using the Library}
fp@1282: 
fp@1282: The application interface header \textit{ecrt.h} can be used both in kernel
fp@1282: and in user context.
fp@1282: 
fp@1282: The following minimal example shows how to build a program with EtherCAT
fp@1282: functionality. An entire example can be found in the \textit{examples/user/}
fp@1282: path of the master sources.
fp@1282: 
fp@1282: \begin{lstlisting}[language=C]
fp@1282: #include <ecrt.h>
fp@1282: 
fp@1282: int main(void)
fp@1282: {
fp@1282:     ec_master_t *master = ecrt_request_master(0);
fp@1282: 
fp@1282:     if (!master)
fp@1282:         return 1; // error
fp@1282: 
fp@1282:     pause(); // wait for signal
fp@1282:     return 0;
fp@1282: }
fp@1282: \end{lstlisting}
fp@1282: 
fp@1282: The program can be compiled and dynamically linked to the library with the
fp@1282: below command:
fp@1282: 
fp@1282: \begin{lstlisting}
fp@1282: gcc ethercat.c -o ectest -I/opt/etherlab/include \
fp@1282:     -L/opt/etherlab/lib -lethercat \
fp@1282:     -Wl,--rpath -Wl,/opt/etherlab/lib
fp@1282: \end{lstlisting}
fp@1282: 
fp@1282: The library can also be linked statically to the program:
fp@1282: 
fp@1282: \begin{lstlisting}
fp@1282: gcc -static ectest.c -o ectest -I/opt/etherlab/include \
fp@1282:     /opt/etherlab/lib/libethercat.a
fp@1282: \end{lstlisting}
fp@1282: 
fp@1282: \subsection{Implementation}
fp@1282: \label{sec:userimp}
fp@1282: 
fp@1282: Basically the kernel API was transferred into userspace via the master
fp@1299: character device (see chap.~\ref{chap:arch}, fig.~\ref{fig:arch} and
fp@1299: sec.~\ref{sec:cdev}).
fp@1282: 
fp@1282: The function calls of the kernel API are mapped to the userspace via an
fp@1282: \lstinline+ioctl()+ interface. Each function has its own \lstinline+ioctl()+
fp@1282: call. The kernel part of the interface calls the according API functions
fp@1282: directly, what results in a minimum additional delay (see
fp@1282: sec.~\ref{sec:usertiming}).
fp@1282: 
fp@1299: For performance reasons, the actual domain process data (see
fp@1299: sec.~\ref{sec:processdata}) are not copied between kernel and user memory on
fp@1299: every access: Instead, the data are memory-mapped to the userspace
fp@1299: application. Once the master is configured and activated, the master module
fp@1299: creates one process data memory area spanning all domains and maps it to
fp@1299: userspace, so that the application can directly access the process data. As a
fp@1299: result, there is no additional delay when accessing process data from
fp@1299: userspace.
fp@1299: 
fp@1299: \paragraph{Kernel/User API Differences} Because of the memory-mapping of the
fp@1299: process data, the memory is managed internally by the library functions. As a
fp@1299: result, it is not possible to provide external memory for domains, like in the
fp@1299: kernel API. The corresponding functions are only available in kernelspace.
fp@1299: This is the only difference when using the application interface in userspace.
fp@1275: 
fp@1281: \subsection{Timing}
fp@1281: \label{sec:usertiming}
fp@1281: 
fp@1281: An interesting aspect is the timing of the userspace library calls compared to
fp@1281: those of the kernel API. Table~\ref{tab:usertiming} shows the call times and
fp@1281: standard deviancies of typical (and time-critical) API functions measured on
fp@1281: an Intel Pentium 4 M CPU with \unit{2.2}{\giga\hertz} and a standard 2.6.26
fp@1281: kernel.
fp@1281: 
fp@1281: \begin{table}[htbp]
fp@1281:   \centering
fp@1281:   \caption{Application Interface Timing Comparison}
fp@1281:   \label{tab:usertiming}
fp@1281:   \vspace{2mm}
fp@1281:   \begin{tabular}{l|c|c|c|c}
fp@1281: 
fp@1281:     &
fp@1281:     \multicolumn{2}{|c}{\textbf{Kernelspace}} &
fp@1281:     \multicolumn{2}{|c}{\textbf{Userspace}}  \\
fp@1281: 
fp@1281:     \textbf{Function} &
fp@1281:     $\mu(t)$ &
fp@1281:     $\sigma(t)$ &
fp@1281:     $\mu(t)$ &
fp@1281:     $\sigma(t)$ \\
fp@1281:     \hline
fp@1281: 
fp@1281:     \lstinline+ecrt_master_receive()+ &
fp@1281:     \unit{1.1}{\micro\second} &
fp@1281:     \unit{0.3}{\micro\second} &
fp@1281:     \unit{2.2}{\micro\second} &
fp@1281:     \unit{0.5}{\micro\second} \\
fp@1281: 
fp@1281:     \lstinline+ecrt_domain_process()+ &
fp@1281:     \unit{<0.1}{\micro\second} &
fp@1281:     \unit{<0.1}{\micro\second} &
fp@1281:     \unit{1.0}{\micro\second} &
fp@1281:     \unit{0.2}{\micro\second} \\
fp@1281: 
fp@1281:     \lstinline+ecrt_domain_queue()+ &
fp@1281:     \unit{<0.1}{\micro\second} &
fp@1281:     \unit{<0.1}{\micro\second} &
fp@1281:     \unit{1.0}{\micro\second} &
fp@1281:     \unit{0.1}{\micro\second} \\
fp@1281: 
fp@1281:     \lstinline+ecrt_master_send()+ &
fp@1281:     \unit{1.8}{\micro\second} &
fp@1281:     \unit{0.2}{\micro\second} &
fp@1281:     \unit{2.5}{\micro\second} &
fp@1281:     \unit{0.5}{\micro\second} \\
fp@1281: 
fp@1281:   \end{tabular}
fp@1281: \end{table}
fp@1281: 
fp@1282: The test results show, that for this configuration, the userspace API causes
fp@1282: about \unit{1}{\micro\second} additional delay for each function, compared to
fp@1282: the kernel API.
fp@1281: 
fp@1275: %------------------------------------------------------------------------------
fp@1275: 
fp@1085: \section{System Integration}
fp@369: \label{sec:system}
fp@369: 
fp@1086: To integrate the EtherCAT master as a service into a running system, it comes
fp@1086: with an init script and a sysconfig file, that are described below.
fp@1086: 
fp@1086: \subsection{Init Script}
fp@369: \label{sec:init}
fp@369: \index{Init script}
fp@369: 
fp@1086: The EtherCAT master init script conforms to the requirements of the ``Linux
fp@1086: Standard Base'' (LSB\index{LSB}, \cite{lsb}). The script is installed to
fp@1202: \textit{etc/init.d/ethercat} below the installation prefix and has to be
fp@1202: copied (or better: linked) to the appropriate location (see
fp@1289: sec.~\ref{sec:installation}), before the master can be inserted as a service.
fp@1289: Please note, that the init script depends on the sysconfig file described
fp@1289: below.
fp@1086: 
fp@1306: To provide service dependencies (i.\,e.\ which services have to be started
fp@1306: before others) inside the init script code, LSB defines a special comment
fp@1306: block. System tools can extract this information to insert the EtherCAT init
fp@1306: script at the correct place in the startup sequence:
fp@1086: 
fp@1086: \lstinputlisting[firstline=38,lastline=48]
fp@1086:     {../script/init.d/ethercat}
fp@1086: 
fp@1202: \subsection{Sysconfig File}
fp@1086: \label{sec:sysconfig}
fp@1086: \index{Sysconfig file}
fp@1086: 
fp@1086: For persistent configuration, the init script uses a sysconfig file installed
fp@1086: to \textit{etc/sysconfig/ethercat} (below the installation prefix), that is
fp@1086: mandatory for the init script. The sysconfig file contains all configuration
fp@1086: variables needed to operate one or more masters. The documentation is inside
fp@1086: the file and included below:
fp@1086: 
fp@1086: \lstinputlisting[numbers=left,firstline=9,basicstyle=\ttfamily\scriptsize]
fp@1086:     {../script/sysconfig/ethercat}
fp@1086: 
fp@1202: \subsection{Starting the Master as a Service}
fp@1086: \label{sec:service}
fp@1086: \index{Service}
fp@1086: 
fp@1086: After the init script and the sysconfig file are placed into the right
fp@1086: location, the EtherCAT master can be inserted as a service. The different Linux
fp@1086: distributions offer different ways to mark a service for starting and stopping
fp@1086: in certain runlevels. For example, SUSE Linux provides the \textit{insserv}
fp@1086: command:
fp@1086: 
fp@1086: \begin{lstlisting}
fp@1086: # `\textbf{insserv ethercat}`
fp@369: \end{lstlisting}
fp@369: 
fp@369: The init script can also be used for manually starting and stopping
fp@369: the EtherCAT master. It has to be executed with one of the parameters
fp@379: \texttt{start}, \texttt{stop}, \texttt{restart} or \texttt{status}.
fp@369: 
fp@1085: \begin{lstlisting}[gobble=2]
fp@379:   # `\textbf{/etc/init.d/ethercat restart}`
fp@369:   Shutting down EtherCAT master                done
fp@369:   Starting EtherCAT master                     done
fp@369: \end{lstlisting}
fp@369: 
fp@369: %------------------------------------------------------------------------------
fp@369: 
fp@1307: \section{Debug Interfaces}
fp@369: \label{sec:debug}
fp@1307: \index{Debug Interfaces}
fp@369: 
fp@1306: EtherCAT buses can always be monitored by inserting a switch between master
fp@1306: and slaves. This allows to connect another PC with a network monitor like
fp@1306: Wireshark~\cite{wireshark}, for example.
fp@1306: 
fp@1307: For convenience, so-called ``debug interfaces'' are supported. Debug
fp@1308: interfaces are virtual network interfaces allowing to capture EtherCAT traffic
fp@1308: with a network monitor (like Wireshark or tcpdump) running on the master
fp@1308: machine without using external hardware. To use this functionality, the master
fp@1308: sources have to be configured with the \lstinline+--enable-debug-if+ switch
fp@1308: (see sec.~\ref{sec:installation}).
fp@1307: 
fp@1307: Every EtherCAT master registers a read-only network interface per attached
fp@1308: physical Ethernet device. The network interfaces are named \textit{ecdbgmX}
fp@1308: for the main device, and \textit{ecdbgbX} for the backup device (for future
fp@1308: use), where X is the master index. The below listing shows a debug interface
fp@1308: among some standard network interfaces:
fp@1306: 
fp@1306: \begin{lstlisting}
fp@1306: # `\textbf{ip link}`
fp@1306: 1: lo: <LOOPBACK,UP> mtu 16436 qdisc noqueue
fp@1306:     link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
fp@1306: 4: eth0: <BROADCAST,MULTICAST> mtu 1500 qdisc noop qlen 1000
fp@1307:     link/ether 00:13:46:3b:ad:d7 brd ff:ff:ff:ff:ff:ff
fp@1308: 8: ecdbgm0: <BROADCAST,MULTICAST> mtu 1500 qdisc pfifo_fast
fp@1308:                                                  qlen 1000
fp@1306:     link/ether 00:04:61:03:d1:01 brd ff:ff:ff:ff:ff:ff
fp@1307: \end{lstlisting}
fp@1307: 
fp@1307: While a debug interface is enabled, all frames sent or received to or from the
fp@1307: physical device are additionally forwarded to the debug interface by the
fp@1308: corresponding master. Network interfaces can be enabled with the below
fp@1308: command:
fp@1306: 
fp@1306: \begin{lstlisting}
fp@1306: # `\textbf{ip link set dev ecdbgm0 up}`
fp@1306: \end{lstlisting}
fp@1306: 
fp@1306: Please note, that the frame rate can be very high. With an application
fp@1306: connected, the debug interface can produce thousands of frames per second.
fp@1306: 
fp@1309: \paragraph{Attention} The socket buffers needed for the operation of debug
fp@1309: interfaces have to be allocated dynamically. Some Linux realtime extensions do
fp@1308: not allow this in realtime context!
fp@369: 
fp@369: %------------------------------------------------------------------------------
fp@369: 
fp@1085: \chapter{Timing Aspects}
fp@369: \label{sec:timing}
fp@369: 
fp@1085: Although EtherCAT's timing is highly deterministic and therefore timing issues
fp@1085: are rare, there are a few aspects that can (and should be) dealt with.
fp@369: 
fp@369: %------------------------------------------------------------------------------
fp@369: 
fp@1202: \subsection{Application Interface Profiling}
fp@369: \label{sec:timing-profile}
fp@1204: \index{Profiling}
fp@1204: % FIXME
fp@369: 
fp@1085: One of the most important timing aspects are the execution times of the
fp@1204: application interface functions, that are called in cyclic context. These
fp@1085: functions make up an important part of the overall timing of the application.
fp@1085: To measure the timing of the functions, the following code was used:
fp@369: 
fp@369: \begin{lstlisting}[gobble=2,language=C]
fp@369:   c0 = get_cycles();
fp@369:   ecrt_master_receive(master);
fp@369:   c1 = get_cycles();
fp@369:   ecrt_domain_process(domain1);
fp@369:   c2 = get_cycles();
fp@369:   ecrt_master_run(master);
fp@369:   c3 = get_cycles();
fp@369:   ecrt_master_send(master);
fp@369:   c4 = get_cycles();
fp@369: \end{lstlisting}
fp@369: 
fp@1085: Between each call of an interface function, the CPU timestamp counter is read.
fp@1085: The counter differences are converted to \micro\second\ with help of the
fp@1085: \lstinline+cpu_khz+ variable, that contains the number of increments per
fp@1085: \milli\second.
fp@1085: 
fp@1085: For the actual measuring, a system with a \unit{2.0}{\giga\hertz} CPU was used,
fp@1085: that ran the above code in an RTAI thread with a period of
fp@1085: \unit{100}{\micro\second}. The measuring was repeated $n = 100$ times and the
fp@1085: results were averaged. These can be seen in table~\ref{tab:profile}.
fp@369: 
fp@369: \begin{table}[htpb]
fp@369:   \centering
fp@1204:   \caption{Profiling of an Application Cycle on a \unit{2.0}{\giga\hertz}
fp@1085:   Processor}
fp@369:   \label{tab:profile}
fp@369:   \vspace{2mm}
fp@369:   \begin{tabular}{l|r|r}
fp@1085:     Element & Mean Duration [\second] & Standard Deviancy [\micro\second] \\
fp@369:     \hline
fp@369:     \textit{ecrt\_master\_receive()} & 8.04 & 0.48\\
fp@369:     \textit{ecrt\_domain\_process()} & 0.14 & 0.03\\
fp@369:     \textit{ecrt\_master\_run()} & 0.29 & 0.12\\
fp@369:     \textit{ecrt\_master\_send()} & 2.18 & 0.17\\ \hline
fp@369:     Complete Cycle & 10.65 & 0.69\\ \hline
fp@369:   \end{tabular}
fp@369: \end{table}
fp@369: 
fp@1085: It is obvious, that the functions accessing hardware make up the
fp@369: lion's share. The \textit{ec\_master\_receive()} executes the ISR of
fp@369: the Ethernet device, analyzes datagrams and copies their contents into
fp@369: the memory of the datagram objects. The \textit{ec\_master\_send()}
fp@369: assembles a frame out of different datagrams and copies it to the
fp@369: hardware buffers. Interestingly, this makes up only a quarter of the
fp@369: receiving time.
fp@369: 
fp@1085: The functions that only operate on the masters internal data structures are
fp@1085: very fast ($\Delta t < \unit{1}{\micro\second}$). Interestingly the runtime of
fp@1085: \textit{ec\_domain\_process()} has a small standard deviancy relative to the
fp@1085: mean value, while this ratio is about twice as big for
fp@1085: \textit{ec\_master\_run()}: This probably results from the latter function
fp@1085: having to execute code depending on the current state and the different state
fp@1085: functions are more or less complex.
fp@1085: 
fp@1085: For a realtime cycle makes up about \unit{10}{\micro\second}, the theoretical
fp@1085: frequency can be up to \unit{100}{\kilo\hertz}. For two reasons, this frequency
fp@369: keeps being theoretical:
fp@369: 
fp@369: \begin{enumerate}
fp@1085: 
fp@1085: \item The processor must still be able to run the operating system between the
fp@1085: realtime cycles.
fp@1085: 
fp@1085: \item The EtherCAT frame must be sent and received, before the next realtime
fp@1085: cycle begins. The determination of the bus cycle time is difficult and covered
fp@1289: in sec.~\ref{sec:timing-bus}.
fp@1085: 
fp@369: \end{enumerate}
fp@369: 
fp@369: %------------------------------------------------------------------------------
fp@369: 
fp@369: \subsection{Bus Cycle Measuring}
fp@369: \label{sec:timing-bus}
fp@369: \index{Bus cycle}
fp@369: 
fp@1297: For measuring the time, a frame is ``on the wire'', two timestamps must be
fp@1297: taken:
fp@369: 
fp@369: \begin{enumerate}
fp@1297: 
fp@1297: \item The time, the Ethernet hardware begins with physically sending the
fp@1297: frame.
fp@1297: 
fp@1297: \item The time, the frame is completely received by the Ethernet hardware.
fp@1297: 
fp@369: \end{enumerate}
fp@369: 
fp@369: Both times are difficult to determine. The first reason is, that the
fp@1297: interrupts are disabled and the master is not notified, when a frame is sent
fp@1297: or received (polling would distort the results). The second reason is, that
fp@1297: even with interrupts enabled, the time from the event to the notification is
fp@1297: unknown. Therefore the only way to confidently determine the bus cycle time is
fp@1297: an electrical measuring.
fp@369: 
fp@1204: Anyway, the bus cycle time is an important factor when designing realtime
fp@1204: code, because it limits the maximum frequency for the cyclic task of the
fp@1204: application.  In practice, these timing parameters are highly dependent on the
fp@1204: hardware and often a trial and error method must be used to determine the
fp@1204: limits of the system.
fp@1085: 
fp@1085: The central question is: What happens, if the cycle frequency is too high? The
fp@1297: answer is, that the EtherCAT frames that have been sent at the end of the
fp@1297: cycle are not yet received, when the next cycle starts.  First this is noticed
fp@1297: by \textit{ecrt\_domain\_process()}, because the working counter of the
fp@1297: process data datagrams were not increased. The function will notify the user
fp@1297: via Syslog\footnote{To limit Syslog output, a mechanism has been implemented,
fp@1297: that outputs a summarized notification at maximum once a second.}. In this
fp@1297: case, the process data keeps being the same as in the last cycle, because it
fp@1297: is not erased by the domain. When the domain datagrams are queued again, the
fp@1297: master notices, that they are already queued (and marked as sent). The master
fp@1297: will mark them as unsent again and output a warning, that datagrams were
fp@1085: ``skipped''.
fp@1085: 
fp@1085: On the mentioned \unit{2.0}{\giga\hertz} system, the possible cycle frequency
fp@1085: can be up to \unit{25}{\kilo\hertz} without skipped frames. This value can
fp@1297: surely be increased by choosing faster hardware. Especially the RealTek
fp@1297: network hardware could be replaced by a faster one. Besides, implementing a
fp@1297: dedicated ISR for EtherCAT devices would also contribute to increasing the
fp@1297: latency. These are two points on the author's to-do list.
fp@1085: 
fp@1085: %------------------------------------------------------------------------------
fp@1085: 
fp@1085: \chapter{Installation}
fp@1085: \label{sec:installation}
fp@1085: \index{Master!Installation}
fp@369: 
fp@1202: \section{Building the Software}
fp@1094: 
fp@1094: The current EtherCAT master code is available at~\cite{etherlab} or can be
fp@1094: obtained from the EtherLab CD. The \textit{tar.bz2} file has to be unpacked
fp@1094: with the commands below (or similar):
fp@369: 
fp@1085: \begin{lstlisting}[gobble=2]
fp@1202:   $ `\textbf{tar xjf ethercat-\masterversion.tar.bz2}`
fp@1202:   $ `\textbf{cd ethercat-\masterversion/}`
fp@374: \end{lstlisting}
fp@374: 
fp@374: The tarball was created with GNU Autotools, so the build process
fp@487: follows the below commands:
fp@369: 
fp@1085: \begin{lstlisting}[gobble=2]
fp@1202:   $ `\textbf{./configure}`
fp@1202:   $ `\textbf{make}`
fp@1202:   $ `\textbf{make modules}`
fp@374: \end{lstlisting}
fp@374: 
fp@1085: Table~\ref{tab:config} lists important configuration switches and options.
fp@1085: 
fp@1085: \begin{table}
fp@1085:   \caption{Configuration options}
fp@1085:   \label{tab:config}
fp@1085:   \vspace{2mm}
fp@1085:   \begin{tabular}{l|p{.3\textwidth}|l}
fp@1085: 
fp@1085: \bf Option/Switch & \bf Description & \bf Default\\\hline
fp@1085: 
fp@1085: \lstinline+--prefix+ & Installation prefix & \textit{/opt/etherlab}\\
fp@1085: 
fp@1085: \lstinline+--with-linux-dir+ & Linux kernel sources & Use running kernel\\
fp@1085: 
fp@1085: \lstinline+--with-rtai-dir+ & RTAI path (only for RTAI example) & \\
fp@1085: 
fp@1085: \hline
fp@1085: 
fp@1085: \lstinline+--enable-eoe+ & Enable EoE support & yes\\
fp@1085: 
fp@1085: \lstinline+--enable-cycles+ & Use CPU timestamp counter. Enable this on Intel
fp@1085: architecture to get finer timing calculation. & no\\
fp@1085: 
fp@1085: \lstinline+--enable-debug-if+ & Create a debug interface for each master & no\\
fp@1085: 
fp@1085: \lstinline+--enable-debug-ring+ & Create a debug ring to record frames & no\\
fp@1085: 
fp@1085: \hline
fp@1085: 
fp@1085: \lstinline+--enable-8139too+ & Build the 8139too driver & yes\\
fp@1085: 
fp@1085: \lstinline+--with-8139too-kernel+ & 8139too kernel & $\dagger$\\
fp@1085: 
fp@1085: \lstinline+--enable-e100+ & Build the e100 driver & no\\
fp@1085: 
fp@1085: \lstinline+--with-e100-kernel+ & e100 kernel & $\dagger$\\
fp@1085: 
fp@1085: \lstinline+--enable-e1000+ & Enable e1000 driver & no\\
fp@1085: 
fp@1085: \lstinline+--with-e1000-kernel+ & e1000 kernel & $\dagger$\\
fp@1085: 
fp@1085:   \end{tabular}
fp@1085:   \vspace{2mm}
fp@1085: 
fp@1085: \begin{description}
fp@1085: 
fp@1085: \item[$\dagger$] If this option is not specified, the kernel version to use is
fp@1085: extracted from the Linux kernel sources.
fp@1085: 
fp@1085: \end{description}
fp@1085: 
fp@1085: \end{table}
fp@487: 
fp@1202: \section{Building the Interface Documentation}
fp@1094: \label{sec:gendoc}
fp@1094: 
fp@1094: The source code is documented using Doxygen~\cite{doxygen}. To build the HTML
fp@1202: documentation, the Doxygen software has to be installed. The below command
fp@1095: will generate the documents in the subdirectory \textit{doxygen-output}:
fp@1094: 
fp@1094: \begin{lstlisting}
fp@1094: $ `\textbf{make doc}`
fp@1094: \end{lstlisting}
fp@1094: 
fp@1204: The interface documentation can be viewed by pointing a browser to the file
fp@1293: \textit{doxygen-output/html/index.html}. The functions and data structures of
fp@1293: the application interface a covered by an own module ``Application
fp@1293: Interface''.
fp@1202: 
fp@1202: \section{Installing the Software}
fp@1094: 
fp@1106: The below commands have to be entered as \textit{root}: The first one will
fp@1275: install the EtherCAT header, init script, sysconfig file and the userspace
fp@1202: tool to the prefix path. The second one will install the kernel modules to the
fp@1202: kernel's modules directory. The final \lstinline+depmod+ call is necessary to
fp@1202: include the kernel modules into the \textit{modules.dep} file to make it
fp@1106: available to the \lstinline+modprobe+ command, used in the init script. 
fp@369: 
fp@1094: \begin{lstlisting}
fp@1106: # `\textbf{make install}`
fp@1094: # `\textbf{make modules\_install}`
fp@1106: # `\textbf{depmod}`
fp@369: \end{lstlisting}
fp@369: 
fp@1095: If the target kernel's modules directory is not under \textit{/lib/modules}, a
fp@1095: different destination directory can be specified with the \lstinline+DESTDIR+
fp@1095: make variable. For example:
fp@487: 
fp@1094: \begin{lstlisting}
fp@1094: # `\textbf{make DESTDIR=/vol/nfs/root modules\_install}`
fp@487: \end{lstlisting}
fp@487: 
fp@487: This command will install the compiled kernel modules to
fp@487: \textit{/vol/nfs/root/lib/modules}, prepended by the kernel release.
fp@487: 
fp@1085: If the EtherCAT master shall be run as a service\footnote{Even if the EtherCAT
fp@1085: master shall not be loaded on system startup, the use of the init script is
fp@1289: recommended for manual (un-)loading.} (see sec.~\ref{sec:system}), the init
fp@1086: script and the sysconfig file have to be copied (or linked) to the appropriate
fp@1086: locations. The below example is suitable for SUSE Linux. It may vary for other
fp@1086: distributions.
fp@1085: 
fp@1107: % FIXME relative ln -s?
fp@1094: \begin{lstlisting}
fp@1094: # `\textbf{cd /opt/etherlab}`
fp@1094: # `\textbf{cp etc/sysconfig/ethercat /etc/sysconfig/}`
fp@1094: # `\textbf{ln -s etc/init.d/ethercat /etc/init.d/}`
fp@1094: # `\textbf{insserv ethercat}`
fp@374: \end{lstlisting}
fp@374: 
fp@376: Now the sysconfig file \texttt{/etc/sysconfig/ethercat} (see
fp@1289: sec.~\ref{sec:sysconfig}) has to be customized. The minimal customization is
fp@1289: to set the \lstinline+MASTER0_DEVICE+ variable to the MAC address of the
fp@1085: Ethernet device to use (or \lstinline+ff:ff:ff:ff:ff:ff+ to use the first
fp@1085: device offered) and selecting the driver(s) to load via the
fp@1085: \lstinline+DEVICE_MODULES+ variable.
fp@369: 
fp@1297: After the basic configuration is done, the master can be started with the
fp@1297: below command:
fp@369: 
fp@1094: \begin{lstlisting}
fp@1094: # `\textbf{/etc/init.d/ethercat start}`
fp@369: \end{lstlisting}
fp@369: 
fp@1214: At this time, the operation of the master can be observed by viewing the
fp@1214: Syslog\index{Syslog} messages, which should look like the ones below. If
fp@1214: EtherCAT slaves are connected to the master's EtherCAT device, the activity
fp@1214: indicators should begin to flash.
fp@369: 
fp@369: \begin{lstlisting}[numbers=left]
fp@1085: EtherCAT: Master driver `\masterversion`
fp@1085: EtherCAT: 1 master waiting for devices.
fp@1085: EtherCAT Intel(R) PRO/1000 Network Driver - version 6.0.60-k2
fp@1085: Copyright (c) 1999-2005 Intel Corporation.
fp@1085: PCI: Found IRQ 12 for device 0000:01:01.0
fp@1085: PCI: Sharing IRQ 12 with 0000:00:1d.2
fp@1085: PCI: Sharing IRQ 12 with 0000:00:1f.1
fp@1085: EtherCAT: Accepting device 00:0E:0C:DA:A2:20 for master 0.
fp@1085: EtherCAT: Starting master thread.
fp@1085: ec_e1000: ec0: e1000_probe: Intel(R) PRO/1000 Network
fp@1085:           Connection
fp@1085: ec_e1000: ec0: e1000_watchdog_task: NIC Link is Up 100 Mbps
fp@1085:           Full Duplex
fp@1085: EtherCAT: Link state changed to UP.
fp@1085: EtherCAT: 7 slave(s) responding.
fp@1085: EtherCAT: Slave states: PREOP.
fp@1085: EtherCAT: Scanning bus.
fp@1085: EtherCAT: Bus scanning completed in 431 ms.
fp@369: \end{lstlisting}
fp@369: 
fp@369: \begin{description}
fp@1085: 
fp@1085: \item[\linenum{1} -- \linenum{2}] The master module is loading, and one master
fp@1085: is initialized.
fp@1085: 
fp@1085: \item[\linenum{3} -- \linenum{8}] The EtherCAT-capable e1000 driver is
fp@1085: loading. The master accepts the device with the address
fp@1085: \lstinline+00:0E:0C:DA:A2:20+.
fp@1085: 
fp@1085: \item[\linenum{9} -- \linenum{16}] The master goes to idle phase, starts its
fp@1085: state machine and begins scanning the bus.
fp@1085: 
fp@369: \end{description}
fp@369: 
fp@1214: \section{Automatic Device Node Creation}
fp@1214: \label{sec:autonode}
fp@1214: 
fp@1289: The \lstinline+ethercat+ command-line tool (see sec.~\ref{sec:tool})
fp@1214: communicates with the master via a character device. The corresponding device
fp@1289: nodes are created automatically, if the udev daemon is running.  Note, that on
fp@1289: some distributions, the \lstinline+udev+ package is not installed by default.
fp@1214: 
fp@1214: The device nodes will be created with mode \lstinline+0660+ and group
fp@1292: \lstinline+root+ by default. If ``normal'' users shall have reading access, a
fp@1292: udev rule file (for example \textit{/etc/udev/rules.d/99-EtherCAT.rules}) has
fp@1292: to be created with the following contents:
fp@1214: 
fp@1214: \begin{lstlisting}
fp@1214: KERNEL=="EtherCAT[0-9]*", MODE="0664"
fp@1214: \end{lstlisting}
fp@1214: 
fp@1214: After the udev rule file is created and the EtherCAT master is restarted with
fp@1214: \lstinline[breaklines=true]+/etc/init.d/ethercat restart+, the device node
fp@1214: will be automatically created with the desired rights:
fp@1214: 
fp@1214: \begin{lstlisting}
fp@1214: # `\textbf{ls -l /dev/EtherCAT0}`
fp@1214: crw-rw-r--  1 root root 252, 0 2008-09-03 16:19 /dev/EtherCAT0
fp@1214: \end{lstlisting}
fp@1214: 
fp@1289: Now, the \lstinline+ethercat+ tool can be used (see sec.~\ref{sec:tool}) even
fp@1289: as a non-root user.
fp@1214: 
fp@1306: If non-root users shall have writing access, the following udev rule can be
fp@1306: used instead:
fp@1306: 
fp@1306: \begin{lstlisting}
fp@1306: KERNEL=="EtherCAT[0-9]*", MODE="0664", GROUP="users"
fp@1306: \end{lstlisting}
fp@1306: 
fp@369: %------------------------------------------------------------------------------
fp@369: 
fp@369: \begin{thebibliography}{99}
fp@1094: 
fp@1094: \bibitem{etherlab} Ingenieurgemeinschaft IgH: EtherLab -- Open Source Toolkit
fp@1094: for rapid realtime code generation under Linux with Simulink/RTW and EtherCAT
fp@1094: technology. \url{http://etherlab.org/en}, 2008.
fp@1094: 
fp@369: \bibitem{dlspec} IEC 61158-4-12: Data-link Protocol Specification.
fp@1095: International Electrotechnical Commission (IEC), 2005.
fp@1094: 
fp@1094: \bibitem{alspec} IEC 61158-6-12: Application Layer Protocol Specification.
fp@1095: International Electrotechnical Commission (IEC), 2005.
fp@1094: 
fp@1094: \bibitem{gpl} GNU General Public License, Version 2.
fp@1275: \url{http://www.gnu.org/licenses/gpl-2.0.html}. October~15, 2008.
fp@1275: 
fp@1275: \bibitem{lgpl} GNU Lesser General Public License, Version 2.1.
fp@1275: \url{http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html}. October~15,
fp@1275: 2008.
fp@1094: 
fp@1094: \bibitem{lsb} Linux Standard Base.
fp@1306: \url{http://www.linuxfoundation.org/en/LSB}. August~9, 2006.
fp@1094: 
fp@1094: \bibitem{wireshark} Wireshark. \url{http://www.wireshark.org}. 2008.
fp@1094: 
fp@1306: \bibitem{automata} {\it Hopcroft, J.\,E.\ / Ullman, J.\,D.}: Introduction to
fp@1094: Automata Theory, Languages and Computation. Adison-Wesley, Reading,
fp@1094: Mass.~1979.
fp@1094: 
fp@1306: \bibitem{fsmmis} {\it Wagner, F.\ / Wolstenholme, P.}: State machine
fp@1094: misunderstandings. In: IEE journal ``Computing and Control Engineering'',
fp@1094: 2004.
fp@1094: 
fp@1094: \bibitem{rtai} RTAI. The RealTime Application Interface for Linux from DIAPM.
fp@1094: \url{http://www.rtai.org}, 2006.
fp@1094: 
fp@1094: \bibitem{doxygen} Doxygen. Source code documentation generator tool.
fp@1094: \url{http://www.stack.nl/~dimitri/doxygen}, 2008.
fp@1094: 
fp@369: \end{thebibliography}
fp@369: 
fp@917: \printnomenclature
fp@369: \addcontentsline{toc}{chapter}{\nomname}
fp@369: \markleft{\nomname}
fp@369: 
fp@369: \printindex
fp@369: \markleft{Index}
fp@369: 
fp@369: %------------------------------------------------------------------------------
fp@369: 
fp@369: \end{document}
fp@369: 
fp@369: %------------------------------------------------------------------------------




