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