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

    21

\usepackage{url}

    22

\usepackage{SIunits}

    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

\SVN $Date$

    67

\SVN $Revision$

    68

    69

\newcommand{\masterversion}{1.5.0}

    70

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

    71

    72

\makeindex

    73

\makenomenclature

    74

    75

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

    76

    77

\begin{document}

    78

    79

\pagenumbering{roman}

    80

\pagestyle{empty}

    81

    82

\begin{titlepage}

    83

  \begin{center}

    84

    \rule{\textwidth}{1.5mm}

    85

    86

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

    87

      Master \masterversion\\[1ex]

    88

      Preliminary Documentation}

    89

    90

    \vspace{1ex}

    91

    \rule{\textwidth}{1.5mm}

    92

    93

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

    94

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

    95

    96

    \vspace{\fill}

    97

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

    98

      Revision \SVNRevision}

    99

  \end{center}

   100

\end{titlepage}

   101

   102

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

   103

   104

\tableofcontents

   105

\listoftables

   106

\listoffigures

   107

%\lstlistoflistings

   108

   109

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

   110

   111

\newpage

   112

\pagestyle{scrheadings}

   113

   114

\section*{Conventions}

   115

\addcontentsline{toc}{section}{Conventions}

   116

\markleft{Conventions}

   117

   118

The following typographic conventions are used:

   119

   120

\begin{itemize}

   121

   122

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

   123

   124

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

   125

output.

   126

   127

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

   128

lines.

   129

   130

\end{itemize}

   131

   132

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

   133

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

   134

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

   135

values are specified as byte addresses.

   136

   137

Function names are always printed with parentheses, but without

   138

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

   139

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

   140

   141

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

   142

   143

\begin{lstlisting}

   144

$

   145

\end{lstlisting}

   146

   147

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

   148

prompt is a mesh:

   149

   150

\begin{lstlisting}

   151

#

   152

\end{lstlisting}

   153

   154

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

   155

   156

\chapter{The IgH EtherCAT Master}

   157

\label{chapter:master}

   158

\pagenumbering{arabic}

   159

   160

This chapter covers some general information about the EtherCAT master.

   161

   162

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

   163

   164

\section{Feature Summary}

   165

\label{sec:summary}

   166

\index{Master!Features}

   167

   168

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

   169

   170

\begin{itemize}

   171

   172

\item Designed as a kernel module for Linux 2.6.

   173

   174

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

   175

   176

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

   177

   178

  \begin{itemize}

   179

   180

  \item The Ethernet hardware is operated without interrupts.

   181

   182

  \item Drivers for additional Ethernet hardware can easily be implemented

   183

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

   184

  the master module.

   185

   186

  \end{itemize}

   187

   188

\item The master module supports multiple EtherCAT masters running in

   189

parallel.

   190

   191

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

   192

independent architecture.

   193

   194

  \begin{itemize}

   195

   196

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

   197

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

   198

  Systems}, etc.

   199

   200

  \item It runs well even without realtime extensions.

   201

   202

  \end{itemize}

   203

   204

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

   205

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

   206

   207

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

   208

  data transfers with different slave groups and task periods.

   209

   210

  \begin{itemize}

   211

   212

  \item Handling of multiple domains with different task periods.

   213

   214

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

   215

  configuration within each domain.

   216

   217

  \end{itemize}

   218

   219

\item Communication through several finite state machines.

   220

   221

  \begin{itemize}

   222

   223

  \item Automatic bus scanning after topology changes.

   224

   225

  \item Bus monitoring during operation.

   226

   227

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

   228

  during operation.

   229

   230

  \end{itemize}

   231

   232

\item CANopen-over-EtherCAT (CoE)

   233

   234

  \begin{itemize}

   235

   236

  \item Sdo upload, download and information service.

   237

   238

  \item Slave configuration via Sdos.

   239

   240

  \item Sdo access from userspace and from the application.

   241

   242

  \end{itemize}

   243

   244

\item Ethernet-over-EtherCAT (EoE)

   245

   246

  \begin{itemize}

   247

   248

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

   249

   250

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

   251

  architecture.

   252

   253

  \end{itemize}

   254

   255

\item Userspace command-line-tool ``ethercat`` (see

   256

section~\ref{sec:ethercat})

   257

   258

  \begin{itemize}

   259

   260

  \item Showing the current bus with slaves, Pdos and Sdos.

   261

  \item Showing the bus configuration.

   262

  \item Showing domains and process data.

   263

  \item Setting the master's debug level.

   264

  \item Writing alias addresses.

   265

  \item Sdo uploading/downloading.

   266

  \item Reading/writing a slave's SII.

   267

  \item Setting slave states.

   268

  \item Generate slave description XML.

   269

   270

  \end{itemize}

   271

   272

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

   273

    Standard Base} compliance.

   274

   275

  \begin{itemize}

   276

   277

  \item Master and network device configuration via sysconfig files.

   278

   279

  \item Init script for master control.

   280

   281

  \end{itemize}

   282

   283

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

   284

  purposes.

   285

   286

\end{itemize}

   287

   288

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

   289

   290

\section{License}

   291

\label{sec:license}

   292

   293

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

   294

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

   295

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

   296

even participate on development.

   297

   298

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

   299

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

   300

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

   301

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

   302

   303

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

   304

   305

\chapter{Architecture}

   306

\label{sec:arch}

   307

\index{Master!Architecture}

   308

   309

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

   310

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

   311

   312

\begin{itemize}

   313

   314

\item Kernel code has significantly better realtime characteristics,

   315

i.\,e.~less latency than userspace code. It was foreseeable, that a fieldbus

   316

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

   317

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

   318

processes timer interrupts is less, when it resides in kernelspace, because

   319

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

   320

   321

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

   322

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

   323

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

   324

master code being in kernelspace.

   325

   326

\end{itemize}

   327

   328

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

   329

   330

\begin{figure}[htbp]

   331

  \centering

   332

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

   333

  \caption{Master architecture}

   334

  \label{fig:arch}

   335

\end{figure}

   336

   337

\paragraph{Master Module}

   338

\index{Master module}

   339

   340

Kernel module containing one or more EtherCAT master instances (see

   341

section~\ref{sec:mastermod}), the ``Device Interface'' (see

   342

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

   343

chap.~\ref{sec:ecrt}).

   344

   345

\paragraph{Device Modules}

   346

\index{Device modules}

   347

   348

EtherCAT-capable Ethernet device driver modules\index{Device modules}, that

   349

offer their devices to the EtherCAT master via the device interface (see

   350

section~\ref{sec:ecdev}). These modified network drivers can handle network

   351

devices used for EtherCAT operation and ``normal'' Ethernet devices in

   352

parallel. A master can accept a certain device and then is able to send and

   353

receive EtherCAT frames. Ethernet devices declined by the master module are

   354

connected to the kernel's network stack as usual.

   355

   356

\paragraph{Application Modules}

   357

\index{Application module}

   358

   359

Kernel modules, that use the EtherCAT master (usually for cyclic exchange of

   360

process data with EtherCAT slaves). These modules are not part of the EtherCAT

   361

master code\footnote{Although there are some examples provided in the

   362

\textit{examples/} directory.}, but have to be generated or written by the

   363

user. An application module can ``request'' a master through the application

   364

interface (see chap.~\ref{sec:ecrt}). If this succeeds, the module has the

   365

control over the master: It can provide a bus configuration and exchange

   366

process data.

   367

   368

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

   369

   370

\section{Phases}

   371

\index{Master phases}

   372

   373

The EtherCAT master runs through several phases (see fig.~\ref{fig:phases}):

   374

   375

\begin{figure}[htbp]

   376

  \centering

   377

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

   378

  \caption{Master phases and transitions}

   379

  \label{fig:phases}

   380

\end{figure}

   381

\begin{description}

   382

   383

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

   384

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

   385

possible until then.

   386

   387

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

   388

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

   389

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

   390

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

   391

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

   392

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

   393

bus configuration.

   394

   395

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

   396

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

   397

   398

\end{description}

   399

   400

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

   401

   402

\section{General Behavior} % FIXME

   403

\index{Master behavior}

   404

   405

\ldots

   406

   407

%   Behavior (Scanning) TODO

   408

   409

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

   410

   411

\section{Master Module}

   412

\label{sec:mastermod}

   413

\index{Master module}

   414

   415

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

   416

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

   417

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

   418

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

   419

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

   420

given.

   421

   422

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

   423

waits for the Ethernet device with the MAC address

   424

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

   425

   426

\begin{lstlisting}

   427

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

   428

\end{lstlisting}

   429

   430

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

   431

   432

\begin{lstlisting}

   433

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

   434

\end{lstlisting}

   435

   436

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

   437

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

   438

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

   439

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

   440

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

   441

defaults to $0$.

   442

   443

\begin{figure}[htbp]

   444

  \centering

   445

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

   446

  \caption{Multiple masters in one module}

   447

  \label{fig:masters}

   448

\end{figure}

   449

   450

\paragraph{Init script}

   451

\index{Init script}

   452

   453

Most probably you won't want to load the master module and the Ethernet driver

   454

modules manually, but start the master as a service. See

   455

section~\ref{sec:system} on how to do this.

   456

   457

\paragraph{Syslog}

   458

   459

The master module outputs information about it's state and events to the

   460

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

   461

loading command should result in the messages below:

   462

   463

\begin{lstlisting}

   464

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

   465

EtherCAT: Master driver `\masterversion`

   466

EtherCAT: 2 masters waiting for devices.

   467

   468

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

   469

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

   470

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

   471

                                 for devices.

   472

\end{lstlisting}

   473

   474

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

   475

searching the logs easier.

   476

   477

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

   478

   479

\section{Handling of Process Data} % FIXME

   480

\label{sec:processdata}

   481

   482

\ldots

   483

   484

\paragraph{Process Data Image}

   485

\index{Process data}

   486

   487

The slaves offer their inputs and outputs by presenting the master so-called

   488

``Process Data Objects'' (Pdos\index{Pdo}). The available Pdos can be

   489

determined by reading out the slave's TXPDO and RXPDO E$^2$PROM categories. The

   490

application can register the Pdos for data exchange during cyclic operation.

   491

The sum of all registered Pdos defines the ``process data image'', which is

   492

exchanged via the ``Logical ReadWrite'' datagrams introduced

   493

in~\cite[section~5.4.2.4]{dlspec}.

   494

   495

\paragraph{Process Data Domains}

   496

\index{Domain}

   497

   498

The process data image can be easily managed by creating so-called