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}

    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.4.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

   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

   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

   297

   298

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

   299

   300

\chapter{Architecture}

   301

\label{sec:arch}

   302

\index{Master!Architecture}

   303

   304

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

   305

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

   306

   307

\begin{itemize}

   308

   315

   316

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

   317

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

   318

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

   320

   321

\end{itemize}

   322

   323

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

   324

   325

\begin{figure}[htbp]

   326

  \centering

   327

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

   328

  \caption{Master architecture}

   329

  \label{fig:arch}

   330

\end{figure}

   331

   332

\paragraph{Master Module}

   333

\index{Master module}

   334

   335

Kernel module containing one or more EtherCAT master instances (see

   336

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

   337

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

   338

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

   339

   340

\paragraph{Device Modules}

   341

\index{Device modules}

   342

   343

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

   344

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

   345

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

   346

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

   347

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

   348

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

   349

connected to the kernel's network stack as usual.

   350

   351

\paragraph{Application Modules}

   352

\index{Application module}

   353

   354

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

   355

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

   356

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

   357

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

   358

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

   359

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

   360

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

   361

process data.

   362

   363

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

   364

   365

\section{Phases}

   366

\index{Master phases}

   367

   368

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

   369

   370

\begin{figure}[htbp]

   371

  \centering

   372

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

   373

  \caption{Master phases and transitions}

   374

  \label{fig:phases}

   375

\end{figure}

   376

\begin{description}

   377

   378

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

   379

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

   380

possible until then.

   381

   382

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

   383

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

   384

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

   389

   390

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

   391

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

   392

   393

\end{description}

   394

   395

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

   396

   397

\section{General Behavior} % FIXME

   398

\index{Master behavior}

   399

   400

\ldots

   401

   402

%   Behavior (Scanning) TODO

   403

   404

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

   405

   406

\section{Master Module}

   407

\label{sec:mastermod}

   408

\index{Master module}

   409

   410

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

   411

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

   412

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

   413

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

   414

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

   415

given.

   416

   417

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

   418

waits for the Ethernet device with the MAC address

   419

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

   420

   421

\begin{lstlisting}

   422

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

   423

\end{lstlisting}

   424

   425

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

   426

   427

\begin{lstlisting}

   428

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

   429

\end{lstlisting}

   430

   431

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

   432

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

   433

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

   434

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

   435

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

   436

defaults to $0$.

   437

   438

\begin{figure}[htbp]

   439

  \centering

   440

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

   441

  \caption{Multiple masters in one module}

   442

  \label{fig:masters}

   443

\end{figure}

   444

   445

\paragraph{Init script}

   446

\index{Init script}

   447

   448

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

   449

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

   450

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

   451

   452

\paragraph{Syslog}

   453

   454

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

   455

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

   456

loading command should result in the messages below:

   457

   458

\begin{lstlisting}

   459

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

   460

EtherCAT: Master driver `\masterversion`

   461

EtherCAT: 2 masters waiting for devices.

   462

   463

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

   464

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

   465

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

   466

                                 for devices.

   467

\end{lstlisting}

   468

   469

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

   470

searching the logs easier.

   471

   472

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

   473

   474

\section{Handling of Process Data} % FIXME

   475

\label{sec:processdata}

   476

   477

\ldots

   478

   479

\paragraph{Process Data Image}

   480

\index{Process data}

   481

   482

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

   483

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

   484

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

   485

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

   486

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

   487

exchanged via the ``Logical ReadWrite'' datagrams introduced

   488

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

   489

   490

\paragraph{Process Data Domains}

   491

\index{Domain}

   492

   493

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

   494

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

   495

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

   496

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

   497

reasons:

   498