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[pdfpagelabels,plainpages=false]{hyperref}

    24

    25

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

    26

\setlength{\parindent}{0mm}

    27

    28

\setcounter{secnumdepth}{\subsubsectionlevel}

    29

    30

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

    31

{

    32

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

    33

}{}

    34

    35

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

    36

  belowskip=2mm,escapechar=`}

    37

\renewcommand\lstlistlistingname{List of Listings}

    38

    39

% Workaround for lstlistoflistings bug

    40

\makeatletter% --> De-TeX-FAQ

    41

\renewcommand*{\lstlistoflistings}{%

    42

  \begingroup

    43

    \if@twocolumn

    44

      \@restonecoltrue\onecolumn

    45

    \else

    46

      \@restonecolfalse

    47

    \fi

    48

    \lol@heading

    49

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

    50

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

    51

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

    52

    \@starttoc{lol}%

    53

    \if@restonecol\twocolumn\fi

    54

  \endgroup

    55

}

    56

\makeatother% --> \makeatletter

    57

    58

\renewcommand\nomname{Glossary}

    59

    60

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

    61

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

    62

    63

\SVN $Date$

    64

\SVN $Revision$

    65

    66

\newcommand{\masterversion}{1.4.0}

    67

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

    68

    69

\makeindex

    70

\makenomenclature

    71

    72

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

    73

    74

\begin{document}

    75

    76

\pagenumbering{roman}

    77

\pagestyle{empty}

    78

    79

\begin{titlepage}

    80

  \begin{center}

    81

    \rule{\textwidth}{1.5mm}

    82

    83

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

    84

      Master \masterversion\\[1ex]

    85

      Documentation}

    86

    87

    \vspace{1ex}

    88

    \rule{\textwidth}{1.5mm}

    89

    90

    \vspace{\fill}

    91

    {\Large Florian Pose, \url{fp@igh-essen.com}\\[1ex]

    92

      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 section~\ref{sec:ecdev}) provided by

   182

  the 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 ``realtime interface'' for applications, that want to use

   203

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

   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 user-space 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 User space command-line-tool ``ethercat`` (see

   254

section~\ref{sec:ethercat})

   255

   256

  \begin{itemize}

   257

   258

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

   259

  \item Showing the bus configuration.

   260

  \item Showing domains and process data.

   261

  \item Setting the master's debug level.

   262

  \item Writing alias addresses.

   263

  \item Sdo uploading/downloading.

   264

  \item Reading/writing a slave's SII.

   265

  \item Setting slave states.

   266

  \item Generate slave description XML.

   267

   268

  \end{itemize}

   269

   270

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

   271

    Standard Base} compliance.

   272

   273

  \begin{itemize}

   274

   275

  \item Master and network device configuration via sysconfig files.

   276

   277

  \item Init script for master control.

   278

   279

  \end{itemize}

   280

   281

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

   282

  purposes.

   283

   284

\end{itemize}

   285

   286

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

   287

   288

\section{License}

   289

\label{sec:license}

   290

   291

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

   292

General Public License\index{GPL} \cite{gpl} (version 2). Other

   293

developers, that want to use EtherCAT with Linux systems, are invited

   294

to use the master code or even participate on development.

   295

   296

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

   297

   298

\chapter{Architecture}

   299

\label{sec:arch}

   300

\index{Master!Architecture}

   301

   302

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

   303

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

   304

   305

\begin{itemize}

   306

   307

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

   308

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

   309

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

   310

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

   311

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

   312

need of time-consuming context switches to a user space process.

   313

   314

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

   315

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

   316

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

   317

master code being in kernel space.

   318

   319

\end{itemize}

   320

   321

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

   322

   323

\begin{figure}[htbp]

   324

  \centering

   325

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

   326

  \caption{Master architecture}

   327

  \label{fig:arch}

   328

\end{figure}

   329

   330

\paragraph{Master Module}

   331

\index{Master module}

   332

   333

Kernel module containing one or more EtherCAT master instances (see

   334

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

   335

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

   336

section~\ref{sec:ecrt}).

   337

   338

\paragraph{Device Modules}

   339

\index{Device modules}

   340

   341

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

   342

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

   343

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

   344

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

   345

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

   346

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

   347

connected to the kernel's network stack as usual.

   348

   349

\paragraph{Application Modules}

   350

\index{Application module}

   351

   352

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

   353

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

   354

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

   355

\textit{examples} directory, see chapter~\ref{chapter:examples}}, but have to

   356

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

   357

master through the realtime interface (see section~\ref{sec:ecrt}). If this

   358

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

   359

configuration and exchange process data.

   360

   361

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

   362

   363

\section{Phases}

   364

\index{Master phases}

   365

   366

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

   367

   368

\begin{figure}[htbp]

   369

  \centering

   370

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

   371

  \caption{Master phases and transitions}

   372

  \label{fig:phases}

   373

\end{figure}

   374

\begin{description}

   375

   376

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

   377

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

   378

possible until then.

   379

   380

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

   381

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

   382

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

   383

scans the bus for slaves and executes pending operations from the user space

   384

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

   385

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

   386

configuration.

   387

   388

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

   389

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

   390

   391

\end{description}

   392

   393

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

   394

   395

\section{General Behavior} % FIXME

   396

\index{Master behavior}

   397

   398

\ldots

   399

   400

%   Behavior (Scanning) TODO

   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 realtime interface (see

   432

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

   433

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

   434

defaults 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{Init script}

   444

\index{Init script}

   445

   446

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

   447

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

   448

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

   449

   450

\paragraph{Syslog}

   451

   452

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

   453

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

   454

loading command should result in the messages below:

   455

   456

\begin{lstlisting}

   457

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

   458

EtherCAT: Master driver `\masterversion`

   459

EtherCAT: 2 masters waiting for devices.

   460

   461

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

   462

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

   463

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

   464

                                 for devices.

   465

\end{lstlisting}

   466

   467

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

   468

searching the logs easier.

   469

   470

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

   471

   472

\section{Handling of Process Data} % FIXME

   473

\label{sec:processdata}

   474

   475

\ldots

   476

   477

\paragraph{Process Data Image}

   478

\index{Process data}

   479

   480

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

   481

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

   482

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

   483

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

   484

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

   485

exchanged via the ``Logical ReadWrite'' datagrams introduced

   486

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

   487

   488

\paragraph{Process Data Domains}

   489

\index{Domain}

   490

   491

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

   492

``domains'', which group Pdos and allocate the datagrams needed to

   493

exchange them. Domains are mandatory for process data exchange, so

   494

there has to be at least one. They were introduced for the following

   495

reasons:

   496

   497

\begin{itemize}

   498

\item The maximum size of a ``Logical ReadWrite'' datagram is limited

   499

  due to the limited size of an Ethernet frame: The maximum data size

   500

  is the Ethernet data field size minus the EtherCAT frame header,

   501

  EtherCAT datagram header and EtherCAT datagram footer: $1500 - 2 -