documentation/ethercat_doc.tex
author Florian Pose <fp@igh-essen.com>
Mon, 05 May 2014 13:55:00 +0200
branchstable-1.5
changeset 2542 8dd49f6f6d32
parent 2535 72b61b089625
child 2691 9149adda56ed
permissions -rw-r--r--
Fixed hex display of slave position; thanks to Henry Bausley.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
     1
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
     2
%
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
     3
%  IgH EtherCAT Master Documentation
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
     4
%
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
     5
%  $Id$
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
     6
%
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
     7
%  vi: spell spelllang=en tw=78
2421
bc2d4bf9cbe5 Removed trailing spaces.
Florian Pose <fp@igh-essen.com>
parents: 2419
diff changeset
     8
%
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
     9
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    10
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    11
\documentclass[a4paper,12pt,BCOR6mm,bibtotoc,idxtotoc]{scrbook}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    12
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    13
\usepackage[latin1]{inputenc}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    14
\usepackage[automark,headsepline]{scrpage2}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    15
\usepackage{graphicx}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    16
\usepackage{makeidx}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    17
\usepackage[refpage]{nomencl}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    18
\usepackage{listings}
1588
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
    19
\usepackage[nofancy]{rcsinfo}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
    20
\usepackage{SIunits}
1517
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
    21
\usepackage{amsmath} % for \text{}
2297
0566476835d7 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2133
diff changeset
    22
\usepackage{longtable}
1275
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
    23
\usepackage{hyperref}
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
    24
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
    25
\hypersetup{pdfpagelabels,plainpages=false}
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
    26
\hypersetup{linkcolor=blue,colorlinks=true,urlcolor=blue}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    27
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    28
\setlength{\parskip}{0.8ex plus 0.8ex minus 0.5ex}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    29
\setlength{\parindent}{0mm}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    30
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    31
\setcounter{secnumdepth}{\subsubsectionlevel}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    32
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    33
\DeclareFontShape{OT1}{cmtt}{bx}{n}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    34
{
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    35
  <5><6><7><8><9><10><10.95><12><14.4><17.28><20.74><24.88>cmttb10
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    36
}{}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    37
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    38
\lstset{basicstyle=\ttfamily\small,numberstyle=\tiny,aboveskip=4mm,
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
    39
  belowskip=2mm,escapechar=`,breaklines=true}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    40
\renewcommand\lstlistlistingname{List of Listings}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    41
917
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    42
% Workaround for lstlistoflistings bug
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    43
\makeatletter% --> De-TeX-FAQ
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    44
\renewcommand*{\lstlistoflistings}{%
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    45
  \begingroup
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    46
    \if@twocolumn
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    47
      \@restonecoltrue\onecolumn
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    48
    \else
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    49
      \@restonecolfalse
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    50
    \fi
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    51
    \lol@heading
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    52
    \setlength{\parskip}{\z@}%
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    53
    \setlength{\parindent}{\z@}%
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    54
    \setlength{\parfillskip}{\z@ \@plus 1fil}%
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    55
    \@starttoc{lol}%
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    56
    \if@restonecol\twocolumn\fi
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    57
  \endgroup
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    58
}
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    59
\makeatother% --> \makeatletter
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    60
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    61
\renewcommand\nomname{Glossary}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    62
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    63
\newcommand{\IgH}{\raisebox{-0.7667ex}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    64
  {\includegraphics[height=2.2ex]{images/ighsign}}}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    65
1589
ffe3cebd5d53 Revision and date on every page.
Florian Pose <fp@igh-essen.com>
parents: 1588
diff changeset
    66
\rcsInfo $RCSId$
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    67
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
    68
\newcommand{\masterversion}{1.5.2}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
    69
\newcommand{\linenum}[1]{\normalfont\textcircled{\tiny #1}}
487
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
    70
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    71
\makeindex
917
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    72
\makenomenclature
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    73
1589
ffe3cebd5d53 Revision and date on every page.
Florian Pose <fp@igh-essen.com>
parents: 1588
diff changeset
    74
% Revision and date on inner footer
ffe3cebd5d53 Revision and date on every page.
Florian Pose <fp@igh-essen.com>
parents: 1588
diff changeset
    75
\ifoot[\scriptsize\rcsInfoRevision, \rcsInfoDate]
ffe3cebd5d53 Revision and date on every page.
Florian Pose <fp@igh-essen.com>
parents: 1588
diff changeset
    76
    {\scriptsize\rcsInfoRevision, \rcsInfoDate}
ffe3cebd5d53 Revision and date on every page.
Florian Pose <fp@igh-essen.com>
parents: 1588
diff changeset
    77
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    78
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    79
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    80
\begin{document}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    81
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    82
\pagenumbering{roman}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    83
\pagestyle{empty}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    84
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    85
\begin{titlepage}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    86
  \begin{center}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    87
    \rule{\textwidth}{1.5mm}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    88
1917
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
    89
    {\Huge\sf\textbf{IgH \includegraphics[height=2.4ex]{images/ethercat}
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
    90
      Master \masterversion}\\[1ex]
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
    91
      \textbf{Documentation}}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    92
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    93
    \vspace{1ex}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    94
    \rule{\textwidth}{1.5mm}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    95
1204
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
    96
    \vspace{\fill} {\Large Dipl.-Ing. (FH) Florian Pose,
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
    97
    \url{fp@igh-essen.com}\\[1ex] Ingenieurgemeinschaft \IgH}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    98
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    99
    \vspace{\fill}
1588
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
   100
    {\Large Essen, \rcsInfoLongDate\\[1ex]
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
   101
      Revision \rcsInfoRevision}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   102
  \end{center}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   103
\end{titlepage}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   104
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   105
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   106
1589
ffe3cebd5d53 Revision and date on every page.
Florian Pose <fp@igh-essen.com>
parents: 1588
diff changeset
   107
\pagestyle{scrplain}
ffe3cebd5d53 Revision and date on every page.
Florian Pose <fp@igh-essen.com>
parents: 1588
diff changeset
   108
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   109
\tableofcontents
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   110
\listoftables
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   111
\listoffigures
1204
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
   112
%\lstlistoflistings
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   113
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   114
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   115
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   116
\newpage
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   117
\pagestyle{scrheadings}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   118
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   119
\section*{Conventions}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   120
\addcontentsline{toc}{section}{Conventions}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   121
\markleft{Conventions}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   122
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   123
The following typographic conventions are used:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   124
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   125
\begin{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   126
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   127
\item \textit{Italic face} is used for newly introduced terms and file names.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   128
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   129
\item \texttt{Typewriter face} is used for code examples and command line
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   130
output.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   131
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   132
\item \texttt{\textbf{Bold typewriter face}} is used for user input in command
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   133
lines.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   134
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   135
\end{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   136
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   137
Data values and addresses are usually specified as hexadecimal values. These
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   138
are marked in the \textit{C} programming language style with the prefix
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   139
\lstinline+0x+ (example: \lstinline+0x88A4+). Unless otherwise noted, address
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   140
values are specified as byte addresses.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   141
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   142
Function names are always printed with parentheses, but without
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   143
parameters. So, if a function \lstinline+ecrt_request_master()+ has
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   144
empty parentheses, this shall not imply that it has no parameters.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   145
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   146
If shell commands have to be entered, this is marked by a dollar prompt:
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   147
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   148
\begin{lstlisting}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   149
$
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   150
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   151
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   152
Further, if a shell command has to be entered as the superuser, the
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   153
prompt is a mesh:
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   154
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   155
\begin{lstlisting}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   156
#
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   157
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   158
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   159
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   160
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   161
\chapter{The IgH EtherCAT Master}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   162
\label{chapter:master}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   163
\pagenumbering{arabic}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   164
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   165
This chapter covers some general information about the EtherCAT master.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   166
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   167
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   168
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   169
\section{Feature Summary}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   170
\label{sec:summary}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   171
\index{Master!Features}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   172
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   173
The list below gives a short summary of the master features.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   174
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   175
\begin{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   176
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   177
\item Designed as a kernel module for Linux 2.6 / 3.x.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   178
1086
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   179
\item Implemented according to IEC 61158-12 \cite{dlspec} \cite{alspec}.
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   180
1588
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
   181
\item Comes with EtherCAT-capable native drivers for several common Ethernet
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
   182
chips, as well as a generic driver for all chips supported by the Linux
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
   183
kernel.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   184
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   185
  \begin{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   186
1588
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
   187
  \item The native drivers operate the hardware without interrupts.
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
   188
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
   189
  \item Native drivers for additional Ethernet hardware can easily be
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   190
  implemented using the common device interface (see~\autoref{sec:ecdev})
1588
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
   191
  provided by the master module.
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
   192
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
   193
  \item For any other hardware, the generic driver can be used. It uses the
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
   194
  lower layers of the Linux network stack.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   195
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   196
  \end{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   197
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   198
\item The master module supports multiple EtherCAT masters running in
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   199
parallel.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   200
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   201
\item The master code supports any Linux realtime extension through its
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   202
independent architecture.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   203
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   204
  \begin{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   205
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   206
  \item RTAI\nomenclature{RTAI}{Realtime Application Interface} \cite{rtai}
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   207
  (including LXRT via RTDM), ADEOS\nomenclature{ADEOS}{Adaptive Domain
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   208
  Environment for Operating Systems}, RT-Preempt \cite{rt-preempt}, Xenomai
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   209
  (including RTDM), etc.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   210
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   211
  \item It runs well even without realtime extensions.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   212
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   213
  \end{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   214
1204
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
   215
\item Common ``Application Interface'' for applications, that want to use
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   216
EtherCAT functionality (see \autoref{chap:api}).
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   217
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   218
\item \textit{Domains} are introduced, to allow grouping of process
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   219
  data transfers with different slave groups and task periods.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   220
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   221
  \begin{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   222
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   223
  \item Handling of multiple domains with different task periods.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   224
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   225
  \item Automatic calculation of process data mapping, FMMU and sync manager
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   226
  configuration within each domain.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   227
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   228
  \end{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   229
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   230
\item Communication through several finite state machines.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   231
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   232
  \begin{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   233
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   234
  \item Automatic bus scanning after topology changes.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   235
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   236
  \item Bus monitoring during operation.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   237
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   238
  \item Automatic reconfiguration of slaves (for example after power failure)
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   239
  during operation.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   240
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   241
  \end{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   242
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   243
\item Distributed Clocks support (see \autoref{sec:dc}).
1517
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   244
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   245
  \begin{itemize}
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   246
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   247
  \item Configuration of the slave's DC parameters through the application
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   248
  interface.
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   249
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   250
  \item Synchronization (offset and drift compensation) of the distributed
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   251
  slave clocks to the reference clock.
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   252
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   253
  \item Optional synchronization of the reference clock to the master clock or
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   254
  the other way round.
1517
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   255
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   256
  \end{itemize}
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   257
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
   258
\item CANopen over EtherCAT (CoE)
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   259
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   260
  \begin{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   261
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
   262
  \item SDO upload, download and information service.
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
   263
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
   264
  \item Slave configuration via SDOs.
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
   265
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
   266
  \item SDO access from userspace and from the application.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   267
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   268
  \end{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   269
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
   270
\item Ethernet over EtherCAT (EoE)
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   271
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   272
  \begin{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   273
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   274
  \item Transparent use of EoE slaves via virtual network interfaces.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   275
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   276
  \item Natively supports either a switched or a routed EoE network
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   277
  architecture.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   278
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   279
  \end{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   280
1364
471cd0e77b55 Updated features.
Florian Pose <fp@igh-essen.com>
parents: 1327
diff changeset
   281
\item Vendor-specific over EtherCAT (VoE)
471cd0e77b55 Updated features.
Florian Pose <fp@igh-essen.com>
parents: 1327
diff changeset
   282
471cd0e77b55 Updated features.
Florian Pose <fp@igh-essen.com>
parents: 1327
diff changeset
   283
  \begin{itemize}
471cd0e77b55 Updated features.
Florian Pose <fp@igh-essen.com>
parents: 1327
diff changeset
   284
471cd0e77b55 Updated features.
Florian Pose <fp@igh-essen.com>
parents: 1327
diff changeset
   285
  \item Communication with vendor-specific mailbox protocols via the API.
471cd0e77b55 Updated features.
Florian Pose <fp@igh-essen.com>
parents: 1327
diff changeset
   286
471cd0e77b55 Updated features.
Florian Pose <fp@igh-essen.com>
parents: 1327
diff changeset
   287
  \end{itemize}
471cd0e77b55 Updated features.
Florian Pose <fp@igh-essen.com>
parents: 1327
diff changeset
   288
471cd0e77b55 Updated features.
Florian Pose <fp@igh-essen.com>
parents: 1327
diff changeset
   289
\item File Access over EtherCAT (FoE)
471cd0e77b55 Updated features.
Florian Pose <fp@igh-essen.com>
parents: 1327
diff changeset
   290
471cd0e77b55 Updated features.
Florian Pose <fp@igh-essen.com>
parents: 1327
diff changeset
   291
  \begin{itemize}
471cd0e77b55 Updated features.
Florian Pose <fp@igh-essen.com>
parents: 1327
diff changeset
   292
471cd0e77b55 Updated features.
Florian Pose <fp@igh-essen.com>
parents: 1327
diff changeset
   293
  \item Loading and storing files via the command-line tool.
471cd0e77b55 Updated features.
Florian Pose <fp@igh-essen.com>
parents: 1327
diff changeset
   294
471cd0e77b55 Updated features.
Florian Pose <fp@igh-essen.com>
parents: 1327
diff changeset
   295
  \item Updating a slave's firmware can be done easily.
471cd0e77b55 Updated features.
Florian Pose <fp@igh-essen.com>
parents: 1327
diff changeset
   296
471cd0e77b55 Updated features.
Florian Pose <fp@igh-essen.com>
parents: 1327
diff changeset
   297
  \end{itemize}
471cd0e77b55 Updated features.
Florian Pose <fp@igh-essen.com>
parents: 1327
diff changeset
   298
1917
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
   299
\item Servo Profile over EtherCAT (SoE)
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
   300
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
   301
  \begin{itemize}
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
   302
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
   303
  \item Implemented according to IEC 61800-7 \cite{soespec}.
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
   304
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
   305
  \item Storing IDN configurations, that are written to the slave during
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
   306
  startup.
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
   307
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
   308
  \item Accessing IDNs via the command-line tool.
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
   309
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
   310
  \item Accessing IDNs at runtime via the the user-space library.
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
   311
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
   312
  \end{itemize}
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
   313
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   314
\item Userspace command-line-tool ``ethercat'' (see \autoref{sec:tool})
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   315
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   316
  \begin{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   317
1364
471cd0e77b55 Updated features.
Florian Pose <fp@igh-essen.com>
parents: 1327
diff changeset
   318
  \item Detailed information about master, slaves, domains and bus
471cd0e77b55 Updated features.
Florian Pose <fp@igh-essen.com>
parents: 1327
diff changeset
   319
  configuration.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   320
  \item Setting the master's debug level.
1364
471cd0e77b55 Updated features.
Florian Pose <fp@igh-essen.com>
parents: 1327
diff changeset
   321
  \item Reading/Writing alias addresses.
471cd0e77b55 Updated features.
Florian Pose <fp@igh-essen.com>
parents: 1327
diff changeset
   322
  \item Listing slave configurations.
471cd0e77b55 Updated features.
Florian Pose <fp@igh-essen.com>
parents: 1327
diff changeset
   323
  \item Viewing process data.
471cd0e77b55 Updated features.
Florian Pose <fp@igh-essen.com>
parents: 1327
diff changeset
   324
  \item SDO download/upload; listing SDO dictionaries.
471cd0e77b55 Updated features.
Florian Pose <fp@igh-essen.com>
parents: 1327
diff changeset
   325
  \item Loading and storing files via FoE.
1917
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
   326
  \item SoE IDN access.
1364
471cd0e77b55 Updated features.
Florian Pose <fp@igh-essen.com>
parents: 1327
diff changeset
   327
  \item Access to slave registers.
471cd0e77b55 Updated features.
Florian Pose <fp@igh-essen.com>
parents: 1327
diff changeset
   328
  \item Slave SII (EEPROM) access.
471cd0e77b55 Updated features.
Florian Pose <fp@igh-essen.com>
parents: 1327
diff changeset
   329
  \item Controlling application-layer states.
1517
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   330
  \item Generation of slave description XML and C-code from existing slaves.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   331
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   332
  \end{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   333
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   334
\item Seamless system integration though LSB\nomenclature{LSB}{Linux
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   335
    Standard Base} compliance.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   336
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   337
  \begin{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   338
1095
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   339
  \item Master and network device configuration via sysconfig files.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   340
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   341
  \item Init script for master control.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   342
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   343
  \item Service file for systemd.
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   344
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   345
  \end{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   346
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   347
\item Virtual read-only network interface for monitoring and debugging
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   348
  purposes.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   349
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   350
\end{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   351
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   352
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   353
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   354
\section{License}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   355
\label{sec:license}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   356
1275
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
   357
The master code is released under the terms and conditions of the GNU General
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
   358
Public License (GPL \cite{gpl})\index{GPL}, version 2. Other developers, that
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
   359
want to use EtherCAT with Linux systems, are invited to use the master code or
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
   360
even participate on development.
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
   361
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
   362
To allow static linking of userspace application against the master's
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   363
application interface (see \autoref{chap:api}), the userspace library (see
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   364
\autoref{sec:userlib}) is licensed under the terms and conditions of the GNU
1275
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
   365
Lesser General Public License (LGPL \cite{lgpl})\index{LGPL}, version 2.1.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   366
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   367
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   368
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   369
\chapter{Architecture}
1299
dd8e55d97280 Userlib.
Florian Pose <fp@igh-essen.com>
parents: 1298
diff changeset
   370
\label{chap:arch}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   371
\index{Master!Architecture}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   372
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   373
The EtherCAT master is integrated into the Linux kernel. This was an early
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   374
design decision, which has been made for several reasons:
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   375
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   376
\begin{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   377
1306
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   378
\item Kernel code has significantly better realtime characteristics, i.\,e.\
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   379
less latency than userspace code. It was foreseeable, that a fieldbus master
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   380
has a lot of cyclic work to do. Cyclic work is usually triggered by timer
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   381
interrupts inside the kernel. The execution delay of a function that processes
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   382
timer interrupts is less, when it resides in kernelspace, because there is no
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   383
need of time-consuming context switches to a userspace process.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   384
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   385
\item It was also foreseeable, that the master code has to directly
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   386
communicate with the Ethernet hardware. This has to be done in the kernel
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   387
anyway (through network device drivers), which is one more reason for the
1275
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
   388
master code being in kernelspace.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   389
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   390
\end{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   391
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   392
\autoref{fig:arch} gives a general overview of the master architecture.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   393
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   394
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   395
  \centering
1588
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
   396
  \includegraphics[width=\textwidth]{images/architecture}
1291
9ce46c40a023 Userspace applications.
Florian Pose <fp@igh-essen.com>
parents: 1289
diff changeset
   397
  \caption{Master Architecture}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   398
  \label{fig:arch}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   399
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   400
1291
9ce46c40a023 Userspace applications.
Florian Pose <fp@igh-essen.com>
parents: 1289
diff changeset
   401
The components of the master environment are described below:
9ce46c40a023 Userspace applications.
Florian Pose <fp@igh-essen.com>
parents: 1289
diff changeset
   402
9ce46c40a023 Userspace applications.
Florian Pose <fp@igh-essen.com>
parents: 1289
diff changeset
   403
\begin{description}
9ce46c40a023 Userspace applications.
Florian Pose <fp@igh-essen.com>
parents: 1289
diff changeset
   404
9ce46c40a023 Userspace applications.
Florian Pose <fp@igh-essen.com>
parents: 1289
diff changeset
   405
\item[Master Module]\index{Master Module} Kernel module containing one or more
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   406
EtherCAT master instances (see \autoref{sec:mastermod}), the ``Device
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   407
Interface'' (see \autoref{sec:ecdev}) and the ``Application Interface'' (see
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   408
\autoref{chap:api}).
1291
9ce46c40a023 Userspace applications.
Florian Pose <fp@igh-essen.com>
parents: 1289
diff changeset
   409
9ce46c40a023 Userspace applications.
Florian Pose <fp@igh-essen.com>
parents: 1289
diff changeset
   410
\item[Device Modules]\index{Device modules} EtherCAT-capable Ethernet device
9ce46c40a023 Userspace applications.
Florian Pose <fp@igh-essen.com>
parents: 1289
diff changeset
   411
driver modules\index{Device modules}, that offer their devices to the EtherCAT
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   412
master via the device interface (see \autoref{sec:ecdev}). These modified
1291
9ce46c40a023 Userspace applications.
Florian Pose <fp@igh-essen.com>
parents: 1289
diff changeset
   413
network drivers can handle network devices used for EtherCAT operation and
9ce46c40a023 Userspace applications.
Florian Pose <fp@igh-essen.com>
parents: 1289
diff changeset
   414
``normal'' Ethernet devices in parallel. A master can accept a certain device
9ce46c40a023 Userspace applications.
Florian Pose <fp@igh-essen.com>
parents: 1289
diff changeset
   415
and then is able to send and receive EtherCAT frames. Ethernet devices
9ce46c40a023 Userspace applications.
Florian Pose <fp@igh-essen.com>
parents: 1289
diff changeset
   416
declined by the master module are connected to the kernel's network stack as
9ce46c40a023 Userspace applications.
Florian Pose <fp@igh-essen.com>
parents: 1289
diff changeset
   417
usual.
9ce46c40a023 Userspace applications.
Florian Pose <fp@igh-essen.com>
parents: 1289
diff changeset
   418
9ce46c40a023 Userspace applications.
Florian Pose <fp@igh-essen.com>
parents: 1289
diff changeset
   419
\item[Application]\index{Application} A program that uses the EtherCAT master
9ce46c40a023 Userspace applications.
Florian Pose <fp@igh-essen.com>
parents: 1289
diff changeset
   420
(usually for cyclic exchange of process data with EtherCAT slaves). These
9ce46c40a023 Userspace applications.
Florian Pose <fp@igh-essen.com>
parents: 1289
diff changeset
   421
programs are not part of the EtherCAT master code\footnote{Although there are
9ce46c40a023 Userspace applications.
Florian Pose <fp@igh-essen.com>
parents: 1289
diff changeset
   422
some examples provided in the \textit{examples/} directory.}, but have to be
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   423
generated or written by the user. An application can request a master through
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   424
the application interface (see \autoref{chap:api}). If this succeeds, it has
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   425
the control over the master: It can provide a bus configuration and exchange
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   426
process data.  Applications can be kernel modules (that use the kernel
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   427
application interface directly) or userspace programs, that use the
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   428
application interface via the EtherCAT library (see \autoref{sec:userlib}), or
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   429
the RTDM library (see~\autoref{sec:rtdm}).
1291
9ce46c40a023 Userspace applications.
Florian Pose <fp@igh-essen.com>
parents: 1289
diff changeset
   430
9ce46c40a023 Userspace applications.
Florian Pose <fp@igh-essen.com>
parents: 1289
diff changeset
   431
\end{description}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   432
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   433
%------------------------------------------------------------------------------
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   434
1306
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   435
\section{Master Module}
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   436
\label{sec:mastermod}
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   437
\index{Master module}
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   438
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   439
The EtherCAT master kernel module \textit{ec\_master} can contain multiple
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   440
master instances. Each master waits for certain Ethernet device(s) identified
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   441
by its MAC address(es)\index{MAC address}. These addresses have to be
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   442
specified on module loading via the \textit{main\_devices} (and optional:
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   443
\textit{backup\_devices}) module parameter.  The number of master instances to
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   444
initialize is taken from the number of MAC addresses given.
1306
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   445
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   446
The below command loads the master module with a single master instance that
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   447
waits for one Ethernet device with the MAC address
1306
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   448
\lstinline+00:0E:0C:DA:A2:20+. The master will be accessible via index $0$.
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   449
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   450
\begin{lstlisting}
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   451
# `\textbf{modprobe ec\_master main\_devices=00:0E:0C:DA:A2:20}`
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   452
\end{lstlisting}
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   453
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   454
MAC addresses for multiple masters have to be separated by commas:
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   455
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   456
\begin{lstlisting}
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   457
# `\textbf{modprobe ec\_master main\_devices=00:0E:0C:DA:A2:20,00:e0:81:71:d5:1c}`
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   458
\end{lstlisting}
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   459
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   460
The two masters can be addressed by their indices 0 and 1 respectively (see
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   461
\autoref{fig:masters}). The master index is needed for the
1306
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   462
\lstinline+ecrt_master_request()+ function of the application interface (see
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   463
\autoref{chap:api}) and the \lstinline+--master+ option of the
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   464
\textit{ethercat} command-line tool (see \autoref{sec:tool}), which defaults
1306
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   465
to $0$.
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   466
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   467
\begin{figure}[htbp]
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   468
  \centering
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   469
  \includegraphics[width=.5\textwidth]{images/masters}
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   470
  \caption{Multiple masters in one module}
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   471
  \label{fig:masters}
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   472
\end{figure}
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   473
1399
f79d4bb5b23a Added debug_level module parameter. debug_level is now unsigned int.
Florian Pose <fp@igh-essen.com>
parents: 1364
diff changeset
   474
\paragraph{Debug Level} The master module also has a parameter
f79d4bb5b23a Added debug_level module parameter. debug_level is now unsigned int.
Florian Pose <fp@igh-essen.com>
parents: 1364
diff changeset
   475
\textit{debug\_level} to set the initial debug level for all masters (see
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   476
also~\autoref{sec:ethercat-debug}).
1399
f79d4bb5b23a Added debug_level module parameter. debug_level is now unsigned int.
Florian Pose <fp@igh-essen.com>
parents: 1364
diff changeset
   477
1306
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   478
\paragraph{Init Script}
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   479
\index{Init script}
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   480
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   481
In most cases it is not necessary to load the master module and the Ethernet
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   482
driver modules manually. There is an init script available, so the master can
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   483
be started as a service (see \autoref{sec:system}). For systems that are
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   484
managed by systemd \cite{systemd}, there is also a service file available.
1306
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   485
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   486
\paragraph{Syslog}
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   487
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   488
The master module outputs information about its state and events to the kernel
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   489
ring buffer. These also end up in the system logs. The above module loading
1306
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   490
command should result in the messages below:
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   491
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   492
\begin{lstlisting}
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   493
# `\textbf{dmesg | tail -2}`
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   494
EtherCAT: Master driver `\masterversion`
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   495
EtherCAT: 2 masters waiting for devices.
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   496
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   497
# `\textbf{tail -2 /var/log/messages}`
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   498
Jul  4 10:22:45 ethercat kernel: EtherCAT: Master driver `\masterversion`
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   499
Jul  4 10:22:45 ethercat kernel: EtherCAT: 2 masters waiting
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   500
                                 for devices.
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   501
\end{lstlisting}
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   502
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   503
Master output is prefixed with \lstinline+EtherCAT+ which makes searching the
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   504
logs easier.
1306
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   505
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   506
%------------------------------------------------------------------------------
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   507
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   508
\section{Master Phases}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   509
\index{Master phases}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   510
1306
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   511
Every EtherCAT master provided by the master module (see
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   512
\autoref{sec:mastermod}) runs through several phases (see
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   513
\autoref{fig:phases}):
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   514
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   515
\begin{figure}[htbp]
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   516
  \centering
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   517
  \includegraphics[width=.9\textwidth]{images/phases}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   518
  \caption{Master phases and transitions}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   519
  \label{fig:phases}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   520
\end{figure}
1291
9ce46c40a023 Userspace applications.
Florian Pose <fp@igh-essen.com>
parents: 1289
diff changeset
   521
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   522
\begin{description}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   523
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   524
\item[Orphaned phase]\index{Orphaned phase} This mode takes effect, when the
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   525
master still waits for its Ethernet device(s) to connect. No bus communication
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   526
is possible until then.
1086
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   527
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   528
\item[Idle phase]\index{Idle phase} takes effect when the master has accepted
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   529
all required Ethernet devices, but is not requested by any application yet.
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   530
The master runs its state machine (see \autoref{sec:fsm-master}), that
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   531
automatically scans the bus for slaves and executes pending operations from
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   532
the userspace interface (for example SDO access). The command-line tool can be
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   533
used to access the bus, but there is no process data exchange because of the
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   534
missing bus configuration.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   535
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   536
\item[Operation phase]\index{Operation phase} The master is requested by an
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   537
application that can provide a bus configuration and exchange process data.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   538
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   539
\end{description}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   540
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   541
%------------------------------------------------------------------------------
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   542
1293
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   543
\section{Process Data}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   544
\label{sec:processdata}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   545
1293
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   546
This section shall introduce a few terms and ideas how the master handles
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   547
process data.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   548
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   549
\paragraph{Process Data Image}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   550
\index{Process data}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   551
1293
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   552
Slaves offer their inputs and outputs by presenting the master so-called
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
   553
``Process Data Objects'' (PDOs\index{PDO}). The available PDOs can be either
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   554
determined by reading out the slave's TxPDO and RxPDO SII categories from the
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
   555
E$^2$PROM (in case of fixed PDOs) or by reading out the appropriate CoE
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   556
objects (see \autoref{sec:coe}), if available.  The application can register
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
   557
the PDOs' entries for exchange during cyclic operation. The sum of all
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
   558
registered PDO entries defines the ``process data image'', which is exchanged
1293
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   559
via datagrams with ``logical'' memory access (like LWR, LRD or LRW) introduced
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   560
in~\cite[sec.~5.4]{dlspec}.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   561
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   562
\paragraph{Process Data Domains}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   563
\index{Domain}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   564
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   565
The process data image can be easily managed by creating so-called
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
   566
``domains'', which allow grouped PDO exchange. They also take care of managing
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
   567
the datagram structures needed to exchange the PDOs. Domains are mandatory for
1293
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   568
process data exchange, so there has to be at least one. They were introduced
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   569
for the following reasons:
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   570
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   571
\begin{itemize}
1293
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   572
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   573
\item The maximum size of a datagram is limited due to the limited size of an
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   574
Ethernet frame: The maximum data size is the Ethernet data field size minus
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   575
the EtherCAT frame header, EtherCAT datagram header and EtherCAT datagram
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   576
footer: $1500 - 2 - 12 - 2 = 1484$ octets. If the size of the process data
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   577
image exceeds this limit, multiple frames have to be sent, and the image has
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   578
to be partitioned for the use of multiple datagrams. A domain manages this
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   579
automatically.
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   580
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
   581
\item Not every PDO has to be exchanged with the same frequency: The values of
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
   582
PDOs can vary slowly over time (for example temperature values), so exchanging
1293
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   583
them with a high frequency would just waste bus bandwidth. For this reason,
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
   584
multiple domains can be created, to group different PDOs and so allow separate
1293
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   585
exchange.
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   586
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   587
\end{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   588
1293
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   589
There is no upper limit for the number of domains, but each domain occupies
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   590
one FMMU in each slave involved, so the maximum number of domains is de facto
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   591
limited by the slaves.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   592
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   593
\paragraph{FMMU Configuration}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   594
\index{FMMU!Configuration}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   595
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
   596
An application can register PDO entries for exchange. Every PDO entry and its
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
   597
parent PDO is part of a memory area in the slave's physical memory, that is
1293
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   598
protected by a sync manager \cite[sec.~6.7]{dlspec} for synchronized access.
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   599
In order to make a sync manager react on a datagram accessing its memory, it
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   600
is necessary to access the last byte covered by the sync manager. Otherwise
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   601
the sync manager will not react on the datagram and no data will be exchanged.
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   602
That is why the whole synchronized memory area has to be included into the
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
   603
process data image: For example, if a certain PDO entry of a slave is
1293
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   604
registered for exchange with a certain domain, one FMMU will be configured to
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
   605
map the complete sync-manager-protected memory, the PDO entry resides in. If a
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
   606
second PDO entry of the same slave is registered for process data exchange
1293
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   607
within the same domain, and it resides in the same sync-manager-protected
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   608
memory as the first one, the FMMU configuration is not altered, because the
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   609
desired memory is already part of the domain's process data image. If the
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
   610
second PDO entry would belong to another sync-manager-protected area, this
1293
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   611
complete area would also be included into the domains process data image.
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   612
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   613
\autoref{fig:fmmus} gives an overview, how FMMUs are configured to map
1293
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   614
physical memory to logical process data images.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   615
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   616
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   617
  \centering
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   618
  \includegraphics[width=\textwidth]{images/fmmus}
1293
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   619
  \caption{FMMU Configuration}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   620
  \label{fig:fmmus}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   621
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   622
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   623
%------------------------------------------------------------------------------
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   624
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   625
\chapter{Application Interface}
1289
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
   626
\label{chap:api}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   627
\index{Application interface}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   628
1297
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
   629
% TODO
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
   630
%
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
   631
% Interface version
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
   632
% Master Requesting and Releasing
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
   633
% Master Locking
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
   634
% Configuring PDO assignment and mapping
1297
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
   635
% Domains (memory)
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
   636
% PDO entry registration
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
   637
% SDO configuration
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
   638
% SDO access
1917
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
   639
% IDN configurations
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
   640
% IDN access
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   641
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   642
The application interface provides functions and data structures for
1292
ea1bcfb8d631 Avouded 'you'.
Florian Pose <fp@igh-essen.com>
parents: 1291
diff changeset
   643
applications to access an EtherCAT master. The complete documentation of the
ea1bcfb8d631 Avouded 'you'.
Florian Pose <fp@igh-essen.com>
parents: 1291
diff changeset
   644
interface is included as Doxygen~\cite{doxygen} comments in the header file
ea1bcfb8d631 Avouded 'you'.
Florian Pose <fp@igh-essen.com>
parents: 1291
diff changeset
   645
\textit{include/ecrt.h}. It can either be read directly from the file
1293
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   646
comments, or as a more comfortable HTML documentation. The HTML generation is
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   647
described in \autoref{sec:gendoc}.
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   648
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   649
The following sections cover a general description of the application
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   650
interface.
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   651
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   652
Every application should use the master in two steps:
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   653
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   654
\begin{description}
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   655
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   656
\item[Configuration] The master is requested and the configuration is applied.
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
   657
For example, domains are created, slaves are configured and PDO entries are
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   658
registered (see \autoref{sec:masterconfig}).
1293
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   659
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   660
\item[Operation] Cyclic code is run and process data are exchanged (see
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   661
\autoref{sec:cyclic}).
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   662
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   663
\end{description}
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   664
1293
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   665
\paragraph{Example Applications}\index{Example Applications} There are a few
1204
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
   666
example applications in the \textit{examples/} subdirectory of the master
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
   667
code. They are documented in the source code.
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
   668
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   669
%------------------------------------------------------------------------------
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   670
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   671
\section{Master Configuration}
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   672
\label{sec:masterconfig}
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   673
1293
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   674
The bus configuration is supplied via the application interface.
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   675
\autoref{fig:app-config} gives an overview of the objects, that can be
1293
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   676
configured by the application.
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   677
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   678
\begin{figure}[htbp]
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   679
  \centering
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   680
  \includegraphics[width=.8\textwidth]{images/app-config}
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
   681
  \caption{Master Configuration}
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   682
  \label{fig:app-config}
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   683
\end{figure}
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   684
1293
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   685
\subsection{Slave Configuration}
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   686
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   687
The application has to tell the master about the expected bus topology. This
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   688
can be done by creating ``slave configurations''. A slave configuration can be
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   689
seen as an expected slave. When a slave configuration is created, the
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   690
application provides the bus position (see below), vendor id and product code.
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   691
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   692
When the bus configuration is applied, the master checks, if there is a slave
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   693
with the given vendor id and product code at the given position. If this is
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   694
the case, the slave configuration is ``attached'' to the real slave on the bus
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   695
and the slave is configured according to the settings provided by the
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   696
application. The state of a slave configuration can either be queried via the
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   697
application interface or via the command-line tool (see
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   698
\autoref{sec:ethercat-config}).
1293
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   699
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   700
\paragraph{Slave Position} The slave position has to be specified as a tuple
1306
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   701
of ``alias'' and ``position''. This allows addressing slaves either via an
1293
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   702
absolute bus position, or a stored identifier called ``alias'', or a mixture
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   703
of both. The alias is a 16-bit value stored in the slave's E$^2$PROM. It can
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   704
be modified via the command-line tool (see \autoref{sec:ethercat-alias}).
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   705
\autoref{tab:slaveposition} shows, how the values are interpreted.
1293
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   706
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   707
\begin{table}[htbp]
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   708
  \centering
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   709
  \caption{Specifying a Slave Position}
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   710
  \label{tab:slaveposition}
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   711
  \vspace{2mm}
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   712
  \begin{tabular}{c|c|p{70mm}}
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   713
    Alias & Position & Interpretation\\
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   714
    \hline
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   715
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   716
    \lstinline+0+ & \lstinline+0+ -- \lstinline+65535+ &
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   717
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   718
    Position addressing. The position parameter is interpreted as the absolute
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   719
    ring position in the bus.\\ \hline
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   720
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   721
    \lstinline+1+ -- \lstinline+65535+ & \lstinline+0+ -- \lstinline+65535+ &
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   722
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   723
    Alias addressing. The position parameter is interpreted as relative
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   724
    position after the first slave with the given alias address. \\ \hline
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   725
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   726
  \end{tabular}
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   727
\end{table}
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   728
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   729
\autoref{fig:attach} shows an example of how slave configurations are
1293
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   730
attached. Some of the configurations were attached, while others remain
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   731
detached. The below lists gives the reasons beginning with the top slave
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   732
configuration.
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   733
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   734
\begin{figure}[htbp]
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   735
  \centering
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   736
  \includegraphics[width=.7\textwidth]{images/attach}
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   737
  \caption{Slave Configuration Attachment}
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   738
  \label{fig:attach}
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   739
\end{figure}
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   740
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   741
\begin{enumerate}
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   742
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   743
\item A zero alias means to use simple position addressing. Slave 1 exists and
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   744
vendor id and product code match the expected values.
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   745
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   746
\item Although the slave with position 0 is found, the product code does not
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   747
match, so the configuration is not attached.
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   748
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   749
\item The alias is non-zero, so alias addressing is used. Slave 2 is the first
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   750
slave with alias \lstinline+0x2000+. Because the position value is zero, the
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   751
same slave is used.
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   752
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   753
\item There is no slave with the given alias, so the configuration can not be
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   754
attached.
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   755
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   756
\item Slave 2 is again the first slave with the alias \lstinline+0x2000+, but
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   757
position is now 1, so slave 3 is attached.
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   758
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   759
\end{enumerate}
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   760
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   761
If the master sources are configured with \lstinline+--enable-wildcards+, then
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   762
\lstinline+0xffffffff+ matches every vendor ID and/or product code.
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   763
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   764
%------------------------------------------------------------------------------
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   765
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   766
\section{Cyclic Operation}
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   767
\label{sec:cyclic}
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   768
1293
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   769
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   770
To enter cyclic operation mode, the master has to be ``activated'' to
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   771
calculate the process data image and apply the bus configuration for the first
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   772
time. After activation, the application is in charge to send and receive
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   773
frames. The configuration can not be changed after activation.
1293
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   774
1297
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
   775
% TODO
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
   776
%
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
   777
% PDO endianess
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
   778
% Datagram injection
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   779
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   780
%------------------------------------------------------------------------------
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   781
1298
de91d633ff6c VoE handlers.
Florian Pose <fp@igh-essen.com>
parents: 1297
diff changeset
   782
\section{VoE Handlers}
de91d633ff6c VoE handlers.
Florian Pose <fp@igh-essen.com>
parents: 1297
diff changeset
   783
\label{sec:api-voe}
de91d633ff6c VoE handlers.
Florian Pose <fp@igh-essen.com>
parents: 1297
diff changeset
   784
de91d633ff6c VoE handlers.
Florian Pose <fp@igh-essen.com>
parents: 1297
diff changeset
   785
During the configuration phase, the application can create handlers for the
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   786
VoE mailbox protocol described in \autoref{sec:voe}. One VoE handler always
1298
de91d633ff6c VoE handlers.
Florian Pose <fp@igh-essen.com>
parents: 1297
diff changeset
   787
belongs to a certain slave configuration, so the creation function is a method
de91d633ff6c VoE handlers.
Florian Pose <fp@igh-essen.com>
parents: 1297
diff changeset
   788
of the slave configuration.
de91d633ff6c VoE handlers.
Florian Pose <fp@igh-essen.com>
parents: 1297
diff changeset
   789
de91d633ff6c VoE handlers.
Florian Pose <fp@igh-essen.com>
parents: 1297
diff changeset
   790
A VoE handler manages the VoE data and the datagram used to transmit and
de91d633ff6c VoE handlers.
Florian Pose <fp@igh-essen.com>
parents: 1297
diff changeset
   791
receive VoE messages. Is contains the state machine necessary to transfer VoE
de91d633ff6c VoE handlers.
Florian Pose <fp@igh-essen.com>
parents: 1297
diff changeset
   792
messages.
de91d633ff6c VoE handlers.
Florian Pose <fp@igh-essen.com>
parents: 1297
diff changeset
   793
de91d633ff6c VoE handlers.
Florian Pose <fp@igh-essen.com>
parents: 1297
diff changeset
   794
The VoE state machine can only process one operation at a time. As a result,
de91d633ff6c VoE handlers.
Florian Pose <fp@igh-essen.com>
parents: 1297
diff changeset
   795
either a read or write operation may be issued at a time\footnote{If
de91d633ff6c VoE handlers.
Florian Pose <fp@igh-essen.com>
parents: 1297
diff changeset
   796
simultaneous sending and receiving is desired, two VoE handlers can be created
de91d633ff6c VoE handlers.
Florian Pose <fp@igh-essen.com>
parents: 1297
diff changeset
   797
for the slave configuration.}. After the operation is initiated, the handler
de91d633ff6c VoE handlers.
Florian Pose <fp@igh-essen.com>
parents: 1297
diff changeset
   798
must be executed cyclically until it is finished. After that, the results of
de91d633ff6c VoE handlers.
Florian Pose <fp@igh-essen.com>
parents: 1297
diff changeset
   799
the operation can be retrieved.
de91d633ff6c VoE handlers.
Florian Pose <fp@igh-essen.com>
parents: 1297
diff changeset
   800
de91d633ff6c VoE handlers.
Florian Pose <fp@igh-essen.com>
parents: 1297
diff changeset
   801
A VoE handler has an own datagram structure, that is marked for exchange after
de91d633ff6c VoE handlers.
Florian Pose <fp@igh-essen.com>
parents: 1297
diff changeset
   802
each execution step. So the application can decide, how many handlers to
de91d633ff6c VoE handlers.
Florian Pose <fp@igh-essen.com>
parents: 1297
diff changeset
   803
execute before sending the corresponding EtherCAT frame(s).
de91d633ff6c VoE handlers.
Florian Pose <fp@igh-essen.com>
parents: 1297
diff changeset
   804
de91d633ff6c VoE handlers.
Florian Pose <fp@igh-essen.com>
parents: 1297
diff changeset
   805
For more information about the use of VoE handlers see the documentation of
de91d633ff6c VoE handlers.
Florian Pose <fp@igh-essen.com>
parents: 1297
diff changeset
   806
the application interface functions and the example applications provided in
de91d633ff6c VoE handlers.
Florian Pose <fp@igh-essen.com>
parents: 1297
diff changeset
   807
the \textit{examples/} directory.
de91d633ff6c VoE handlers.
Florian Pose <fp@igh-essen.com>
parents: 1297
diff changeset
   808
de91d633ff6c VoE handlers.
Florian Pose <fp@igh-essen.com>
parents: 1297
diff changeset
   809
%------------------------------------------------------------------------------
de91d633ff6c VoE handlers.
Florian Pose <fp@igh-essen.com>
parents: 1297
diff changeset
   810
1294
b08eb1ffa6dd Fixed missing paren.
Florian Pose <fp@igh-essen.com>
parents: 1293
diff changeset
   811
\section{Concurrent Master Access}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   812
\label{sec:concurr}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   813
\index{Concurrency}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   814
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   815
In some cases, one master is used by several instances, for example when an
1289
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
   816
application does cyclic process data exchange, and there are EoE-capable
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
   817
slaves that require to exchange Ethernet data with the kernel (see
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   818
\autoref{sec:eoe}). For this reason, the master is a shared resource, and
1289
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
   819
access to it has to be sequentialized. This is usually done by locking with
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   820
semaphores, or other methods to protect critical sections.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   821
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   822
The master itself can not provide locking mechanisms, because it has no chance
1291
9ce46c40a023 Userspace applications.
Florian Pose <fp@igh-essen.com>
parents: 1289
diff changeset
   823
to know the appropriate kind of lock. For example if the application is in
9ce46c40a023 Userspace applications.
Florian Pose <fp@igh-essen.com>
parents: 1289
diff changeset
   824
kernelspace and uses RTAI functionality, ordinary kernel semaphores would not
9ce46c40a023 Userspace applications.
Florian Pose <fp@igh-essen.com>
parents: 1289
diff changeset
   825
be sufficient. For that, an important design decision was made: The
9ce46c40a023 Userspace applications.
Florian Pose <fp@igh-essen.com>
parents: 1289
diff changeset
   826
application that reserved a master must have the total control, therefore it
9ce46c40a023 Userspace applications.
Florian Pose <fp@igh-essen.com>
parents: 1289
diff changeset
   827
has to take responsibility for providing the appropriate locking mechanisms.
1517
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   828
If another instance wants to access the master, it has to request the bus
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   829
access via callbacks, that have to be provided by the application. Moreover
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   830
the application can deny access to the master if it considers it to be awkward
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   831
at the moment.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   832
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   833
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   834
  \centering
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   835
  \includegraphics[width=.6\textwidth]{images/master-locks}
1295
4627823c2e8f Capital.
Florian Pose <fp@igh-essen.com>
parents: 1294
diff changeset
   836
  \caption{Concurrent Master Access}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   837
  \label{fig:locks}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   838
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   839
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   840
\autoref{fig:locks} exemplary shows, how two processes share one master:
1204
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
   841
The application's cyclic task uses the master for process data exchange, while
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
   842
the master-internal EoE process uses it to communicate with EoE-capable
1517
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   843
slaves. Both have to access the bus from time to time, but the EoE process
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   844
does this by ``asking'' the application to do the bus access for it. In this
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   845
way, the application can use the appropriate locking mechanism to avoid
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   846
accessing the bus at the same time. See the application interface
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   847
documentation (\autoref{chap:api}) for how to use these callbacks.
1517
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   848
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   849
%------------------------------------------------------------------------------
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   850
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   851
\section{Distributed Clocks}
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   852
\label{sec:dc}
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   853
\index{Distributed Clocks}
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   854
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   855
From version 1.5, the master supports EtherCAT's ``Distributed Clocks''
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   856
feature. It is possible to synchronize the slave clocks on the bus to the
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   857
``reference clock'' (which is the local clock of the first slave with DC
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   858
support) and to synchronize the reference clock to the ``master clock'' (which
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   859
is the local clock of the master). All other clocks on the bus (after the
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   860
reference clock) are considered as ``slave clocks'' (see \autoref{fig:dc}).
1517
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   861
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   862
\begin{figure}[htbp]
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   863
  \centering
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   864
  \includegraphics[width=.8\textwidth]{images/dc}
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   865
  \caption{Distributed Clocks}
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   866
  \label{fig:dc}
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   867
\end{figure}
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   868
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   869
\paragraph{Local Clocks} Any EtherCAT slave that supports DC has a local clock
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   870
register with nanosecond resolution. If the slave is powered, the clock starts
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   871
from zero, meaning that when slaves are powered on at different times, their
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   872
clocks will have different values. These ``offsets'' have to be compensated by
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   873
the distributed clocks mechanism. On the other hand, the clocks do not run
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   874
exactly with the same speed, since the used quarts units have a natural
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   875
frequency deviation. This deviation is usually very small, but over longer
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   876
periods, the error would accumulate and the difference between local clocks
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   877
would grow. This clock ``drift'' has also to be compensated by the DC
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   878
mechanism.
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   879
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   880
\paragraph{Application Time} The common time base for the bus has to be
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   881
provided by the application. This application time $t_\text{app}$ is used
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   882
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   883
\begin{enumerate}
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   884
\item to configure the slaves' clock offsets (see below),
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   885
\item to program the slave's start times for sync pulse generation (see
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   886
below).
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   887
\item to synchronize the reference clock to the master clock (optional).
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   888
\end{enumerate}
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   889
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   890
\paragraph{Offset Compensation} For the offset compensation, each slave
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   891
provides a ``System Time Offset'' register $t_\text{off}$, that is added to
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   892
the internal clock value $t_\text{int}$ to get the ``System Time''
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   893
$t_\text{sys}$:
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   894
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   895
\begin{eqnarray}
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   896
t_\text{sys} & = & t_\text{int} + t_\text{off} \\
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   897
\Rightarrow t_\text{int} & = & t_\text{sys} - t_\text{off} \nonumber
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   898
\end{eqnarray}
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   899
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   900
The master reads the values of both registers to calculate a new system time
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   901
offset in a way, that the resulting system time shall match the master's
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   902
application time $t_\text{app}$:
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   903
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   904
\begin{eqnarray}
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   905
t_\text{sys} & \stackrel{!}{=} & t_\text{app} \\
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   906
\Rightarrow t_\text{int} + t_\text{off} & \stackrel{!}{=} & t_\text{app} \nonumber \\
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   907
\Rightarrow t_\text{off} & = & t_\text{app} - t_\text{int} \nonumber \\
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   908
\Rightarrow t_\text{off} & = & t_\text{app} - (t_\text{sys} - t_\text{off}) \nonumber \\
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   909
\Rightarrow t_\text{off} & = & t_\text{app} - t_\text{sys} + t_\text{off}
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   910
\end{eqnarray}
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   911
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   912
The small time offset error resulting from the different times of reading and
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   913
writing the registers will be compensated by the drift compensation.
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   914
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   915
\paragraph{Drift Compensation} The drift compensation is possible due to a
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   916
special mechanism in each DC-capable slave: A write operation to the ``System
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   917
time'' register will cause the internal time control loop to compare the
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   918
written time (minus the programmed transmission delay, see below) to the
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   919
current system time. The calculated time error will be used as an input to the
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   920
time controller, that will tune the local clock speed to be a little faster or
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   921
slower\footnote{The local slave clock will be incremented either with
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   922
\unit{9}{\nano\second}, \unit{10}{\nano\second} or \unit{11}{\nano\second}
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   923
every \unit{10}{\nano\second}.}, according to the sign of the error.
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   924
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   925
\paragraph{Transmission Delays} The Ethernet frame needs a small amount of
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   926
time to get from slave to slave. The resulting transmission delay times
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   927
accumulate on the bus and can reach microsecond magnitude and thus have to be
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   928
considered during the drift compensation. EtherCAT slaves supporting DC
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   929
provide a mechanism to measure the transmission delays: For each of the four
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   930
slave ports there is a receive time register. A write operation to the receive
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   931
time register of port 0 starts the measuring and the current system time is
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   932
latched and stored in a receive time register once the frame is received on
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   933
the corresponding port. The master can read out the relative receive times,
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   934
then calculate time delays between the slaves (using its knowledge of the bus
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   935
topology), and finally calculate the time delays from the reference clock to
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   936
each slave. These values are programmed into the slaves' transmission delay
2421
bc2d4bf9cbe5 Removed trailing spaces.
Florian Pose <fp@igh-essen.com>
parents: 2419
diff changeset
   937
registers. In this way, the drift compensation can reach nanosecond synchrony.
1517
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   938
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   939
\paragraph{Checking Synchrony} DC-capable slaves provide the 32-bit ``System
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   940
time difference'' register at address \lstinline+0x092c+, where the system
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   941
time difference of the last drift compensation is stored in nanosecond
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   942
resolution and in sign-and-magnitude coding\footnote{This allows
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   943
broadcast-reading all system time difference registers on the bus to get an
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   944
upper approximation}. To check for bus synchrony, the system time difference
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   945
registers can also be cyclically read via the command-line-tool (see
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   946
\autoref{sec:regaccess}):
1517
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   947
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   948
\begin{lstlisting}
1917
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
   949
$ `\textbf{watch -n0 "ethercat reg\_read -p4 -tsm32 0x92c"}`
1517
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   950
\end{lstlisting}
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   951
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   952
\paragraph{Sync Signals} Synchronous clocks are only the prerequisite for
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   953
synchronous events on the bus. Each slave with DC support provides two ``sync
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   954
signals'', that can be programmed to create events, that will for example
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   955
cause the slave application to latch its inputs on a certain time. A sync
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   956
event can either be generated once or cyclically, depending on what makes
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   957
sense for the slave application. Programming the sync signals is a matter of
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   958
setting the so-called ``AssignActivate'' word and the sync signals' cycle- and
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   959
shift times. The AssignActivate word is slave-specific and has to be taken
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   960
from the XML slave description (\lstinline+Device+ $\rightarrow$
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   961
\lstinline+Dc+), where also typical sync signal configurations ``OpModes'' can
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   962
be found.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   963
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   964
%------------------------------------------------------------------------------
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   965
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   966
\chapter{Ethernet Devices}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   967
\label{sec:devices}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   968
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
   969
The EtherCAT protocol is based on the Ethernet standard, so a master relies on
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
   970
standard Ethernet hardware to communicate with the bus.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   971
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   972
The term \textit{device} is used as a synonym for Ethernet network interface
1588
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
   973
hardware.
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
   974
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
   975
\paragraph{Native Ethernet Device Drivers} There are native device driver
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   976
modules (see \autoref{sec:native-drivers}) that handle Ethernet hardware,
1588
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
   977
which a master can use to connect to an EtherCAT bus. They offer their
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
   978
Ethernet hardware to the master module via the device interface (see
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   979
\autoref{sec:ecdev}) and must be capable to prepare Ethernet devices either
1588
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
   980
for EtherCAT (realtime) operation or for ``normal'' operation using the
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
   981
kernel's network stack. The advantage of this approach is that the master can
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
   982
operate nearly directly on the hardware, which allows a high performance. The
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
   983
disadvantage is, that there has to be an EtherCAT-capable version of the
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
   984
original Ethernet driver.
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
   985
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
   986
\paragraph{Generic Ethernet Device Driver} From master version 1.5, there is a
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
   987
generic Ethernet device driver module (see \autoref{sec:generic-driver}),
1588
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
   988
that uses the lower layers of the network stack to connect to the hardware.
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
   989
The advantage is, that arbitrary Ethernet hardware can be used for EtherCAT
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
   990
operation, independently of the actual hardware driver (so all Linux Ethernet
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
   991
drivers are supported without modifications). The disadvantage is, that this
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
   992
approach does not support realtime extensions like RTAI, because the Linux
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
   993
network stack is addressed. Moreover the performance is a little worse than
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
   994
the native approach, because the Ethernet frame data have to traverse the
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
   995
network stack.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   996
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   997
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   998
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   999
\section{Network Driver Basics}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1000
\label{sec:networkdrivers}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1001
\index{Network drivers}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1002
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1003
EtherCAT relies on Ethernet hardware and the master needs a physical
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1004
Ethernet device to communicate with the bus. Therefore it is necessary
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1005
to understand how Linux handles network devices and their drivers,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1006
respectively.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1007
1588
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1008
\paragraph{Tasks of a Network Driver} Network device drivers usually handle
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1009
the lower two layers of the OSI model, that is the physical layer and the
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1010
data-link layer. A network device itself natively handles the physical layer
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1011
issues: It represents the hardware to connect to the medium and to send and
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1012
receive data in the way, the physical layer protocol describes. The network
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1013
device driver is responsible for getting data from the kernel's networking
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1014
stack and forwarding it to the hardware, that does the physical transmission.
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1015
If data is received by the hardware respectively, the driver is notified
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1016
(usually by means of an interrupt) and has to read the data from the hardware
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1017
memory and forward it to the network stack. There are a few more tasks, a
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1018
network device driver has to handle, including queue control, statistics and
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1019
device dependent features.
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1020
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1021
\paragraph{Driver Startup} Usually, a driver searches for compatible devices
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1022
on module loading.  For PCI drivers, this is done by scanning the PCI bus and
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1023
checking for known device IDs. If a device is found, data structures are
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1024
allocated and the device is taken into operation.
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1025
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1026
\paragraph{Interrupt Operation}\index{Interrupt} A network device usually
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1027
provides a hardware interrupt that is used to notify the driver of received
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1028
frames and success of transmission, or errors, respectively. The driver has to
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1029
register an interrupt service routine
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1030
(ISR\index{ISR}\nomenclature{ISR}{Interrupt Service Routine}), that is
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1031
executed each time, the hardware signals such an event. If the interrupt was
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1032
thrown by the own device (multiple devices can share one hardware interrupt),
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1033
the reason for the interrupt has to be determined by reading the device's
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1034
interrupt register. For example, if the flag for received frames is set, frame
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1035
data has to be copied from hardware to kernel memory and passed to the network
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1036
stack.
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1037
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1038
\paragraph{The \lstinline+net_device+ Structure}\index{net\_device} The driver
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1039
registers a \lstinline+net_device+ structure for each device to communicate
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1040
with the network stack and to create a ``network interface''. In case of an
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1041
Ethernet driver, this interface appears as \textit{ethX}, where X is a number
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1042
assigned by the kernel on registration. The \lstinline+net_device+ structure
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1043
receives events (either from userspace or from the network stack) via several
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1044
callbacks, which have to be set before registration. Not every callback is
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1045
mandatory, but for reasonable operation the ones below are needed in any case:
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1046
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1047
\newsavebox\boxopen
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1048
\sbox\boxopen{\lstinline+open()+}
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1049
\newsavebox\boxstop
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1050
\sbox\boxstop{\lstinline+stop()+}
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1051
\newsavebox\boxxmit
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1052
\sbox\boxxmit{\lstinline+hard_start_xmit()+}
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1053
\newsavebox\boxstats
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1054
\sbox\boxstats{\lstinline+get_stats()+}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1055
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1056
\begin{description}
1095
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  1057
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1058
\item[\usebox\boxopen] This function is called when network communication has
1275
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  1059
to be started, for example after a command \lstinline+ip link set ethX up+
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  1060
from userspace. Frame reception has to be enabled by the driver.
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1061
1297
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
  1062
\item[\usebox\boxstop] The purpose of this callback is to ``close'' the
1306
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
  1063
device, i.\,e.\ make the hardware stop receiving frames.
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1064
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1065
\item[\usebox\boxxmit] This function is called for each frame that has to be
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1066
transmitted. The network stack passes the frame as a pointer to an
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1067
\lstinline+sk_buff+ structure (``socket buffer''\index{Socket buffer}, see
1095
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  1068
below), which has to be freed after sending.
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  1069
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1070
\item[\usebox\boxstats] This call has to return a pointer to the device's
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1071
\lstinline+net_device_stats+ structure, which permanently has to be filled with
1095
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  1072
frame statistics. This means, that every time a frame is received, sent, or an
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  1073
error happened, the appropriate counter in this structure has to be increased.
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  1074
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  1075
\end{description}
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  1076
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  1077
The actual registration is done with the \lstinline+register_netdev()+ call,
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  1078
unregistering is done with \lstinline+unregister_netdev()+.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1079
1588
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1080
\paragraph{The \lstinline+netif+ Interface}\index{netif} All other
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1081
communication in the direction interface $\to$ network stack is done via the
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1082
\lstinline+netif_*()+ calls. For example, on successful device opening, the
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1083
network stack has to be notified, that it can now pass frames to the
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1084
interface. This is done by calling \lstinline+netif_start_queue()+. After this
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1085
call, the \lstinline+hard_start_xmit()+ callback can be called by the network
1588
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1086
stack. Furthermore a network driver usually manages a frame transmission
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1087
queue.  If this gets filled up, the network stack has to be told to stop
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1088
passing further frames for a while. This happens with a call to
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1089
\lstinline+netif_stop_queue()+. If some frames have been sent, and there is
1095
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  1090
enough space again to queue new frames, this can be notified with
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  1091
\lstinline+netif_wake_queue()+. Another important call is
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  1092
\lstinline+netif_receive_skb()+\footnote{This function is part of the NAPI
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  1093
(``New API''), that replaces the kernel 2.4 technique for interfacing to the
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  1094
network stack (with \lstinline+netif_rx()+). NAPI is a technique to improve
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  1095
network performance on Linux. Read more in
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  1096
\url{http://www.cyberus.ca/~hadi/usenix-paper.tgz}.}: It passes a frame to the
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  1097
network stack, that was just received by the device. Frame data has to be
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1098
included in a so-called ``socket buffer'' for that (see below).
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1099
1588
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1100
\paragraph{Socket Buffers}\index{Socket buffer} Socket buffers are the basic
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1101
data type for the whole network stack. They serve as containers for network
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1102
data and are able to quickly add data headers and footers, or strip them off
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1103
again. Therefore a socket buffer consists of an allocated buffer and several
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1104
pointers that mark beginning of the buffer (\lstinline+head+), beginning of
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1105
data (\lstinline+data+), end of data (\lstinline+tail+) and end of buffer
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1106
(\lstinline+end+). In addition, a socket buffer holds network header
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1107
information and (in case of received data) a pointer to the
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1108
\lstinline+net_device+, it was received on. There exist functions that create
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1109
a socket buffer (\lstinline+dev_alloc_skb()+), add data either from front
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1110
(\lstinline+skb_push()+) or back (\lstinline+skb_put()+), remove data from
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1111
front (\lstinline+skb_pull()+) or back (\lstinline+skb_trim()+), or delete the
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1112
buffer (\lstinline+kfree_skb()+).  A socket buffer is passed from layer to
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1113
layer, and is freed by the layer that uses it the last time. In case of
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1114
sending, freeing has to be done by the network driver.
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1115
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1116
%------------------------------------------------------------------------------
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1117
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1118
\section{Native EtherCAT Device Drivers}
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1119
\label{sec:native-drivers}
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1120
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1121
There are a few requirements, that applies to Ethernet hardware when used with
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1122
a native Ethernet driver with EtherCAT functionality.
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1123
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1124
\paragraph{Dedicated Hardware} For performance and realtime purposes, the
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1125
EtherCAT master needs direct and exclusive access to the Ethernet hardware.
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1126
This implies that the network device must not be connected to the kernel's
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1127
network stack as usual, because the kernel would try to use it as an ordinary
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1128
Ethernet device.
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1129
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1130
\paragraph{Interrupt-less Operation}\index{Interrupt} EtherCAT frames travel
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1131
through the logical EtherCAT ring and are then sent back to the master.
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1132
Communication is highly deterministic: A frame is sent and will be received
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1133
again after a constant time, so there is no need to notify the driver about
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1134
frame reception: The master can instead query the hardware for received
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1135
frames, if it expects them to be already received.
1095
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  1136
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  1137
\autoref{fig:interrupt} shows two workflows for cyclic frame transmission
1095
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  1138
and reception with and without interrupts.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1139
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1140
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1141
  \centering
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1142
  \includegraphics[width=.9\textwidth]{images/interrupt}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1143
  \caption{Interrupt Operation versus Interrupt-less Operation}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1144
  \label{fig:interrupt}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1145
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1146
1095
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  1147
In the left workflow ``Interrupt Operation'', the data from the last cycle is
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  1148
first processed and a new frame is assembled with new datagrams, which is then
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  1149
sent.  The cyclic work is done for now.  Later, when the frame is received
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  1150
again by the hardware, an interrupt is triggered and the ISR is executed. The
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  1151
ISR will fetch the frame data from the hardware and initiate the frame
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  1152
dissection: The datagrams will be processed, so that the data is ready for
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  1153
processing in the next cycle.
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  1154
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  1155
In the right workflow ``Interrupt-less Operation'', there is no hardware
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  1156
interrupt enabled.  Instead, the hardware will be polled by the master by
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  1157
executing the ISR. If the frame has been received in the meantime, it will be
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  1158
dissected. The situation is now the same as at the beginning of the left
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  1159
workflow: The received data is processed and a new frame is assembled and
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  1160
sent. There is nothing to do for the rest of the cycle.
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  1161
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1162
The interrupt-less operation is desirable, because hardware interrupts are not
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1163
conducive in improving the driver's realtime behaviour: Their indeterministic
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1164
incidences contribute to increasing the jitter. Besides, if a realtime
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1165
extension (like RTAI) is used, some additional effort would have to be made to
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1166
prioritize interrupts.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1167
1588
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1168
\paragraph{Ethernet and EtherCAT Devices} Another issue lies in the way Linux
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1169
handles devices of the same type.  For example, a
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1170
PCI\nomenclature{PCI}{Peripheral Component Interconnect, Computer Bus} driver
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1171
scans the PCI bus for devices it can handle. Then it registers itself as the
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1172
responsible driver for all of the devices found. The problem is, that an
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1173
unmodified driver can not be told to ignore a device because it will be used
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1174
for EtherCAT later. There must be a way to handle multiple devices of the same
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1175
type, where one is reserved for EtherCAT, while the other is treated as an
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1176
ordinary Ethernet device.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1177
1095
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  1178
For all this reasons, the author decided that the only acceptable solution is
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  1179
to modify standard Ethernet drivers in a way that they keep their normal
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  1180
functionality, but gain the ability to treat one or more of the devices as
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  1181
EtherCAT-capable.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1182
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1183
Below are the advantages of this solution:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1184
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1185
\begin{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1186
\item No need to tell the standard drivers to ignore certain devices.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1187
\item One networking driver for EtherCAT and non-EtherCAT devices.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1188
\item No need to implement a network driver from scratch and running
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1189
  into issues, the former developers already solved.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1190
\end{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1191
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1192
The chosen approach has the following disadvantages:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1193
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1194
\begin{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1195
\item The modified driver gets more complicated, as it must handle
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1196
  EtherCAT and non-EtherCAT devices.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1197
\item Many additional case differentiations in the driver code.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1198
\item Changes and bug fixes on the standard drivers have to be ported
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1199
  to the Ether\-CAT-capable versions from time to time.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1200
\end{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1201
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1202
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1203
1588
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1204
\section{Generic EtherCAT Device Driver}
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1205
\label{sec:generic-driver}
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1206
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1207
Since there are approaches to enable the complete Linux kernel for realtime
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1208
operation \cite{rt-preempt}, it is possible to operate without native
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1209
implementations of EtherCAT-capable Ethernet device drivers and use the Linux
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  1210
network stack instead. \autoref{fig:arch} shows the ``Generic Ethernet Driver
1588
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1211
Module'', that connects to local Ethernet devices via the network stack. The
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1212
kernel module is named \lstinline+ec_generic+ and can be loaded after the
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1213
master module like a native EtherCAT-capable Ethernet driver.
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1214
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1215
The generic device driver scans the network stack for interfaces, that have
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1216
been registered by Ethernet device drivers. It offers all possible devices to
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1217
the EtherCAT master. If the master accepts a device, the generic driver
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1218
creates a packet socket (see \lstinline+man 7 packet+) with
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1219
\lstinline+socket_type+ set to \lstinline+SOCK_RAW+, bound to that device. All
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  1220
functions of the device interface (see \autoref{sec:ecdev}) will then operate
1588
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1221
on that socket.
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1222
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1223
Below are the advantages of this solution:
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1224
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1225
\begin{itemize}
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1226
\item Any Ethernet hardware, that is covered by a Linux Ethernet driver can be
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1227
used for EtherCAT.
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1228
\item No modifications have to be made to the actual Ethernet drivers.
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1229
\end{itemize}
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1230
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1231
The generic approach has the following disadvantages:
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1232
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1233
\begin{itemize}
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1234
\item The performance is a little worse than the native approach, because the
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1235
frame data have to traverse the lower layers of the network stack.
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1236
\item It is not possible to use in-kernel realtime extensions like RTAI with
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1237
the generic driver, because the network stack code uses dynamic memory
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1238
allocations and other things, that could cause the system to freeze in
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1239
realtime context.
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1240
\end{itemize}
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1241
2535
72b61b089625 Generic driver device activation in documentation.
Florian Pose <fp@igh-essen.com>
parents: 2515
diff changeset
  1242
\paragraph{Device Activation} In order to send and receive frames through a
72b61b089625 Generic driver device activation in documentation.
Florian Pose <fp@igh-essen.com>
parents: 2515
diff changeset
  1243
socket, the Ethernet device linked to that socket has to be activated,
72b61b089625 Generic driver device activation in documentation.
Florian Pose <fp@igh-essen.com>
parents: 2515
diff changeset
  1244
otherwise all frames will be rejected. Activation has to take place before the
72b61b089625 Generic driver device activation in documentation.
Florian Pose <fp@igh-essen.com>
parents: 2515
diff changeset
  1245
master module is loaded and can happen in several ways:
72b61b089625 Generic driver device activation in documentation.
Florian Pose <fp@igh-essen.com>
parents: 2515
diff changeset
  1246
72b61b089625 Generic driver device activation in documentation.
Florian Pose <fp@igh-essen.com>
parents: 2515
diff changeset
  1247
\begin{itemize}
72b61b089625 Generic driver device activation in documentation.
Florian Pose <fp@igh-essen.com>
parents: 2515
diff changeset
  1248
72b61b089625 Generic driver device activation in documentation.
Florian Pose <fp@igh-essen.com>
parents: 2515
diff changeset
  1249
\item Ad-hoc, using the command \lstinline+ip link set dev ethX up+ (or the
72b61b089625 Generic driver device activation in documentation.
Florian Pose <fp@igh-essen.com>
parents: 2515
diff changeset
  1250
older \lstinline+ifconfig ethX up+),
72b61b089625 Generic driver device activation in documentation.
Florian Pose <fp@igh-essen.com>
parents: 2515
diff changeset
  1251
72b61b089625 Generic driver device activation in documentation.
Florian Pose <fp@igh-essen.com>
parents: 2515
diff changeset
  1252
\item Configured, depending on the distribution, for example using
72b61b089625 Generic driver device activation in documentation.
Florian Pose <fp@igh-essen.com>
parents: 2515
diff changeset
  1253
\lstinline+ifcfg+ files (\lstinline+/etc/sysconfig/network/ifcfg-ethX+) in
72b61b089625 Generic driver device activation in documentation.
Florian Pose <fp@igh-essen.com>
parents: 2515
diff changeset
  1254
openSUSE and others. This is the better choice, if the EtherCAT master shall
72b61b089625 Generic driver device activation in documentation.
Florian Pose <fp@igh-essen.com>
parents: 2515
diff changeset
  1255
start at system boot time. Since the Ethernet device shall only be activated,
72b61b089625 Generic driver device activation in documentation.
Florian Pose <fp@igh-essen.com>
parents: 2515
diff changeset
  1256
but no IP address etc.\ shall be assigned, it is enough to use
72b61b089625 Generic driver device activation in documentation.
Florian Pose <fp@igh-essen.com>
parents: 2515
diff changeset
  1257
\lstinline+STARTMODE=auto+ as configuration.
72b61b089625 Generic driver device activation in documentation.
Florian Pose <fp@igh-essen.com>
parents: 2515
diff changeset
  1258
72b61b089625 Generic driver device activation in documentation.
Florian Pose <fp@igh-essen.com>
parents: 2515
diff changeset
  1259
\end{itemize}
72b61b089625 Generic driver device activation in documentation.
Florian Pose <fp@igh-essen.com>
parents: 2515
diff changeset
  1260
1588
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1261
%------------------------------------------------------------------------------
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1262
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1263
\section{Providing Ethernet Devices}
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1264
\label{sec:providing-devices}
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1265
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1266
After loading the master module, additional module(s) have to be loaded to
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  1267
offer devices to the master(s) (see \autoref{sec:ecdev}). The master module
1588
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1268
knows the devices to choose from the module parameters (see
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  1269
\autoref{sec:mastermod}). If the init script is used to start the master, the
1588
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1270
drivers and devices to use can be specified in the sysconfig file (see
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  1271
\autoref{sec:sysconfig}).
1588
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1272
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1273
Modules offering Ethernet devices can be
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1274
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1275
\begin{itemize}
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1276
\item native EtherCAT-capable network driver modules (see
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  1277
\autoref{sec:native-drivers}) or
1588
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1278
\item the generic EtherCAT device driver module (see
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  1279
\autoref{sec:generic-driver}).
1588
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1280
\end{itemize}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1281
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1282
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1283
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  1284
\section{Redundancy}
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  1285
\label{sec:redundancy}
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  1286
\index{Redundancy}
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  1287
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  1288
Redundant bus operation means, that there is more than one Ethernet connection
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  1289
from the master to the slaves. Process data exchange datagrams are sent out on
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  1290
every master link, so that the exchange is still complete, even if the bus is
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  1291
disconnected somewhere in between.
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  1292
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  1293
Prerequisite for fully redundant bus operation is, that every slave can be
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  1294
reached by at least one master link. In this case a single connection failure
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  1295
(i.\,e.~cable break) will never lead to incomplete process data. Double-faults
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  1296
can not be handled with two Ethernet devices.
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  1297
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  1298
Redundancy is configured with the \lstinline+--with-devices+ switch at
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  1299
configure time (see \autoref{sec:installation}) and using the
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  1300
\lstinline+backup_devices+ parameter of the \lstinline+ec_master+ kernel
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  1301
module (see \autoref{sec:mastermod}) or the appropriate variable
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  1302
\lstinline+MASTERx_BACKUP+ in the (sys-)config file (see
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  1303
\autoref{sec:sysconfig}).
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  1304
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  1305
Bus scanning is done after a topology change on any Ethernet link. The
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  1306
application interface (see \autoref{chap:api}) and the command-line tool (see
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  1307
\autoref{sec:tool}) both have methods to query the status of the redundant
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  1308
operation.
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  1309
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  1310
%------------------------------------------------------------------------------
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  1311
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1312
\section{EtherCAT Device Interface}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1313
\label{sec:ecdev}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1314
\index{Device interface}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1315
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1316
An anticipation to the section about the master module
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  1317
(\autoref{sec:mastermod}) has to be made in order to understand the way, a
1289
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  1318
network device driver module can connect a device to a specific EtherCAT
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  1319
master.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1320
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1321
The master module provides a ``device interface'' for network device drivers.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1322
To use this interface, a network device driver module must include the header
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1323
\textit{devices/ecdev.h}\nomenclature{ecdev}{EtherCAT Device}, coming with the
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1324
EtherCAT master code. This header offers a function interface for EtherCAT
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1325
devices. All functions of the device interface are named with the prefix
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1326
\lstinline+ecdev+.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1327
1289
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  1328
The documentation of the device interface can be found in the header file or
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  1329
in the appropriate module of the interface documentation (see
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  1330
\autoref{sec:gendoc} for generation instructions).
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1331
1296
69582b88e8fd Removed ldots
Florian Pose <fp@igh-essen.com>
parents: 1295
diff changeset
  1332
% TODO general description of the device interface
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1333
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1334
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1335
1588
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1336
\section{Patching Native Network Drivers}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1337
\label{sec:patching}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1338
\index{Network drivers}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1339
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1340
This section will describe, how to make a standard Ethernet driver
1588
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1341
EtherCAT-capable, using the native approach (see
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  1342
\autoref{sec:native-drivers}). Unfortunately, there is no standard procedure
1588
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1343
to enable an Ethernet driver for use with the EtherCAT master, but there are a
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1344
few common techniques.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1345
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1346
\begin{enumerate}
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1347
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1348
\item A first simple rule is, that \lstinline+netif_*()+ calls must be avoided
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1349
for all EtherCAT devices. As mentioned before, EtherCAT devices have no
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1350
connection to the network stack, and therefore must not call its interface
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1351
functions.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1352
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1353
\item Another important thing is, that EtherCAT devices should be operated
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1354
without interrupts. So any calls of registering interrupt handlers and enabling
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1355
interrupts at hardware level must be avoided, too.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1356
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1357
\item The master does not use a new socket buffer for each send operation:
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1358
Instead there is a fix one allocated on master initialization. This socket
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1359
buffer is filled with an EtherCAT frame with every send operation and passed to
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1360
the \lstinline+hard_start_xmit()+ callback. For that it is necessary, that the
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1361
socket buffer is not be freed by the network driver as usual.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1362
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1363
\end{enumerate}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1364
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1365
An Ethernet driver usually handles several Ethernet devices, each described by
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1366
a \lstinline+net_device+ structure with a \lstinline+priv_data+ field to
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1367
attach driver-dependent data to the structure. To distinguish between normal
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1368
Ethernet devices and the ones used by EtherCAT masters, the private data
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1369
structure used by the driver could be extended by a pointer, that points to an
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1370
\lstinline+ec_device_t+ object returned by \lstinline+ecdev_offer()+ (see
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  1371
\autoref{sec:ecdev}) if the device is used by a master and otherwise is zero.
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1372
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1373
The RealTek RTL-8139 Fast Ethernet driver is a ``simple'' Ethernet driver and
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1374
can be taken as an example to patch new drivers. The interesting sections can
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1375
be found by searching the string ``ecdev" in the file
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1376
\textit{devices/8139too-2.6.24-ethercat.c}.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1377
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1378
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1379
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1380
\chapter{State Machines}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1381
\label{sec:fsm}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1382
\index{FSM}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1383
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1384
Many parts of the EtherCAT master are implemented as \textit{finite state
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1385
machines} (FSMs\nomenclature{FSM}{Finite State Machine}). Though this leads
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1386
to a higher grade of complexity in some aspects, is opens many new
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1387
possibilities.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1388
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1389
The below short code example exemplary shows how to read all slave
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1390
states and moreover illustrates the restrictions of ``sequential''
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1391
coding:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1392
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1393
\begin{lstlisting}[gobble=2,language=C,numbers=left]
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1394
  ec_datagram_brd(datagram, 0x0130, 2); // prepare datagram
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1395
  if (ec_master_simple_io(master, datagram)) return -1;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1396
  slave_states = EC_READ_U8(datagram->data); // process datagram
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1397
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1398
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1399
The \textit{ec\_master\_simple\_io()} function provides a simple interface for
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1400
synchronously sending a single datagram and receiving the result\footnote{For
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1401
all communication issues have been meanwhile sourced out into state machines,
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1402
the function is deprecated and stopped existing. Nevertheless it is adequate
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1403
for showing it's own restrictions.}. Internally, it queues the specified
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1404
datagram, invokes the \textit{ec\_master\_send\_datagrams()} function to send
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1405
a frame with the queued datagram and then waits actively for its reception.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1406
1289
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  1407
This sequential approach is very simple, reflecting in only three lines of
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  1408
code. The disadvantage is, that the master is blocked for the time it waits
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  1409
for datagram reception. There is no difficulty when only one instance is using
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  1410
the master, but if more instances want to (synchronously\footnote{At this
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  1411
time, synchronous master access will be adequate to show the advantages of an
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  1412
FSM. The asynchronous approach will be discussed in \autoref{sec:eoe}}) use
1289
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  1413
the master, it is inevitable to think about an alternative to the sequential
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  1414
model.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1415
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1416
Master access has to be sequentialized for more than one instance
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1417
wanting to send and receive datagrams synchronously. With the present
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1418
approach, this would result in having one phase of active waiting for
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1419
each instance, which would be non-acceptable especially in realtime
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1420
circumstances, because of the huge time overhead.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1421
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1422
A possible solution is, that all instances would be executed
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1423
sequentially to queue their datagrams, then give the control to the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1424
next instance instead of waiting for the datagram reception. Finally,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1425
bus IO is done by a higher instance, which means that all queued
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1426
datagrams are sent and received. The next step is to execute all
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1427
instances again, which then process their received datagrams and issue
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1428
new ones.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1429
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1430
This approach results in all instances having to retain their state,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1431
when giving the control back to the higher instance. It is quite
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1432
obvious to use a \textit{finite state machine} model in this case.
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  1433
\autoref{sec:fsmtheory} will introduce some of the theory used,
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1434
while the listings below show the basic approach by coding the example
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1435
from above as a state machine:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1436
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1437
\begin{lstlisting}[gobble=2,language=C,numbers=left]
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1438
  // state 1
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1439
  ec_datagram_brd(datagram, 0x0130, 2); // prepare datagram
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1440
  ec_master_queue(master, datagram); // queue datagram
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1441
  next_state = state_2;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1442
  // state processing finished
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1443
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1444
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1445
After all instances executed their current state and queued their
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1446
datagrams, these are sent and received. Then the respective next
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1447
states are executed:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1448
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1449
\begin{lstlisting}[gobble=2,language=C,numbers=left]
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1450
  // state 2
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1451
  if (datagram->state != EC_DGRAM_STATE_RECEIVED) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1452
          next_state = state_error;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1453
          return; // state processing finished
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1454
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1455
  slave_states = EC_READ_U8(datagram->data); // process datagram
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1456
  // state processing finished.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1457
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1458
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  1459
See \autoref{sec:statemodel} for an introduction to the state machine
1289
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  1460
programming concept used in the master code.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1461
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1462
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1463
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1464
\section{State Machine Theory}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1465
\label{sec:fsmtheory}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1466
\index{FSM!Theory}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1467
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1468
A finite state machine \cite{automata} is a model of behavior with
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1469
inputs and outputs, where the outputs not only depend on the inputs,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1470
but the history of inputs. The mathematical definition of a finite
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1471
state machine (or finite automaton) is a six-tuple $(\Sigma, \Gamma,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1472
S, s_0, \delta, \omega)$, with
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1473
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1474
\begin{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1475
\item the input alphabet $\Sigma$, with $\Sigma \neq
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1476
  \emptyset$, containing all input symbols,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1477
\item the output alphabet $\Gamma$, with $\Gamma \neq
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1478
  \emptyset$, containing all output symbols,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1479
\item the set of states $S$, with $S \neq \emptyset$,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1480
\item the set of initial states $s_0$ with $s_0 \subseteq S, s_0 \neq
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1481
  \emptyset$
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1482
\item the transition function $\delta: S \times \Sigma \rightarrow S
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1483
  \times \Gamma$
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1484
\item the output function $\omega$.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1485
\end{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1486
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1487
The state transition function $\delta$ is often specified by a
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1488
\textit{state transition table}, or by a \textit{state transition
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1489
  diagram}. The transition table offers a matrix view of the state
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  1490
machine behavior (see \autoref{tab:statetrans}). The matrix rows
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1491
correspond to the states ($S = \{s_0, s_1, s_2\}$) and the columns
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1492
correspond to the input symbols ($\Gamma = \{a, b, \varepsilon\}$).
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1493
The table contents in a certain row $i$ and column $j$ then represent
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1494
the next state (and possibly the output) for the case, that a certain
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1495
input symbol $\sigma_j$ is read in the state $s_i$.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1496
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1497
\begin{table}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1498
  \caption{A typical state transition table}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1499
  \label{tab:statetrans}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1500
  \vspace{2mm}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1501
  \centering
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1502
  \begin{tabular}{l|ccc}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1503
    & $a$ & $b$ & $\varepsilon$\\ \hline
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1504
    $s_0$ & $s_1$ & $s_1$ & $s_2$\\
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1505
    $s_1$ & $s_2$ & $s_1$ & $s_0$\\
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1506
    $s_2$ & $s_0$ & $s_0$ & $s_0$\\ \hline
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1507
  \end{tabular}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1508
\end{table}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1509
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1510
The state diagram for the same example looks like the one in
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  1511
\autoref{fig:statetrans}. The states are represented as circles or
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1512
ellipses and the transitions are drawn as arrows between them. Close
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1513
to a transition arrow can be the condition that must be fulfilled to
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1514
allow the transition. The initial state is marked by a filled black
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1515
circle with an arrow pointing to the respective state.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1516
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1517
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1518
  \centering
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1519
  \includegraphics[width=.5\textwidth]{images/statetrans}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1520
  \caption{A typical state transition diagram}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1521
  \label{fig:statetrans}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1522
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1523
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1524
\paragraph{Deterministic and non-deterministic state machines}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1525
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1526
A state machine can be deterministic, meaning that for one state and
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1527
input, there is one (and only one) following state. In this case, the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1528
state machine has exactly one starting state. Non-deterministic state
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1529
machines can have more than one transitions for a single state-input
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1530
combination. There is a set of starting states in the latter case.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1531
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1532
\paragraph{Moore and Mealy machines}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1533
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1534
There is a distinction between so-called \textit{Moore machines}, and
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1535
\textit{Mealy machines}. Mathematically spoken, the distinction lies
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1536
in the output function $\omega$: If it only depends on the current
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1537
state ($\omega: S \rightarrow \Gamma$), the machine corresponds to the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1538
``Moore Model''. Otherwise, if $\omega$ is a function of a state and
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1539
the input alphabet ($\omega: S \times \Sigma \rightarrow \Gamma$) the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1540
state machine corresponds to the ``Mealy model''. Mealy machines are
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1541
the more practical solution in most cases, because their design allows
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1542
machines with a minimum number of states. In practice, a mixture of
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1543
both models is often used.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1544
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1545
\paragraph{Misunderstandings about state machines}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1546
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1547
There is a phenomenon called ``state explosion'', that is often taken as a
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1548
counter-argument against general use of state machines in complex environments.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1549
It has to be mentioned, that this point is misleading~\cite{fsmmis}. State
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1550
explosions happen usually as a result of a bad state machine design: Common
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1551
mistakes are storing the present values of all inputs in a state, or not
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1552
dividing a complex state machine into simpler sub state machines. The EtherCAT
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1553
master uses several state machines, that are executed hierarchically and so
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1554
serve as sub state machines. These are also described below.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1555
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1556
%------------------------------------------------------------------------------
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1557
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1558
\section{The Master's State Model}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1559
\label{sec:statemodel}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1560
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1561
This section will introduce the techniques used in the master to
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1562
implement state machines.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1563
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1564
\paragraph{State Machine Programming}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1565
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1566
There are certain ways to implement a state machine in \textit{C}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1567
code. An obvious way is to implement the different states and actions
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1568
by one big case differentiation:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1569
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1570
\begin{lstlisting}[gobble=2,language=C,numbers=left]
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1571
  enum {STATE_1, STATE_2, STATE_3};
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1572
  int state = STATE_1;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1573
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1574
  void state_machine_run(void *priv_data) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1575
          switch (state) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1576
                  case STATE_1:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1577
                          action_1();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1578
                          state = STATE_2;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1579
                          break;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1580
                  case STATE_2:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1581
                          action_2()
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1582
                          if (some_condition) state = STATE_1;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1583
                          else state = STATE_3;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1584
                          break;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1585
                  case STATE_3:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1586
                          action_3();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1587
                          state = STATE_1;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1588
                          break;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1589
          }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1590
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1591
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1592
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1593
For small state machines, this is an option. The disadvantage is, that
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1594
with an increasing number of states the code soon gets complex and an
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1595
additional case differentiation is executed each run. Besides, lots of
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1596
indentation is wasted.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1597
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1598
The method used in the master is to implement every state in an own
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1599
function and to store the current state function with a function
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1600
pointer:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1601
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1602
\begin{lstlisting}[gobble=2,language=C,numbers=left]
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1603
  void (*state)(void *) = state1;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1604
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1605
  void state_machine_run(void *priv_data) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1606
          state(priv_data);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1607
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1608
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1609
  void state1(void *priv_data) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1610
          action_1();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1611
          state = state2;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1612
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1613
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1614
  void state2(void *priv_data) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1615
          action_2();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1616
          if (some_condition) state = state1;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1617
          else state = state2;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1618
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1619
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1620
  void state3(void *priv_data) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1621
          action_3();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1622
          state = state1;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1623
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1624
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1625
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1626
In the master code, state pointers of all state machines\footnote{All except
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1627
for the EoE state machine, because multiple EoE slaves have to be handled in
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1628
parallel. For this reason each EoE handler object has its own state pointer.}
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1629
are gathered in a single object of the \lstinline+ec_fsm_master_t+ class. This
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1630
is advantageous, because there is always one instance of every state machine
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1631
available and can be started on demand.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1632
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1633
\paragraph{Mealy and Moore}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1634
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1635
If a closer look is taken to the above listing, it can be seen that the
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1636
actions executed (the ``outputs'' of the state machine) only depend on the
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1637
current state. This accords to the ``Moore'' model introduced in
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  1638
\autoref{sec:fsmtheory}. As mentioned, the ``Mealy'' model offers a higher
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1639
flexibility, which can be seen in the listing below:
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1640
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1641
\begin{lstlisting}[gobble=2,language=C,numbers=left]
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1642
  void state7(void *priv_data) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1643
          if (some_condition) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1644
                  action_7a();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1645
                  state = state1;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1646
          }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1647
          else {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1648
                  action_7b();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1649
                  state = state8;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1650
          }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1651
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1652
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1653
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1654
\begin{description}
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1655
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1656
\item[\linenum{3} + \linenum{7}] The state function executes the actions
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1657
depending on the state transition, that is about to be done.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1658
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1659
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1660
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1661
The most flexible alternative is to execute certain actions depending
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1662
on the state, followed by some actions dependent on the state
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1663
transition:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1664
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1665
\begin{lstlisting}[gobble=2,language=C,numbers=left]
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1666
  void state9(void *priv_data) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1667
          action_9();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1668
          if (some_condition) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1669
                  action_9a();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1670
                  state = state7;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1671
          }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1672
          else {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1673
                  action_9b();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1674
                  state = state10;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1675
          }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1676
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1677
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1678
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1679
This model is often used in the master. It combines the best aspects of both
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1680
approaches.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1681
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1682
\paragraph{Using Sub State Machines}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1683
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1684
To avoid having too much states, certain functions of the EtherCAT master
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1685
state machine have been sourced out into sub state machines.  This helps to
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1686
encapsulate the related workflows and moreover avoids the ``state explosion''
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  1687
phenomenon described in \autoref{sec:fsmtheory}. If the master would instead
1289
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  1688
use one big state machine, the number of states would be a multiple of the
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  1689
actual number. This would increase the level of complexity to a non-manageable
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  1690
grade.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1691
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1692
\paragraph{Executing Sub State Machines}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1693
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1694
If a state machine starts to execute a sub state machine, it usually
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1695
remains in one state until the sub state machine terminates. This is
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1696
usually done like in the listing below, which is taken out of the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1697
slave configuration state machine code:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1698
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1699
\begin{lstlisting}[gobble=2,language=C,numbers=left]
813
bfc3f1ab52de Fixed typo SAVEOP -> SAFEOP.
Florian Pose <fp@igh-essen.com>
parents: 487
diff changeset
  1700
  void ec_fsm_slaveconf_safeop(ec_fsm_t *fsm)
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1701
  {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1702
          fsm->change_state(fsm); // execute state change
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1703
                                  // sub state machine
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1704
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1705
          if (fsm->change_state == ec_fsm_error) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1706
                  fsm->slave_state = ec_fsm_end;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1707
                  return;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1708
          }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1709
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1710
          if (fsm->change_state != ec_fsm_end) return;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1711
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1712
          // continue state processing
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1713
          ...
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1714
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1715
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1716
\begin{description}
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1717
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1718
\item[\linenum{3}] \lstinline+change_state+ is the state pointer of the state
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1719
change state machine. The state function, the pointer points on, is
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1720
executed\ldots
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1721
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1722
\item[\linenum{6}] \ldots either until the state machine terminates with the
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1723
error state \ldots
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1724
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1725
\item[\linenum{11}] \ldots or until the state machine terminates in the end
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1726
state. Until then, the ``higher'' state machine remains in the current state
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1727
and executes the sub state machine again in the next cycle.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1728
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1729
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1730
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1731
\paragraph{State Machine Descriptions}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1732
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1733
The below sections describe every state machine used in the EtherCAT master.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1734
The textual descriptions of the state machines contain references to the
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1735
transitions in the corresponding state transition diagrams, that are marked
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1736
with an arrow followed by the name of the successive state. Transitions caused
1306
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
  1737
by trivial error cases (i.\,e.\ no response from slave) are not described
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1738
explicitly. These transitions are drawn as dashed arrows in the diagrams.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1739
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1740
%------------------------------------------------------------------------------
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1741
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1742
\section{The Master State Machine}
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1743
\label{sec:fsm-master}
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1744
\index{FSM!Master}
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1745
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1746
The master state machine is executed in the context of the master thread.
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  1747
\autoref{fig:fsm-master} shows its transition diagram. Its purposes are:
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1748
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1749
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1750
  \centering
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1751
  \includegraphics[width=\textwidth]{graphs/fsm_master}
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1752
  \caption{Transition diagram of the master state machine}
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1753
  \label{fig:fsm-master}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1754
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1755
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1756
\begin{description}
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1757
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1758
\item[Bus monitoring] The bus topology is monitored. If it changes, the bus is
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1759
(re-)scanned.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1760
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1761
\item[Slave configuration] The application-layer states of the slaves are
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1762
monitored. If a slave is not in the state it supposed to be, the slave is
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1763
(re-)configured.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1764
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1765
\item[Request handling] Requests (either originating from the application or
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1766
from external sources) are handled. A request is a job that the master shall
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  1767
process asynchronously, for example an SII access, SDO access, or similar.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1768
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1769
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1770
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1771
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1772
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1773
\section{The Slave Scan State Machine}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1774
\label{sec:fsm-scan}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1775
\index{FSM!Slave Scan}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1776
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1777
The slave scan state machine, which can be seen in
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  1778
\autoref{fig:fsm-slavescan}, leads through the process of reading desired
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1779
slave information.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1780
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1781
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1782
  \centering
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1783
  \includegraphics[height=.8\textheight]{graphs/fsm_slave_scan}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1784
  \caption{Transition diagram of the slave scan state machine}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1785
  \label{fig:fsm-slavescan}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1786
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1787
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1788
The scan process includes the following steps:
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1789
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1790
\begin{description}
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1791
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1792
\item[Node Address] The node address is set for the slave, so that it can be
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1793
node-addressed for all following operations.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1794
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1795
\item[AL State] The initial application-layer state is read.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1796
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1797
\item[Base Information] Base information (like the number of supported FMMUs)
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1798
is read from the lower physical memory.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1799
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1800
\item[Data Link] Information about the physical ports is read.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1801
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1802
\item[SII Size] The size of the SII contents is determined to allocate SII
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1803
image memory.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1804
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1805
\item[SII Data] The SII contents are read into the master's image.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1806
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1807
\item[PREOP] If the slave supports CoE, it is set to PREOP state using the
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  1808
State change FSM (see \autoref{sec:fsm-change}) to enable mailbox
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  1809
communication and read the PDO configuration via CoE.
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  1810
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  1811
\item[PDOs] The PDOs are read via CoE (if supported) using the PDO Reading FSM
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  1812
(see \autoref{sec:fsm-pdo}). If this is successful, the PDO information from
1289
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  1813
the SII (if any) is overwritten.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1814
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1815
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1816
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1817
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1818
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1819
\section{The Slave Configuration State Machine}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1820
\label{sec:fsm-conf}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1821
\index{FSM!Slave Configuration}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1822
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1823
The slave configuration state machine, which can be seen in
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  1824
\autoref{fig:fsm-slaveconf}, leads through the process of configuring a
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1825
slave and bringing it to a certain application-layer state.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1826
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1827
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1828
  \centering
1406
8686c5b3d14b Clear DC assignment after going to INIT.
Florian Pose <fp@igh-essen.com>
parents: 1399
diff changeset
  1829
  \includegraphics[height=\textheight]{graphs/fsm_slave_conf}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1830
  \caption{Transition diagram of the slave configuration state
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1831
    machine}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1832
  \label{fig:fsm-slaveconf}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1833
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1834
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1835
\begin{description}
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1836
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1837
\item[INIT] The state change FSM is used to bring the slave to the INIT state.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1838
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1839
\item[FMMU Clearing] To avoid that the slave reacts on any process data, the
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1840
FMMU configuration are cleared. If the slave does not support FMMUs, this
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1841
state is skipped. If INIT is the requested state, the state machine is
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1842
finished.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1843
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1844
\item[Mailbox Sync Manager Configuration] If the slaves support mailbox
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1845
communication, the mailbox sync managers are configured. Otherwise this state
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1846
is skipped.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1847
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1848
\item[PREOP] The state change FSM is used to bring the slave to PREOP state.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1849
If this is the requested state, the state machine is finished.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1850
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  1851
\item[SDO Configuration] If there is a slave configuration attached (see
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  1852
\autoref{sec:masterconfig}), and there are any SDO configurations are
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1853
provided by the application, these are sent to the slave.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1854
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  1855
\item[PDO Configuration] The PDO configuration state machine is executed to
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  1856
apply all necessary PDO configurations.
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  1857
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  1858
\item[PDO Sync Manager Configuration] If any PDO sync managers exist, they are
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1859
configured.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1860
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1861
\item[FMMU Configuration] If there are FMMUs configurations supplied by the
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  1862
application (i.\,e.\ if the application registered PDO entries), they are
2421
bc2d4bf9cbe5 Removed trailing spaces.
Florian Pose <fp@igh-essen.com>
parents: 2419
diff changeset
  1863
applied.
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1864
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1865
\item[SAFEOP] The state change FSM is used to bring the slave to SAFEOP state.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1866
If this is the requested state, the state machine is finished.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1867
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1868
\item[OP] The state change FSM is used to bring the slave to OP state.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1869
If this is the requested state, the state machine is finished.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1870
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1871
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1872
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1873
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1874
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1875
\section{The State Change State Machine}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1876
\label{sec:fsm-change}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1877
\index{FSM!State Change}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1878
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1879
The state change state machine, which can be seen in
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  1880
\autoref{fig:fsm-change}, leads through the process of changing a slave's
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1881
application-layer state. This implements the states and transitions described
1289
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  1882
in \cite[sec.~6.4.1]{alspec}.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1883
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1884
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1885
  \centering
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1886
  \includegraphics[width=.6\textwidth]{graphs/fsm_change}
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1887
  \caption{Transition Diagram of the State Change State Machine}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1888
  \label{fig:fsm-change}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1889
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1890
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1891
\begin{description}
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1892
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1893
\item[Start] The new application-layer state is requested via the ``AL Control
1306
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
  1894
Request'' register (see~\cite[sec. 5.3.1]{alspec}).
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1895
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1896
\item[Check for Response] Some slave need some time to respond to an AL state
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1897
change command, and do not respond for some time. For this case, the command
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1898
is issued again, until it is acknowledged.
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1899
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1900
\item[Check AL Status] If the AL State change datagram was acknowledged, the
1289
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  1901
``AL Control Response'' register (see~\cite[sec. 5.3.2]{alspec}) must be read
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  1902
out until the slave changes the AL state.
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1903
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1904
\item[AL Status Code] If the slave refused the state change command, the
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1905
reason can be read from the ``AL Status Code'' field in the ``AL State
1289
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  1906
Changed'' registers (see~\cite[sec. 5.3.3]{alspec}).
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1907
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1908
\item[Acknowledge State] If the state change was not successful, the master
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1909
has to acknowledge the old state by writing to the ``AL Control request''
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1910
register again.
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1911
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1912
\item[Check Acknowledge] After sending the acknowledge command, it has to read
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1913
out the ``AL Control Response'' register again.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1914
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1915
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1916
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1917
The ``start\_ack'' state is a shortcut in the state machine for the case, that
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1918
the master wants to acknowledge a spontaneous AL state change, that was not
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1919
requested.
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1920
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1921
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1922
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1923
\section{The SII State Machine}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1924
\label{sec:fsm-sii}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1925
\index{FSM!SII}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1926
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  1927
The SII\index{SII} state machine (shown in \autoref{fig:fsm-sii})
1289
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  1928
implements the process of reading or writing SII data via the Slave
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  1929
Information Interface described in \cite[sec.~6.4]{dlspec}.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1930
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1931
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1932
  \centering
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1933
  \includegraphics[width=.5\textwidth]{graphs/fsm_sii}
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1934
  \caption{Transition Diagram of the SII State Machine}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1935
  \label{fig:fsm-sii}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1936
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1937
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1938
This is how the reading part of the state machine works:
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1939
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1940
\begin{description}
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1941
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1942
\item[Start Reading] The read request and the requested word address are
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1943
written to the SII attribute.
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1944
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1945
\item[Check Read Command] If the SII read request command has been
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1946
acknowledged, a timer is started. A datagram is issued, that reads out the SII
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1947
attribute for state and data.
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1948
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1949
\item[Fetch Data] If the read operation is still busy (the SII is usually
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1950
implemented as an E$^2$PROM), the state is read again. Otherwise the data are
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1951
copied from the datagram.
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1952
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1953
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1954
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1955
The writing part works nearly similar:
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1956
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1957
\begin{description}
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1958
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1959
\item[Start Writing] A write request, the target address and the data word are
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1960
written to the SII attribute.
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1961
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1962
\item[Check Write Command] If the SII write request command has been
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1963
acknowledged, a timer is started. A datagram is issued, that reads out the SII
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1964
attribute for the state of the write operation.
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1965
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1966
\item[Wait while Busy] If the write operation is still busy (determined by a
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1967
minimum wait time and the state of the busy flag), the state machine remains in
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1968
this state to avoid that another write operation is issued too early.
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1969
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1970
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1971
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1972
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1973
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  1974
\section{The PDO State Machines}
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1975
\label{sec:fsm-pdo}
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  1976
\index{FSM!PDO}
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  1977
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  1978
The PDO state machines are a set of state machines that read or write the PDO
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  1979
assignment and the PDO mapping via the ``CoE Communication Area'' described in
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  1980
\cite[sec. 5.6.7.4]{alspec}. For the object access, the CANopen over EtherCAT
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  1981
access primitives are used (see \autoref{sec:coe}), so the slave must support
1289
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  1982
the CoE mailbox protocol.
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1983
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  1984
\paragraph{PDO Reading FSM} This state machine (\autoref{fig:fsm-pdo-read})
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  1985
has the purpose to read the complete PDO configuration of a slave. It reads
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  1986
the PDO assignment for each Sync Manager and uses the PDO Entry Reading FSM
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  1987
(\autoref{fig:fsm-pdo-entry-read}) to read the mapping for each assigned PDO.
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1988
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1989
\begin{figure}[htbp]
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1990
  \centering
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1991
  \includegraphics[width=.4\textwidth]{graphs/fsm_pdo_read}
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  1992
  \caption{Transition Diagram of the PDO Reading State Machine}
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1993
  \label{fig:fsm-pdo-read}
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1994
\end{figure}
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1995
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  1996
Basically it reads the every Sync manager's PDO assignment SDO's
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1997
(\lstinline+0x1C1x+) number of elements to determine the number of assigned
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  1998
PDOs for this sync manager and then reads out the subindices of the SDO to get
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  1999
the assigned PDO's indices. When a PDO index is read, the PDO Entry Reading
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  2000
FSM is executed to read the PDO's mapped PDO entries.
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  2001
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  2002
\paragraph{PDO Entry Reading FSM} This state machine
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2003
(\autoref{fig:fsm-pdo-entry-read}) reads the PDO mapping (the PDO entries) of
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  2004
a PDO. It reads the respective mapping SDO (\lstinline+0x1600+ --
1293
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
  2005
\lstinline+0x17ff+, or \lstinline+0x1a00+ -- \lstinline+0x1bff+) for the given
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  2006
PDO by reading first the subindex zero (number of elements) to determine the
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  2007
number of mapped PDO entries. After that, each subindex is read to get the
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  2008
mapped PDO entry index, subindex and bit size.
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  2009
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  2010
\begin{figure}[htbp]
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  2011
  \centering
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  2012
  \includegraphics[width=.4\textwidth]{graphs/fsm_pdo_entry_read}
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  2013
  \caption{Transition Diagram of the PDO Entry Reading State Machine}
1204
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
  2014
  \label{fig:fsm-pdo-entry-read}
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  2015
\end{figure}
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  2016
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  2017
\begin{figure}[htbp]
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  2018
  \centering
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  2019
  \includegraphics[width=.9\textwidth]{graphs/fsm_pdo_conf}
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  2020
  \caption{Transition Diagram of the PDO Configuration State Machine}
1204
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
  2021
  \label{fig:fsm-pdo-conf}
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  2022
\end{figure}
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  2023
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  2024
\begin{figure}[htbp]
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  2025
  \centering
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  2026
  \includegraphics[width=.4\textwidth]{graphs/fsm_pdo_entry_conf}
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  2027
  \caption{Transition Diagram of the PDO Entry Configuration State Machine}
1204
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
  2028
  \label{fig:fsm-pdo-entry-conf}
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  2029
\end{figure}
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  2030
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  2031
%------------------------------------------------------------------------------
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  2032
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2033
\chapter{Mailbox Protocol Implementations}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2034
\index{Mailbox}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2035
1917
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2036
The EtherCAT master implements the CANopen over EtherCAT (CoE), Ethernet over
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2037
EtherCAT (EoE), File-access over EtherCAT (FoE), Vendor-specific over EtherCAT
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2038
(VoE) and Servo Profile over EtherCAT (SoE) mailbox protocols. See the below
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2039
sections for details.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2040
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2041
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2042
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  2043
\section{Ethernet over EtherCAT (EoE)}
1269
fe4688f2c9e7 sec:ecrt is a chapter; sec:eoeimp -> sec:eoe, ...
Florian Pose <fp@igh-essen.com>
parents: 1235
diff changeset
  2044
\label{sec:eoe}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2045
\index{EoE}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2046
1306
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
  2047
The EtherCAT master implements the
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  2048
Ethernet over EtherCAT\nomenclature{EoE}{Ethernet over EtherCAT, Mailbox
1306
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
  2049
Protocol} mailbox protocol~\cite[sec.~5.7]{alspec} to enable the tunneling of
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
  2050
Ethernet frames to special slaves, that can either have physical Ethernet
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
  2051
ports to forward the frames to, or have an own IP stack to receive the frames.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2052
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2053
\paragraph{Virtual Network Interfaces}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2054
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2055
The master creates a virtual EoE network interface for every EoE-capable
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2056
slave. These interfaces are called either
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2057
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2058
\begin{description}
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2059
1293
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
  2060
\item[eoeXsY] for a slave without an alias address (see
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2061
\autoref{sec:ethercat-alias}), where X is the master index and Y is the
1293
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
  2062
slave's ring position, or
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2063
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2064
\item[eoeXaY] for a slave with a non-zero alias address, where X is the master
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2065
index and Y is the decimal alias address.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2066
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2067
\end{description}
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2068
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2069
Frames sent to these interfaces are forwarded to the associated slaves by the
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2070
master. Frames, that are received by the slaves, are fetched by the master and
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2071
forwarded to the virtual interfaces.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2072
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2073
This bears the following advantages:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2074
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2075
\begin{itemize}
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2076
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2077
\item Flexibility: The user can decide, how the EoE-capable slaves are
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2078
interconnected with the rest of the world.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2079
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2080
\item Standard tools can be used to monitor the EoE activity and to configure
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2081
the EoE interfaces.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2082
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2083
\item The Linux kernel's layer-2-bridging implementation (according to the
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2084
IEEE 802.1D MAC Bridging standard) can be used natively to bridge Ethernet
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2085
traffic between EoE-capable slaves.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2086
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2087
\item The Linux kernel's network stack can be used to route packets between
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2088
EoE-capable slaves and to track security issues, just like having physical
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2089
network interfaces.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2090
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2091
\end{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2092
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2093
\paragraph{EoE Handlers}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2094
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2095
The virtual EoE interfaces and the related functionality is encapsulated in
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2096
the \lstinline+ec_eoe_t+ class. An object of this class is called ``EoE
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2097
handler''. For example the master does not create the network interfaces
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2098
directly: This is done inside the constructor of an EoE handler. An EoE
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2099
handler additionally contains a frame queue. Each time, the kernel passes a
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2100
new socket buffer for sending via the interface's
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2101
\lstinline+hard_start_xmit()+ callback, the socket buffer is queued for
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2102
transmission by the EoE state machine (see below). If the queue gets filled
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2103
up, the passing of new socket buffers is suspended with a call to
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2104
\lstinline+netif_stop_queue()+.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2105
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2106
\paragraph{Creation of EoE Handlers}
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2107
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2108
During bus scanning (see \autoref{sec:fsm-scan}), the master determines the
1289
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  2109
supported mailbox protocols foe each slave. This is done by examining the
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2110
``Supported Mailbox Protocols'' mask field at word address 0x001C of the
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2111
SII\index{SII}. If bit 1 is set, the slave supports the EoE protocol. In this
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2112
case, an EoE handler is created for that slave.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2113
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2114
\paragraph{EoE State Machine}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2115
\index{FSM!EoE}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2116
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2117
Every EoE handler owns an EoE state machine, that is used to send frames to
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2118
the corresponding slave and receive frames from the it via the EoE
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2119
communication primitives. This state machine is showed in
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2120
\autoref{fig:fsm-eoe}.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2121
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2122
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2123
  \centering
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2124
  \includegraphics[width=.7\textwidth]{images/fsm-eoe} % FIXME
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2125
  \caption{Transition Diagram of the EoE State Machine}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2126
  \label{fig:fsm-eoe}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2127
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2128
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2129
% FIXME
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2130
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2131
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2132
\item[RX\_START] The beginning state of the EoE state machine. A
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2133
  mailbox check datagram is sent, to query the slave's mailbox for new
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2134
  frames. $\rightarrow$~RX\_CHECK
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2135
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2136
\item[RX\_CHECK] The mailbox check datagram is received. If the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2137
  slave's mailbox did not contain data, a transmit cycle is started.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2138
  $\rightarrow$~TX\_START
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2139
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2140
  If there are new data in the mailbox, a datagram is sent to fetch
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2141
  the new data. $\rightarrow$~RX\_FETCH
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2142
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2143
\item[RX\_FETCH] The fetch datagram is received. If the mailbox data
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2144
  do not contain a ``EoE Fragment request'' command, the data are
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2145
  dropped and a transmit sequence is started.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2146
  $\rightarrow$~TX\_START
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2147
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2148
  If the received Ethernet frame fragment is the first fragment, a new
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2149
  socket buffer is allocated. In either case, the data are copied into
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2150
  the correct position of the socket buffer.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2151
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2152
  If the fragment is the last fragment, the socket buffer is forwarded
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2153
  to the network stack and a transmit sequence is started.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2154
  $\rightarrow$~TX\_START
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2155
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2156
  Otherwise, a new receive sequence is started to fetch the next
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2157
  fragment. $\rightarrow$~RX\_\-START
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2158
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2159
\item[TX\_START] The beginning state of a transmit sequence. It is
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2160
  checked, if the transmission queue contains a frame to send. If not,
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2161
  a receive sequence is started. $\rightarrow$~RX\_START
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2162
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2163
  If there is a frame to send, it is dequeued. If the queue was
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2164
  inactive before (because it was full), the queue is woken up with a
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2165
  call to \textit{netif\_wake\_queue()}. The first fragment of the
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2166
  frame is sent. $\rightarrow$~TX\_SENT
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2167
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2168
\item[TX\_SENT] It is checked, if the first fragment was sent
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2169
  successfully. If the current frame consists of further fragments,
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2170
  the next one is sent. $\rightarrow$~TX\_SENT
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2171
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2172
  If the last fragment was sent, a new receive sequence is started.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2173
  $\rightarrow$~RX\_START
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2174
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2175
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2176
\paragraph{EoE Processing}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2177
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2178
To execute the EoE state machine of every active EoE handler, there must be a
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2179
cyclic process. The easiest solution would be to execute the EoE state
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2180
machines synchronously with the master state machine (see
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2181
\autoref{sec:fsm-master}). This approach has the following disadvantage:
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2182
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2183
Only one EoE fragment could be sent or received every few cycles. This
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2184
causes the data rate to be very low, because the EoE state machines are not
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2185
executed in the time between the application cycles. Moreover, the data rate
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2186
would be dependent on the period of the application task.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2187
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2188
To overcome this problem, an own cyclic process is needed to asynchronously
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2189
execute the EoE state machines. For that, the master owns a kernel timer, that
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2190
is executed each timer interrupt. This guarantees a constant bandwidth, but
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2191
poses the new problem of concurrent access to the master. The locking
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2192
mechanisms needed for this are introduced in \autoref{sec:concurr}.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2193
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2194
\paragraph{Automatic Configuration}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2195
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2196
By default, slaves are left in PREOP state, if no configuration is applied. If
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2197
an EoE interface link is set to ``up'', the requested slave's
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2198
application-layer state is automatically set to OP.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2199
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2200
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2201
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  2202
\section{CANopen over EtherCAT (CoE)}
1269
fe4688f2c9e7 sec:ecrt is a chapter; sec:eoeimp -> sec:eoe, ...
Florian Pose <fp@igh-essen.com>
parents: 1235
diff changeset
  2203
\label{sec:coe}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2204
\index{CoE}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2205
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  2206
The CANopen over EtherCAT\nomenclature{CoE}{CANopen over EtherCAT, Mailbox
1306
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
  2207
Protocol} protocol~\cite[sec.~5.6]{alspec} is used to configure slaves and
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
  2208
exchange data objects on application level.
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2209
1297
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
  2210
% TODO
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  2211
%
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  2212
% Download / Upload
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  2213
% Expedited / Normal
1204
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
  2214
% Segmenting
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  2215
% SDO Info Services
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  2216
%
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  2217
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  2218
\paragraph{SDO Download State Machine}
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  2219
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  2220
The best time to apply SDO configurations is during the slave's PREOP state,
1289
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  2221
because mailbox communication is already possible and slave's application will
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  2222
start with updating input data in the succeeding SAFEOP state. Therefore the
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  2223
SDO configuration has to be part of the slave configuration state machine (see
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2224
\autoref{sec:fsm-conf}): It is implemented via an SDO download state machine,
1289
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  2225
that is executed just before entering the slave's SAFEOP state. In this way,
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  2226
it is guaranteed that the SDO configurations are applied each time, the slave
1289
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  2227
is reconfigured.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2228
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  2229
The transition diagram of the SDO Download state machine can be seen
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2230
in \autoref{fig:fsm-coedown}.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2231
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2232
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2233
  \centering
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2234
  \includegraphics[width=.9\textwidth]{images/fsm-coedown} % FIXME
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2235
  \caption{Transition diagram of the CoE download state machine}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2236
  \label{fig:fsm-coedown}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2237
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2238
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2239
% FIXME
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2240
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2241
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2242
\item[START] The beginning state of the CoE download state
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  2243
  machine. The ``SDO Download Normal Request'' mailbox command is
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2244
  sent. $\rightarrow$~REQUEST
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2245
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2246
\item[REQUEST] It is checked, if the CoE download request has been
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2247
  received by the slave. After that, a mailbox check command is issued
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2248
  and a timer is started. $\rightarrow$~CHECK
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2249
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2250
\item[CHECK] If no mailbox data is available, the timer is checked.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2251
  \begin{itemize}
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  2252
  \item If it timed out, the SDO download is aborted.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2253
    $\rightarrow$~ERROR
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2254
  \item Otherwise, the mailbox is queried again.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2255
    $\rightarrow$~CHECK
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2256
  \end{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2257
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2258
  If the mailbox contains new data, the response is fetched.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2259
  $\rightarrow$~RESPONSE
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2260
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2261
\item[RESPONSE] If the mailbox response could not be fetched, the data
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  2262
  is invalid, the wrong protocol was received, or a ``Abort SDO
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  2263
  Transfer Request'' was received, the SDO download is aborted.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2264
  $\rightarrow$~ERROR
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2265
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  2266
  If a ``SDO Download Normal Response'' acknowledgement was received,
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  2267
  the SDO download was successful. $\rightarrow$~END
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  2268
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  2269
\item[END] The SDO download was successful.
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  2270
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  2271
\item[ERROR] The SDO download was aborted due to an error.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2272
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2273
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2274
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2275
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2276
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  2277
\section{Vendor specific over EtherCAT (VoE)}
1270
11f4b6e10d74 Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1269
diff changeset
  2278
\label{sec:voe}
11f4b6e10d74 Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1269
diff changeset
  2279
\index{VoE}
11f4b6e10d74 Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1269
diff changeset
  2280
11f4b6e10d74 Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1269
diff changeset
  2281
The VoE protocol opens the possibility to implement a vendor-specific mailbox
11f4b6e10d74 Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1269
diff changeset
  2282
communication protocol. VoE mailbox messages are prepended by a VoE header
11f4b6e10d74 Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1269
diff changeset
  2283
containing a 32-bit vendor ID and a 16-bit vendor-type. There are no more
11f4b6e10d74 Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1269
diff changeset
  2284
constraints regarding this protocol.
11f4b6e10d74 Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1269
diff changeset
  2285
11f4b6e10d74 Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1269
diff changeset
  2286
The EtherCAT master allows to create multiple VoE handlers per slave
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2287
configuration via the application interface (see \autoref{chap:api}). These
1270
11f4b6e10d74 Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1269
diff changeset
  2288
handlers contain the state machine necessary for the communication via VoE.
1298
de91d633ff6c VoE handlers.
Florian Pose <fp@igh-essen.com>
parents: 1297
diff changeset
  2289
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2290
For more information about using VoE handlers, see \autoref{sec:api-voe} or
1298
de91d633ff6c VoE handlers.
Florian Pose <fp@igh-essen.com>
parents: 1297
diff changeset
  2291
the example applications provided in the \textit{examples/} subdirectory.
1270
11f4b6e10d74 Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1269
diff changeset
  2292
11f4b6e10d74 Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1269
diff changeset
  2293
%------------------------------------------------------------------------------
11f4b6e10d74 Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1269
diff changeset
  2294
1917
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2295
\section{Servo Profile over EtherCAT (SoE)}
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2296
\label{sec:soe}
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2297
\index{SoE}
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2298
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2299
The SoE protocol implements the Service Channel layer, specified in IEC
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2300
61800-7 \cite{soespec} via EtherCAT mailboxes.
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2301
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2302
The SoE protocol is quite similar to the CoE protocol (see
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2303
\autoref{sec:coe}). Instead of SDO indices and subindices, so-called
1917
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2304
identification numbers (IDNs) identify parameters.
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2305
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2306
The implementation covers the ``SCC Read'' and ``SCC Write'' primitives, each
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2307
with the ability to fragment data.
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2308
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2309
There are several ways to use the SoE implementation:
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2310
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2311
\begin{itemize}
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2312
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2313
\item Reading and writing IDNs via the command-line tool (see
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2314
\autoref{sec:soeaccess}).
1917
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2315
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2316
\item Storing configurations for arbitrary IDNs via the application interface
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2317
(see \autoref{chap:api}, i.\,e.~\lstinline+ecrt_slave_config_idn()+). These
1917
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2318
configurations are written to the slave during configuration in PREOP state,
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2319
before going to SAFEOP.
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2320
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2321
\item The user-space library (see \autoref{sec:userlib}), offers functions to
1917
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2322
read/write IDNs in blocking mode (\lstinline+ecrt_master_read_idn()+,
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2323
\lstinline+ecrt_master_write_idn()+).
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2324
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2325
\end{itemize}
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2326
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2327
%------------------------------------------------------------------------------
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2328
1275
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  2329
\chapter{Userspace Interfaces}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2330
\label{sec:user}
1275
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  2331
\index{Userspace}
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2332
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  2333
For the master runs as a kernel module, accessing it is natively limited to
1275
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  2334
analyzing Syslog messages and controlling using \textit{modutils}.
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  2335
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  2336
It was necessary to implement further interfaces, that make it easier to access
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  2337
the master from userspace and allow a finer influence. It should be possible
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  2338
to view and to change special parameters at runtime.
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  2339
1275
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  2340
Bus visualization is another point: For development and debugging purposes it
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  2341
is necessary to show the connected slaves with a single command, for instance
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2342
(see \autoref{sec:tool}).
1275
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  2343
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  2344
The application interface has to be available in userspace, to allow userspace
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  2345
programs to use EtherCAT master functionality. This was implemented via a
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2346
character device and a userspace library (see \autoref{sec:userlib}).
1275
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  2347
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  2348
Another aspect is automatic startup and configuration. The master must be able
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  2349
to automatically start up with a persistent configuration (see
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2350
\autoref{sec:system}).
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  2351
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  2352
A last thing is monitoring EtherCAT communication. For debugging purposes,
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  2353
there had to be a way to analyze EtherCAT datagrams. The best way would be
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2354
with a popular network analyzer, like Wireshark \cite{wireshark} or others
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2355
(see \autoref{sec:debug}).
1275
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  2356
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  2357
This chapter covers all these points and introduces the interfaces and tools
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  2358
to make all that possible.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2359
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2360
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2361
1087
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2362
\section{Command-line Tool}
1289
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  2363
\label{sec:tool}
1087
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2364
1297
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
  2365
% TODO --master
1087
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2366
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2367
\subsection{Character Devices}
1087
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2368
\label{sec:cdev}
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2369
1214
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  2370
Each master instance will get a character device as a userspace interface.
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  2371
The devices are named \textit{/dev/EtherCATx}, where $x \in \{0 \ldots n\}$ is
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  2372
the index of the master.
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  2373
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  2374
\paragraph{Device Node Creation} The character device nodes are automatically
1289
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  2375
created, if the \lstinline+udev+ Package is installed. See
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2376
\autoref{sec:autonode} for how to install and configure it.
1087
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2377
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2378
%------------------------------------------------------------------------------
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2379
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2380
\subsection{Setting Alias Addresses}
1293
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
  2381
\label{sec:ethercat-alias}
1140
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2382
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2383
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_alias}
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2384
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2385
%------------------------------------------------------------------------------
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2386
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2387
\subsection{Displaying the Bus Configuration}
1293
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
  2388
\label{sec:ethercat-config}
1140
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2389
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2390
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_config}
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2391
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2392
%------------------------------------------------------------------------------
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2393
1514
85ac1c91045d Added 'ethercat cstruct' command to output PDO information in C language.
Florian Pose <fp@igh-essen.com>
parents: 1485
diff changeset
  2394
\subsection{Output PDO information in C Language}
85ac1c91045d Added 'ethercat cstruct' command to output PDO information in C language.
Florian Pose <fp@igh-essen.com>
parents: 1485
diff changeset
  2395
\label{sec:ethercat-cstruct}
85ac1c91045d Added 'ethercat cstruct' command to output PDO information in C language.
Florian Pose <fp@igh-essen.com>
parents: 1485
diff changeset
  2396
85ac1c91045d Added 'ethercat cstruct' command to output PDO information in C language.
Florian Pose <fp@igh-essen.com>
parents: 1485
diff changeset
  2397
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_cstruct}
85ac1c91045d Added 'ethercat cstruct' command to output PDO information in C language.
Florian Pose <fp@igh-essen.com>
parents: 1485
diff changeset
  2398
85ac1c91045d Added 'ethercat cstruct' command to output PDO information in C language.
Florian Pose <fp@igh-essen.com>
parents: 1485
diff changeset
  2399
%------------------------------------------------------------------------------
85ac1c91045d Added 'ethercat cstruct' command to output PDO information in C language.
Florian Pose <fp@igh-essen.com>
parents: 1485
diff changeset
  2400
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2401
\subsection{Displaying Process Data}
1140
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2402
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2403
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_data}
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2404
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2405
%------------------------------------------------------------------------------
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2406
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2407
\subsection{Setting a Master's Debug Level}
1399
f79d4bb5b23a Added debug_level module parameter. debug_level is now unsigned int.
Florian Pose <fp@igh-essen.com>
parents: 1364
diff changeset
  2408
\label{sec:ethercat-debug}
1140
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2409
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2410
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_debug}
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2411
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2412
%------------------------------------------------------------------------------
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2413
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2414
\subsection{Configured Domains}
1140
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2415
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2416
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_domains}
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2417
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2418
%------------------------------------------------------------------------------
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2419
1423
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2420
\subsection{SDO Access}
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2421
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2422
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_download}
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2423
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2424
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_upload}
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2425
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2426
%------------------------------------------------------------------------------
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2427
1485
5ddc3a455059 ethercat eoe command.
Florian Pose <fp@igh-essen.com>
parents: 1423
diff changeset
  2428
\subsection{EoE Statistics}
5ddc3a455059 ethercat eoe command.
Florian Pose <fp@igh-essen.com>
parents: 1423
diff changeset
  2429
5ddc3a455059 ethercat eoe command.
Florian Pose <fp@igh-essen.com>
parents: 1423
diff changeset
  2430
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_eoe}
5ddc3a455059 ethercat eoe command.
Florian Pose <fp@igh-essen.com>
parents: 1423
diff changeset
  2431
5ddc3a455059 ethercat eoe command.
Florian Pose <fp@igh-essen.com>
parents: 1423
diff changeset
  2432
%------------------------------------------------------------------------------
5ddc3a455059 ethercat eoe command.
Florian Pose <fp@igh-essen.com>
parents: 1423
diff changeset
  2433
1423
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2434
\subsection{File-Access over EtherCAT}
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2435
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2436
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_foe_read}
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2437
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2438
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_foe_write}
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2439
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2440
%------------------------------------------------------------------------------
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2441
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2442
\subsection{Creating Topology Graphs}
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2443
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2444
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_graph}
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2445
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2446
%------------------------------------------------------------------------------
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2447
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2448
\subsection{Master and Ethernet Devices}
1140
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2449
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2450
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_master}
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2451
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2452
%------------------------------------------------------------------------------
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2453
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  2454
\subsection{Sync Managers, PDOs and PDO Entries}
1140
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2455
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2456
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_pdos}
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2457
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2458
%------------------------------------------------------------------------------
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2459
1423
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2460
\subsection{Register Access}
1517
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
  2461
\label{sec:regaccess}
1423
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2462
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2463
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_reg_read}
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2464
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2465
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_reg_write}
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2466
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2467
%------------------------------------------------------------------------------
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2468
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  2469
\subsection{SDO Dictionary}
1140
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2470
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2471
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_sdos}
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2472
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2473
%------------------------------------------------------------------------------
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2474
1423
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2475
\subsection{SII Access}
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2476
\label{sec:siiaccess}
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2477
\index{SII!Access}
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2478
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2479
It is possible to directly read or write the complete SII contents of the
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2480
slaves. This was introduced for the reasons below:
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2481
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2482
\begin{itemize}
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2483
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2484
\item The format of the SII data is still in development and categories can be
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2485
added in the future. With read and write access, the complete memory contents
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2486
can be easily backed up and restored.
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2487
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2488
\item Some SII data fields have to be altered (like the alias address). A quick
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2489
writing must be possible for that.
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2490
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2491
\item Through reading access, analyzing category data is possible from
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2492
userspace.
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2493
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2494
\end{itemize}
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2495
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2496
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_sii_read}
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2497
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2498
Reading out SII data is as easy as other commands. Though the data are in
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2499
binary format, analysis is easier with a tool like \textit{hexdump}:
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2500
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2501
\begin{lstlisting}
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2502
$ `\textbf{ethercat sii\_read --position 3 | hexdump}`
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2503
0000000 0103 0000 0000 0000 0000 0000 0000 008c
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2504
0000010 0002 0000 3052 07f0 0000 0000 0000 0000
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2505
0000020 0000 0000 0000 0000 0000 0000 0000 0000
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2506
...
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2507
\end{lstlisting}
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2508
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2509
Backing up SII contents can easily done with a redirection:
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2510
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2511
\begin{lstlisting}
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2512
$ `\textbf{ethercat sii\_read --position 3 > sii-of-slave3.bin}`
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2513
\end{lstlisting}
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2514
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2515
To download SII contents to a slave, writing access to the master's character
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2516
device is necessary (see \autoref{sec:cdev}).
1423
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2517
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2518
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_sii_write}
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2519
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2520
\begin{lstlisting}
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2521
# `\textbf{ethercat sii\_write --position 3 sii-of-slave3.bin}`
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2522
\end{lstlisting}
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2523
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2524
The SII contents will be checked for validity and then sent to the slave. The
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2525
write operation may take a few seconds.
1140
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2526
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2527
%------------------------------------------------------------------------------
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2528
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2529
\subsection{Slaves on the Bus}
1087
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2530
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2531
Slave information can be gathered with the subcommand \lstinline+slaves+:
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2532
1140
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2533
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_slaves}
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2534
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2535
Below is a typical output:
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2536
1087
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2537
\begin{lstlisting}
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2538
$ `\textbf{ethercat slaves}`
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2539
0     0:0  PREOP  +  EK1100 Ethernet Kopplerklemme (2A E-Bus)
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2540
1  5555:0  PREOP  +  EL3162 2K. Ana. Eingang 0-10V
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2541
2  5555:1  PREOP  +  EL4102 2K. Ana. Ausgang 0-10V
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2542
3  5555:2  PREOP  +  EL2004 4K. Dig. Ausgang 24V, 0,5A
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2543
\end{lstlisting}
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2544
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2545
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2546
1917
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2547
\subsection{SoE IDN Access}
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2548
\label{sec:soeaccess}
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2549
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2550
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_soe_read}
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2551
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2552
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_soe_write}
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2553
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2554
%------------------------------------------------------------------------------
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2555
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2556
\subsection{Requesting Application-Layer States}
1140
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2557
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2558
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_states}
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2559
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2560
%------------------------------------------------------------------------------
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2561
1423
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2562
\subsection{Displaying the Master Version}
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2563
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2564
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_version}
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2565
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2566
%------------------------------------------------------------------------------
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2567
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2568
\subsection{Generating Slave Description XML}
1140
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2569
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2570
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_xml}
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2571
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2572
%------------------------------------------------------------------------------
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2573
1275
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  2574
\section{Userspace Library}
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  2575
\label{sec:userlib}
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  2576
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2577
The native application interface (see \autoref{chap:api}) resides in
1282
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2578
kernelspace and hence is only accessible from inside the kernel. To make the
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2579
application interface available from userspace programs, a userspace library
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2580
has been created, that can be linked to programs under the terms and
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2581
conditions of the LGPL, version 2 \cite{lgpl}.
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2582
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2583
The library is named \textit{libethercat}. Its sources reside in the
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2584
\textit{lib/} subdirectory and are build by default when using
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2585
\lstinline+make+. It is installed in the \textit{lib/} path below the
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2586
installation prefix as \textit{libethercat.a} (for static linking),
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2587
\textit{libethercat.la} (for the use with \textit{libtool}) and
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2588
\textit{libethercat.so} (for dynamic linking).
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2589
1299
dd8e55d97280 Userlib.
Florian Pose <fp@igh-essen.com>
parents: 1298
diff changeset
  2590
\subsection{Using the Library}
1282
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2591
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2592
The application interface header \textit{ecrt.h} can be used both in kernel
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2593
and in user context.
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2594
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2595
The following minimal example shows how to build a program with EtherCAT
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2596
functionality. An entire example can be found in the \textit{examples/user/}
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2597
path of the master sources.
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2598
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2599
\begin{lstlisting}[language=C]
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2600
#include <ecrt.h>
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2601
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2602
int main(void)
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2603
{
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2604
    ec_master_t *master = ecrt_request_master(0);
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2605
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2606
    if (!master)
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2607
        return 1; // error
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2608
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2609
    pause(); // wait for signal
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2610
    return 0;
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2611
}
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2612
\end{lstlisting}
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2613
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2614
The program can be compiled and dynamically linked to the library with the
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2615
below command:
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2616
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2617
\begin{lstlisting}[caption=Linker command for using the userspace library,
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2618
label=lst:linker-user]
1282
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2619
gcc ethercat.c -o ectest -I/opt/etherlab/include \
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2620
    -L/opt/etherlab/lib -lethercat \
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2621
    -Wl,--rpath -Wl,/opt/etherlab/lib
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2622
\end{lstlisting}
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2623
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2624
The library can also be linked statically to the program:
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2625
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2626
\begin{lstlisting}
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2627
gcc -static ectest.c -o ectest -I/opt/etherlab/include \
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2628
    /opt/etherlab/lib/libethercat.a
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2629
\end{lstlisting}
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2630
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2631
\subsection{Implementation}
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2632
\label{sec:userimp}
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2633
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2634
Basically the kernel API was transferred into userspace via the master
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2635
character device (see \autoref{chap:arch}, \autoref{fig:arch} and
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2636
\autoref{sec:cdev}).
1282
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2637
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2638
The function calls of the kernel API are mapped to the userspace via an
1517
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
  2639
\lstinline+ioctl()+ interface. The userspace API functions share a set of
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
  2640
generic \lstinline+ioctl()+ calls. The kernel part of the interface calls the
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
  2641
according API functions directly, what results in a minimum additional delay
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2642
(see \autoref{sec:usertiming}).
1282
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2643
1299
dd8e55d97280 Userlib.
Florian Pose <fp@igh-essen.com>
parents: 1298
diff changeset
  2644
For performance reasons, the actual domain process data (see
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2645
\autoref{sec:processdata}) are not copied between kernel and user memory on
1299
dd8e55d97280 Userlib.
Florian Pose <fp@igh-essen.com>
parents: 1298
diff changeset
  2646
every access: Instead, the data are memory-mapped to the userspace
dd8e55d97280 Userlib.
Florian Pose <fp@igh-essen.com>
parents: 1298
diff changeset
  2647
application. Once the master is configured and activated, the master module
dd8e55d97280 Userlib.
Florian Pose <fp@igh-essen.com>
parents: 1298
diff changeset
  2648
creates one process data memory area spanning all domains and maps it to
dd8e55d97280 Userlib.
Florian Pose <fp@igh-essen.com>
parents: 1298
diff changeset
  2649
userspace, so that the application can directly access the process data. As a
dd8e55d97280 Userlib.
Florian Pose <fp@igh-essen.com>
parents: 1298
diff changeset
  2650
result, there is no additional delay when accessing process data from
dd8e55d97280 Userlib.
Florian Pose <fp@igh-essen.com>
parents: 1298
diff changeset
  2651
userspace.
dd8e55d97280 Userlib.
Florian Pose <fp@igh-essen.com>
parents: 1298
diff changeset
  2652
dd8e55d97280 Userlib.
Florian Pose <fp@igh-essen.com>
parents: 1298
diff changeset
  2653
\paragraph{Kernel/User API Differences} Because of the memory-mapping of the
dd8e55d97280 Userlib.
Florian Pose <fp@igh-essen.com>
parents: 1298
diff changeset
  2654
process data, the memory is managed internally by the library functions. As a
dd8e55d97280 Userlib.
Florian Pose <fp@igh-essen.com>
parents: 1298
diff changeset
  2655
result, it is not possible to provide external memory for domains, like in the
dd8e55d97280 Userlib.
Florian Pose <fp@igh-essen.com>
parents: 1298
diff changeset
  2656
kernel API. The corresponding functions are only available in kernelspace.
dd8e55d97280 Userlib.
Florian Pose <fp@igh-essen.com>
parents: 1298
diff changeset
  2657
This is the only difference when using the application interface in userspace.
1275
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  2658
1281
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2659
\subsection{Timing}
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2660
\label{sec:usertiming}
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2661
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2662
An interesting aspect is the timing of the userspace library calls compared to
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2663
those of the kernel API. \autoref{tab:usertiming} shows the call times and
1281
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2664
standard deviancies of typical (and time-critical) API functions measured on
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2665
an Intel Pentium 4 M CPU with \unit{2.2}{\giga\hertz} and a standard 2.6.26
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2666
kernel.
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2667
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2668
\begin{table}[htbp]
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2669
  \centering
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2670
  \caption{Application Interface Timing Comparison}
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2671
  \label{tab:usertiming}
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2672
  \vspace{2mm}
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2673
  \begin{tabular}{l|c|c|c|c}
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2674
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2675
    &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2676
    \multicolumn{2}{|c}{\textbf{Kernelspace}} &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2677
    \multicolumn{2}{|c}{\textbf{Userspace}}  \\
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2678
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2679
    \textbf{Function} &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2680
    $\mu(t)$ &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2681
    $\sigma(t)$ &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2682
    $\mu(t)$ &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2683
    $\sigma(t)$ \\
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2684
    \hline
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2685
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2686
    \lstinline+ecrt_master_receive()+ &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2687
    \unit{1.1}{\micro\second} &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2688
    \unit{0.3}{\micro\second} &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2689
    \unit{2.2}{\micro\second} &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2690
    \unit{0.5}{\micro\second} \\
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2691
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2692
    \lstinline+ecrt_domain_process()+ &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2693
    \unit{<0.1}{\micro\second} &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2694
    \unit{<0.1}{\micro\second} &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2695
    \unit{1.0}{\micro\second} &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2696
    \unit{0.2}{\micro\second} \\
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2697
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2698
    \lstinline+ecrt_domain_queue()+ &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2699
    \unit{<0.1}{\micro\second} &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2700
    \unit{<0.1}{\micro\second} &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2701
    \unit{1.0}{\micro\second} &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2702
    \unit{0.1}{\micro\second} \\
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2703
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2704
    \lstinline+ecrt_master_send()+ &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2705
    \unit{1.8}{\micro\second} &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2706
    \unit{0.2}{\micro\second} &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2707
    \unit{2.5}{\micro\second} &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2708
    \unit{0.5}{\micro\second} \\
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2709
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2710
  \end{tabular}
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2711
\end{table}
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2712
1282
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2713
The test results show, that for this configuration, the userspace API causes
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2714
about \unit{1}{\micro\second} additional delay for each function, compared to
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2715
the kernel API.
1281
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2716
1275
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  2717
%------------------------------------------------------------------------------
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  2718
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2719
\section{RTDM Interface}
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2720
\label{sec:rtdm}
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2721
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2722
When using the userspace interfaces of realtime extensions like Xenomai or
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2723
RTAI, the use of \textit{ioctl()} is not recommended, because it may disturb
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2724
realtime operation. To accomplish this, the Real-Time Device Model (RTDM)
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2725
\cite{rtdm} has been developed.  The master module provides an RTDM interface
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2726
(see \autoref{fig:arch}) in addition to the normal character device, if the
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2727
master sources were configured with \lstinline+--enable-rtdm+ (see
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2728
\autoref{sec:installation}).
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2729
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2730
To force an application to use the RTDM interface instead of the normal
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2731
character device, it has to be linked with the \textit{libethercat\_rtdm}
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2732
library instead of \textit{libethercat}. The use of the
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2733
\textit{libethercat\_rtdm} is transparent, so the EtherCAT header
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2734
\textit{ecrt.h} with the complete API can be used as usual.
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2735
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2736
To make the example in \autoref{lst:linker-user} use the RTDM library, the
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2737
linker command has to be altered as follows:
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2738
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2739
\begin{lstlisting}
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2740
gcc ethercat-with-rtdm.c -o ectest -I/opt/etherlab/include \
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2741
    -L/opt/etherlab/lib -lethercat_rtdm \
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2742
    -Wl,--rpath -Wl,/opt/etherlab/lib
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2743
\end{lstlisting}
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2744
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2745
%------------------------------------------------------------------------------
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2746
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2747
\section{System Integration}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2748
\label{sec:system}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2749
1086
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2750
To integrate the EtherCAT master as a service into a running system, it comes
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2751
with an init script and a sysconfig file, that are described below. Modern
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2752
systems may be managed by systemd \cite{systemd}. Integration of the master
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2753
with systemd is described in \autoref{sec:systemd}.
1086
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2754
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2755
\subsection{Init Script}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2756
\label{sec:init}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2757
\index{Init script}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2758
1086
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2759
The EtherCAT master init script conforms to the requirements of the ``Linux
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2760
Standard Base'' (LSB\index{LSB}, \cite{lsb}). The script is installed to
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2761
\textit{etc/init.d/ethercat} below the installation prefix and has to be
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2762
copied (or better: linked) to the appropriate location (see
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2763
\autoref{sec:installation}), before the master can be inserted as a service.
1289
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  2764
Please note, that the init script depends on the sysconfig file described
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  2765
below.
1086
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2766
1306
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
  2767
To provide service dependencies (i.\,e.\ which services have to be started
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
  2768
before others) inside the init script code, LSB defines a special comment
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
  2769
block. System tools can extract this information to insert the EtherCAT init
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
  2770
script at the correct place in the startup sequence:
1086
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2771
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2772
\lstinputlisting[firstline=38,lastline=48]
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2773
    {../script/init.d/ethercat}
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2774
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2775
\subsection{Sysconfig File}
1086
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2776
\label{sec:sysconfig}
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2777
\index{Sysconfig file}
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2778
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2779
For persistent configuration, the init script uses a sysconfig file installed
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2780
to \textit{etc/sysconfig/ethercat} (below the installation prefix), that is
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2781
mandatory for the init script. The sysconfig file contains all configuration
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2782
variables needed to operate one or more masters. The documentation is inside
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2783
the file and included below:
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2784
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2785
\lstinputlisting[numbers=left,firstline=9,basicstyle=\ttfamily\scriptsize]
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2786
    {../script/sysconfig/ethercat}
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2787
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2788
For systems managed by systemd (see \autoref{sec:systemd}), the sysconfig file
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2789
has moved to \lstinline+/etc/ethercat.conf+. Both versions are part of the
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2790
master sources and are meant to used alternatively.
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2791
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2792
\subsection{Starting the Master as a Service}
1086
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2793
\label{sec:service}
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2794
\index{Service}
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2795
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2796
After the init script and the sysconfig file are placed into the right
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2797
location, the EtherCAT master can be inserted as a service. The different Linux
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2798
distributions offer different ways to mark a service for starting and stopping
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2799
in certain runlevels. For example, SUSE Linux provides the \textit{insserv}
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2800
command:
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2801
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2802
\begin{lstlisting}
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2803
# `\textbf{insserv ethercat}`
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2804
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2805
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2806
The init script can also be used for manually starting and stopping
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2807
the EtherCAT master. It has to be executed with one of the parameters
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2808
\texttt{start}, \texttt{stop}, \texttt{restart} or \texttt{status}.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2809
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2810
\begin{lstlisting}[gobble=2]
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2811
  # `\textbf{/etc/init.d/ethercat restart}`
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2812
  Shutting down EtherCAT master                done
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2813
  Starting EtherCAT master                     done
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2814
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2815
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2816
\subsection{Integration with systemd}
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2817
\label{sec:systemd}
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2818
\index{systemd}
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2819
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2820
Distributions using \textit{systemd} instead of the SysV init system are using service files to describe how a service is to be maintained. \autoref{lst:service} lists the master's service file:
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2821
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2822
\lstinputlisting[basicstyle=\ttfamily\footnotesize,caption=Service file,
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2823
label=lst:service]{../script/ethercat.service}
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2824
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2825
The \textit{ethercatctl} command is used to load and unload the master and
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2826
network driver modules in a similar way to the former init script
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2827
(\autoref{sec:init}). Because it is installed into the \textit{sbin/}
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2828
directory, it can also be used separately:
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2829
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2830
\begin{lstlisting}[gobble=2]
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2831
  # `\textbf{ethercatctl start}`
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2832
\end{lstlisting}
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2833
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2834
When using systemd and/or the \textit{ethercatctl} command, the master
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2835
configuration must be in \texttt{/etc/ethercat.conf} instead of
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2836
\texttt{/etc/sysconfig/ethercat}! The latter is ignored. The configuration
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2837
options are exactly the same.
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2838
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2839
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2840
1307
45a82ad140f8 New debug interfaces docs.
Florian Pose <fp@igh-essen.com>
parents: 1306
diff changeset
  2841
\section{Debug Interfaces}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2842
\label{sec:debug}
1307
45a82ad140f8 New debug interfaces docs.
Florian Pose <fp@igh-essen.com>
parents: 1306
diff changeset
  2843
\index{Debug Interfaces}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2844
1306
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
  2845
EtherCAT buses can always be monitored by inserting a switch between master
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
  2846
and slaves. This allows to connect another PC with a network monitor like
1588
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  2847
Wireshark~\cite{wireshark}, for example. It is also possible to listen to
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  2848
local network interfaces on the machine running the EtherCAT master directly.
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2849
If the generic Ethernet driver (see \autoref{sec:generic-driver}) is used,
1588
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  2850
the network monitor can directly listen on the network interface connected to
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  2851
the EtherCAT bus.
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  2852
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2853
When using native Ethernet drivers (see \autoref{sec:native-drivers}), there
1588
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  2854
are no local network interfaces to listen to, because the Ethernet devices
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  2855
used for EtherCAT are not registered at the network stack. For that case,
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  2856
so-called ``debug interfaces'' are supported, which are virtual network
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  2857
interfaces allowing to capture EtherCAT traffic with a network monitor (like
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  2858
Wireshark or tcpdump) running on the master machine without using external
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  2859
hardware. To use this functionality, the master sources have to be configured
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  2860
with the \lstinline+--enable-debug-if+ switch (see
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2861
\autoref{sec:installation}).
1307
45a82ad140f8 New debug interfaces docs.
Florian Pose <fp@igh-essen.com>
parents: 1306
diff changeset
  2862
45a82ad140f8 New debug interfaces docs.
Florian Pose <fp@igh-essen.com>
parents: 1306
diff changeset
  2863
Every EtherCAT master registers a read-only network interface per attached
1308
c8b82c27b6df Improved new debug interfaces again.
Florian Pose <fp@igh-essen.com>
parents: 1307
diff changeset
  2864
physical Ethernet device. The network interfaces are named \textit{ecdbgmX}
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2865
for the main device, and \textit{ecdbgbX} for the backup device, where X is
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2866
the master index. The below listing shows a debug interface among some
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2867
standard network interfaces:
1306
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
  2868
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
  2869
\begin{lstlisting}
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
  2870
# `\textbf{ip link}`
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
  2871
1: lo: <LOOPBACK,UP> mtu 16436 qdisc noqueue
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
  2872
    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
  2873
4: eth0: <BROADCAST,MULTICAST> mtu 1500 qdisc noop qlen 1000
1307
45a82ad140f8 New debug interfaces docs.
Florian Pose <fp@igh-essen.com>
parents: 1306
diff changeset
  2874
    link/ether 00:13:46:3b:ad:d7 brd ff:ff:ff:ff:ff:ff
1308
c8b82c27b6df Improved new debug interfaces again.
Florian Pose <fp@igh-essen.com>
parents: 1307
diff changeset
  2875
8: ecdbgm0: <BROADCAST,MULTICAST> mtu 1500 qdisc pfifo_fast
c8b82c27b6df Improved new debug interfaces again.
Florian Pose <fp@igh-essen.com>
parents: 1307
diff changeset
  2876
                                                 qlen 1000
1306
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
  2877
    link/ether 00:04:61:03:d1:01 brd ff:ff:ff:ff:ff:ff
1307
45a82ad140f8 New debug interfaces docs.
Florian Pose <fp@igh-essen.com>
parents: 1306
diff changeset
  2878
\end{lstlisting}
45a82ad140f8 New debug interfaces docs.
Florian Pose <fp@igh-essen.com>
parents: 1306
diff changeset
  2879
45a82ad140f8 New debug interfaces docs.
Florian Pose <fp@igh-essen.com>
parents: 1306
diff changeset
  2880
While a debug interface is enabled, all frames sent or received to or from the
45a82ad140f8 New debug interfaces docs.
Florian Pose <fp@igh-essen.com>
parents: 1306
diff changeset
  2881
physical device are additionally forwarded to the debug interface by the
1308
c8b82c27b6df Improved new debug interfaces again.
Florian Pose <fp@igh-essen.com>
parents: 1307
diff changeset
  2882
corresponding master. Network interfaces can be enabled with the below
c8b82c27b6df Improved new debug interfaces again.
Florian Pose <fp@igh-essen.com>
parents: 1307
diff changeset
  2883
command:
1306
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
  2884
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
  2885
\begin{lstlisting}
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
  2886
# `\textbf{ip link set dev ecdbgm0 up}`
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
  2887
\end{lstlisting}
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
  2888
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
  2889
Please note, that the frame rate can be very high. With an application
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
  2890
connected, the debug interface can produce thousands of frames per second.
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
  2891
1309
Florian Pose <fp@igh-essen.com>
parents: 1308
diff changeset
  2892
\paragraph{Attention} The socket buffers needed for the operation of debug
1588
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  2893
interfaces have to be allocated dynamically. Some Linux realtime extensions
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  2894
(like RTAI) do not allow this in realtime context!
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2895
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2896
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2897
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2898
\chapter{Timing Aspects}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2899
\label{sec:timing}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2900
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2901
Although EtherCAT's timing is highly deterministic and therefore timing issues
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2902
are rare, there are a few aspects that can (and should be) dealt with.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2903
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2904
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2905
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2906
\subsection{Application Interface Profiling}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2907
\label{sec:timing-profile}
1204
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
  2908
\index{Profiling}
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
  2909
% FIXME
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2910
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2911
One of the most important timing aspects are the execution times of the
1204
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
  2912
application interface functions, that are called in cyclic context. These
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2913
functions make up an important part of the overall timing of the application.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2914
To measure the timing of the functions, the following code was used:
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2915
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2916
\begin{lstlisting}[gobble=2,language=C]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2917
  c0 = get_cycles();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2918
  ecrt_master_receive(master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2919
  c1 = get_cycles();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2920
  ecrt_domain_process(domain1);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2921
  c2 = get_cycles();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2922
  ecrt_master_run(master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2923
  c3 = get_cycles();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2924
  ecrt_master_send(master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2925
  c4 = get_cycles();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2926
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2927
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2928
Between each call of an interface function, the CPU timestamp counter is read.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2929
The counter differences are converted to \micro\second\ with help of the
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2930
\lstinline+cpu_khz+ variable, that contains the number of increments per
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2931
\milli\second.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2932
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2933
For the actual measuring, a system with a \unit{2.0}{\giga\hertz} CPU was used,
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2934
that ran the above code in an RTAI thread with a period of
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2935
\unit{100}{\micro\second}. The measuring was repeated $n = 100$ times and the
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2936
results were averaged. These can be seen in \autoref{tab:profile}.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2937
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2938
\begin{table}[htpb]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2939
  \centering
1204
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
  2940
  \caption{Profiling of an Application Cycle on a \unit{2.0}{\giga\hertz}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2941
  Processor}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2942
  \label{tab:profile}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2943
  \vspace{2mm}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2944
  \begin{tabular}{l|r|r}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2945
    Element & Mean Duration [\second] & Standard Deviancy [\micro\second] \\
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2946
    \hline
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2947
    \textit{ecrt\_master\_receive()} & 8.04 & 0.48\\
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2948
    \textit{ecrt\_domain\_process()} & 0.14 & 0.03\\
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2949
    \textit{ecrt\_master\_run()} & 0.29 & 0.12\\
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2950
    \textit{ecrt\_master\_send()} & 2.18 & 0.17\\ \hline
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2951
    Complete Cycle & 10.65 & 0.69\\ \hline
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2952
  \end{tabular}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2953
\end{table}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2954
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2955
It is obvious, that the functions accessing hardware make up the
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2956
lion's share. The \textit{ec\_master\_receive()} executes the ISR of
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2957
the Ethernet device, analyzes datagrams and copies their contents into
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2958
the memory of the datagram objects. The \textit{ec\_master\_send()}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2959
assembles a frame out of different datagrams and copies it to the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2960
hardware buffers. Interestingly, this makes up only a quarter of the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2961
receiving time.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2962
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2963
The functions that only operate on the masters internal data structures are
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2964
very fast ($\Delta t < \unit{1}{\micro\second}$). Interestingly the runtime of
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2965
\textit{ec\_domain\_process()} has a small standard deviancy relative to the
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2966
mean value, while this ratio is about twice as big for
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2967
\textit{ec\_master\_run()}: This probably results from the latter function
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2968
having to execute code depending on the current state and the different state
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2969
functions are more or less complex.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2970
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2971
For a realtime cycle makes up about \unit{10}{\micro\second}, the theoretical
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2972
frequency can be up to \unit{100}{\kilo\hertz}. For two reasons, this frequency
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2973
keeps being theoretical:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2974
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2975
\begin{enumerate}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2976
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2977
\item The processor must still be able to run the operating system between the
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2978
realtime cycles.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2979
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2980
\item The EtherCAT frame must be sent and received, before the next realtime
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2981
cycle begins. The determination of the bus cycle time is difficult and covered
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  2982
in \autoref{sec:timing-bus}.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2983
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2984
\end{enumerate}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2985
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2986
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2987
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2988
\subsection{Bus Cycle Measuring}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2989
\label{sec:timing-bus}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2990
\index{Bus cycle}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2991
1297
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
  2992
For measuring the time, a frame is ``on the wire'', two timestamps must be
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
  2993
taken:
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2994
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2995
\begin{enumerate}
1297
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
  2996
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
  2997
\item The time, the Ethernet hardware begins with physically sending the
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
  2998
frame.
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
  2999
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
  3000
\item The time, the frame is completely received by the Ethernet hardware.
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
  3001
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3002
\end{enumerate}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3003
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3004
Both times are difficult to determine. The first reason is, that the
1297
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
  3005
interrupts are disabled and the master is not notified, when a frame is sent
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
  3006
or received (polling would distort the results). The second reason is, that
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
  3007
even with interrupts enabled, the time from the event to the notification is
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
  3008
unknown. Therefore the only way to confidently determine the bus cycle time is
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
  3009
an electrical measuring.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3010
1204
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
  3011
Anyway, the bus cycle time is an important factor when designing realtime
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
  3012
code, because it limits the maximum frequency for the cyclic task of the
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
  3013
application.  In practice, these timing parameters are highly dependent on the
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
  3014
hardware and often a trial and error method must be used to determine the
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
  3015
limits of the system.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3016
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3017
The central question is: What happens, if the cycle frequency is too high? The
1297
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
  3018
answer is, that the EtherCAT frames that have been sent at the end of the
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
  3019
cycle are not yet received, when the next cycle starts.  First this is noticed
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
  3020
by \textit{ecrt\_domain\_process()}, because the working counter of the
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
  3021
process data datagrams were not increased. The function will notify the user
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
  3022
via Syslog\footnote{To limit Syslog output, a mechanism has been implemented,
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
  3023
that outputs a summarized notification at maximum once a second.}. In this
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
  3024
case, the process data keeps being the same as in the last cycle, because it
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
  3025
is not erased by the domain. When the domain datagrams are queued again, the
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
  3026
master notices, that they are already queued (and marked as sent). The master
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
  3027
will mark them as unsent again and output a warning, that datagrams were
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3028
``skipped''.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3029
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3030
On the mentioned \unit{2.0}{\giga\hertz} system, the possible cycle frequency
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3031
can be up to \unit{25}{\kilo\hertz} without skipped frames. This value can
1297
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
  3032
surely be increased by choosing faster hardware. Especially the RealTek
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
  3033
network hardware could be replaced by a faster one. Besides, implementing a
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
  3034
dedicated ISR for EtherCAT devices would also contribute to increasing the
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
  3035
latency. These are two points on the author's to-do list.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3036
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3037
%------------------------------------------------------------------------------
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3038
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3039
\chapter{Installation}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3040
\label{sec:installation}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3041
\index{Master!Installation}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3042
1772
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  3043
\section{Getting the Software}
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  3044
\label{sec:getting}
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  3045
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  3046
There are several ways to get the master software:
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  3047
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  3048
\begin{enumerate}
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  3049
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  3050
\item An official release (for example \masterversion), can be downloaded from
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  3051
the master's website\footnote{\url{http://etherlab.org/en/ethercat/index.php}}
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  3052
at~the EtherLab project~\cite{etherlab} as a tarball.
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  3053
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  3054
\item The most recent development revision (and moreover any other revision)
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  3055
can be obtained via the Mercurial~\cite{mercurial} repository on the master's
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  3056
project page on
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  3057
SourceForge.net\footnote{\url{http://sourceforge.net/projects/etherlabmaster}}.
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  3058
The whole repository can be cloned with the command
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  3059
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  3060
\begin{lstlisting}[breaklines=true]
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  3061
hg clone http://etherlabmaster.hg.sourceforge.net/hgweb/etherlabmaster/etherlabmaster `\textit{local-dir}`
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  3062
\end{lstlisting}
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  3063
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  3064
\item Without a local Mercurial installation, tarballs of arbitrary revisions
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  3065
can be downloaded via the ``bz2'' links in the browsable repository
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  3066
pages\footnote{\url{http://etherlabmaster.hg.sourceforge.net/hgweb/etherlabmaster/etherlabmaster}}.
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  3067
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  3068
\end{enumerate}
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  3069
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  3070
\section{Building the Software}
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3071
1772
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  3072
After downloading a tarball or cloning the repository as described in
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  3073
\autoref{sec:getting}, the sources have to be prepared and configured for the
1772
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  3074
build process.
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  3075
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  3076
When a tarball was downloaded, it has to be extracted with the following
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  3077
commands:
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3078
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3079
\begin{lstlisting}[gobble=2]
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  3080
  $ `\textbf{tar xjf ethercat-\masterversion.tar.bz2}`
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  3081
  $ `\textbf{cd ethercat-\masterversion/}`
374
e43a29f9079e Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents: 371
diff changeset
  3082
\end{lstlisting}
e43a29f9079e Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents: 371
diff changeset
  3083
1772
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  3084
The software configuration is managed with Autoconf~\cite{autoconf} so the
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  3085
released versions contain a \lstinline+configure+ shell script, that has to be
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  3086
executed for configuration (see below).
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  3087
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  3088
\paragraph{Bootstrap} When downloading or cloning directly from the
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  3089
repository, the \lstinline+configure+ script does not yet exist. It can be
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  3090
created via the \lstinline+bootstrap.sh+ script in the master sources. The
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  3091
autoconf and automake packages are required for this.
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  3092
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  3093
\paragraph{Configuration and Build} The configuration and the build process
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  3094
follow the below commands:
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3095
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3096
\begin{lstlisting}[gobble=2]
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  3097
  $ `\textbf{./configure}`
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  3098
  $ `\textbf{make}`
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  3099
  $ `\textbf{make modules}`
374
e43a29f9079e Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents: 371
diff changeset
  3100
\end{lstlisting}
e43a29f9079e Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents: 371
diff changeset
  3101
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  3102
\autoref{tab:config} lists important configuration switches and options.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3103
2297
0566476835d7 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2133
diff changeset
  3104
\begin{longtable}{l|p{.4\textwidth}|l}
0566476835d7 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2133
diff changeset
  3105
  \caption{Configuration options}\rule[-5ex]{0mm}{0mm}
0566476835d7 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2133
diff changeset
  3106
  \label{tab:config}\\
0566476835d7 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2133
diff changeset
  3107
0566476835d7 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2133
diff changeset
  3108
\textbf{Option/Switch} & \textbf{Description} & \textbf{Default}\\\hline
0566476835d7 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2133
diff changeset
  3109
\endfirsthead
0566476835d7 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2133
diff changeset
  3110
0566476835d7 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2133
diff changeset
  3111
\textbf{Option/Switch} & \textbf{Description} & \textbf{Default}\\\hline
0566476835d7 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2133
diff changeset
  3112
\endhead
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3113
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3114
\lstinline+--prefix+ & Installation prefix & \textit{/opt/etherlab}\\
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3115
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3116
\lstinline+--with-linux-dir+ & Linux kernel sources & Use running kernel\\
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3117
2297
0566476835d7 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2133
diff changeset
  3118
\lstinline+--with-module-dir+ & Subdirectory in the kernel module tree, where
0566476835d7 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2133
diff changeset
  3119
the EtherCAT kernel modules shall be installed. & \textit{ethercat}\\
0566476835d7 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2133
diff changeset
  3120
0566476835d7 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2133
diff changeset
  3121
\hline
0566476835d7 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2133
diff changeset
  3122
0566476835d7 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2133
diff changeset
  3123
\lstinline+--enable-generic+ & Build the generic Ethernet driver (see
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  3124
\autoref{sec:generic-driver}). & yes\\
2297
0566476835d7 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2133
diff changeset
  3125
0566476835d7 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2133
diff changeset
  3126
\lstinline+--enable-8139too+ & Build the 8139too driver & yes\\
0566476835d7 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2133
diff changeset
  3127
0566476835d7 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2133
diff changeset
  3128
\lstinline+--with-8139too-kernel+ & 8139too kernel & $\dagger$\\
0566476835d7 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2133
diff changeset
  3129
0566476835d7 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2133
diff changeset
  3130
\lstinline+--enable-e100+ & Build the e100 driver & no\\
0566476835d7 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2133
diff changeset
  3131
0566476835d7 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2133
diff changeset
  3132
\lstinline+--with-e100-kernel+ & e100 kernel & $\dagger$\\
0566476835d7 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2133
diff changeset
  3133
0566476835d7 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2133
diff changeset
  3134
\lstinline+--enable-e1000+ & Enable e1000 driver & no\\
0566476835d7 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2133
diff changeset
  3135
0566476835d7 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2133
diff changeset
  3136
\lstinline+--with-e1000-kernel+ & e1000 kernel & $\dagger$\\
0566476835d7 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2133
diff changeset
  3137
2364
41ad0b0e55b0 Use 1.5 documentation/ethercat_doc.tex.
Florian Pose <fp@igh-essen.com>
parents: 2330
diff changeset
  3138
\lstinline+--enable-e1000e+ & Enable e1000e driver & no\\
41ad0b0e55b0 Use 1.5 documentation/ethercat_doc.tex.
Florian Pose <fp@igh-essen.com>
parents: 2330
diff changeset
  3139
41ad0b0e55b0 Use 1.5 documentation/ethercat_doc.tex.
Florian Pose <fp@igh-essen.com>
parents: 2330
diff changeset
  3140
\lstinline+--with-e1000e-kernel+ & e1000e kernel & $\dagger$\\
41ad0b0e55b0 Use 1.5 documentation/ethercat_doc.tex.
Florian Pose <fp@igh-essen.com>
parents: 2330
diff changeset
  3141
2297
0566476835d7 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2133
diff changeset
  3142
\lstinline+--enable-r8169+ & Enable r8169 driver & no\\
0566476835d7 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2133
diff changeset
  3143
0566476835d7 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2133
diff changeset
  3144
\lstinline+--with-r8169-kernel+ & r8169 kernel & $\dagger$\\
0566476835d7 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2133
diff changeset
  3145
0566476835d7 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2133
diff changeset
  3146
\hline
0566476835d7 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2133
diff changeset
  3147
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  3148
\lstinline+--enable-rtdm+ & Create the RTDM interface (RTAI or Xenomai
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  3149
directory needed, see below) & no\\
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  3150
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  3151
\lstinline+--with-rtai-dir+ & RTAI path (for RTAI examples and RTDM interface)
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  3152
& \\
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  3153
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  3154
\lstinline+--with-xenomai-dir+ & Xenomai path (for Xenomai examples and RTDM
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  3155
interface) & \\
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  3156
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  3157
\lstinline+--with-devices+ & Number of Ethernet devices for redundant
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  3158
operation ($>1$ switches redundancy on) & 1\\
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3159
2297
0566476835d7 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2133
diff changeset
  3160
\lstinline+--enable-debug-if+ & Create a debug interface for each master & no\\
0566476835d7 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2133
diff changeset
  3161
0566476835d7 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2133
diff changeset
  3162
\lstinline+--enable-debug-ring+ & Create a debug ring to record frames & no\\
0566476835d7 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2133
diff changeset
  3163
0566476835d7 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2133
diff changeset
  3164
\lstinline+--enable-eoe+ & Enable EoE support & yes\\
0566476835d7 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2133
diff changeset
  3165
0566476835d7 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2133
diff changeset
  3166
\lstinline+--enable-cycles+ & Use CPU timestamp counter. Enable this on Intel
0566476835d7 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2133
diff changeset
  3167
architecture to get finer timing calculation. & no\\
0566476835d7 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2133
diff changeset
  3168
0566476835d7 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2133
diff changeset
  3169
\lstinline+--enable-hrtimer+ & Use high-resolution timer to let the master
0566476835d7 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2133
diff changeset
  3170
state machine sleep between sending frames. & no\\
0566476835d7 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2133
diff changeset
  3171
0566476835d7 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2133
diff changeset
  3172
\lstinline+--enable-regalias+ & Read alias address from register. & no\\
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3173
1588
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  3174
\lstinline+--enable-tool+ & Build the command-line tool ``ethercat'' (see
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  3175
\autoref{sec:tool}). & yes\\
1588
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  3176
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  3177
\lstinline+--enable-userlib+ & Build the userspace library. & yes\\
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  3178
2297
0566476835d7 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2133
diff changeset
  3179
\lstinline+--enable-tty+ & Build the TTY driver. & no\\
0566476835d7 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2133
diff changeset
  3180
0566476835d7 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2133
diff changeset
  3181
\lstinline+--enable-wildcards+ & Enable \textit{0xffffffff} to be wildcards
0566476835d7 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2133
diff changeset
  3182
for vendor ID and product code. & no\\
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3183
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  3184
\lstinline+--enable-sii-assign+ & Enable assigning SII access to the PDI layer
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  3185
during slave configuration. & no\\
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  3186
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3187
\hline
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3188
2297
0566476835d7 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2133
diff changeset
  3189
\end{longtable}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3190
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3191
\begin{description}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3192
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3193
\item[$\dagger$] If this option is not specified, the kernel version to use is
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3194
extracted from the Linux kernel sources.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3195
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3196
\end{description}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3197
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  3198
\section{Building the Interface Documentation}
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3199
\label{sec:gendoc}
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3200
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3201
The source code is documented using Doxygen~\cite{doxygen}. To build the HTML
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  3202
documentation, the Doxygen software has to be installed. The below command
1095
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  3203
will generate the documents in the subdirectory \textit{doxygen-output}:
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3204
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3205
\begin{lstlisting}
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3206
$ `\textbf{make doc}`
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3207
\end{lstlisting}
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3208
1204
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
  3209
The interface documentation can be viewed by pointing a browser to the file
1293
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
  3210
\textit{doxygen-output/html/index.html}. The functions and data structures of
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
  3211
the application interface a covered by an own module ``Application
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
  3212
Interface''.
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  3213
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  3214
\section{Installing the Software}
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3215
1106
745a0cc03143 Added depmod call to docs.
Florian Pose <fp@igh-essen.com>
parents: 1095
diff changeset
  3216
The below commands have to be entered as \textit{root}: The first one will
1275
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  3217
install the EtherCAT header, init script, sysconfig file and the userspace
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  3218
tool to the prefix path. The second one will install the kernel modules to the
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  3219
kernel's modules directory. The final \lstinline+depmod+ call is necessary to
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  3220
include the kernel modules into the \textit{modules.dep} file to make it
2421
bc2d4bf9cbe5 Removed trailing spaces.
Florian Pose <fp@igh-essen.com>
parents: 2419
diff changeset
  3221
available to the \lstinline+modprobe+ command, used in the init script.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3222
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3223
\begin{lstlisting}
1106
745a0cc03143 Added depmod call to docs.
Florian Pose <fp@igh-essen.com>
parents: 1095
diff changeset
  3224
# `\textbf{make install}`
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3225
# `\textbf{make modules\_install}`
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3226
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3227
1095
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  3228
If the target kernel's modules directory is not under \textit{/lib/modules}, a
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  3229
different destination directory can be specified with the \lstinline+DESTDIR+
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  3230
make variable. For example:
487
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
  3231
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3232
\begin{lstlisting}
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3233
# `\textbf{make DESTDIR=/vol/nfs/root modules\_install}`
487
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
  3234
\end{lstlisting}
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
  3235
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
  3236
This command will install the compiled kernel modules to
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
  3237
\textit{/vol/nfs/root/lib/modules}, prepended by the kernel release.
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
  3238
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3239
If the EtherCAT master shall be run as a service\footnote{Even if the EtherCAT
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3240
master shall not be loaded on system startup, the use of the init script is
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  3241
recommended for manual (un-)loading.} (see \autoref{sec:system}), the init
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  3242
script and the sysconfig file (or the systemd service file, respectively) have
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  3243
to be copied (or linked) to the appropriate locations. The below example is
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  3244
suitable for SUSE Linux. It may vary for other distributions.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3245
1107
Florian Pose <fp@igh-essen.com>
parents: 1106
diff changeset
  3246
% FIXME relative ln -s?
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3247
\begin{lstlisting}
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3248
# `\textbf{cd /opt/etherlab}`
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3249
# `\textbf{cp etc/sysconfig/ethercat /etc/sysconfig/}`
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3250
# `\textbf{ln -s etc/init.d/ethercat /etc/init.d/}`
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3251
# `\textbf{insserv ethercat}`
374
e43a29f9079e Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents: 371
diff changeset
  3252
\end{lstlisting}
e43a29f9079e Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents: 371
diff changeset
  3253
376
d1441d87f5c1 Documentation: EtherLab-CD; obtaining the DEVICE_INDEX.
Florian Pose <fp@igh-essen.com>
parents: 374
diff changeset
  3254
Now the sysconfig file \texttt{/etc/sysconfig/ethercat} (see
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  3255
\autoref{sec:sysconfig}), or the configuration file
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  3256
\textit{/etc/ethercat.conf}, if using systemd, has to be customized. The
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  3257
minimal customization is to set the \lstinline+MASTER0_DEVICE+ variable to the
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  3258
MAC address of the Ethernet device to use (or \lstinline+ff:ff:ff:ff:ff:ff+ to
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  3259
use the first device offered) and selecting the driver(s) to load via the
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3260
\lstinline+DEVICE_MODULES+ variable.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3261
1297
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
  3262
After the basic configuration is done, the master can be started with the
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
  3263
below command:
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3264
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3265
\begin{lstlisting}
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3266
# `\textbf{/etc/init.d/ethercat start}`
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3267
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3268
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  3269
When using systemd, the following command can be used alternatively:
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  3270
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  3271
\begin{lstlisting}
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  3272
# `\textbf{ethercatctl start}`
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  3273
\end{lstlisting}
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  3274
1214
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  3275
At this time, the operation of the master can be observed by viewing the
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  3276
Syslog\index{Syslog} messages, which should look like the ones below. If
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  3277
EtherCAT slaves are connected to the master's EtherCAT device, the activity
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  3278
indicators should begin to flash.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3279
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3280
\begin{lstlisting}[numbers=left]
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3281
EtherCAT: Master driver `\masterversion`
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3282
EtherCAT: 1 master waiting for devices.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3283
EtherCAT Intel(R) PRO/1000 Network Driver - version 6.0.60-k2
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3284
Copyright (c) 1999-2005 Intel Corporation.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3285
PCI: Found IRQ 12 for device 0000:01:01.0
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3286
PCI: Sharing IRQ 12 with 0000:00:1d.2
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3287
PCI: Sharing IRQ 12 with 0000:00:1f.1
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3288
EtherCAT: Accepting device 00:0E:0C:DA:A2:20 for master 0.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3289
EtherCAT: Starting master thread.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3290
ec_e1000: ec0: e1000_probe: Intel(R) PRO/1000 Network
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3291
          Connection
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3292
ec_e1000: ec0: e1000_watchdog_task: NIC Link is Up 100 Mbps
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3293
          Full Duplex
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3294
EtherCAT: Link state changed to UP.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3295
EtherCAT: 7 slave(s) responding.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3296
EtherCAT: Slave states: PREOP.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3297
EtherCAT: Scanning bus.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3298
EtherCAT: Bus scanning completed in 431 ms.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3299
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3300
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3301
\begin{description}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3302
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3303
\item[\linenum{1} -- \linenum{2}] The master module is loading, and one master
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3304
is initialized.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3305
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3306
\item[\linenum{3} -- \linenum{8}] The EtherCAT-capable e1000 driver is
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3307
loading. The master accepts the device with the address
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3308
\lstinline+00:0E:0C:DA:A2:20+.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3309
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3310
\item[\linenum{9} -- \linenum{16}] The master goes to idle phase, starts its
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3311
state machine and begins scanning the bus.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3312
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3313
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3314
1214
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  3315
\section{Automatic Device Node Creation}
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  3316
\label{sec:autonode}
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  3317
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  3318
The \lstinline+ethercat+ command-line tool (see \autoref{sec:tool})
1214
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  3319
communicates with the master via a character device. The corresponding device
1289
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  3320
nodes are created automatically, if the udev daemon is running.  Note, that on
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  3321
some distributions, the \lstinline+udev+ package is not installed by default.
1214
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  3322
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  3323
The device nodes will be created with mode \lstinline+0660+ and group
1292
ea1bcfb8d631 Avouded 'you'.
Florian Pose <fp@igh-essen.com>
parents: 1291
diff changeset
  3324
\lstinline+root+ by default. If ``normal'' users shall have reading access, a
ea1bcfb8d631 Avouded 'you'.
Florian Pose <fp@igh-essen.com>
parents: 1291
diff changeset
  3325
udev rule file (for example \textit{/etc/udev/rules.d/99-EtherCAT.rules}) has
ea1bcfb8d631 Avouded 'you'.
Florian Pose <fp@igh-essen.com>
parents: 1291
diff changeset
  3326
to be created with the following contents:
1214
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  3327
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  3328
\begin{lstlisting}
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  3329
KERNEL=="EtherCAT[0-9]*", MODE="0664"
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  3330
\end{lstlisting}
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  3331
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  3332
After the udev rule file is created and the EtherCAT master is restarted with
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  3333
\lstinline[breaklines=true]+/etc/init.d/ethercat restart+, the device node
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  3334
will be automatically created with the desired rights:
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  3335
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  3336
\begin{lstlisting}
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  3337
# `\textbf{ls -l /dev/EtherCAT0}`
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  3338
crw-rw-r--  1 root root 252, 0 2008-09-03 16:19 /dev/EtherCAT0
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  3339
\end{lstlisting}
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  3340
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  3341
Now, the \lstinline+ethercat+ tool can be used (see \autoref{sec:tool}) even
1289
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  3342
as a non-root user.
1214
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  3343
1306
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
  3344
If non-root users shall have writing access, the following udev rule can be
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
  3345
used instead:
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
  3346
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
  3347
\begin{lstlisting}
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
  3348
KERNEL=="EtherCAT[0-9]*", MODE="0664", GROUP="users"
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
  3349
\end{lstlisting}
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
  3350
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3351
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3352
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3353
\begin{thebibliography}{99}
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3354
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3355
\bibitem{etherlab} Ingenieurgemeinschaft IgH: EtherLab -- Open Source Toolkit
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3356
for rapid realtime code generation under Linux with Simulink/RTW and EtherCAT
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3357
technology. \url{http://etherlab.org/en}, 2008.
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3358
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3359
\bibitem{dlspec} IEC 61158-4-12: Data-link Protocol Specification.
1095
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  3360
International Electrotechnical Commission (IEC), 2005.
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3361
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3362
\bibitem{alspec} IEC 61158-6-12: Application Layer Protocol Specification.
1095
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  3363
International Electrotechnical Commission (IEC), 2005.
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3364
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3365
\bibitem{gpl} GNU General Public License, Version 2.
1275
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  3366
\url{http://www.gnu.org/licenses/gpl-2.0.html}. October~15, 2008.
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  3367
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  3368
\bibitem{lgpl} GNU Lesser General Public License, Version 2.1.
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  3369
\url{http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html}. October~15,
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  3370
2008.
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3371
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3372
\bibitem{lsb} Linux Standard Base.
1306
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
  3373
\url{http://www.linuxfoundation.org/en/LSB}. August~9, 2006.
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3374
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  3375
\bibitem{systemd} systemd System and Service Manager
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  3376
\url{http://freedesktop.org/wiki/Software/systemd}. January~18, 2013.
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  3377
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3378
\bibitem{wireshark} Wireshark. \url{http://www.wireshark.org}. 2008.
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3379
1306
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
  3380
\bibitem{automata} {\it Hopcroft, J.\,E.\ / Ullman, J.\,D.}: Introduction to
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3381
Automata Theory, Languages and Computation. Adison-Wesley, Reading,
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3382
Mass.~1979.
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3383
1306
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
  3384
\bibitem{fsmmis} {\it Wagner, F.\ / Wolstenholme, P.}: State machine
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3385
misunderstandings. In: IEE journal ``Computing and Control Engineering'',
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3386
2004.
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3387
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3388
\bibitem{rtai} RTAI. The RealTime Application Interface for Linux from DIAPM.
1588
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  3389
\url{https://www.rtai.org}, 2010.
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  3390
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  3391
\bibitem{rt-preempt} RT PREEMPT HOWTO.
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  3392
\url{http://rt.wiki.kernel.org/index.php/RT_PREEMPT_HOWTO}, 2010.
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3393
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3394
\bibitem{doxygen} Doxygen. Source code documentation generator tool.
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3395
\url{http://www.stack.nl/~dimitri/doxygen}, 2008.
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3396
1772
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  3397
\bibitem{mercurial} Mercurial SCM. \url{http://mercurial.selenic.com}, 2010.
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  3398
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  3399
\bibitem{autoconf} Autoconf -- GNU Project -- Free Software Foundation (FSF).
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  3400
\url{http://www.gnu.org/software/autoconf}, 2010.
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  3401
1917
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  3402
\bibitem{soespec} IEC 61800-7-304: Adjustable speed electrical power drive
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  3403
systems - Part 7-300: Generic interface and use of profiles for power drive
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  3404
systems - Mapping of profiles to network technologies. International
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  3405
Electrotechnical Commission (IEC), 2007.
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  3406
2515
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  3407
\bibitem{rtdm} {\it J. Kiszka}: The Real-Time Driver Model and First
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  3408
Applications.
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  3409
\url{http://svn.gna.org/svn/xenomai/tags/v2.4.0/doc/nodist/pdf/RTDM-and-Applications.pdf},
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  3410
2013.
1f03f2543fc3 Documented redundancy, RTDM interface and systemd usage.
Florian Pose <fp@igh-essen.com>
parents: 2421
diff changeset
  3411
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3412
\end{thebibliography}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3413
917
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
  3414
\printnomenclature
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3415
\addcontentsline{toc}{chapter}{\nomname}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3416
\markleft{\nomname}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3417
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3418
\printindex
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3419
\markleft{Index}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3420
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3421
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3422
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3423
\end{document}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3424
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3425
%------------------------------------------------------------------------------