fp@1727: %------------------------------------------------------------------------------ fp@1727: % fp@1727: % IgH EtherCAT Master Documentation fp@1727: % fp@1727: % $Id$ fp@1727: % fp@1727: %------------------------------------------------------------------------------ fp@1727: fp@1727: \documentclass[a4paper,12pt,BCOR6mm,bibtotoc,idxtotoc]{scrbook} fp@1727: fp@1727: \usepackage[latin1]{inputenc} fp@1727: \usepackage[automark,headsepline]{scrpage2} fp@1727: \usepackage{graphicx} fp@1727: \usepackage{makeidx} fp@1727: \usepackage[refpage]{nomencl} fp@1727: \usepackage{listings} fp@1727: \usepackage{svn} fp@1727: \usepackage{textcomp} fp@1727: \usepackage{url} fp@1727: \usepackage[pdfpagelabels,plainpages=false]{hyperref} fp@1727: fp@1727: \setlength{\parskip}{0.8ex plus 0.8ex minus 0.5ex} fp@1727: \setlength{\parindent}{0mm} fp@1727: fp@1727: \setcounter{secnumdepth}{\subsubsectionlevel} fp@1727: fp@1727: \DeclareFontShape{OT1}{cmtt}{bx}{n} fp@1727: { fp@1727: <5><6><7><8><9><10><10.95><12><14.4><17.28><20.74><24.88>cmttb10 fp@1727: }{} fp@1727: fp@1727: \lstset{basicstyle=\ttfamily\small,numberstyle=\tiny,aboveskip=4mm, fp@1727: belowskip=2mm,gobble=2,escapechar=`} fp@1727: \renewcommand\lstlistlistingname{List of Listings} fp@1727: fp@1727: \renewcommand\nomname{Glossary} fp@1727: fp@1727: \newcommand{\IgH}{\raisebox{-0.7667ex} fp@1727: {\includegraphics[height=2.2ex]{images/ighsign}}} fp@1727: fp@1727: \SVN $Date$ fp@1727: \SVN $Revision$ fp@1727: fp@1732: \newcommand{\masterversion}{1.1.1} fp@1732: fp@1727: \makeindex fp@1727: \makeglossary fp@1727: fp@1727: %------------------------------------------------------------------------------ fp@1727: fp@1727: \begin{document} fp@1727: fp@1727: \pagenumbering{roman} fp@1727: \pagestyle{empty} fp@1727: fp@1727: \begin{titlepage} fp@1727: \begin{center} fp@1727: \rule{\textwidth}{1.5mm} fp@1727: fp@1727: {\Huge\bf IgH \includegraphics[height=2.4ex]{images/ethercat} fp@1732: Master \masterversion\\[1ex] fp@1727: Documentation} fp@1727: fp@1727: \vspace{1ex} fp@1727: \rule{\textwidth}{1.5mm} fp@1727: fp@1727: \vspace{\fill} fp@1727: {\Large Florian Pose, \url{fp@igh-essen.com}\\[1ex] fp@1727: Ingenieurgemeinschaft \IgH} fp@1727: fp@1727: \vspace{\fill} fp@1727: {\Large Essen, \SVNDate\\[1ex] fp@1727: Revision \SVNRevision} fp@1727: \end{center} fp@1727: \end{titlepage} fp@1727: fp@1727: %------------------------------------------------------------------------------ fp@1727: fp@1727: \tableofcontents fp@1727: \listoftables fp@1727: \listoffigures fp@1727: \lstlistoflistings fp@1727: fp@1727: %------------------------------------------------------------------------------ fp@1727: fp@1727: \newpage fp@1727: \pagestyle{scrheadings} fp@1727: fp@1727: \section*{Conventions} fp@1727: \addcontentsline{toc}{section}{Conventions} fp@1727: \markleft{Conventions} fp@1727: fp@1727: The following typographic conventions are used: fp@1727: fp@1727: \begin{itemize} fp@1727: \item \textit{Italic face} is used for newly introduced terms, file fp@1727: names, parameter names and in-text source code elements. fp@1727: \item \texttt{Typewriter face} is used for code examples and fp@1727: command line output. fp@1727: \item \texttt{\textbf{Bold typewriter face}} is used for user input in fp@1727: command lines. fp@1727: \end{itemize} fp@1727: fp@1727: Data values and addresses are specified as hexadecimal values with the fp@1727: prefix 0x. Example: 0x88A4. Unless otherwise noted, address values are fp@1727: specified as byte addresses. fp@1727: fp@1727: Concerning bit operations, the phrase ``setting a bit'', stands for fp@1727: setting the bit to $1$, ``clearing a bit'' means setting it to $0$, fp@1727: respectively. fp@1727: fp@1727: Function names are always printed with parentheses, but without fp@1727: parameters. So, if a function \textit{ecrt\_request\_master()} has fp@1727: empty parentheses, this does not mean, that it has no parameters. fp@1727: fp@1727: If shell commands have to be entered, this is marked by a prompt: fp@1727: fp@1727: \begin{lstlisting}[gobble=2] fp@1729: `\$` fp@1727: \end{lstlisting} fp@1727: fp@1727: Further, if a shell command has to be entered as the superuser, the fp@1727: prompt ends with a mesh: fp@1727: fp@1727: \begin{lstlisting}[gobble=2] fp@1729: # fp@1727: \end{lstlisting} fp@1727: fp@1727: %------------------------------------------------------------------------------ fp@1727: fp@1727: \chapter{The IgH EtherCAT Master} fp@1727: \label{chapter:master} fp@1727: \pagenumbering{arabic} fp@1727: fp@1727: This section will first introduce the master's general features and fp@1727: the concepts used for master development and will then explain the fp@1727: master's general architecture and offer details of the different fp@1727: modules. In addition, it will cover state machine definitions, mailbox fp@1727: protocol implementation and the user space interface. The last section fp@1727: will deal with timing aspects. fp@1727: fp@1727: %------------------------------------------------------------------------------ fp@1727: fp@1727: \section{Feature Summary} fp@1727: \label{sec:summary} fp@1727: \index{Master!Features} fp@1727: fp@1727: The list below gives a short summary of the features of the fp@1727: implemented EtherCAT master. fp@1727: fp@1727: \begin{itemize} fp@1727: \item The master runs as a kernel module for Linux 2.6. fp@1727: \item It comes with EtherCAT-capable network driver for RealTek fp@1727: RTL8139 (and compatible) network interface cards. fp@1727: \begin{itemize} fp@1727: \item The Ethernet hardware is operated without interrupts. fp@1727: \item Drivers for additional Ethernet hardware can easily be fp@1727: implemented due to a common device interface provided by the fp@1727: master. fp@1727: \end{itemize} fp@1727: \item The master module supports multiple EtherCAT masters on one fp@1727: machine. fp@1727: \item The master code supports any Linux realtime extension through fp@1727: its independent architecture. fp@1727: \begin{itemize} fp@1727: \item RTAI\nomenclature{RTAI}{RealTime Application Interface}, fp@1727: ADEOS\nomenclature{ADEOS}{Adaptive Domain Environment for fp@1727: Operating Systems}, etc. fp@1727: \item It runs well even without realtime extensions. fp@1727: \end{itemize} fp@1727: \item Common ``realtime interface'' for modules, that want to use fp@1727: EtherCAT functionality. fp@1727: \begin{itemize} fp@1727: \item Synchronous and asynchronous sending and receiving of frames fp@1727: is supported. fp@1727: \item Avoidance of unnecessary copy operations for process data. fp@1727: \end{itemize} fp@1727: \item \textit{Domains} are introduced, to allow grouping of process fp@1727: data objects. fp@1727: \begin{itemize} fp@1727: \item Handling of multiple domains with different sampling rates. fp@1727: \item Automatic calculation of process data mapping, FMMU and sync manager fp@1727: configuration within each domain. fp@1727: \end{itemize} fp@1727: \item Communication through serveral finite state machines. fp@1727: \begin{itemize} fp@1727: \item Bus monitoring possible during realtime operation. fp@1727: \item Automatic reconfiguration of slaves on bus power failure fp@1727: during realtime operation. fp@1727: \item Controlling of single slaves during realtime operation. fp@1727: \end{itemize} fp@1727: \item Master idle mode. fp@1727: \begin{itemize} fp@1727: \item Automatic scanning of slaves upon topology changes. fp@1727: \item Bus visualisation and EoE processing without a realtime module fp@1727: connected. fp@1727: \end{itemize} fp@1727: \item Implementation of the CANopen-over-EtherCAT (CoE) protocol. fp@1727: \begin{itemize} fp@1727: \item Configuration of CoE-capable slaves via SDO interface. fp@1727: \end{itemize} fp@1727: \item Implementation of the Ethernet-over-EtherCAT (EoE) protocol. fp@1727: \begin{itemize} fp@1727: \item Each master creates virtual network devices that are fp@1727: automatically coupled to EoE-cap\-able slaves found. fp@1727: \item This implementation natively supports either a switched or a fp@1727: routed EoE network architecture. fp@1727: \end{itemize} fp@1727: \item User space interface via the System Filesystem fp@1727: (Sysfs)\nomenclature{Sysfs}{System Filesystem}. fp@1727: \begin{itemize} fp@1727: \item User space tool for bus visualisation. fp@1727: \item Slave E$^2$PROM image reading and writing. fp@1727: \end{itemize} fp@1727: \item Seamless system integration though LSB\nomenclature{LSB}{Linux fp@1727: Standard Base} compliance. fp@1727: \begin{itemize} fp@1727: \item Master and network device configuration via Sysconfig files. fp@1727: \item Linux Standard Base compatible init script for master control. fp@1727: \end{itemize} fp@1727: \item Virtual read-only network interface for monitoring and debugging fp@1727: purposes. fp@1727: \end{itemize} fp@1727: fp@1727: %------------------------------------------------------------------------------ fp@1727: fp@1727: \section{License} fp@1727: \label{sec:license} fp@1727: fp@1727: The master code is released under the terms and conditions of the GNU fp@1727: General Public License\index{GPL} \cite{gpl} (version 2). Other fp@1727: developers, that want to use EtherCAT with Linux systems, are invited fp@1727: to use the master code or even participate on development. fp@1727: fp@1727: %------------------------------------------------------------------------------ fp@1727: fp@1727: \section{General Master Architecture} fp@1727: \label{sec:masterarch} fp@1727: \index{Master!Architecture} fp@1727: fp@1727: The EtherCAT master is integrated into the Linux 2.6 kernel. This was fp@1727: an early design decision, which has been made for serveral reasons: fp@1727: fp@1727: \begin{itemize} fp@1727: \item Kernel code has significantly better realtime characteristics, fp@1727: i.~e. less jitter than user space code. It was foreseeable, that a fp@1727: fieldbus master has a lot of cyclic work to do. Cyclic work is fp@1727: usually triggered by timer interrupts inside the kernel. The fp@1727: execution delay of a function that processes timer interrupts is fp@1727: less, when it resides in kernel space, because there is no need of fp@1727: time-consuming context switches to a user space process. fp@1727: \item It was also foreseeable, that the master code has to directly fp@1727: communicate with the Ethernet hardware. This has to be done in the fp@1727: kernel anyway (through network device drivers), which is one more fp@1727: reason for the master code being in kernel space. fp@1727: \end{itemize} fp@1727: fp@1727: A general overview of the master architecture can be seen in fp@1727: figure~\ref{fig:masterarch}. fp@1727: fp@1727: \begin{figure}[htbp] fp@1727: \centering fp@1727: \includegraphics[width=.9\textwidth]{images/masterarch} fp@1727: \caption{Master architecture} fp@1727: \label{fig:masterarch} fp@1727: \end{figure} fp@1727: fp@1727: \paragraph{Master Module} fp@1727: \index{Master module} fp@1727: fp@1727: The EtherCAT master mainly consists of the master module, containing fp@1727: one or more EtherCAT masters (section~\ref{sec:mastermod}), the fp@1727: ``Device Interface'' (section~\ref{sec:ecdev}) and the ``Realtime fp@1727: Interface'' (section~\ref{sec:ecrt}). fp@1727: fp@1727: \paragraph{Device Modules} fp@1727: \index{Device modules} fp@1727: fp@1727: Furthermore there are EtherCAT-capable network device driver fp@1727: modules\index{Device modules}, that connect to the EtherCAT master via fp@1727: the device interface. These modified network drivers can handle both fp@1727: network devices used for EtherCAT operation and ``normal'' Ethernet fp@1727: devices. The common case is, that the master module offers a single fp@1727: EtherCAT master: An EtherCAT-capable network device driver module fp@1727: connects one network device to this master, that is now able to send fp@1727: and receive EtherCAT frames, while all other network devices handled fp@1727: by the network driver get connected to the kernel's network stack as fp@1727: usual. fp@1727: fp@1727: \paragraph{Realtime Modules} fp@1727: fp@1727: A ``realtime module''\index{Realtime module} is a kernel module, that fp@1727: uses the EtherCAT master for cyclic exchange of process data with fp@1727: EtherCAT slaves. Realtime modules are not part of the EtherCAT master fp@1727: code\footnote{Although there are serveral examples provided in the fp@1727: \textit{examples} directory, see chapter~\ref{chapter:usage} for fp@1727: more information}, so anybody wanting to use the master has to write fp@1727: one. A realtime module can ``request'' a master through the realtime fp@1727: interface. If this succeeds, the module has the control over the fp@1727: master. It can now configure slaves and set up a process data image fp@1727: (see section~\ref{sec:processdata}) for cyclic exchange. This cyclic fp@1727: code has to be provided by the realtime module, so it is in hands of fp@1727: the developer, which mechanism to use for this. Moreover he has to fp@1727: decide, whether or not using a Linux realtime extension. fp@1727: fp@1727: \paragraph{Why ``Realtime'' Module?} fp@1727: fp@1727: The name shall not imply, that a linux realtime extension is fp@1727: mandatory: The master runs well even without realtime extensions, as fp@1727: section~\ref{sec:mini} shows. However, the code using the master is fp@1727: time-critical, because process data IO has to be done in cyclic work. fp@1727: Some EtherCAT slaves support watchdog units, that stop driving the fp@1727: outputs when process data was not exchanged for some time. So the fp@1727: names ``realtime interface'' and ``realtime module'' are quite fp@1727: appropriate. fp@1727: fp@1727: %------------------------------------------------------------------------------ fp@1727: fp@1727: \subsection{Handling of Process Data} fp@1727: \label{sec:processdata} fp@1727: fp@1727: \paragraph{Process Data Image} fp@1727: \index{Process data} fp@1727: fp@1727: The slaves offer their inputs and outputs by presenting the master fp@1727: so-called ``Process Data Objects'' (PDOs\index{PDO}). The available fp@1727: PDOs can be determined by reading out the slave's TXPDO and RXPDO fp@1727: E$^2$PROM categories. The realtime module can register the PDOs for fp@1727: data exchange during cyclic operation. The sum of all registered PDOs fp@1727: defines the ``process data image'', which is exchanged via the fp@1727: ``Logical ReadWrite'' datagrams introduced fp@1727: in~\cite[section~5.4.2.4]{dlspec}. fp@1727: fp@1727: \paragraph{Process Data Domains} fp@1727: \index{Domain} fp@1727: fp@1727: The process data image can be easily managed by creating co-called fp@1727: ``domains'', which group PDOs and allocate the datagrams needed to fp@1727: exchange them. Domains are mandatory for process data exchange, so fp@1727: there has to be at least one. They were introduced for the following fp@1727: reasons: fp@1727: fp@1727: \begin{itemize} fp@1727: \item The maximum size of a ``Logical ReadWrite'' datagram is limited fp@1727: due to the limited size of an Ethernet frame: The maximum data size fp@1727: is the Ethernet data field size minus the EtherCAT frame header, fp@1727: EtherCAT datagram header and EtherCAT datagram footer: $1500 - 2 - fp@1727: 12 - 2 = 1484$ octets. If the size of the process data image exceeds fp@1727: this limit, multiple frames have to be sent, and the image has to be fp@1727: partitioned for the use of multiple datagrams. A domain manages this fp@1727: automatically. fp@1727: \item Not every PDO has to be exchanged with the same frequency: The fp@1727: values of PDOs can vary slowly over time (for example temperature fp@1727: values), so exchanging them with a high frequency would just waste fp@1727: bus bandwidth. For this reason, multiple domains can be created, to fp@1727: group different PDOs and so allow separate exchange. fp@1727: \end{itemize} fp@1727: fp@1727: There is no upper limit for the number of domains, but each domain fp@1727: occupies one FMMU in each slave involved, so the maximum number of fp@1727: domains is also limited by the slaves' capabilities. fp@1727: fp@1727: \paragraph{FMMU Configuration} fp@1727: \index{FMMU!Configuration} fp@1727: fp@1727: A realtime module can register PDOs for process data exchange. Every fp@1727: PDO is part of a memory area in the slave's physical memory, that is fp@1727: protected by a sync manager \cite[section~6.7]{dlspec} for fp@1727: synchronized access. In order to make a sync manager react on a fp@1727: datagram accessing its memory, it is necessary to access the last byte fp@1727: covered by the sync manager. Otherwise the sync manager will not react fp@1727: on the datagram and no data will be exchanged. That is why the whole fp@1727: synchronized memory area has to be included into the process data fp@1727: image: For example, if a certain PDO of a slave is registered for fp@1727: exchange with a certain domain, one FMMU will be configured to map the fp@1727: complete sync-manager-protected memory, the PDO resides in. If a fp@1727: second PDO of the same slave is registered for process data exchange fp@1727: within the same domain, and this PDO resides in the same fp@1727: sync-manager-protected memory as the first PDO, the FMMU configuration fp@1727: is not touched, because the appropriate memory is already part of the fp@1727: domain's process data image. If the second PDO belongs to another fp@1727: sync-manager-protected area, this complete area is also included into fp@1727: the domains process data image. See figure~\ref{fig:fmmus} for an fp@1727: overview, how FMMU's are configured to map physical memory to logical fp@1727: process data images. fp@1727: fp@1727: \begin{figure}[htbp] fp@1727: \centering fp@1727: \includegraphics[width=\textwidth]{images/fmmus} fp@1727: \caption{FMMU configuration for serveral domains} fp@1727: \label{fig:fmmus} fp@1727: \end{figure} fp@1727: fp@1727: \paragraph{Process Data Pointers} fp@1727: fp@1727: The figure also demonstrates the way, the realtime module can access the fp@1727: exchanged process data: At PDO registration, the realtime module has fp@1727: to provide the address of a process data pointer. Upon calculation of fp@1727: the domain image and allocation of process data memory, this pointer fp@1727: is redirected to the appropriate location inside the domain's process fp@1727: data memory and can later be easily dereferenced by the module code. fp@1727: fp@1727: %------------------------------------------------------------------------------ fp@1727: fp@1727: \subsection{Operation Modes} fp@1727: \index{Master modes} fp@1727: fp@1727: The EtherCAT master has serveral modes of operation: fp@1727: fp@1727: \begin{description} fp@1727: \item[Orphaned Mode] This mode takes effect, when the master has no fp@1727: EtherCAT-capable network device connected. No bus communication is fp@1727: possible, so this mode is not of further interest. fp@1727: \item[Idle Mode]\index{Idle mode} takes effect when the master is fp@1727: unused (i.~e. there is no realtime module, that reserved the fp@1727: master). In this case, the master has the ability to scan the bus by fp@1727: itsself and generously allow bus access from user space. This mode fp@1727: is meant for maintenance and visualisation. fp@1727: \item[Operation Mode]\index{Operation mode} The master is reserved for fp@1727: exclusive access by a realtime module. In this mode, the master is fp@1727: adjusted for availability and monitoring. Access from user space is fp@1727: very restrictive and mostly limited to reading direction. fp@1727: fp@1727: \end{description} fp@1727: fp@1727: Figure~\ref{fig:modes} shows the three modes and the possible mode fp@1727: transitions. fp@1727: fp@1727: \begin{figure}[htbp] fp@1727: \centering fp@1727: \includegraphics[width=.9\textwidth]{images/modes} fp@1727: \caption{Master modes and transitions} fp@1727: \label{fig:modes} fp@1727: \end{figure} fp@1727: fp@1727: \subsubsection{Idle Mode} fp@1727: \index{Idle mode} fp@1727: fp@1727: The master enters idle mode upon connection of a device module (see fp@1727: section~\ref{sec:device}) or releasing by a realtime module. The fp@1727: master owns a kernel workqueue and a suitable work structure, which is fp@1727: used to cyclically process the ``Idle state machine'' (see fp@1727: section~\ref{sec:fsm-idle}). This state machine automatically scans fp@1727: the bus for slaves (and re-scans upon topology changes), configures fp@1727: slaves for idle operation and executes pending operations from the fp@1727: user space interface (for example E$^2$PROM writing). On device fp@1727: disconnection or realtime request, the idle mode is stopped by fp@1727: cancelling the work and flushing the workqueue. fp@1727: fp@1727: \subsubsection{Operation Mode} fp@1727: \index{Operation mode} fp@1727: fp@1727: Operation mode is entered when a realtime module requests the master. fp@1727: The idle mode is stopped and the bus is scanned by getting the number fp@1727: of slaves and executing the ``Slave scan state machine'' (see fp@1727: section~\ref{sec:fsm-scan}) for each slave. The master is now ready to fp@1727: create domains and accept PDO registrations and slave configurations. fp@1727: After that, cyclic communication can be done by the realtime module. fp@1727: fp@1727: \paragraph{Master Phases} fp@1727: fp@1727: Every realtime module should use the master in three phases: fp@1727: fp@1727: \begin{enumerate} fp@1727: \item \textit{Startup} - The master is requested and the bus is fp@1727: validated. Domains are created and PDOs are registered. Slave fp@1727: configurations are applied. fp@1727: \item \textit{Operation} - Cyclic code is run, process data is fp@1727: exchanged and the master state machine is executed. fp@1727: \item \textit{Shutdown} - Cyclic code is stopped and the master fp@1727: is released. fp@1727: \end{enumerate} fp@1727: fp@1727: %------------------------------------------------------------------------------ fp@1727: fp@1727: \section{Device Modules} fp@1727: \label{sec:device} fp@1727: \index{Device modules} fp@1727: fp@1727: Device modules are network device driver modules that handle Ethernet fp@1727: devices, which the master can use to connect to an EtherCAT bus. fp@1727: fp@1727: Section~\ref{sec:networkdrivers} offers an overview of general Linux fp@1727: network driver modules, while section~\ref{sec:requirements} will show fp@1727: the requirements to an EtherCAT-enabled network driver. Finally, fp@1727: sections~\ref{sec:seldev} to~\ref{sec:patching} show how to fulfill fp@1727: these requirements and implement such a driver module. fp@1727: fp@1727: %------------------------------------------------------------------------------ fp@1727: fp@1727: \subsection{Network Driver Basics} fp@1727: \label{sec:networkdrivers} fp@1727: \index{Network drivers} fp@1727: fp@1727: EtherCAT relies on Ethernet hardware and the master needs a physical fp@1727: Ethernet device to communicate with the bus. Therefore it is necessary fp@1727: to understand how Linux handles network devices and their drivers, fp@1727: respectively. fp@1727: fp@1727: \paragraph{Tasks of a Network Driver} fp@1727: fp@1727: Network device drivers handle the lower two layers of the OSI model, fp@1727: that is the physical layer and the data-link layer. A network device fp@1727: itself natively handles the physical layer issues: It represents the fp@1727: hardware to connect to the medium and to send and receive data in the fp@1727: way, the physical layer protocol describes. The network device driver fp@1727: is responsible for getting data from the kernel's networking stack and fp@1727: forwarding it to the hardware, that does the physical transmission. fp@1727: If data is received by the hardware respectively, the driver is fp@1727: notified (usually by means of an interrupt) and has to read the data fp@1727: from the hardware memory and forward it to the network stack. There fp@1727: are a few more tasks, a network device driver has to handle, including fp@1727: queue control, statistics and device dependent features. fp@1727: fp@1727: \paragraph{Driver Startup} fp@1727: fp@1727: Usually, a driver searches for compatible devices on module loading. fp@1727: For PCI drivers, this is done by scanning the PCI bus and checking for fp@1727: known device IDs. If a device is found, data structures are allocated fp@1727: and the device is taken into operation. fp@1727: fp@1727: \paragraph{Interrupt Operation} fp@1727: \index{Interrupt} fp@1727: fp@1727: A network device usually provides a hardware interrupt that is used to fp@1727: notify the driver of received frames and success of transmittion, or fp@1727: errors, respectively. The driver has to register an interrupt service fp@1727: routine (ISR\index{ISR}\nomenclature{ISR}{Interrupt Service Routine}), fp@1727: that is executed each time, the hardware signals such an event. If the fp@1727: interrupt was thrown by the own device (multiple devices can share one fp@1727: hardware interrupt), the reason for the interrupt has to be determined fp@1727: by reading the device's interrupt register. For example, if the flag fp@1727: for received frames is set, frame data has to be copied from hardware fp@1727: to kernel memory and passed to the network stack. fp@1727: fp@1727: \paragraph{The net\_device structure} fp@1727: \index{net\_device} fp@1727: fp@1727: The driver registers a \textit{net\_device} structure for each device fp@1727: to communicate with the network stack and to create a ``network fp@1727: interface''. In case of an Ethernet driver, this interface appears as fp@1727: \textit{ethX}, where X is a number assigned by the kernel on fp@1727: registration. The \textit{net\_device} structure receives events fp@1727: (either from user space or from the network stack) via serveral fp@1727: callbacks, which have to be set before registration. Not every fp@1727: callback is mandatory, but for reasonable operation the ones below are fp@1727: needed in any case: fp@1727: fp@1727: \begin{description} fp@1727: \item[int (*open)(struct net\_device *)] This function is called when fp@1727: network communication has to be started, for example after a command fp@1727: \textit{ifconfig ethX up} from user space. Frame reception has to be fp@1727: enabled by the driver. fp@1727: \item[int (*stop)(struct net\_device *)] The purpose of this callback fp@1727: is to ``close'' the device, i.~e. make the hardware stop receiving fp@1727: frames. fp@1727: \item[int (*hard\_start\_xmit)(struct sk\_buff *, struct net\_device fp@1727: *)] This function is cal\-led for each frame that has to be fp@1727: transmitted. The network stack passes the frame as a pointer to an fp@1727: \textit{sk\_buff} structure (``socket buffer''\index{Socket buffer}, fp@1727: see below), which has to be freed after sending. fp@1727: \item[struct net\_device\_stats *(*get\_stats)(struct net\_device *)] fp@1727: This call has to return a pointer to the device's fp@1727: \textit{net\_device\_stats} structure, which permanently has to be fp@1727: filled with frame statistics. This means, that everytime a frame is fp@1727: received, sent, or an error happened, the appropriate counter in fp@1727: this structure has to be increased. fp@1727: \end{description} fp@1727: fp@1727: The actual registration is done with the \textit{register\_netdev()} fp@1727: call, unregistering is done with \textit{unregister\_netdev()}. fp@1727: fp@1727: \paragraph{The netif Interface} fp@1727: \index{netif} fp@1727: fp@1727: All other communication in the direction interface $\to$ network stack fp@1727: is done via the \textit{netif\_*} calls. For example, on successful fp@1727: device opening, the network stack has to be notified, that it can now fp@1727: pass frames to the interface. This is done by calling fp@1727: \textit{netif\_start\_queue()}. After this call, the fp@1727: \textit{hard\_start\_xmit()} callback can be called by the network fp@1727: stack. Furthermore a network driver usually manages a frame fp@1727: transmission queue. If this gets filled up, the network stack has to fp@1727: be told to stop passing further frames for a while. This happens with fp@1727: a call to \textit{netif\_stop\_queue()}. If some frames have been fp@1727: sent, and there is enough space again to queue new frames, this can be fp@1727: notified with \textit{netif\_wake\_queue()}. Another important call is fp@1727: \textit{netif\_receive\_skb()}\footnote{This function is part of the fp@1727: NAPI (``New API''), that replaces the ``old'' kernel 2.4 technique fp@1727: for interfacing to the network stack (with \textit{netif\_rx()}). fp@1727: NAPI is a technique to improve network performance on Linux. Read fp@1727: more in fp@1727: http://www.cyberus.ca/\textasciitilde{}hadi/usenix-paper.tgz}: It fp@1727: passes a frame to the network stack, that was just received by the fp@1727: device. Frame data has to be packed into a so-called ``socket fp@1727: buffer'' for that (see below). fp@1727: fp@1727: \paragraph{Socket Buffers} fp@1727: \index{Socket buffer} fp@1727: fp@1727: Socket buffers are the basic data type for the whole network stack. fp@1727: They serve as containers for network data and are able to quickly add fp@1727: data headers and footers, or strip them off again. Therefore a socket fp@1727: buffer consists of an allocated buffer and serveral pointers that mark fp@1727: beginning of the buffer (\textit{head}), beginning of data fp@1727: (\textit{data}), end of data (\textit{tail}) and end of buffer fp@1727: (\textit{end}). In addition, a socket buffer holds network header fp@1727: information and (in case of received data) a pointer to the fp@1727: \textit{net\_device}, it was received on. There exist functions that fp@1727: create a socket buffer (\textit{dev\_alloc\_skb()}), add data either fp@1727: from front (\textit{skb\_push()}) or back (\textit{skb\_put()}), fp@1727: remove data from front (\textit{skb\_pull()}) or back fp@1727: (\textit{skb\_trim()}), or delete the buffer (\textit{kfree\_skb()}). fp@1727: A socket buffer is passed from layer to layer, and is freed by the fp@1727: layer that uses it the last time. In case of sending, freeing has to fp@1727: be done by the network driver. fp@1727: fp@1727: %------------------------------------------------------------------------------ fp@1727: fp@1727: \subsection{EtherCAT Network Drivers} fp@1727: \label{sec:requirements} fp@1727: fp@1727: There are a few requirements for Ethernet network devices to function fp@1727: as EtherCAT devices, when connected to an EtherCAT bus. fp@1727: fp@1727: \paragraph{Dedicated Interfaces} fp@1727: fp@1727: For performance and realtime purposes, the EtherCAT master needs fp@1727: direct and exclusive access to the Ethernet hardware. This implies fp@1727: that the network device must not be connected to the kernel's network fp@1727: stack as usual, because the kernel would try to use it as an ordinary fp@1727: Ethernet device. fp@1727: fp@1727: \paragraph{Interrupt-less Operation} fp@1727: \index{Interrupt} fp@1727: fp@1727: EtherCAT frames travel through the logical EtherCAT ring and are then fp@1727: sent back to the master. Communication is highly deterministic: A fp@1727: frame is sent and will be received again after a constant time. fp@1727: Therefore, there is no need to notify the driver about frame fp@1727: reception: The master can instead query the hardware for received fp@1727: frames. fp@1727: fp@1727: Figure~\ref{fig:interrupt} shows two workflows for cyclic frame fp@1727: transmittion and reception with and without interrupts. fp@1727: fp@1727: \begin{figure}[htbp] fp@1727: \centering fp@1727: \includegraphics[width=.8\textwidth]{images/interrupt} fp@1727: \caption{Interrupt Operation versus Interrupt-less Operation} fp@1727: \label{fig:interrupt} fp@1727: \end{figure} fp@1727: fp@1727: In the left workflow ``Interrupt Operation'', the data from the last fp@1727: cycle is first processed and a new frame is assembled with new fp@1727: datagrams, which is then sent. The cyclic work is done for now. fp@1727: Later, when the frame is received again by the hardware, an interrupt fp@1727: is triggered and the ISR is executed. The ISR will fetch the frame fp@1727: data from the hardware and initiate the frame dissection: The fp@1727: datagrams will be processed, so that the data is ready for processing fp@1727: in the next cycle. fp@1727: fp@1727: In the right workflow ``Interrupt-less Operation'', there is no fp@1727: hardware interrupt enabled. Instead, the hardware will be polled by fp@1727: the master by executing the ISR. If the frame has been received in the fp@1727: meantime, it will be dissected. The situation is now the same as at fp@1727: the beginning of the left workflow: The received data is processed and fp@1727: a new frame is assembled and sent. There is nothing to do for the rest fp@1727: of the cycle. fp@1727: fp@1727: The interrupt-less operation is desirable, because there is simply no fp@1727: need for an interrupt. Moreover hardware interrupts are not conducive fp@1727: in improving the driver's realtime behaviour: Their undeterministic fp@1727: incidences contribute to increasing the jitter. Besides, if a realtime fp@1727: extension (like RTAI) is used, some additional effort would have to be fp@1727: made to priorize interrupts. fp@1727: fp@1727: \paragraph{Ethernet and EtherCAT Devices} fp@1727: fp@1727: Another issue lies in the way Linux handles devices of the same type. fp@1727: For example, a PCI\nomenclature{PCI}{Peripheral Component fp@1727: Interconnect, Computer Bus} driver scans the PCI bus for devices it fp@1727: can handle. Then it registers itself as the responsible driver for all fp@1727: of the devices found. The problem is, that an unmodified driver can fp@1727: not be told to ignore a device because it will be used for EtherCAT fp@1727: later. There must be a way to handle multiple devices of the same fp@1727: type, where one is reserved for EtherCAT, while the other is treated fp@1727: as an ordinary Ethernet device. fp@1727: fp@1727: For all this reasons, the author has decided that the only acceptable fp@1727: solution is to modify standard Ethernet drivers in a way that they fp@1727: keep their normal functionality, but gain the ability to treat one or fp@1727: more of the devices as EtherCAT-capable. fp@1727: fp@1727: Below are the advantages of this solution: fp@1727: fp@1727: \begin{itemize} fp@1727: \item No need to tell the standard drivers to ignore certain devices. fp@1727: \item One networking driver for EtherCAT and non-EtherCAT devices. fp@1727: \item No need to implement a network driver from scratch and running fp@1727: into issues, the former developers already solved. fp@1727: \end{itemize} fp@1727: fp@1727: The chosen approach has the following disadvantages: fp@1727: fp@1727: \begin{itemize} fp@1727: \item The modified driver gets more complicated, as it must handle fp@1727: EtherCAT and non-EtherCAT devices. fp@1727: \item Many additional case differentiations in the driver code. fp@1727: \item Changes and bugfixes on the standard drivers have to be ported fp@1727: to the Ether\-CAT-capable versions from time to time. fp@1727: \end{itemize} fp@1727: fp@1727: %------------------------------------------------------------------------------ fp@1727: fp@1727: \subsection{Device Selection} fp@1727: \label{sec:seldev} fp@1727: fp@1727: After loading the master module, at least one EtherCAT-capable network fp@1727: driver module has to be loaded, that connects one of its devices to fp@1727: the master. To specify an EtherCAT device and the master to connect fp@1727: to, all EtherCAT-capable network driver modules should provide two fp@1727: module parameters: fp@1727: fp@1727: \begin{description} fp@1727: \item[ec\_device\_index] PCI device index of the device that is fp@1727: connected to the EtherCAT bus. If this parameter is left away, all fp@1727: devices found are treated as ordinary Ethernet devices. Default: fp@1727: $-1$ fp@1727: \item[ec\_master\_index] Index of the master to connect to. Default: fp@1727: $0$ fp@1727: \end{description} fp@1727: fp@1727: The following command loads the EtherCAT-capable RTL8139 device fp@1727: driver, telling it to handle the second device as an EtherCAT device fp@1727: and connecting it to the first master: fp@1727: fp@1727: \begin{lstlisting} fp@1729: # `\textbf{modprobe ec\_8139too ec\_device\_index=1}` fp@1727: \end{lstlisting} fp@1727: fp@1727: Usually, this command does not have to be entered manually, but is fp@1727: called by the EtherCAT init script. See section~\ref{sec:init} for fp@1727: more information. fp@1727: fp@1727: %------------------------------------------------------------------------------ fp@1727: fp@1727: \subsection{The Device Interface} fp@1727: \label{sec:ecdev} fp@1727: \index{Device interface} fp@1727: fp@1727: An anticipation to the section about the master module fp@1727: (section~\ref{sec:mastermod}) has to be made in order to understand fp@1727: the way, a network device driver module can connect a device to a fp@1727: specific EtherCAT master. fp@1727: fp@1727: The master module provides a ``device interface'' for network device fp@1727: drivers. To use this interface, a network device driver module must fp@1727: include the header fp@1727: \textit{devices/ecdev.h}\nomenclature{ecdev}{EtherCAT Device}, coming fp@1727: with the EtherCAT master code. This header offers a function interface fp@1727: for EtherCAT devices which is explained below. All functions of the fp@1727: device interface are named with the prefix \textit{ecdev}. fp@1727: fp@1727: \paragraph{Device Registration} fp@1727: fp@1727: A network device driver can connect a physical device to an EtherCAT fp@1727: master with the \textit{ecdev\_register()} function. fp@1727: fp@1727: \begin{lstlisting}[language=C] fp@1727: ec_device_t *ecdev_register(unsigned int master_index, fp@1727: struct net_device *net_dev, fp@1727: ec_isr_t isr, fp@1727: struct module *module); fp@1727: \end{lstlisting} fp@1727: fp@1727: The first parameter \textit{master\_index} must be the index of the fp@1727: EtherCAT master to connect to (see section~\ref{sec:mastermod}), fp@1727: followed by \textit{net\_dev}, the pointer to the corresponding fp@1727: net\_device structure, which represents the network device to connect. fp@1727: The third parameter \textit{isr} must be a pointer to the interrupt fp@1727: service routine (ISR\index{ISR}) handling the device. The master will fp@1727: later execute the ISR in order to receive frames and to update the fp@1727: device status. The last parameter \textit{module} must be the pointer fp@1727: to the device driver module, which is usually accessible via the macro fp@1727: \textit{THIS\_MODULE} (see next paragraph). On success, the function fp@1727: returns a pointer to an \textit{ec\_device\_t} object, which has to be fp@1727: specified when calling further functions of the device interface. fp@1727: Therefore the device module has to store this pointer for future use. fp@1727: In error case, the \textit{ecdev\_register()} returns \textit{NULL}, fp@1727: which means that the device could not be registered. The reason for fp@1727: this is printed to \textit{syslog}\index{syslog}. In this case, the fp@1727: device module is supposed to abort the module initialisation and let fp@1727: the \textit{insmod} command fail. fp@1727: fp@1727: \paragraph{Implicit Dependencies} fp@1727: fp@1727: The reason for the module pointer has to be specified at device fp@1727: registration is a non-trivial one: The master has to know about the fp@1727: module, because there will be an implicit dependency between the fp@1727: device module and a later connected realtime module: When a realtime fp@1727: module connects to the master, the use count of the master module will fp@1727: be increased, so that the master module can not be unloaded for the fp@1727: time of the connection. This is reasonable, and so automatically done fp@1727: by the kernel. The kernel knows about this dependency, because the fp@1727: realtime module uses kernel symbols provided by the master module. fp@1727: Moreover it is mandatory, that the device module can be unloaded fp@1727: neither, because it is implicitely used by the realtime module, too. fp@1727: Unloading it would lead to a fatal situation, because the master would fp@1727: have no device to send and receive frames for the realtime module. fp@1727: This dependency can not be detected automatically, because the fp@1727: realtime module does not use any symbols of the device module. fp@1727: Therefore the master explicitly increments the use counter of the fp@1727: connected device module upon connection of a realtime module and fp@1727: decrements it, if the realtime module disconnects. In this manner, it fp@1727: is impossible to unload a device module while the master is in use. fp@1727: This is done with the kernel function pair \textit{try\_module\_get()} fp@1727: \index{try\_module\_get@\textit{try\_module\_get()}} and fp@1727: \textit{module\_put()} \index{module\_put@\textit{module\_put()}}. The fp@1727: first one increases the use count of a module and only fails, if the fp@1727: module is currenly being unloaded. The last one decreases the use fp@1727: count again and never fails. Both functions take a pointer to the fp@1727: module as their argument, which the device module therefore has to fp@1727: specify upon device registration. fp@1727: fp@1727: \paragraph{Device Unregistering} fp@1727: fp@1727: The unregistration of a device is usually done in the device module's fp@1727: cleanup function, by calling the \textit{ecdev\_unregister()} function fp@1727: and specifying the master index and a pointer to the device object fp@1727: again. fp@1727: fp@1727: \begin{lstlisting}[language=C] fp@1727: void ecdev_unregister(unsigned int master_index, fp@1727: ec_device_t *device); fp@1727: \end{lstlisting} fp@1727: fp@1727: This function can fail too (if the master index is invalid, or the fp@1727: given device was not registered), but due to the fact, that this fp@1727: failure can not be dealt with appropriately, because the device module fp@1727: is unloading anyway, the failure code would not be of any interest. So fp@1727: the function has a void return value. fp@1727: fp@1727: \paragraph{Starting the Master} fp@1727: fp@1727: When a device has been initialized completely and is ready to send and fp@1727: receive frames, the master has to be notified about this by calling fp@1727: the \textit{ecdev\_start()} function. fp@1727: fp@1727: \begin{lstlisting}[language=C] fp@1727: int ecdev_start(unsigned int master_index); fp@1727: \end{lstlisting} fp@1727: fp@1727: The master will then enter ``Idle Mode'' and start scanning the bus fp@1727: (and possibly handling EoE slaves). Moreover it will make the bus fp@1727: accessible via Sysfs interface and react to user interactions. The fp@1727: function takes one parameter \textit{master\_index}, which has to be fp@1727: the same as at the call to \textit{ecdev\_register()}. The return fp@1727: value will be non-zero if the starting process failed. In this case fp@1727: the device module is supposed to abort the init sequence and make the fp@1727: init function return an error code. fp@1727: fp@1727: \paragraph{Stopping the Master} fp@1727: fp@1727: Before a device can be unregistered, the master has to be stopped by fp@1727: calling the \textit{ecdev\_stop()} function. It will stop processing fp@1727: messages of EoE slaves and leave ``Idle Mode''. The only parameter is fp@1727: \textit{master\_index}. This function can not fail. fp@1727: fp@1727: \begin{lstlisting}[language=C] fp@1727: void ecdev_stop(unsigned int master_index); fp@1727: \end{lstlisting} fp@1727: fp@1727: A subsequent call to \textit{ecdev\_unregister()} will now unregister fp@1727: the device savely. fp@1727: fp@1727: \paragraph{Receiving Frames} fp@1727: fp@1727: The interrupt service routine handling device events usually has a fp@1727: section where new frames are fetched from the hardware and forwarded fp@1727: to the kernel network stack via \textit{netif\_receive\_skb()}. For an fp@1727: EtherCAT-capable device, this has to be replaced by calling the fp@1727: \textit{ecdev\_receive()} function to forward the received data to the fp@1727: connected EtherCAT master instead. fp@1727: fp@1727: \begin{lstlisting}[language=C] fp@1727: void ecdev_receive(ec_device_t *device, fp@1727: const void *data, fp@1727: size_t size); fp@1727: \end{lstlisting} fp@1727: fp@1727: This function takes 3 arguments, a pointer to the device object fp@1727: (\textit{device}), a pointer to the received data, and the size of the fp@1727: received data. The data range has to include the Ethernet headers fp@1727: starting with the destination address and reach up to the last octet fp@1727: of EtherCAT data, excluding the FCS. Most network devices handle the fp@1727: FCS in hardware, so it is not seen by the driver code and therefore fp@1727: doesn't have to be cut off manually. fp@1727: fp@1727: \paragraph{Handling the Link Status} fp@1727: fp@1727: Information about the link status (i.~e. if there is a carrier signal fp@1727: detected on the physical port) is also important to the master. This fp@1727: information is usually gathered by the ISR and should be forwarded to fp@1727: the master by calling the \textit{ecdev\_link\_state()} function. The fp@1727: master then can react on this and warn the realtime module of a lost fp@1727: link. fp@1727: fp@1727: \begin{lstlisting}[language=C] fp@1727: void ecdev_link_state(ec_device_t *device, fp@1727: uint8_t new_state); fp@1727: \end{lstlisting} fp@1727: fp@1727: The parameter \textit{device} has to be a pointer to the device object fp@1727: returned by \textit{ecdev\_\-register()}. With the second parameter fp@1727: \textit{new\_state}, the new link state is passed: 1, if the link went fp@1727: up, and 0, if it went down. fp@1727: fp@1727: %------------------------------------------------------------------------------ fp@1727: fp@1727: \subsection{Patching Network Drivers} fp@1727: \label{sec:patching} fp@1727: \index{Network drivers} fp@1727: fp@1727: This section will demonstrate, how to make a standard Ethernet driver fp@1727: EtherCAT-capable. The below code examples are taken out of the fp@1727: modified RealTek RTL8139 driver coming with the EtherCAT master fp@1727: (\textit{devices/8139too.c}). The driver was originally developed by fp@1727: Donald Becker, and is currently maintained by Jeff Garzik. fp@1727: fp@1727: Unfortunately, there is no standard procedure to enable an Ethernet fp@1727: driver for use with the EtherCAT master, but there are a few common fp@1727: techniques, that are described in this section. fp@1727: fp@1727: \begin{enumerate} fp@1727: \item A first simple rule is, that \textit{netif\_*()}-calls must be fp@1727: strictly avoided for all EtherCAT devices. As mentioned before, fp@1727: EtherCAT devices have no connection to the network stack, and fp@1727: therefore must not call its interface functions. fp@1727: \item Another important thing is, that EtherCAT devices should be fp@1727: operated without interrupts. So any calls of registering interrupt fp@1727: handlers and enabling interrupts at hardware level must be avoided, fp@1727: too. fp@1727: \item The master does not use a new socket buffer for each send fp@1727: operation: Instead there is a fix one allocated on master fp@1727: initialization. This socket buffer is filled with an EtherCAT frame fp@1727: with every send operation and passed to the fp@1727: \textit{hard\_start\_xmit()} callback. For that it is necessary, fp@1727: that the socket buffer is not be freed by the network driver as fp@1727: usual. fp@1727: \end{enumerate} fp@1727: fp@1727: As mentioned before, the driver will handle both EtherCAT and ordinary fp@1727: Ethernet devices. This implies, that for each device-dependent fp@1727: operation, it has to be checked if an EtherCAT device is involved, or fp@1727: just an Ethernet device. For means of simplicity, this example driver fp@1727: will only handle one EtherCAT device. This makes the case fp@1727: differentiations easier. fp@1727: fp@1727: \paragraph{Global Variables} fp@1727: fp@1727: First of all, there have to be additional global variables declared, fp@1727: as shown in the listing: fp@1727: fp@1727: \begin{lstlisting}[language=C,numbers=left] fp@1727: static int ec_device_index = -1; fp@1727: static int ec_device_master_index = 0; fp@1727: static ec_device_t *rtl_ec_dev; fp@1727: struct net_device *rtl_ec_net_dev = NULL; fp@1727: \end{lstlisting} fp@1727: fp@1727: \begin{description} fp@1727: \item[\normalfont\textcircled{\tiny 1} -- \textcircled{\tiny 2}] To fp@1727: comply to the requirements for parameters of EtherCAT device modules fp@1727: described in section~\ref{sec:seldev}, there have to be additional fp@1727: parameter variables: \textit{ec\_\-device\_\-index} holds the index fp@1727: of the EtherCAT device and defaults to $-1$ (no EtherCAT device), fp@1727: while \textit{ec\_device\_master\_index} stores index of the master, fp@1727: the single device will be connected to. Default: $0$ fp@1727: \item[\normalfont\textcircled{\tiny 3}] \textit{rtl\_ec\_dev} will be fp@1727: the pointer to the later registered RealTek EtherCAT device, which fp@1727: can be used as a parameter for device methods. fp@1727: \item[\normalfont\textcircled{\tiny 4}] \textit{rtl\_ec\_net\_dev} is fp@1727: a pointer to the \textit{net\_device} structure of the dedicated fp@1727: device and is set while scanning the PCI bus and finding the device fp@1727: with the specified index. This is done inside the fp@1727: \textit{pci\_module\_init()} function executed as the first thing on fp@1727: module loading. fp@1727: \end{description} fp@1727: fp@1727: \paragraph{Module Initialization} fp@1727: fp@1727: Below is the (shortened) coding of the device driver's module init fp@1727: function: fp@1727: fp@1727: \begin{lstlisting}[language=C,numbers=left] fp@1727: static int __init rtl8139_init_module(void) fp@1727: { fp@1727: if (pci_module_init(&rtl8139_pci_driver) < 0) { fp@1727: printk(KERN_ERR "Failed to init PCI mod.\n"); fp@1727: goto out_return; fp@1727: } fp@1727: fp@1727: if (rtl_ec_net_dev) { fp@1727: printk(KERN_INFO "Registering" fp@1727: " EtherCAT device...\n"); fp@1727: if (!(rtl_ec_dev = fp@1727: ecdev_register(ec_device_master_index, fp@1727: rtl_ec_net_dev, fp@1727: rtl8139_interrupt, fp@1727: THIS_MODULE))) { fp@1727: printk(KERN_ERR "Failed to reg." fp@1727: " EtherCAT device!\n"); fp@1727: goto out_unreg_pci; fp@1727: } fp@1727: fp@1727: printk(KERN_INFO "Starting EtherCAT" fp@1727: " device...\n"); fp@1727: if (ecdev_start(ec_device_master_index)) { fp@1727: printk(KERN_ERR "Failed to start" fp@1727: " EtherCAT device!\n"); fp@1727: goto out_unreg_ec; fp@1727: } fp@1727: } else { fp@1727: printk(KERN_WARNING "No EtherCAT device" fp@1727: " registered!\n"); fp@1727: } fp@1727: fp@1727: return 0; fp@1727: fp@1727: out_unreg_ec: fp@1727: ecdev_unregister(ec_device_master_index, rtl_ec_dev); fp@1727: out_unreg_pci: fp@1727: pci_unregister_driver(&rtl8139_pci_driver); fp@1727: out_return: fp@1727: return -1; fp@1727: } fp@1727: \end{lstlisting} fp@1727: fp@1727: \begin{description} fp@1727: \item[\normalfont\textcircled{\tiny 3}] This call initializes all fp@1727: RTL8139-compatible devices found on the pci bus. If a device with fp@1727: index \textit{ec\_device\_index} is found, a pointer to its fp@1727: \textit{net\_device} structure is stored in fp@1727: \textit{rtl\_ec\_net\_dev} for later use (see next listings). fp@1727: \item[\normalfont\textcircled{\tiny 8}] If the specified device was fp@1727: found, \textit{rtl\_ec\_net\_dev} is non-zero. fp@1727: \item[\normalfont\textcircled{\tiny 11}] The device is connected to fp@1727: the specified master with a call to \textit{ecdev\_register()}. If fp@1727: this fails, module loading is aborted. fp@1727: \item[\normalfont\textcircled{\tiny 23}] The device registration was fp@1727: successful and the master is started. This can fail, which aborts fp@1727: module loading. fp@1727: \item[\normalfont\textcircled{\tiny 29}] If no EtherCAT device was fp@1727: found, a warning is output. fp@1727: \end{description} fp@1727: fp@1727: \paragraph{Device Searching} fp@1727: fp@1727: During the PCI initialization phase, a variable \textit{board\_idx} is fp@1727: increased for each RTL8139-compatible device found. The code below is fp@1727: executed for each device: fp@1727: fp@1727: \begin{lstlisting}[language=C,numbers=left] fp@1727: if (board_idx == ec_device_index) { fp@1727: rtl_ec_net_dev = dev; fp@1727: strcpy(dev->name, "ec0"); fp@1727: } fp@1727: \end{lstlisting} fp@1727: fp@1727: \begin{description} fp@1727: \item[\normalfont\textcircled{\tiny 1}] The device with the specified fp@1727: index will be the EtherCAT device. fp@1727: \end{description} fp@1727: fp@1727: \paragraph{Avoiding Device Registration} fp@1727: fp@1727: Later in the PCI initialization phase, the net\_devices get fp@1727: registered. This has to be avoided for EtherCAT devices and so this is fp@1727: a typical example for an EtherCAT case differentiation: fp@1727: fp@1727: \begin{lstlisting}[language=C,numbers=left] fp@1727: if (dev != rtl_ec_net_dev) { fp@1727: i = register_netdev(dev); fp@1727: if (i) goto err_out; fp@1727: } fp@1727: \end{lstlisting} fp@1727: fp@1727: \begin{description} fp@1727: \item[\normalfont\textcircled{\tiny 1}] If the current net\_device is fp@1727: not the EtherCAT device, it is registered at the network stack. fp@1727: \end{description} fp@1727: fp@1727: \paragraph{Avoiding Interrupt Registration} fp@1727: fp@1727: In the next two listings, there is an interrupt requested and the fp@1727: device's interrupts are enabled. This also has to be encapsulated by fp@1727: if-clauses, because interrupt operation is not wanted for EtherCAT fp@1727: devices. fp@1727: fp@1727: \begin{lstlisting}[language=C,numbers=left] fp@1727: if (dev != rtl_ec_net_dev) { fp@1727: retval = request_irq(dev->irq, rtl8139_interrupt, fp@1727: SA_SHIRQ, dev->name, dev); fp@1727: if (retval) return retval; fp@1727: } fp@1727: \end{lstlisting} fp@1727: fp@1727: \begin{lstlisting}[language=C,numbers=left] fp@1727: if (dev != rtl_ec_net_dev) { fp@1727: /* Enable all known interrupts by setting fp@1727: the interrupt mask. */ fp@1727: RTL_W16(IntrMask, rtl8139_intr_mask); fp@1727: } fp@1727: \end{lstlisting} fp@1727: fp@1727: \paragraph{Frame Sending} fp@1727: fp@1727: The listing below shows an exerpt of the function representing the fp@1727: \textit{hard\_start\_xmit()} callback of the net\_device. fp@1727: fp@1727: \begin{lstlisting}[language=C,numbers=left] fp@1727: /* Note: the chip doesn't have auto-pad! */ fp@1727: if (likely(len < TX_BUF_SIZE)) { fp@1727: if (len < ETH_ZLEN) fp@1727: memset(tp->tx_buf[entry], 0, ETH_ZLEN); fp@1727: skb_copy_and_csum_dev(skb, tp->tx_buf[entry]); fp@1727: if (dev != rtl_ec_net_dev) { fp@1727: dev_kfree_skb(skb); fp@1727: } fp@1727: } else { fp@1727: if (dev != rtl_ec_net_dev) { fp@1727: dev_kfree_skb(skb); fp@1727: } fp@1727: tp->stats.tx_dropped++; fp@1727: return 0; fp@1727: } fp@1727: \end{lstlisting} fp@1727: fp@1727: \begin{description} fp@1727: \item[\normalfont\textcircled{\tiny 6} + \textcircled{\tiny 10}] The fp@1727: master uses a fixed socket buffer for transmission, which is reused fp@1727: and may not be freed. fp@1727: \end{description} fp@1727: fp@1727: \paragraph{Frame Receiving} fp@1727: fp@1727: During ordinary frame reception, a socket buffer is created and filled fp@1727: with the received data. This is not necessary for an EtherCAT device: fp@1727: fp@1727: \begin{lstlisting}[language=C,numbers=left] fp@1727: if (dev != rtl_ec_net_dev) { fp@1727: /* Malloc up new buffer, compatible with net-2e. */ fp@1727: /* Omit the four octet CRC from the length. */ fp@1727: fp@1727: skb = dev_alloc_skb (pkt_size + 2); fp@1727: if (likely(skb)) { fp@1727: skb->dev = dev; fp@1727: skb_reserve(skb, 2); /* 16 byte align fp@1727: the IP fields. */ fp@1727: eth_copy_and_sum(skb, &rx_ring[ring_off + 4], fp@1727: pkt_size, 0); fp@1727: skb_put(skb, pkt_size); fp@1727: skb->protocol = eth_type_trans(skb, dev); fp@1727: fp@1727: dev->last_rx = jiffies; fp@1727: tp->stats.rx_bytes += pkt_size; fp@1727: tp->stats.rx_packets++; fp@1727: fp@1727: netif_receive_skb (skb); fp@1727: } else { fp@1727: if (net_ratelimit()) fp@1727: printk(KERN_WARNING fp@1727: "%s: Memory squeeze, dropping" fp@1727: " packet.\n", dev->name); fp@1727: tp->stats.rx_dropped++; fp@1727: } fp@1727: } else { fp@1727: ecdev_receive(rtl_ec_dev, fp@1727: &rx_ring[ring_offset + 4], pkt_size); fp@1727: dev->last_rx = jiffies; fp@1727: tp->stats.rx_bytes += pkt_size; fp@1727: tp->stats.rx_packets++; fp@1727: } fp@1727: \end{lstlisting} fp@1727: fp@1727: \begin{description} fp@1727: \item[\normalfont\textcircled{\tiny 28}] If the device is an EtherCAT fp@1727: device, no socket buffer is allocated. Instead a pointer to the data fp@1727: (which is still in the device's receive ring) is passed to the fp@1727: EtherCAT master. Unnecessary copy operations are avoided. fp@1727: \item[\normalfont\textcircled{\tiny 30} -- \textcircled{\tiny 32}] The fp@1727: device's statistics are updated as usual. fp@1727: \end{description} fp@1727: fp@1727: \paragraph{Link State} fp@1727: fp@1727: The link state (i.~e. if there is a carrier signal detected on the fp@1727: receive port) is determined during execution of the ISR. The listing fp@1727: below shows the different processing for Ethernet and EtherCAT fp@1727: devices: fp@1727: fp@1727: \begin{lstlisting}[language=C,numbers=left] fp@1727: if (dev != rtl_ec_net_dev) { fp@1727: if (tp->phys[0] >= 0) { fp@1727: mii_check_media(&tp->mii, netif_msg_link(tp), fp@1727: init_media); fp@1727: } fp@1727: } else { fp@1727: void __iomem *ioaddr = tp->mmio_addr; fp@1727: uint16_t link = RTL_R16(BasicModeStatus) fp@1727: & BMSR_LSTATUS; fp@1727: ecdev_link_state(rtl_ec_dev, link ? 1 : 0); fp@1727: } fp@1727: \end{lstlisting} fp@1727: fp@1727: \begin{description} fp@1727: \item[\normalfont\textcircled{\tiny 3}] The ``media check'' is done fp@1727: via the media independent interface (MII\nomenclature{MII}{Media fp@1727: Independent Interface}), a standard interface for Fast Ethernet fp@1727: devices. fp@1727: \item[\normalfont\textcircled{\tiny 7} -- \textcircled{\tiny 10}] For fp@1727: EtherCAT devices, the link state is fetched manually from the fp@1727: appropriate device register, and passed to the EtherCAT master by fp@1727: calling \textit{ecdev\_\-link\_\-state()}. fp@1727: \end{description} fp@1727: fp@1727: \paragraph{Module Cleanup} fp@1727: fp@1727: Below is the module's cleanup function: fp@1727: fp@1727: \begin{lstlisting}[language=C,numbers=left] fp@1727: static void __exit rtl8139_cleanup_module (void) fp@1727: { fp@1727: printk(KERN_INFO "Cleaning up RTL8139-EtherCAT" fp@1727: " module...\n"); fp@1727: fp@1727: if (rtl_ec_net_dev) { fp@1727: printk(KERN_INFO "Stopping device...\n"); fp@1727: ecdev_stop(ec_device_master_index); fp@1727: printk(KERN_INFO "Unregistering device...\n"); fp@1727: ecdev_unregister(ec_device_master_index, fp@1727: rtl_ec_dev); fp@1727: rtl_ec_dev = NULL; fp@1727: } fp@1727: fp@1727: pci_unregister_driver(&rtl8139_pci_driver); fp@1727: fp@1727: printk(KERN_INFO "RTL8139-EtherCAT module" fp@1727: " cleaned up.\n"); fp@1727: } fp@1727: \end{lstlisting} fp@1727: fp@1727: \begin{description} fp@1727: \item[\normalfont\textcircled{\tiny 6}] Stopping and unregistration is fp@1727: only done, if a device was registered before. fp@1727: \item[\normalfont\textcircled{\tiny 8}] The master is first stopped, fp@1727: so it does not access the device any more. fp@1727: \item[\normalfont\textcircled{\tiny 10}] After this, the device is fp@1727: unregistered. The master is now ``ophaned''. fp@1727: \end{description} fp@1727: fp@1727: %------------------------------------------------------------------------------ fp@1727: fp@1727: \section{The Master Module} fp@1727: \label{sec:mastermod} fp@1727: \index{Master module} fp@1727: fp@1727: The EtherCAT master is designed to run as a kernel module. Moreover fp@1727: the master kernel module \textit{ec\_master} can handle multiple fp@1727: masters at the same time: The number of masters has to be passed to fp@1727: the module with the parameter \textit{ec\_master\_count}, that fp@1727: defaults to $1$. A certain master can later be addressed by its index. fp@1727: For example, if the master module has been loaded with the command fp@1727: fp@1727: \begin{lstlisting} fp@1729: # `\textbf{modprobe ec\_master ec\_master\_count=2}` fp@1727: \end{lstlisting} fp@1727: fp@1727: the two masters can be addressed by their indices 0 and 1 respectively fp@1727: (see figure~\ref{fig:masters}). This master index mandatory for fp@1727: certain functions of the master interfaces. fp@1727: fp@1727: \begin{figure}[htbp] fp@1727: \centering fp@1727: \includegraphics[width=.5\textwidth]{images/masters} fp@1727: \caption{Multiple masters in one module} fp@1727: \label{fig:masters} fp@1727: \end{figure} fp@1727: fp@1727: \paragraph{Master Log Messages} fp@1727: fp@1727: The master module gives information about it's state and events via fp@1727: the syslog interface. The module loading command above should result fp@1732: in the syslog messages below (or similar): fp@1727: fp@1727: \begin{lstlisting} fp@1727: EtherCAT: Master driver, 1.1 (stable) - rev. 513, fp@1727: compiled by fp at Aug 09 2006 09:43:50 fp@1727: EtherCAT: Initializing 2 EtherCAT master(s)... fp@1727: EtherCAT: Initializing master 0. fp@1727: EtherCAT: Initializing master 1. fp@1727: EtherCAT: Master driver initialized. fp@1727: \end{lstlisting} fp@1727: fp@1727: The master provides information about it's version number, subversion fp@1727: revision number and compile information, like the date of compilation fp@1727: and the user, who compiled. All messages are prefixed either with fp@1727: \texttt{EtherCAT:}, \texttt{EtherCAT WARNING:} or \texttt{EtherCAT fp@1727: ERROR:}, which makes searching the logs easier. fp@1727: fp@1727: %------------------------------------------------------------------------------ fp@1727: fp@1727: \subsection{Class Reference} fp@1727: \label{sec:classes} fp@1727: fp@1727: This section is not intended to be a complete reference of master fp@1727: classes and functions\footnote{The comprehensive master reference can fp@1727: be obtained at http://etherlab.org/download/download-en.html}, but fp@1727: will give a general survey of the master's classes, and how they fp@1727: interact. fp@1727: fp@1727: Figure~\ref{fig:uml-all} shows an UML class diagram of the master fp@1727: classes. fp@1727: fp@1727: \begin{figure}[htbp] fp@1727: \centering fp@1727: \includegraphics[width=\textwidth]{images/uml-all} fp@1727: \caption{UML class diagram with associations} fp@1727: \label{fig:uml-all} fp@1727: \end{figure} fp@1727: fp@1727: The following subsections introduce serveral classes with their fp@1727: attributes and methods. fp@1727: fp@1727: %------------------------------------------------------------------------------ fp@1727: fp@1727: \subsubsection{The Master Class} fp@1727: \label{sec:class-master} fp@1727: \index{Master!Class} fp@1727: fp@1727: Figure~\ref{fig:uml-master} shows an UML class diagram of the master fp@1727: class. There is a short explanation of the attributes and methods fp@1727: below. fp@1727: fp@1727: \begin{figure}[htbp] fp@1727: \centering fp@1727: \includegraphics[width=.8\textwidth]{images/uml-master} fp@1727: \caption{Master UML class diagram} fp@1727: \label{fig:uml-master} fp@1727: \end{figure} fp@1727: fp@1727: \paragraph{Master Attributes} fp@1727: fp@1727: \begin{description} fp@1727: \item[list] is a listhead structure that is needed to manage the list fp@1727: of masters in the master module (see section~\ref{sec:mastermod}). fp@1727: \item[reserved] is a flag, that marks the master as reserved for a fp@1727: realtime module, so that a call to \textit{ecrt\_request\_master()} fp@1727: fails, if another module is already using the master. fp@1727: \item[index] contains the number of the master. The first master will fp@1727: get index 0, the second index 1, and so on. fp@1727: \item[kobj] In order to make the master object available via Sysfs fp@1727: (see section~\ref{sec:sysfs}), this structure is needed inside the fp@1727: master object (see section~\ref{sec:sysfs}). fp@1727: \item[slaves] is the list of slaves. It consists of objects of the fp@1727: \textit{ec\_slave\_t} class (see section~\ref{sec:class-slave}). fp@1727: \item[slave\_count] is the number of slaves in the list. fp@1727: \item[device] points to the network device that is used by the master fp@1727: to send and receive frames (see section~\ref{sec:class-device}). It fp@1727: is \textit{NULL}, if no device is connected. fp@1727: \item[datagram\_queue] is a list of datagrams (see fp@1727: section~\ref{sec:class-datagram}) that have to be sent by the fp@1727: master, or have already been sent and wait to be received again. fp@1727: Upon reception or error, the datagrams are dequeued. fp@1727: \item[datagram\_index] contains the index value for the next datagram. fp@1727: The master stores this incrementing index into every datagram, to fp@1727: make it easier to assign a received datagram to the one sent before. fp@1727: \item[domains] contains the list of domains created by the realtime fp@1727: module (section~\ref{sec:class-domain}). fp@1727: \item[debug\_level] controls, how much debugging output is printed by fp@1727: the master: 0 means no debugging output, 1 means to output certain fp@1727: executing marks and actions, and 2 means to output frame contents in fp@1727: addition. This value can be changed at runtime via the Sysfs fp@1727: interface (see section~\ref{sec:sysfs}). fp@1727: \item[stats] is a statistics object that contains certain counters fp@1727: (like the number of missed frames). These statistics are output on fp@1727: demand, but at most once a second. fp@1727: \item[workqueue] is the kernel workqueue used for idle mode. fp@1727: \item[idle\_work] is the work object, that is queued. fp@1727: \item[fsm] The attribute \textit{fsm} represents the master's finite fp@1727: state machine, that does all the slave processing. See fp@1727: sections~\ref{sec:class-fsm} and~\ref{sec:fsm} for further details. fp@1727: \item[mode] contains the current master mode, if it is orphaned, idle, fp@1727: or in operation mode. fp@1727: \item[eoe\_timer] is the kernel timer used for EoE\index{EoE} fp@1727: processing. fp@1727: \item[eoe\_running] marks the state of EoE processing. fp@1727: \item[eoe\_handlers] is the list of EoE handlers (see fp@1727: section~\ref{sec:class-eoe}). fp@1727: \item[internal\_lock] is a spinlock used in idle mode, that controls fp@1727: the concurrency of the idle and EoE processes. fp@1727: \item[request\_cb] The ``request lock'' callback function, the master fp@1727: has to provide for foreign instances, which want to access the fp@1727: master (see section~\ref{sec:concurr}). fp@1727: \item[release\_cb] The callback function that will release the master fp@1727: lock. fp@1727: \item[cb\_data] This value will be passed as an argument to each fp@1727: callback. fp@1727: \item[eeprom\_write\_enable] flag can be written via Sysfs to enable fp@1727: the general writing of E$^2$PROM contents. fp@1727: \end{description} fp@1727: fp@1727: \paragraph{Public Master Methods} fp@1727: fp@1727: \begin{description} fp@1727: \item[ec\_master\_init()] is the master's constructor. It initializes fp@1727: all attributes, creates the workqueue, creates EoE handlers and the fp@1727: state machine object, and adds the kernel object to the Sysfs fp@1727: hierarchy. fp@1727: \item[ec\_master\_clear()] is the destructor and undoes all these fp@1727: actions. fp@1727: \item[ec\_master\_reset()] clears the master, but initializes it fp@1727: again. This is needed, when a realtime module disconnects: Slaves fp@1727: and other attributes are cleared and are later rebuilt by the idle fp@1727: process. fp@1727: \item[ec\_master\_idle\_start/stop()] These methods enable or disable fp@1727: the idle process. fp@1727: \item[ec\_master\_eoe\_start/stop()] These methods do the same for the fp@1727: EoE timer. fp@1727: \item[ec\_master\_receive\_datagrams()] This method is called by the fp@1727: device, which uses it to pass received frames to the master. The fp@1727: frame is dissected and the contained datagrams are assigned to the fp@1727: datagram objects in the datagram queue, which are dequeued on fp@1727: reception or error. fp@1727: \item[ec\_master\_queue\_datagram()] This method is used to queue a fp@1727: new datagram for sending and receiving. fp@1727: \item[ec\_master\_output\_stats()] This method is cyclically called to fp@1727: output a summary of the \textit{stats} attribute at most once a fp@1727: second. fp@1727: \item[ec\_master\_clear\_slaves()] clears the list of slaves. This is fp@1727: needed on connection/disconnection of a realtime module or at a fp@1727: topology change in idle mode, when all slaves objects are rebuilt. fp@1727: \end{description} fp@1727: fp@1727: \paragraph{Private Master Methods} fp@1727: fp@1727: A few of a master's methods are private, meaning, that they can only fp@1727: be called from other master methods: fp@1727: fp@1727: \begin{description} fp@1727: \item[ec\_master\_send\_datagrams()] searches the datagram queue for fp@1727: unsent datagrams, allocates frames to send them, does the actual fp@1727: sending and marks the datagrams as sent. fp@1727: \item[ec\_master\_idle\_run()] is the work function for the idle mode. fp@1727: It executes the idle state machine, described in fp@1727: section~\ref{sec:fsm-idle}. fp@1727: \item[ec\_master\_eoe\_run()] is called by the EoE timer and is fp@1727: responsible for communicating with EoE-capable slaves. See fp@1727: section~\ref{sec:eoeimp} for more information. fp@1727: \end{description} fp@1727: fp@1727: \paragraph{Master Methods (Realtime Interface)} fp@1727: fp@1727: The master methods belonging to the Eth\-er\-CAT realtime fp@1727: interface\index{ecrt@\textit{ecrt}}\nomenclature{ecrt}{EtherCAT fp@1727: Realtime Interface} begin with the prefix \textit{ecrt} instead of fp@1727: \textit{ec}. The functions of the realtime interface are explained in fp@1727: section~\ref{sec:ecrt-master}. fp@1727: fp@1727: %------------------------------------------------------------------------------ fp@1727: fp@1727: \subsubsection{The Slave Class} fp@1727: \label{sec:class-slave} fp@1727: \index{Slave!Class} fp@1727: fp@1727: Figure~\ref{fig:uml-slave} shows an UML class diagram of the slave fp@1727: class. There is a short explanation of the attributes and methods fp@1727: below. fp@1727: fp@1727: \begin{figure}[htbp] fp@1727: \centering fp@1727: \includegraphics[width=.8\textwidth]{images/uml-slave} fp@1727: \caption{Slave UML class diagram} fp@1727: \label{fig:uml-slave} fp@1727: \end{figure} fp@1727: fp@1727: \paragraph{Slave Attributes} fp@1727: fp@1727: \begin{description} fp@1727: \item[list] The master holds a slave list, therefore the slave class fp@1727: must contain this structure used as an anchor for the linked fp@1727: list. fp@1727: \item[kobj] This pointer serves as base object for the slave's Sysfs fp@1727: representation. fp@1727: \item[master] is the pointer to the master owning this slave object. fp@1727: \item[ring\_position] is the logical position in the logical ring fp@1727: topology. fp@1727: \item[station\_address] is the configured station address. This is fp@1727: always the ring position~+~$1$). fp@1727: \item[coupler\_index] is the index of the last bus coupler. fp@1727: \item[coupler\_subindex] is the slave's position, counted from the fp@1727: last bus coupler. See section~\ref{sec:addr} for more information. fp@1727: \item[base\_*] These attributes contain base information about the fp@1727: slave, that are read from the ``DL Information'' attribute. fp@1727: \item[dl\_*] These fields store information of the ``DL Status'' fp@1727: attribute, for example states of the the communication ports. fp@1727: \item[sii\_*] These attributes contain values from the ``Slave fp@1727: Information Interface'' \cite[section~6.4]{dlspec}, mostly identity fp@1727: and mailbox information, but also the list of sync manager fp@1727: configurations and PDOs. fp@1727: \item[registered] This flag is set, if one or more PDOs of the slave fp@1727: have been registered for process data exchange. Otherwise a warning fp@1727: is output, because the slave is unused. fp@1727: \item[fmmus] Is an array of FMMU configurations, that have to be fp@1727: applied to the slave. fp@1727: \item[fmmu\_count] contains number of FMMUs used. fp@1727: \item[eeprom\_*] These fields contain E$^2$PROM contents and the fp@1727: extracted category information \cite[section~5.4]{alspec}. fp@1727: \item[new\_eeprom\_data] If this pointer is not \textit{NULL}, it fp@1727: points to new E$^2$PROM contents, that have to be written to the fp@1727: slave. fp@1727: \item[new\_eeprom\_size] This field represents the size of the new fp@1727: E$^2$PROM data. fp@1727: \item[requested\_state] is the requested slave state. fp@1727: \item[current\_state] is the current slave state. fp@1727: \item[error\_flag] is used by the operation and idle state machines fp@1727: to indicate, that a state transisition has failed and should not be fp@1727: tried again until an external event happens. fp@1727: \item[online] This flag contains the online state of the slave (i.~e. fp@1727: if it currently responds to the masters commands). Changes of the fp@1727: online state are always reported. fp@1727: \item[varsize\_fields] is only suitable for slaves that provide PDOs fp@1727: of variable size (like slaves that manage a sub-fieldbus) and fp@1727: contains information about what size this fields actually should fp@1727: have. fp@1727: \end{description} fp@1727: fp@1727: \paragraph{Public Slave Methods} fp@1727: fp@1727: \begin{description} fp@1727: \item[ec\_slave\_init()] The slave's constructor. fp@1727: \item[ec\_slave\_clear()] The slave's destructor. fp@1727: \item[ec\_prepare\_fmmu()] prepares an FMMU configuration. The FMMU is fp@1727: configured for a certain sync manager and domain. fp@1727: \item[ec\_fetch\_*()] Serveral methods to extract information of the fp@1727: E$^2$PROM category contents. fp@1727: \item[ec\_slave\_locate\_string()] extracts a string out of a STRING fp@1727: category and allocates string memory. fp@1727: \item[ec\_slave\_calc\_sync\_size()] calculates the size of sync fp@1727: manager contents, because they can be variable due to variable-sized fp@1727: PDOs. fp@1727: \item[ec\_slave\_info()] This method prints all slave information into fp@1727: a buffer for Sysfs reading. fp@1727: \item[ec\_slave\_mbox\_*()] These functions prepare datagrams for fp@1727: mailbox communication, or process mailbox responses, respectively. fp@1727: \end{description} fp@1727: fp@1727: \paragraph{Private Slave Methods} fp@1727: fp@1727: \begin{description} fp@1727: \item[ec\_slave\_write\_eeprom()] This function accepts E$^2$PROM data fp@1727: from user space, does a quick validation of the contents and fp@1727: schedules them for writing through the idle state machine. fp@1727: \end{description} fp@1727: fp@1727: \paragraph{Slave Methods (Realtime Interface)} fp@1727: fp@1727: \begin{description} fp@1727: \item[ecrt\_slave\_conf\_sdo*()] These methods accept SDO fp@1727: configurations, that are applied on slave activation (i.~e. fp@1727: everytime the slave is configured). The methods differ only in the fp@1727: data size of the SDO (8, 16 or 32 bit). fp@1727: \item[ecrt\_slave\_pdo\_size()] This method specifies the size of a fp@1727: variable-sized PDO. fp@1727: \end{description} fp@1727: fp@1727: %------------------------------------------------------------------------------ fp@1727: fp@1727: \subsubsection{The Device Class} fp@1727: \label{sec:class-device} fp@1727: \index{Device!Class} fp@1727: fp@1727: The device class is responsible for communicating with the connected fp@1727: EtherCAT-enabled network driver. Figure~\ref{fig:uml-device} shows its fp@1727: UML class diagram. fp@1727: fp@1727: \begin{figure}[htbp] fp@1727: \centering fp@1727: \includegraphics[width=.3\textwidth]{images/uml-device} fp@1727: \caption{Device UML class diagram} fp@1727: \label{fig:uml-device} fp@1727: \end{figure} fp@1727: fp@1727: \paragraph{Device Attributes} fp@1727: fp@1727: \begin{description} fp@1727: \item[master] A pointer to the master, which owns the device object. fp@1727: \item[dev] This is the pointer to the \textit{net\_device} structure fp@1727: of the connected network device driver. fp@1727: \item[open] This flag stores, if the network device is ``opened'' and fp@1727: ready for transmitting and receiving frames. fp@1727: \item[tx\_skb] The transmittion socket buffer. Instead of allocating a fp@1727: new socket buffer for each frame, the same socket buffer is recycled fp@1727: and used for every frame. fp@1727: \item[isr] The pointer to the network device's interrupt service fp@1727: routine. \textit{ec\_isr\_t} is a type definition in the device fp@1727: interface, which looks like below: fp@1727: \begin{lstlisting}[gobble=4,language=C] fp@1727: typedef irqreturn_t (*ec_isr_t)(int, void *, fp@1727: struct pt_regs *); fp@1727: \end{lstlisting} fp@1727: \item[module] A pointer to the network driver module, to increase and fp@1727: decrease the use counter (see paragraph ``Implicit Dependencies'' in fp@1727: section~\ref{sec:ecdev}). fp@1727: \item[link\_state] The current link state. It can be 0 ``down'' or 1 fp@1727: ``up''. fp@1727: \item[dbg] Every device objects contains a debugging interface (see fp@1727: sectios~\ref{sec:class-debug} and~\ref{sec:debug}). fp@1727: \end{description} fp@1727: fp@1727: \paragraph{Public Device Methods} fp@1727: fp@1727: \begin{description} fp@1727: \item[ec\_device\_init()] The device constructor. fp@1727: \item[ec\_device\_clear()] The device destructor. fp@1727: \item[ec\_device\_open()] ``Opens'' the device for transmittion and fp@1727: reception of frames. This is equivalent to the \textit{ifconfig up} fp@1727: command for ordinary Ethernet devices. fp@1727: \item[ec\_device\_close()] Stops frame transmittion and reception. fp@1727: This is equivalent to the \textit{ifconfig down} command for fp@1727: ordinary Ethernet devices. fp@1727: \item[ec\_device\_call\_isr()] Calls the interrupt service routine of fp@1727: the device. fp@1727: \item[ec\_device\_tx\_data()] Returns a pointer into the memory of the fp@1727: transmittion socket buffer \textit{tx\_skb}. This is used by the fp@1727: master to assemble a new EtherCAT frame. fp@1727: \item[ec\_device\_send()] Sends an assembled frame by passing it to fp@1727: the device's \textit{hard\_\-start\_\-xmit()} callback. fp@1727: \end{description} fp@1727: fp@1727: \paragraph{Device Methods (Device Interface)} fp@1727: fp@1727: The device methods belonging to the device interface are explained in fp@1727: section~\ref{sec:ecdev}. fp@1727: fp@1727: %------------------------------------------------------------------------------ fp@1727: fp@1727: \subsubsection{The Datagram Class} fp@1727: \label{sec:class-datagram} fp@1727: \index{Datagram!Class} fp@1727: fp@1727: So send and receive a datagram, an object of the fp@1727: \textit{ec\_datagram\_t} class is needed. It can be initialized with a fp@1727: datagram type \cite[section~5.4]{dlspec} and length (optionally filled fp@1727: with data) and appended to the master's datagram queue. fp@1727: Figure~\ref{fig:uml-datagram} shows its UML class diagram. fp@1727: fp@1727: \begin{figure}[htbp] fp@1727: \centering fp@1727: \includegraphics[width=.3\textwidth]{images/uml-datagram} fp@1727: \caption{Datagram UML class diagram} fp@1727: \label{fig:uml-datagram} fp@1727: \end{figure} fp@1727: fp@1727: \paragraph{Datagram Attributes} fp@1727: fp@1727: \begin{description} fp@1727: \item[list] This attribute is needed to make a list of datagrams, as fp@1727: used in the domain class (see section~\ref{sec:class-domain}). fp@1727: \item[queue] This attribute is the anchor to the master's datagram fp@1727: queue, which is implemented as a linked list. fp@1727: \item[type] The datagram type. \textit{ec\_\-datagram\_\-type\_\-t} is fp@1727: an enumeration, which can have the values fp@1727: \textit{EC\_\-DATAGRAM\_\-APRD}, \textit{EC\_\-DATAGRAM\_\-APWR}, fp@1727: \textit{EC\_\-DATAGRAM\_\-NPRD}, \textit{EC\_\-DATAGRAM\_\-NPWR}, fp@1727: \textit{EC\_\-DATAGRAM\_\-BRD}, \textit{EC\_\-DATAGRAM\_\-BWR} or fp@1727: \textit{EC\_\-DATAGRAM\_\-LRW}. fp@1727: \item[address] The slave address. For all addressing schemes take 4 fp@1727: bytes, \textit{ec\_address\_t} is a union type: fp@1727: \begin{lstlisting}[gobble=4,language=C] fp@1727: typedef union { fp@1727: struct { fp@1727: uint16_t slave; /**< configured or fp@1727: autoincrement fp@1727: address */ fp@1727: uint16_t mem; /**< physical memory fp@1727: address */ fp@1727: } physical; /**< physical address */ fp@1727: uint32_t logical; /**< logical address */ fp@1727: } ec_address_t; fp@1727: \end{lstlisting} fp@1727: \item[data] The actual data of the datagram. These are either filled fp@1727: in before sending (at writing access) or are inserted by the fp@1727: adressed slave(s) (at reading access). In any case, the data memory fp@1727: must be dynamically allocated. Besides, this can be done before fp@1727: cyclic processing with the \textit{ec\_datagram\_prealloc()} method fp@1727: (see below). fp@1727: \item[mem\_size] The size of the allocated memory, \textit{data} fp@1727: points to. fp@1727: \item[data\_size] The size of the actual data in the \textit{data} fp@1727: memory. fp@1727: \item[index] The sequential EtherCAT datagram index. This value is set fp@1727: by the master on sending, to easier assign a received datagram to a fp@1727: queued datagram object. fp@1727: \item[working\_counter] The working counter of the datagram. This is fp@1727: set to zero on sending and filled with the real value of the working fp@1727: counter on datagram reception. fp@1727: \item[state] The state of the datagram. fp@1727: \textit{ec\_\-datagram\_\-state\_\-t} is an enumeration and can be fp@1727: \textit{EC\_\-DATA\-GRAM\_\-INIT}, fp@1727: \textit{EC\_\-DATA\-GRAM\_\-QUEU\-ED}, fp@1727: \textit{EC\_\-DATA\-GR\-AM\_\-SEN\-T}, fp@1727: \textit{EC\_\-DATA\-GRAM\_\-REC\-EIVED}, fp@1727: \textit{EC\_\-DATA\-GRAM\_\-TIMED\_\-OUT} or fp@1727: \textit{EC\_\-DA\-TA\-GRAM\_\-ERR\-OR}. fp@1727: \item[t\_sent] This attribute is set to the timestamp, when the fp@1727: datagram was sent, to later detect a timeout. fp@1727: \end{description} fp@1727: fp@1727: \paragraph{Public Datagram Methods} fp@1727: fp@1727: \begin{description} fp@1727: \item[ec\_datagram\_init()] The datagram's constructor. fp@1727: \item[ec\_datagram\_clear()] The datagram's destructor. fp@1727: \item[ec\_datagram\_prealloc()] Allocates memory for the datagram fp@1727: data. This is especially needed, if the datagram structure will fp@1727: later be used in a context, where no dynamic memory allocation is fp@1727: allowed. fp@1727: \item[ec\_datagram\_nprd()] Initializes a ``Node-Addressed Physical fp@1727: Read'' datagram \cite[section~5.4.1.2]{dlspec}. fp@1727: \item[ec\_datagram\_npwr()] Initializes a ``Node-Addressed Physical fp@1727: Write'' datagram \cite[section~5.4.2.2]{dlspec}. fp@1727: \item[ec\_datagram\_aprd()] Initializes a ``Auto-Increment Physical fp@1727: Read'' datagram \cite[section~5.4.1.1]{dlspec}. fp@1727: \item[ec\_datagram\_apwr()] Initializes a ``Auto-Increment Physical fp@1727: Write'' datagram \cite[section~5.4.2.1]{dlspec}. fp@1727: \item[ec\_datagram\_brd()] Initializes a ``Broadcast Read'' datagram fp@1727: \cite[section~5.4.1.3]{dlspec}. fp@1727: \item[ec\_datagram\_bwr()] Initializes a ``Broadcast Write'' datagram fp@1727: \cite[section~5.4.2.3]{dlspec}. fp@1727: \item[ec\_datagram\_lrw()] Initializes a ``Logical ReadWrite'' fp@1727: datagram \cite[section~5.4.3.4]{dlspec}. fp@1727: \end{description} fp@1727: fp@1727: %------------------------------------------------------------------------------ fp@1727: fp@1727: \subsubsection{The Domain Class} fp@1727: \label{sec:class-domain} fp@1727: \index{Domain!Class} fp@1727: fp@1727: The domain class encapsules PDO registration and management of the fp@1727: process data image and its exchange. The UML class diagram can be seen fp@1727: in figure~\ref{fig:uml-domain}. fp@1727: fp@1727: \begin{figure}[htbp] fp@1727: \centering fp@1727: \includegraphics[width=.4\textwidth]{images/uml-domain} fp@1727: \caption{Domain UML class diagram} fp@1727: \label{fig:uml-domain} fp@1727: \end{figure} fp@1727: fp@1727: \paragraph{Domain Attributes} fp@1727: fp@1727: \begin{description} fp@1727: \item[kobj] This \textit{kobject} structure is needed for the Sysfs fp@1727: representation of the domain. fp@1727: \item[list] The master manages a list of domains, so this list anchor fp@1727: is needed. fp@1727: \item[index] The domain's index. The first domain will get index 0, fp@1727: the second index 1, and so on. fp@1727: \item[master] A pointer to the master owning the domain. fp@1727: \item[data\_size] The size of the domain's process data image. fp@1727: \item[datagram] A linked list with the datagram objects, the domain fp@1727: needs for process data exchange (see fp@1727: section~\ref{sec:class-datagram}). fp@1727: \item[base\_address] This attribute stores the logical offset, to fp@1727: which the domain's process data are mapped. fp@1727: \item[response\_count] The sum of the datagrams' working counters at fp@1727: the last process data exchange. Changes are always reported. fp@1727: \item[data\_regs] The (linked) list of PDO registrations. The realtime fp@1727: module requests the exchange of certain PDOs and supplies the fp@1727: address of process data pointers, that will later point to the fp@1727: respective locations in the process data image. These ``data fp@1727: registrations'' are saved in the \textit{data\_regs} list. fp@1727: \item[working\_counter\_changes] This field stores the number of fp@1727: working counter changes since the last notification. This helps to fp@1727: reduce syslog output in case of frequent changes. fp@1727: \item[t\_last] The timestamp of the last working counter change fp@1727: notification. fp@1727: \end{description} fp@1727: fp@1727: \paragraph{Public Domain Methods} fp@1727: fp@1727: \begin{description} fp@1727: \item[ec\_domain\_init()] The domain's constructor. fp@1727: \item[ec\_domain\_clear()] The domain's destructor. fp@1727: \item[ec\_domain\_alloc()] Allocates the process data image and the fp@1727: respective datagrams based on the process data registrations. fp@1727: \item[ec\_domain\_queue()] Queues the domain's datagrams for exchange fp@1727: via the master. fp@1727: \end{description} fp@1727: fp@1727: \paragraph{Private Domain Methods} fp@1727: fp@1727: \begin{description} fp@1727: \item[ec\_domain\_reg\_pdo\_entry()] This method is used to do a PDO fp@1727: registration. It finds the appropriate sync manager covering the PDO fp@1727: data, calculates its offset in the sync-manager-protected memory and fp@1727: prepares the FMMU configurations for the related slave. Then the PDO fp@1727: registration is appended to the list. fp@1727: \item[ec\_domain\_clear\_data\_regs()] Clearing all process data fp@1727: registrations is needed in serveral places and therefore has been fp@1727: sourced out to an own method. fp@1727: \item[ec\_domain\_add\_datagram()] This methods allocates a datagram fp@1727: and appends it to the list. This is done during domain allocation. fp@1727: \end{description} fp@1727: fp@1727: \paragraph{Domain Methods (Realtime Interface)} fp@1727: fp@1727: The domain methods belonging to the realtime interface are introduced fp@1727: in section~\ref{sec:ecrt-domain}. fp@1727: fp@1727: %------------------------------------------------------------------------------ fp@1727: fp@1727: \subsubsection{The Finite State Machine Class} fp@1727: \label{sec:class-fsm} fp@1727: \index{FSM!Class} fp@1727: fp@1727: This class encapsules all state machines, except the EoE state fp@1727: machine. Its UML class diagram can be seen in fp@1727: figure~\ref{fig:uml-fsm}. fp@1727: fp@1727: \begin{figure}[htbp] fp@1727: \centering fp@1727: \includegraphics[width=.9\textwidth]{images/uml-fsm} fp@1727: \caption{Finite State Machine UML class diagram} fp@1727: \label{fig:uml-fsm} fp@1727: \end{figure} fp@1727: fp@1727: \paragraph{FSM Attributes} fp@1727: fp@1727: \begin{description} fp@1727: \item[master] A pointer to the master owning the FSM object. fp@1727: \item[slave] Serveral sub state machines are executed for single fp@1727: slaves. This pointer stores the current slave for these FSMs. fp@1727: \item[datagram] The FSM class has its own datagram, which is used in fp@1727: every state and sub-state. fp@1727: \item[master\_state] This function pointer stores the current state fp@1727: function for one of the master's state machines. fp@1727: \item[master\_slaves\_responding] This attribute is used in the fp@1727: operation state machine (see section~\ref{sec:fsm-op}) to store the fp@1727: number of slaves, that responded to the last broadcast command. fp@1727: \item[master\_slave\_states] This attribute stores the slave states, fp@1727: that were determined by the last broadcast command. fp@1727: \item[master\_validation] This flag is used by the operation state fp@1727: machine and is non-zero, if a bus validation has to be done. fp@1727: \item[slave\_state] This function pointer stores the current state of fp@1727: the slave scan state machine (see section~\ref{sec:fsm-scan}) or the fp@1727: slave configuration state machine (see section~\ref{sec:fsm-conf}). fp@1727: \item[sii\_state] This function pointer stores the current state of fp@1727: the SII state machine (see section~\ref{sec:fsm-sii}). fp@1727: \item[sii\_offset] This attribute is used by the SII state machine to fp@1727: store the word address for the current read or write cycle. fp@1727: \item[sii\_mode] If this attribute is zero, the SII access is done fp@1727: with ``auto-increment'' datagrams \cite[section~5.4]{dlspec}. fp@1727: If it is non-zero, ``station-address'' datagrams are used. fp@1727: \item[sii\_value] This attribute stores the value to write, or the fp@1727: read value, respectively. fp@1727: \item[sii\_start] A timestamp attribute, that stores the beginning fp@1727: time of an SII operation to detect a timeout. fp@1727: \item[change\_state] This function pointer stores the current state of fp@1727: the state change state machine. fp@1727: \item[change\_new] This attribute stores the requested state for the fp@1727: state change state machine. fp@1727: \item[change\_start] A timestamp attribute to detect a timeout while fp@1727: changing slave states. fp@1727: \item[coe\_state] This function pointer stores the current state of fp@1727: the CoE state machines. fp@1727: \item[sdodata] This is an SDO data object that stores information fp@1727: about the current SDO to write. fp@1727: \item[coe\_start] A timestamp attribute to detect timeouts during CoE fp@1727: configuration. fp@1727: \end{description} fp@1727: fp@1727: \paragraph{Public FSM Methods} fp@1727: fp@1727: \begin{description} fp@1727: \item[ec\_fsm\_init()] Constructor of the FSM class. fp@1727: \item[ec\_fsm\_clear()] Destructor of the FSM class. fp@1727: \item[ec\_fsm\_reset()] Resets the whole FSM object. This is needed to fp@1727: restart the master state machines. fp@1727: \item[ec\_fsm\_execute()] Executes one state of the current state fp@1727: machine and then returns. fp@1727: \item[ec\_fsm\_startup()] Initializes the master startup state fp@1727: machine, which determines the number of slaves and executes the fp@1727: slave scan state machine for each slave. fp@1727: \item[ec\_fsm\_startup\_running()] Returns non-zero, if the startup fp@1727: state machine did not terminate yet. fp@1727: \item[ec\_fsm\_startup\_success()] Returns non-zero, if the startup fp@1727: state machine terminated with success. fp@1727: \item[ec\_fsm\_configuration()] Initializes the master configuration fp@1727: state machine, which executes the slave configuration state machine fp@1727: for each slave. fp@1727: \item[ec\_fsm\_configuration\_running()] Returns non-zero, if the fp@1727: configuration state machine did not terminate yet. fp@1727: \item[ec\_fsm\_configuration\_success()] Returns non-zero, if the fp@1727: configuration state machine terminated with success. fp@1727: \end{description} fp@1727: fp@1727: \paragraph{FSM State Methods} fp@1727: fp@1727: The rest of the methods showed in the UML class diagram are state fp@1727: methods of the state machines. These states are described in fp@1727: section~\ref{sec:fsm}. fp@1727: fp@1727: %------------------------------------------------------------------------------ fp@1727: fp@1727: \subsubsection{The EoE Class} fp@1727: \label{sec:class-eoe} fp@1727: \index{EoE!Class} fp@1727: fp@1727: Objects of the \textit{ec\_eoe\_t} class are called EoE handlers. Each fp@1727: EoE handler represents a virtual network interface and can be coupled fp@1727: to a EoE-capable slave on demand. The UML class diagram can be seen in fp@1727: figure~\ref{fig:uml-eoe}. fp@1727: fp@1727: \begin{figure}[htbp] fp@1727: \centering fp@1727: \includegraphics[width=.4\textwidth]{images/uml-eoe} fp@1727: \caption{EoE UML class diagram} fp@1727: \label{fig:uml-eoe} fp@1727: \end{figure} fp@1727: fp@1727: \paragraph{EoE Attributes} fp@1727: fp@1727: \begin{description} fp@1727: \item[list] The master class maintains a list of EoE handlers. fp@1727: Therefore this list anchor is needed. fp@1727: \item[slave] If an EoE handler is coupled to a slave, this pointer fp@1727: points to the related slave object. Otherwise it is \textit{NULL}. fp@1727: \item[datagram] Every EoE handler owns a datagram object to exchange fp@1727: data with the coupled slave via its state machine. fp@1727: \item[state] This function pointer points to the current state of the fp@1727: EoE state machine (see section~\ref{sec:eoeimp}). fp@1727: \item[dev] A pointer to the \textit{net\_device} structure that fp@1727: represents the network interface to the kernel. fp@1727: \item[stats] The statistics object for the network interface. fp@1727: \item[opened] This flag stores, if the network interface was opened. fp@1727: No EoE processing will be done, if the device is not opened. fp@1727: \item[t\_last] This timestamp attribute stores the time of the last fp@1727: bit rate measurement. fp@1727: \item[rx\_skb] A pointer to the current receive socket buffer. On fp@1727: every first fragment of a received frame, a new receive socket fp@1727: buffer is allocated. On every last fragment, this buffer will be fp@1727: passed to the network stack. fp@1727: \item[rx\_skb\_offset] This attribute stores the offset for the next fp@1727: fragment data in the receive socket buffer. fp@1727: \item[rx\_skb\_size] This attribute stores the current data size of fp@1727: the receive socket buffer. fp@1727: \item[rx\_expected\_fragment] The expected number of the next fp@1727: fragment. If a fragment with an invalid number is received, the fp@1727: whole frame will be dropped. fp@1727: \item[rx\_counter] This is the sum of the octets received since the fp@1727: last bit rate measurement. fp@1727: \item[rx\_rate] This attribute stores the receive bit rate in bps. fp@1727: \item[tx\_queue] Each EoE handler maintains a transmittion queue for fp@1727: frames, that come in via the network interface. This queue is fp@1727: implemented with a linked list and protected by a spinlock. fp@1727: \item[tx\_queue\_active] This flag stores, if the transmittion queue fp@1727: is currently accepting frames from the network stack. If the queue fp@1727: gets filled up, frame transmittion is suspended with a call to fp@1727: \textit{netif\_stop\_queue()}. If the fill state decreases below the fp@1727: half capacity, frame transmittion is restarted with fp@1727: \textit{netif\_wake\_queue()}. fp@1727: \item[tx\_queued\_frames] The number of frames in the transmittion fp@1727: queue. fp@1727: \item[tx\_queue\_lock] The spinlock used to protect the transmittion fp@1727: queue. This is needed, because the queue is accessed both from fp@1727: network stack context and from the master's EoE timer. fp@1727: \item[tx\_frame] The frame that is currently sent. The fp@1727: \textit{ec\_eoe\_frame\_t} structure combines the socket buffer fp@1727: structure with a list head to append it to the transmittion queue. fp@1727: \item[tx\_frame\_number] The EoE protocol demands to maintain a fp@1727: sequencial frame number, that must be increased with every frame fp@1727: sent. fp@1727: \item[tx\_fragment\_number] The sequencial number of the next fragment fp@1727: to transmit. fp@1727: \item[tx\_offset] Current frame data offset for the next fragment to fp@1727: transmit. fp@1727: \item[tx\_counter] The number of octets transferred since the last bit fp@1727: rate measurement. fp@1727: \item[tx\_rate] The recent transmittion bit rate in bps. fp@1727: \end{description} fp@1727: fp@1727: \paragraph{Public EoE Methods} fp@1727: fp@1727: \begin{description} fp@1727: \item[ec\_eoe\_init()] The EoE handler's constructor. The network fp@1727: interface is allocated and registered. fp@1727: \item[ec\_eoe\_clear()] The EoE handler's destructor. The network fp@1727: interface is unregistered and all allocated memory is freed. fp@1727: \item[ec\_eoe\_run()] Executes the EoE state machine (see fp@1727: section~\ref{sec:eoeimp}) for this handler. fp@1727: \item[ec\_eoe\_active()] Returns true, if the handler has a slave fp@1727: coupled and the network interface is opened. fp@1727: \end{description} fp@1727: fp@1727: \paragraph{Private EoE Methods} fp@1727: fp@1727: \begin{description} fp@1727: \item[ec\_eoe\_flush()] Clears the transmittion queue and drops all fp@1727: frames queued for sending. fp@1727: \item[ec\_eoe\_send()] Sends one fragment of the current frame. fp@1727: \end{description} fp@1727: fp@1727: fp@1727: \paragraph{EoE State Methods} fp@1727: fp@1727: The rest of the private methods are state functions for the EoE state fp@1727: machine, which is discussed in section~\ref{sec:eoeimp}. fp@1727: fp@1727: %------------------------------------------------------------------------------ fp@1727: fp@1727: \subsubsection{The Debug Class} fp@1727: \label{sec:class-debug} fp@1727: fp@1727: The debug class maintains a virtual network interface. All frames that fp@1727: are sent and received by the master will be forwarded to this network fp@1727: interface, so that bus monitoring can be done with third party tools fp@1727: (see section~\ref{sec:debug}). Figure~\ref{fig:uml-debug} shows the fp@1727: UML class diagram. fp@1727: fp@1727: \begin{figure}[htbp] fp@1727: \centering fp@1727: \includegraphics[width=.3\textwidth]{images/uml-debug} fp@1727: \caption{Debug UML class diagram} fp@1727: \label{fig:uml-debug} fp@1727: \end{figure} fp@1727: fp@1727: \paragraph{Debug Attributes} fp@1727: fp@1727: \begin{description} fp@1727: \item[dev] A pointer to the allocated \textit{net\_device} structure fp@1727: that represents the network interface in the kernel. fp@1727: \item[stats] An object for interface statistics. fp@1727: \item[opened] Stores the state of the device. Frames will only be fp@1727: forwarded, if the device was opened with the \textit{ifconfig up} fp@1727: command (or something similar). fp@1727: \end{description} fp@1727: fp@1727: \paragraph{Public Debug Methods} fp@1727: fp@1727: \begin{description} fp@1727: \item[ec\_debug\_init()] The constructor. fp@1727: \item[ec\_debug\_clear()] The destructor. fp@1727: \item[ec\_debug\_send()] This method forwards a frame to the virtual fp@1727: network interface. It dynamically allocates a new socket buffer and fp@1727: passes it to the network stack. fp@1727: \end{description} fp@1727: fp@1727: %------------------------------------------------------------------------------ fp@1727: fp@1727: \subsection{The Realtime Interface} fp@1727: \label{sec:ecrt} fp@1727: \index{Realtime interface} fp@1727: fp@1727: The realtime interface provides functions and data structures for fp@1727: realtime modules to access and use an EtherCAT master. fp@1727: fp@1727: \subsubsection{Master Requesting and Releasing} fp@1727: fp@1727: Before a realtime module can access am EtherCAT master provided by the fp@1727: master module, it has to reserve one for exclusive use. After use, it fp@1727: has to release the requested master and make it available for other fp@1727: modules. This is done with the following functions: fp@1727: fp@1727: \begin{lstlisting}[language=C] fp@1727: ec_master_t *ecrt_request_master(unsigned int master_index); fp@1727: void ecrt_release_master(ec_master_t *master); fp@1727: \end{lstlisting} fp@1727: fp@1727: The \textit{ecrt\_request\_master()} function has to be the first fp@1727: function a module has to call, when using EtherCAT. The function takes fp@1727: the index of the master as its argument. The first master has index 0, fp@1727: the $n$th master has index $n - 1$. The number of existent masters has fp@1727: to be specified when loading the master module (see fp@1727: section~\ref{sec:mastermod}). The function tries to reserve the fp@1727: specified master and scans for slaves. It returns a pointer to the fp@1727: reserved master object upon success, or \textit{NULL} if an error fp@1727: occured. fp@1727: fp@1727: The \textit{ecrt\_release\_master()} function releases a reserved fp@1727: master after use. It takes the pointer to the master object returned fp@1727: by \textit{ecrt\_request\_master()} as its argument and can never fp@1727: fail. fp@1727: fp@1727: \subsubsection{Master Methods} fp@1727: \label{sec:ecrt-master} fp@1727: fp@1727: \paragraph{Domain Creation} fp@1727: fp@1727: For process data exchange, at least one process data domain is needed fp@1727: (see section~\ref{sec:processdata}). fp@1727: fp@1727: \begin{lstlisting}[language=C] fp@1727: ec_domain_t *ecrt_master_create_domain(ec_master_t *master); fp@1727: \end{lstlisting} fp@1727: fp@1727: The \textit{ecrt\_master\_create\_domain()} method creates a new fp@1727: process data domain and returns a pointer to the new domain object. fp@1727: This object can be used for registering process data objects and fp@1727: exchange process data in cyclic operation. On failure, the function fp@1727: returns \textit{NULL}. fp@1727: fp@1727: \paragraph{Slave Handlers} fp@1727: fp@1727: To access a certain slave, there is a method to get a slave handler: fp@1727: fp@1727: \begin{lstlisting}[language=C] fp@1727: ec_slave_t *ecrt_master_get_slave(const ec_master_t *, fp@1727: const char *); fp@1727: \end{lstlisting} fp@1727: fp@1727: The \textit{ecrt\_master\_get\_slave()} method returns a pointer to a fp@1727: certain slave object, specified by its ASCII address (see fp@1727: section~\ref{sec:addr}). If the address is invalid, \textit{NULL} is fp@1727: returned. fp@1727: fp@1727: \paragraph{Master Activation} fp@1727: fp@1727: When all domains are created, and all process data objects are fp@1727: registered, the master can be activated: fp@1727: fp@1727: \begin{lstlisting}[language=C] fp@1727: int ecrt_master_activate(ec_master_t *master); fp@1727: void ecrt_master_deactivate(ec_master_t *master); fp@1727: \end{lstlisting} fp@1727: fp@1727: By calling the \textit{ecrt\_master\_activate()} method, all slaves fp@1727: are configured according to the prior method calls and are brought fp@1729: into OP state. In this case, the method has a return value of 0. fp@1729: Otherwise (wrong configuration or bus failure) the method returns fp@1727: non-zero. fp@1727: fp@1727: The \textit{ecrt\_master\_deactivate()} method is the counterpart to fp@1729: the activate call: It brings all slaves back into INIT state again. fp@1729: This method should be called prior to fp@1727: \textit{ecrt\_\-master\_\-release()}. fp@1727: fp@1727: \paragraph{Locking Callbacks} fp@1727: fp@1727: For concurrent master access, the realtime module has to provide a fp@1727: locking mechanism (see section~\ref{sec:concurr}): fp@1727: fp@1727: \begin{lstlisting}[language=C] fp@1727: void ecrt_master_callbacks(ec_master_t *master, fp@1727: int (*request_cb)(void *), fp@1727: void (*release_cb)(void *), fp@1727: void *cb_data); fp@1727: \end{lstlisting} fp@1727: fp@1727: The ``request lock'' and ``release lock'' callbacks can be set with fp@1727: the \textit{ecrt\_master\_call\-backs()} method. It takes two function fp@1727: pointers and a data value as additional arguments. The arbitrary data fp@1727: value will be passed as argument on every callback. Asynchronous fp@1727: master access (like EoE processing) is only possible if these fp@1727: callbacks have been set. fp@1727: fp@1727: \paragraph{Preparation of Cyclic Data Exchange} fp@1727: fp@1727: Cyclic operation mostly consists of the three steps input, processing fp@1727: and output. In EtherCAT terms this would mean: Receive datagrams, fp@1727: evaluate process data and send datagrams. The first cycle differs from fp@1727: this principle, because no datagrams have been sent yet, so there is fp@1727: nothing to receive. To avoid having a case differantiation (in terms fp@1727: of an \textit{if} clause), the following method exists: fp@1727: fp@1727: \begin{lstlisting}[language=C] fp@1727: void ecrt_master_prepare(ec_master_t *master); fp@1727: \end{lstlisting} fp@1727: fp@1727: As a last thing before cyclic operation, a call to the fp@1727: \textit{ecrt\_master\_prepare()} method should be issued. It makes all fp@1727: process data domains queue their datagrams and issues a send command, fp@1727: so that the first receive call in cyclic operation will not fail. fp@1727: fp@1727: \paragraph{Frame Sending and Receiving} fp@1727: fp@1727: To send all queued datagrams and to later receive the sent datagrams fp@1727: there are two methods: fp@1727: fp@1727: \begin{lstlisting}[language=C] fp@1727: void ecrt_master_send(ec_master_t *master); fp@1727: void ecrt_master_receive(ec_master_t *master); fp@1727: \end{lstlisting} fp@1727: fp@1727: The \textit{ecrt\_master\_send()} method takes all datagrams, that fp@1727: have been queued for transmission, packs them into frames, and passes fp@1727: them to the network device for sending. fp@1727: fp@1727: The \textit{ecrt\_master\_receive()} queries the network device for fp@1727: received frames (by calling the ISR\index{ISR}), extracts received fp@1727: datagrams and dispatches the results to the datagram objects in the fp@1727: queue. Received datagrams, and the ones that timed out, will be fp@1727: marked, and then dequeued. fp@1727: fp@1727: \paragraph{Running the Operation State Machine} fp@1727: fp@1727: The master's operation state machine (see section~\ref{sec:fsm-op}) fp@1727: monitors the bus in cyclic operation and reconfigures slaves, if fp@1727: necessary. Therefore, the following method should be called fp@1727: cyclically: fp@1727: fp@1727: \begin{lstlisting}[language=C] fp@1727: void ecrt_master_run(ec_master_t *master); fp@1727: \end{lstlisting} fp@1727: fp@1727: The \textit{ecrt\_master\_run()} method executes the master's fp@1727: operation state machine step by step. It returns after processing one fp@1727: state and queuing a datagram. Calling this function is not mandatory, fp@1727: but highly recommended. fp@1727: fp@1727: \paragraph{Master Monitoring} fp@1727: fp@1727: It is also highly recommended to evaluate the master's error state. In fp@1727: this way it is possible to notice lost network links, failed bus fp@1727: segments, and other issues: fp@1727: fp@1727: \begin{lstlisting}[language=C] fp@1727: int ecrt_master_state(const ec_master_t *master); fp@1727: \end{lstlisting} fp@1727: fp@1727: The \textit{ecrt\_master\_state()} method returns the master's error fp@1727: state. The following states are defined as part of the realtime fp@1727: interface: fp@1727: fp@1727: \begin{description} fp@1727: \item[EC\_MASTER\_OK] means, that no error has occurred. fp@1727: \item[EC\_MASTER\_LINK\_ERROR] means, that the network link is fp@1727: currently down. fp@1727: \item[EC\_MASTER\_BUS\_ERROR] means, that one or more slaves do not fp@1727: respond. fp@1727: \end{description} fp@1727: fp@1727: \subsubsection{Domain Methods} fp@1727: \label{sec:ecrt-domain} fp@1727: fp@1727: \paragraph{PDO Registration} fp@1727: fp@1727: To access data of a slave's PDO in cyclic operation, it is necessary fp@1727: to make it part of a process data domain: fp@1727: fp@1727: \begin{lstlisting}[language=C] fp@1727: ec_slave_t *ecrt_domain_register_pdo(ec_domain_t *domain, fp@1727: const char *address, fp@1727: uint32_t vendor_id, fp@1727: uint32_t product_code, fp@1727: const char *pdo_name fp@1727: void **data_ptr); fp@1727: int ecrt_domain_register_pdo_list(ec_domain_t *domain, fp@1727: const ec_pdo_reg_t *pdos); fp@1727: \end{lstlisting} fp@1727: fp@1727: The \textit{ecrt\_domain\_register\_pdo()} method registers a certain fp@1727: PDO as part of the domain and takes the address of the process data fp@1727: pointer. This pointer will be set on master activation and then can be fp@1727: parameter to the \textit{EC\_READ\_*} and \textit{EC\_WRITE\_*} macros fp@1727: described below. fp@1727: fp@1727: A perhaps easier way to register multiple PDOs at the same time is to fp@1727: fill an array of \textit{ec\_pdo\_reg\_t} and hand it to the fp@1727: \textit{ecrt\_domain\_register\_pdo\_list()} method. Attention: This fp@1727: array has to be terminated by an empty structure (\textit{\{\}})! fp@1727: fp@1727: \paragraph{Evaluating Domain Data} fp@1727: fp@1727: To evaluate domain data, the following method has to be used: fp@1727: fp@1727: \begin{lstlisting}[language=C] fp@1727: void ecrt_domain_process(ec_domain_t *domain); fp@1727: \end{lstlisting} fp@1727: fp@1727: The \textit{ecrt\_domain\_process()} method sets the domains state and fp@1727: requeues its datagram for sending. fp@1727: fp@1727: \paragraph{Domain State} fp@1727: fp@1727: Similar to the master state, a domain has an own error state: fp@1727: fp@1727: \begin{lstlisting}[language=C] fp@1727: int ecrt_domain_state(const ec_domain_t *domain); fp@1727: \end{lstlisting} fp@1727: fp@1727: The \textit{ecrt\_domain\_state()} method returns the domain's error fp@1727: state. It is non-zero if \underline{not} all process data values could fp@1727: be exchanged, and zero otherwise. fp@1727: fp@1727: \subsubsection{Slave Methods} fp@1727: \label{sec:ecrt-slave} fp@1727: fp@1727: \paragraph{SDO Configuration} fp@1727: fp@1727: To configure slave SDOs, the function interface below can be used: fp@1727: fp@1727: \begin{lstlisting}[language=C] fp@1727: int ecrt_slave_conf_sdo8(ec_slave_t *slave, fp@1727: uint16_t sdo_index, fp@1727: uint8_t sdo_subindex, fp@1727: uint8_t value); fp@1727: int ecrt_slave_conf_sdo16(ec_slave_t *slave, fp@1727: uint16_t sdo_index, fp@1727: uint8_t sdo_subindex, fp@1727: uint16_t value); fp@1727: int ecrt_slave_conf_sdo32(ec_slave_t *slave, fp@1727: uint16_t sdo_index, fp@1727: uint8_t sdo_subindex, fp@1727: uint32_t value); fp@1727: \end{lstlisting} fp@1727: fp@1727: The \textit{ecrt\_slave\_conf\_sdo*()} methods prepare the fp@1727: configuration of a certain SDO. The index and subindex of the SDO, and fp@1727: the value have to be specified. The configuration is done each time, fp@1727: the slave is reconfigured. The methods only differ in the SDO's data fp@1727: type. If the configuration could be prepared, zero is returned. If an fp@1727: error occured, non-zero is returned. fp@1727: fp@1727: \paragraph{Variable-sized PDOs} fp@1727: fp@1727: For specifying the size of variable-sized PDOs, the following method fp@1727: can be used: fp@1727: fp@1727: \begin{lstlisting}[language=C] fp@1727: int ecrt_slave_pdo_size(ec_slave_t *slave, fp@1727: const char *pdo_name, fp@1727: size_t size); fp@1727: \end{lstlisting} fp@1727: fp@1727: The \textit{ecrt\_slave\_pdo\_size()} method takes the name of the PDO fp@1727: and the size. It returns zero on success, otherwise non-zero. fp@1727: fp@1727: \subsubsection{Process Data Access} fp@1727: \label{sec:macros} fp@1727: fp@1727: The endianess of the process data could differ from that of the CPU. fp@1727: Therefore, process data access has to be done by the macros below, fp@1727: that are also provided by the realtime interface: fp@1727: fp@1727: \begin{lstlisting}[language=C] fp@1727: #define EC_READ_BIT(DATA, POS) fp@1727: #define EC_WRITE_BIT(DATA, POS, VAL) fp@1727: fp@1727: #define EC_READ_U8(DATA) fp@1727: #define EC_READ_S8(DATA) fp@1727: #define EC_READ_U16(DATA) fp@1727: #define EC_READ_S16(DATA) fp@1727: #define EC_READ_U32(DATA) fp@1727: #define EC_READ_S32(DATA) fp@1727: fp@1727: #define EC_WRITE_U8(DATA, VAL) fp@1727: #define EC_WRITE_S8(DATA, VAL) fp@1727: #define EC_WRITE_U16(DATA, VAL) fp@1727: #define EC_WRITE_S16(DATA, VAL) fp@1727: #define EC_WRITE_U32(DATA, VAL) fp@1727: #define EC_WRITE_S32(DATA, VAL) fp@1727: \end{lstlisting} fp@1727: fp@1727: There are macros for bitwise access (\textit{EC\_READ\_BIT()}, fp@1727: \textit{EC\_WRITE\_BIT()}), and bytewise access fp@1727: (\textit{EC\_READ\_*()}, \textit{EC\_WRITE\_*()}). The bytewise macros fp@1727: carry the data type in their name. Example: \textit{EC\_WRITE\_S16()} fp@1727: writes a 16 bit signed value to EtherCAT data. The \textit{DATA} fp@1727: parameter is supposed to be a process data pointer, as provided at PDO fp@1727: registration. fp@1727: fp@1727: The macros use the kernel's endianess conversion macros, that are fp@1727: preprocessed to empty macros in case of equal endianess. This is the fp@1727: definition for the \textit{EC\_\-READ\_\-U16()} macro: fp@1727: fp@1727: \begin{lstlisting}[language=C] fp@1727: #define EC_READ_U16(DATA) \ fp@1727: ((uint16_t) le16_to_cpup((void *) (DATA))) fp@1727: \end{lstlisting} fp@1727: fp@1727: The \textit{le16\_to\_cpup()} macro converts a little-endian, 16 bit fp@1727: value to the CPU's architecture and takes a pointer to the input value fp@1727: as its argument. If the CPU's architecture is little-endian, too (for fp@1727: example on X86 and compatible), nothing has to be converted. In this fp@1727: case, the macro is replaced with an empty macro by the preprocessor fp@1727: and so there is no unneeded function call or case differentiation in fp@1727: the code. fp@1727: fp@1727: For keeping it portable, it is highly recommended to make use of these fp@1727: macros. fp@1727: fp@1727: %------------------------------------------------------------------------------ fp@1727: fp@1727: \subsection{Slave Addressing} fp@1727: \label{sec:addr} fp@1727: \index{Slave!Addressing} fp@1727: fp@1727: The master offers the serveral slave addressing schemes (for PDO fp@1727: registration or configuration) via the realtime interface. For this fp@1727: reason, slave addresses are ASCII\nomenclature{ASCII}{American fp@1727: Standard Code for Information Interchange}-coded and passed as a fp@1727: string. The addressing schemes are independent of the EtherCAT fp@1727: protocol and represent an additional feature of the master. fp@1727: fp@1727: Below, the allowed addressing schemes are described. The descriptions fp@1727: are followed by a regular expression formally defining the addressing fp@1727: scheme, and one or more examples. fp@1727: fp@1727: \begin{description} fp@1727: \item[Position Addressing] This is the normal addressing scheme, where fp@1727: each slave is addressed by its ring position. The first slave has fp@1727: address 0, and the $n$th slave has address $n - 1$. This addressing fp@1727: scheme is useful for small busses that have a fixed number of slaves.\\ fp@1727: RegEx: \texttt{[0-9]+} --- Example: \texttt{"42"} fp@1727: \item[Advanced Position Addressing] Bus couplers segment the bus into fp@1727: (physical) blocks. Though the logical ring positions keep being the fp@1727: same, it is easier to address a slave with its block number and the fp@1727: relative position inside the block. This addressing is done by fp@1727: passing the (zero-based) index of the bus coupler (not the coupler's fp@1727: ring position), followed by a colon and the relative position of the fp@1727: actual slave starting at the bus coupler.\\ fp@1727: RegEx: \texttt{[0-9]+:[0-9]+} --- Examples: \texttt{"0:42"}, fp@1727: \texttt{"2:7"} fp@1727: \item[Alias Addressing] Each slave can have a ``secondary slave fp@1727: address'' or ``alias address''\footnote{Information about how to set fp@1727: the alias can be found in section~\ref{sec:eepromaccess}} stored fp@1727: in its E$^2$PROM. The alias is evaluated by the master and can be fp@1727: used to address the slave, which is useful when a clearly defined fp@1727: slave has to be addressed and the ring position is not known or can fp@1727: change over time. This scheme is used by starting the address string fp@1727: with a mesh (\#) followed by the alias address. The latter can also fp@1727: be provided as hexadecimal value, prefixed with \textit{0x}.\\ fp@1727: RegEx: \texttt{\#(0x[0-9A-F]+|[0-9]+)} --- Examples: fp@1727: \texttt{"\#6622"}, \texttt{"\#0xBEEF"} fp@1727: \item[Advanced Alias Addressing] This is a mixture of the ``Alias fp@1727: Addressing'' and ``Advanced Position Addressing'' schemes. A certain fp@1727: slave is addressed by specifying its relative position after an fp@1727: aliased slave. This is very useful, if a complete block of slaves fp@1727: can vary its position in the bus. The bus coupler preceeding the fp@1727: block should get an alias. The block slaves can then be addressed by fp@1727: specifying this alias and their position inside the block. This fp@1727: scheme is used by starting the address string with a mesh (\#) fp@1727: followed by the alias address (which can be hexadecimal), then a fp@1727: colon and the relative posision of the slave to fp@1727: address.\\ fp@1727: RegEx: \texttt{\#(0x[0-9A-F]+|[0-9]+):[0-9]+} --- Examples: fp@1727: \texttt{"\#0xBEEF:7"}, \texttt{"\#6:2"} fp@1727: \end{description} fp@1727: fp@1727: In anticipation of section~\ref{sec:ecrt}, the functions accepting fp@1727: these address strings are \textit{ecrt\_\-master\_\-get\_slave()}, fp@1727: \textit{ecrt\_domain\_register\_pdo()} and fp@1727: \textit{ecrt\_domain\_register\_pdo\_list()} (the latter through the fp@1727: \textit{ec\_pdo\_reg\_t} structure). fp@1727: fp@1727: %------------------------------------------------------------------------------ fp@1727: fp@1727: \subsection{Concurrent Master Access} fp@1727: \label{sec:concurr} fp@1727: \index{Concurrency} fp@1727: fp@1727: In some cases, one master is used by serveral instances, for example fp@1727: when a realtime module does cyclic process data exchange, and there fp@1727: are EoE-capable slaves that require to exchange Ethernet data with the fp@1727: kernel (see section~\ref{sec:eoeimp}). For this reason, the master is fp@1727: a shared resource, and access to it has to be sequenctialized. This is fp@1727: usually done by locking with semaphores, or other methods to protect fp@1727: critical sections. fp@1727: fp@1727: The master itself can not provide locking mechanisms, because it has fp@1727: no chance to know the appropriate kind of lock. Imagine, the realtime fp@1727: module uses RTAI functionality, then ordinary kernel semaphores would fp@1727: not be sufficient. For that, an important design decision was made: fp@1727: The realtime module that reserved a master must have the total fp@1727: control, therefore it has to take responsibility for providing the fp@1727: appropriate locking mechanisms. If another instance wants to access fp@1727: the master, it has to request the master lock by callbacks, that have fp@1727: to be set by the realtime module. Moreover the realtime module can fp@1727: deny access to the master if it consideres it to be awkward at the fp@1727: moment. fp@1727: fp@1727: \begin{figure}[htbp] fp@1727: \centering fp@1727: \includegraphics[width=.6\textwidth]{images/master-locks} fp@1727: \caption{Concurrent master access} fp@1727: \label{fig:locks} fp@1727: \end{figure} fp@1727: fp@1727: Figure~\ref{fig:locks} exemplary shows, how two processes share one fp@1727: master: The realtime module's cyclic thread uses the master for fp@1727: process data exchange, while the master-internal EoE process uses it fp@1727: to communicate with EoE-capable slaves. Both have to aquire the master fp@1727: lock before access: The realtime thread can access the lock natively, fp@1727: while the EoE process has to use the master callbacks. fp@1727: Section~\ref{sec:concurrency} gives an example, of how to implement fp@1727: this. fp@1727: fp@1727: %------------------------------------------------------------------------------ fp@1727: fp@1727: \section{The Master's State Machines} fp@1727: \label{sec:fsm} fp@1727: \index{FSM} fp@1727: fp@1727: Many parts of the EtherCAT master are implemented as \textit{finite fp@1727: state machines} (FSMs\nomenclature{FSM}{Finite State Machine}). fp@1727: Though this leads to a higher grade of complexity in some aspects, is fp@1727: opens many new possibilities. fp@1727: fp@1727: The below short code example exemplary shows how to read all slave fp@1727: states and moreover illustrates the restrictions of ``sequential'' fp@1727: coding: fp@1727: fp@1727: \begin{lstlisting}[language=C,numbers=left] fp@1727: ec_datagram_brd(datagram, 0x0130, 2); // prepare datagram fp@1727: if (ec_master_simple_io(master, datagram)) return -1; fp@1727: slave_states = EC_READ_U8(datagram->data); // process datagram fp@1727: \end{lstlisting} fp@1727: fp@1727: The \textit{ec\_master\_simple\_io()} function provides a simple fp@1727: interface for synchronously sending a single datagram and receiving fp@1727: the result\footnote{For all communication issues have been meanwhile fp@1727: sourced out into state machines, the function is deprecated and fp@1727: stopped existing. Nevertheless it is adequate for showing it's own fp@1727: restrictions.}. Internally, it queues the specified datagram, fp@1727: invokes the \textit{ec\_master\_send\_datagrams()} function to send a fp@1727: frame with the queued datagram and then waits actively for its fp@1727: reception. fp@1727: fp@1727: This sequential approach is very simple, reflecting in only three fp@1727: lines of code. The disadvantage is, that the master is blocked for the fp@1727: time it waits for datagram reception. There is no difficulty when only fp@1727: one instance is using the master, but if more instances want to fp@1727: (synchronously\footnote{At this time, synchronous master access will fp@1727: be adequate to show the advantages of an FSM. The asynchronous fp@1727: approach will be discussed in section~\ref{sec:eoeimp}}) use the fp@1727: master, it is inevitable to think about an alternative to the fp@1727: sequential model. fp@1727: fp@1727: Master access has to be sequentialized for more than one instance fp@1727: wanting to send and receive datagrams synchronously. With the present fp@1727: approach, this would result in having one phase of active waiting for fp@1727: each instance, which would be non-acceptable especially in realtime fp@1727: circumstances, because of the huge time overhead. fp@1727: fp@1727: A possible solution is, that all instances would be executed fp@1727: sequentially to queue their datagrams, then give the control to the fp@1727: next instance instead of waiting for the datagram reception. Finally, fp@1727: bus IO is done by a higher instance, which means that all queued fp@1727: datagrams are sent and received. The next step is to execute all fp@1727: instances again, which then process their received datagrams and issue fp@1727: new ones. fp@1727: fp@1727: This approach results in all instances having to retain their state, fp@1727: when giving the control back to the higher instance. It is quite fp@1727: obvious to use a \textit{finite state machine} model in this case. fp@1727: Section~\ref{sec:fsmtheory} will introduce some of the theory used, fp@1727: while the listings below show the basic approach by coding the example fp@1727: from above as a state machine: fp@1727: fp@1727: \begin{lstlisting}[language=C,numbers=left] fp@1727: // state 1 fp@1727: ec_datagram_brd(datagram, 0x0130, 2); // prepare datagram fp@1727: ec_master_queue(master, datagram); // queue datagram fp@1727: next_state = state_2; fp@1727: // state processing finished fp@1727: \end{lstlisting} fp@1727: fp@1727: After all instances executed their current state and queued their fp@1727: datagrams, these are sent and received. Then the respective next fp@1727: states are executed: fp@1727: fp@1727: \begin{lstlisting}[language=C,numbers=left] fp@1727: // state 2 fp@1727: if (datagram->state != EC_DGRAM_STATE_RECEIVED) { fp@1727: next_state = state_error; fp@1727: return; // state processing finished fp@1727: } fp@1727: slave_states = EC_READ_U8(datagram->data); // process datagram fp@1727: // state processing finished. fp@1727: \end{lstlisting} fp@1727: fp@1727: See section~\ref{sec:statemodel} for an introduction to the fp@1727: state machine programming concept used in the master code. fp@1727: fp@1727: %------------------------------------------------------------------------------ fp@1727: fp@1727: \subsection{State Machine Theory} fp@1727: \label{sec:fsmtheory} fp@1727: \index{FSM!Theory} fp@1727: fp@1727: A finite state machine \cite{automata} is a model of behavior with fp@1727: inputs and outputs, where the outputs not only depend on the inputs, fp@1727: but the history of inputs. The mathematical definition of a finite fp@1727: state machine (or finite automaton) is a six-tuple $(\Sigma, \Gamma, fp@1727: S, s_0, \delta, \omega)$, with fp@1727: fp@1727: \begin{itemize} fp@1727: \item the input alphabet $\Sigma$, with $\Sigma \neq fp@1727: \emptyset$, containing all input symbols, fp@1727: \item the output alphabet $\Gamma$, with $\Gamma \neq fp@1727: \emptyset$, containing all output symbols, fp@1727: \item the set of states $S$, with $S \neq \emptyset$, fp@1727: \item the set of initial states $s_0$ with $s_0 \subseteq S, s_0 \neq fp@1727: \emptyset$ fp@1727: \item the transition function $\delta: S \times \Sigma \rightarrow S fp@1727: \times \Gamma$ fp@1727: \item the output function $\omega$. fp@1727: \end{itemize} fp@1727: fp@1727: The state transition function $\delta$ is often specified by a fp@1727: \textit{state transition table}, or by a \textit{state transition fp@1727: diagram}. The transition table offers a matrix view of the state fp@1727: machine behavior (see table~\ref{tab:statetrans}). The matrix rows fp@1727: correspond to the states ($S = \{s_0, s_1, s_2\}$) and the columns fp@1727: correspond to the input symbols ($\Gamma = \{a, b, \varepsilon\}$). fp@1727: The table contents in a certain row $i$ and column $j$ then represent fp@1727: the next state (and possibly the output) for the case, that a certain fp@1727: input symbol $\sigma_j$ is read in the state $s_i$. fp@1727: fp@1727: \begin{table}[htbp] fp@1727: \caption{A typical state transition table} fp@1727: \label{tab:statetrans} fp@1727: \vspace{2mm} fp@1727: \centering fp@1727: \begin{tabular}{l|ccc} fp@1727: & $a$ & $b$ & $\varepsilon$\\ \hline fp@1727: $s_0$ & $s_1$ & $s_1$ & $s_2$\\ fp@1727: $s_1$ & $s_2$ & $s_1$ & $s_0$\\ fp@1727: $s_2$ & $s_0$ & $s_0$ & $s_0$\\ \hline fp@1727: \end{tabular} fp@1727: \end{table} fp@1727: fp@1727: The state diagram for the same example looks like the one in fp@1727: figure~\ref{fig:statetrans}. The states are represented as circles or fp@1727: ellipses and the transitions are drawn as arrows between them. Close fp@1727: to a transition arrow can be the condition that must be fulfilled to fp@1727: allow the transition. The initial state is marked by a filled black fp@1727: circle with an arrow pointing to the respective state. fp@1727: fp@1727: \begin{figure}[htbp] fp@1727: \centering fp@1727: \includegraphics[width=.5\textwidth]{images/statetrans} fp@1727: \caption{A typical state transition diagram} fp@1727: \label{fig:statetrans} fp@1727: \end{figure} fp@1727: fp@1727: \paragraph{Deterministic and non-deterministic state machines} fp@1727: fp@1727: A state machine can be deterministic, meaning that for one state and fp@1727: input, there is one (and only one) following state. In this case, the fp@1727: state machine has exactly one starting state. Non-deterministic state fp@1727: machines can have more than one transitions for a single state-input fp@1727: combination. There is a set of starting states in the latter case. fp@1727: fp@1727: \paragraph{Moore and Mealy machines} fp@1727: fp@1727: There is a distinction between so-called \textit{Moore machines}, and fp@1727: \textit{Mealy machines}. Mathematically spoken, the distinction lies fp@1727: in the output function $\omega$: If it only depends on the current fp@1727: state ($\omega: S \rightarrow \Gamma$), the machine corresponds to the fp@1727: ``Moore Model''. Otherwise, if $\omega$ is a function of a state and fp@1727: the input alphabet ($\omega: S \times \Sigma \rightarrow \Gamma$) the fp@1727: state machine corresponds to the ``Mealy model''. Mealy machines are fp@1727: the more practical solution in most cases, because their design allows fp@1727: machines with a minimum number of states. In practice, a mixture of fp@1727: both models is often used. fp@1727: fp@1727: \paragraph{Misunderstandings about state machines} fp@1727: fp@1727: There is a phenomenon called ``state explosion'', that is oftenly fp@1727: taken as a counter-argument against general use of state machines in fp@1727: complex environments. It has to be mentioned, that this point is fp@1727: misleading~\cite{fsmmis}. State explosions happen usually as a result fp@1727: of a bad state machine design: Common mistakes are storing the present fp@1727: values of all inputs in a state, or not dividing a complex state fp@1727: machine into simpler sub state machines. The EtherCAT master uses fp@1727: serveral state machines, that are executed hierarchically and so serve fp@1727: as sub state machines. These are also described below. fp@1727: fp@1727: %------------------------------------------------------------------------------ fp@1727: fp@1727: \subsection{The Master's State Model} fp@1727: \label{sec:statemodel} fp@1727: fp@1727: This section will introduce the techniques used in the master to fp@1727: implement state machines. fp@1727: fp@1727: \paragraph{State Machine Programming} fp@1727: fp@1727: There are certain ways to implement a state machine in \textit{C} fp@1727: code. An obvious way is to implement the different states and actions fp@1727: by one big case differentiation: fp@1727: fp@1727: \begin{lstlisting}[language=C,numbers=left] fp@1727: enum {STATE_1, STATE_2, STATE_3}; fp@1727: int state = STATE_1; fp@1727: fp@1727: void state_machine_run(void *priv_data) { fp@1727: switch (state) { fp@1727: case STATE_1: fp@1727: action_1(); fp@1727: state = STATE_2; fp@1727: break; fp@1727: case STATE_2: fp@1727: action_2() fp@1727: if (some_condition) state = STATE_1; fp@1727: else state = STATE_3; fp@1727: break; fp@1727: case STATE_3: fp@1727: action_3(); fp@1727: state = STATE_1; fp@1727: break; fp@1727: } fp@1727: } fp@1727: \end{lstlisting} fp@1727: fp@1727: For small state machines, this is an option. The disadvantage is, that fp@1727: with an increasing number of states the code soon gets complex and an fp@1727: additional case differentiation is executed each run. Besides, lots of fp@1727: indentation is wasted. fp@1727: fp@1727: The method used in the master is to implement every state in an own fp@1727: function and to store the current state function with a function fp@1727: pointer: fp@1727: fp@1727: \begin{lstlisting}[language=C,numbers=left] fp@1727: void (*state)(void *) = state1; fp@1727: fp@1727: void state_machine_run(void *priv_data) { fp@1727: state(priv_data); fp@1727: } fp@1727: fp@1727: void state1(void *priv_data) { fp@1727: action_1(); fp@1727: state = state2; fp@1727: } fp@1727: fp@1727: void state2(void *priv_data) { fp@1727: action_2(); fp@1727: if (some_condition) state = state1; fp@1727: else state = state2; fp@1727: } fp@1727: fp@1727: void state3(void *priv_data) { fp@1727: action_3(); fp@1727: state = state1; fp@1727: } fp@1727: \end{lstlisting} fp@1727: fp@1727: In the master code, state pointers of all state machines\footnote{All fp@1727: except for the EoE state machine, because multiple EoE slaves have fp@1727: to be handled in parallel. For this reason each EoE handler object fp@1727: has its own state pointer.} are gathered in a single object of the fp@1727: \textit{ec\_fsm\_t} class. This is advantageous, because there is fp@1727: always one instance of every state machine available and can be fp@1727: started on demand. fp@1727: fp@1727: \paragraph{Mealy and Moore} fp@1727: fp@1727: If a closer look is taken to the above listing, it can be seen that fp@1727: the actions executed (the ``outputs'' of the state machine) only fp@1727: depend on the current state. This accords to the ``Moore'' model fp@1727: introduced in section~\ref{sec:fsmtheory}. As mentioned, the ``Mealy'' fp@1727: model offers a higher flexibility, which can be seen in the listing fp@1727: below: fp@1727: fp@1727: \begin{lstlisting}[language=C,numbers=left] fp@1727: void state7(void *priv_data) { fp@1727: if (some_condition) { fp@1727: action_7a(); fp@1727: state = state1; fp@1727: } fp@1727: else { fp@1727: action_7b(); fp@1727: state = state8; fp@1727: } fp@1727: } fp@1727: \end{lstlisting} fp@1727: fp@1727: \begin{description} fp@1727: \item[\normalfont\textcircled{\tiny 3} + \textcircled{\tiny 7}] The fp@1727: state function executes the actions depending on the state fp@1727: transition, that is about to be done. fp@1727: \end{description} fp@1727: fp@1727: The most flexible alternative is to execute certain actions depending fp@1727: on the state, followed by some actions dependent on the state fp@1727: transition: fp@1727: fp@1727: \begin{lstlisting}[language=C,numbers=left] fp@1727: void state9(void *priv_data) { fp@1727: action_9(); fp@1727: if (some_condition) { fp@1727: action_9a(); fp@1727: state = state7; fp@1727: } fp@1727: else { fp@1727: action_9b(); fp@1727: state = state10; fp@1727: } fp@1727: } fp@1727: \end{lstlisting} fp@1727: fp@1727: This model is oftenly used in the master. It combines the best aspects fp@1727: of both approaches. fp@1727: fp@1727: \paragraph{Using Sub State Machines} fp@1727: fp@1727: To avoid having too much states, certain functions of the EtherCAT fp@1727: master state machine have been sourced out into sub state machines. fp@1727: This helps to encapsule the related workflows and moreover avoids the fp@1727: ``state explosion'' phenomenon described in fp@1727: section~\ref{sec:fsmtheory}. If the master would instead use one big fp@1727: state machine, the number of states would be a multiple of the actual fp@1727: number. This would increase the level of complexity to a fp@1727: non-manageable grade. fp@1727: fp@1727: \paragraph{Executing Sub State Machines} fp@1727: fp@1727: If a state machine starts to execute a sub state machine, it usually fp@1727: remains in one state until the sub state machine terminates. This is fp@1727: usually done like in the listing below, which is taken out of the fp@1727: slave configuration state machine code: fp@1727: fp@1727: \begin{lstlisting}[language=C,numbers=left] fp@1727: void ec_fsm_slaveconf_saveop(ec_fsm_t *fsm) fp@1727: { fp@1727: fsm->change_state(fsm); // execute state change fp@1727: // sub state machine fp@1727: fp@1727: if (fsm->change_state == ec_fsm_error) { fp@1727: fsm->slave_state = ec_fsm_end; fp@1727: return; fp@1727: } fp@1727: fp@1727: if (fsm->change_state != ec_fsm_end) return; fp@1727: fp@1727: // continue state processing fp@1727: ... fp@1727: \end{lstlisting} fp@1727: fp@1727: \begin{description} fp@1727: \item[\normalfont\textcircled{\tiny 3}] \textit{change\_state} is the fp@1727: state pointer of the state change state machine. The state function, fp@1727: the pointer points on, is executed\ldots fp@1727: \item[\normalfont\textcircled{\tiny 6}] \ldots either until the state fp@1727: machine terminates with the error state \ldots fp@1727: \item[\normalfont\textcircled{\tiny 11}] \ldots or until the state fp@1727: machine terminates in the end state. Until then, the ``higher'' fp@1727: state machine remains in the current state and executes the sub fp@1727: state machine again in the next cycle. fp@1727: \end{description} fp@1727: fp@1727: \paragraph{State Machine Descriptions} fp@1727: fp@1727: The below sections describe every state machine used in the EtherCAT fp@1727: master. The textual descriptions of the state machines contain fp@1727: references to the transitions in the corresponding state transition fp@1727: diagrams, that are marked with an arrow followed by the name of the fp@1727: successive state. Transitions caused by trivial error cases (i.~e. no fp@1727: response from slave) are not described explicitly. These transitions fp@1727: are drawn as dashed arrows in the diagrams. fp@1727: fp@1727: %------------------------------------------------------------------------------ fp@1727: fp@1727: \subsection{The Operation State Machine} fp@1727: \label{sec:fsm-op} fp@1727: \index{FSM!Operation} fp@1727: fp@1727: The Operation state machine is executed by calling the fp@1727: \textit{ecrt\_master\_run()} method in cyclic realtime code. Its fp@1727: purpose is to monitor the bus and to reconfigure slaves after a bus fp@1727: failure or power failure. Figure~\ref{fig:fsm-op} shows its transition fp@1727: diagram. fp@1727: fp@1727: \begin{figure}[htbp] fp@1727: \centering fp@1727: \includegraphics[width=.8\textwidth]{images/fsm-op} fp@1727: \caption{Transition diagram of the operation state machine} fp@1727: \label{fig:fsm-op} fp@1727: \end{figure} fp@1727: fp@1727: \begin{description} fp@1727: \item[START] This is the beginning state of the operation state fp@1727: machine. There is a datagram issued, that queries the ``AL Control fp@1727: Response'' attribute \cite[section~5.3.2]{alspec} of all slaves via fp@1727: broadcast. In this way, all slave states and the number of slaves fp@1729: responding can be determined. $\rightarrow$~BROADCAST fp@1727: fp@1727: \item[BROADCAST] The broadcast datagram is evaluated. A change in the fp@1727: number of responding slaves is treates as a topology change. If the fp@1727: number of slaves is not as expected, the bus is marked as fp@1727: ``tainted''. In this state, no slave reconfiguration is possible, fp@1727: because the assignment of known slaves and those present on the bus fp@1727: is ambiguous. If the number of slaves is considered as right, the fp@1727: bus is marked for validation, because it turned from tainted to fp@1727: normal state and it has to be checked, if all slaves are valid. Now, fp@1727: the state of every single slave has to be determined. For that, a fp@1727: (unicast) datagram is issued, that queries the first slave's ``AL fp@1729: Control Response'' attribute. $\rightarrow$~READ STATES fp@1727: fp@1727: \item[READ STATES] If the current slave did not respond to its fp@1727: configured station address, it is marked as offline, and the next fp@1729: slave is queried. $\rightarrow$~READ STATES fp@1727: fp@1727: If the slave responded, it is marked as online and its current state fp@1729: is stored. The next slave is queried. $\rightarrow$~READ STATES fp@1727: fp@1727: If all slaves have been queried, and the bus is marked for fp@1727: validation, the validation is started by checking the first slaves fp@1729: vendor ID. $\rightarrow$~VALIDATE VENDOR fp@1727: fp@1727: If no validation has to be done, it is checked, if all slaves are in fp@1727: the state they are supposed to be. If not, the first of slave with fp@1727: the wrong state is reconfigured and brought in the required state. fp@1729: $\rightarrow$~CONFIGURE SLAVES fp@1727: fp@1727: If all slaves are in the correct state, the state machine is fp@1729: restarted. $\rightarrow$~START fp@1727: fp@1727: \item[CONFIGURE SLAVES] The slave configuration state machine is fp@1729: executed until termination. $\rightarrow$~CONFIGURE SLAVES fp@1727: fp@1727: If there are still slaves in the wrong state after another check, fp@1727: the first of these slaves is configured and brought into the correct fp@1729: state again. $\rightarrow$~CONFIGURE SLAVES fp@1727: fp@1727: If all slaves are in the correct state, the state machine is fp@1729: restarted. $\rightarrow$~START fp@1727: fp@1727: \item[VALIDATE VENDOR] The SII state machine is executed until fp@1727: termination. If the slave has the wrong vendor ID, the state machine fp@1729: is restarted. $\rightarrow$~START fp@1727: fp@1727: If the slave has the correct vendor ID, its product ID is queried. fp@1729: $\rightarrow$~VALIDATE PRODUCT fp@1727: fp@1727: \item[VALIDATE PRODUCT] The SII state machine is executed until fp@1727: termination. If the slave has the wrong product ID, the state fp@1729: machine is restarted. $\rightarrow$~START fp@1727: fp@1727: If the slave has the correct product ID, the next slave's vendor ID fp@1729: is queried. $\rightarrow$~VALIDATE VENDOR fp@1727: fp@1727: If all slaves have the correct vendor IDs and product codes, the fp@1727: configured station addresses can be safely rewritten. This is done fp@1727: for the first slave marked as offline. fp@1729: $\rightarrow$~REWRITE ADDRESSES fp@1727: fp@1727: \item[REWRITE ADDRESSES] If the station address was successfully fp@1727: written, it is sear\-ched for the next slave marked as offline. If fp@1727: there is one, its address is reconfigured, too. fp@1729: $\rightarrow$~REWRITE ADDRESSES fp@1727: fp@1727: If there are no more slaves marked as offline, the state machine is fp@1729: restarted. $\rightarrow$~START fp@1727: \end{description} fp@1727: fp@1727: %------------------------------------------------------------------------------ fp@1727: fp@1727: \subsection{The Idle State Machine} fp@1727: \label{sec:fsm-idle} fp@1727: \index{FSM!Idle} fp@1727: fp@1727: The Idle state machine is executed by a kernel workqueue, if no fp@1727: realtime module is connected. Its purpose is to make slave information fp@1727: available to user space, operate EoE-capable slaves, read and write fp@1727: E$^2$PROM contents and test slave functionality. fp@1727: Figure~\ref{fig:fsm-idle} shows its transition diagram. fp@1727: fp@1727: \begin{figure}[htbp] fp@1727: \centering fp@1727: \includegraphics[width=.8\textwidth]{images/fsm-idle} fp@1727: \caption{Transition diagram of the idle state machine} fp@1727: \label{fig:fsm-idle} fp@1727: \end{figure} fp@1727: fp@1727: \begin{description} fp@1727: \item[START] The beginning state of the idle state machine. Similar to fp@1727: the operation state machine, a broadcast datagram is issued, to fp@1727: query all slave states and the number of slaves. fp@1729: $\rightarrow$~BROADCAST fp@1727: fp@1727: \item[BROADCAST] The number of responding slaves is evaluated. If it fp@1727: has changed since the last time, this is treated as a topology fp@1727: change and the internal list of slaves is cleared and rebuild fp@1727: completely. The slave scan state machine is started for the first fp@1729: slave. $\rightarrow$~SCAN FOR SLAVES fp@1727: fp@1727: If no topology change happened, every single slave state is fetched. fp@1729: $\rightarrow$~READ STATES fp@1727: fp@1727: \item[SCAN FOR SLAVES] The slave scan state machine is executed until fp@1729: termination. $\rightarrow$~SCAN FOR SLAVES fp@1727: fp@1727: If there is another slave to scan, the slave scan state machine is fp@1729: started again. $\rightarrow$~SCAN FOR SLAVES fp@1727: fp@1727: If all slave information has been fetched, slave addresses are fp@1727: calculated and EoE processing is started. Then, the state machine is fp@1729: restarted. $\rightarrow$~START fp@1727: fp@1727: \item[READ STATES] If the slave did not respond to the query, it is fp@1727: marked as offline. The next slave is queried. fp@1729: $\rightarrow$~READ STATES fp@1727: fp@1727: If the slave responded, it is marked as online. And the next slave fp@1729: is queried. $\rightarrow$~READ STATES fp@1727: fp@1727: If all slave states have been determined, it is checked, if any fp@1727: slaves are not in the state they supposed to be. If this is true, fp@1727: the slave configuration state machine is started for the first of fp@1729: them. $\rightarrow$~CONFIGURE SLAVES fp@1727: fp@1727: If all slaves are in the correct state, it is checked, if any fp@1727: E$^2$PROM write operations are pending. If this is true, the first fp@1727: pending operation is executed by starting the SII state machine for fp@1729: writing access. $\rightarrow$~WRITE EEPROM fp@1727: fp@1727: If all these conditions are false, there is nothing to do and the fp@1729: state machine is restarted. $\rightarrow$~START fp@1727: fp@1727: \item[CONFIGURE SLAVES] The slave configuration state machine is fp@1729: executed until termination. $\rightarrow$~CONFIGURE SLAVES fp@1727: fp@1727: After this, it is checked, if another slave needs a state change. If fp@1727: this is true, the slave state change state machine is started for fp@1729: this slave. $\rightarrow$~CONFIGURE SLAVES fp@1727: fp@1727: If all slaves are in the correct state, it is determined, if any fp@1727: E$^2$PROM write operations are pending. If this is true, the first fp@1727: pending operation is executed by starting the SII state machine for fp@1729: writing access. $\rightarrow$~WRITE EEPROM fp@1727: fp@1727: If all prior conditions are false, the state machine is restarted. fp@1729: $\rightarrow$~START fp@1727: fp@1727: \item[WRITE EEPROM] The SII state machine is executed until fp@1729: termination. $\rightarrow$~WRITE EEPROM fp@1727: fp@1727: If the current word has been written successfully, and there are fp@1727: still word to write, the SII state machine is started for the next fp@1729: word. $\rightarrow$~WRITE EEPROM fp@1727: fp@1727: If all words have been written successfully, the new E$^2$PROM fp@1727: contents are evaluated and the state machine is restarted. fp@1729: $\rightarrow$~START fp@1727: fp@1727: \end{description} fp@1727: fp@1727: %------------------------------------------------------------------------------ fp@1727: fp@1727: \subsection{The Slave Scan State Machine} fp@1727: \label{sec:fsm-scan} fp@1727: \index{FSM!Slave Scan} fp@1727: fp@1727: The slave scan state machine, which can be seen in fp@1727: figure~\ref{fig:fsm-slavescan}, leads through the process of fetching fp@1727: all slave information. fp@1727: fp@1727: \begin{figure}[htbp] fp@1727: \centering fp@1727: \includegraphics[width=.6\textwidth]{images/fsm-slavescan} fp@1727: \caption{Transition diagram of the slave scan state machine} fp@1727: \label{fig:fsm-slavescan} fp@1727: \end{figure} fp@1727: fp@1727: \begin{description} fp@1727: \item[START] In the beginning state of the slave scan state machine, fp@1727: the station address is written to the slave, which is always the fp@1727: ring position~+~$1$. In this way, the address 0x0000 (default fp@1727: address) is not used, which makes it easy to detect unconfigured fp@1729: slaves. $\rightarrow$~ADDRESS fp@1727: fp@1727: \item[ADDRESS] The writing of the station address is verified. After fp@1727: that, the slave's ``AL Control Response'' attribute is queried. fp@1729: $\rightarrow$~STATE fp@1727: fp@1727: \item[STATE] The AL state is evaluated. A warning is output, if the fp@1727: slave has still the \textit{Change} bit set. After that, the slave's fp@1727: ``DL Information'' attribute is queried. fp@1729: $\rightarrow$~BASE fp@1727: fp@1727: \item[BASE] The queried base data are evaluated: Slave type, revision fp@1727: and build number, and even more important, the number of supported fp@1727: sync managers and FMMUs are stored. After that, the slave's data fp@1727: link layer information is read from the ``DL Status'' attribute at fp@1729: address 0x0110. $\rightarrow$~DATALINK fp@1727: fp@1727: \item[DATALINK] In this state, the DL information is evaluated: This fp@1727: information about the communication ports contains, if the link is fp@1727: up, if the loop has been closed and if there is a carrier detected fp@1727: on the RX side of each port. fp@1727: fp@1727: Then, the state machine starts measuring the size of the slave's fp@1727: E$^2$PROM contents. This is done by subsequently reading out each fp@1727: category header, until the last category is reached (type 0xFFFF). fp@1727: This procedure is started by querying the first category header at fp@1727: word address 0x0040 via the SII state machine. fp@1729: $\rightarrow$~EEPROM SIZE fp@1727: fp@1727: \item[EEPROM SIZE] The SII state machine is executed until fp@1729: termination. $\rightarrow$~EEPROM SIZE fp@1727: fp@1727: If the category type does not mark the end of the categories, the fp@1727: position of the next category header is determined via the length of fp@1727: the current category, and the SII state machine is started again. fp@1729: $\rightarrow$~EEPROM SIZE fp@1727: fp@1727: If the size of the E$^2$PROM contents has been determined, memory is fp@1727: allocated, to read all the contents. The SII state machine is fp@1729: started to read the first word. $\rightarrow$~EEPROM DATA fp@1727: fp@1727: \item[EEPROM DATA] The SII state machine is executed until fp@1729: termination. $\rightarrow$~EEPROM DATA fp@1727: fp@1727: Two words have been read. If more than one word is needed, the two fp@1727: words are written in the allocated memory. Otherwise only one word fp@1727: (the last word) is copied. If more words are to read, the SII state fp@1727: machine is started again to read the next two words. fp@1729: $\rightarrow$~EEPROM DATA fp@1727: fp@1727: The complete E$^2$PROM contents have been read. The slave's identity fp@1727: object and mailbox information are evaluated. Moreover the category fp@1727: types STRINGS, GENERAL, SYNC and PDO are evaluated. The slave fp@1729: scanning has been completed. $\rightarrow$~END fp@1727: fp@1727: \item[END] Slave scanning has been finished. fp@1727: fp@1727: \end{description} fp@1727: fp@1727: %------------------------------------------------------------------------------ fp@1727: fp@1727: \subsection{The Slave Configuration State Machine} fp@1727: \label{sec:fsm-conf} fp@1727: \index{FSM!Slave Configuration} fp@1727: fp@1727: The slave configuration state machine, which can be seen in fp@1727: figure~\ref{fig:fsm-slaveconf}, leads through the process of fp@1727: configuring a slave and bringing it to a certain state. fp@1727: fp@1727: \begin{figure}[htbp] fp@1727: \centering fp@1727: \includegraphics[width=.6\textwidth]{images/fsm-slaveconf} fp@1727: \caption{Transition diagram of the slave configuration state fp@1727: machine} fp@1727: \label{fig:fsm-slaveconf} fp@1727: \end{figure} fp@1727: fp@1727: \begin{description} fp@1727: \item[INIT] The state change state machine has been initialized to fp@1729: bring the slave into the INIT state. Now, the slave state change fp@1729: state machine is executed until termination. $\rightarrow$~INIT fp@1727: fp@1727: If the slave state change failed, the configuration has to be fp@1729: aborted. $\rightarrow$~END fp@1729: fp@1729: The slave state change succeeded and the slave is now in INIT state. fp@1729: If this is the target state, the configuration is finished. fp@1729: $\rightarrow$~END fp@1727: fp@1727: If the slave does not support any sync managers, the sync manager fp@1727: configuration can be skipped. The state change state machine is fp@1729: started to bring the slave into PREOP state. fp@1729: $\rightarrow$~PREOP fp@1727: fp@1727: Sync managers are configured conforming to the sync manager category fp@1727: information provided in the slave's E$^2$PROM. The corresponding fp@1729: datagram is issued. $\rightarrow$~SYNC fp@1727: fp@1727: \item[SYNC] If the sync manager configuration datagram is accepted, fp@1727: the sync manager configuration was successful. The slave may now fp@1729: enter the PREOP state, and the state change state machine is fp@1729: started. $\rightarrow$~PREOP fp@1727: fp@1727: \item[PREOP] The state change state machine is executed until fp@1729: termination. $\rightarrow$~PREOP fp@1727: fp@1727: If the state change failed, the configuration has to be aborted. fp@1729: $\rightarrow$~END fp@1729: fp@1729: If the PREOP state was the target state, the configuration is fp@1729: finished. $\rightarrow$~END fp@1727: fp@1727: If the slave supports no FMMUs, the FMMU configuration can be fp@1727: skipped. If the slave has SDOs to configure, it is begun with fp@1729: sending the first SDO. $\rightarrow$~SDO\_CONF fp@1727: fp@1727: If no SDO configurations are provided, the slave can now directly be fp@1729: brought into the SAVEOP state and the state change state machine is fp@1729: started again. $\rightarrow$~SAVEOP fp@1727: fp@1727: Otherwise, all supported FMMUs are configured according to the PDOs fp@1727: requested via the master's realtime interface. The appropriate fp@1729: datagram is issued. $\rightarrow$~FMMU fp@1727: fp@1727: \item[FMMU] The FMMU configuration datagram was accepted. If the slave fp@1727: has SDOs to configure, it is begun with sending the first SDO. fp@1729: $\rightarrow$~SDO\_CONF fp@1729: fp@1729: Otherwise, the slave can now be brought into the SAVEOP state. The fp@1729: state change state machine is started. fp@1729: $\rightarrow$~SAVEOP fp@1727: fp@1727: \item[SDO\_CONF] The CoE state machine is executed until termination. fp@1729: $\rightarrow$~SDO\_CONF fp@1727: fp@1727: If another SDO has to be configured, a new SDO download sequence is fp@1729: begun. $\rightarrow$~SDO\_CONF fp@1729: fp@1729: Otherwise, the slave can now be brought into the SAVEOP state. The fp@1729: state change state machine is started. fp@1729: $\rightarrow$~SAVEOP fp@1727: fp@1727: \item[SAVEOP] The state change state machine is executed until fp@1729: termination. $\rightarrow$~SAVEOP fp@1727: fp@1727: If the state change failed, the configuration has to be aborted. fp@1729: $\rightarrow$~END fp@1729: fp@1729: If the SAVEOP state was the target state, the configuration is fp@1729: finished. $\rightarrow$~END fp@1729: fp@1729: The slave can now directly be brought into the OP state and the fp@1729: state change state machine is started a last time. fp@1729: $\rightarrow$~OP fp@1727: fp@1727: \item[OP] The state change state machine is executed until fp@1729: termination. $\rightarrow$~OP fp@1727: fp@1727: If the state change state machine terminates, the slave fp@1727: configuration is finished, regardless of its success. fp@1729: $\rightarrow$~END fp@1727: fp@1727: \item[END] The termination state. fp@1727: fp@1727: \end{description} fp@1727: fp@1727: %------------------------------------------------------------------------------ fp@1727: fp@1727: \subsection{The State Change State Machine} fp@1727: \label{sec:fsm-change} fp@1727: \index{FSM!State Change} fp@1727: fp@1727: The state change state machine, which can be seen in fp@1727: figure~\ref{fig:fsm-change}, leads through the process of changing a fp@1727: slave's state. This implements the states and transitions described in fp@1727: \cite[section~6.4.1]{alspec}. fp@1727: fp@1727: \begin{figure}[htbp] fp@1727: \centering fp@1727: \includegraphics[width=.9\textwidth]{images/fsm-change} fp@1727: \caption{Transition diagram of the state change state machine} fp@1727: \label{fig:fsm-change} fp@1727: \end{figure} fp@1727: fp@1727: \begin{description} fp@1727: \item[START] The beginning state, where a datagram with the state fp@1727: change command is written to the slave's ``AL Control Request'' fp@1729: attribute. Nothing can fail. $\rightarrow$~CHECK fp@1727: fp@1727: \item[CHECK] After the state change datagram has been sent, the ``AL fp@1727: Control Response'' attribute is queried with a second datagram. fp@1729: $\rightarrow$~STATUS fp@1727: fp@1727: \item[STATUS] The read memory contents are evaluated: While the fp@1727: parameter \textit{State} still contains the old slave state, the fp@1727: slave is busy with reacting on the state change command. In this fp@1727: case, the attribute has to be queried again. fp@1729: $\rightarrow$~STATUS fp@1727: fp@1727: In case of success, the \textit{State} parameter contains the new fp@1727: state and the \textit{Change} bit is cleared. The slave is in the fp@1729: requested state. $\rightarrow$~END fp@1727: fp@1727: If the slave can not process the state change, the \textit{Change} fp@1727: bit is set: Now the master tries to get the reason for this by fp@1727: querying the \textit{AL Status Code} parameter. fp@1729: $\rightarrow$~CODE fp@1727: fp@1727: \item[END] If the state machine ends in this state, the slaves's state fp@1727: change has been successful. fp@1727: fp@1727: \item[CODE] The status code query has been sent. Reading the fp@1727: \textit{AL Status Code} might fail, because not all slaves support fp@1727: this parameter. Anyway, the master has to acknowledge the state fp@1727: change error by writing the current slave state to the ``AL Control fp@1727: Request'' attribute with the \textit{Acknowledge} bit set. fp@1729: $\rightarrow$~ACK fp@1727: fp@1727: \item[ACK] After that, the ``AL Control Response'' attribute is fp@1727: queried for the state of the acknowledgement. fp@1729: $\rightarrow$~CHECK ACK fp@1727: fp@1727: \item[CHECK ACK] If the acknowledgement has been accepted by the fp@1727: slave, the old state is kept. Still, the state change was fp@1729: unsuccessful. $\rightarrow$~ERROR fp@1727: fp@1727: If the acknowledgement is ignored by the slave, a timeout happens. fp@1727: In any case, the overall state change was unsuccessful. fp@1729: $\rightarrow$~ERROR fp@1727: fp@1727: If there is still now response from the slave, but the timer did not fp@1727: run out yet, the slave's ``AL Control Response'' attribute is fp@1729: queried again. $\rightarrow$~CHECK ACK fp@1727: fp@1727: \item[ERROR] If the state machine ends in this state, the slave's fp@1727: state change was unsuccessful. fp@1727: fp@1727: \end{description} fp@1727: fp@1727: %------------------------------------------------------------------------------ fp@1727: fp@1727: \subsection{The SII State Machine} fp@1727: \label{sec:fsm-sii} fp@1727: \index{FSM!SII} fp@1727: fp@1727: The SII\index{SII} state machine (shown in figure~\ref{fig:fsm-sii}) fp@1727: implements the process of reading or writing E$^2$PROM data via the fp@1727: Slave Information Interface described in \cite[section~5.4]{alspec}. fp@1727: fp@1727: \begin{figure}[htbp] fp@1727: \centering fp@1727: \includegraphics[width=.9\textwidth]{images/fsm-sii} fp@1727: \caption{Transition diagram of the SII state machine} fp@1727: \label{fig:fsm-sii} fp@1727: \end{figure} fp@1727: fp@1727: \begin{description} fp@1727: \item[READ\_START] The beginning state for reading access, where the fp@1727: read request and the requested address are written to the SII fp@1727: attribute. Nothing can fail up to now. fp@1729: $\rightarrow$~READ\_CHECK fp@1727: fp@1727: \item[READ\_CHECK] When the SII read request has been sent fp@1727: successfully, a timer is started. A check/fetch datagram is issued, fp@1727: that reads out the SII attribute for state and data. fp@1729: $\rightarrow$~READ\_FETCH fp@1727: fp@1727: \item[READ\_FETCH] Upon reception of the check/fetch datagram, the fp@1727: \textit{Read Operation} and \textit{Busy} parameters are checked: fp@1727: \begin{itemize} fp@1727: \item If the slave is still busy with fetching E$^2$PROM data into fp@1727: the interface, the timer is checked. If it timed out, the reading fp@1729: is aborted ($\rightarrow$~ERROR), if not, the check/fetch datagram fp@1729: is issued again. $\rightarrow$~READ\_FETCH fp@1727: fp@1727: \item If the slave is ready with reading data, these are copied from fp@1727: the datagram and the read cycle is completed. fp@1729: $\rightarrow$~END fp@1727: \end{itemize} fp@1727: \end{description} fp@1727: fp@1727: The write access states behave nearly the same: fp@1727: fp@1727: \begin{description} fp@1727: \item[WRITE\_START] The beginning state for writing access, fp@1727: respectively. A write request, the target address and the data word fp@1727: are written to the SII attribute. Nothing can fail. fp@1729: $\rightarrow$~WRITE\_CHECK fp@1727: fp@1727: \item[WRITE\_CHECK] When the SII write request has been sent fp@1727: successfully, the timer is started. A check datagram is issued, that fp@1727: reads out the SII attribute for the state of the write operation. fp@1729: $\rightarrow$~WRITE\_CHECK2 fp@1727: fp@1727: \item[WRITE\_CHECK2] Upon reception of the check datagram, the fp@1727: \textit{Write Operation} and \textit{Busy} parameters are checked: fp@1727: \begin{itemize} fp@1727: \item If the slave is still busy with writing E$^2$PROM data, the fp@1727: timer is checked. If it timed out, the operation is aborted fp@1729: ($\rightarrow$~ERROR), if not, the check datagram is issued again. fp@1729: $\rightarrow$~WRITE\_CHECK2 fp@1727: \item If the slave is ready with writing data, the write cycle is fp@1729: completed. $\rightarrow$~END fp@1727: \end{itemize} fp@1727: \end{description} fp@1727: fp@1727: %------------------------------------------------------------------------------ fp@1727: fp@1727: \section{Mailbox Protocol Implementations} fp@1727: \index{Mailbox} fp@1727: fp@1727: The EtherCAT master implements the EoE and the CoE mailbox fp@1727: protocols. See the below section for details. fp@1727: fp@1727: %------------------------------------------------------------------------------ fp@1727: fp@1727: \subsection{Ethernet-over-EtherCAT (EoE)} fp@1727: \label{sec:eoeimp} fp@1727: \index{EoE} fp@1727: fp@1727: The EtherCAT master implements the Ethernet-over-EtherCAT mailbox fp@1727: protocol to enable the tunneling of Ethernet frames to special slaves, fp@1727: that can either have physical Ethernet ports to forward the frames to, fp@1727: or have an own IP stack to receive the frames. fp@1727: fp@1727: \paragraph{Virtual Network Interfaces} fp@1727: fp@1727: The master creates a virtual EoE network interface for every fp@1727: EoE-capable slave. These interfaces are called \textit{eoeX}, where X fp@1727: is a number provided by the kernel on interface registration. Frames fp@1727: sent to these interfaces are forwarded to the associated slaves by the fp@1727: master. Frames, that are received by the slaves, are fetched by the fp@1727: master and forwarded to the virtual interfaces. fp@1727: fp@1727: This bears the following advantages: fp@1727: fp@1727: \begin{itemize} fp@1727: \item Flexibility: The user can decide, how the EoE-capable slaves are fp@1727: interconnected with the rest of the world. fp@1727: \item Standard tools can be used to monitor the EoE activity and to fp@1727: configure the EoE interfaces. fp@1727: \item The Linux kernel's layer-2-bridging implementation (according to fp@1727: the IEEE 802.1D MAC Bridging standard) can be used natively to fp@1727: bridge Ethernet traffic between EoE-capable slaves. fp@1727: \item The Linux kernel's network stack can be used to route packets fp@1727: between EoE-capable slaves and to track security issues, just like fp@1727: having physical network interfaces. fp@1727: \end{itemize} fp@1727: fp@1727: \paragraph{EoE Handlers} fp@1727: fp@1727: The virtual EoE interfaces and the related functionality is encapsuled fp@1727: in the \textit{ec\_eoe\_t} class (see section~\ref{sec:class-eoe}). fp@1727: So the master does not create the network interfaces directly: This is fp@1727: done inside the constructor of the \textit{ec\_eoe\_t} class. An fp@1727: object of this class is called ``EoE handler'' below. An EoE handler fp@1727: additionaly contains a frame queue. Each time, the kernel passes a new fp@1727: socket buffer for sending via the interface's fp@1727: \textit{hard\_start\_xmit()} callback, the socket buffer is queued for fp@1727: transmittion by the EoE state machine (see below). If the queue gets fp@1727: filled up, the passing of new socket buffers is suspended with a call fp@1727: to \textit{netif\_stop\_queue()}. fp@1727: fp@1727: \paragraph{Static Handler Creation} fp@1727: fp@1727: The master creates a pool of EoE handlers at startup, that are coupled fp@1727: to EoE-capable slaves on demand. The lifetime of the corresponding fp@1727: network interfaces is equal to the lifetime of the master module. fp@1727: This approach is opposed to creating the virtual network interfaces on fp@1727: demand (i.~e. on running across a new EoE-capable slave). The latter fp@1727: approach was considered as difficult, because of serveral reasons: fp@1727: fp@1727: \begin{itemize} fp@1727: \item The \textit{alloc\_netdev()} function can sleep and must be fp@1727: called from a non-interrupt context. This reduces the flexibility of fp@1727: choosing an appropriate method for cyclic EoE processing. fp@1727: \item Unregistering network interfaces requires them to be ``down'', fp@1727: which can not be guaranteed upon sudden disappearing of an fp@1727: EoE-capable slave. fp@1727: \item The connection to the EoE-capable slaves must be as continuous fp@1727: as possible. Especially the transition from idle to operation mode fp@1727: (and vice versa) causes the rebuilding of the internal data fp@1727: structures. These transitions must be as transparent as possible for fp@1727: the instances using the network interfaces. fp@1727: \end{itemize} fp@1727: fp@1727: \paragraph{Number of Handlers} fp@1727: fp@1727: The master module has a parameter \textit{ec\_eoeif\_count} to specify fp@1727: the number of EoE interfaces (and handlers) per master to create. This fp@1727: parameter can either be specified when manually loading the master fp@1727: module, or (when using the init script) by setting the fp@1729: \$EOE\_INTERFACES variable in the sysconfig file (see fp@1727: section~\ref{sec:sysconfig}). Upon loading of the master module, the fp@1727: virtual interfaces become available: fp@1727: fp@1727: \begin{lstlisting} fp@1729: # `\textbf{ifconfig -a}` fp@1727: eoe0 Link encap:Ethernet HWaddr 00:11:22:33:44:06 fp@1727: BROADCAST MULTICAST MTU:1500 Metric:1 fp@1727: RX packets:0 errors:0 dropped:0 overruns:0 frame:0 fp@1727: TX packets:0 errors:0 dropped:0 overruns:0 carrier:0 fp@1727: collisions:0 txqueuelen:1000 fp@1727: RX bytes:0 (0.0 b) TX bytes:0 (0.0 b) fp@1727: fp@1727: eoe1 Link encap:Ethernet HWaddr 00:11:22:33:44:07 fp@1727: BROADCAST MULTICAST MTU:1500 Metric:1 fp@1727: RX packets:0 errors:0 dropped:0 overruns:0 frame:0 fp@1727: TX packets:0 errors:0 dropped:0 overruns:0 carrier:0 fp@1727: collisions:0 txqueuelen:1000 fp@1727: RX bytes:0 (0.0 b) TX bytes:0 (0.0 b) fp@1727: ... fp@1727: \end{lstlisting} fp@1727: fp@1727: \paragraph{Coupling of EoE Slaves} fp@1727: fp@1727: During execution of the slave scan state machine (see fp@1727: section~\ref{sec:fsm-scan}), the master determines the supported fp@1727: mailbox protocols. This is done by examining the ``Supported Mailbox fp@1727: Protocols'' mask field at word address 0x001C of the SII\index{SII}. fp@1727: If bit 1 is set, the slave supports the EoE protocol. After slave fp@1727: scanning, the master runs through all slaves again and couples each fp@1727: EoE-capable slave to a free EoE handler. It can happen, that there are fp@1727: not enough EoE handlers to cover all EoE-capable slaves. In this case, fp@1727: the number of EoE handlers must be increased accordingly. fp@1727: fp@1727: \paragraph{EoE State Machine} fp@1727: \index{FSM!EoE} fp@1727: fp@1727: Every EoE handler owns an EoE state machine, that is used to send fp@1727: frames to the coupled slave and receive frames from the it via the EoE fp@1727: communication primitives. This state machine is showed in fp@1727: figure~\ref{fig:fsm-eoe}. fp@1727: fp@1727: \begin{figure}[htbp] fp@1727: \centering fp@1727: \includegraphics[width=.7\textwidth]{images/fsm-eoe} fp@1727: \caption{Transition diagram of the EoE state machine} fp@1727: \label{fig:fsm-eoe} fp@1727: \end{figure} fp@1727: fp@1727: \begin{description} fp@1727: \item[RX\_START] The beginning state of the EoE state machine. A fp@1727: mailbox check datagram is sent, to query the slave's mailbox for new fp@1729: frames. $\rightarrow$~RX\_CHECK fp@1727: fp@1727: \item[RX\_CHECK] The mailbox check datagram is received. If the fp@1727: slave's mailbox did not contain data, a transmit cycle is started. fp@1729: $\rightarrow$~TX\_START fp@1727: fp@1727: If there are new data in the mailbox, a datagram is sent to fetch fp@1729: the new data. $\rightarrow$~RX\_FETCH fp@1727: fp@1727: \item[RX\_FETCH] The fetch datagram is received. If the mailbox data fp@1727: do not contain a ``EoE Fragment request'' command, the data are fp@1727: dropped and a transmit sequence is started. fp@1729: $\rightarrow$~TX\_START fp@1727: fp@1727: If the received Ethernet frame fragment is the first fragment, a new fp@1727: socket buffer is allocated. In either case, the data are copied into fp@1727: the correct position of the socket buffer. fp@1727: fp@1727: If the fragment is the last fragment, the socket buffer is forwarded fp@1727: to the network stack and a transmit sequence is started. fp@1729: $\rightarrow$~TX\_START fp@1727: fp@1727: Otherwise, a new receive sequence is started to fetch the next fp@1729: fragment. $\rightarrow$~RX\_\-START fp@1727: fp@1727: \item[TX\_START] The beginning state of a transmit sequence. It is fp@1727: checked, if the transmittion queue contains a frame to send. If not, fp@1729: a receive sequence is started. $\rightarrow$~RX\_START fp@1727: fp@1727: If there is a frame to send, it is dequeued. If the queue was fp@1727: inactive before (because it was full), the queue is woken up with a fp@1727: call to \textit{netif\_wake\_queue()}. The first fragment of the fp@1729: frame is sent. $\rightarrow$~TX\_SENT fp@1727: fp@1727: \item[TX\_SENT] It is checked, if the first fragment was sent fp@1727: successfully. If the current frame consists of further fragments, fp@1729: the next one is sent. $\rightarrow$~TX\_SENT fp@1727: fp@1727: If the last fragment was sent, a new receive sequence is started. fp@1729: $\rightarrow$~RX\_START fp@1727: \end{description} fp@1727: fp@1727: \paragraph{EoE Processing} fp@1727: fp@1727: To execute the EoE state machine of every active EoE handler, there fp@1727: must be a cyclic process. The easiest thing would be to execute the fp@1727: EoE state machines synchronously to the operation state machine (see fp@1727: section~\ref{sec:fsm-op}) with every realtime cycle. This approach has fp@1727: the following disadvantages: fp@1727: fp@1727: \begin{itemize} fp@1727: \item Only one EoE fragment can be sent or received every few cycles. fp@1727: This causes the data rate to be very low, because the EoE state fp@1727: machines are not executed in the time between the realtime fp@1727: cycles. Moreover, the data rate would be dependent on the frequency fp@1727: of the realtime process. fp@1727: \item The receiving and forwarding of frames to the kernel requires fp@1727: the dynamic allocation of frames. Some realtime extensions do not fp@1727: support calling memory allocation functions in realtime context, so fp@1727: the EoE state machine may not be executed with each realtime cycle. fp@1727: \end{itemize} fp@1727: fp@1727: To overcome these problems, an own cyclic process is needed to fp@1727: asynchronously execute the EoE state machines. For that, the master fp@1727: owns a kernel timer, that is executed each timer interrupt. This fp@1727: guarantees a constant bandwidth, but poses the new problem of fp@1727: concurrent access to the master. The locking mechanisms needed for fp@1727: this are introduced in section~\ref{sec:concurr}. fp@1727: Section~\ref{sec:concurrency} gives practical implementation examples. fp@1727: fp@1727: \paragraph{Idle Mode} fp@1727: fp@1727: EoE data must also be exchanged idle mode, to guarantee the continuous fp@1727: availability of the connection to the EoE-capable slaves. Although fp@1727: there is no realtime module connected in this case, the master is fp@1727: still accessed by the idle state machine (see fp@1727: section~\ref{sec:fsm-idle}), that is executed by the master's fp@1727: workqueue. With the EoE timer running in addition, there is still fp@1727: concurrency, that has to be protected by a lock. Therefore the master fp@1727: owns an internal spinlock that is used protect master access during fp@1727: idle mode. fp@1727: fp@1727: \paragraph{Automatic Configuration} fp@1727: fp@1729: By default, slaves are left in INIT state during idle mode. If an EoE fp@1729: interface is set to running state (i.~e. with the \textit{ifconfig up} fp@1729: command), the requested slave state of the related slave is fp@1729: automatically set to OP, whereupon the idle state machine will attempt fp@1729: to configure the slave and put it into operation. fp@1727: fp@1727: %------------------------------------------------------------------------------ fp@1727: fp@1727: \subsection{CANopen-over-EtherCAT (CoE)} fp@1727: \label{sec:coeimp} fp@1727: \index{CoE} fp@1727: fp@1727: The CANopen-over-EtherCAT protocol \cite[section~5.6]{alspec} is used fp@1727: to configure slaves on application level. Each CoE-capable slave fp@1727: provides a list of SDOs for this reason. fp@1727: fp@1727: \paragraph{SDO Configuration} fp@1727: fp@1727: The SDO configurations have to be provided by the realtime module. fp@1727: This is done via the \textit{ecrt\_slave\_conf\_sdo*()} methods (see fp@1727: section~\ref{sec:ecrt-slave}), that are part of the realtime fp@1727: interface. The slave stores the SDO configurations in a linked list, fp@1727: but does not apply them at once. fp@1727: fp@1727: \paragraph{SDO Download State Machine} fp@1727: fp@1729: The best time to apply SDO configurations is during the slave's PREOP fp@1729: state, because mailbox communication is already possible and slave's fp@1729: application will start with updating input data in the succeeding fp@1729: SAVEOP state. Therefore the SDO configuration has to be part of the fp@1729: slave configuration state machine (see section~\ref{sec:fsm-conf}): It fp@1729: is implemented via an SDO download state machine, that is executed fp@1729: just before entering the slave's SAVEOP state. In this way, it is fp@1729: guaranteed that the SDO configurations are applied each time, the fp@1729: slave is reconfigured. fp@1727: fp@1727: The transition diagram of the SDO Download state machine can be seen fp@1727: in figure~\ref{fig:fsm-coedown}. fp@1727: fp@1727: \begin{figure}[htbp] fp@1727: \centering fp@1727: \includegraphics[width=.9\textwidth]{images/fsm-coedown} fp@1727: \caption{Transition diagram of the CoE download state machine} fp@1727: \label{fig:fsm-coedown} fp@1727: \end{figure} fp@1727: fp@1727: \begin{description} fp@1727: \item[START] The beginning state of the CoE download state fp@1727: machine. The ``SDO Download Normal Request'' mailbox command is fp@1729: sent. $\rightarrow$~REQUEST fp@1727: fp@1727: \item[REQUEST] It is checked, if the CoE download request has been fp@1727: received by the slave. After that, a mailbox check command is issued fp@1729: and a timer is started. $\rightarrow$~CHECK fp@1727: fp@1727: \item[CHECK] If no mailbox data is available, the timer is checked. fp@1727: \begin{itemize} fp@1727: \item If it timed out, the SDO download is aborted. fp@1729: $\rightarrow$~ERROR fp@1727: \item Otherwise, the mailbox is queried again. fp@1729: $\rightarrow$~CHECK fp@1727: \end{itemize} fp@1727: fp@1727: If the mailbox contains new data, the response is fetched. fp@1729: $\rightarrow$~RESPONSE fp@1727: fp@1727: \item[RESPONSE] If the mailbox response could not be fetched, the data fp@1727: is invalid, the wrong protocol was received, or a ``Abort SDO fp@1727: Transfer Request'' was received, the SDO download is aborted. fp@1729: $\rightarrow$~ERROR fp@1727: fp@1727: If a ``SDO Download Normal Response'' acknowledgement was received, fp@1729: the SDO download was successful. $\rightarrow$~END fp@1727: fp@1727: \item[END] The SDO download was successful. fp@1727: fp@1727: \item[ERROR] The SDO download was aborted due to an error. fp@1727: fp@1727: \end{description} fp@1727: fp@1727: %------------------------------------------------------------------------------ fp@1727: fp@1727: \section{User Space} fp@1727: \label{sec:user} fp@1727: \index{User space} fp@1727: fp@1727: For the master runs as a kernel module, accessing it is natively fp@1727: limited to analyzing syslog messages and controlling using modutils. fp@1727: fp@1727: It is necessary to implement further interfaces, that make it easier fp@1727: to access the master from user space and allow a finer influence. It fp@1727: should be possible to view and to change special parameters at runtime. fp@1727: fp@1727: Bus visualization is a second point: For development and debugging fp@1727: purposes it would be nice, if one could show the connected slaves with fp@1727: a single command. fp@1727: fp@1727: Another aspect is automatic startup and configuration. If the master fp@1727: is to be integrated into a running system, it must be able to fp@1727: automatically start with a persistent configuration. fp@1727: fp@1727: A last thing is monitoring EtherCAT communication. For debugging fp@1727: purposes, there had to be a way to analyze EtherCAT datagrams. The fp@1727: best way would be with a popular network analyzer, like Wireshark fp@1727: \cite{wireshark} (the former Ethereal) or others. fp@1727: fp@1727: This section covers all those points and introduces the interfaces and fp@1727: tools to make all that possible. fp@1727: fp@1727: %------------------------------------------------------------------------------ fp@1727: fp@1727: \subsection{The Sysfs Interface} fp@1727: \label{sec:sysfs} fp@1727: fp@1727: The system filesystem (Sysfs\index{Sysfs}) was introduced with Linux fp@1727: kernel 2.5 and is a well-defined interface for drivers to export fp@1727: information to user space. It serves also as an relief for the process fp@1727: filesystem (Procfs), where over the years much non-process information fp@1727: was concentrated. fp@1727: fp@1727: Sysfs exports information about devices, classes and busses via a fp@1727: virtual filesystem, usually mounted to \textit{/sys}. The EtherCAT fp@1727: master slightly differs from this concept, because the only physical fp@1727: device is the network adapter it uses for bus communication, which is fp@1727: already represented in Sysfs. For the EtherCAT bus is no system bus fp@1727: like PCI (with device and driver structures), it would not make any fp@1727: sense to represent it as bus structure in Sysfs. fp@1727: fp@1727: Therefore, the EtherCAT master is represented as a new directory fp@1727: directly unter the Sysfs root. Every master gets its own Sysfs entry fp@1727: named \textit{ethercatX}, where X is the index of the master. Two fp@1727: masters would result in the directories \textit{/sys/ethercat0} and fp@1727: \textit{/sys/ethercat1}, respectively. fp@1727: fp@1727: The Sysfs base class in the kernel code is the \textit{kobject} fp@1727: structure. Each object structure, that is to be represented in Sysfs, fp@1727: has to contain such a structure, because due to the concurrent access fp@1727: (through ``normal'' kernel code and Sysfs code) the object deletion fp@1727: gets a little more complicated: The object may not be freed until no fp@1727: instance uses it any more. Therefore, each kobject maintains a fp@1727: reference counter. If the reference counter gets zero, the object is fp@1727: finally freed. A kobject can be registered to appear as a directory in fp@1727: Sysfs with a call to \textit{kobject\_add()}. Each kobject type can fp@1727: define attributes, that appear as files in the kobject's fp@1727: directory. Callback functions have to be provided for reading (and fp@1727: perhaps writing) access. fp@1727: fp@1727: \subsubsection{Master Attributes} fp@1727: \label{sec:sysfs-master} fp@1727: fp@1727: Below is a typical listing of the masters Sysfs directory (that is a fp@1727: file system representation of the master's kobject): fp@1727: fp@1727: \begin{lstlisting} fp@1729: `\$` `\textbf{ls /sys/ethercat0}` fp@1727: debug_level slave000 slave003 slave006 fp@1727: eeprom_write_enable slave001 slave004 slave007 fp@1727: info slave002 slave005 slave008 fp@1727: \end{lstlisting} fp@1727: fp@1727: The following attributes exist in the master directory: fp@1727: fp@1727: \begin{description} fp@1727: \item[debug\_level] (read/write) This attribute contains the master's fp@1727: debug level, which controls, how much information is printed into fp@1727: syslog. The values 0 (no additional debug messages), 1 (a few fp@1727: additional debug messages) and 2 (all additional debug messages) are fp@1727: defined. Writing is done with command like fp@1727: fp@1727: \begin{lstlisting}[gobble=4] fp@1729: # `\textbf{echo 1 > /sys/ethercat0/debug\_level}` fp@1727: \end{lstlisting} fp@1727: fp@1727: and is receipted with a syslog message by the master: fp@1727: fp@1727: \begin{lstlisting}[gobble=4] fp@1727: EtherCAT: Master debug level set to 1. fp@1727: \end{lstlisting} fp@1727: fp@1727: \item[enable\_eeprom\_writing] (read/write) See fp@1727: section~\ref{sec:eepromaccess} for how to use this attribute. fp@1727: fp@1727: \item[info] (read only) This attribute contains information about the fp@1727: master. Example contents are below: fp@1727: fp@1727: \begin{lstlisting}[gobble=4] fp@1729: `\$` `\textbf{cat /sys/ethercat0/info}` fp@1727: fp@1727: Mode: IDLE fp@1727: Slaves: 9 fp@1727: fp@1727: Timing (min/avg/max) [us]: fp@1727: Idle cycle: 4 / 4.38 / 34 fp@1727: EoE cycle: 9 / 11.91 / 23 fp@1727: fp@1727: EoE statistics (RX/TX) [bps]: fp@1727: eoe0: 0 / 3184 fp@1727: \end{lstlisting} fp@1727: fp@1727: The mode can be \textit{ORPHANED}, \textit{IDLE} or fp@1727: \textit{OPERATION}. The other parameters are self-explanatory. fp@1727: fp@1727: \end{description} fp@1727: fp@1727: \subsubsection{Domain Attributes} fp@1727: \label{sec:sysfs-domain} fp@1727: fp@1727: In operation mode, each created domain is represented as a directory fp@1727: \textit{domainX}, where X is the domain index. Below is a listing of fp@1727: the domain directory contents: fp@1727: fp@1727: \begin{lstlisting} fp@1729: `\$` `\textbf{ls /sys/ethercat0/domain0}` fp@1727: image_size fp@1727: \end{lstlisting} fp@1727: fp@1727: The domain directories currently only export the domain's image size. fp@1727: It is planned to export the whole process data mapping for debugging fp@1727: purposes. fp@1727: fp@1727: \subsubsection{Slave Attributes} fp@1727: \label{sec:sysfs-slave} fp@1727: fp@1727: Each slave on the bus is represented in its own directory fp@1727: \textit{slaveXXX}, where XXX is the slave's 3-digit ring position in fp@1727: the EtherCAT bus. Below is a listing of a slave directory: fp@1727: fp@1727: \begin{lstlisting} fp@1729: `\$` `\textbf{ls /sys/ethercat0/slave003}` fp@1727: eeprom info state fp@1727: \end{lstlisting} fp@1727: fp@1727: \begin{description} fp@1727: \item[eeprom] (read/write) See section~\ref{sec:eepromaccess} for how fp@1727: to use this attribute. fp@1727: fp@1727: \item[info] (read only) This attribute contains a bunch of information fp@1727: about the slave. Below is an example output: fp@1727: fp@1727: \begin{lstlisting}[gobble=4] fp@1729: `\$` `\textbf{cat /sys/ethercat0/slave003/info}` fp@1727: fp@1727: Name: EL4132 2K. Ana. Ausgang +/-10V fp@1727: Vendor ID: 0x00000002 fp@1727: Product code: 0x10243052 fp@1727: fp@1727: State: INIT fp@1727: Ring position: 3 fp@1727: Advanced position: 1:3 fp@1727: fp@1727: Data link status: fp@1727: Port 0 (EBUS) Link down, Loop open, Signal detected fp@1727: Port 1 (EBUS) Link down, Loop open, Signal detected fp@1727: Port 2 (EBUS) Link down, Loop closed, No signal fp@1727: Port 3 (EBUS) Link down, Loop closed, No signal fp@1727: fp@1727: Mailboxes: fp@1727: RX mailbox: 0x1800/246, TX mailbox: 0x18F6/246 fp@1727: Supported protocols: CoE, FoE fp@1727: fp@1727: SII data: fp@1727: Group: AnaOut fp@1727: Image: TERM_AO fp@1727: Order#: EL4132 fp@1727: fp@1727: Sync-Managers: fp@1727: 0: 0x1800, length 246, control 0x26, enable fp@1727: 1: 0x18F6, length 246, control 0x22, enable fp@1727: 2: 0x1000, length 0, control 0x24, enable fp@1727: 3: 0x1100, length 0, control 0x20, enable fp@1727: fp@1727: PDOs: fp@1727: RXPDO "Channel 1" (0x1600), Sync-Manager 2 fp@1727: "Output" 0x6411:1, 16 bit fp@1727: RXPDO "Channel 2" (0x1601), Sync-Manager 2 fp@1727: "Output" 0x6411:2, 16 bit fp@1727: \end{lstlisting} fp@1727: fp@1727: This is nearly all of the SII category information needed to fp@1727: configure the slave, supplemented with state and addressing fp@1727: information. fp@1727: fp@1727: \item[state] (read/write) This attribute contains the slave's state. fp@1727: It can be read or written: fp@1727: fp@1727: \begin{lstlisting}[gobble=4] fp@1729: # `\textbf{cat /sys/ethercat0/slave003/state}` fp@1727: OP fp@1729: # `\textbf{echo SAVEOP > /sys/ethercat0/slave003/state}` fp@1727: \end{lstlisting} fp@1727: fp@1727: This command should also be receipted with a syslog message: fp@1727: fp@1727: \begin{lstlisting}[gobble=4] fp@1727: EtherCAT: Accepted new state SAVEOP for slave 3. fp@1727: EtherCAT: Changing state of slave 3 from OP to SAVEOP. fp@1727: EtherCAT: Slave states: INIT, SAVEOP, OP. fp@1727: \end{lstlisting} fp@1727: fp@1727: After the new requested state was accepted from user space, the fp@1727: operation state machine (see section~\ref{sec:fsm-op}) or the idle fp@1727: state machine (section~\ref{sec:fsm-idle}) notices, that the fp@1727: requested slave state differs from the current one, and therefore fp@1727: executes the slave configuration state machine, until the slave has fp@1727: reached the requested state. fp@1727: \end{description} fp@1727: fp@1727: %------------------------------------------------------------------------------ fp@1727: fp@1727: \subsubsection{E$^2$PROM Access} fp@1727: \label{sec:eepromaccess} fp@1727: \index{E$^2$PROM!Access} fp@1727: fp@1727: It is possible to directly read or write the complete E$^2$PROM fp@1727: contents of the slaves. This was introduced for the reasons below: fp@1727: fp@1727: \begin{itemize} fp@1727: \item The format of the E$^2$PROM data is still in development and fp@1727: categories can be added in the future. With read and write access, fp@1727: the complete memory contents can be easily backed up and restored. fp@1727: \item Some E$^2$PROM data fields have to be altered (like the alias fp@1727: address). A quick writing must be possible for that. fp@1727: \item Through read access, analyzing category data is possible from fp@1727: user space. fp@1727: \end{itemize} fp@1727: fp@1727: Reading out E$^2$PROM data is as easy as reading other fp@1727: attributes. Though the data are in binary format, analyzation is fp@1727: easier with a tool like \textit{hexdump}: fp@1727: fp@1727: \begin{lstlisting} fp@1729: `\$` `\textbf{cat /sys/ethercat0/slave003/eeprom | hexdump}` fp@1727: 0000000 0103 0000 0000 0000 0000 0000 0000 008c fp@1727: 0000010 0002 0000 3052 07f0 0000 0000 0000 0000 fp@1727: 0000020 0000 0000 0000 0000 0000 0000 0000 0000 fp@1727: ... fp@1727: \end{lstlisting} fp@1727: fp@1727: Backing up E$^2$PROM contents gets as easy as copying a file: fp@1727: fp@1727: \begin{lstlisting} fp@1729: `\$` `\textbf{cp /sys/ethercat0/slave003/eeprom slave003.eep}` fp@1727: \end{lstlisting} fp@1727: fp@1727: Writing access is only possible as \textit{root}. Moreover writing has fp@1727: to be explicitly enabled and is only allowed in idle mode. This is a fp@1727: safety measure, because without the correct memory contents, a slave fp@1727: is unusable. Writing E$^2$PROM contents in operation mode is not fp@1727: provided yet. fp@1727: fp@1727: E$^2$PROM writing is enabled with the command below: fp@1727: fp@1727: \begin{lstlisting} fp@1729: # `\textbf{echo 1 > /sys/ethercat0/eeprom\_write\_enable}` fp@1727: \end{lstlisting} fp@1727: fp@1727: The success can be seen in the syslog messages again: fp@1727: fp@1727: \begin{lstlisting} fp@1727: EtherCAT: Slave EEPROM writing enabled. fp@1727: \end{lstlisting} fp@1727: fp@1727: Now, it is possible to write E$^2$PROM contents to a slave. The master fp@1727: will accept data through the \textit{eeprom} file and will perform a fp@1727: short validation of the contents, before starting the write operation. fp@1727: This validation checks the complete size and the category headers. fp@1727: fp@1727: \begin{lstlisting} fp@1729: # `\textbf{cat slave003.eep > /sys/ethercat0/slave003/eeprom}` fp@1727: \end{lstlisting} fp@1727: fp@1727: The write operation can take a few seconds. fp@1727: fp@1727: \begin{lstlisting} fp@1727: EtherCAT: EEPROM writing scheduled for slave 3, 88 words. fp@1727: EtherCAT: Writing EEPROM of slave 3... fp@1727: EtherCAT: Finished writing EEPROM of slave 3. fp@1727: \end{lstlisting} fp@1727: fp@1727: %------------------------------------------------------------------------------ fp@1727: fp@1727: \subsection{User Space Tools} fp@1727: \index{User space!Tools} fp@1727: fp@1727: There is a user space tool called \textit{lsec}\index{lsec} (``List fp@1727: EtherCAT'') to visualize the EtherCAT bus. Running it usually results fp@1727: in an output like this: fp@1727: fp@1727: \begin{lstlisting} fp@1729: `\$` `\textbf{lsec}` fp@1727: EtherCAT bus listing for master 0: fp@1727: 0 1:0 OP EK1100 Ethernet Kopplerklemme (2A E-Bus) fp@1727: 1 1:1 INIT EL4132 2K. Ana. Ausgang +/-10V fp@1727: 2 1:2 INIT EL4132 2K. Ana. Ausgang +/-10V fp@1727: 3 1:3 SAVEOP EL4132 2K. Ana. Ausgang +/-10V fp@1727: 4 1:4 INIT EL5101 Incremental Encoder Interface fp@1727: 5 1:5 INIT EL1014 4K. Dig. Eingang 24V, 10s fp@1727: 6 1:6 OP EL6601 1 Port Switch (Ethernet, CoE) fp@1727: 7 1:7 INIT EL5101 Incremental Encoder Interface fp@1727: 8 1:8 INIT EL5001 1K. SSI Encoder fp@1727: \end{lstlisting} fp@1727: fp@1727: Every slave is displayed as one text row. The first column shows its fp@1727: ring position, the second displays the ``advanced position address'' fp@1727: (see section~\ref{sec:addr}) and the third column displays the current fp@1727: slave state. The last column is the slave's name, as it appears in the fp@1727: ``general'' E$^2$PROM category. fp@1727: fp@1727: The lsec program is a Perl script, that evaluates the Sysfs fp@1727: \textit{info} attributes of the slaves (see fp@1727: section~\ref{sec:sysfs-slave}). This is done for master $0$ by fp@1727: default, but the master index can be specified via command line: fp@1727: fp@1727: \begin{lstlisting} fp@1729: `\$` `\textbf{lsec -h}` fp@1727: Usage: ec_list [OPTIONS] fp@1727: -m Query master . fp@1727: -h Show this help. fp@1727: \end{lstlisting} fp@1727: fp@1727: This script has proved as useful for troubleshooting: If it displays fp@1727: slaves, the master is up and running, and the bus connection is fp@1727: present, too. It is also useful when building up a bus: It can verify fp@1727: the list of slaves and help to create a process data image (see fp@1727: chapter~\ref{chapter:usage}). fp@1727: fp@1727: %------------------------------------------------------------------------------ fp@1727: fp@1727: \subsection{System Integration} fp@1727: \label{sec:system} fp@1727: fp@1727: To integrate the EtherCAT master into a running system, it has to be fp@1727: guaranteed, that it is started on system startup. In addition, there has fp@1727: to be a persistent configuration, that is also applied on startup. fp@1727: fp@1727: \subsubsection{The EtherCAT Init Script} fp@1727: \label{sec:init} fp@1727: \index{Init script} fp@1727: fp@1727: The EtherCAT master provides an ``init script'', that conforms to the fp@1727: requirements of the ``Linux Standard Base'' (LSB\index{LSB}, fp@1727: \cite{lsb}). The script is installed to \textit{etc/init.d/ethercat} fp@1727: below the installation prefix and has to be copied to the appropriate fp@1727: location (see section~\ref{sec:make}), before the master can be fp@1727: inserted as a service. The different Linux distributions offer fp@1727: different ways to mark the service for starting and stopping in fp@1727: certain runlevels (for example, SUSE Linux provides the fp@1727: \textit{insserv} command). fp@1727: fp@1727: To provide service dependencies (i.~e. which services have to be fp@1727: started before) right inside the init script code, LSB defines a fp@1727: special comment block. System tools can extract this information to fp@1727: insert the EtherCAT init script at the correct place in the startup fp@1727: sequence: fp@1727: fp@1727: \begin{lstlisting} fp@1727: ### BEGIN INIT INFO fp@1727: # Provides: ethercat fp@1727: # Required-Start: $local_fs $syslog $network fp@1727: # Should-Start: $time fp@1727: # Required-Stop: $local_fs $syslog $network fp@1727: # Should-Stop: $time fp@1727: # Default-Start: 3 5 fp@1727: # Default-Stop: 0 1 2 6 fp@1727: # Short-Description: EtherCAT master modules fp@1727: # Description: fp@1727: ### END INIT INFO fp@1727: \end{lstlisting} fp@1727: fp@1727: The init script can also be used for manually starting and stopping fp@1727: the EtherCAT master. It has to be executed with one of the parameters fp@1729: \texttt{start}, \texttt{stop}, \texttt{restart} or \texttt{status}. fp@1727: fp@1727: \begin{lstlisting} fp@1729: # `\textbf{/etc/init.d/ethercat restart}` fp@1727: Shutting down EtherCAT master done fp@1727: Starting EtherCAT master done fp@1727: \end{lstlisting} fp@1727: fp@1727: \subsubsection{The EtherCAT Sysconfig File} fp@1727: \label{sec:sysconfig} fp@1727: \index{Sysconfig file} fp@1727: fp@1727: For persistent configuration, the init script uses a sysconfig file fp@1727: installed to \textit{etc/sysconfig/ethercat} (below the installation fp@1727: prefix), that is mandatory for the init script. The sysconfig file fp@1727: contains all configuration variables needed to operate a master: fp@1727: fp@1727: \begin{description} fp@1727: \item[DEVICE\_INDEX] This variable must contain the PCI index of the fp@1727: EtherCAT device. Setting this is mandatory for the EtherCAT init fp@1727: script. Default: $-1$ fp@1727: \item[EOE\_INTERFACES] The number of virtual Ethernet-over-EtherCAT fp@1727: interfaces, every master creates on startup. See fp@1727: section~\ref{sec:eoeimp}. Default: $0$ fp@1727: \item[EOE\_BRIDGE] If this variable is set, all EoE interfaces will be fp@1727: added to a network bridge according to IEEE 802.1D after master fp@1727: startup. The variable must contain the name of the bridge. To use fp@1727: this functionality, the kernel must be configured with the fp@1729: CONFIG\_BRIDGE option and the \textit{bridge-utils} package must be fp@1729: installed (i.~e. the \textit{brctl} command is needed). fp@1727: \item[EOE\_IP\_ADDRESS] The IP address of the EoE bridge. Setting this fp@1729: together with \$EOE\_IP\_NETMASK will let the local host communicate fp@1729: with devices on the EoE bridge. fp@1727: \item[EOE\_IP\_NETMASK] IP netmask of the EoE bridge. fp@1727: \item[EOE\_EXTRA\_INTERFACES] The list of extra interfaces to include fp@1727: in the EoE brid\-ge. Set this to interconnect the EoE bridge with fp@1729: other local interfaces. If \$EOE\_\-BRIDGE is empty or undefined, fp@1729: setting this variable has no effect. Important: The IP address of fp@1729: the listed interfaces will be cleared. Setting fp@1729: \$EOE\_\-IP\_\-ADDRESS and \$EOE\_IP\_NETMASK will re-enable them fp@1729: for IP traffic. fp@1727: \item[EOE\_GATEWAY] The IP address of the default gateway. If this fp@1727: variable is set, the gateway will be renewed after bridge fp@1727: installation. This is necessary, if the default gateway's interface fp@1729: is one of the \$EOE\_EXTRA\_INTERFACES. fp@1727: \end{description} fp@1727: fp@1727: %------------------------------------------------------------------------------ fp@1727: fp@1727: \subsection{Monitoring and Debugging} fp@1727: \label{sec:debug} fp@1727: \index{Monitoring} fp@1727: fp@1727: For debugging purposes, every EtherCAT master registeres a read-only fp@1727: network interface \textit{ecX}, where X is a number, provided by the fp@1727: kernel on device registration. While it is ``up'', the master forwards fp@1727: every frame sent and received to this interface. fp@1727: fp@1727: This makes it possible to connect an network monitor (like Wireshark fp@1727: or tcpdump) to the debug interface and monitor the EtherCAT frames. fp@1727: fp@1727: It has to be considered, that can be frame rate can be very high. The fp@1727: idle state machine usually runs every kernel timer interrupt (up to fp@1727: $1$~kHz) and with a connected realtime module, the rate can be even fp@1727: higher. fp@1727: fp@1727: \paragraph{Attention:} The socket buffers needed for the operation of fp@1727: the debugging interface have to be allocated dynamically. Some Linux fp@1727: realtime extensions do not allow this in realtime context! fp@1727: fp@1727: %------------------------------------------------------------------------------ fp@1727: fp@1727: \section{Timing Aspects} fp@1727: \label{sec:timing} fp@1727: fp@1727: Although EtherCAT's timing is highly deterministic and therefore fp@1727: timing issues are rare, there are a few aspects that can (and should fp@1727: be) dealt with. fp@1727: fp@1727: %------------------------------------------------------------------------------ fp@1727: fp@1727: \subsection{Realtime Interface Profiling} fp@1727: \label{sec:timing-profile} fp@1727: \index{Realtime!Profiling} fp@1727: fp@1727: One of the most important timing aspects are the runtimes of the fp@1727: realtime interface functions, that are called in cyclic context. These fp@1727: functions make up an important part of the overall timing of the fp@1727: realtime module. To measure the timing of the functions, the following fp@1727: code was used: fp@1727: fp@1727: \begin{lstlisting}[gobble=2,language=C] fp@1727: c0 = get_cycles(); fp@1727: ecrt_master_receive(master); fp@1727: c1 = get_cycles(); fp@1727: ecrt_domain_process(domain1); fp@1727: c2 = get_cycles(); fp@1727: ecrt_master_run(master); fp@1727: c3 = get_cycles(); fp@1727: ecrt_master_send(master); fp@1727: c4 = get_cycles(); fp@1727: \end{lstlisting} fp@1727: fp@1727: Between each call of an interface function, the CPU timestamp counter fp@1727: is read. The counter differences are converted to microseconds with fp@1727: help of the \textit{cpu\_khz} variable, that contains the number of fp@1727: increments per millisecond. fp@1727: fp@1727: For the actual measuring, a system with a $2.0$~GHz CPU was used, that fp@1727: ran the above code in an RTAI thread with a cycle time of $100$ fp@1727: \textmu s. The measuring was repeated $n = 100$ times and the results fp@1727: were averaged. These can be seen in table~\ref{tab:profile}. fp@1727: fp@1727: \begin{table}[htpb] fp@1727: \centering fp@1727: \caption{Profiling of a Realtime Cycle on a $2.0$~GHz Processor} fp@1727: \label{tab:profile} fp@1727: \vspace{2mm} fp@1727: \begin{tabular}{l|r|r} fp@1727: Element & Mean Duration [\textmu s] & Standard Deviancy [\textmu s] \\ fp@1727: \hline fp@1727: \textit{ecrt\_master\_receive()} & 8.04 & 0.48\\ fp@1727: \textit{ecrt\_domain\_process()} & 0.14 & 0.03\\ fp@1727: \textit{ecrt\_master\_run()} & 0.29 & 0.12\\ fp@1727: \textit{ecrt\_master\_send()} & 2.18 & 0.17\\ \hline fp@1727: Complete Cycle & 10.65 & 0.69\\ \hline fp@1727: \end{tabular} fp@1727: \end{table} fp@1727: fp@1727: It is obvious, that the the functions accessing hardware make up the fp@1727: lion's share. The \textit{ec\_master\_receive()} executes the ISR of fp@1727: the Ethernet device, analyzes datagrams and copies their contents into fp@1727: the memory of the datagram objects. The \textit{ec\_master\_send()} fp@1727: assembles a frame out of different datagrams and copies it to the fp@1727: hardware buffers. Interestingly, this makes up only a quarter of the fp@1727: receiving time. fp@1727: fp@1727: The functions that only operate on the masters internal data fp@1727: structures are very fast ($\Delta t < 1$~\textmu s). Interestingly the fp@1727: runtime of \textit{ec\_domain\_process()} has a small standard fp@1727: deviancy relative to the mean value, while this ratio is about twice fp@1727: as big for \textit{ec\_master\_run()}: This probably results from the fp@1727: latter function having to execute code depending on the current state fp@1727: and the different state functions are more or less complex. fp@1727: fp@1727: For a realtime cycle makes up about $10$~\textmu s, the theoretical fp@1727: frequency can be up to $100$~kHz. For two reasons, this frequency fp@1727: keeps being theoretical: fp@1727: fp@1727: \begin{enumerate} fp@1727: \item The processor must still be able to run the operating system fp@1727: between the realtime cycles. fp@1727: \item The EtherCAT frame must be sent and received, before the next fp@1727: realtime cycle begins. The determination of the bus cycle time is fp@1727: difficult and covered in section~\ref{sec:timing-bus}. fp@1727: \end{enumerate} fp@1727: fp@1727: %------------------------------------------------------------------------------ fp@1727: fp@1727: \subsection{Bus Cycle Measuring} fp@1727: \label{sec:timing-bus} fp@1727: \index{Bus cycle} fp@1727: fp@1727: For measuring the time, a frame is ``on the wire'', two timestamps fp@1727: must be be taken: fp@1727: fp@1727: \begin{enumerate} fp@1727: \item The time, the Ethernet hardware begins with physically sending fp@1727: the frame. fp@1727: \item The time, the frame is completely received by the Ethernet fp@1727: hardware. fp@1727: \end{enumerate} fp@1727: fp@1727: Both times are difficult to determine. The first reason is, that the fp@1727: interrupts are disabled and the master is not notified, when a frame fp@1727: is sent or received (polling would distort the results). The second fp@1727: reason is, that even with interrupts enabled, the time from the event fp@1727: to the notification is unknown. Therefore the only way to confidently fp@1727: determine the bus cycle time is an electrical measuring. fp@1727: fp@1727: Anyway, the bus cycle time is an important factor when designing fp@1727: realtime code, because it limits the maximum frequency for the cyclic fp@1727: part of the realtime module. In practice, these timing parameters are fp@1727: highly dependent on the hardware and often a trial and error method fp@1727: must be used to determine the limits of the system. fp@1727: fp@1727: The central question is: What happens, if the cycle frequency is too fp@1727: high? The answer is, that the EtherCAT frames that have been sent at fp@1727: the end of the cycle are not yet received, when the next cycle starts. fp@1727: First this is noticed by \textit{ecrt\_domain\_process()}, because the fp@1727: working counter of the process data datagrams were not increased. The fp@1727: function will notify the user via syslog\footnote{To limit syslog fp@1727: output, a mechanism has been implementet, that outputs a summarized fp@1727: notification at maximum once a second.}. In this case, the process fp@1727: data keeps being the same as in the last cycle, because it is not fp@1727: erased by the domain. When the domain datagrams are queued again, the fp@1727: master notices, that they are already queued (and marked as sent). The fp@1727: master will mark them as unsent again and output a warning, that fp@1727: datagrams were ``skipped''. fp@1727: fp@1727: On the mentioned $2.0$~GHz system, the possible cycle frequency can be fp@1727: up to $25$~kHz without skipped frames. This value can surely be fp@1727: increased by choosing faster hardware. Especially the RealTek network fp@1727: hardware could be replaced by a faster one. Besides, implementing a fp@1727: dedicated ISR for EtherCAT devices would also contribute to increasing fp@1727: the latency. These are two points on the author's to-do list. fp@1727: fp@1727: %------------------------------------------------------------------------------ fp@1727: fp@1727: \chapter{Using the EtherCAT Master} fp@1727: \label{chapter:usage} fp@1727: \index{Master!Usage} fp@1727: fp@1727: This chapter will give practical examples of how to use the EtherCAT fp@1727: master via the realtime interface by writing a realtime module. fp@1727: fp@1727: Section~\ref{sec:make} shows how to compile and install the master, fp@1727: while the sections~\ref{sec:mini} to~\ref{sec:concurrency} give fp@1727: examples for different realtime modules. fp@1727: fp@1727: %------------------------------------------------------------------------------ fp@1727: fp@1727: \section{Compiling and Installing} fp@1727: \label{sec:make} fp@1727: \index{Master!Compilation} fp@1727: fp@1728: The current EtherCAT master code is available at~\cite{etherlab} or fp@1728: can be obtained from the EtherLab\textsuperscript{\textregistered} CD. fp@1732: The \textit{tar.bz2} file has to be unpacked with the commands below fp@1728: (or similar): fp@1727: fp@1727: \begin{lstlisting} fp@1732: `\$` `\textbf{tar xjf ethercat-\masterversion.tar.bz2}` fp@1732: `\$` `\textbf{cd ethercat-\masterversion/}` fp@1727: \end{lstlisting} fp@1727: fp@1727: The tarball was created with GNU Autotools, so the build process fp@1732: follows the below commands: fp@1727: fp@1727: \begin{lstlisting} fp@1729: `\$` `\textbf{./configure}` fp@1732: `\$` `\textbf{make modules}` fp@1727: \end{lstlisting} fp@1727: fp@1727: The default installation prefix is \textit{/opt/etherlab}. It can be fp@1727: changed with the \texttt{--prefix} argument. fp@1727: fp@1727: Linux kernel sources are needed for compilation\footnote{If a realtime fp@1727: extension shall to be used, the kernel should be patched before fp@1727: compiling the EtherCAT master.}. To compile the EtherCAT master fp@1727: modules for a different kernel than the running kernel, the target fp@1727: kernel version can be specified with the \texttt{--with-linux} fp@1727: argument. Example: fp@1727: fp@1727: \begin{lstlisting} fp@1729: `\$` `\textbf{./configure --with-linux="2.6.17-ipipe"}` fp@1732: `\$` `\textbf{make modules}` fp@1732: \end{lstlisting} fp@1732: fp@1732: The below commands have to be entered as \textit{root}: The first one fp@1732: will install the kernel modules to the kernel's modules directory. The fp@1732: second one will install EtherCAT headers, the init script, the fp@1732: sysconfig file and the user space tools to the prefix path. fp@1727: fp@1727: \begin{lstlisting} fp@1732: # `\textbf{make modules\_install}` fp@1729: # `\textbf{make install}` fp@1727: \end{lstlisting} fp@1727: fp@1732: If the target kernel's modules directory is not under fp@1732: \textit{/lib/modules}, a different destination directory can be fp@1732: specified with the \textit{DESTDIR} make variable. For example: fp@1732: fp@1732: \begin{lstlisting} fp@1732: # `\textbf{make DESTDIR=/vol/nfs/root modules\_install}` fp@1732: \end{lstlisting} fp@1732: fp@1732: This command will install the compiled kernel modules to fp@1732: \textit{/vol/nfs/root/lib/modules}, prepended by the kernel release. fp@1732: fp@1728: If the EtherCAT master shall be run as a service fp@1728: (recommended\footnote{Even if the EtherCAT master shall not be loaded fp@1728: on system startup, the use of the init script is recommended for fp@1728: manual (un-)loading.}), the init script and the sysconfig file have fp@1728: to be copied to the appropriate locations. The below example is fp@1728: suitable for SUSE Linux. It may vary for other distributions. fp@1727: fp@1727: \begin{lstlisting} fp@1729: # `\textbf{cd /opt/etherlab}` fp@1729: # `\textbf{cp etc/sysconfig/ethercat /etc/sysconfig/}` fp@1729: # `\textbf{cp etc/init.d/ethercat /etc/init.d/}` fp@1729: # `\textbf{insserv ethercat}` fp@1727: \end{lstlisting} fp@1727: fp@1728: Now the sysconfig file \texttt{/etc/sysconfig/ethercat} (see fp@1728: section~\ref{sec:sysconfig}) has to be customized: This is mainly done fp@1729: by uncommenting and adjusting the \$DEVICE\_INDEX variable. It has to fp@1729: be set to the index of the compatible network device to use with fp@1729: EtherCAT, where the order of devices is dependent on their position in fp@1729: the PCI bus: fp@1728: fp@1728: \begin{lstlisting}[numbers=left,basicstyle=\ttfamily\scriptsize] fp@1729: # `\textbf{lspci}` fp@1728: 00:00.0 Host bridge: VIA Technologies, Inc. VT8363/8365 [KT133/KM133] (rev 03) fp@1728: 00:01.0 PCI bridge: VIA Technologies, Inc. VT8363/8365 [KT133/KM133 AGP] fp@1728: 00:04.0 ISA bridge: VIA Technologies, Inc. VT82C686 [Apollo Super South] (rev 40) fp@1728: 00:04.1 IDE interface: VIA Technologies, Inc. VT82C586A/B/VT82C686/A/B/VT823x/A/C... fp@1728: 00:04.2 USB Controller: VIA Technologies, Inc. VT82xxxxx UHCI USB 1.1 Controller... fp@1728: 00:04.3 USB Controller: VIA Technologies, Inc. VT82xxxxx UHCI USB 1.1 Controller... fp@1728: 00:04.4 Bridge: VIA Technologies, Inc. VT82C686 [Apollo Super ACPI] (rev 40) fp@1728: 00:09.0 Ethernet controller: D-Link System Inc RTL8139 Ethernet (rev 10) fp@1728: 00:0a.0 Ethernet controller: Intel Corporation 82557/8/9 [Ethernet Pro 100] (rev 08) fp@1728: 00:0b.0 Ethernet controller: D-Link System Inc RTL8139 Ethernet (rev 10) fp@1728: 00:0c.0 VGA compatible controller: ATI Technologies Inc Rage XL (rev 27) fp@1728: 00:11.0 Unknown mass storage controller: Promise Technology, Inc. PDC20265... fp@1728: \end{lstlisting} fp@1728: fp@1728: In the above output of the \textit{lspci} command, two compatible fp@1728: network devices can be found in lines~\textcircled{\tiny 9} and fp@1729: \textcircled{\tiny 11}. The \$DEVICE\_INDEX variable should be set to fp@1729: $0$ or $1$, respectively. fp@1727: fp@1727: After the basic configuration is done, the master can be started with fp@1727: the below command: fp@1727: fp@1727: \begin{lstlisting} fp@1729: # `\textbf{/etc/init.d/ethercat start}` fp@1727: \end{lstlisting} fp@1727: fp@1727: The operation of the master can be observed by looking at the fp@1727: syslog\index{syslog} messages, which should look like the ones below. fp@1727: If EtherCAT slaves are connected to the master's EtherCAT device, the fp@1727: activity indicators should begin to flash. fp@1727: fp@1727: \begin{lstlisting}[numbers=left] fp@1727: EtherCAT: Master driver, 1.1 (stable) - rev. 513, fp@1727: compiled by fp at Aug 09 2006 10:23:20 fp@1727: EtherCAT: Initializing 1 EtherCAT master(s)... fp@1727: EtherCAT: Initializing master 0. fp@1727: EtherCAT: Master driver initialized. fp@1727: ec_8139too Fast Ethernet driver 0.9.27 Revision 513, fp@1727: compiled by fp at Aug 09 2006 10:23:20 fp@1727: ec_device_index is 0 fp@1727: ACPI: PCI Interrupt 0000:01:00.0[A] -> Link [LNKC] fp@1727: -> GSI 11 (level, low) -> IRQ 11 fp@1727: ec0: RealTek RTL8139 at 0xd047c000, 00:c0:26:00:c6:aa, IRQ 11 fp@1727: ec0: Identified 8139 chip type 'RTL-8100B/8139D' fp@1727: Registering EtherCAT device... fp@1727: Starting EtherCAT device... fp@1727: EtherCAT: Link state changed to UP. fp@1727: EtherCAT: Starting Idle mode. fp@1727: EtherCAT: 11 slaves responding. fp@1727: EtherCAT: Slave states: INIT, OP. fp@1727: EtherCAT: Scanning bus. fp@1727: EtherCAT: Bus scanning completed. fp@1727: EtherCAT: No EoE handlers coupled. fp@1727: \end{lstlisting} fp@1727: fp@1727: \begin{description} fp@1727: \item[\normalfont\textcircled{\tiny 1}] The master module is loaded, fp@1727: and one master is initialized. fp@1727: \item[\normalfont\textcircled{\tiny 6}] The EtherCAT-capable RTL8139 fp@1727: device driver is loaded. It connects its first network device to the fp@1727: master. fp@1727: \item[\normalfont\textcircled{\tiny 16}] The master starts idle mode fp@1727: and begins scanning the bus for slaves. fp@1727: \end{description} fp@1727: fp@1727: %------------------------------------------------------------------------------ fp@1727: fp@1727: \section{A Minimal Example Module} fp@1727: \label{sec:mini} fp@1727: \index{Examples!Minimal} fp@1727: fp@1727: This section will explain the usage of the EtherCAT master from a fp@1727: minimal kernel module. The complete module code is obtainable as a fp@1727: part of the EtherCAT master code release (see~\cite{etherlab}, file fp@1727: \textit{examples/mini/mini.c}). fp@1727: fp@1727: The minimal example uses a kernel timer (software interrupt) to handle fp@1727: cyclic code. After the timer function is executed, it re-adds itself fp@1727: with a delay of one \textit{jiffy}\index{jiffies}, which results in a fp@1727: timer frequency of \textit{HZ}\nomenclature{HZ}{Kernel macro fp@1727: containing the timer interrupt frequency} fp@1727: fp@1727: The module-global variables, needed to operate the master can be seen fp@1727: in listing~\ref{lst:minivar}. fp@1727: fp@1727: \begin{lstlisting}[language=C,numbers=left,caption={Minimal fp@1727: variables},label=lst:minivar] fp@1727: struct timer_list timer; fp@1727: fp@1727: ec_master_t *master = NULL; fp@1727: ec_domain_t *domain1 = NULL; fp@1727: fp@1727: void *r_dig_in, *r_ana_out; fp@1727: fp@1727: ec_pdo_reg_t domain1_pdos[] = { fp@1727: {"1", Beckhoff_EL1014_Inputs, &r_dig_in}, fp@1727: {"2", Beckhoff_EL4132_Ouput1, &r_ana_out}, fp@1727: {} fp@1727: }; fp@1727: \end{lstlisting} fp@1727: fp@1727: \begin{description} fp@1727: \item[\normalfont\textcircled{\tiny 1}] There is a timer object fp@1727: declared, that is needed to tell the kernel to install a timer and fp@1727: execute a certain function, if it runs out. This is done by a fp@1727: variable of the \textit{timer\_list} structure. fp@1727: \item[\normalfont\textcircled{\tiny 3} -- \textcircled{\tiny 4}] There fp@1727: is a pointer declared, that will later point to a requested EtherCAT fp@1727: master. Additionally there is a pointer to a domain object needed, fp@1727: that will manage process data IO. fp@1727: \item[\normalfont\textcircled{\tiny 6}] The pointers \textit{r\_*} fp@1727: will later point to the \underline{r}aw process data values inside fp@1727: the domain memory. The addresses they point to will be set during a fp@1727: call to \textit{ec\_\-master\_\-activate()}, that will create the fp@1727: domain memory and configure the mapped process data image. fp@1727: \item[\normalfont\textcircled{\tiny 8} -- \textcircled{\tiny 12}] The fp@1727: configuration of the mapping of certain PDOs in a domain can easily fp@1727: be done with the help of an initialization array of the fp@1727: \textit{ec\_pdo\_reg\_t} type, defined as part of the realtime fp@1727: interface. Each record must contain the ASCII bus-address of the fp@1727: slave (see section~\ref{sec:addr}), the slave's vendor ID and fp@1727: product code, and the index and subindex of the PDO to map (these fp@1727: four fields can be specified in junction, by using one of the fp@1727: defines out of the \textit{include/ecdb.h} header). The last field fp@1727: has to be the address of the process data pointer, so it can later fp@1727: be redirected appropriately. Attention: The initialization array fp@1727: must end with an empty record (\textit{\{\}})! fp@1727: \end{description} fp@1727: fp@1727: The initialization of the minimal realtime module is done by the fp@1727: ``Minimal init function'' in listing~\ref{lst:miniinit}. fp@1727: fp@1727: \begin{lstlisting}[language=C,numbers=left,caption={Minimal init fp@1727: function},label={lst:miniinit}] fp@1727: int __init init_mini_module(void) fp@1727: { fp@1727: if (!(master = ecrt_request_master(0))) { fp@1727: goto out_return; fp@1727: } fp@1727: fp@1727: if (!(domain1 = ecrt_master_create_domain(master))) { fp@1727: goto out_release_master; fp@1727: } fp@1727: fp@1727: if (ecrt_domain_register_pdo_list(domain1, fp@1727: domain1_pdos)) { fp@1727: goto out_release_master; fp@1727: } fp@1727: fp@1727: if (ecrt_master_activate(master)) { fp@1727: goto out_release_master; fp@1727: } fp@1727: fp@1727: ecrt_master_prepare(master); fp@1727: fp@1727: init_timer(&timer); fp@1727: timer.function = run; fp@1727: timer.expires = jiffies + 10; fp@1727: add_timer(&timer); fp@1727: fp@1727: return 0; fp@1727: fp@1727: out_release_master: fp@1727: ecrt_release_master(master); fp@1727: out_return: fp@1727: return -1; fp@1727: } fp@1727: \end{lstlisting} fp@1727: fp@1727: \begin{description} fp@1727: \item[\normalfont\textcircled{\tiny 3}] It is tried to request the fp@1727: first EtherCAT master (index 0). On success, the fp@1727: \textit{ecrt\_\-request\_\-master()} function returns a pointer to fp@1727: the reserved master, that can be used as an object to following fp@1727: functions calls. On failure, the function returns \textit{NULL}. fp@1727: \item[\normalfont\textcircled{\tiny 7}] In order to exchange process fp@1727: data, a domain object has to be created. The fp@1727: \textit{ecrt\_\-master\_\-create\_domain()} function also returns a fp@1727: pointer to the created domain, or \textit{NULL} in error case. fp@1727: \item[\normalfont\textcircled{\tiny 11}] The registration of domain fp@1727: PDOs with an initialization array results in a single function call. fp@1727: Alternatively the data fields could be registered with individual fp@1727: calls of \textit{ecrt\_domain\_register\_pdo()}. fp@1727: \item[\normalfont\textcircled{\tiny 16}] After the configuration of fp@1727: process data mapping, the master can be activated for cyclic fp@1727: operation. This will configure all slaves and bring them into fp@1729: OP state. fp@1727: \item[\normalfont\textcircled{\tiny 20}] This call is needed to avoid fp@1727: a case differentiation in cyclic operation: The first operation in fp@1727: cyclic mode is a receive call. Due to the fact, that there is fp@1727: nothing to receive during the first cycle, there had to be an fp@1727: \textit{if}-statement to avoid a warning. A call to fp@1727: \textit{ec\_master\_prepare()} sends a first datagram containing a fp@1727: process data exchange datagram, so that the first receive call will fp@1727: not fail. fp@1727: \item[\normalfont\textcircled{\tiny 22} -- \textcircled{\tiny 25}] The fp@1727: master is now ready for cyclic operation. The kernel timer that fp@1727: cyclically executes the \textit{run()} function is initialized and fp@1727: started. fp@1727: \end{description} fp@1727: fp@1727: The coding of a cleanup function fo the minimal module can be seen in fp@1727: listing~\ref{lst:miniclean}. fp@1727: fp@1727: \begin{lstlisting}[language=C,numbers=left,caption={Minimal cleanup fp@1727: function},label={lst:miniclean}] fp@1727: void __exit cleanup_mini_module(void) fp@1727: { fp@1727: del_timer_sync(&timer); fp@1727: ecrt_master_deactivate(master); fp@1727: ecrt_release_master(master); fp@1727: } fp@1727: \end{lstlisting} fp@1727: fp@1727: \begin{description} fp@1727: \item[\normalfont\textcircled{\tiny 3}] To cleanup the module, it it fp@1727: necessary to stop the cyclic processing. This is done by a call to fp@1727: \textit{del\_timer\_sync()} which safely removes a queued timer fp@1727: object. It is assured, that no cyclic work will be done after this fp@1727: call returns. fp@1727: \item[\normalfont\textcircled{\tiny 4}] This call deactivates the fp@1729: master, which results in all slaves being brought to their INIT fp@1729: state again. fp@1727: \item[\normalfont\textcircled{\tiny 5}] This call releases the master, fp@1727: removes any existing configuration and silently starts the idle fp@1727: mode. The value of the master pointer is invalid after this call and fp@1727: the module can be safely unloaded. fp@1727: \end{description} fp@1727: fp@1727: The final part of the minimal module is that for the cyclic work. Its fp@1727: coding can be seen in listing~\ref{lst:minirun}. fp@1727: fp@1727: \begin{lstlisting}[language=C,numbers=left,caption={Minimal cyclic fp@1727: function},label={lst:minirun}] fp@1727: void run(unsigned long data) fp@1727: { fp@1727: static uint8_t dig_in_0; fp@1727: fp@1727: ecrt_master_receive(master); fp@1727: ecrt_domain_process(domain1); fp@1727: fp@1727: dig_in_0 = EC_READ_BIT(r_dig_in, 0); fp@1727: EC_WRITE_S16(r_ana_out, dig_in_0 * 0x3FFF); fp@1727: fp@1727: ecrt_master_run(master); fp@1727: ecrt_master_send(master); fp@1727: fp@1727: timer.expires += 1; // frequency = HZ fp@1727: add_timer(&timer); fp@1727: } fp@1727: \end{lstlisting} fp@1727: fp@1727: \begin{description} fp@1727: \item[\normalfont\textcircled{\tiny 5}] The cyclic processing starts fp@1727: with receiving datagrams, that were sent in the last cycle. The fp@1727: frames containing these datagrams have to be received by the network fp@1727: interface card prior to this call. fp@1727: \item[\normalfont\textcircled{\tiny 6}] The process data of domain 1 fp@1727: has been automatically copied into domain memory while datagram fp@1727: reception. This call checks the working counter for changes and fp@1727: re-queues the domain's datagram for sending. fp@1727: \item[\normalfont\textcircled{\tiny 8}] This is an example for reading fp@1727: out a bit-oriented process data value (i.~e. bit 0) via the fp@1727: \textit{EC\_READ\_BIT()} macro. See section~\ref{sec:macros} for fp@1727: more information about those macros. fp@1727: \item[\normalfont\textcircled{\tiny 9}] This line shows how to write a fp@1727: signed, 16-bit process data value. In this case, the slave is able fp@1727: to output voltages of $-10$~V to $+10$~V with a resolution of 16 fp@1727: bit. This write command outputs either $0$~V or $+5$~V, depending fp@1727: of the value of \textit{dig\_in\_0}. fp@1727: \item[\normalfont\textcircled{\tiny 11}] This call runs the master's fp@1727: operation state machine (see section~\ref{sec:fsm-op}). A single fp@1727: state is processed, and datagrams are queued. Mainly bus observation fp@1727: is done: The bus state is determined and in case of slaves that lost fp@1727: their configuration, reconfiguration is tried. fp@1727: \item[\normalfont\textcircled{\tiny 12}] This method sends all queued fp@1727: datagrams, in this case the domain's datagram and one of the master fp@1727: state machine. In best case, all datagrams fit into one frame. fp@1727: \item[\normalfont\textcircled{\tiny 14} -- \textcircled{\tiny 15}] fp@1727: Kernel timers are implemented as ``one-shot'' timers, so they have fp@1727: to be re-added after each execution. The time of the next execution fp@1727: is specified in \textit{jiffies} and will happen at the time of the fp@1727: next system timer interrupt. This results in the \textit{run()} fp@1727: function being executed with a frequency of \textit{HZ}. fp@1727: \end{description} fp@1727: fp@1727: %------------------------------------------------------------------------------ fp@1727: fp@1727: \section{An RTAI Example Module} fp@1727: \label{sec:rtai} fp@1727: \index{Examples!RTAI} fp@1727: fp@1727: The whole code can be seen in the EtherCAT master code release fp@1727: (see~\cite{etherlab}, file \textit{examples/rtai/rtai\_sample.c}). fp@1727: fp@1727: Listing~\ref{lst:rtaivar} shows the defines and global variables fp@1727: needed for a minimal RTAI module with EtherCAT processing. fp@1727: fp@1727: \begin{lstlisting}[language=C,numbers=left,caption={RTAI task fp@1727: declaration},label={lst:rtaivar}] fp@1727: #define FREQUENCY 10000 fp@1727: #define TIMERTICKS (1000000000 / FREQUENCY) fp@1727: fp@1727: RT_TASK task; fp@1727: \end{lstlisting} fp@1727: fp@1727: \begin{description} fp@1727: \item[\normalfont\textcircled{\tiny 1} -- \textcircled{\tiny 2}] RTAI fp@1727: takes the cycle period as nanoseconds, so the easiest way is to fp@1727: define a frequency and convert it to a cycle time in nanoseconds. fp@1727: \item[\normalfont\textcircled{\tiny 4}] The \textit{task} variable fp@1727: later contains information about the running RTAI task. fp@1727: \end{description} fp@1727: fp@1727: Listing~\ref{lst:rtaiinit} shows the module init function for the RTAI fp@1727: module. Most lines are the same as in listing~\ref{lst:miniinit}, fp@1727: differences come up when starting the cyclic code. fp@1727: fp@1727: \begin{lstlisting}[language=C,numbers=left,caption={RTAI module init fp@1727: function},label={lst:rtaiinit}] fp@1727: int __init init_mod(void) fp@1727: { fp@1727: RTIME requested_ticks, tick_period, now; fp@1727: fp@1727: if (!(master = ecrt_request_master(0))) { fp@1727: goto out_return; fp@1727: } fp@1727: fp@1727: if (!(domain1 = ecrt_master_create_domain(master))) { fp@1727: goto out_release_master; fp@1727: } fp@1727: fp@1727: if (ecrt_domain_register_pdo_list(domain1, fp@1727: domain1_pdos)) { fp@1727: goto out_release_master; fp@1727: } fp@1727: fp@1727: if (ecrt_master_activate(master)) { fp@1727: goto out_release_master; fp@1727: } fp@1727: fp@1727: ecrt_master_prepare(master); fp@1727: fp@1727: requested_ticks = nano2count(TIMERTICKS); fp@1727: tick_period = start_rt_timer(requested_ticks); fp@1727: fp@1727: if (rt_task_init(&task, run, 0, 2000, 0, 1, NULL)) { fp@1727: goto out_stop_timer; fp@1727: } fp@1727: fp@1727: now = rt_get_time(); fp@1727: if (rt_task_make_periodic(&task, now + tick_period, fp@1727: tick_period)) { fp@1727: goto out_stop_task; fp@1727: } fp@1727: fp@1727: return 0; fp@1727: fp@1727: out_stop_task: fp@1727: rt_task_delete(&task); fp@1727: out_stop_timer: fp@1727: stop_rt_timer(); fp@1727: out_deactivate: fp@1727: ecrt_master_deactivate(master); fp@1727: out_release_master: fp@1727: ecrt_release_master(master); fp@1727: out_return: fp@1727: return -1; fp@1727: } fp@1727: \end{lstlisting} fp@1727: fp@1727: \begin{description} fp@1727: \item[\normalfont\textcircled{\tiny 24} -- \textcircled{\tiny 25}] The fp@1727: nanoseconds are converted to RTAI timer ticks and an RTAI timer is fp@1727: started. \textit{tick\_period} will be the ``real'' number of ticks fp@1727: used for the timer period (which can be different to the requested fp@1727: one). fp@1727: \item[\normalfont\textcircled{\tiny 27}] The RTAI task is initialized fp@1727: by specifying the cyclic function, the parameter to hand over, the fp@1727: stack size, priority, a flag that tells, if the function will use fp@1727: floating point operations and a signal handler. fp@1727: \item[\normalfont\textcircled{\tiny 32}] The task is made periodic by fp@1727: specifying a start time and a period. fp@1727: \end{description} fp@1727: fp@1727: The cleanup function of the RTAI module in listing~\ref{lst:rtaiclean} fp@1727: is nearly as simple as that of the minimal module. fp@1727: fp@1727: \begin{lstlisting}[language=C,numbers=left,caption={RTAI module fp@1727: cleanup function},label={lst:rtaiclean}] fp@1727: void __exit cleanup_mod(void) fp@1727: { fp@1727: rt_task_delete(&task); fp@1727: stop_rt_timer(); fp@1727: ecrt_master_deactivate(master); fp@1727: ecrt_release_master(master); fp@1727: rt_sem_delete(&master_sem); fp@1727: } fp@1727: \end{lstlisting} fp@1727: fp@1727: \begin{description} fp@1727: \item[\normalfont\textcircled{\tiny 2}] The RTAI task will be stopped fp@1727: and deleted. fp@1727: \item[\normalfont\textcircled{\tiny 3}] After that, the RTAI timer can fp@1727: be stopped. fp@1727: \end{description} fp@1727: fp@1727: The rest is the same as for the minimal module. fp@1727: fp@1727: Worth to mention is, that the cyclic function of the RTAI module fp@1727: (listing~\ref{lst:rtairun}) has a slightly different architecture. The fp@1727: function is not executed until returning for every cycle, but has an fp@1727: infinite loop in it, that is placed in a waiting state for the rest of fp@1727: each cycle. fp@1727: fp@1727: \begin{lstlisting}[language=C,numbers=left,caption={RTAI module cyclic fp@1727: function},label={lst:rtairun}] fp@1727: void run(long data) fp@1727: { fp@1727: while (1) { fp@1727: ecrt_master_receive(master); fp@1727: ecrt_domain_process(domain1); fp@1727: fp@1727: k_pos = EC_READ_U32(r_ssi_input); fp@1727: fp@1727: ecrt_master_run(master); fp@1727: ecrt_master_send(master); fp@1727: fp@1727: rt_task_wait_period(); fp@1727: } fp@1727: } fp@1727: \end{lstlisting} fp@1727: fp@1727: \begin{description} fp@1727: \item[\normalfont\textcircled{\tiny 3}] The \textit{while (1)} loop fp@1727: executes for the lifetime of the RTAI task. fp@1727: \item[\normalfont\textcircled{\tiny 12}] The fp@1727: \textit{rt\_task\_wait\_period()} function sets the process into a fp@1727: sleeping state until the beginning of the next cycle. It also fp@1727: checks, if the cyclic function has to be terminated. fp@1727: \end{description} fp@1727: fp@1727: %------------------------------------------------------------------------------ fp@1727: fp@1727: \section{Concurrency Example} fp@1727: \label{sec:concurrency} fp@1727: \index{Examples!Concurrency} fp@1727: fp@1727: As mentioned before, there can be concurrent access to the EtherCAT fp@1727: master. The realtime module and a EoE\index{EoE} process can compete fp@1727: for master access, for example. In this case, the module has to fp@1727: provide the locking mechanism, because it depends on the module's fp@1727: architecture which lock has to be used. The module makes this locking fp@1727: mechanism available to the master through the master's locking fp@1727: callbacks. fp@1727: fp@1727: In case of RTAI, the lock can be an RTAI semaphore, as shown in fp@1727: listing~\ref{lst:convar}. A normal linux semaphore would not be fp@1727: appropriate, because it could not block the RTAI task due to RTAI fp@1727: running in a higher domain than the linux kernel (see~\cite{rtai}). fp@1727: fp@1727: \begin{lstlisting}[language=C,numbers=left,caption={RTAI semaphore for fp@1727: concurrent access},label={lst:convar}] fp@1727: SEM master_sem; fp@1727: \end{lstlisting} fp@1727: fp@1727: The module has to implement the two callbacks for requesting and fp@1727: releasing the master lock. An exemplary coding can be seen in fp@1727: listing~\ref{lst:conlock}. fp@1727: fp@1727: \begin{lstlisting}[language=C,numbers=left,caption={RTAI locking fp@1727: callbacks for concurrent access},label={lst:conlock}] fp@1727: int request_lock(void *data) fp@1727: { fp@1727: rt_sem_wait(&master_sem); fp@1727: return 0; fp@1727: } fp@1727: fp@1727: void release_lock(void *data) fp@1727: { fp@1727: rt_sem_signal(&master_sem); fp@1727: } fp@1727: \end{lstlisting} fp@1727: fp@1727: \begin{description} fp@1727: \item[\normalfont\textcircled{\tiny 1}] The \textit{request\_lock()} fp@1727: function has a data parameter. The master always passes the value, fp@1727: that was specified when registering the callback function. This can fp@1727: be used for handing the master pointer. Notice, that it has an fp@1727: integer return value (see line 4). fp@1727: \item[\normalfont\textcircled{\tiny 3}] The call to fp@1727: \textit{rt\_sem\_wait()} either returns at once, when the semaphore fp@1727: was free, or blocks until the semaphore is freed again. In any case, fp@1727: the semaphore finally is reserved for the process calling the fp@1727: request function. fp@1727: \item[\normalfont\textcircled{\tiny 4}] When the lock was requested fp@1727: successfully, the function should return 0. The module can prohibit fp@1727: requesting the lock by returning non-zero (see paragraph ``Tuning fp@1727: the jitter'' below). fp@1727: \item[\normalfont\textcircled{\tiny 7}] The \textit{release\_lock()} fp@1727: function gets the same argument passed, but has a void return value, fp@1727: because is always succeeds. fp@1727: \item[\normalfont\textcircled{\tiny 9}] The \textit{rt\_sem\_signal()} fp@1727: function frees the semaphore, that was prior reserved with fp@1727: \textit{rt\_sem\_wait()}. fp@1727: \end{description} fp@1727: fp@1727: In the module's init function, the semaphore must be initialized, and fp@1727: the callbacks must be passed to the EtherCAT master: fp@1727: fp@1727: \begin{lstlisting}[language=C,numbers=left,caption={Module init fp@1727: function for concurrent access},label={lst:coninit}] fp@1727: int __init init_mod(void) fp@1727: { fp@1727: RTIME tick_period, requested_ticks, now; fp@1727: fp@1727: rt_sem_init(&master_sem, 1); fp@1727: fp@1727: if (!(master = ecrt_request_master(0))) { fp@1727: goto out_return; fp@1727: } fp@1727: fp@1727: ecrt_master_callbacks(master, request_lock, fp@1727: release_lock, NULL); fp@1727: // ... fp@1727: \end{lstlisting} fp@1727: fp@1727: \begin{description} fp@1727: \item[\normalfont\textcircled{\tiny 5}] The call to fp@1727: \textit{rt\_sem\_init()} initializes the semaphore and sets its fp@1727: value to 1, meaning that only one process can reserve the semaphore fp@1727: without blocking. fp@1727: \item[\normalfont\textcircled{\tiny 11}] The callbacks are passed to fp@1727: the master with a call to \textit{ecrt\_master\_callbacks()}. The fp@1727: last parameter is the argument, that the master should pass with fp@1727: each call to a callback function. Here it is not used and set to fp@1727: \textit{NULL}. fp@1727: \end{description} fp@1727: fp@1727: For the cyclic function being only one competitor for master access, fp@1727: it has to request the lock like any other process. There is no need to fp@1727: use the callbacks (which are meant for processes of lower priority), fp@1727: so it can access the semaphore directly: fp@1727: fp@1727: \begin{lstlisting}[language=C,numbers=left,caption={RTAI cyclic fp@1727: function for concurrent access},label={lst:conrun}] fp@1727: void run(long data) fp@1727: { fp@1727: while (1) { fp@1727: rt_sem_wait(&master_sem); fp@1727: fp@1727: ecrt_master_receive(master); fp@1727: ecrt_domain_process(domain1); fp@1727: fp@1727: k_pos = EC_READ_U32(r_ssi_input); fp@1727: fp@1727: ecrt_master_run(master); fp@1727: ecrt_master_send(master); fp@1727: fp@1727: rt_sem_signal(&master_sem); fp@1727: rt_task_wait_period(); fp@1727: } fp@1727: } fp@1727: \end{lstlisting} fp@1727: fp@1727: \begin{description} fp@1727: \item[\normalfont\textcircled{\tiny 4}] Every access to the master has fp@1727: to be preceeded by a call to \textit{rt\_sem\_wait()}, because fp@1727: another instance might currently access the master. fp@1727: \item[\normalfont\textcircled{\tiny 14}] When cyclic processing fp@1727: finished, the semaphore has to be freed again, so that other fp@1727: processes have the possibility to access the master. fp@1727: \end{description} fp@1727: fp@1727: A little change has to be made to the cleanup function in case of fp@1727: concurrent master access. fp@1727: fp@1727: \begin{lstlisting}[language=C,numbers=left,caption={RTAI module fp@1727: cleanup function for concurrent access},label={lst:conclean}] fp@1727: void __exit cleanup_mod(void) fp@1727: { fp@1727: rt_task_delete(&task); fp@1727: stop_rt_timer(); fp@1727: ecrt_master_deactivate(master); fp@1727: ecrt_release_master(master); fp@1727: rt_sem_delete(&master_sem); fp@1727: } fp@1727: \end{lstlisting} fp@1727: fp@1727: \begin{description} fp@1727: \item[\normalfont\textcircled{\tiny 7}] Upon module cleanup, the fp@1727: semaphore has to be deleted, so that memory can be freed. fp@1727: \end{description} fp@1727: fp@1727: \paragraph{Tuning the Jitter} fp@1727: \index{Jitter} fp@1727: fp@1727: Concurrent access leads to higher jitter of the realtime process, fp@1727: because there are situations, in which the realtime process has to fp@1727: wait for a process of lower priority to finish accessing the master. fp@1727: In most cases this is acceptable, because a master access cycle fp@1727: (receive/process/send) only takes $10$~\textmu s to $20$~\textmu s on fp@1727: recent systems, what would be the maximum additional jitter. However fp@1727: some applications demand a minimum jitter. For this reason the master fp@1727: access can be prohibited by the realtime module: If the time, another fp@1727: process wants to access the master, is to close to the beginning of fp@1727: the next realtime cycle, the module can disallow, that the lock is fp@1727: taken. In this case, the request callback has to return $1$, meaning fp@1727: that the lock has not been taken. The foreign process must abort its fp@1727: master access and try again next time. fp@1727: fp@1727: This measure helps to significantly reducing the jitter produced by fp@1727: concurrent master access. Below are exerpts of an example coding: fp@1727: fp@1727: \begin{lstlisting}[language=C,numbers=left,caption={Variables for fp@1727: jitter reduction},label={lst:redvar}] fp@1727: #define FREQUENCY 10000 // RTAI task frequency in Hz fp@1727: // ... fp@1727: cycles_t t_last_cycle = 0; fp@1727: const cycles_t t_critical = cpu_khz * 1000 / FREQUENCY fp@1727: - cpu_khz * 30 / 1000; fp@1727: \end{lstlisting} fp@1727: fp@1727: \begin{description} fp@1727: \item[\normalfont\textcircled{\tiny 3}] The variable fp@1727: \textit{t\_last\_cycle} holds the timer ticks at the beginning of fp@1727: the last realtime cycle. fp@1727: \item[\normalfont\textcircled{\tiny 4}] \textit{t\_critical} contains fp@1727: the number of ticks, that may have passed since the beginning of the fp@1727: last cycle, until there is no more foreign access possible. It is fp@1727: calculated by substracting the ticks for $30$~\textmu s from the fp@1727: ticks for a complete cycle. fp@1727: \end{description} fp@1727: fp@1727: \begin{lstlisting}[language=C,numbers=left,caption={Cyclic function fp@1727: with reduced jitter},label={lst:redrun}] fp@1727: void run(long data) fp@1727: { fp@1727: while (1) { fp@1727: t_last_cycle = get_cycles(); fp@1727: rt_sem_wait(&master_sem); fp@1727: // ... fp@1727: \end{lstlisting} fp@1727: fp@1727: \begin{description} fp@1727: \item[\normalfont\textcircled{\tiny 4}] The ticks of the beginning of fp@1727: the current realtime cycle are taken before reserving the semaphore. fp@1727: \end{description} fp@1727: fp@1727: \begin{lstlisting}[language=C,numbers=left,caption={Request callback fp@1727: for reduced jitter},label={lst:redreq}] fp@1727: int request_lock(void *data) fp@1727: { fp@1727: // too close to the next RT cycle: deny access. fp@1727: if (get_cycles() - t_last_cycle > t_critical) fp@1727: return -1; fp@1727: fp@1727: // allow access fp@1727: rt_sem_wait(&master_sem); fp@1727: return 0; fp@1727: } fp@1727: \end{lstlisting} fp@1727: fp@1727: \begin{description} fp@1727: \item[\normalfont\textcircled{\tiny 4}] If the time of request is too fp@1727: close to the next realtime cycle (here: \textless~$30$~\textmu s fp@1727: before the estimated beginning), the locking is denied. The fp@1727: requesting process must abort its cycle. fp@1727: \end{description} fp@1727: fp@1727: %------------------------------------------------------------------------------ fp@1727: fp@1727: \begin{thebibliography}{99} fp@1727: \bibitem{etherlab} Ingenieurgemeinschaft IgH: EtherLab -- Open Source fp@1727: Toolkit for rapid realtime code generation under Linux with fp@1727: Simulink/RTW and EtherCAT technology. URL: http://etherlab.org, fp@1727: July~31, 2006. fp@1727: \bibitem{dlspec} IEC 61158-4-12: Data-link Protocol Specification. fp@1727: International Electrotechnical Comission (IEC), 2005. fp@1727: \bibitem{alspec} IEC 61158-6-12: Application Layer Protocol fp@1727: Specification. International Electrotechnical Comission (IEC), 2005. fp@1727: \bibitem{gpl} GNU General Public License, Version 2. URL: fp@1727: http://www.gnu.org/licenses/gpl.txt. August~9, 2006. fp@1727: \bibitem{lsb} Linux Standard Base. URL: fp@1727: http://www.freestandards.org/en/LSB. August~9, 2006. fp@1727: \bibitem{wireshark} Wireshark. URL: http://www.wireshark.org. fp@1727: August~9, 2006. fp@1727: \bibitem{automata} {\it Hopcroft, J.~E. / Ullman, J.~D.}: Introduction fp@1727: to Automata Theory, Languages and Computation. Adison-Wesley, fp@1727: Reading, Mass.~1979. fp@1727: \bibitem{fsmmis} {\it Wagner, F. / Wolstenholme, P.}: State machine fp@1727: misunderstandings. In: IEE journal ``Computing and Control fp@1727: Engineering'', 2004. fp@1727: \bibitem{rtai} RTAI. The RealTime Application Interface for Linux from fp@1727: DIAPM. URL: http://www.rtai.org, 2006. fp@1727: \end{thebibliography} fp@1727: fp@1727: \printglossary fp@1727: \addcontentsline{toc}{chapter}{\nomname} fp@1727: \markleft{\nomname} fp@1727: fp@1727: \printindex fp@1727: \markleft{Index} fp@1727: fp@1727: %------------------------------------------------------------------------------ fp@1727: fp@1727: \end{document} fp@1727: fp@1727: %------------------------------------------------------------------------------