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

    23

    24

\hypersetup{pdfpagelabels,plainpages=false}

    25

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

    26

    27

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

    28

\setlength{\parindent}{0mm}

    29

    30

\setcounter{secnumdepth}{\subsubsectionlevel}

    31

    32

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

    33

{

    34

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

    35

}{}

    36

    37

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

    38

  belowskip=2mm,escapechar=`}

    39

\renewcommand\lstlistlistingname{List of Listings}

    40

    41

% Workaround for lstlistoflistings bug

    42

\makeatletter% --> De-TeX-FAQ

    43

\renewcommand*{\lstlistoflistings}{%

    44

  \begingroup

    45

    \if@twocolumn

    46

      \@restonecoltrue\onecolumn

    47

    \else

    48

      \@restonecolfalse

    49

    \fi

    50

    \lol@heading

    51

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

    52

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

    53

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

    54

    \@starttoc{lol}%

    55

    \if@restonecol\twocolumn\fi

    56

  \endgroup

    57

}

    58

\makeatother% --> \makeatletter

    59

    60

\renewcommand\nomname{Glossary}

    61

    62

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

    63

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

    64

    65

\rcsInfo $RCSId$

    66

    67

\newcommand{\masterversion}{1.5.0}

    68

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

    69

    70

\makeindex

    71

\makenomenclature

    72

    73

% Revision and date on inner footer

    74

\ifoot[\scriptsize\rcsInfoRevision, \rcsInfoDate]

    75

    {\scriptsize\rcsInfoRevision, \rcsInfoDate}

    76

    77

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

    78

    79

\begin{document}

    80

    81

\pagenumbering{roman}

    82

\pagestyle{empty}

    83

    84

\begin{titlepage}

    85

  \begin{center}

    86

    \rule{\textwidth}{1.5mm}

    87

    88

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

    89

      Master \masterversion\\[1ex]

    90

      Documentation}

    91

    92

    \vspace{1ex}

    93

    \rule{\textwidth}{1.5mm}

    94

    95

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

    96

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

    97

    98

    \vspace{\fill}

    99

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

   100

      Revision \rcsInfoRevision}

   101

  \end{center}

   102

\end{titlepage}

   103

   104

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

   105

   106

\pagestyle{scrplain}

   107

   108

\tableofcontents

   109

\listoftables

   110

\listoffigures

   111

%\lstlistoflistings

   112

   113

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

   114

   115

\newpage

   116

\pagestyle{scrheadings}

   117

   118

\section*{Conventions}

   119

\addcontentsline{toc}{section}{Conventions}

   120

\markleft{Conventions}

   121

   122

The following typographic conventions are used:

   123

   124

\begin{itemize}

   125

   126

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

   127

   128

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

   129

output.

   130

   131

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

   132

lines.

   133

   134

\end{itemize}

   135

   136

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

   137

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

   138

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

   139

values are specified as byte addresses.

   140

   141

Function names are always printed with parentheses, but without

   142

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

   143

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

   144

   145

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

   146

   147

\begin{lstlisting}

   148

$

   149

\end{lstlisting}

   150

   151

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

   152

prompt is a mesh:

   153

   154

\begin{lstlisting}

   155

#

   156

\end{lstlisting}

   157

   158

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

   159

   160

\chapter{The IgH EtherCAT Master}

   161

\label{chapter:master}

   162

\pagenumbering{arabic}

   163

   164

This chapter covers some general information about the EtherCAT master.

   165

   166

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

   167

   168

\section{Feature Summary}

   169

\label{sec:summary}

   170

\index{Master!Features}

   171

   172

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

   173

   174

\begin{itemize}

   175

   176

\item Designed as a kernel module for Linux 2.6.

   177

   178

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

   179

   180

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

   181

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

   182

kernel.

   183

   184

  \begin{itemize}

   185

   186

  \item The native drivers operate the hardware without interrupts.

   187

   188

  \item Native drivers for additional Ethernet hardware can easily be

   189

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

   190

  provided by the master module.

   191

   192

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

   193

  lower layers of the Linux network stack.

   194

   195

  \end{itemize}

   196

   197

\item The master module supports multiple EtherCAT masters running in

   198

parallel.

   199

   200

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

   201

independent architecture.

   202

   203

  \begin{itemize}

   204

   205

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

   206

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

   207

  Systems}, RT-Preempt \cite{rt-preempt}, etc.

   208

   209

  \item It runs well even without realtime extensions.

   210

   211

  \end{itemize}

   212

   213

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

   214

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

   215

   216

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

   217

  data transfers with different slave groups and task periods.

   218

   219

  \begin{itemize}

   220

   221

  \item Handling of multiple domains with different task periods.

   222

   223

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

   224

  configuration within each domain.

   225

   226

  \end{itemize}

   227

   228

\item Communication through several finite state machines.

   229

   230

  \begin{itemize}

   231

   232

  \item Automatic bus scanning after topology changes.

   233

   234

  \item Bus monitoring during operation.

   235

   236

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

   237

  during operation.

   238

   239

  \end{itemize}

   240

   241

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

   242

   243

  \begin{itemize}

   244

   245

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

   246

  interface.

   247

   248

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

   249

  slave clocks to the reference clock.

   250

   251

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

   252

   253

  \end{itemize}

   254

   255

\item CANopen over EtherCAT (CoE)

   256

   257

  \begin{itemize}

   258

   259

  \item SDO upload, download and information service.

   260

   261

  \item Slave configuration via SDOs.

   262

   263

  \item SDO access from userspace and from the application.

   264

   265

  \end{itemize}

   266

   267

\item Ethernet over EtherCAT (EoE)

   268

   269

  \begin{itemize}

   270

   271

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

   272

   273

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

   274

  architecture.

   275

   276

  \end{itemize}

   277

   278

\item Vendor-specific over EtherCAT (VoE)

   279

   280

  \begin{itemize}

   281

   282

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

   283

   284

  \end{itemize}

   285

   286

\item File Access over EtherCAT (FoE)

   287

   288

  \begin{itemize}

   289

   290

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

   291

   292

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

   293

   294

  \end{itemize}

   295

   296

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

   297

   298

  \begin{itemize}

   299

   300

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

   301

  configuration.

   302

  \item Setting the master's debug level.

   303

  \item Reading/Writing alias addresses.

   304

  \item Listing slave configurations.

   305

  \item Viewing process data.

   306

  \item SDO download/upload; listing SDO dictionaries.

   307

  \item Loading and storing files via FoE.

   308

  \item Access to slave registers.

   309

  \item Slave SII (EEPROM) access.

   310

  \item Controlling application-layer states.

   311

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

   312

   313

  \end{itemize}

   314

   315

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

   316

    Standard Base} compliance.

   317

   318

  \begin{itemize}

   319

   320

  \item Master and network device configuration via sysconfig files.

   321

   322

  \item Init script for master control.

   323

   324

  \end{itemize}

   325

   326

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

   327

  purposes.

   328

   329

\end{itemize}

   330

   331

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

   332

   333

\section{License}

   334

\label{sec:license}

   335

   336

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

   337

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

   338

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

   339

even participate on development.

   340

   341

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

   342

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

   343

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

   344

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

   345

   346

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

   347

   348

\chapter{Architecture}

   349

\label{chap:arch}

   350

\index{Master!Architecture}

   351

   352

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

   353

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

   354

   355

\begin{itemize}

   356

   357

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

   358

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

   359

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

   360

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

   361

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

   362

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

   363

   364

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

   365

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

   366

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

   367

master code being in kernelspace.

   368

   369

\end{itemize}

   370

   371

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

   372

   373

\begin{figure}[htbp]

   374

  \centering

   375

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

   376

  \caption{Master Architecture}

   377

  \label{fig:arch}

   378

\end{figure}

   379

   380

The components of the master environment are described below:

   381

   382

\begin{description}

   383

   384

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

   385

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

   386

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

   387

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

   388

   389

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

   390

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

   391

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

   392

network drivers can handle network devices used for EtherCAT operation and

   393

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

   394

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

   395

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

   396

usual.

   397

   398

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

   399

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

   400

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

   401

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

   402

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

   403

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

   404

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

   405

configuration and exchange process data.  Applications can be kernel modules

   406

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

   407

that use the application interface via the EtherCAT library (see

   408

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

   409

   410

\end{description}

   411

   412

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

   413

   414

\section{Master Module}

   415

\label{sec:mastermod}

   416

\index{Master module}

   417

   418

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

   419

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

   420

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

   421

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

   422

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

   423

given.

   424

   425

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

   426

waits for the Ethernet device with the MAC address

   427

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

   428

   429

\begin{lstlisting}

   430

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

   431

\end{lstlisting}

   432

   433

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

   434

   435

\begin{lstlisting}

   436

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

   437

\end{lstlisting}

   438

   439

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

   440

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

   441

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

   442

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

   443

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

   444

to $0$.

   445

   446

\begin{figure}[htbp]

   447

  \centering

   448

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

   449

  \caption{Multiple masters in one module}

   450

  \label{fig:masters}

   451

\end{figure}

   452

   453

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

   454

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

   455

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

   456

   457

\paragraph{Init Script}

   458

\index{Init script}

   459

   460

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

   461

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

   462

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

   463

   464

\paragraph{Syslog}

   465

   466

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

   467

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

   468

command should result in the messages below:

   469

   470

\begin{lstlisting}

   471

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

   472

EtherCAT: Master driver `\masterversion`

   473

EtherCAT: 2 masters waiting for devices.

   474

   475

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

   476

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

   477

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

   478

                                 for devices.

   479

\end{lstlisting}

   480

   481

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

   482

searching the logs easier.

   483

   484

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

   485

   486

\section{Master Phases}

   487

\index{Master phases}

   488

   489

Every EtherCAT master provided by the master module (see

   490

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

   491

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

   492

   493

\begin{figure}[htbp]

   494

  \centering

   495

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

   496

  \caption{Master phases and transitions}