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

    23

\usepackage{hyperref}

    24

    25

\hypersetup{pdfpagelabels,plainpages=false}

    26

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

    27

    28

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

    29

\setlength{\parindent}{0mm}

    30

    31

\setcounter{secnumdepth}{\subsubsectionlevel}

    32

    33

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

    34

{

    35

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

    36

}{}

    37

    38

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

    39

  belowskip=2mm,escapechar=`}

    40

\renewcommand\lstlistlistingname{List of Listings}

    41

    42

% Workaround for lstlistoflistings bug

    43

\makeatletter% --> De-TeX-FAQ

    44

\renewcommand*{\lstlistoflistings}{%

    45

  \begingroup

    46

    \if@twocolumn

    47

      \@restonecoltrue\onecolumn

    48

    \else

    49

      \@restonecolfalse

    50

    \fi

    51

    \lol@heading

    52

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

    53

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

    54

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

    55

    \@starttoc{lol}%

    56

    \if@restonecol\twocolumn\fi

    57

  \endgroup

    58

}

    59

\makeatother% --> \makeatletter

    60

    61

\renewcommand\nomname{Glossary}

    62

    63

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

    64

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

    65

    66

\rcsInfo $RCSId$

    67

    68

\newcommand{\masterversion}{1.5.0}

    69

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

    70

    71

\makeindex

    72

\makenomenclature

    73

    74

% Revision and date on inner footer

    75

\ifoot[\scriptsize\rcsInfoRevision, \rcsInfoDate]

    76

    {\scriptsize\rcsInfoRevision, \rcsInfoDate}

    77

    78

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

    79

    80

\begin{document}

    81

    82

\pagenumbering{roman}

    83

\pagestyle{empty}

    84

    85

\begin{titlepage}

    86

  \begin{center}

    87

    \rule{\textwidth}{1.5mm}

    88

    89

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

    90

      Master \masterversion}\\[1ex]

    91

      \textbf{Documentation}}

    92

    93

    \vspace{1ex}

    94

    \rule{\textwidth}{1.5mm}

    95

    96

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

    97

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

    98

    99

    \vspace{\fill}

   100

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

   101

      Revision \rcsInfoRevision}

   102

  \end{center}

   103

\end{titlepage}

   104

   105

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

   106

   107

\pagestyle{scrplain}

   108

   109

\tableofcontents

   110

\listoftables

   111

\listoffigures

   112

%\lstlistoflistings

   113

   114

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

   115

   116

\newpage

   117

\pagestyle{scrheadings}

   118

   119

\section*{Conventions}

   120

\addcontentsline{toc}{section}{Conventions}

   121

\markleft{Conventions}

   122

   123

The following typographic conventions are used:

   124

   125

\begin{itemize}

   126

   127

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

   128

   129

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

   130

output.

   131

   132

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

   133

lines.

   134

   135

\end{itemize}

   136

   137

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

   138

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

   139

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

   140

values are specified as byte addresses.

   141

   142

Function names are always printed with parentheses, but without

   143

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

   144

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

   145

   146

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

   147

   148

\begin{lstlisting}

   149

$

   150

\end{lstlisting}

   151

   152

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

   153

prompt is a mesh:

   154

   155

\begin{lstlisting}

   156

#

   157

\end{lstlisting}

   158

   159

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

   160

   161

\chapter{The IgH EtherCAT Master}

   162

\label{chapter:master}

   163

\pagenumbering{arabic}

   164

   165

This chapter covers some general information about the EtherCAT master.

   166

   167

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

   168

   169

\section{Feature Summary}

   170

\label{sec:summary}

   171

\index{Master!Features}

   172

   173

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

   174

   175

\begin{itemize}

   176

   177

\item Designed as a kernel module for Linux 2.6.

   178

   179

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

   180

   181

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

   182

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

   183

kernel.

   184

   185

  \begin{itemize}

   186

   187

  \item The native drivers operate the hardware without interrupts.

   188

   189

  \item Native drivers for additional Ethernet hardware can easily be

   190

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

   191

  provided by the master module.

   192

   193

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

   194

  lower layers of the Linux network stack.

   195

   196

  \end{itemize}

   197

   198

\item The master module supports multiple EtherCAT masters running in

   199

parallel.

   200

   201

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

   202

independent architecture.

   203

   204

  \begin{itemize}

   205

   206

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

   207

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

   208

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

   209

   210

  \item It runs well even without realtime extensions.

   211

   212

  \end{itemize}

   213

   214

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

   215

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

   216

   217

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

   218

  data transfers with different slave groups and task periods.

   219

   220

  \begin{itemize}

   221

   222

  \item Handling of multiple domains with different task periods.

   223

   224

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

   225

  configuration within each domain.

   226

   227

  \end{itemize}

   228

   229

\item Communication through several finite state machines.

   230

   231

  \begin{itemize}

   232

   233

  \item Automatic bus scanning after topology changes.

   234

   235

  \item Bus monitoring during operation.

   236

   237

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

   238

  during operation.

   239

   240

  \end{itemize}

   241

   242

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

   243

   244

  \begin{itemize}

   245

   246

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

   247

  interface.

   248

   249

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

   250

  slave clocks to the reference clock.

   251

   252

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

   253

   254

  \end{itemize}

   255

   256

\item CANopen over EtherCAT (CoE)

   257

   258

  \begin{itemize}

   259

   260

  \item SDO upload, download and information service.

   261

   262

  \item Slave configuration via SDOs.

   263

   264

  \item SDO access from userspace and from the application.

   265

   266

  \end{itemize}

   267

   268

\item Ethernet over EtherCAT (EoE)

   269

   270

  \begin{itemize}

   271

   272

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

   273

   274

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

   275

  architecture.

   276

   277

  \end{itemize}

   278

   279

\item Vendor-specific over EtherCAT (VoE)

   280

   281

  \begin{itemize}

   282

   283

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

   284

   285

  \end{itemize}

   286

   287

\item File Access over EtherCAT (FoE)

   288

   289

  \begin{itemize}

   290

   291

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

   292

   293

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

   294

   295

  \end{itemize}

   296

   297

\item Servo Profile over EtherCAT (SoE)

   298

   299

  \begin{itemize}

   300

   301

  \item Implemented according to IEC 61800-7 \cite{soespec}.

   302

   303

  \item Storing IDN configurations, that are written to the slave during

   304

  startup.

   305

   306

  \item Accessing IDNs via the command-line tool.

   307

   308

  \item Accessing IDNs at runtime via the the user-space library.

   309

   310

  \end{itemize}

   311

   312

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

   313

   314

  \begin{itemize}

   315

   316

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

   317

  configuration.

   318

  \item Setting the master's debug level.

   319

  \item Reading/Writing alias addresses.

   320

  \item Listing slave configurations.

   321

  \item Viewing process data.

   322

  \item SDO download/upload; listing SDO dictionaries.

   323

  \item Loading and storing files via FoE.

   324

  \item SoE IDN access.

   325

  \item Access to slave registers.

   326

  \item Slave SII (EEPROM) access.

   327

  \item Controlling application-layer states.

   328

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

   329

   330

  \end{itemize}

   331

   332

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

   333

    Standard Base} compliance.

   334

   335

  \begin{itemize}

   336

   337

  \item Master and network device configuration via sysconfig files.

   338

   339

  \item Init script for master control.

   340

   341

  \end{itemize}

   342

   343

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

   344

  purposes.

   345

   346

\end{itemize}

   347

   348

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

   349

   350

\section{License}

   351

\label{sec:license}

   352

   353

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

   354

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

   355

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

   356

even participate on development.

   357

   358

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

   359

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

   360

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

   361

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

   362

   363

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

   364

   365

\chapter{Architecture}

   366

\label{chap:arch}

   367

\index{Master!Architecture}

   368

   369

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

   370

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

   371

   372

\begin{itemize}

   373

   374

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

   375

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

   376

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

   377

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

   378

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

   379

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

   380

   381

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

   382

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

   383

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

   384

master code being in kernelspace.

   385

   386

\end{itemize}

   387

   388

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

   389

   390

\begin{figure}[htbp]

   391

  \centering

   392

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

   393

  \caption{Master Architecture}

   394

  \label{fig:arch}

   395

\end{figure}

   396

   397

The components of the master environment are described below:

   398

   399

\begin{description}

   400

   401

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

   402

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

   403

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

   404

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

   405

   406

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

   407

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

   408

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

   409

network drivers can handle network devices used for EtherCAT operation and

   410

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

   411

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

   412

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

   413

usual.

   414

   415

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

   416

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

   417

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

   418

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

   419

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

   420

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

   421

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

   422

configuration and exchange process data.  Applications can be kernel modules

   423

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

   424

that use the application interface via the EtherCAT library (see

   425

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

   426

   427

\end{description}

   428

   429

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

   430

   431

\section{Master Module}

   432

\label{sec:mastermod}

   433

\index{Master module}

   434

   435

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

   436

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

   437

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

   438

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

   439

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

   440

given.

   441

   442

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

   443

waits for the Ethernet device with the MAC address

   444

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

   445

   446

\begin{lstlisting}

   447

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

   448

\end{lstlisting}

   449

   450

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

   451

   452

\begin{lstlisting}

   453

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

   454

\end{lstlisting}

   455

   456

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

   457

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

   458

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

   459

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

   460

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

   461

to $0$.

   462

   463

\begin{figure}[htbp]

   464

  \centering

   465

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

   466

  \caption{Multiple masters in one module}

   467

  \label{fig:masters}

   468

\end{figure}

   469

   470

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

   471

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

   472

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

   473

   474

\paragraph{Init Script}

   475

\index{Init script}

   476

   477

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

   478

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

   479

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

   480

   481

\paragraph{Syslog}

   482

   483

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

   484

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

   485

command should result in the messages below:

   486

   487

\begin{lstlisting}

   488

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

   489

EtherCAT: Master driver `\masterversion`

   490

EtherCAT: 2 masters waiting for devices.

   491

   492

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

   493

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

   494

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

   495

                                 for devices.

   496

\end{lstlisting}