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{svn}

    20

\usepackage{SIunits}

    21

\usepackage{hyperref}

    22

    23

\hypersetup{pdfpagelabels,plainpages=false}

    24

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

    25

    26

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

    27

\setlength{\parindent}{0mm}

    28

    29

\setcounter{secnumdepth}{\subsubsectionlevel}

    30

    31

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

    32

{

    33

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

    34

}{}

    35

    36

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

    37

  belowskip=2mm,escapechar=`}

    38

\renewcommand\lstlistlistingname{List of Listings}

    39

    40

% Workaround for lstlistoflistings bug

    41

\makeatletter% --> De-TeX-FAQ

    42

\renewcommand*{\lstlistoflistings}{%

    43

  \begingroup

    44

    \if@twocolumn

    45

      \@restonecoltrue\onecolumn

    46

    \else

    47

      \@restonecolfalse

    48

    \fi

    49

    \lol@heading

    50

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

    51

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

    52

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

    53

    \@starttoc{lol}%

    54

    \if@restonecol\twocolumn\fi

    55

  \endgroup

    56

}

    57

\makeatother% --> \makeatletter

    58

    59

\renewcommand\nomname{Glossary}

    60

    61

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

    62

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

    63

    64

\SVN $Date$

    65

\SVN $Revision$

    66

    67

\newcommand{\masterversion}{1.5.0}

    68

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

    69

    70

\makeindex

    71

\makenomenclature

    72

    73

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

    74

    75

\begin{document}

    76

    77

\pagenumbering{roman}

    78

\pagestyle{empty}

    79

    80

\begin{titlepage}

    81

  \begin{center}

    82

    \rule{\textwidth}{1.5mm}

    83

    84

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

    85

      Master \masterversion\\[1ex]

    86

      Preliminary Documentation}

    87

    88

    \vspace{1ex}

    89

    \rule{\textwidth}{1.5mm}

    90

    91

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

    92

    \url{fp@igh-essen.com}\\[1ex] Ingenieurgemeinschaft \IgH}

    93

    94

    \vspace{\fill}

    95

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

    96

      Revision \SVNRevision}

    97

  \end{center}

    98

\end{titlepage}

    99

   100

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

   101

   102

\tableofcontents

   103

\listoftables

   104

\listoffigures

   105

%\lstlistoflistings

   106

   107

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

   108

   109

\newpage

   110

\pagestyle{scrheadings}

   111

   112

\section*{Conventions}

   113

\addcontentsline{toc}{section}{Conventions}

   114

\markleft{Conventions}

   115

   116

The following typographic conventions are used:

   117

   118

\begin{itemize}

   119

   120

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

   121

   122

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

   123

output.

   124

   125

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

   126

lines.

   127

   128

\end{itemize}

   129

   130

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

   131

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

   132

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

   133

values are specified as byte addresses.

   134

   135

Function names are always printed with parentheses, but without

   136

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

   137

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

   138

   139

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

   140

   141

\begin{lstlisting}

   142

$

   143

\end{lstlisting}

   144

   145

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

   146

prompt is a mesh:

   147

   148

\begin{lstlisting}

   149

#

   150

\end{lstlisting}

   151

   152

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

   153

   154

\chapter{The IgH EtherCAT Master}

   155

\label{chapter:master}

   156

\pagenumbering{arabic}

   157

   158

This chapter covers some general information about the EtherCAT master.

   159

   160

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

   161

   162

\section{Feature Summary}

   163

\label{sec:summary}

   164

\index{Master!Features}

   165

   166

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

   167

   168

\begin{itemize}

   169

   170

\item Designed as a kernel module for Linux 2.6.

   171

   172

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

   173

   174

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

   175

   176

  \begin{itemize}

   177

   178

  \item The Ethernet hardware is operated without interrupts.

   179

   180

  \item Drivers for additional Ethernet hardware can easily be implemented

   181

  using the common device interface (see sec.~\ref{sec:ecdev}) provided by the

   182

  master module.

   183

   184

  \end{itemize}

   185

   186

\item The master module supports multiple EtherCAT masters running in

   187

parallel.

   188

   189

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

   190

independent architecture.

   191

   192

  \begin{itemize}

   193

   194

  \item RTAI\nomenclature{RTAI}{Realtime Application Interface},

   195

  ADEOS\nomenclature{ADEOS}{Adaptive Domain Environment for Operating

   196

  Systems}, etc.

   197

   198

  \item It runs well even without realtime extensions.

   199

   200

  \end{itemize}

   201

   202

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

   203

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

   204

   205

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

   206

  data transfers with different slave groups and task periods.

   207

   208

  \begin{itemize}

   209

   210

  \item Handling of multiple domains with different task periods.

   211

   212

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

   213

  configuration within each domain.

   214

   215

  \end{itemize}

   216

   217

\item Communication through several finite state machines.

   218

   219

  \begin{itemize}

   220

   221

  \item Automatic bus scanning after topology changes.

   222

   223

  \item Bus monitoring during operation.

   224

   225

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

   226

  during operation.

   227

   228

  \end{itemize}

   229

   230

\item CANopen-over-EtherCAT (CoE)

   231

   232

  \begin{itemize}

   233

   234

  \item Sdo upload, download and information service.

   235

   236

  \item Slave configuration via Sdos.

   237

   238

  \item Sdo access from userspace and from the application.

   239

   240

  \end{itemize}

   241

   242

\item Ethernet-over-EtherCAT (EoE)

   243

   244

  \begin{itemize}

   245

   246

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

   247

   248

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

   249

  architecture.

   250

   251

  \end{itemize}

   252

   253

\item Userspace command-line-tool ``ethercat`` (see sec.~\ref{sec:tool})

   254

   255

  \begin{itemize}

   256

   257

  \item Showing the current bus with slaves, Pdos and Sdos.

   258

  \item Showing the bus configuration.

   259

  \item Showing domains and process data.

   260

  \item Setting the master's debug level.

   261

  \item Writing alias addresses.

   262

  \item Sdo uploading/downloading.

   263

  \item Reading/writing a slave's SII.

   264

  \item Setting slave states.

   265

  \item Generate slave description XML.

   266

   267

  \end{itemize}

   268

   269

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

   270

    Standard Base} compliance.

   271

   272

  \begin{itemize}

   273

   274

  \item Master and network device configuration via sysconfig files.

   275

   276

  \item Init script for master control.

   277

   278

  \end{itemize}

   279

   280

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

   281

  purposes.

   282

   283

\end{itemize}

   284

   285

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

   286

   287

\section{License}

   288

\label{sec:license}

   289

   290

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

   291

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

   292

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

   293

even participate on development.

   294

   295

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

   296

application interface (see chap.~\ref{chap:api}), the userspace library (see

   297

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

   298

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

   299

   300

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

   301

   302

\chapter{Architecture}

   303

\label{chap:arch}

   304

\index{Master!Architecture}

   305

   306

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

   307

an early design decision, which has been made for several reasons:

   308

   309

\begin{itemize}

   310

   311

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

   312

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

   313

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

   314

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

   315

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

   316

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

   317

   318

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

   319

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

   320

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

   321

master code being in kernelspace.

   322

   323

\end{itemize}

   324

   325

Figure~\ref{fig:arch} gives a general overview of the master architecture.

   326

   327

\begin{figure}[htbp]

   328

  \centering

   329

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

   330

  \caption{Master Architecture}

   331

  \label{fig:arch}

   332

\end{figure}

   333

   334

The components of the master environment are described below:

   335

   336

\begin{description}

   337

   338

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

   339

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

   340

Interface'' (see sec.~\ref{sec:ecdev}) and the ``Application Interface'' (see

   341

chap.~\ref{chap:api}).

   342

   343

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

   344

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

   345

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

   346

network drivers can handle network devices used for EtherCAT operation and

   347

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

   348

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

   349

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

   350

usual.

   351

   352

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

   353

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

   354

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

   355

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

   356

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

   357

through the application interface (see chap.~\ref{chap:api}). If this

   358

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

   359

configuration and exchange process data.  Applications can be kernel modules

   360

(that use the kernel application interface directly) or userspace programs,

   361

that use the application interface via the EtherCAT library (see

   362

sec.~\ref{sec:userlib}).

   363

   364

\end{description}

   365

   366

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

   367

   368

\section{Master Module}

   369

\label{sec:mastermod}

   370

\index{Master module}

   371

   372

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

   373

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

   374

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

   375

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

   376

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

   377

given.

   378

   379

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

   380

waits for the Ethernet device with the MAC address

   381

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

   382

   383

\begin{lstlisting}

   384

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

   385

\end{lstlisting}

   386

   387

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

   388

   389

\begin{lstlisting}

   390

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

   391

\end{lstlisting}

   392

   393

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

   394

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

   395

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

   396

chap.~\ref{chap:api}) and the \lstinline+--master+ option of the

   397

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

   398

to $0$.

   399

   400

\begin{figure}[htbp]

   401

  \centering

   402

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

   403

  \caption{Multiple masters in one module}

   404

  \label{fig:masters}

   405

\end{figure}

   406

   407

\paragraph{Init Script}

   408

\index{Init script}

   409

   410

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

   411

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

   412

be started as a service (see sec.~\ref{sec:system}).

   413

   414

\paragraph{Syslog}

   415

   416

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

   417

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

   418

command should result in the messages below:

   419

   420

\begin{lstlisting}

   421

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

   422

EtherCAT: Master driver `\masterversion`

   423

EtherCAT: 2 masters waiting for devices.

   424

   425

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

   426

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

   427

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

   428

                                 for devices.

   429

\end{lstlisting}

   430

   431

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

   432

searching the logs easier.

   433

   434

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

   435

   436

\section{Master Phases}

   437

\index{Master phases}

   438

   439

Every EtherCAT master provided by the master module (see

   440

sec.~\ref{sec:mastermod}) runs through several phases (see

   441

fig.~\ref{fig:phases}):

   442

   443

\begin{figure}[htbp]

   444

  \centering

   445

  \includegraphics[width=.9\textwidth]{images/phases}

   446

  \caption{Master phases and transitions}

   447

  \label{fig:phases}

   448

\end{figure}

   449

   450

\begin{description}

   451

   452

\item[Orphaned phase]\index{Orphaned phase} This mode takes effect, when the

   453

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

   454

possible until then.

   455

   456

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

   457

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

   458

runs its state machine (see sec.~\ref{sec:fsm-master}), that automatically

   459

scans the bus for slaves and executes pending operations from the userspace

   460

interface (for example Sdo access). The command-line tool can be used to

   461

access the bus, but there is no process data exchange because of the missing

   462

bus configuration.

   463

   464

\item[Operation phase]\index{Operation phase} The master is requested by an

   465

application that can provide a bus configuration and exchange process data.

   466

   467

\end{description}

   468

   469

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

   470

   471

\section{Process Data}

   472

\label{sec:processdata}

   473

   474

This section shall introduce a few terms and ideas how the master handles

   475

process data.

   476

   477

\paragraph{Process Data Image}

   478

\index{Process data}

   479

   480

Slaves offer their inputs and outputs by presenting the master so-called

   481

``Process Data Objects'' (Pdos\index{Pdo}). The available Pdos can be either

   482

determined by reading out the slave's TXPDO and RXPDO SII categories from the

   483

E$^2$PROM (in case of fixed Pdos) or by reading out the appropriate CoE

   484

objects (see sec.~\ref{sec:coe}), if available.  The application can register

   485

the Pdos' entries for exchange during cyclic operation. The sum of all

   486

registered Pdo entries defines the ``process data image'', which is exchanged

   487

via datagrams with ``logical'' memory access (like LWR, LRD or LRW) introduced

   488

in~\cite[sec.~5.4]{dlspec}.

   489

   490

\paragraph{Process Data Domains}

   491

\index{Domain}

   492

   493

The process data image can be easily managed by creating so-called

   494

``domains'', which allow grouped Pdo exchange. They also take care of managing

   495

the datagram structures needed to exchange the Pdos. Domains are mandatory for

   496

process data exchange, so there has to be at least one. They were introduced

   497

for the following reasons:

   498