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

\SVN $Date$

    66

\SVN $Revision$

    67

    68

\newcommand{\masterversion}{1.5.0}

    69

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

    70

    71

\makeindex

    72

\makenomenclature

    73

    74

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

    75

    76

\begin{document}

    77

    78

\pagenumbering{roman}

    79

\pagestyle{empty}

    80

    81

\begin{titlepage}

    82

  \begin{center}

    83

    \rule{\textwidth}{1.5mm}

    84

    85

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

    86

      Master \masterversion\\[1ex]

    87

      Preliminary Documentation}

    88

    89

    \vspace{1ex}

    90

    \rule{\textwidth}{1.5mm}

    91

    92

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

    93

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

    94

    95

    \vspace{\fill}

    96

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

    97

      Revision \SVNRevision}

    98

  \end{center}

    99

\end{titlepage}

   100

   101

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

   102

   103

\tableofcontents

   104

\listoftables

   105

\listoffigures

   106

%\lstlistoflistings

   107

   108

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

   109

   110

\newpage

   111

\pagestyle{scrheadings}

   112

   113

\section*{Conventions}

   114

\addcontentsline{toc}{section}{Conventions}

   115

\markleft{Conventions}

   116

   117

The following typographic conventions are used:

   118

   119

\begin{itemize}

   120

   121

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

   122

   123

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

   124

output.

   125

   126

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

   127

lines.

   128

   129

\end{itemize}

   130

   131

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

   132

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

   133

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

   134

values are specified as byte addresses.

   135

   136

Function names are always printed with parentheses, but without

   137

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

   138

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

   139

   140

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

   141

   142

\begin{lstlisting}

   143

$

   144

\end{lstlisting}

   145

   146

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

   147

prompt is a mesh:

   148

   149

\begin{lstlisting}

   150

#

   151

\end{lstlisting}

   152

   153

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

   154

   155

\chapter{The IgH EtherCAT Master}

   156

\label{chapter:master}

   157

\pagenumbering{arabic}

   158

   159

This chapter covers some general information about the EtherCAT master.

   160

   161

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

   162

   163

\section{Feature Summary}

   164

\label{sec:summary}

   165

\index{Master!Features}

   166

   167

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

   168

   169

\begin{itemize}

   170

   171

\item Designed as a kernel module for Linux 2.6.

   172

   173

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

   174

   175

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

   176

   177

  \begin{itemize}

   178

   179

  \item The Ethernet hardware is operated without interrupts.

   180

   181

  \item Drivers for additional Ethernet hardware can easily be implemented

   182

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

   183

  master module.

   184

   185

  \end{itemize}

   186

   187

\item The master module supports multiple EtherCAT masters running in

   188

parallel.

   189

   190

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

   191

independent architecture.

   192

   193

  \begin{itemize}

   194

   195

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

   196

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

   197

  Systems}, etc.

   198

   199

  \item It runs well even without realtime extensions.

   200

   201

  \end{itemize}

   202

   203

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

   204

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

   205

   206

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

   207

  data transfers with different slave groups and task periods.

   208

   209

  \begin{itemize}

   210

   211

  \item Handling of multiple domains with different task periods.

   212

   213

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

   214

  configuration within each domain.

   215

   216

  \end{itemize}

   217

   218

\item Communication through several finite state machines.

   219

   220

  \begin{itemize}

   221

   222

  \item Automatic bus scanning after topology changes.

   223

   224

  \item Bus monitoring during operation.

   225

   226

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

   227

  during operation.

   228

   229

  \end{itemize}

   230

   231

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

   232

   233

  \begin{itemize}

   234

   235

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

   236

  interface.

   237

   238

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

   239

  slave clocks to the reference clock.

   240

   241

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

   242

   243

  \end{itemize}

   244

   245

\item CANopen over EtherCAT (CoE)

   246

   247

  \begin{itemize}

   248

   249

  \item SDO upload, download and information service.

   250

   251

  \item Slave configuration via SDOs.

   252

   253

  \item SDO access from userspace and from the application.

   254

   255

  \end{itemize}

   256

   257

\item Ethernet over EtherCAT (EoE)

   258

   259

  \begin{itemize}

   260

   261

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

   262

   263

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

   264

  architecture.

   265

   266

  \end{itemize}

   267

   268

\item Vendor-specific over EtherCAT (VoE)

   269

   270

  \begin{itemize}

   271

   272

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

   273

   274

  \end{itemize}

   275

   276

\item File Access over EtherCAT (FoE)

   277

   278

  \begin{itemize}

   279

   280

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

   281

   282

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

   283

   284

  \end{itemize}

   285

   286

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

   287

   288

  \begin{itemize}

   289

   290

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

   291

  configuration.

   292

  \item Setting the master's debug level.

   293

  \item Reading/Writing alias addresses.

   294

  \item Listing slave configurations.

   295

  \item Viewing process data.

   296

  \item SDO download/upload; listing SDO dictionaries.

   297

  \item Loading and storing files via FoE.

   298

  \item Access to slave registers.

   299

  \item Slave SII (EEPROM) access.

   300

  \item Controlling application-layer states.

   301

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

   302

   303

  \end{itemize}

   304

   305

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

   306

    Standard Base} compliance.

   307

   308

  \begin{itemize}

   309

   310

  \item Master and network device configuration via sysconfig files.

   311

   312

  \item Init script for master control.

   313

   314

  \end{itemize}

   315

   316

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

   317

  purposes.

   318

   319

\end{itemize}

   320

   321

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

   322

   323

\section{License}

   324

\label{sec:license}

   325

   326

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

   327

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

   328

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

   329

even participate on development.

   330

   331

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

   332

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

   333

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

   334

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

   335

   336

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

   337

   338

\chapter{Architecture}

   339

\label{chap:arch}

   340

\index{Master!Architecture}

   341

   342

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

   343

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

   344

   345

\begin{itemize}

   346

   347

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

   348

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

   349

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

   350

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

   351

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

   352

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

   353

   354

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

   355

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

   356

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

   357

master code being in kernelspace.

   358

   359

\end{itemize}

   360

   361

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

   362

   363

\begin{figure}[htbp]

   364

  \centering

   365

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

   366

  \caption{Master Architecture}

   367

  \label{fig:arch}

   368

\end{figure}

   369

   370

The components of the master environment are described below:

   371

   372

\begin{description}

   373

   374

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

   375

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

   376

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

   377

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

   378

   379

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

   380

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

   381

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

   382

network drivers can handle network devices used for EtherCAT operation and

   383

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

   384

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

   385

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

   386

usual.

   387

   388

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

   389

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

   390

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

   391

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

   392

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

   393

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

   394

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

   395

configuration and exchange process data.  Applications can be kernel modules

   396

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

   397

that use the application interface via the EtherCAT library (see

   398

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

   399

   400

\end{description}

   401

   402

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

   403

   404

\section{Master Module}

   405

\label{sec:mastermod}

   406

\index{Master module}

   407

   408

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

   409

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

   410

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

   411

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

   412

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

   413

given.

   414

   415

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

   416

waits for the Ethernet device with the MAC address

   417

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

   418

   419

\begin{lstlisting}

   420

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

   421

\end{lstlisting}

   422

   423

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

   424

   425

\begin{lstlisting}

   426

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

   427

\end{lstlisting}

   428

   429

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

   430

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

   431

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

   432

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

   433

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

   434

to $0$.

   435

   436

\begin{figure}[htbp]

   437

  \centering

   438

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

   439

  \caption{Multiple masters in one module}

   440

  \label{fig:masters}

   441

\end{figure}

   442

   443

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

   444

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

   445

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

   446

   447

\paragraph{Init Script}

   448

\index{Init script}

   449

   450

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

   451

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

   452

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

   453

   454

\paragraph{Syslog}

   455

   456

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

   457

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

   458

command should result in the messages below:

   459

   460

\begin{lstlisting}

   461

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

   462

EtherCAT: Master driver `\masterversion`

   463

EtherCAT: 2 masters waiting for devices.

   464

   465

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

   466

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

   467

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

   468

                                 for devices.

   469

\end{lstlisting}

   470

   471

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

   472

searching the logs easier.

   473

   474

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

   475

   476

\section{Master Phases}

   477

\index{Master phases}

   478

   479

Every EtherCAT master provided by the master module (see

   480

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

   481

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

   482

   483

\begin{figure}[htbp]

   484

  \centering

   485

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

   486

  \caption{Master phases and transitions}

   487

  \label{fig:phases}

   488

\end{figure}

   489

   490

\begin{description}

   491

   492

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

   493

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

   494

possible until then.

   495

   496

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

   497

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