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 Vendor-specific over EtherCAT (VoE)

   254

   255

  \begin{itemize}

   256

   257

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

   258

   259

  \end{itemize}

   260

   261

\item File Access over EtherCAT (FoE)

   262

   263

  \begin{itemize}

   264

   265

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

   266

   267

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

   268

   269

  \end{itemize}

   270

   271

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

   272

   273

  \begin{itemize}

   274

   275

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

   276

  configuration.

   277

  \item Setting the master's debug level.

   278

  \item Reading/Writing alias addresses.

   279

  \item Listing slave configurations.

   280

  \item Viewing process data.

   281

  \item SDO download/upload; listing SDO dictionaries.

   282

  \item Loading and storing files via FoE.

   283

  \item Access to slave registers.

   284

  \item Slave SII (EEPROM) access.

   285

  \item Controlling application-layer states.

   286

  \item Generation of slave description XML from existing slaves.

   287

   288

  \end{itemize}

   289

   290

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

   291

    Standard Base} compliance.

   292

   293

  \begin{itemize}

   294

   295

  \item Master and network device configuration via sysconfig files.

   296

   297

  \item Init script for master control.

   298

   299

  \end{itemize}

   300

   301

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

   302

  purposes.

   303

   304

\end{itemize}

   305

   306

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

   307

   308

\section{License}

   309

\label{sec:license}

   310

   311

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

   312

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

   313

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

   314

even participate on development.

   315

   316

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

   317

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

   318

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

   319

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

   320

   321

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

   322

   323

\chapter{Architecture}

   324

\label{chap:arch}

   325

\index{Master!Architecture}

   326

   327

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

   328

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

   329

   330

\begin{itemize}

   331

   332

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

   333

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

   334

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

   335

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

   336

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

   337

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

   338

   339

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

   340

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

   341

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

   342

master code being in kernelspace.

   343

   344

\end{itemize}

   345

   346

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

   347

   348

\begin{figure}[htbp]

   349

  \centering

   350

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

   351

  \caption{Master Architecture}

   352

  \label{fig:arch}

   353

\end{figure}

   354

   355

The components of the master environment are described below:

   356

   357

\begin{description}

   358

   359

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

   360

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

   361

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

   362

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

   363

   364

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

   365

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

   366

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

   367

network drivers can handle network devices used for EtherCAT operation and

   368

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

   369

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

   370

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

   371

usual.

   372

   373

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

   374

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

   375

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

   376

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

   377

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

   378

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

   379

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

   380

configuration and exchange process data.  Applications can be kernel modules

   381

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

   382

that use the application interface via the EtherCAT library (see

   383

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

   384

   385

\end{description}

   386

   387

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

   388

   389

\section{Master Module}

   390

\label{sec:mastermod}

   391

\index{Master module}

   392

   393

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

   394

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

   395

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

   396

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

   397

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

   398

given.

   399

   400

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

   401

waits for the Ethernet device with the MAC address

   402

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

   403

   404

\begin{lstlisting}

   405

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

   406

\end{lstlisting}

   407

   408

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

   409

   410

\begin{lstlisting}

   411

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

   412

\end{lstlisting}

   413

   414

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

   415

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

   416

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

   417

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

   418

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

   419

to $0$.

   420

   421

\begin{figure}[htbp]

   422

  \centering

   423

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

   424

  \caption{Multiple masters in one module}

   425

  \label{fig:masters}

   426

\end{figure}

   427

   428

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

   429

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

   430

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

   431

   432

\paragraph{Init Script}

   433

\index{Init script}

   434

   435

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

   436

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

   437

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

   438

   439

\paragraph{Syslog}

   440

   441

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

   442

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

   443

command should result in the messages below:

   444

   445

\begin{lstlisting}

   446

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

   447

EtherCAT: Master driver `\masterversion`

   448

EtherCAT: 2 masters waiting for devices.

   449

   450

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

   451

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

   452

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

   453

                                 for devices.

   454

\end{lstlisting}

   455

   456

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

   457

searching the logs easier.

   458

   459

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

   460

   461

\section{Master Phases}

   462

\index{Master phases}

   463

   464

Every EtherCAT master provided by the master module (see

   465

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

   466

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

   467

   468

\begin{figure}[htbp]

   469

  \centering

   470

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

   471

  \caption{Master phases and transitions}

   472

  \label{fig:phases}

   473

\end{figure}

   474

   475

\begin{description}

   476

   477

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

   478

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

   479

possible until then.

   480

   481

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

   482

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

   483

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

   484

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

   485

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

   486

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

   487

bus configuration.

   488

   489

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

   490

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

   491

   492

\end{description}

   493

   494

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

   495

   496

\section{Process Data}

   497

\label{sec:processdata}