1

%------------------------------------------------------------------------------

     2

%

     3

%  IgH EtherCAT Master Documentation

     4

%

     5

%  $Id$

     6

%

     7

%  vi: spell spelllang=en tw=78

     8

%

     9

%------------------------------------------------------------------------------

    10

    11

\documentclass[a4paper,12pt,BCOR6mm,bibtotoc,idxtotoc]{scrbook}

    12

    13

\usepackage[latin1]{inputenc}

    14

\usepackage[automark,headsepline]{scrpage2}

    15

\usepackage{graphicx}

    16

\usepackage{makeidx}

    17

\usepackage[refpage]{nomencl}

    18

\usepackage{listings}

    19

\usepackage[nofancy]{rcsinfo}

    20

\usepackage{SIunits}

    21

\usepackage{amsmath} % for \text{}

    22

\usepackage{longtable}

    23

\usepackage{hyperref}

    24

    25

\hypersetup{pdfpagelabels,plainpages=false}

    26

\hypersetup{linkcolor=blue,colorlinks=true,urlcolor=blue}

    27

    28

\setlength{\parskip}{0.8ex plus 0.8ex minus 0.5ex}

    29

\setlength{\parindent}{0mm}

    30

    31

\setcounter{secnumdepth}{\subsubsectionlevel}

    32

    33

\DeclareFontShape{OT1}{cmtt}{bx}{n}

    34

{

    35

  <5><6><7><8><9><10><10.95><12><14.4><17.28><20.74><24.88>cmttb10

    36

}{}

    37

    38

\lstset{basicstyle=\ttfamily\small,numberstyle=\tiny,aboveskip=4mm,

    39

  belowskip=2mm,escapechar=`,breaklines=true}

    40

\renewcommand\lstlistlistingname{List of Listings}

    41

    42

% Workaround for lstlistoflistings bug

    43

\makeatletter% --> De-TeX-FAQ

    44

\renewcommand*{\lstlistoflistings}{%

    45

  \begingroup

    46

    \if@twocolumn

    47

      \@restonecoltrue\onecolumn

    48

    \else

    49

      \@restonecolfalse

    50

    \fi

    51

    \lol@heading

    52

    \setlength{\parskip}{\z@}%

    53

    \setlength{\parindent}{\z@}%

    54

    \setlength{\parfillskip}{\z@ \@plus 1fil}%

    55

    \@starttoc{lol}%

    56

    \if@restonecol\twocolumn\fi

    57

  \endgroup

    58

}

    59

\makeatother% --> \makeatletter

    60

    61

\renewcommand\nomname{Glossary}

    62

    63

\newcommand{\IgH}{\raisebox{-0.7667ex}

    64

  {\includegraphics[height=2.2ex]{images/ighsign}}}

    65

    66

\rcsInfo $RCSId$

    67

    68

\newcommand{\masterversion}{1.5.2}

    69

\newcommand{\linenum}[1]{\normalfont\textcircled{\tiny #1}}

    70

    71

\makeindex

    72

\makenomenclature

    73

    74

% Revision and date on inner footer

    75

\ifoot[\scriptsize\rcsInfoRevision, \rcsInfoDate]

    76

    {\scriptsize\rcsInfoRevision, \rcsInfoDate}

    77

    78

%------------------------------------------------------------------------------

    79

    80

\begin{document}

    81

    82

\pagenumbering{roman}

    83

\pagestyle{empty}

    84

    85

\begin{titlepage}

    86

  \begin{center}

    87

    \rule{\textwidth}{1.5mm}

    88

    89

    {\Huge\sf\textbf{IgH \includegraphics[height=2.4ex]{images/ethercat}

    90

      Master \masterversion}\\[1ex]

    91

      \textbf{Documentation}}

    92

    93

    \vspace{1ex}

    94

    \rule{\textwidth}{1.5mm}

    95

    96

    \vspace{\fill} {\Large Dipl.-Ing. (FH) Florian Pose,

    97

    \url{fp@igh.de}\\[1ex] Ingenieurgemeinschaft \IgH}

    98

    99

    \vspace{\fill}

   100

    {\Large Essen, \rcsInfoLongDate\\[1ex]

   101

      Revision \rcsInfoRevision}

   102

  \end{center}

   103

\end{titlepage}

   104

   105

%------------------------------------------------------------------------------

   106

   107

\pagestyle{scrplain}

   108

   109

\tableofcontents

   110

\listoftables

   111

\listoffigures

   112

%\lstlistoflistings

   113

   114

%------------------------------------------------------------------------------

   115

   116

\newpage

   117

\pagestyle{scrheadings}

   118

   119

\section*{Conventions}

   120

\addcontentsline{toc}{section}{Conventions}

   121

\markleft{Conventions}

   122

   123

The following typographic conventions are used:

   124

   125

\begin{itemize}

   126

   127

\item \textit{Italic face} is used for newly introduced terms and file names.

   128

   129

\item \texttt{Typewriter face} is used for code examples and command line

   130

output.

   131

   132

\item \texttt{\textbf{Bold typewriter face}} is used for user input in command

   133

lines.

   134

   135

\end{itemize}

   136

   137

Data values and addresses are usually specified as hexadecimal values. These

   138

are marked in the \textit{C} programming language style with the prefix

   139

\lstinline+0x+ (example: \lstinline+0x88A4+). Unless otherwise noted, address

   140

values are specified as byte addresses.

   141

   142

Function names are always printed with parentheses, but without

   143

parameters. So, if a function \lstinline+ecrt_request_master()+ has

   144

empty parentheses, this shall not imply that it has no parameters.

   145

   146

If shell commands have to be entered, this is marked by a dollar prompt:

   147

   148

\begin{lstlisting}

   149

$

   150

\end{lstlisting}

   151

   152

Further, if a shell command has to be entered as the superuser, the

   153

prompt is a mesh:

   154

   155

\begin{lstlisting}

   156

#

   157

\end{lstlisting}

   158

   159

%------------------------------------------------------------------------------

   160

   161

\chapter{The IgH EtherCAT Master}

   162

\label{chapter:master}

   163

\pagenumbering{arabic}

   164

   165

This chapter covers some general information about the EtherCAT master.

   166

   167

%------------------------------------------------------------------------------

   168

   169

\section{Feature Summary}

   170

\label{sec:summary}

   171

\index{Master!Features}

   172

   173

The list below gives a short summary of the master features.

   174

   175

\begin{itemize}

   176

   177

\item Designed as a kernel module for Linux 2.6 / 3.x.

   178

   179

\item Implemented according to IEC 61158-12 \cite{dlspec} \cite{alspec}.

   180

   181

\item Comes with EtherCAT-capable native drivers for several common Ethernet

   182

chips, as well as a generic driver for all chips supported by the Linux

   183

kernel.

   184

   185

  \begin{itemize}

   186

   187

  \item The native drivers operate the hardware without interrupts.

   188

   189

  \item Native drivers for additional Ethernet hardware can easily be

   190

  implemented using the common device interface (see~\autoref{sec:ecdev})

   191

  provided by the master module.

   192

   193

  \item For any other hardware, the generic driver can be used. It uses the

   194

  lower layers of the Linux network stack.

   195

   196

  \end{itemize}

   197

   198

\item The master module supports multiple EtherCAT masters running in

   199

parallel.

   200

   201

\item The master code supports any Linux realtime extension through its

   202

independent architecture.

   203

   204

  \begin{itemize}

   205

   206

  \item RTAI\nomenclature{RTAI}{Realtime Application Interface} \cite{rtai}

   207

  (including LXRT via RTDM), ADEOS\nomenclature{ADEOS}{Adaptive Domain

   208

  Environment for Operating Systems}, RT-Preempt \cite{rt-preempt}, Xenomai

   209

  (including RTDM), etc.

   210

   211

  \item It runs well even without realtime extensions.

   212

   213

  \end{itemize}

   214

   215

\item Common ``Application Interface'' for applications, that want to use

   216

EtherCAT functionality (see \autoref{chap:api}).

   217

   218

\item \textit{Domains} are introduced, to allow grouping of process

   219

  data transfers with different slave groups and task periods.

   220

   221

  \begin{itemize}

   222

   223

  \item Handling of multiple domains with different task periods.

   224

   225

  \item Automatic calculation of process data mapping, FMMU and sync manager

   226

  configuration within each domain.

   227

   228

  \end{itemize}

   229

   230

\item Communication through several finite state machines.

   231

   232

  \begin{itemize}

   233

   234

  \item Automatic bus scanning after topology changes.

   235

   236

  \item Bus monitoring during operation.

   237

   238

  \item Automatic reconfiguration of slaves (for example after power failure)

   239

  during operation.

   240

   241

  \end{itemize}

   242

   243

\item Distributed Clocks support (see \autoref{sec:dc}).

   244

   245

  \begin{itemize}

   246

   247

  \item Configuration of the slave's DC parameters through the application

   248

  interface.

   249

   250

  \item Synchronization (offset and drift compensation) of the distributed

   251

  slave clocks to the reference clock.

   252

   253

  \item Optional synchronization of the reference clock to the master clock or

   254

  the other way round.

   255

   256

  \end{itemize}

   257

   258

\item CANopen over EtherCAT (CoE)

   259

   260

  \begin{itemize}

   261

   262

  \item SDO upload, download and information service.

   263

   264

  \item Slave configuration via SDOs.

   265

   266

  \item SDO access from userspace and from the application.

   267

   268

  \end{itemize}

   269

   270

\item Ethernet over EtherCAT (EoE)

   271

   272

  \begin{itemize}

   273

   274

  \item Transparent use of EoE slaves via virtual network interfaces.

   275

   276

  \item Natively supports either a switched or a routed EoE network

   277

  architecture.

   278

   279

  \end{itemize}

   280

   281

\item Vendor-specific over EtherCAT (VoE)

   282

   283

  \begin{itemize}

   284

   285

  \item Communication with vendor-specific mailbox protocols via the API.

   286

   287

  \end{itemize}

   288

   289

\item File Access over EtherCAT (FoE)

   290

   291

  \begin{itemize}

   292

   293

  \item Loading and storing files via the command-line tool.

   294

   295

  \item Updating a slave's firmware can be done easily.

   296

   297

  \end{itemize}

   298

   299

\item Servo Profile over EtherCAT (SoE)

   300

   301

  \begin{itemize}

   302

   303

  \item Implemented according to IEC 61800-7 \cite{soespec}.

   304

   305

  \item Storing IDN configurations, that are written to the slave during

   306

  startup.

   307

   308

  \item Accessing IDNs via the command-line tool.

   309

   310

  \item Accessing IDNs at runtime via the the user-space library.

   311

   312

  \end{itemize}

   313

   314

\item Userspace command-line-tool ``ethercat'' (see \autoref{sec:tool})

   315

   316

  \begin{itemize}

   317

   318

  \item Detailed information about master, slaves, domains and bus

   319

  configuration.

   320

  \item Setting the master's debug level.

   321

  \item Reading/Writing alias addresses.

   322

  \item Listing slave configurations.

   323

  \item Viewing process data.

   324

  \item SDO download/upload; listing SDO dictionaries.

   325

  \item Loading and storing files via FoE.

   326

  \item SoE IDN access.

   327

  \item Access to slave registers.

   328

  \item Slave SII (EEPROM) access.

   329

  \item Controlling application-layer states.

   330

  \item Generation of slave description XML and C-code from existing slaves.

   331

   332

  \end{itemize}

   333

   334

\item Seamless system integration though LSB\nomenclature{LSB}{Linux

   335

    Standard Base} compliance.

   336

   337

  \begin{itemize}

   338

   339

  \item Master and network device configuration via sysconfig files.

   340

   341

  \item Init script for master control.

   342

   343

  \item Service file for systemd.

   344

   345

  \end{itemize}

   346

   347

\item Virtual read-only network interface for monitoring and debugging

   348

  purposes.

   349

   350

\end{itemize}

   351

   352

%------------------------------------------------------------------------------

   353

   354

\section{License}

   355

\label{sec:license}

   356

   357

The master code is released under the terms and conditions of the GNU General

   358

Public License (GPL \cite{gpl})\index{GPL}, version 2. Other developers, that

   359

want to use EtherCAT with Linux systems, are invited to use the master code or

   360

even participate on development.

   361

   362

To allow static linking of userspace application against the master's

   363

application interface (see \autoref{chap:api}), the userspace library (see

   364

\autoref{sec:userlib}) is licensed under the terms and conditions of the GNU

   365

Lesser General Public License (LGPL \cite{lgpl})\index{LGPL}, version 2.1.

   366

   367

%------------------------------------------------------------------------------

   368

   369

\chapter{Architecture}

   370

\label{chap:arch}

   371

\index{Master!Architecture}

   372

   373

The EtherCAT master is integrated into the Linux kernel. This was an early

   374

design decision, which has been made for several reasons:

   375

   376

\begin{itemize}

   377

   378

\item Kernel code has significantly better realtime characteristics, i.\,e.\

   379

less latency than userspace code. It was foreseeable, that a fieldbus master

   380

has a lot of cyclic work to do. Cyclic work is usually triggered by timer

   381

interrupts inside the kernel. The execution delay of a function that processes

   382

timer interrupts is less, when it resides in kernelspace, because there is no

   383

need of time-consuming context switches to a userspace process.

   384

   385

\item It was also foreseeable, that the master code has to directly

   386

communicate with the Ethernet hardware. This has to be done in the kernel

   387

anyway (through network device drivers), which is one more reason for the

   388

master code being in kernelspace.

   389

   390

\end{itemize}

   391

   392

\autoref{fig:arch} gives a general overview of the master architecture.

   393

   394

\begin{figure}[htbp]

   395

  \centering

   396

  \includegraphics[width=\textwidth]{images/architecture}

   397

  \caption{Master Architecture}

   398

  \label{fig:arch}

   399

\end{figure}

   400

   401

The components of the master environment are described below:

   402

   403

\begin{description}

   404

   405

\item[Master Module]\index{Master Module} Kernel module containing one or more

   406

EtherCAT master instances (see \autoref{sec:mastermod}), the ``Device

   407

Interface'' (see \autoref{sec:ecdev}) and the ``Application Interface'' (see

   408

\autoref{chap:api}).

   409

   410

\item[Device Modules]\index{Device modules} EtherCAT-capable Ethernet device

   411

driver modules\index{Device modules}, that offer their devices to the EtherCAT

   412

master via the device interface (see \autoref{sec:ecdev}). These modified

   413

network drivers can handle network devices used for EtherCAT operation and

   414

``normal'' Ethernet devices in parallel. A master can accept a certain device

   415

and then is able to send and receive EtherCAT frames. Ethernet devices

   416

declined by the master module are connected to the kernel's network stack as

   417

usual.

   418

   419

\item[Application]\index{Application} A program that uses the EtherCAT master

   420

(usually for cyclic exchange of process data with EtherCAT slaves). These

   421

programs are not part of the EtherCAT master code\footnote{Although there are

   422

some examples provided in the \textit{examples/} directory.}, but have to be

   423

generated or written by the user. An application can request a master through

   424

the application interface (see \autoref{chap:api}). If this succeeds, it has

   425

the control over the master: It can provide a bus configuration and exchange

   426

process data.  Applications can be kernel modules (that use the kernel

   427

application interface directly) or userspace programs, that use the

   428

application interface via the EtherCAT library (see \autoref{sec:userlib}), or

   429

the RTDM library (see~\autoref{sec:rtdm}).

   430

   431

\end{description}

   432

   433

%------------------------------------------------------------------------------

   434

   435

\section{Master Module}

   436

\label{sec:mastermod}

   437

\index{Master module}

   438

   439

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

   440

master instances. Each master waits for certain Ethernet device(s) identified

   441

by its MAC address(es)\index{MAC address}. These addresses have to be

   442

specified on module loading via the \textit{main\_devices} (and optional:

   443

\textit{backup\_devices}) module parameter.  The number of master instances to

   444

initialize is taken from the number of MAC addresses given.

   445

   446

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

   447

waits for one Ethernet device with the MAC address

   448

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

   449

   450

\begin{lstlisting}

   451

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

   452

\end{lstlisting}

   453

   454

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

   455

   456

\begin{lstlisting}

   457

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

   458

\end{lstlisting}

   459

   460

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

   461

\autoref{fig:masters}). The master index is needed for the

   462

\lstinline+ecrt_master_request()+ function of the application interface (see

   463

\autoref{chap:api}) and the \lstinline+--master+ option of the

   464

\textit{ethercat} command-line tool (see \autoref{sec:tool}), which defaults

   465

to $0$.

   466

   467

\begin{figure}[htbp]

   468

  \centering

   469

  \includegraphics[width=.5\textwidth]{images/masters}

   470

  \caption{Multiple masters in one module}

   471

  \label{fig:masters}

   472

\end{figure}

   473

   474

\paragraph{Debug Level} The master module also has a parameter

   475

\textit{debug\_level} to set the initial debug level for all masters (see

   476

also~\autoref{sec:ethercat-debug}).

   477

   478

\paragraph{Init Script}

   479

\index{Init script}

   480

   481

In most cases it is not necessary to load the master module and the Ethernet

   482

driver modules manually. There is an init script available, so the master can

   483

be started as a service (see \autoref{sec:system}). For systems that are

   484

managed by systemd \cite{systemd}, there is also a service file available.

   485

   486

\paragraph{Syslog}

   487

   488

The master module outputs information about its state and events to the kernel

   489

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

   490

command should result in the messages below:

   491

   492

\begin{lstlisting}

   493

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

   494

EtherCAT: Master driver `\masterversion`

   495