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{sec: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,

   312

i.\,e.~less latency than userspace code. It was foreseeable, that a fieldbus

   313

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

   314

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

   315

processes timer interrupts is less, when it resides in kernelspace, because

   316

there is no 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{Phases}

   369

\index{Master phases}

   370

   371

The EtherCAT master runs through several phases (see fig.~\ref{fig:phases}):

   372

   373

\begin{figure}[htbp]

   374

  \centering

   375

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

   376

  \caption{Master phases and transitions}

   377

  \label{fig:phases}

   378

\end{figure}

   379

   380

\begin{description}

   381

   382

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

   383

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

   384

possible until then.

   385

   386

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

   387

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

   388

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

   389

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

   390

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

   391

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

   392

bus configuration.

   393

   394

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

   395

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

   396

   397

\end{description}

   398

   399

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

   400

   401

\section{General Behavior} % FIXME

   402

\index{Master behavior}

   403

   404

\ldots

   405

   406

%   Behavior (Scanning) TODO

   407

   408

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

   409

   410

\section{Master Module}

   411

\label{sec:mastermod}

   412

\index{Master module}

   413

   414

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

   415

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

   416

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

   417

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

   418

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

   419

given.

   420

   421

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

   422

waits for the Ethernet device with the MAC address

   423

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

   424

   425

\begin{lstlisting}

   426

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

   427

\end{lstlisting}

   428

   429

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

   430

   431

\begin{lstlisting}

   432

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

   433

\end{lstlisting}

   434

   435

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

   436

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

   437

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

   438

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

   439

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

   440

to $0$.

   441

   442

\begin{figure}[htbp]

   443

  \centering

   444

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

   445

  \caption{Multiple masters in one module}

   446

  \label{fig:masters}

   447

\end{figure}

   448

   449

\paragraph{Init Script}

   450

\index{Init script}

   451

   452

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

   453

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

   454

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

   455

   456

\paragraph{Syslog}

   457

   458

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

   459

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

   460

command should result in the messages below:

   461

   462

\begin{lstlisting}

   463

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

   464

EtherCAT: Master driver `\masterversion`

   465

EtherCAT: 2 masters waiting for devices.

   466

   467

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

   468

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

   469

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

   470

                                 for devices.

   471

\end{lstlisting}

   472

   473

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

   474

searching the logs easier.

   475

   476

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

   477

   478

\section{Process Data}

   479

\label{sec:processdata}

   480

   481

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

   482

process data.

   483

   484

\paragraph{Process Data Image}

   485

\index{Process data}

   486

   487

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

   488

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

   489

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

   490

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

   491

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

   492

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

   493

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

   494

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

   495

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

   496

   497

\paragraph{Process Data Domains}