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

      Preliminary Documentation}

    86

    87

    \vspace{1ex}

    88

    \rule{\textwidth}{1.5mm}

    89

    90

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

    91

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

    92

    93

    \vspace{\fill}

    94

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

    95

      Revision \SVNRevision}

    96

  \end{center}

    97

\end{titlepage}

    98

    99

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

   100

   101

\tableofcontents

   102

\listoftables

   103

\listoffigures

   104

%\lstlistoflistings

   105

   106

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

   107

   108

\newpage

   109

\pagestyle{scrheadings}

   110

   111

\section*{Conventions}

   112

\addcontentsline{toc}{section}{Conventions}

   113

\markleft{Conventions}

   114

   115

The following typographic conventions are used:

   116

   117

\begin{itemize}

   118

   119

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

   120

   121

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

   122

output.

   123

   124

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

   125

lines.

   126

   127

\end{itemize}

   128

   129

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

   130

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

   131

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

   132

values are specified as byte addresses.

   133

   134

Function names are always printed with parentheses, but without

   135

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

   136

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

   137

   138

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

   139

   140

\begin{lstlisting}

   141

$

   142

\end{lstlisting}

   143

   144

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

   145

prompt is a mesh:

   146

   147

\begin{lstlisting}

   148

#

   149

\end{lstlisting}

   150

   151

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

   152

   153

\chapter{The IgH EtherCAT Master}

   154

\label{chapter:master}

   155

\pagenumbering{arabic}

   156

   157

This chapter covers some general information about the EtherCAT master.

   158

   159

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

   160

   161

\section{Feature Summary}

   162

\label{sec:summary}

   163

\index{Master!Features}

   164

   165

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

   166

   167

\begin{itemize}

   168

   169

\item Designed as a kernel module for Linux 2.6.

   170

   171

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

   172

   173

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

   174

   175

  \begin{itemize}

   176

   177

  \item The Ethernet hardware is operated without interrupts.

   178

   179

  \item Drivers for additional Ethernet hardware can easily be implemented

   180

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

   181

  the master module.

   182

   183

  \end{itemize}

   184

   185

\item The master module supports multiple EtherCAT masters running in

   186

parallel.

   187

   188

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

   189

independent architecture.

   190

   191

  \begin{itemize}

   192

   193

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

   194

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

   195

  Systems}, etc.

   196

   197

  \item It runs well even without realtime extensions.

   198

   199

  \end{itemize}

   200

   201

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

   202

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

   203

   204

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

   205

  data transfers with different slave groups and task periods.

   206

   207

  \begin{itemize}

   208

   209

  \item Handling of multiple domains with different task periods.

   210

   211

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

   212

  configuration within each domain.

   213

   214

  \end{itemize}

   215

   216

\item Communication through several finite state machines.

   217

   218

  \begin{itemize}

   219

   220

  \item Automatic bus scanning after topology changes.

   221

   222

  \item Bus monitoring during operation.

   223

   224

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

   225

  during operation.

   226

   227

  \end{itemize}

   228

   229

\item CANopen-over-EtherCAT (CoE)

   230

   231

  \begin{itemize}

   232

   233

  \item Sdo upload, download and information service.

   234

   235

  \item Slave configuration via Sdos.

   236

   237

  \item Sdo access from user-space and from the application.

   238

   239

  \end{itemize}

   240

   241

\item Ethernet-over-EtherCAT (EoE)

   242

   243

  \begin{itemize}

   244

   245

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

   246

   247

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

   248

  architecture.

   249

   250

  \end{itemize}

   251

   252

\item User space command-line-tool ``ethercat`` (see

   253

section~\ref{sec:ethercat})

   254

   255

  \begin{itemize}

   256

   257

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

   258

  \item Showing the bus configuration.

   259

  \item Showing domains and process data.

   260

  \item Setting the master's debug level.

   261

  \item Writing alias addresses.

   262

  \item Sdo uploading/downloading.

   263

  \item Reading/writing a slave's SII.

   264

  \item Setting slave states.

   265

  \item Generate slave description XML.

   266

   267

  \end{itemize}

   268

   269

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

   270

    Standard Base} compliance.

   271

   272

  \begin{itemize}

   273

   274

  \item Master and network device configuration via sysconfig files.

   275

   276

  \item Init script for master control.

   277

   278

  \end{itemize}

   279

   280

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

   281

  purposes.

   282

   283

\end{itemize}

   284

   285

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

   286

   287

\section{License}

   288

\label{sec:license}

   289

   290

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

   291

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

   292

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

   293

to use the master code or even participate on development.

   294

   295

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

   296

   297

\chapter{Architecture}

   298

\label{sec:arch}

   299

\index{Master!Architecture}

   300

   301

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

   302

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

   303

   304

\begin{itemize}

   305

   306

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

   307

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

   308

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

   309

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

   310

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

   311

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

   312

   313

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

   314

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

   315

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

   316

master code being in kernel space.

   317

   318

\end{itemize}

   319

   320

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

   321

   322

\begin{figure}[htbp]

   323

  \centering

   324

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

   325

  \caption{Master architecture}

   326

  \label{fig:arch}

   327

\end{figure}

   328

   329

\paragraph{Master Module}

   330

\index{Master module}

   331

   332

Kernel module containing one or more EtherCAT master instances (see

   333

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

   334

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

   335

section~\ref{sec:ecrt}).

   336

   337

\paragraph{Device Modules}

   338

\index{Device modules}

   339

   340

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

   341

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

   342

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

   343

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

   344

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

   345

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

   346

connected to the kernel's network stack as usual.

   347

   348

\paragraph{Application Modules}

   349

\index{Application module}

   350

   351

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

   352

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

   353

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

   354

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

   355

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

   356

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

   357

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

   358

process data.

   359

   360

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

   361

   362

\section{Phases}

   363

\index{Master phases}

   364

   365

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

   366

   367

\begin{figure}[htbp]

   368

  \centering

   369

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

   370

  \caption{Master phases and transitions}

   371

  \label{fig:phases}

   372

\end{figure}

   373

\begin{description}

   374

   375

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

   376

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

   377

possible until then.

   378

   379

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

   380

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

   381

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

   382

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

   383

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

   384

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

   385

configuration.

   386

   387

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

   388

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

   389

   390

\end{description}

   391

   392

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

   393

   394

\section{General Behavior} % FIXME

   395

\index{Master behavior}

   396

   397

\ldots

   398

   399

%   Behavior (Scanning) TODO

   400

   401

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

   402

   403

\section{Master Module}

   404

\label{sec:mastermod}

   405

\index{Master module}

   406

   407

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

   408

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

   409

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

   410

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

   411

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

   412

given.

   413

   414

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

   415

waits for the Ethernet device with the MAC address

   416

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

   417

   418

\begin{lstlisting}

   419

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

   420

\end{lstlisting}

   421

   422

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

   423

   424

\begin{lstlisting}

   425

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

   426

\end{lstlisting}

   427

   428

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

   429

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

   430

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

   431

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

   432

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

   433

defaults to $0$.

   434

   435

\begin{figure}[htbp]

   436

  \centering

   437

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

   438

  \caption{Multiple masters in one module}

   439

  \label{fig:masters}

   440

\end{figure}

   441

   442

\paragraph{Init script}

   443

\index{Init script}

   444

   445

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

   446

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

   447

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

   448

   449

\paragraph{Syslog}

   450

   451

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

   452

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

   453

loading command should result in the messages below:

   454

   455

\begin{lstlisting}

   456

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

   457

EtherCAT: Master driver `\masterversion`

   458

EtherCAT: 2 masters waiting for devices.

   459

   460

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

   461

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

   462

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

   463

                                 for devices.

   464

\end{lstlisting}

   465

   466

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

   467

searching the logs easier.

   468

   469

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

   470

   471

\section{Handling of Process Data} % FIXME

   472

\label{sec:processdata}

   473

   474

\ldots

   475

   476

\paragraph{Process Data Image}

   477

\index{Process data}

   478

   479

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

   480

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

   481

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

   482

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

   483

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

   484

exchanged via the ``Logical ReadWrite'' datagrams introduced

   485

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

   486

   487

\paragraph{Process Data Domains}

   488

\index{Domain}

   489

   490

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

   491

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

   492

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

   493

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

   494

reasons:

   495

   496

\begin{itemize}

   497

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

   498

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

   499

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