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