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.4.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

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

   296

   297

\chapter{Architecture}

   298

\label{sec:arch}

   299

\index{Master!Architecture}

   300

   301

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

   302

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

   303

   304

\begin{itemize}

   305

   306

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

   307

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

   308

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

   309

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

   310

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

   311

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

   312

   313

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

   314

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

   315

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

   316

master code being in kernelspace.

   317

   318

\end{itemize}

   319

   320

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

   321

   322

\begin{figure}[htbp]

   323

  \centering

   324

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

   325

  \caption{Master Architecture}

   326

  \label{fig:arch}

   327

\end{figure}

   328

   329

The components of the master environment are described below:

   330

   331

\begin{description}

   332

   333

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

   334

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

   335

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

   336

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

   337

   338

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

   339

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

   340

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

   341

network drivers can handle network devices used for EtherCAT operation and

   342

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

   343

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

   344

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

   345

usual.

   346

   347

\item[Application Modules]\index{Application} A kernel module that uses the

   348

EtherCAT master (usually for cyclic exchange of process data with EtherCAT

   349

slaves). These modules are not part of the EtherCAT master

   350

code\footnote{Although there are some examples provided in the

   351

\textit{examples/} directory.}, but have to be generated or written by the

   352

user. An application module can ``request'' a master through the application

   353

interface (see chap.~\ref{chap:api}). If this succeeds, it has the control

   354

over the master: It can provide a bus configuration and exchange process data.

   355

   356

\end{description}

   357

   358

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

   359

   360

\section{Master Module}

   361

\label{sec:mastermod}

   362

\index{Master module}

   363

   364

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

   365

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

   366

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

   367

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

   368

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

   369

given.

   370

   371

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

   372

waits for the Ethernet device with the MAC address

   373

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

   374

   375

\begin{lstlisting}

   376

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

   377

\end{lstlisting}

   378

   379

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

   380

   381

\begin{lstlisting}

   382

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

   383

\end{lstlisting}

   384

   385

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

   386

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

   387

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

   388

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

   389

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

   390

to $0$.

   391

   392

\begin{figure}[htbp]

   393

  \centering

   394

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

   395

  \caption{Multiple masters in one module}

   396

  \label{fig:masters}

   397

\end{figure}

   398

   399

\paragraph{Init Script}

   400

\index{Init script}

   401

   402

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

   403

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

   404

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

   405

   406

\paragraph{Syslog}

   407

   408

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

   409

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

   410

command should result in the messages below:

   411

   412

\begin{lstlisting}

   413

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

   414

EtherCAT: Master driver `\masterversion`

   415

EtherCAT: 2 masters waiting for devices.

   416

   417

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

   418

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

   419

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

   420

                                 for devices.

   421

\end{lstlisting}

   422

   423

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

   424

searching the logs easier.

   425

   426

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

   427

   428

\section{Master Phases}

   429

\index{Master phases}

   430

   431

Every EtherCAT master provided by the master module (see

   432

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

   433

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

   434

   435

\begin{figure}[htbp]

   436

  \centering

   437

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

   438

  \caption{Master phases and transitions}

   439

  \label{fig:phases}

   440

\end{figure}

   441

   442

\begin{description}

   443

   444

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

   445

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

   446

possible until then.

   447

   448

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

   449

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

   450

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

   451

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

   452

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

   453

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

   454

bus configuration.

   455

   456

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

   457

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

   458

   459

\end{description}

   460

   461

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

   462

   463

\section{Process Data}

   464

\label{sec:processdata}

   465

   466

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

   467

process data.

   468

   469

\paragraph{Process Data Image}

   470

\index{Process data}

   471

   472

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

   473

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

   474

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

   475

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

   476

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

   477

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

   478

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

   479

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

   480

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

   481

   482

\paragraph{Process Data Domains}

   483

\index{Domain}

   484

   485

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

   486

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

   487

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

   488

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

   489

for the following reasons:

   490

   491

\begin{itemize}

   492

   493

\item The maximum size of a datagram is limited due to the limited size of an

   494

Ethernet frame: The maximum data size is the Ethernet data field size minus

   495

the EtherCAT frame header, EtherCAT datagram header and EtherCAT datagram

   496

footer: $1500 - 2 - 12 - 2 = 1484$ octets. If the size of the process data

   497

image exceeds this limit, multiple frames have to be sent, and the image has

   498

to be partitioned for the use of multiple datagrams. A domain manages this