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\sf\textbf{IgH \includegraphics[height=2.4ex]{images/ethercat}

    89

      Master \masterversion}\\[1ex]

    90

      \textbf{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 Servo Profile over EtherCAT (SoE)

   297

   298

  \begin{itemize}

   299

   300

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

   301

   302

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

   303

  startup.

   304

   305

  \item Accessing IDNs via the command-line tool.

   306

   307

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

   308

   309

  \end{itemize}

   310

   311

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

   312

   313

  \begin{itemize}

   314

   315

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

   316

  configuration.

   317

  \item Setting the master's debug level.

   318

  \item Reading/Writing alias addresses.

   319

  \item Listing slave configurations.

   320

  \item Viewing process data.

   321

  \item SDO download/upload; listing SDO dictionaries.

   322

  \item Loading and storing files via FoE.

   323

  \item SoE IDN access.

   324

  \item Access to slave registers.

   325

  \item Slave SII (EEPROM) access.

   326

  \item Controlling application-layer states.

   327

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

   328

   329

  \end{itemize}

   330

   331

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

   332

    Standard Base} compliance.

   333

   334

  \begin{itemize}

   335

   336

  \item Master and network device configuration via sysconfig files.

   337

   338

  \item Init script for master control.

   339

   340

  \end{itemize}

   341

   342

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

   343

  purposes.

   344

   345

\end{itemize}

   346

   347

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

   348

   349

\section{License}

   350

\label{sec:license}

   351

   352

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

   353

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

   354

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

   355

even participate on development.

   356

   357

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

   358

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

   359

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

   360

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

   361

   362

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

   363

   364

\chapter{Architecture}

   365

\label{chap:arch}

   366

\index{Master!Architecture}

   367

   368

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

   369

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

   370

   371

\begin{itemize}

   372

   373

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

   374

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

   375

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

   376

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

   377

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

   378

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

   379

   380

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

   381

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

   382

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

   383

master code being in kernelspace.

   384

   385

\end{itemize}

   386

   387

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

   388

   389

\begin{figure}[htbp]

   390

  \centering

   391

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

   392

  \caption{Master Architecture}

   393

  \label{fig:arch}

   394

\end{figure}

   395

   396

The components of the master environment are described below:

   397

   398

\begin{description}

   399

   400

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

   401

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

   402

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

   403

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

   404

   405

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

   406

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

   407

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

   408

network drivers can handle network devices used for EtherCAT operation and

   409

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

   410

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

   411

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

   412

usual.

   413

   414

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

   415

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

   416

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

   417

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

   418

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

   419

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

   420

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

   421

configuration and exchange process data.  Applications can be kernel modules

   422

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

   423

that use the application interface via the EtherCAT library (see

   424

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

   425

   426

\end{description}

   427

   428

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

   429

   430

\section{Master Module}

   431

\label{sec:mastermod}

   432

\index{Master module}

   433

   434

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

   435

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

   436

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

   437

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

   438

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

   439

given.

   440

   441

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

   442

waits for the Ethernet device with the MAC address

   443

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

   444

   445

\begin{lstlisting}

   446

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

   447

\end{lstlisting}

   448

   449

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

   450

   451

\begin{lstlisting}

   452

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

   453

\end{lstlisting}

   454

   455

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

   456

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

   457

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

   458

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

   459

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

   460

to $0$.

   461

   462

\begin{figure}[htbp]

   463

  \centering

   464

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

   465

  \caption{Multiple masters in one module}

   466

  \label{fig:masters}

   467

\end{figure}

   468

   469

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

   470

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

   471

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

   472

   473

\paragraph{Init Script}

   474

\index{Init script}

   475

   476

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

   477

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

   478

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

   479

   480

\paragraph{Syslog}

   481

   482

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

   483

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

   484

command should result in the messages below:

   485

   486

\begin{lstlisting}

   487

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

   488

EtherCAT: Master driver `\masterversion`

   489

EtherCAT: 2 masters waiting for devices.

   490

   491

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

   492

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

   493

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

   494

                                 for devices.

   495

\end{lstlisting}

   496