documentation/ethercat_doc.tex
author Florian Pose <fp@igh-essen.com>
Tue, 10 Jan 2012 10:43:56 +0100
changeset 2254 fe87d02a6790
parent 2229 97c7c202fa78
child 2589 2b9c78543663
permissions -rw-r--r--
Fixed suspend/resume for r8169 drivers.
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
%
2229
97c7c202fa78 Enable generic driver by default.
Florian Pose <fp@igh-essen.com>
parents: 2153
diff changeset
     5
%  $Id$
369
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
1095
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
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{}
2153
5bb7df22ced2 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2076
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,
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
    39
  belowskip=2mm,escapechar=`}
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
2229
97c7c202fa78 Enable generic driver by default.
Florian Pose <fp@igh-essen.com>
parents: 2153
diff changeset
    66
\rcsInfo $RCSId$
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    67
1270
11f4b6e10d74 Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1269
diff changeset
    68
\newcommand{\masterversion}{1.5.0}
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
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   177
\item Designed as a kernel module for Linux 2.6.
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
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
   190
  implemented using the common device interface (see sec.~\ref{sec:ecdev})
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
1588
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
   206
  \item RTAI\nomenclature{RTAI}{Realtime Application Interface} \cite{rtai},
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   207
  ADEOS\nomenclature{ADEOS}{Adaptive Domain Environment for Operating
1588
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
   208
  Systems}, RT-Preempt \cite{rt-preempt}, etc.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   209
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   210
  \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
   211
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   212
  \end{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   213
1204
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
   214
\item Common ``Application Interface'' for applications, that want to use
1289
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
   215
EtherCAT functionality (see chap.~\ref{chap:api}).
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   216
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   217
\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
   218
  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
   219
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   220
  \begin{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   221
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   222
  \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
   223
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   224
  \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
   225
  configuration within each domain.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   226
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   227
  \end{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   228
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   229
\item Communication through several finite state machines.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   230
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   231
  \begin{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   232
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   233
  \item Automatic bus scanning after topology changes.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   234
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   235
  \item Bus monitoring during operation.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   236
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   237
  \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
   238
  during operation.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   239
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   240
  \end{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   241
1517
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   242
\item Distributed Clocks support (see sec.~\ref{sec:dc}).
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   243
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   244
  \begin{itemize}
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   245
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   246
  \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
   247
  interface.
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   248
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   249
  \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
   250
  slave clocks to the reference clock.
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   251
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   252
  \item Optional synchronization of the reference clock to the master clock.
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   253
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   254
  \end{itemize}
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   255
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
   256
\item CANopen over EtherCAT (CoE)
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   257
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   258
  \begin{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   259
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
   260
  \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
   261
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
   262
  \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
   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 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
   265
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   266
  \end{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   267
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
   268
\item Ethernet over EtherCAT (EoE)
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   269
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   270
  \begin{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   271
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   272
  \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
   273
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   274
  \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
   275
  architecture.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   276
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   277
  \end{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   278
1364
471cd0e77b55 Updated features.
Florian Pose <fp@igh-essen.com>
parents: 1327
diff changeset
   279
\item Vendor-specific over EtherCAT (VoE)
471cd0e77b55 Updated features.
Florian Pose <fp@igh-essen.com>
parents: 1327
diff changeset
   280
471cd0e77b55 Updated features.
Florian Pose <fp@igh-essen.com>
parents: 1327
diff changeset
   281
  \begin{itemize}
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
  \item Communication with vendor-specific mailbox protocols via the API.
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
  \end{itemize}
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
\item File Access over EtherCAT (FoE)
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
  \begin{itemize}
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
  \item Loading and storing files via the command-line tool.
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 Updating a slave's firmware can be done easily.
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
  \end{itemize}
471cd0e77b55 Updated features.
Florian Pose <fp@igh-essen.com>
parents: 1327
diff changeset
   296
1917
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
   297
\item Servo Profile over EtherCAT (SoE)
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
   298
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
   299
  \begin{itemize}
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
  \item Implemented according to IEC 61800-7 \cite{soespec}.
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 Storing IDN configurations, that are written to the slave during
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
   304
  startup.
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
   305
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
   306
  \item Accessing IDNs via the command-line tool.
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 at runtime via the the user-space library.
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
  \end{itemize}
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
   311
1517
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   312
\item Userspace command-line-tool ``ethercat'' (see sec.~\ref{sec:tool})
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   313
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   314
  \begin{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   315
1364
471cd0e77b55 Updated features.
Florian Pose <fp@igh-essen.com>
parents: 1327
diff changeset
   316
  \item Detailed information about master, slaves, domains and bus
471cd0e77b55 Updated features.
Florian Pose <fp@igh-essen.com>
parents: 1327
diff changeset
   317
  configuration.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   318
  \item Setting the master's debug level.
1364
471cd0e77b55 Updated features.
Florian Pose <fp@igh-essen.com>
parents: 1327
diff changeset
   319
  \item Reading/Writing alias addresses.
471cd0e77b55 Updated features.
Florian Pose <fp@igh-essen.com>
parents: 1327
diff changeset
   320
  \item Listing slave configurations.
471cd0e77b55 Updated features.
Florian Pose <fp@igh-essen.com>
parents: 1327
diff changeset
   321
  \item Viewing process data.
471cd0e77b55 Updated features.
Florian Pose <fp@igh-essen.com>
parents: 1327
diff changeset
   322
  \item SDO download/upload; listing SDO dictionaries.
471cd0e77b55 Updated features.
Florian Pose <fp@igh-essen.com>
parents: 1327
diff changeset
   323
  \item Loading and storing files via FoE.
1917
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
   324
  \item SoE IDN access.
1364
471cd0e77b55 Updated features.
Florian Pose <fp@igh-essen.com>
parents: 1327
diff changeset
   325
  \item Access to slave registers.
471cd0e77b55 Updated features.
Florian Pose <fp@igh-essen.com>
parents: 1327
diff changeset
   326
  \item Slave SII (EEPROM) access.
471cd0e77b55 Updated features.
Florian Pose <fp@igh-essen.com>
parents: 1327
diff changeset
   327
  \item Controlling application-layer states.
1517
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   328
  \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
   329
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   330
  \end{itemize}
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
\item Seamless system integration though LSB\nomenclature{LSB}{Linux
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   333
    Standard Base} compliance.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   334
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   335
  \begin{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   336
1095
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   337
  \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
   338
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   339
  \item Init script for master control.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   340
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   341
  \end{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   342
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   343
\item Virtual read-only network interface for monitoring and debugging
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   344
  purposes.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   345
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   346
\end{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   347
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   348
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   349
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   350
\section{License}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   351
\label{sec:license}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   352
1275
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
   353
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
   354
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
   355
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
   356
even participate on development.
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
   357
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
   358
To allow static linking of userspace application against the master's
1289
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
   359
application interface (see chap.~\ref{chap:api}), the userspace library (see
1275
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
   360
sec.~\ref{sec:userlib}) is licensed under the terms and conditions of the GNU
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
   361
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
   362
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   363
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   364
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   365
\chapter{Architecture}
1299
dd8e55d97280 Userlib.
Florian Pose <fp@igh-essen.com>
parents: 1298
diff changeset
   366
\label{chap:arch}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   367
\index{Master!Architecture}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   368
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   369
The EtherCAT master is integrated into the Linux 2.6 kernel. This was
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   370
an early design decision, which has been made for several reasons:
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   371
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   372
\begin{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   373
1306
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   374
\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
   375
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
   376
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
   377
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
   378
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
   379
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
   380
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   381
\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
   382
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
   383
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
   384
master code being in kernelspace.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   385
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   386
\end{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   387
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   388
Figure~\ref{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
   389
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   390
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   391
  \centering
1588
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
   392
  \includegraphics[width=\textwidth]{images/architecture}
1291
9ce46c40a023 Userspace applications.
Florian Pose <fp@igh-essen.com>
parents: 1289
diff changeset
   393
  \caption{Master Architecture}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   394
  \label{fig:arch}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   395
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   396
1291
9ce46c40a023 Userspace applications.
Florian Pose <fp@igh-essen.com>
parents: 1289
diff changeset
   397
The components of the master environment are described below:
9ce46c40a023 Userspace applications.
Florian Pose <fp@igh-essen.com>
parents: 1289
diff changeset
   398
9ce46c40a023 Userspace applications.
Florian Pose <fp@igh-essen.com>
parents: 1289
diff changeset
   399
\begin{description}
9ce46c40a023 Userspace applications.
Florian Pose <fp@igh-essen.com>
parents: 1289
diff changeset
   400
9ce46c40a023 Userspace applications.
Florian Pose <fp@igh-essen.com>
parents: 1289
diff changeset
   401
\item[Master Module]\index{Master Module} Kernel module containing one or more
9ce46c40a023 Userspace applications.
Florian Pose <fp@igh-essen.com>
parents: 1289
diff changeset
   402
EtherCAT master instances (see sec.~\ref{sec:mastermod}), the ``Device
9ce46c40a023 Userspace applications.
Florian Pose <fp@igh-essen.com>
parents: 1289
diff changeset
   403
Interface'' (see sec.~\ref{sec:ecdev}) and the ``Application Interface'' (see
9ce46c40a023 Userspace applications.
Florian Pose <fp@igh-essen.com>
parents: 1289
diff changeset
   404
chap.~\ref{chap:api}).
9ce46c40a023 Userspace applications.
Florian Pose <fp@igh-essen.com>
parents: 1289
diff changeset
   405
9ce46c40a023 Userspace applications.
Florian Pose <fp@igh-essen.com>
parents: 1289
diff changeset
   406
\item[Device Modules]\index{Device modules} EtherCAT-capable Ethernet device
9ce46c40a023 Userspace applications.
Florian Pose <fp@igh-essen.com>
parents: 1289
diff changeset
   407
driver modules\index{Device modules}, that offer their devices to the EtherCAT
9ce46c40a023 Userspace applications.
Florian Pose <fp@igh-essen.com>
parents: 1289
diff changeset
   408
master via the device interface (see sec.~\ref{sec:ecdev}). These modified
9ce46c40a023 Userspace applications.
Florian Pose <fp@igh-essen.com>
parents: 1289
diff changeset
   409
network drivers can handle network devices used for EtherCAT operation and
9ce46c40a023 Userspace applications.
Florian Pose <fp@igh-essen.com>
parents: 1289
diff changeset
   410
``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
   411
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
   412
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
   413
usual.
9ce46c40a023 Userspace applications.
Florian Pose <fp@igh-essen.com>
parents: 1289
diff changeset
   414
9ce46c40a023 Userspace applications.
Florian Pose <fp@igh-essen.com>
parents: 1289
diff changeset
   415
\item[Application]\index{Application} A program that uses the EtherCAT master
9ce46c40a023 Userspace applications.
Florian Pose <fp@igh-essen.com>
parents: 1289
diff changeset
   416
(usually for cyclic exchange of process data with EtherCAT slaves). These
9ce46c40a023 Userspace applications.
Florian Pose <fp@igh-essen.com>
parents: 1289
diff changeset
   417
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
   418
some examples provided in the \textit{examples/} directory.}, but have to be
9ce46c40a023 Userspace applications.
Florian Pose <fp@igh-essen.com>
parents: 1289
diff changeset
   419
generated or written by the user. An application can ``request'' a master
9ce46c40a023 Userspace applications.
Florian Pose <fp@igh-essen.com>
parents: 1289
diff changeset
   420
through the application interface (see chap.~\ref{chap:api}). If this
9ce46c40a023 Userspace applications.
Florian Pose <fp@igh-essen.com>
parents: 1289
diff changeset
   421
succeeds, it has the control over the master: It can provide a bus
9ce46c40a023 Userspace applications.
Florian Pose <fp@igh-essen.com>
parents: 1289
diff changeset
   422
configuration and exchange process data.  Applications can be kernel modules
9ce46c40a023 Userspace applications.
Florian Pose <fp@igh-essen.com>
parents: 1289
diff changeset
   423
(that use the kernel application interface directly) or userspace programs,
9ce46c40a023 Userspace applications.
Florian Pose <fp@igh-essen.com>
parents: 1289
diff changeset
   424
that use the application interface via the EtherCAT library (see
9ce46c40a023 Userspace applications.
Florian Pose <fp@igh-essen.com>
parents: 1289
diff changeset
   425
sec.~\ref{sec:userlib}).
9ce46c40a023 Userspace applications.
Florian Pose <fp@igh-essen.com>
parents: 1289
diff changeset
   426
9ce46c40a023 Userspace applications.
Florian Pose <fp@igh-essen.com>
parents: 1289
diff changeset
   427
\end{description}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   428
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   429
%------------------------------------------------------------------------------
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   430
1306
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   431
\section{Master Module}
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   432
\label{sec:mastermod}
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   433
\index{Master module}
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   434
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   435
The EtherCAT master kernel module \textit{ec\_master} can contain multiple
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   436
master instances. Each master waits for a certain Ethernet device identified
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   437
by its MAC address\index{MAC address}. These addresses have to be specified on
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   438
module loading via the \textit{main\_devices} module parameter. The number of
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   439
master instances to initialize is taken from the number of MAC addresses
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   440
given.
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   441
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   442
The below command loads the master module with a single master instance that
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   443
waits for the Ethernet device with the MAC address
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   444
\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
   445
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   446
\begin{lstlisting}
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   447
# `\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
   448
\end{lstlisting}
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
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
   451
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   452
\begin{lstlisting}
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   453
# `\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
   454
\end{lstlisting}
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
The two masters can be addressed by their indices 0 and 1 respectively (see
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   457
figure~\ref{fig:masters}). The master index is needed for the
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   458
\lstinline+ecrt_master_request()+ function of the application interface (see
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   459
chap.~\ref{chap:api}) and the \lstinline+--master+ option of the
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   460
\textit{ethercat} command-line tool (see sec.~\ref{sec:tool}), which defaults
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   461
to $0$.
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   462
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   463
\begin{figure}[htbp]
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   464
  \centering
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   465
  \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
   466
  \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
   467
  \label{fig:masters}
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   468
\end{figure}
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   469
1399
f79d4bb5b23a Added debug_level module parameter. debug_level is now unsigned int.
Florian Pose <fp@igh-essen.com>
parents: 1364
diff changeset
   470
\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
   471
\textit{debug\_level} to set the initial debug level for all masters (see
f79d4bb5b23a Added debug_level module parameter. debug_level is now unsigned int.
Florian Pose <fp@igh-essen.com>
parents: 1364
diff changeset
   472
also~\ref{sec:ethercat-debug}).
f79d4bb5b23a Added debug_level module parameter. debug_level is now unsigned int.
Florian Pose <fp@igh-essen.com>
parents: 1364
diff changeset
   473
1306
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   474
\paragraph{Init Script}
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   475
\index{Init script}
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   476
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   477
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
   478
driver modules manually. There is an init script available, so the master can
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   479
be started as a service (see sec.~\ref{sec:system}).
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
\paragraph{Syslog}
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   482
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   483
The master module outputs information about its state and events to the kernel
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   484
ring buffer. These also end up in the system logs.  The above module loading
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   485
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
   486
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   487
\begin{lstlisting}
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   488
# `\textbf{dmesg | tail -2}`
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   489
EtherCAT: Master driver `\masterversion`
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   490
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
   491
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   492
# `\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
   493
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
   494
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
   495
                                 for devices.
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   496
\end{lstlisting}
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   497
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   498
All EtherCAT master output is prefixed with \lstinline+EtherCAT+ which makes
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   499
searching the logs easier.
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   500
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   501
%------------------------------------------------------------------------------
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   502
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   503
\section{Master Phases}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   504
\index{Master phases}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   505
1306
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   506
Every EtherCAT master provided by the master module (see
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   507
sec.~\ref{sec:mastermod}) runs through several phases (see
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
   508
fig.~\ref{fig:phases}):
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   509
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   510
\begin{figure}[htbp]
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   511
  \centering
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   512
  \includegraphics[width=.9\textwidth]{images/phases}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   513
  \caption{Master phases and transitions}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   514
  \label{fig:phases}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   515
\end{figure}
1291
9ce46c40a023 Userspace applications.
Florian Pose <fp@igh-essen.com>
parents: 1289
diff changeset
   516
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   517
\begin{description}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   518
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   519
\item[Orphaned phase]\index{Orphaned phase} This mode takes effect, when the
1086
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   520
master still waits for its Ethernet device to connect. No bus communication is
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   521
possible until then.
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   522
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   523
\item[Idle phase]\index{Idle phase} takes effect when the master has accepted
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   524
an Ethernet device, but is not requested by any application yet. The master
1289
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
   525
runs its state machine (see sec.~\ref{sec:fsm-master}), that automatically
1275
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
   526
scans the bus for slaves and executes pending operations from the userspace
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
   527
interface (for example SDO access). The command-line tool can be used to
1275
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
   528
access the bus, but there is no process data exchange because of the missing
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
   529
bus configuration.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   530
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   531
\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
   532
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
   533
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   534
\end{description}
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
%------------------------------------------------------------------------------
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   537
1293
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   538
\section{Process Data}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   539
\label{sec:processdata}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   540
1293
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   541
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
   542
process data.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   543
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   544
\paragraph{Process Data Image}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   545
\index{Process data}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   546
1293
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   547
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
   548
``Process Data Objects'' (PDOs\index{PDO}). The available PDOs can be either
1293
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   549
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
   550
E$^2$PROM (in case of fixed PDOs) or by reading out the appropriate CoE
1293
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   551
objects (see sec.~\ref{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
   552
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
   553
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
   554
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
   555
in~\cite[sec.~5.4]{dlspec}.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   556
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   557
\paragraph{Process Data Domains}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   558
\index{Domain}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   559
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   560
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
   561
``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
   562
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
   563
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
   564
for the following reasons:
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   565
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   566
\begin{itemize}
1293
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   567
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   568
\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
   569
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
   570
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
   571
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
   572
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
   573
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
   574
automatically.
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   575
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
   576
\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
   577
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
   578
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
   579
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
   580
exchange.
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   581
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   582
\end{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   583
1293
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   584
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
   585
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
   586
limited by the slaves.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   587
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   588
\paragraph{FMMU Configuration}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   589
\index{FMMU!Configuration}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   590
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
   591
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
   592
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
   593
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
   594
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
   595
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
   596
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
   597
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
   598
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
   599
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
   600
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
   601
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
   602
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
   603
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
   604
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
   605
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
   606
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
   607
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   608
Figure~\ref{fig:fmmus} gives an overview, how FMMUs are configured to map
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   609
physical memory to logical process data images.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   610
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   611
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   612
  \centering
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   613
  \includegraphics[width=\textwidth]{images/fmmus}
1293
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   614
  \caption{FMMU Configuration}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   615
  \label{fig:fmmus}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   616
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   617
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   618
%------------------------------------------------------------------------------
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   619
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   620
\chapter{Application Interface}
1289
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
   621
\label{chap:api}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   622
\index{Application interface}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   623
1297
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
   624
% TODO
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
   625
%
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
   626
% Interface version
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
   627
% Master Requesting and Releasing
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
   628
% 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
   629
% Configuring PDO assignment and mapping
1297
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
   630
% 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
   631
% 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
   632
% SDO configuration
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
   633
% SDO access
1917
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
   634
% IDN configurations
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
   635
% IDN access
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   636
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   637
The application interface provides functions and data structures for
1292
ea1bcfb8d631 Avouded 'you'.
Florian Pose <fp@igh-essen.com>
parents: 1291
diff changeset
   638
applications to access an EtherCAT master. The complete documentation of the
ea1bcfb8d631 Avouded 'you'.
Florian Pose <fp@igh-essen.com>
parents: 1291
diff changeset
   639
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
   640
\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
   641
comments, or as a more comfortable HTML documentation. The HTML generation is
1292
ea1bcfb8d631 Avouded 'you'.
Florian Pose <fp@igh-essen.com>
parents: 1291
diff changeset
   642
described in sec.~\ref{sec:gendoc}.
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   643
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   644
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
   645
interface.
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   646
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   647
Every application should use the master in two steps:
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
\begin{description}
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   650
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   651
\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
   652
For example, domains are created, slaves are configured and PDO entries are
1293
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   653
registered (see sec.~\ref{sec:masterconfig}).
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   654
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   655
\item[Operation] Cyclic code is run and process data are exchanged (see
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   656
sec.~\ref{sec:cyclic}).
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   657
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   658
\end{description}
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   659
1293
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   660
\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
   661
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
   662
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
   663
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   664
%------------------------------------------------------------------------------
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   665
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   666
\section{Master Configuration}
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   667
\label{sec:masterconfig}
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   668
1293
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   669
The bus configuration is supplied via the application interface.
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   670
Figure~\ref{fig:app-config} gives an overview of the objects, that can be
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   671
configured by the application.
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   672
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   673
\begin{figure}[htbp]
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   674
  \centering
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   675
  \includegraphics[width=.8\textwidth]{images/app-config}
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
   676
  \caption{Master Configuration}
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   677
  \label{fig:app-config}
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   678
\end{figure}
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   679
1293
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   680
\subsection{Slave Configuration}
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   681
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   682
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
   683
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
   684
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
   685
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
   686
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   687
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
   688
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
   689
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
   690
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
   691
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
   692
application interface or via the command-line tool (see
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   693
sec.~\ref{sec:ethercat-config}).
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   694
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   695
\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
   696
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
   697
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
   698
of both. The alias is a 16-bit value stored in the slave's E$^2$PROM. It can
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   699
be modified via the command-line tool (see sec.~\ref{sec:ethercat-alias}).
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   700
Table~\ref{tab:slaveposition} shows, how the values are interpreted.
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   701
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   702
\begin{table}[htbp]
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   703
  \centering
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   704
  \caption{Specifying a Slave Position}
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   705
  \label{tab:slaveposition}
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   706
  \vspace{2mm}
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   707
  \begin{tabular}{c|c|p{70mm}}
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   708
    Alias & Position & Interpretation\\
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   709
    \hline
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   710
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   711
    \lstinline+0+ & \lstinline+0+ -- \lstinline+65535+ &
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   712
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   713
    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
   714
    ring position in the bus.\\ \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+1+ -- \lstinline+65535+ & \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
    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
   719
    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
   720
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   721
  \end{tabular}
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   722
\end{table}
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   723
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   724
Figure~\ref{fig:attach} shows an example of how slave configurations are
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   725
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
   726
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
   727
configuration.
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   728
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   729
\begin{figure}[htbp]
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   730
  \centering
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   731
  \includegraphics[width=.7\textwidth]{images/attach}
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   732
  \caption{Slave Configuration Attachment}
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   733
  \label{fig:attach}
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   734
\end{figure}
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   735
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   736
\begin{enumerate}
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   737
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   738
\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
   739
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
   740
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   741
\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
   742
match, so the configuration is not attached.
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   743
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   744
\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
   745
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
   746
same slave is used.
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   747
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   748
\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
   749
attached.
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   750
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   751
\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
   752
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
   753
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   754
\end{enumerate}
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   755
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   756
%------------------------------------------------------------------------------
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   757
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   758
\section{Cyclic Operation}
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   759
\label{sec:cyclic}
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   760
1293
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   761
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   762
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
   763
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
   764
time. After activation, the application is in charge to send and receive
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   765
frames.
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
   766
1297
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
   767
% TODO
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
   768
%
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
   769
% PDO endianess
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
   770
% Datagram injection
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   771
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   772
%------------------------------------------------------------------------------
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   773
1298
de91d633ff6c VoE handlers.
Florian Pose <fp@igh-essen.com>
parents: 1297
diff changeset
   774
\section{VoE Handlers}
de91d633ff6c VoE handlers.
Florian Pose <fp@igh-essen.com>
parents: 1297
diff changeset
   775
\label{sec:api-voe}
de91d633ff6c VoE handlers.
Florian Pose <fp@igh-essen.com>
parents: 1297
diff changeset
   776
de91d633ff6c VoE handlers.
Florian Pose <fp@igh-essen.com>
parents: 1297
diff changeset
   777
During the configuration phase, the application can create handlers for the
de91d633ff6c VoE handlers.
Florian Pose <fp@igh-essen.com>
parents: 1297
diff changeset
   778
VoE mailbox protocol described in sec.~\ref{sec:voe}. One VoE handler always
de91d633ff6c VoE handlers.
Florian Pose <fp@igh-essen.com>
parents: 1297
diff changeset
   779
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
   780
of the slave configuration.
de91d633ff6c VoE handlers.
Florian Pose <fp@igh-essen.com>
parents: 1297
diff changeset
   781
de91d633ff6c VoE handlers.
Florian Pose <fp@igh-essen.com>
parents: 1297
diff changeset
   782
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
   783
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
   784
messages.
de91d633ff6c VoE handlers.
Florian Pose <fp@igh-essen.com>
parents: 1297
diff changeset
   785
de91d633ff6c VoE handlers.
Florian Pose <fp@igh-essen.com>
parents: 1297
diff changeset
   786
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
   787
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
   788
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
   789
for the slave configuration.}. After the operation is initiated, the handler
de91d633ff6c VoE handlers.
Florian Pose <fp@igh-essen.com>
parents: 1297
diff changeset
   790
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
   791
the operation can be retrieved.
de91d633ff6c VoE handlers.
Florian Pose <fp@igh-essen.com>
parents: 1297
diff changeset
   792
de91d633ff6c VoE handlers.
Florian Pose <fp@igh-essen.com>
parents: 1297
diff changeset
   793
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
   794
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
   795
execute before sending the corresponding EtherCAT frame(s).
de91d633ff6c VoE handlers.
Florian Pose <fp@igh-essen.com>
parents: 1297
diff changeset
   796
de91d633ff6c VoE handlers.
Florian Pose <fp@igh-essen.com>
parents: 1297
diff changeset
   797
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
   798
the application interface functions and the example applications provided in
de91d633ff6c VoE handlers.
Florian Pose <fp@igh-essen.com>
parents: 1297
diff changeset
   799
the \textit{examples/} directory.
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
%------------------------------------------------------------------------------
de91d633ff6c VoE handlers.
Florian Pose <fp@igh-essen.com>
parents: 1297
diff changeset
   802
1294
b08eb1ffa6dd Fixed missing paren.
Florian Pose <fp@igh-essen.com>
parents: 1293
diff changeset
   803
\section{Concurrent Master Access}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   804
\label{sec:concurr}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   805
\index{Concurrency}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   806
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   807
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
   808
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
   809
slaves that require to exchange Ethernet data with the kernel (see
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
   810
sec.~\ref{sec:eoe}). For this reason, the master is a shared resource, and
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
   811
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
   812
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
   813
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   814
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
   815
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
   816
kernelspace and uses RTAI functionality, ordinary kernel semaphores would not
9ce46c40a023 Userspace applications.
Florian Pose <fp@igh-essen.com>
parents: 1289
diff changeset
   817
be sufficient. For that, an important design decision was made: The
9ce46c40a023 Userspace applications.
Florian Pose <fp@igh-essen.com>
parents: 1289
diff changeset
   818
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
   819
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
   820
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
   821
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
   822
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
   823
at the moment.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   824
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   825
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   826
  \centering
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   827
  \includegraphics[width=.6\textwidth]{images/master-locks}
1295
4627823c2e8f Capital.
Florian Pose <fp@igh-essen.com>
parents: 1294
diff changeset
   828
  \caption{Concurrent Master Access}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   829
  \label{fig:locks}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   830
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   831
1204
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
   832
Figure~\ref{fig:locks} exemplary shows, how two processes share one master:
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
   833
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
   834
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
   835
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
   836
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
   837
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
   838
accessing the bus at the same time. See the application interface
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   839
documentation (chap.~\ref{chap:api}) for how to use these callbacks.
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   840
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   841
%------------------------------------------------------------------------------
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   842
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   843
\section{Distributed Clocks}
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   844
\label{sec:dc}
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   845
\index{Distributed Clocks}
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   846
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   847
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
   848
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
   849
``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
   850
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
   851
is the local clock of the master). All other clocks on the bus (after the
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   852
reference clock) are considered as ``slave clocks'' (see fig.~\ref{fig:dc}).
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   853
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   854
\begin{figure}[htbp]
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   855
  \centering
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   856
  \includegraphics[width=.8\textwidth]{images/dc}
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   857
  \caption{Distributed Clocks}
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   858
  \label{fig:dc}
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   859
\end{figure}
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   860
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   861
\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
   862
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
   863
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
   864
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
   865
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
   866
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
   867
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
   868
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
   869
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
   870
mechanism.
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   871
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   872
\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
   873
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
   874
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   875
\begin{enumerate}
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   876
\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
   877
\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
   878
below).
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   879
\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
   880
\end{enumerate}
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   881
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   882
\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
   883
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
   884
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
   885
$t_\text{sys}$:
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   886
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   887
\begin{eqnarray}
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   888
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
   889
\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
   890
\end{eqnarray}
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   891
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   892
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
   893
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
   894
application time $t_\text{app}$:
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   895
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   896
\begin{eqnarray}
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   897
t_\text{sys} & \stackrel{!}{=} & t_\text{app} \\
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   898
\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
   899
\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
   900
\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
   901
\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
   902
\end{eqnarray}
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
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
   905
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
   906
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   907
\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
   908
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
   909
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
   910
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
   911
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
   912
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
   913
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
   914
\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
   915
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
   916
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   917
\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
   918
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
   919
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
   920
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
   921
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
   922
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
   923
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
   924
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
   925
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
   926
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
   927
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
   928
each slave. These values are programmed into the slaves' transmission delay
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   929
registers. In this way, the drift compensation can reach nanosecond synchrony. 
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   930
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   931
\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
   932
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
   933
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
   934
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
   935
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
   936
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
   937
registers can also be cyclically read via the command-line-tool (see
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   938
sec.~\ref{sec:regaccess}):
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   939
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   940
\begin{lstlisting}
1917
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
   941
$ `\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
   942
\end{lstlisting}
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   943
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
   944
\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
   945
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
   946
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
   947
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
   948
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
   949
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
   950
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
   951
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
   952
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
   953
\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
   954
be found.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   955
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   956
%------------------------------------------------------------------------------
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   957
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   958
\chapter{Ethernet Devices}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   959
\label{sec:devices}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   960
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
   961
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
   962
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
   963
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   964
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
   965
hardware.
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
   966
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
   967
\paragraph{Native Ethernet Device Drivers} There are native device driver
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
   968
modules (see sec.~\ref{sec:native-drivers}) that handle Ethernet hardware,
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
   969
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
   970
Ethernet hardware to the master module via the device interface (see
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
   971
sec.~\ref{sec:ecdev}) and must be capable to prepare Ethernet devices either
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
   972
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
   973
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
   974
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
   975
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
   976
original Ethernet driver.
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
   977
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
   978
\paragraph{Generic Ethernet Device Driver} From master version 1.5, there is a
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
   979
generic Ethernet device driver module (see sec.~\ref{sec:generic-driver}),
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
   980
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
   981
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
   982
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
   983
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
   984
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
   985
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
   986
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
   987
network stack.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   988
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   989
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   990
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   991
\section{Network Driver Basics}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   992
\label{sec:networkdrivers}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   993
\index{Network drivers}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   994
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   995
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
   996
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
   997
to understand how Linux handles network devices and their drivers,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   998
respectively.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   999
1588
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1000
\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
  1001
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
  1002
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
  1003
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
  1004
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
  1005
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
  1006
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
  1007
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
  1008
(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
  1009
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
  1010
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
  1011
device dependent features.
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1012
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1013
\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
  1014
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
  1015
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
  1016
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
  1017
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1018
\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
  1019
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
  1020
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
  1021
register an interrupt service routine
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1022
(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
  1023
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
  1024
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
  1025
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
  1026
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
  1027
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
  1028
stack.
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1029
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1030
\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
  1031
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
  1032
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
  1033
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
  1034
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
  1035
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
  1036
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
  1037
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
  1038
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1039
\newsavebox\boxopen
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1040
\sbox\boxopen{\lstinline+open()+}
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1041
\newsavebox\boxstop
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1042
\sbox\boxstop{\lstinline+stop()+}
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1043
\newsavebox\boxxmit
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1044
\sbox\boxxmit{\lstinline+hard_start_xmit()+}
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1045
\newsavebox\boxstats
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1046
\sbox\boxstats{\lstinline+get_stats()+}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1047
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1048
\begin{description}
1095
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  1049
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1050
\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
  1051
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
  1052
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
  1053
1297
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
  1054
\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
  1055
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
  1056
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1057
\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
  1058
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
  1059
\lstinline+sk_buff+ structure (``socket buffer''\index{Socket buffer}, see
1095
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  1060
below), which has to be freed after sending.
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  1061
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1062
\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
  1063
\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
  1064
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
  1065
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
  1066
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  1067
\end{description}
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  1068
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  1069
The actual registration is done with the \lstinline+register_netdev()+ call,
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  1070
unregistering is done with \lstinline+unregister_netdev()+.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1071
1588
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1072
\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
  1073
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
  1074
\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
  1075
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
  1076
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
  1077
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
  1078
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
  1079
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
  1080
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
  1081
\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
  1082
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
  1083
\lstinline+netif_wake_queue()+. Another important call is
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  1084
\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
  1085
(``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
  1086
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
  1087
network performance on Linux. Read more in
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  1088
\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
  1089
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
  1090
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
  1091
1588
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1092
\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
  1093
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
  1094
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
  1095
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
  1096
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
  1097
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
  1098
(\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
  1099
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
  1100
\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
  1101
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
  1102
(\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
  1103
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
  1104
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
  1105
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
  1106
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
  1107
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1108
%------------------------------------------------------------------------------
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1109
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1110
\section{Native EtherCAT Device Drivers}
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1111
\label{sec:native-drivers}
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1112
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1113
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
  1114
a native Ethernet driver with EtherCAT functionality.
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
\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
  1117
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
  1118
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
  1119
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
  1120
Ethernet device.
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1121
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1122
\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
  1123
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
  1124
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
  1125
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
  1126
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
  1127
frames, if it expects them to be already received.
1095
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  1128
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  1129
Figure~\ref{fig:interrupt} shows two workflows for cyclic frame transmission
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  1130
and reception with and without interrupts.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1131
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1132
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1133
  \centering
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1134
  \includegraphics[width=.9\textwidth]{images/interrupt}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1135
  \caption{Interrupt Operation versus Interrupt-less Operation}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1136
  \label{fig:interrupt}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1137
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1138
1095
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  1139
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
  1140
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
  1141
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
  1142
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
  1143
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
  1144
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
  1145
processing in the next cycle.
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  1146
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  1147
In the right workflow ``Interrupt-less Operation'', there is no hardware
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  1148
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
  1149
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
  1150
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
  1151
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
  1152
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
  1153
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1154
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
  1155
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
  1156
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
  1157
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
  1158
prioritize interrupts.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1159
1588
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1160
\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
  1161
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
  1162
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
  1163
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
  1164
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
  1165
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
  1166
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
  1167
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
  1168
ordinary Ethernet device.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1169
1095
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  1170
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
  1171
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
  1172
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
  1173
EtherCAT-capable.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1174
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1175
Below are the advantages of this solution:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1176
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1177
\begin{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1178
\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
  1179
\item One networking driver for EtherCAT and non-EtherCAT devices.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1180
\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
  1181
  into issues, the former developers already solved.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1182
\end{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1183
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1184
The chosen approach has the following disadvantages:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1185
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1186
\begin{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1187
\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
  1188
  EtherCAT and non-EtherCAT devices.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1189
\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
  1190
\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
  1191
  to the Ether\-CAT-capable versions from time to time.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1192
\end{itemize}
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
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1195
1588
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1196
\section{Generic EtherCAT Device Driver}
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1197
\label{sec:generic-driver}
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1198
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1199
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
  1200
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
  1201
implementations of EtherCAT-capable Ethernet device drivers and use the Linux
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1202
network stack instead. Fig.~\ref{fig:arch} shows the ``Generic Ethernet Driver
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1203
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
  1204
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
  1205
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
  1206
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1207
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
  1208
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
  1209
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
  1210
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
  1211
\lstinline+socket_type+ set to \lstinline+SOCK_RAW+, bound to that device. All
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1212
functions of the device interface (see sec.~\ref{sec:ecdev}) will then operate
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1213
on that socket.
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
Below are the advantages of this solution:
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1216
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1217
\begin{itemize}
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1218
\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
  1219
used for EtherCAT.
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1220
\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
  1221
\end{itemize}
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
The generic approach has the following disadvantages:
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 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
  1227
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
  1228
\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
  1229
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
  1230
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
  1231
realtime context.
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1232
\end{itemize}
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1233
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1234
%------------------------------------------------------------------------------
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1235
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1236
\section{Providing Ethernet Devices}
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1237
\label{sec:providing-devices}
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1238
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1239
After loading the master module, additional module(s) have to be loaded to
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1240
offer devices to the master(s) (see sec.~\ref{sec:ecdev}). The master module
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1241
knows the devices to choose from the module parameters (see
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1242
sec.~\ref{sec:mastermod}). If the init script is used to start the master, the
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1243
drivers and devices to use can be specified in the sysconfig file (see
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1244
sec.~\ref{sec:sysconfig}).
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1245
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1246
Modules offering Ethernet devices can be
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1247
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1248
\begin{itemize}
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1249
\item native EtherCAT-capable network driver modules (see
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1250
sec.~\ref{sec:native-drivers}) or
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1251
\item the generic EtherCAT device driver module (see
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1252
sec.~\ref{sec:generic-driver}).
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1253
\end{itemize}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1254
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1255
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1256
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1257
\section{EtherCAT Device Interface}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1258
\label{sec:ecdev}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1259
\index{Device interface}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1260
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1261
An anticipation to the section about the master module
1289
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  1262
(sec.~\ref{sec:mastermod}) has to be made in order to understand the way, a
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  1263
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
  1264
master.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1265
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1266
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
  1267
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
  1268
\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
  1269
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
  1270
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
  1271
\lstinline+ecdev+.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1272
1289
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  1273
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
  1274
in the appropriate module of the interface documentation (see
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  1275
sec.~\ref{sec:gendoc} for generation instructions).
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1276
1296
69582b88e8fd Removed ldots
Florian Pose <fp@igh-essen.com>
parents: 1295
diff changeset
  1277
% TODO general description of the device interface
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1278
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1279
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1280
1588
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1281
\section{Patching Native Network Drivers}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1282
\label{sec:patching}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1283
\index{Network drivers}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1284
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1285
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
  1286
EtherCAT-capable, using the native approach (see
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1287
sec.~\ref{sec:native-drivers}). Unfortunately, there is no standard procedure
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  1288
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
  1289
few common techniques.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1290
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1291
\begin{enumerate}
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1292
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1293
\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
  1294
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
  1295
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
  1296
functions.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1297
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1298
\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
  1299
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
  1300
interrupts at hardware level must be avoided, too.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1301
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1302
\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
  1303
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
  1304
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
  1305
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
  1306
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
  1307
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1308
\end{enumerate}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1309
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1310
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
  1311
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
  1312
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
  1313
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
  1314
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
  1315
\lstinline+ec_device_t+ object returned by \lstinline+ecdev_offer()+ (see
1289
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  1316
sec.~\ref{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
  1317
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1318
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
  1319
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
  1320
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
  1321
\textit{devices/8139too-2.6.24-ethercat.c}.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1322
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1323
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1324
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1325
\chapter{State Machines}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1326
\label{sec:fsm}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1327
\index{FSM}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1328
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1329
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
  1330
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
  1331
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
  1332
possibilities.
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
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
  1335
states and moreover illustrates the restrictions of ``sequential''
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1336
coding:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1337
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1338
\begin{lstlisting}[gobble=2,language=C,numbers=left]
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1339
  ec_datagram_brd(datagram, 0x0130, 2); // prepare datagram
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1340
  if (ec_master_simple_io(master, datagram)) return -1;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1341
  slave_states = EC_READ_U8(datagram->data); // process datagram
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1342
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1343
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1344
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
  1345
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
  1346
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
  1347
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
  1348
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
  1349
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
  1350
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
  1351
1289
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  1352
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
  1353
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
  1354
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
  1355
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
  1356
time, synchronous master access will be adequate to show the advantages of an
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  1357
FSM. The asynchronous approach will be discussed in sec.~\ref{sec:eoe}}) use
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  1358
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
  1359
model.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1360
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1361
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
  1362
wanting to send and receive datagrams synchronously. With the present
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1363
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
  1364
each instance, which would be non-acceptable especially in realtime
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1365
circumstances, because of the huge time overhead.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1366
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1367
A possible solution is, that all instances would be executed
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1368
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
  1369
next instance instead of waiting for the datagram reception. Finally,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1370
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
  1371
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
  1372
instances again, which then process their received datagrams and issue
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1373
new ones.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1374
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1375
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
  1376
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
  1377
obvious to use a \textit{finite state machine} model in this case.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1378
Section~\ref{sec:fsmtheory} will introduce some of the theory used,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1379
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
  1380
from above as a state machine:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1381
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1382
\begin{lstlisting}[gobble=2,language=C,numbers=left]
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1383
  // state 1
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1384
  ec_datagram_brd(datagram, 0x0130, 2); // prepare datagram
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1385
  ec_master_queue(master, datagram); // queue datagram
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1386
  next_state = state_2;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1387
  // state processing finished
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1388
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1389
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1390
After all instances executed their current state and queued their
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1391
datagrams, these are sent and received. Then the respective next
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1392
states are executed:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1393
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1394
\begin{lstlisting}[gobble=2,language=C,numbers=left]
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1395
  // state 2
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1396
  if (datagram->state != EC_DGRAM_STATE_RECEIVED) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1397
          next_state = state_error;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1398
          return; // state processing finished
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1399
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1400
  slave_states = EC_READ_U8(datagram->data); // process datagram
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1401
  // state processing finished.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1402
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1403
1289
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  1404
See sec.~\ref{sec:statemodel} for an introduction to the state machine
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  1405
programming concept used in the master code.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1406
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1407
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1408
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1409
\section{State Machine Theory}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1410
\label{sec:fsmtheory}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1411
\index{FSM!Theory}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1412
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1413
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
  1414
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
  1415
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
  1416
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
  1417
S, s_0, \delta, \omega)$, with
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1418
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1419
\begin{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1420
\item the input alphabet $\Sigma$, with $\Sigma \neq
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1421
  \emptyset$, containing all input symbols,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1422
\item the output alphabet $\Gamma$, with $\Gamma \neq
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1423
  \emptyset$, containing all output symbols,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1424
\item the set of states $S$, with $S \neq \emptyset$,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1425
\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
  1426
  \emptyset$
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1427
\item the transition function $\delta: S \times \Sigma \rightarrow S
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1428
  \times \Gamma$
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1429
\item the output function $\omega$.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1430
\end{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1431
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1432
The state transition function $\delta$ is often specified by a
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1433
\textit{state transition table}, or by a \textit{state transition
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1434
  diagram}. The transition table offers a matrix view of the state
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1435
machine behavior (see table~\ref{tab:statetrans}). The matrix rows
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1436
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
  1437
correspond to the input symbols ($\Gamma = \{a, b, \varepsilon\}$).
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1438
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
  1439
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
  1440
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
  1441
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1442
\begin{table}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1443
  \caption{A typical state transition table}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1444
  \label{tab:statetrans}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1445
  \vspace{2mm}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1446
  \centering
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1447
  \begin{tabular}{l|ccc}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1448
    & $a$ & $b$ & $\varepsilon$\\ \hline
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1449
    $s_0$ & $s_1$ & $s_1$ & $s_2$\\
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1450
    $s_1$ & $s_2$ & $s_1$ & $s_0$\\
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1451
    $s_2$ & $s_0$ & $s_0$ & $s_0$\\ \hline
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1452
  \end{tabular}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1453
\end{table}
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
The state diagram for the same example looks like the one in
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1456
figure~\ref{fig:statetrans}. The states are represented as circles or
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1457
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
  1458
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
  1459
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
  1460
circle with an arrow pointing to the respective state.
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
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1463
  \centering
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1464
  \includegraphics[width=.5\textwidth]{images/statetrans}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1465
  \caption{A typical state transition diagram}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1466
  \label{fig:statetrans}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1467
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1468
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1469
\paragraph{Deterministic and non-deterministic state machines}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1470
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1471
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
  1472
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
  1473
state machine has exactly one starting state. Non-deterministic state
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1474
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
  1475
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
  1476
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1477
\paragraph{Moore and Mealy machines}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1478
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1479
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
  1480
\textit{Mealy machines}. Mathematically spoken, the distinction lies
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1481
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
  1482
state ($\omega: S \rightarrow \Gamma$), the machine corresponds to the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1483
``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
  1484
the input alphabet ($\omega: S \times \Sigma \rightarrow \Gamma$) the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1485
state machine corresponds to the ``Mealy model''. Mealy machines are
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1486
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
  1487
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
  1488
both models is often used.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1489
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1490
\paragraph{Misunderstandings about state machines}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1491
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1492
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
  1493
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
  1494
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
  1495
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
  1496
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
  1497
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
  1498
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
  1499
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
  1500
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1501
%------------------------------------------------------------------------------
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1502
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1503
\section{The Master's State Model}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1504
\label{sec:statemodel}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1505
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1506
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
  1507
implement state machines.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1508
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1509
\paragraph{State Machine Programming}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1510
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1511
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
  1512
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
  1513
by one big case differentiation:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1514
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1515
\begin{lstlisting}[gobble=2,language=C,numbers=left]
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1516
  enum {STATE_1, STATE_2, STATE_3};
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1517
  int state = STATE_1;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1518
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1519
  void state_machine_run(void *priv_data) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1520
          switch (state) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1521
                  case STATE_1:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1522
                          action_1();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1523
                          state = STATE_2;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1524
                          break;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1525
                  case STATE_2:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1526
                          action_2()
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1527
                          if (some_condition) state = STATE_1;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1528
                          else state = STATE_3;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1529
                          break;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1530
                  case STATE_3:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1531
                          action_3();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1532
                          state = STATE_1;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1533
                          break;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1534
          }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1535
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1536
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1537
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1538
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
  1539
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
  1540
additional case differentiation is executed each run. Besides, lots of
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1541
indentation is wasted.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1542
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1543
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
  1544
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
  1545
pointer:
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
\begin{lstlisting}[gobble=2,language=C,numbers=left]
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1548
  void (*state)(void *) = state1;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1549
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1550
  void state_machine_run(void *priv_data) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1551
          state(priv_data);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1552
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1553
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1554
  void state1(void *priv_data) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1555
          action_1();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1556
          state = state2;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1557
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1558
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1559
  void state2(void *priv_data) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1560
          action_2();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1561
          if (some_condition) state = state1;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1562
          else state = state2;
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
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1565
  void state3(void *priv_data) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1566
          action_3();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1567
          state = state1;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1568
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1569
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1570
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1571
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
  1572
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
  1573
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
  1574
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
  1575
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
  1576
available and can be started on demand.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1577
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1578
\paragraph{Mealy and Moore}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1579
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1580
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
  1581
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
  1582
current state. This accords to the ``Moore'' model introduced in
1289
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  1583
sec.~\ref{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
  1584
flexibility, which can be seen in the listing below:
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1585
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1586
\begin{lstlisting}[gobble=2,language=C,numbers=left]
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1587
  void state7(void *priv_data) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1588
          if (some_condition) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1589
                  action_7a();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1590
                  state = state1;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1591
          }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1592
          else {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1593
                  action_7b();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1594
                  state = state8;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1595
          }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1596
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1597
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1598
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1599
\begin{description}
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1600
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1601
\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
  1602
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
  1603
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1604
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1605
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1606
The most flexible alternative is to execute certain actions depending
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1607
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
  1608
transition:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1609
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1610
\begin{lstlisting}[gobble=2,language=C,numbers=left]
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1611
  void state9(void *priv_data) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1612
          action_9();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1613
          if (some_condition) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1614
                  action_9a();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1615
                  state = state7;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1616
          }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1617
          else {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1618
                  action_9b();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1619
                  state = state10;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1620
          }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1621
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1622
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1623
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1624
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
  1625
approaches.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1626
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1627
\paragraph{Using Sub State Machines}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1628
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1629
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
  1630
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
  1631
encapsulate the related workflows and moreover avoids the ``state explosion''
1289
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  1632
phenomenon described in sec.~\ref{sec:fsmtheory}. If the master would instead
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  1633
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
  1634
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
  1635
grade.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1636
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1637
\paragraph{Executing Sub State Machines}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1638
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1639
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
  1640
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
  1641
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
  1642
slave configuration state machine code:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1643
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1644
\begin{lstlisting}[gobble=2,language=C,numbers=left]
813
bfc3f1ab52de Fixed typo SAVEOP -> SAFEOP.
Florian Pose <fp@igh-essen.com>
parents: 487
diff changeset
  1645
  void ec_fsm_slaveconf_safeop(ec_fsm_t *fsm)
369
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
          fsm->change_state(fsm); // execute state change
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1648
                                  // sub state machine
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1649
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1650
          if (fsm->change_state == ec_fsm_error) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1651
                  fsm->slave_state = ec_fsm_end;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1652
                  return;
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
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1655
          if (fsm->change_state != ec_fsm_end) return;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1656
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1657
          // continue state processing
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1658
          ...
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1659
\end{lstlisting}
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
\begin{description}
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1662
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1663
\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
  1664
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
  1665
executed\ldots
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1666
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1667
\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
  1668
error state \ldots
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1669
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1670
\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
  1671
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
  1672
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
  1673
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1674
\end{description}
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
\paragraph{State Machine Descriptions}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1677
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1678
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
  1679
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
  1680
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
  1681
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
  1682
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
  1683
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
  1684
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1685
%------------------------------------------------------------------------------
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1686
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1687
\section{The Master State Machine}
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1688
\label{sec:fsm-master}
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1689
\index{FSM!Master}
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1690
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1691
The master state machine is executed in the context of the master thread.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1692
Figure~\ref{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
  1693
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1694
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1695
  \centering
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1696
  \includegraphics[width=\textwidth]{graphs/fsm_master}
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1697
  \caption{Transition diagram of the master state machine}
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1698
  \label{fig:fsm-master}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1699
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1700
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1701
\begin{description}
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1702
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1703
\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
  1704
(re-)scanned.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1705
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1706
\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
  1707
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
  1708
(re-)configured.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1709
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1710
\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
  1711
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
  1712
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
  1713
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1714
\end{description}
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
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1717
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1718
\section{The Slave Scan State Machine}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1719
\label{sec:fsm-scan}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1720
\index{FSM!Slave Scan}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1721
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1722
The slave scan state machine, which can be seen in
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1723
figure~\ref{fig:fsm-slavescan}, leads through the process of reading desired
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1724
slave information.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1725
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1726
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1727
  \centering
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1728
  \includegraphics[height=.8\textheight]{graphs/fsm_slave_scan}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1729
  \caption{Transition diagram of the slave scan state machine}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1730
  \label{fig:fsm-slavescan}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1731
\end{figure}
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 scan process includes the following steps:
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1734
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1735
\begin{description}
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1736
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1737
\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
  1738
node-addressed for all following operations.
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
\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
  1741
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1742
\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
  1743
is read from the lower physical memory.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1744
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1745
\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
  1746
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1747
\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
  1748
image memory.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1749
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1750
\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
  1751
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1752
\item[PREOP] If the slave supports CoE, it is set to PREOP state using the
1289
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  1753
State change FSM (see sec.~\ref{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
  1754
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
  1755
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  1756
\item[PDOs] The PDOs are read via CoE (if supported) using the PDO Reading FSM
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  1757
(see sec.~\ref{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
  1758
the SII (if any) is overwritten.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1759
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1760
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1761
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1762
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1763
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1764
\section{The Slave Configuration State Machine}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1765
\label{sec:fsm-conf}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1766
\index{FSM!Slave Configuration}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1767
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1768
The slave configuration state machine, which can be seen in
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1769
figure~\ref{fig:fsm-slaveconf}, leads through the process of configuring a
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1770
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
  1771
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1772
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1773
  \centering
1406
8686c5b3d14b Clear DC assignment after going to INIT.
Florian Pose <fp@igh-essen.com>
parents: 1399
diff changeset
  1774
  \includegraphics[height=\textheight]{graphs/fsm_slave_conf}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1775
  \caption{Transition diagram of the slave configuration state
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1776
    machine}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1777
  \label{fig:fsm-slaveconf}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1778
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1779
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1780
\begin{description}
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1781
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1782
\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
  1783
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1784
\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
  1785
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
  1786
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
  1787
finished.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1788
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1789
\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
  1790
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
  1791
is skipped.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1792
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1793
\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
  1794
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
  1795
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  1796
\item[SDO Configuration] If there is a slave configuration attached (see
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  1797
sec.~\ref{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
  1798
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
  1799
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  1800
\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
  1801
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
  1802
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  1803
\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
  1804
configured.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1805
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1806
\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
  1807
application (i.\,e.\ if the application registered PDO entries), they are
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1808
applied. 
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1809
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1810
\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
  1811
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
  1812
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1813
\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
  1814
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
  1815
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1816
\end{description}
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
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1819
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1820
\section{The State Change State Machine}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1821
\label{sec:fsm-change}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1822
\index{FSM!State Change}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1823
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1824
The state change state machine, which can be seen in
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1825
figure~\ref{fig:fsm-change}, leads through the process of changing a slave's
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1826
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
  1827
in \cite[sec.~6.4.1]{alspec}.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1828
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1829
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1830
  \centering
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1831
  \includegraphics[width=.6\textwidth]{graphs/fsm_change}
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1832
  \caption{Transition Diagram of the State Change State Machine}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1833
  \label{fig:fsm-change}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1834
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1835
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1836
\begin{description}
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1837
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1838
\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
  1839
Request'' register (see~\cite[sec. 5.3.1]{alspec}).
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1840
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1841
\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
  1842
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
  1843
is issued again, until it is acknowledged.
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1844
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1845
\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
  1846
``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
  1847
out until the slave changes the AL state.
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1848
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1849
\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
  1850
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
  1851
Changed'' registers (see~\cite[sec. 5.3.3]{alspec}).
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1852
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1853
\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
  1854
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
  1855
register again.
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1856
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1857
\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
  1858
out the ``AL Control Response'' register again.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1859
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1860
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1861
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1862
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
  1863
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
  1864
requested.
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1865
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1866
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1867
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1868
\section{The SII State Machine}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1869
\label{sec:fsm-sii}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1870
\index{FSM!SII}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1871
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1872
The SII\index{SII} state machine (shown in figure~\ref{fig:fsm-sii})
1289
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  1873
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
  1874
Information Interface described in \cite[sec.~6.4]{dlspec}.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1875
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1876
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1877
  \centering
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1878
  \includegraphics[width=.5\textwidth]{graphs/fsm_sii}
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1879
  \caption{Transition Diagram of the SII State Machine}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1880
  \label{fig:fsm-sii}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1881
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1882
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1883
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
  1884
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1885
\begin{description}
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1886
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1887
\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
  1888
written to the SII attribute.
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1889
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1890
\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
  1891
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
  1892
attribute for state and data.
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1893
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1894
\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
  1895
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
  1896
copied from the datagram.
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1897
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1898
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1899
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1900
The writing part works nearly similar:
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1901
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1902
\begin{description}
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[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
  1905
written to the SII attribute.
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1906
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1907
\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
  1908
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
  1909
attribute for the state of the write operation.
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1910
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1911
\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
  1912
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
  1913
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
  1914
369
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
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1917
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1918
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  1919
\section{The PDO State Machines}
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1920
\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
  1921
\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
  1922
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  1923
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
  1924
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
  1925
\cite[sec. 5.6.7.4]{alspec}. For the object access, the CANopen over EtherCAT
1289
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  1926
access primitives are used (see sec.~\ref{sec:coe}), so the slave must support
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  1927
the CoE mailbox protocol.
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1928
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  1929
\paragraph{PDO Reading FSM} This state machine (fig.~\ref{fig:fsm-pdo-read})
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  1930
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
  1931
the PDO assignment for each Sync Manager and uses the PDO Entry Reading FSM
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  1932
(fig.~\ref{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
  1933
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1934
\begin{figure}[htbp]
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1935
  \centering
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1936
  \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
  1937
  \caption{Transition Diagram of the PDO Reading State Machine}
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1938
  \label{fig:fsm-pdo-read}
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1939
\end{figure}
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1940
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  1941
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
  1942
(\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
  1943
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
  1944
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
  1945
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
  1946
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  1947
\paragraph{PDO Entry Reading FSM} This state machine
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  1948
(fig.~\ref{fig:fsm-pdo-entry-read}) reads the PDO mapping (the PDO entries) of
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  1949
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
  1950
\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
  1951
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
  1952
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
  1953
mapped PDO entry index, subindex and bit size.
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1954
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1955
\begin{figure}[htbp]
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1956
  \centering
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1957
  \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
  1958
  \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
  1959
  \label{fig:fsm-pdo-entry-read}
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1960
\end{figure}
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
\begin{figure}[htbp]
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1963
  \centering
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1964
  \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
  1965
  \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
  1966
  \label{fig:fsm-pdo-conf}
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1967
\end{figure}
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1968
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1969
\begin{figure}[htbp]
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1970
  \centering
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1971
  \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
  1972
  \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
  1973
  \label{fig:fsm-pdo-entry-conf}
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1974
\end{figure}
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1975
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1976
%------------------------------------------------------------------------------
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1977
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1978
\chapter{Mailbox Protocol Implementations}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1979
\index{Mailbox}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1980
1917
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  1981
The EtherCAT master implements the CANopen over EtherCAT (CoE), Ethernet over
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  1982
EtherCAT (EoE), File-access over EtherCAT (FoE), Vendor-specific over EtherCAT
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  1983
(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
  1984
sections for details.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1985
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1986
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1987
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  1988
\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
  1989
\label{sec:eoe}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1990
\index{EoE}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1991
1306
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
  1992
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
  1993
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
  1994
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
  1995
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
  1996
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
  1997
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1998
\paragraph{Virtual Network Interfaces}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1999
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2000
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
  2001
slave. These interfaces are called either
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2002
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2003
\begin{description}
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2004
1293
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
  2005
\item[eoeXsY] for a slave without an alias address (see
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
  2006
sec.~\ref{sec:ethercat-alias}), where X is the master index and Y is the
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
  2007
slave's ring position, or
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2008
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2009
\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
  2010
index and Y is the decimal alias address.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2011
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2012
\end{description}
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2013
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2014
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
  2015
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
  2016
forwarded to the virtual interfaces.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2017
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2018
This bears the following advantages:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2019
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2020
\begin{itemize}
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2021
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2022
\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
  2023
interconnected with the rest of the world.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2024
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2025
\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
  2026
the EoE interfaces.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2027
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2028
\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
  2029
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
  2030
traffic between EoE-capable slaves.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2031
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2032
\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
  2033
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
  2034
network interfaces.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2035
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2036
\end{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2037
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2038
\paragraph{EoE Handlers}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2039
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2040
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
  2041
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
  2042
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
  2043
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
  2044
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
  2045
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
  2046
\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
  2047
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
  2048
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
  2049
\lstinline+netif_stop_queue()+.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2050
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2051
\paragraph{Creation of EoE Handlers}
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2052
1289
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  2053
During bus scanning (see sec.~\ref{sec:fsm-scan}), the master determines the
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  2054
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
  2055
``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
  2056
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
  2057
case, an EoE handler is created for that slave.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2058
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2059
\paragraph{EoE State Machine}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2060
\index{FSM!EoE}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2061
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2062
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
  2063
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
  2064
communication primitives. This state machine is showed in
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2065
figure~\ref{fig:fsm-eoe}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2066
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2067
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2068
  \centering
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2069
  \includegraphics[width=.7\textwidth]{images/fsm-eoe} % FIXME
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2070
  \caption{Transition Diagram of the EoE State Machine}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2071
  \label{fig:fsm-eoe}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2072
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2073
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2074
% FIXME
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2075
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2076
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2077
\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
  2078
  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
  2079
  frames. $\rightarrow$~RX\_CHECK
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2080
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2081
\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
  2082
  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
  2083
  $\rightarrow$~TX\_START
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2084
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2085
  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
  2086
  the new data. $\rightarrow$~RX\_FETCH
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2087
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2088
\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
  2089
  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
  2090
  dropped and a transmit sequence is started.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2091
  $\rightarrow$~TX\_START
369
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
  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
  2094
  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
  2095
  the correct position of the socket buffer.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2096
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2097
  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
  2098
  to the network stack and a transmit sequence is started.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2099
  $\rightarrow$~TX\_START
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2100
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2101
  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
  2102
  fragment. $\rightarrow$~RX\_\-START
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2103
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2104
\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
  2105
  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
  2106
  a receive sequence is started. $\rightarrow$~RX\_START
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2107
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2108
  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
  2109
  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
  2110
  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
  2111
  frame is sent. $\rightarrow$~TX\_SENT
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2112
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2113
\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
  2114
  successfully. If the current frame consists of further fragments,
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2115
  the next one is sent. $\rightarrow$~TX\_SENT
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2116
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2117
  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
  2118
  $\rightarrow$~RX\_START
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2119
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2120
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2121
\paragraph{EoE Processing}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2122
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2123
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
  2124
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
  2125
machines synchronously with the master state machine (see
1289
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  2126
sec.~\ref{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
  2127
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2128
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
  2129
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
  2130
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
  2131
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
  2132
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2133
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
  2134
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
  2135
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
  2136
poses the new problem of concurrent access to the master. The locking
1289
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  2137
mechanisms needed for this are introduced in sec.~\ref{sec:concurr}.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2138
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2139
\paragraph{Automatic Configuration}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2140
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2141
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
  2142
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
  2143
application-layer state is automatically set to OP.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2144
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2145
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2146
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  2147
\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
  2148
\label{sec:coe}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2149
\index{CoE}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2150
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  2151
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
  2152
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
  2153
exchange data objects on application level.
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2154
1297
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
  2155
% TODO
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  2156
%
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  2157
% Download / Upload
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  2158
% Expedited / Normal
1204
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
  2159
% Segmenting
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  2160
% SDO Info Services
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  2161
%
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  2162
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  2163
\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
  2164
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  2165
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
  2166
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
  2167
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
  2168
SDO configuration has to be part of the slave configuration state machine (see
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  2169
sec.~\ref{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
  2170
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
  2171
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
  2172
is reconfigured.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2173
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  2174
The transition diagram of the SDO Download state machine can be seen
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2175
in figure~\ref{fig:fsm-coedown}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2176
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2177
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2178
  \centering
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2179
  \includegraphics[width=.9\textwidth]{images/fsm-coedown} % FIXME
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2180
  \caption{Transition diagram of the CoE download state machine}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2181
  \label{fig:fsm-coedown}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2182
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2183
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2184
% FIXME
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2185
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2186
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2187
\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
  2188
  machine. The ``SDO Download Normal Request'' mailbox command is
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2189
  sent. $\rightarrow$~REQUEST
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2190
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2191
\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
  2192
  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
  2193
  and a timer is started. $\rightarrow$~CHECK
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2194
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2195
\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
  2196
  \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
  2197
  \item If it timed out, the SDO download is aborted.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2198
    $\rightarrow$~ERROR
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2199
  \item Otherwise, the mailbox is queried again.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2200
    $\rightarrow$~CHECK
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2201
  \end{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2202
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2203
  If the mailbox contains new data, the response is fetched.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2204
  $\rightarrow$~RESPONSE
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2205
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2206
\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
  2207
  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
  2208
  Transfer Request'' was received, the SDO download is aborted.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2209
  $\rightarrow$~ERROR
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2210
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  2211
  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
  2212
  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
  2213
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  2214
\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
  2215
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  2216
\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
  2217
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2218
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2219
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2220
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2221
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  2222
\section{Vendor specific over EtherCAT (VoE)}
1270
11f4b6e10d74 Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1269
diff changeset
  2223
\label{sec:voe}
11f4b6e10d74 Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1269
diff changeset
  2224
\index{VoE}
11f4b6e10d74 Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1269
diff changeset
  2225
11f4b6e10d74 Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1269
diff changeset
  2226
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
  2227
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
  2228
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
  2229
constraints regarding this protocol.
11f4b6e10d74 Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1269
diff changeset
  2230
11f4b6e10d74 Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1269
diff changeset
  2231
The EtherCAT master allows to create multiple VoE handlers per slave
1289
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  2232
configuration via the application interface (see chap.~\ref{chap:api}). These
1270
11f4b6e10d74 Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1269
diff changeset
  2233
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
  2234
de91d633ff6c VoE handlers.
Florian Pose <fp@igh-essen.com>
parents: 1297
diff changeset
  2235
For more information about using VoE handlers, see sec.~\ref{sec:api-voe} or
de91d633ff6c VoE handlers.
Florian Pose <fp@igh-essen.com>
parents: 1297
diff changeset
  2236
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
  2237
11f4b6e10d74 Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1269
diff changeset
  2238
%------------------------------------------------------------------------------
11f4b6e10d74 Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1269
diff changeset
  2239
1917
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2240
\section{Servo Profile over EtherCAT (SoE)}
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2241
\label{sec:soe}
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2242
\index{SoE}
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2243
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2244
The SoE protocol implements the Service Channel layer, specified in IEC
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2245
61800-7 \cite{soespec} via EtherCAT mailboxes.
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2246
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2247
The SoE protocol is quite similar to the CoE protocol (see
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2248
sec.~\ref{sec:coe}). Instead of SDO indices and subindices, so-called
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2249
identification numbers (IDNs) identify parameters.
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2250
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2251
The implementation covers the ``SCC Read'' and ``SCC Write'' primitives, each
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2252
with the ability to fragment data.
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2253
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2254
There are several ways to use the SoE implementation:
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2255
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2256
\begin{itemize}
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2257
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2258
\item Reading and writing IDNs via the command-line tool (see
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2259
sec.~\ref{sec:soeaccess}).
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2260
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2261
\item Storing configurations for arbitrary IDNs via the application interface
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2262
(see chap.~\ref{chap:api}, i.\,e.~\lstinline+ecrt_slave_config_idn()+). These
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2263
configurations are written to the slave during configuration in PREOP state,
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2264
before going to SAFEOP.
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2265
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2266
\item The user-space library (see sec.~\ref{sec:userlib}), offers functions to
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2267
read/write IDNs in blocking mode (\lstinline+ecrt_master_read_idn()+,
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2268
\lstinline+ecrt_master_write_idn()+).
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2269
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2270
\end{itemize}
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2271
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2272
%------------------------------------------------------------------------------
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2273
1275
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  2274
\chapter{Userspace Interfaces}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2275
\label{sec:user}
1275
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  2276
\index{Userspace}
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2277
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  2278
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
  2279
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
  2280
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  2281
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
  2282
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
  2283
to view and to change special parameters at runtime.
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  2284
1275
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  2285
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
  2286
is necessary to show the connected slaves with a single command, for instance
1289
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  2287
(see sec.~\ref{sec:tool}).
1275
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  2288
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  2289
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
  2290
programs to use EtherCAT master functionality. This was implemented via a
1282
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2291
character device and a userspace library (see sec.~\ref{sec:userlib}).
1275
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  2292
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  2293
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
  2294
to automatically start up with a persistent configuration (see
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  2295
sec.~\ref{sec:system}).
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  2296
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  2297
A last thing is monitoring EtherCAT communication. For debugging purposes,
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  2298
there had to be a way to analyze EtherCAT datagrams. The best way would be
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  2299
with a popular network analyzer, like Wireshark \cite{wireshark} (the former
1275
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  2300
Ethereal) or others (see sec.~\ref{sec:debug}).
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  2301
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  2302
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
  2303
to make all that possible.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2304
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2305
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2306
1087
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2307
\section{Command-line Tool}
1289
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  2308
\label{sec:tool}
1087
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2309
1297
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
  2310
% TODO --master
1087
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2311
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2312
\subsection{Character Devices}
1087
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2313
\label{sec:cdev}
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2314
1214
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  2315
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
  2316
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
  2317
the index of the master.
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  2318
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  2319
\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
  2320
created, if the \lstinline+udev+ Package is installed. See
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  2321
sec.~\ref{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
  2322
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2323
%------------------------------------------------------------------------------
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2324
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2325
\subsection{Setting Alias Addresses}
1293
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
  2326
\label{sec:ethercat-alias}
1140
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2327
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2328
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_alias}
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2329
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2330
%------------------------------------------------------------------------------
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2331
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2332
\subsection{Displaying the Bus Configuration}
1293
a2a03519ee47 Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents: 1292
diff changeset
  2333
\label{sec:ethercat-config}
1140
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2334
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2335
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_config}
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2336
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2337
%------------------------------------------------------------------------------
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2338
1514
85ac1c91045d Added 'ethercat cstruct' command to output PDO information in C language.
Florian Pose <fp@igh-essen.com>
parents: 1485
diff changeset
  2339
\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
  2340
\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
  2341
85ac1c91045d Added 'ethercat cstruct' command to output PDO information in C language.
Florian Pose <fp@igh-essen.com>
parents: 1485
diff changeset
  2342
\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
  2343
85ac1c91045d Added 'ethercat cstruct' command to output PDO information in C language.
Florian Pose <fp@igh-essen.com>
parents: 1485
diff changeset
  2344
%------------------------------------------------------------------------------
85ac1c91045d Added 'ethercat cstruct' command to output PDO information in C language.
Florian Pose <fp@igh-essen.com>
parents: 1485
diff changeset
  2345
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2346
\subsection{Displaying Process Data}
1140
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2347
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2348
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_data}
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2349
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2350
%------------------------------------------------------------------------------
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2351
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2352
\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
  2353
\label{sec:ethercat-debug}
1140
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2354
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2355
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_debug}
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2356
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2357
%------------------------------------------------------------------------------
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2358
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2359
\subsection{Configured Domains}
1140
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2360
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2361
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_domains}
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2362
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2363
%------------------------------------------------------------------------------
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2364
1423
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2365
\subsection{SDO Access}
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2366
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2367
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_download}
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2368
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2369
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_upload}
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2370
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2371
%------------------------------------------------------------------------------
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2372
1485
5ddc3a455059 ethercat eoe command.
Florian Pose <fp@igh-essen.com>
parents: 1423
diff changeset
  2373
\subsection{EoE Statistics}
5ddc3a455059 ethercat eoe command.
Florian Pose <fp@igh-essen.com>
parents: 1423
diff changeset
  2374
5ddc3a455059 ethercat eoe command.
Florian Pose <fp@igh-essen.com>
parents: 1423
diff changeset
  2375
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_eoe}
5ddc3a455059 ethercat eoe command.
Florian Pose <fp@igh-essen.com>
parents: 1423
diff changeset
  2376
5ddc3a455059 ethercat eoe command.
Florian Pose <fp@igh-essen.com>
parents: 1423
diff changeset
  2377
%------------------------------------------------------------------------------
5ddc3a455059 ethercat eoe command.
Florian Pose <fp@igh-essen.com>
parents: 1423
diff changeset
  2378
1423
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2379
\subsection{File-Access over EtherCAT}
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2380
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2381
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_foe_read}
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2382
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2383
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_foe_write}
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2384
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2385
%------------------------------------------------------------------------------
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2386
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2387
\subsection{Creating Topology Graphs}
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2388
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2389
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_graph}
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2390
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2391
%------------------------------------------------------------------------------
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2392
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2393
\subsection{Master and Ethernet Devices}
1140
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2394
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2395
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_master}
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2396
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2397
%------------------------------------------------------------------------------
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2398
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  2399
\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
  2400
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2401
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_pdos}
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
%------------------------------------------------------------------------------
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2404
1423
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2405
\subsection{Register Access}
1517
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
  2406
\label{sec:regaccess}
1423
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2407
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2408
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_reg_read}
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2409
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2410
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_reg_write}
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2411
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2412
%------------------------------------------------------------------------------
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2413
1327
4d179b06dd3c merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents: 1309
diff changeset
  2414
\subsection{SDO Dictionary}
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_sdos}
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{SII Access}
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2421
\label{sec:siiaccess}
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2422
\index{SII!Access}
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
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
  2425
slaves. This was introduced for the reasons below:
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
\begin{itemize}
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2428
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2429
\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
  2430
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
  2431
can be easily backed up and restored.
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2432
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2433
\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
  2434
writing must be possible for that.
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
\item Through reading access, analyzing category data is possible from
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2437
userspace.
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2438
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2439
\end{itemize}
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
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_sii_read}
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2442
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2443
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
  2444
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
  2445
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2446
\begin{lstlisting}
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2447
$ `\textbf{ethercat sii\_read --position 3 | hexdump}`
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2448
0000000 0103 0000 0000 0000 0000 0000 0000 008c
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2449
0000010 0002 0000 3052 07f0 0000 0000 0000 0000
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2450
0000020 0000 0000 0000 0000 0000 0000 0000 0000
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2451
...
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2452
\end{lstlisting}
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2453
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2454
Backing up SII contents can easily done with a redirection:
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2455
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2456
\begin{lstlisting}
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2457
$ `\textbf{ethercat sii\_read --position 3 > sii-of-slave3.bin}`
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2458
\end{lstlisting}
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2459
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2460
To download SII contents to a slave, writing access to the master's character
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2461
device is necessary (see sec.~\ref{sec:cdev}).
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_sii_write}
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
\begin{lstlisting}
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2466
# `\textbf{ethercat sii\_write --position 3 sii-of-slave3.bin}`
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2467
\end{lstlisting}
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2468
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2469
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
  2470
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
  2471
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
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2474
\subsection{Slaves on the Bus}
1087
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2475
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2476
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
  2477
1140
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2478
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_slaves}
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2479
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2480
Below is a typical output:
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2481
1087
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2482
\begin{lstlisting}
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2483
$ `\textbf{ethercat slaves}`
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2484
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
  2485
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
  2486
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
  2487
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
  2488
\end{lstlisting}
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2489
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2490
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2491
1917
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2492
\subsection{SoE IDN Access}
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2493
\label{sec:soeaccess}
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2494
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2495
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_soe_read}
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2496
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2497
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_soe_write}
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2498
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2499
%------------------------------------------------------------------------------
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  2500
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2501
\subsection{Requesting Application-Layer States}
1140
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2502
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2503
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_states}
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2504
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2505
%------------------------------------------------------------------------------
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2506
1423
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2507
\subsection{Displaying the Master Version}
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
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_version}
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
%------------------------------------------------------------------------------
41e3baa2da23 Updated command doc.
Florian Pose <fp@igh-essen.com>
parents: 1406
diff changeset
  2512
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2513
\subsection{Generating Slave Description XML}
1140
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2514
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2515
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_xml}
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2516
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2517
%------------------------------------------------------------------------------
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2518
1275
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  2519
\section{Userspace Library}
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  2520
\label{sec:userlib}
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  2521
1289
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  2522
The native application interface (see chap.~\ref{chap:api}) resides in
1282
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2523
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
  2524
application interface available from userspace programs, a userspace library
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2525
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
  2526
conditions of the LGPL, version 2 \cite{lgpl}.
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2527
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2528
The library is named \textit{libethercat}. Its sources reside in the
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2529
\textit{lib/} subdirectory and are build by default when using
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2530
\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
  2531
installation prefix as \textit{libethercat.a} (for static linking),
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2532
\textit{libethercat.la} (for the use with \textit{libtool}) and
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2533
\textit{libethercat.so} (for dynamic linking).
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2534
1299
dd8e55d97280 Userlib.
Florian Pose <fp@igh-essen.com>
parents: 1298
diff changeset
  2535
\subsection{Using the Library}
1282
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2536
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2537
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
  2538
and in user context.
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2539
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2540
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
  2541
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
  2542
path of the master sources.
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2543
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2544
\begin{lstlisting}[language=C]
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2545
#include <ecrt.h>
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2546
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2547
int main(void)
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2548
{
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2549
    ec_master_t *master = ecrt_request_master(0);
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2550
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2551
    if (!master)
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2552
        return 1; // error
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2553
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2554
    pause(); // wait for signal
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2555
    return 0;
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2556
}
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2557
\end{lstlisting}
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2558
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2559
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
  2560
below command:
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2561
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2562
\begin{lstlisting}
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2563
gcc ethercat.c -o ectest -I/opt/etherlab/include \
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2564
    -L/opt/etherlab/lib -lethercat \
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2565
    -Wl,--rpath -Wl,/opt/etherlab/lib
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2566
\end{lstlisting}
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2567
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2568
The library can also be linked statically to the program:
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2569
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2570
\begin{lstlisting}
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2571
gcc -static ectest.c -o ectest -I/opt/etherlab/include \
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2572
    /opt/etherlab/lib/libethercat.a
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2573
\end{lstlisting}
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2574
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2575
\subsection{Implementation}
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2576
\label{sec:userimp}
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2577
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2578
Basically the kernel API was transferred into userspace via the master
1299
dd8e55d97280 Userlib.
Florian Pose <fp@igh-essen.com>
parents: 1298
diff changeset
  2579
character device (see chap.~\ref{chap:arch}, fig.~\ref{fig:arch} and
dd8e55d97280 Userlib.
Florian Pose <fp@igh-essen.com>
parents: 1298
diff changeset
  2580
sec.~\ref{sec:cdev}).
1282
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2581
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2582
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
  2583
\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
  2584
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
  2585
according API functions directly, what results in a minimum additional delay
b99f2f9cb73f DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents: 1514
diff changeset
  2586
(see sec.~\ref{sec:usertiming}).
1282
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2587
1299
dd8e55d97280 Userlib.
Florian Pose <fp@igh-essen.com>
parents: 1298
diff changeset
  2588
For performance reasons, the actual domain process data (see
dd8e55d97280 Userlib.
Florian Pose <fp@igh-essen.com>
parents: 1298
diff changeset
  2589
sec.~\ref{sec:processdata}) are not copied between kernel and user memory on
dd8e55d97280 Userlib.
Florian Pose <fp@igh-essen.com>
parents: 1298
diff changeset
  2590
every access: Instead, the data are memory-mapped to the userspace
dd8e55d97280 Userlib.
Florian Pose <fp@igh-essen.com>
parents: 1298
diff changeset
  2591
application. Once the master is configured and activated, the master module
dd8e55d97280 Userlib.
Florian Pose <fp@igh-essen.com>
parents: 1298
diff changeset
  2592
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
  2593
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
  2594
result, there is no additional delay when accessing process data from
dd8e55d97280 Userlib.
Florian Pose <fp@igh-essen.com>
parents: 1298
diff changeset
  2595
userspace.
dd8e55d97280 Userlib.
Florian Pose <fp@igh-essen.com>
parents: 1298
diff changeset
  2596
dd8e55d97280 Userlib.
Florian Pose <fp@igh-essen.com>
parents: 1298
diff changeset
  2597
\paragraph{Kernel/User API Differences} Because of the memory-mapping of the
dd8e55d97280 Userlib.
Florian Pose <fp@igh-essen.com>
parents: 1298
diff changeset
  2598
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
  2599
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
  2600
kernel API. The corresponding functions are only available in kernelspace.
dd8e55d97280 Userlib.
Florian Pose <fp@igh-essen.com>
parents: 1298
diff changeset
  2601
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
  2602
1281
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2603
\subsection{Timing}
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2604
\label{sec:usertiming}
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2605
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2606
An interesting aspect is the timing of the userspace library calls compared to
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2607
those of the kernel API. Table~\ref{tab:usertiming} shows the call times and
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2608
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
  2609
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
  2610
kernel.
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2611
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2612
\begin{table}[htbp]
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2613
  \centering
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2614
  \caption{Application Interface Timing Comparison}
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2615
  \label{tab:usertiming}
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2616
  \vspace{2mm}
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2617
  \begin{tabular}{l|c|c|c|c}
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2618
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2619
    &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2620
    \multicolumn{2}{|c}{\textbf{Kernelspace}} &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2621
    \multicolumn{2}{|c}{\textbf{Userspace}}  \\
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2622
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2623
    \textbf{Function} &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2624
    $\mu(t)$ &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2625
    $\sigma(t)$ &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2626
    $\mu(t)$ &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2627
    $\sigma(t)$ \\
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2628
    \hline
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2629
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2630
    \lstinline+ecrt_master_receive()+ &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2631
    \unit{1.1}{\micro\second} &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2632
    \unit{0.3}{\micro\second} &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2633
    \unit{2.2}{\micro\second} &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2634
    \unit{0.5}{\micro\second} \\
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2635
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2636
    \lstinline+ecrt_domain_process()+ &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2637
    \unit{<0.1}{\micro\second} &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2638
    \unit{<0.1}{\micro\second} &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2639
    \unit{1.0}{\micro\second} &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2640
    \unit{0.2}{\micro\second} \\
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2641
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2642
    \lstinline+ecrt_domain_queue()+ &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2643
    \unit{<0.1}{\micro\second} &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2644
    \unit{<0.1}{\micro\second} &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2645
    \unit{1.0}{\micro\second} &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2646
    \unit{0.1}{\micro\second} \\
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2647
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2648
    \lstinline+ecrt_master_send()+ &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2649
    \unit{1.8}{\micro\second} &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2650
    \unit{0.2}{\micro\second} &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2651
    \unit{2.5}{\micro\second} &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2652
    \unit{0.5}{\micro\second} \\
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2653
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2654
  \end{tabular}
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2655
\end{table}
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2656
1282
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2657
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
  2658
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
  2659
the kernel API.
1281
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2660
1275
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  2661
%------------------------------------------------------------------------------
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  2662
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2663
\section{System Integration}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2664
\label{sec:system}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2665
1086
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2666
To integrate the EtherCAT master as a service into a running system, it comes
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2667
with an init script and a sysconfig file, that are described below.
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2668
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2669
\subsection{Init Script}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2670
\label{sec:init}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2671
\index{Init script}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2672
1086
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2673
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
  2674
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
  2675
\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
  2676
copied (or better: linked) to the appropriate location (see
1289
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  2677
sec.~\ref{sec:installation}), before the master can be inserted as a service.
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  2678
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
  2679
below.
1086
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2680
1306
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
  2681
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
  2682
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
  2683
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
  2684
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
  2685
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2686
\lstinputlisting[firstline=38,lastline=48]
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2687
    {../script/init.d/ethercat}
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2688
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2689
\subsection{Sysconfig File}
1086
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2690
\label{sec:sysconfig}
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2691
\index{Sysconfig file}
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2692
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2693
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
  2694
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
  2695
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
  2696
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
  2697
the file and included below:
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2698
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2699
\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
  2700
    {../script/sysconfig/ethercat}
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2701
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2702
\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
  2703
\label{sec:service}
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2704
\index{Service}
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2705
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2706
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
  2707
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
  2708
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
  2709
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
  2710
command:
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2711
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2712
\begin{lstlisting}
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2713
# `\textbf{insserv ethercat}`
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2714
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2715
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2716
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
  2717
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
  2718
\texttt{start}, \texttt{stop}, \texttt{restart} or \texttt{status}.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2719
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2720
\begin{lstlisting}[gobble=2]
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2721
  # `\textbf{/etc/init.d/ethercat restart}`
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2722
  Shutting down EtherCAT master                done
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2723
  Starting EtherCAT master                     done
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2724
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2725
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2726
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2727
1307
45a82ad140f8 New debug interfaces docs.
Florian Pose <fp@igh-essen.com>
parents: 1306
diff changeset
  2728
\section{Debug Interfaces}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2729
\label{sec:debug}
1307
45a82ad140f8 New debug interfaces docs.
Florian Pose <fp@igh-essen.com>
parents: 1306
diff changeset
  2730
\index{Debug Interfaces}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2731
1306
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
  2732
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
  2733
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
  2734
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
  2735
local network interfaces on the machine running the EtherCAT master directly.
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  2736
If the generic Ethernet driver (see sec.~\ref{sec:generic-driver}) is used,
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  2737
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
  2738
the EtherCAT bus.
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  2739
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  2740
When using native Ethernet drivers (see sec.~\ref{sec:native-drivers}), there
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  2741
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
  2742
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
  2743
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
  2744
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
  2745
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
  2746
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
  2747
with the \lstinline+--enable-debug-if+ switch (see
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  2748
sec.~\ref{sec:installation}).
1307
45a82ad140f8 New debug interfaces docs.
Florian Pose <fp@igh-essen.com>
parents: 1306
diff changeset
  2749
45a82ad140f8 New debug interfaces docs.
Florian Pose <fp@igh-essen.com>
parents: 1306
diff changeset
  2750
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
  2751
physical Ethernet device. The network interfaces are named \textit{ecdbgmX}
c8b82c27b6df Improved new debug interfaces again.
Florian Pose <fp@igh-essen.com>
parents: 1307
diff changeset
  2752
for the main device, and \textit{ecdbgbX} for the backup device (for future
c8b82c27b6df Improved new debug interfaces again.
Florian Pose <fp@igh-essen.com>
parents: 1307
diff changeset
  2753
use), where X is the master index. The below listing shows a debug interface
c8b82c27b6df Improved new debug interfaces again.
Florian Pose <fp@igh-essen.com>
parents: 1307
diff changeset
  2754
among some standard network interfaces:
1306
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
  2755
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
  2756
\begin{lstlisting}
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
  2757
# `\textbf{ip link}`
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
  2758
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
  2759
    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
  2760
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
  2761
    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
  2762
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
  2763
                                                 qlen 1000
1306
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
  2764
    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
  2765
\end{lstlisting}
45a82ad140f8 New debug interfaces docs.
Florian Pose <fp@igh-essen.com>
parents: 1306
diff changeset
  2766
45a82ad140f8 New debug interfaces docs.
Florian Pose <fp@igh-essen.com>
parents: 1306
diff changeset
  2767
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
  2768
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
  2769
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
  2770
command:
1306
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
  2771
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
  2772
\begin{lstlisting}
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
  2773
# `\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
  2774
\end{lstlisting}
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
  2775
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
  2776
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
  2777
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
  2778
1309
Florian Pose <fp@igh-essen.com>
parents: 1308
diff changeset
  2779
\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
  2780
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
  2781
(like RTAI) do not allow this in realtime context!
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2782
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2783
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2784
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2785
\chapter{Timing Aspects}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2786
\label{sec:timing}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2787
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2788
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
  2789
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
  2790
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2791
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2792
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2793
\subsection{Application Interface Profiling}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2794
\label{sec:timing-profile}
1204
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
  2795
\index{Profiling}
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
  2796
% FIXME
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2797
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2798
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
  2799
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
  2800
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
  2801
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
  2802
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2803
\begin{lstlisting}[gobble=2,language=C]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2804
  c0 = get_cycles();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2805
  ecrt_master_receive(master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2806
  c1 = get_cycles();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2807
  ecrt_domain_process(domain1);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2808
  c2 = get_cycles();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2809
  ecrt_master_run(master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2810
  c3 = get_cycles();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2811
  ecrt_master_send(master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2812
  c4 = get_cycles();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2813
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2814
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2815
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
  2816
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
  2817
\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
  2818
\milli\second.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2819
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2820
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
  2821
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
  2822
\unit{100}{\micro\second}. The measuring was repeated $n = 100$ times and the
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2823
results were averaged. These can be seen in table~\ref{tab:profile}.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2824
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2825
\begin{table}[htpb]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2826
  \centering
1204
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
  2827
  \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
  2828
  Processor}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2829
  \label{tab:profile}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2830
  \vspace{2mm}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2831
  \begin{tabular}{l|r|r}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2832
    Element & Mean Duration [\second] & Standard Deviancy [\micro\second] \\
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2833
    \hline
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2834
    \textit{ecrt\_master\_receive()} & 8.04 & 0.48\\
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2835
    \textit{ecrt\_domain\_process()} & 0.14 & 0.03\\
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2836
    \textit{ecrt\_master\_run()} & 0.29 & 0.12\\
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2837
    \textit{ecrt\_master\_send()} & 2.18 & 0.17\\ \hline
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2838
    Complete Cycle & 10.65 & 0.69\\ \hline
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2839
  \end{tabular}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2840
\end{table}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2841
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2842
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
  2843
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
  2844
the Ethernet device, analyzes datagrams and copies their contents into
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2845
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
  2846
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
  2847
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
  2848
receiving time.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2849
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2850
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
  2851
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
  2852
\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
  2853
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
  2854
\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
  2855
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
  2856
functions are more or less complex.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2857
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2858
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
  2859
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
  2860
keeps being theoretical:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2861
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2862
\begin{enumerate}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2863
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2864
\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
  2865
realtime cycles.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2866
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2867
\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
  2868
cycle begins. The determination of the bus cycle time is difficult and covered
1289
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  2869
in sec.~\ref{sec:timing-bus}.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2870
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2871
\end{enumerate}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2872
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2873
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2874
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2875
\subsection{Bus Cycle Measuring}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2876
\label{sec:timing-bus}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2877
\index{Bus cycle}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2878
1297
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
  2879
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
  2880
taken:
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2881
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2882
\begin{enumerate}
1297
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
  2883
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
  2884
\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
  2885
frame.
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
  2886
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
  2887
\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
  2888
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2889
\end{enumerate}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2890
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2891
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
  2892
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
  2893
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
  2894
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
  2895
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
  2896
an electrical measuring.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2897
1204
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
  2898
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
  2899
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
  2900
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
  2901
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
  2902
limits of the system.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2903
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2904
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
  2905
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
  2906
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
  2907
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
  2908
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
  2909
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
  2910
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
  2911
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
  2912
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
  2913
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
  2914
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
  2915
``skipped''.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2916
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2917
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
  2918
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
  2919
surely be increased by choosing faster hardware. Especially the RealTek
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
  2920
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
  2921
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
  2922
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
  2923
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2924
%------------------------------------------------------------------------------
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2925
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2926
\chapter{Installation}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2927
\label{sec:installation}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2928
\index{Master!Installation}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2929
1772
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  2930
\section{Getting the Software}
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  2931
\label{sec:getting}
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  2932
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  2933
There are several ways to get the master software:
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  2934
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  2935
\begin{enumerate}
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  2936
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  2937
\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
  2938
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
  2939
at~the EtherLab project~\cite{etherlab} as a tarball.
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  2940
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  2941
\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
  2942
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
  2943
project page on
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  2944
SourceForge.net\footnote{\url{http://sourceforge.net/projects/etherlabmaster}}.
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  2945
The whole repository can be cloned with the command
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  2946
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  2947
\begin{lstlisting}[breaklines=true]
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  2948
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
  2949
\end{lstlisting}
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  2950
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  2951
\item Without a local Mercurial installation, tarballs of arbitrary revisions
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  2952
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
  2953
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
  2954
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  2955
\end{enumerate}
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  2956
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2957
\section{Building the Software}
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  2958
1772
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  2959
After downloading a tarball or cloning the repository as described in
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  2960
sec.~\ref{sec:getting}, the sources have to be prepared and configured for the
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  2961
build process.
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  2962
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  2963
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
  2964
commands:
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2965
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2966
\begin{lstlisting}[gobble=2]
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2967
  $ `\textbf{tar xjf ethercat-\masterversion.tar.bz2}`
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2968
  $ `\textbf{cd ethercat-\masterversion/}`
374
e43a29f9079e Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents: 371
diff changeset
  2969
\end{lstlisting}
e43a29f9079e Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents: 371
diff changeset
  2970
1772
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  2971
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
  2972
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
  2973
executed for configuration (see below).
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  2974
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  2975
\paragraph{Bootstrap} When downloading or cloning directly from the
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  2976
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
  2977
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
  2978
autoconf and automake packages are required for this.
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  2979
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  2980
\paragraph{Configuration and Build} The configuration and the build process
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  2981
follow the below commands:
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2982
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2983
\begin{lstlisting}[gobble=2]
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2984
  $ `\textbf{./configure}`
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2985
  $ `\textbf{make}`
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2986
  $ `\textbf{make modules}`
374
e43a29f9079e Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents: 371
diff changeset
  2987
\end{lstlisting}
e43a29f9079e Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents: 371
diff changeset
  2988
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2989
Table~\ref{tab:config} lists important configuration switches and options.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2990
2153
5bb7df22ced2 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2076
diff changeset
  2991
\begin{longtable}{l|p{.4\textwidth}|l}
5bb7df22ced2 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2076
diff changeset
  2992
  \caption{Configuration options}\rule[-5ex]{0mm}{0mm}
5bb7df22ced2 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2076
diff changeset
  2993
  \label{tab:config}\\
5bb7df22ced2 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2076
diff changeset
  2994
5bb7df22ced2 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2076
diff changeset
  2995
\textbf{Option/Switch} & \textbf{Description} & \textbf{Default}\\\hline
5bb7df22ced2 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2076
diff changeset
  2996
\endfirsthead
5bb7df22ced2 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2076
diff changeset
  2997
5bb7df22ced2 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2076
diff changeset
  2998
\textbf{Option/Switch} & \textbf{Description} & \textbf{Default}\\\hline
5bb7df22ced2 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2076
diff changeset
  2999
\endhead
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3000
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3001
\lstinline+--prefix+ & Installation prefix & \textit{/opt/etherlab}\\
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3002
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3003
\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
  3004
2153
5bb7df22ced2 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2076
diff changeset
  3005
\lstinline+--with-module-dir+ & Subdirectory in the kernel module tree, where
5bb7df22ced2 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2076
diff changeset
  3006
the EtherCAT kernel modules shall be installed. & \textit{ethercat}\\
5bb7df22ced2 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2076
diff changeset
  3007
5bb7df22ced2 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2076
diff changeset
  3008
\hline
5bb7df22ced2 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2076
diff changeset
  3009
5bb7df22ced2 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2076
diff changeset
  3010
\lstinline+--enable-generic+ & Build the generic Ethernet driver (see
2229
97c7c202fa78 Enable generic driver by default.
Florian Pose <fp@igh-essen.com>
parents: 2153
diff changeset
  3011
sec.~\ref{sec:generic-driver}). & yes\\
2153
5bb7df22ced2 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2076
diff changeset
  3012
5bb7df22ced2 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2076
diff changeset
  3013
\lstinline+--enable-8139too+ & Build the 8139too driver & yes\\
5bb7df22ced2 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2076
diff changeset
  3014
5bb7df22ced2 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2076
diff changeset
  3015
\lstinline+--with-8139too-kernel+ & 8139too kernel & $\dagger$\\
5bb7df22ced2 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2076
diff changeset
  3016
5bb7df22ced2 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2076
diff changeset
  3017
\lstinline+--enable-e100+ & Build the e100 driver & no\\
5bb7df22ced2 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2076
diff changeset
  3018
5bb7df22ced2 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2076
diff changeset
  3019
\lstinline+--with-e100-kernel+ & e100 kernel & $\dagger$\\
5bb7df22ced2 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2076
diff changeset
  3020
5bb7df22ced2 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2076
diff changeset
  3021
\lstinline+--enable-e1000+ & Enable e1000 driver & no\\
5bb7df22ced2 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2076
diff changeset
  3022
5bb7df22ced2 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2076
diff changeset
  3023
\lstinline+--with-e1000-kernel+ & e1000 kernel & $\dagger$\\
5bb7df22ced2 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2076
diff changeset
  3024
5bb7df22ced2 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2076
diff changeset
  3025
\lstinline+--enable-e1000e+ & Enable e1000e driver & no\\
5bb7df22ced2 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2076
diff changeset
  3026
5bb7df22ced2 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2076
diff changeset
  3027
\lstinline+--with-e1000e-kernel+ & e1000e kernel & $\dagger$\\
5bb7df22ced2 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2076
diff changeset
  3028
5bb7df22ced2 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2076
diff changeset
  3029
\lstinline+--enable-r8169+ & Enable r8169 driver & no\\
5bb7df22ced2 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2076
diff changeset
  3030
5bb7df22ced2 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2076
diff changeset
  3031
\lstinline+--with-r8169-kernel+ & r8169 kernel & $\dagger$\\
5bb7df22ced2 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2076
diff changeset
  3032
5bb7df22ced2 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2076
diff changeset
  3033
\hline
5bb7df22ced2 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2076
diff changeset
  3034
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3035
\lstinline+--with-rtai-dir+ & RTAI path (only for RTAI example) & \\
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3036
2153
5bb7df22ced2 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2076
diff changeset
  3037
\lstinline+--enable-debug-if+ & Create a debug interface for each master & no\\
5bb7df22ced2 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2076
diff changeset
  3038
5bb7df22ced2 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2076
diff changeset
  3039
\lstinline+--enable-debug-ring+ & Create a debug ring to record frames & no\\
5bb7df22ced2 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2076
diff changeset
  3040
5bb7df22ced2 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2076
diff changeset
  3041
\lstinline+--enable-eoe+ & Enable EoE support & yes\\
5bb7df22ced2 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2076
diff changeset
  3042
5bb7df22ced2 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2076
diff changeset
  3043
\lstinline+--enable-cycles+ & Use CPU timestamp counter. Enable this on Intel
5bb7df22ced2 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2076
diff changeset
  3044
architecture to get finer timing calculation. & no\\
5bb7df22ced2 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2076
diff changeset
  3045
5bb7df22ced2 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2076
diff changeset
  3046
\lstinline+--enable-hrtimer+ & Use high-resolution timer to let the master
5bb7df22ced2 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2076
diff changeset
  3047
state machine sleep between sending frames. & no\\
5bb7df22ced2 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2076
diff changeset
  3048
5bb7df22ced2 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2076
diff changeset
  3049
\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
  3050
1588
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  3051
\lstinline+--enable-tool+ & Build the command-line tool ``ethercat'' (see
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  3052
sec.~\ref{sec:tool}). & yes\\
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  3053
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  3054
\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
  3055
2153
5bb7df22ced2 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2076
diff changeset
  3056
\lstinline+--enable-tty+ & Build the TTY driver. & no\\
5bb7df22ced2 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2076
diff changeset
  3057
5bb7df22ced2 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2076
diff changeset
  3058
\lstinline+--enable-wildcards+ & Enable \textit{0xffffffff} to be wildcards
5bb7df22ced2 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2076
diff changeset
  3059
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
  3060
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3061
\hline
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3062
2153
5bb7df22ced2 Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents: 2076
diff changeset
  3063
\end{longtable}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3064
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3065
\begin{description}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3066
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3067
\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
  3068
extracted from the Linux kernel sources.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3069
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3070
\end{description}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3071
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  3072
\section{Building the Interface Documentation}
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3073
\label{sec:gendoc}
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3074
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3075
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
  3076
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
  3077
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
  3078
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3079
\begin{lstlisting}
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3080
$ `\textbf{make doc}`
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3081
\end{lstlisting}
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3082
1204
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
  3083
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
  3084
\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
  3085
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
  3086
Interface''.
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  3087
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  3088
\section{Installing the Software}
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3089
1106
745a0cc03143 Added depmod call to docs.
Florian Pose <fp@igh-essen.com>
parents: 1095
diff changeset
  3090
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
  3091
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
  3092
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
  3093
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
  3094
include the kernel modules into the \textit{modules.dep} file to make it
1106
745a0cc03143 Added depmod call to docs.
Florian Pose <fp@igh-essen.com>
parents: 1095
diff changeset
  3095
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
  3096
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3097
\begin{lstlisting}
1106
745a0cc03143 Added depmod call to docs.
Florian Pose <fp@igh-essen.com>
parents: 1095
diff changeset
  3098
# `\textbf{make install}`
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3099
# `\textbf{make modules\_install}`
1106
745a0cc03143 Added depmod call to docs.
Florian Pose <fp@igh-essen.com>
parents: 1095
diff changeset
  3100
# `\textbf{depmod}`
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3101
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3102
1095
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  3103
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
  3104
different destination directory can be specified with the \lstinline+DESTDIR+
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  3105
make variable. For example:
487
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
  3106
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3107
\begin{lstlisting}
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3108
# `\textbf{make DESTDIR=/vol/nfs/root modules\_install}`
487
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
  3109
\end{lstlisting}
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
  3110
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
  3111
This command will install the compiled kernel modules to
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
  3112
\textit{/vol/nfs/root/lib/modules}, prepended by the kernel release.
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
  3113
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3114
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
  3115
master shall not be loaded on system startup, the use of the init script is
1289
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  3116
recommended for manual (un-)loading.} (see sec.~\ref{sec:system}), the init
1086
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  3117
script and the sysconfig file have to be copied (or linked) to the appropriate
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  3118
locations. The below example is suitable for SUSE Linux. It may vary for other
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  3119
distributions.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3120
1107
Florian Pose <fp@igh-essen.com>
parents: 1106
diff changeset
  3121
% FIXME relative ln -s?
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3122
\begin{lstlisting}
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3123
# `\textbf{cd /opt/etherlab}`
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3124
# `\textbf{cp etc/sysconfig/ethercat /etc/sysconfig/}`
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3125
# `\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
  3126
# `\textbf{insserv ethercat}`
374
e43a29f9079e Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents: 371
diff changeset
  3127
\end{lstlisting}
e43a29f9079e Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents: 371
diff changeset
  3128
376
d1441d87f5c1 Documentation: EtherLab-CD; obtaining the DEVICE_INDEX.
Florian Pose <fp@igh-essen.com>
parents: 374
diff changeset
  3129
Now the sysconfig file \texttt{/etc/sysconfig/ethercat} (see
1289
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  3130
sec.~\ref{sec:sysconfig}) has to be customized. The minimal customization is
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  3131
to set the \lstinline+MASTER0_DEVICE+ variable to the MAC address of the
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3132
Ethernet device to use (or \lstinline+ff:ff:ff:ff:ff:ff+ to use the first
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3133
device offered) and selecting the driver(s) to load via the
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3134
\lstinline+DEVICE_MODULES+ variable.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3135
1297
129a7224e010 FIXME, TODO; typos.
Florian Pose <fp@igh-essen.com>
parents: 1296
diff changeset
  3136
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
  3137
below command:
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3138
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3139
\begin{lstlisting}
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3140
# `\textbf{/etc/init.d/ethercat start}`
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3141
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3142
1214
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  3143
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
  3144
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
  3145
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
  3146
indicators should begin to flash.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3147
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3148
\begin{lstlisting}[numbers=left]
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3149
EtherCAT: Master driver `\masterversion`
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3150
EtherCAT: 1 master waiting for devices.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3151
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
  3152
Copyright (c) 1999-2005 Intel Corporation.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3153
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
  3154
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
  3155
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
  3156
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
  3157
EtherCAT: Starting master thread.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3158
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
  3159
          Connection
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3160
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
  3161
          Full Duplex
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3162
EtherCAT: Link state changed to UP.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3163
EtherCAT: 7 slave(s) responding.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3164
EtherCAT: Slave states: PREOP.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3165
EtherCAT: Scanning bus.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3166
EtherCAT: Bus scanning completed in 431 ms.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3167
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3168
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3169
\begin{description}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3170
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3171
\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
  3172
is initialized.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3173
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3174
\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
  3175
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
  3176
\lstinline+00:0E:0C:DA:A2:20+.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3177
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3178
\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
  3179
state machine and begins scanning the bus.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3180
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3181
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3182
1214
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  3183
\section{Automatic Device Node Creation}
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  3184
\label{sec:autonode}
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  3185
1289
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  3186
The \lstinline+ethercat+ command-line tool (see sec.~\ref{sec:tool})
1214
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  3187
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
  3188
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
  3189
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
  3190
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  3191
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
  3192
\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
  3193
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
  3194
to be created with the following contents:
1214
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  3195
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  3196
\begin{lstlisting}
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  3197
KERNEL=="EtherCAT[0-9]*", MODE="0664"
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  3198
\end{lstlisting}
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  3199
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  3200
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
  3201
\lstinline[breaklines=true]+/etc/init.d/ethercat restart+, the device node
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  3202
will be automatically created with the desired rights:
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  3203
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  3204
\begin{lstlisting}
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  3205
# `\textbf{ls -l /dev/EtherCAT0}`
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  3206
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
  3207
\end{lstlisting}
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  3208
1289
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  3209
Now, the \lstinline+ethercat+ tool can be used (see sec.~\ref{sec:tool}) even
5b82b6b39c2d Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents: 1283
diff changeset
  3210
as a non-root user.
1214
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  3211
1306
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
  3212
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
  3213
used instead:
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
  3214
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
  3215
\begin{lstlisting}
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
  3216
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
  3217
\end{lstlisting}
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
  3218
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3219
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3220
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3221
\begin{thebibliography}{99}
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3222
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3223
\bibitem{etherlab} Ingenieurgemeinschaft IgH: EtherLab -- Open Source Toolkit
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3224
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
  3225
technology. \url{http://etherlab.org/en}, 2008.
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3226
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3227
\bibitem{dlspec} IEC 61158-4-12: Data-link Protocol Specification.
1095
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  3228
International Electrotechnical Commission (IEC), 2005.
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3229
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3230
\bibitem{alspec} IEC 61158-6-12: Application Layer Protocol Specification.
1095
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  3231
International Electrotechnical Commission (IEC), 2005.
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3232
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3233
\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
  3234
\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
  3235
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  3236
\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
  3237
\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
  3238
2008.
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3239
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3240
\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
  3241
\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
  3242
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3243
\bibitem{wireshark} Wireshark. \url{http://www.wireshark.org}. 2008.
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3244
1306
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
  3245
\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
  3246
Automata Theory, Languages and Computation. Adison-Wesley, Reading,
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3247
Mass.~1979.
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3248
1306
a27c839d043b merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents: 1299
diff changeset
  3249
\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
  3250
misunderstandings. In: IEE journal ``Computing and Control Engineering'',
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3251
2004.
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3252
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3253
\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
  3254
\url{https://www.rtai.org}, 2010.
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  3255
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  3256
\bibitem{rt-preempt} RT PREEMPT HOWTO.
2f6e6e7d31dd Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents: 1517
diff changeset
  3257
\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
  3258
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3259
\bibitem{doxygen} Doxygen. Source code documentation generator tool.
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3260
\url{http://www.stack.nl/~dimitri/doxygen}, 2008.
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3261
1772
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  3262
\bibitem{mercurial} Mercurial SCM. \url{http://mercurial.selenic.com}, 2010.
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  3263
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  3264
\bibitem{autoconf} Autoconf -- GNU Project -- Free Software Foundation (FSF).
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  3265
\url{http://www.gnu.org/software/autoconf}, 2010.
b4c85bedd68f Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents: 1592
diff changeset
  3266
1917
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  3267
\bibitem{soespec} IEC 61800-7-304: Adjustable speed electrical power drive
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  3268
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
  3269
systems - Mapping of profiles to network technologies. International
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  3270
Electrotechnical Commission (IEC), 2007.
6129a5f715fb SoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1772
diff changeset
  3271
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3272
\end{thebibliography}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3273
917
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
  3274
\printnomenclature
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3275
\addcontentsline{toc}{chapter}{\nomname}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3276
\markleft{\nomname}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3277
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3278
\printindex
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3279
\markleft{Index}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3280
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3281
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3282
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3283
\end{document}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3284
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3285
%------------------------------------------------------------------------------