documentation/ethercat_doc.tex
author Florian Pose <fp@igh-essen.com>
Mon, 20 Oct 2008 15:04:43 +0000
changeset 1282 d494455b64a2
parent 1281 9e9393cfc4f7
child 1283 e539c765f6a6
permissions -rw-r--r--
Completed library.
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}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    19
\usepackage{svn}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    20
\usepackage{textcomp}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    21
\usepackage{url}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
    22
\usepackage{SIunits}
1275
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
    23
\usepackage{hyperref}
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
    24
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
    25
\hypersetup{pdfpagelabels,plainpages=false}
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
    26
\hypersetup{linkcolor=blue,colorlinks=true,urlcolor=blue}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    27
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    28
\setlength{\parskip}{0.8ex plus 0.8ex minus 0.5ex}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    29
\setlength{\parindent}{0mm}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    30
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    31
\setcounter{secnumdepth}{\subsubsectionlevel}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    32
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    33
\DeclareFontShape{OT1}{cmtt}{bx}{n}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    34
{
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    35
  <5><6><7><8><9><10><10.95><12><14.4><17.28><20.74><24.88>cmttb10
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    36
}{}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    37
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    38
\lstset{basicstyle=\ttfamily\small,numberstyle=\tiny,aboveskip=4mm,
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
    39
  belowskip=2mm,escapechar=`}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    40
\renewcommand\lstlistlistingname{List of Listings}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    41
917
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    42
% Workaround for lstlistoflistings bug
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    43
\makeatletter% --> De-TeX-FAQ
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    44
\renewcommand*{\lstlistoflistings}{%
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    45
  \begingroup
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    46
    \if@twocolumn
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    47
      \@restonecoltrue\onecolumn
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    48
    \else
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    49
      \@restonecolfalse
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    50
    \fi
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    51
    \lol@heading
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    52
    \setlength{\parskip}{\z@}%
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    53
    \setlength{\parindent}{\z@}%
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    54
    \setlength{\parfillskip}{\z@ \@plus 1fil}%
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    55
    \@starttoc{lol}%
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    56
    \if@restonecol\twocolumn\fi
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    57
  \endgroup
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    58
}
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    59
\makeatother% --> \makeatletter
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    60
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    61
\renewcommand\nomname{Glossary}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    62
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    63
\newcommand{\IgH}{\raisebox{-0.7667ex}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    64
  {\includegraphics[height=2.2ex]{images/ighsign}}}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    65
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    66
\SVN $Date$
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    67
\SVN $Revision$
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    68
1270
11f4b6e10d74 Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1269
diff changeset
    69
\newcommand{\masterversion}{1.5.0}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
    70
\newcommand{\linenum}[1]{\normalfont\textcircled{\tiny #1}}
487
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
    71
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    72
\makeindex
917
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    73
\makenomenclature
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    74
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    75
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    76
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    77
\begin{document}
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
\pagenumbering{roman}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    80
\pagestyle{empty}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    81
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    82
\begin{titlepage}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    83
  \begin{center}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    84
    \rule{\textwidth}{1.5mm}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    85
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    86
    {\Huge\bf IgH \includegraphics[height=2.4ex]{images/ethercat}
487
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
    87
      Master \masterversion\\[1ex]
1204
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
    88
      Preliminary Documentation}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    89
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    90
    \vspace{1ex}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    91
    \rule{\textwidth}{1.5mm}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    92
1204
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
    93
    \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
    94
    \url{fp@igh-essen.com}\\[1ex] Ingenieurgemeinschaft \IgH}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    95
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    96
    \vspace{\fill}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    97
    {\Large Essen, \SVNDate\\[1ex]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    98
      Revision \SVNRevision}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    99
  \end{center}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   100
\end{titlepage}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   101
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   102
%------------------------------------------------------------------------------
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
\tableofcontents
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   105
\listoftables
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   106
\listoffigures
1204
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
   107
%\lstlistoflistings
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   108
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   109
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   110
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   111
\newpage
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   112
\pagestyle{scrheadings}
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
\section*{Conventions}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   115
\addcontentsline{toc}{section}{Conventions}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   116
\markleft{Conventions}
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
The following typographic conventions are used:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   119
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   120
\begin{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   121
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   122
\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
   123
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   124
\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
   125
output.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   126
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   127
\item \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
   128
lines.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   129
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   130
\end{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   131
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   132
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
   133
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
   134
\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
   135
values are specified as byte addresses.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   136
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   137
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
   138
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
   139
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
   140
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   141
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
   142
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   143
\begin{lstlisting}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   144
$
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   145
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   146
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   147
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
   148
prompt is a mesh:
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   149
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   150
\begin{lstlisting}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   151
#
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   152
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   153
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   154
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   155
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   156
\chapter{The IgH EtherCAT Master}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   157
\label{chapter:master}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   158
\pagenumbering{arabic}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   159
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   160
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
   161
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   162
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   163
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   164
\section{Feature Summary}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   165
\label{sec:summary}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   166
\index{Master!Features}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   167
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   168
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
   169
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   170
\begin{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   171
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   172
\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
   173
1086
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   174
\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
   175
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   176
\item Comes with EtherCAT-capable drivers for several common Ethernet devices.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   177
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   178
  \begin{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   179
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   180
  \item The Ethernet hardware is operated without interrupts.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   181
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   182
  \item Drivers for additional Ethernet hardware can easily be implemented
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   183
  using the common device interface (see section~\ref{sec:ecdev}) provided by
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   184
  the master module.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   185
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   186
  \end{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   187
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   188
\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
   189
parallel.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   190
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   191
\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
   192
independent architecture.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   193
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   194
  \begin{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   195
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   196
  \item RTAI\nomenclature{RTAI}{Realtime Application Interface},
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   197
  ADEOS\nomenclature{ADEOS}{Adaptive Domain Environment for Operating
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   198
  Systems}, etc.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   199
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   200
  \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
   201
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   202
  \end{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   203
1204
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
   204
\item Common ``Application Interface'' for applications, that want to use
1269
fe4688f2c9e7 sec:ecrt is a chapter; sec:eoeimp -> sec:eoe, ...
Florian Pose <fp@igh-essen.com>
parents: 1235
diff changeset
   205
EtherCAT functionality (see chap.~\ref{sec:ecrt}).
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   206
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   207
\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
   208
  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
   209
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   210
  \begin{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   211
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   212
  \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
   213
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   214
  \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
   215
  configuration within each domain.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   216
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   217
  \end{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   218
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   219
\item Communication through several finite state machines.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   220
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   221
  \begin{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   222
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   223
  \item Automatic bus scanning after topology changes.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   224
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   225
  \item Bus monitoring during operation.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   226
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   227
  \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
   228
  during operation.
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
  \end{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 CANopen-over-EtherCAT (CoE)
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   233
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   234
  \begin{itemize}
1085
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 Sdo upload, download and information service.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   237
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   238
  \item Slave configuration via Sdos.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   239
1275
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
   240
  \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
   241
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   242
  \end{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   243
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   244
\item Ethernet-over-EtherCAT (EoE)
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   245
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   246
  \begin{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   247
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   248
  \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
   249
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   250
  \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
   251
  architecture.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   252
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   253
  \end{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   254
1275
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
   255
\item Userspace command-line-tool ``ethercat`` (see
1140
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
   256
section~\ref{sec:ethercat})
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   257
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   258
  \begin{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   259
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   260
  \item Showing the current bus with slaves, Pdos and Sdos.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   261
  \item Showing the bus configuration.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   262
  \item Showing domains and process data.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   263
  \item Setting the master's debug level.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   264
  \item Writing alias addresses.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   265
  \item Sdo uploading/downloading.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   266
  \item Reading/writing a slave's SII.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   267
  \item Setting slave states.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   268
  \item Generate slave description XML.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   269
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   270
  \end{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   271
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   272
\item Seamless system integration though LSB\nomenclature{LSB}{Linux
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   273
    Standard Base} compliance.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   274
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   275
  \begin{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   276
1095
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   277
  \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
   278
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   279
  \item Init script for master control.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   280
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   281
  \end{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   282
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   283
\item Virtual read-only network interface for monitoring and debugging
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   284
  purposes.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   285
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   286
\end{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   287
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   288
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   289
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   290
\section{License}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   291
\label{sec:license}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   292
1275
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
   293
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
   294
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
   295
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
   296
even participate on development.
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
   297
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
   298
To allow static linking of userspace application against the master's
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
   299
application interface (see chap.~\ref{sec:ecrt}), the userspace library (see
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
   300
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
   301
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
   302
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   303
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   304
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   305
\chapter{Architecture}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   306
\label{sec:arch}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   307
\index{Master!Architecture}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   308
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   309
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
   310
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
   311
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   312
\begin{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   313
1275
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
   314
\item Kernel code has significantly better realtime characteristics,
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
   315
i.\,e.~less latency than userspace code. It was foreseeable, that a fieldbus
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
   316
master has a lot of cyclic work to do. Cyclic work is usually triggered by
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
   317
timer interrupts inside the kernel. The execution delay of a function that
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
   318
processes timer interrupts is less, when it resides in kernelspace, because
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
   319
there is no 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
   320
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   321
\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
   322
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
   323
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
   324
master code being in kernelspace.
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
\end{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   327
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   328
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
   329
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   330
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   331
  \centering
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   332
  \includegraphics[width=.9\textwidth]{images/architecture}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   333
  \caption{Master architecture}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   334
  \label{fig:arch}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   335
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   336
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   337
\paragraph{Master Module}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   338
\index{Master module}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   339
1086
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   340
Kernel module containing one or more EtherCAT master instances (see
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   341
section~\ref{sec:mastermod}), the ``Device Interface'' (see
1204
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
   342
section~\ref{sec:ecdev}) and the ``Application Interface'' (see
1269
fe4688f2c9e7 sec:ecrt is a chapter; sec:eoeimp -> sec:eoe, ...
Florian Pose <fp@igh-essen.com>
parents: 1235
diff changeset
   343
chap.~\ref{sec:ecrt}).
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   344
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   345
\paragraph{Device Modules}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   346
\index{Device modules}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   347
1086
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   348
EtherCAT-capable Ethernet device driver modules\index{Device modules}, that
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   349
offer their devices to the EtherCAT master via the device interface (see
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   350
section~\ref{sec:ecdev}). These modified network drivers can handle network
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   351
devices used for EtherCAT operation and ``normal'' Ethernet devices in
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   352
parallel. A master can accept a certain device and then is able to send and
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   353
receive EtherCAT frames. Ethernet devices declined by the master module are
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   354
connected to the kernel's network stack as usual.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   355
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   356
\paragraph{Application Modules}
1086
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   357
\index{Application module}
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   358
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   359
Kernel modules, that use the EtherCAT master (usually for cyclic exchange of
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   360
process data with EtherCAT slaves). These modules are not part of the EtherCAT
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   361
master code\footnote{Although there are some examples provided in the
1204
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
   362
\textit{examples/} directory.}, but have to be generated or written by the
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
   363
user. An application module can ``request'' a master through the application
1269
fe4688f2c9e7 sec:ecrt is a chapter; sec:eoeimp -> sec:eoe, ...
Florian Pose <fp@igh-essen.com>
parents: 1235
diff changeset
   364
interface (see chap.~\ref{sec:ecrt}). If this succeeds, the module has the
1204
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
   365
control over the master: It can provide a bus configuration and exchange
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
   366
process data.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   367
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   368
%------------------------------------------------------------------------------
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   369
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   370
\section{Phases}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   371
\index{Master phases}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   372
1086
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   373
The EtherCAT master runs through several phases (see fig.~\ref{fig:phases}):
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   374
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   375
\begin{figure}[htbp]
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   376
  \centering
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   377
  \includegraphics[width=.9\textwidth]{images/phases}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   378
  \caption{Master phases and transitions}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   379
  \label{fig:phases}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   380
\end{figure}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   381
\begin{description}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   382
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   383
\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
   384
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
   385
possible until then.
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   386
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   387
\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
   388
an Ethernet device, but is not requested by any application yet. The master
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   389
runs its state machine (see section~\ref{sec:fsm-master}), that automatically
1275
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
   390
scans the bus for slaves and executes pending operations from the userspace
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
   391
interface (for example Sdo access). The command-line tool can be used to
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
   392
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
   393
bus configuration.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   394
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   395
\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
   396
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
   397
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   398
\end{description}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   399
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   400
%------------------------------------------------------------------------------
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   401
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   402
\section{General Behavior} % FIXME
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   403
\index{Master behavior}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   404
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   405
\ldots
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   406
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   407
%   Behavior (Scanning) TODO
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   408
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   409
%------------------------------------------------------------------------------
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   410
1086
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   411
\section{Master Module}
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   412
\label{sec:mastermod}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   413
\index{Master module}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   414
1086
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   415
The EtherCAT master kernel module \textit{ec\_master} can contain multiple
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   416
master instances. Each master waits for a certain Ethernet device identified
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   417
by its MAC address\index{MAC address}. These addresses have to be specified on
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   418
module loading via the \textit{main\_devices} module parameter. The number of
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   419
master instances to initialize is taken from the number of MAC addresses
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   420
given.
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   421
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   422
The below command loads the master module with a single master instance that
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   423
waits for the Ethernet device with the MAC address
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   424
\lstinline+00:0E:0C:DA:A2:20+. The master will be accessible via index $0$.
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   425
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   426
\begin{lstlisting}
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   427
# `\textbf{modprobe ec\_master main\_devices=00:0E:0C:DA:A2:20}`
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   428
\end{lstlisting}
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   429
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   430
MAC addresses for multiple masters have to be separated by commas:
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   431
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   432
\begin{lstlisting}
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   433
# `\textbf{modprobe ec\_master main\_devices=00:0E:0C:DA:A2:20,00:e0:81:71:d5:1c}`
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   434
\end{lstlisting}
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   435
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   436
The two masters can be addressed by their indices 0 and 1 respectively (see
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   437
figure~\ref{fig:masters}). The master index is needed for the
1204
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
   438
\lstinline+ecrt_master_request()+ function of the application interface (see
1269
fe4688f2c9e7 sec:ecrt is a chapter; sec:eoeimp -> sec:eoe, ...
Florian Pose <fp@igh-essen.com>
parents: 1235
diff changeset
   439
chap.~\ref{sec:ecrt}) and the \lstinline+--master+ option of the
1086
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   440
\textit{ethercat} command-line tool (see section~\ref{sec:ethercat}), which
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   441
defaults to $0$.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   442
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   443
\begin{figure}[htbp]
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   444
  \centering
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   445
  \includegraphics[width=.5\textwidth]{images/masters}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   446
  \caption{Multiple masters in one module}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   447
  \label{fig:masters}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   448
\end{figure}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   449
1086
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   450
\paragraph{Init script}
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   451
\index{Init script}
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   452
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   453
Most probably you won't want to load the master module and the Ethernet driver
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   454
modules manually, but start the master as a service. See
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   455
section~\ref{sec:system} on how to do this.
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   456
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   457
\paragraph{Syslog}
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   458
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   459
The master module outputs information about it's state and events to the
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   460
kernel ring buffer. These also end up in the system logs.  The above module
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   461
loading command should result in the messages below:
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   462
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   463
\begin{lstlisting}
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   464
# `\textbf{dmesg | tail -2}`
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   465
EtherCAT: Master driver `\masterversion`
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   466
EtherCAT: 2 masters waiting for devices.
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   467
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   468
# `\textbf{tail -2 /var/log/messages}`
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   469
Jul  4 10:22:45 ethercat kernel: EtherCAT: Master driver `\masterversion`
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   470
Jul  4 10:22:45 ethercat kernel: EtherCAT: 2 masters waiting
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   471
                                 for devices.
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   472
\end{lstlisting}
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   473
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   474
All EtherCAT master output is prefixed with \lstinline+EtherCAT+ which makes
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   475
searching the logs easier.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   476
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   477
%------------------------------------------------------------------------------
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   478
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   479
\section{Handling of Process Data} % FIXME
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   480
\label{sec:processdata}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   481
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   482
\ldots
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   483
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   484
\paragraph{Process Data Image}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   485
\index{Process data}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   486
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   487
The slaves offer their inputs and outputs by presenting the master so-called
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   488
``Process Data Objects'' (Pdos\index{Pdo}). The available Pdos can be
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   489
determined by reading out the slave's TXPDO and RXPDO E$^2$PROM categories. The
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   490
application can register the Pdos for data exchange during cyclic operation.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   491
The sum of all registered Pdos defines the ``process data image'', which is
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   492
exchanged via the ``Logical ReadWrite'' datagrams introduced
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   493
in~\cite[section~5.4.2.4]{dlspec}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   494
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   495
\paragraph{Process Data Domains}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   496
\index{Domain}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   497
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   498
The process data image can be easily managed by creating so-called
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
   499
``domains'', which group Pdos and allocate the datagrams needed to
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   500
exchange them. Domains are mandatory for process data exchange, so
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   501
there has to be at least one. They were introduced for the following
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   502
reasons:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   503
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   504
\begin{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   505
\item The maximum size of a ``Logical ReadWrite'' datagram is limited
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   506
  due to the limited size of an Ethernet frame: The maximum data size
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   507
  is the Ethernet data field size minus the EtherCAT frame header,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   508
  EtherCAT datagram header and EtherCAT datagram footer: $1500 - 2 -
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   509
  12 - 2 = 1484$ octets. If the size of the process data image exceeds
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   510
  this limit, multiple frames have to be sent, and the image has to be
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   511
  partitioned for the use of multiple datagrams. A domain manages this
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   512
  automatically.
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
   513
\item Not every Pdo has to be exchanged with the same frequency: The
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
   514
  values of Pdos can vary slowly over time (for example temperature
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   515
  values), so exchanging them with a high frequency would just waste
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   516
  bus bandwidth. For this reason, multiple domains can be created, to
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
   517
  group different Pdos and so allow separate exchange.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   518
\end{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   519
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   520
There is no upper limit for the number of domains, but each domain
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   521
occupies one FMMU in each slave involved, so the maximum number of
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   522
domains is also limited by the slaves' capabilities.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   523
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   524
\paragraph{FMMU Configuration}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   525
\index{FMMU!Configuration}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   526
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   527
An application can register Pdos for process data exchange. Every
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
   528
Pdo is part of a memory area in the slave's physical memory, that is
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   529
protected by a sync manager \cite[section~6.7]{dlspec} for
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   530
synchronized access. In order to make a sync manager react on a
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   531
datagram accessing its memory, it is necessary to access the last byte
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   532
covered by the sync manager. Otherwise the sync manager will not react
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   533
on the datagram and no data will be exchanged. That is why the whole
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   534
synchronized memory area has to be included into the process data
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
   535
image: For example, if a certain Pdo of a slave is registered for
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   536
exchange with a certain domain, one FMMU will be configured to map the
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
   537
complete sync-manager-protected memory, the Pdo resides in. If a
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
   538
second Pdo of the same slave is registered for process data exchange
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
   539
within the same domain, and this Pdo resides in the same
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
   540
sync-manager-protected memory as the first Pdo, the FMMU configuration
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   541
is not touched, because the appropriate memory is already part of the
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
   542
domain's process data image.  If the second Pdo belongs to another
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   543
sync-manager-protected area, this complete area is also included into
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   544
the domains process data image. See figure~\ref{fig:fmmus} for an
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   545
overview, how FMMU's are configured to map physical memory to logical
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   546
process data images.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   547
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   548
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   549
  \centering
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   550
  \includegraphics[width=\textwidth]{images/fmmus}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   551
  \caption{FMMU configuration for several domains}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   552
  \label{fig:fmmus}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   553
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   554
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   555
\paragraph{Process Data Pointers} % FIXME
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   556
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   557
The figure also demonstrates the way, the application can access the exchanged
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   558
process data: At Pdo registration, the application has to provide the address
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   559
of a process data pointer. Upon calculation of the domain image and allocation
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   560
of process data memory, this pointer is redirected to the appropriate location
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   561
inside the domain's process data memory and can later be easily dereferenced by
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   562
the module code.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   563
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   564
%------------------------------------------------------------------------------
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   565
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   566
\chapter{Application Interface}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   567
\label{sec:ecrt}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   568
\index{Application interface}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   569
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   570
%   Interface version
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   571
%   Master Requesting and Releasing
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   572
%   Master Locking
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   573
%   Slave configuration
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   574
%   Configuring Pdo assignment and mapping
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   575
%   Domains (memory)
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   576
%   Pdo entry registration
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   577
%   Sdo configuration
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   578
%   Sdo access
1270
11f4b6e10d74 Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1269
diff changeset
   579
%   VoE handlers
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   580
%   Cyclic operation
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   581
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   582
The application interface provides functions and data structures for
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   583
applications to access and use an EtherCAT master. The complete documentation
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   584
of the interface is included as Doxygen~\cite{doxygen} comments in the header
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   585
file \textit{include/ecrt.h}. You can either directly view the file comments
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   586
or generate an HTML documentation as described in section~\ref{sec:gendoc}.
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   587
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   588
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
   589
interface.
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   590
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   591
Every application should use the master in two steps:
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   592
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   593
\begin{description}
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   594
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   595
\item[Configuration] The master is requested and the configuration is applied.
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   596
Domains are created Slaves are configured and Pdo entries are registered (see
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   597
section~\ref{sec:masterconfig}).
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   598
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   599
\item[Operation] Cyclic code is run, process data is exchanged (see
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   600
section~\ref{sec:cyclic}).
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   601
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   602
\end{description}
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   603
1204
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
   604
\paragraph{Example Applications} \index{Example Applications} There are a few
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
   605
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
   606
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
   607
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   608
%------------------------------------------------------------------------------
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   609
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   610
\section{Master Configuration}
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   611
\label{sec:masterconfig}
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   612
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   613
\ldots
1204
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
   614
% FIXME Attaching
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   615
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   616
\begin{figure}[htbp]
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   617
  \centering
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   618
  \includegraphics[width=.8\textwidth]{images/app-config}
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
   619
  \caption{Master Configuration}
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   620
  \label{fig:app-config}
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   621
\end{figure}
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   622
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   623
%------------------------------------------------------------------------------
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
\section{Cyclic Operation}
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   626
\label{sec:cyclic}
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
\ldots
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   629
% FIXME PDOS endianess
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   630
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
%------------------------------------------------------------------------------
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   633
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   634
\section{Concurrent Master Access} % FIXME
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   635
\label{sec:concurr}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   636
\index{Concurrency}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   637
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   638
In some cases, one master is used by several instances, for example when an
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   639
application does cyclic process data exchange, and there are EoE-capable slaves
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   640
that require to exchange Ethernet data with the kernel (see
1269
fe4688f2c9e7 sec:ecrt is a chapter; sec:eoeimp -> sec:eoe, ...
Florian Pose <fp@igh-essen.com>
parents: 1235
diff changeset
   641
section~\ref{sec:eoe}). For this reason, the master is a shared resource,
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   642
and access to it has to be sequentialized. This is usually done by locking with
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   643
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
   644
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   645
The master itself can not provide locking mechanisms, because it has no chance
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   646
to know the appropriate kind of lock. For example if the application uses RTAI
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   647
functionality, ordinary kernel semaphores would not be sufficient. For that, an
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   648
important design decision was made: The application that reserved a master must
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   649
have the total control, therefore it has to take responsibility for providing
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   650
the appropriate locking mechanisms. If another instance wants to access the
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   651
master, it has to request the master lock by callbacks, that have to be set by
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   652
the application. Moreover the application can deny access to the master if it
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   653
considers it to be awkward at the moment.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   654
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   655
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   656
  \centering
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   657
  \includegraphics[width=.6\textwidth]{images/master-locks}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   658
  \caption{Concurrent master access}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   659
  \label{fig:locks}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   660
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   661
1204
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
   662
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
   663
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
   664
the master-internal EoE process uses it to communicate with EoE-capable
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
   665
slaves.  Both have to acquire the master lock before access: The application
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
   666
task can access the lock natively, while the EoE process has to use the
1269
fe4688f2c9e7 sec:ecrt is a chapter; sec:eoeimp -> sec:eoe, ...
Florian Pose <fp@igh-essen.com>
parents: 1235
diff changeset
   667
callbacks.  See the application interface documentation (chap.~\ref{sec:ecrt}
fe4688f2c9e7 sec:ecrt is a chapter; sec:eoeimp -> sec:eoe, ...
Florian Pose <fp@igh-essen.com>
parents: 1235
diff changeset
   668
of how to use the locking callbacks.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   669
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   670
%------------------------------------------------------------------------------
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   671
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   672
\chapter{Ethernet Devices}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   673
\label{sec:devices}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   674
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
   675
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
   676
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
   677
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   678
The term \textit{device} is used as a synonym for Ethernet network interface
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   679
hardware. There are device driver modules that handle Ethernet hardware, which
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
   680
a master can use to connect to an EtherCAT bus.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   681
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   682
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   683
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   684
\section{Network Driver Basics}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   685
\label{sec:networkdrivers}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   686
\index{Network drivers}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   687
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   688
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
   689
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
   690
to understand how Linux handles network devices and their drivers,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   691
respectively.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   692
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   693
\paragraph{Tasks of a Network Driver}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   694
1095
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   695
Network device drivers usually handle the lower two layers of the OSI model,
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   696
that is the physical layer and the data-link layer. A network device itself
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   697
natively handles the physical layer issues: It represents the hardware to
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   698
connect to the medium and to send and receive data in the way, the physical
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   699
layer protocol describes. The network device driver is responsible for getting
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   700
data from the kernel's networking stack and forwarding it to the hardware,
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   701
that does the physical transmission.  If data is received by the hardware
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   702
respectively, the driver is notified (usually by means of an interrupt) and
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   703
has to read the data from the hardware memory and forward it to the network
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   704
stack. There are a few more tasks, a network device driver has to handle,
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   705
including queue control, statistics and device dependent features.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   706
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   707
\paragraph{Driver Startup}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   708
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   709
Usually, a driver searches for compatible devices on module loading.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   710
For PCI drivers, this is done by scanning the PCI bus and checking for
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   711
known device IDs. If a device is found, data structures are allocated
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   712
and the device is taken into operation.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   713
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   714
\paragraph{Interrupt Operation}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   715
\index{Interrupt}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   716
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   717
A network device usually provides a hardware interrupt that is used to
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   718
notify the driver of received frames and success of transmission, or
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   719
errors, respectively. The driver has to register an interrupt service
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   720
routine (ISR\index{ISR}\nomenclature{ISR}{Interrupt Service Routine}),
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   721
that is executed each time, the hardware signals such an event. If the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   722
interrupt was thrown by the own device (multiple devices can share one
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   723
hardware interrupt), the reason for the interrupt has to be determined
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   724
by reading the device's interrupt register. For example, if the flag
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   725
for received frames is set, frame data has to be copied from hardware
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   726
to kernel memory and passed to the network stack.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   727
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
   728
\paragraph{The \lstinline+net_device+ Structure}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   729
\index{net\_device}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   730
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   731
The driver registers a \lstinline+net_device+ structure for each device to
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   732
communicate with the network stack and to create a ``network interface''. In
1275
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
   733
case of an Ethernet driver, this interface appears as \textit{ethX}, where X
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
   734
is a number assigned by the kernel on registration. The \lstinline+net_device+
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
   735
structure receives events (either from userspace or from the network stack)
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   736
via several callbacks, which have to be set before registration. Not every
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   737
callback is mandatory, but for reasonable operation the ones below are needed
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   738
in any case:
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   739
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   740
\newsavebox\boxopen
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   741
\sbox\boxopen{\lstinline+open()+}
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   742
\newsavebox\boxstop
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   743
\sbox\boxstop{\lstinline+stop()+}
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   744
\newsavebox\boxxmit
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   745
\sbox\boxxmit{\lstinline+hard_start_xmit()+}
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   746
\newsavebox\boxstats
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   747
\sbox\boxstats{\lstinline+get_stats()+}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   748
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   749
\begin{description}
1095
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   750
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   751
\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
   752
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
   753
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
   754
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   755
\item[\usebox\boxstop] The purpose of this callback is to ``close'' the device,
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   756
i.~e.  make the hardware stop receiving frames.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   757
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   758
\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
   759
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
   760
\lstinline+sk_buff+ structure (``socket buffer''\index{Socket buffer}, see
1095
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   761
below), which has to be freed after sending.
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   762
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   763
\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
   764
\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
   765
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
   766
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
   767
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   768
\end{description}
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   769
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   770
The actual registration is done with the \lstinline+register_netdev()+ call,
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   771
unregistering is done with \lstinline+unregister_netdev()+.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   772
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
   773
\paragraph{The \lstinline+netif+ Interface}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   774
\index{netif}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   775
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   776
All other communication in the direction interface $\to$ network stack is done
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   777
via the \lstinline+netif_*()+ calls. For example, on successful device opening,
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   778
the network stack has to be notified, that it can now pass frames to the
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   779
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
   780
call, the \lstinline+hard_start_xmit()+ callback can be called by the network
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   781
stack. Furthermore a network driver usually manages a frame transmission queue.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   782
If this gets filled up, the network stack has to be told to stop passing
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   783
further frames for a while. This happens with a call to
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   784
\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
   785
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
   786
\lstinline+netif_wake_queue()+. Another important call is
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   787
\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
   788
(``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
   789
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
   790
network performance on Linux. Read more in
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   791
\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
   792
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
   793
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
   794
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   795
\paragraph{Socket Buffers}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   796
\index{Socket buffer}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   797
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   798
Socket buffers are the basic data type for the whole network stack. They serve
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   799
as containers for network data and are able to quickly add data headers and
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   800
footers, or strip them off again. Therefore a socket buffer consists of an
1095
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   801
allocated buffer and several pointers that mark beginning of the buffer
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   802
(\lstinline+head+), beginning of data (\lstinline+data+), end of data
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   803
(\lstinline+tail+) and end of buffer (\lstinline+end+). In addition, a socket
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   804
buffer holds network header information and (in case of received data) a
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   805
pointer to the \lstinline+net_device+, it was received on. There exist
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   806
functions that create a socket buffer (\lstinline+dev_alloc_skb()+), add data
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   807
either from front (\lstinline+skb_push()+) or back (\lstinline+skb_put()+),
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   808
remove data from front (\lstinline+skb_pull()+) or back
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   809
(\lstinline+skb_trim()+), or delete the buffer (\lstinline+kfree_skb()+).  A
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   810
socket buffer is passed from layer to layer, and is freed by the layer that
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   811
uses it the last time. In case of sending, freeing has to be done by the
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   812
network driver.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   813
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   814
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   815
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   816
\section{EtherCAT Device Drivers}
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
   817
\label{sec:ethercatdrivers}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   818
1095
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   819
There are a few requirements for Ethernet network devices to function as
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   820
EtherCAT devices, when connected to an EtherCAT bus.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   821
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   822
\paragraph{Dedicated Interfaces}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   823
1095
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   824
For performance and realtime purposes, the EtherCAT master needs direct and
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   825
exclusive access to the Ethernet hardware. This implies that the network device
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   826
must not be connected to the kernel's network stack as usual, because the
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   827
kernel would try to use it as an ordinary Ethernet device.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   828
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   829
\paragraph{Interrupt-less Operation}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   830
\index{Interrupt}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   831
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   832
EtherCAT frames travel through the logical EtherCAT ring and are then sent back
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   833
to the master. Communication is highly deterministic: A frame is sent and will
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   834
be received again after a constant time, so there is no need to notify the
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   835
driver about frame reception: The master can instead query the hardware for
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   836
received frames, if it expects them to be already received.
1095
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   837
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   838
Figure~\ref{fig:interrupt} shows two workflows for cyclic frame transmission
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   839
and reception with and without interrupts.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   840
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   841
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   842
  \centering
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   843
  \includegraphics[width=.9\textwidth]{images/interrupt}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   844
  \caption{Interrupt Operation versus Interrupt-less Operation}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   845
  \label{fig:interrupt}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   846
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   847
1095
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   848
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
   849
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
   850
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
   851
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
   852
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
   853
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
   854
processing in the next cycle.
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   855
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   856
In the right workflow ``Interrupt-less Operation'', there is no hardware
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   857
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
   858
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
   859
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
   860
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
   861
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
   862
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   863
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
   864
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
   865
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
   866
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
   867
prioritize interrupts.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   868
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   869
\paragraph{Ethernet and EtherCAT Devices}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   870
1095
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   871
Another issue lies in the way Linux handles devices of the same type.  For
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   872
example, a PCI\nomenclature{PCI}{Peripheral Component Interconnect, Computer
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   873
Bus} driver scans the PCI bus for devices it can handle. Then it registers
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   874
itself as the responsible driver for all of the devices found. The problem is,
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   875
that an unmodified driver can not be told to ignore a device because it will
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   876
be used for EtherCAT later. There must be a way to handle multiple devices of
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   877
the same type, where one is reserved for EtherCAT, while the other is treated
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   878
as an ordinary Ethernet device.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   879
1095
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   880
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
   881
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
   882
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
   883
EtherCAT-capable.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   884
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   885
Below are the advantages of this solution:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   886
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   887
\begin{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   888
\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
   889
\item One networking driver for EtherCAT and non-EtherCAT devices.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   890
\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
   891
  into issues, the former developers already solved.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   892
\end{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   893
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   894
The chosen approach has the following disadvantages:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   895
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   896
\begin{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   897
\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
   898
  EtherCAT and non-EtherCAT devices.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   899
\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
   900
\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
   901
  to the Ether\-CAT-capable versions from time to time.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   902
\end{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   903
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   904
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   905
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   906
\section{Device Selection}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   907
\label{sec:deviceselection}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   908
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   909
After loading the master module, at least one EtherCAT-capable network driver
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   910
module has to be loaded, that offers its devices to the master (see
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   911
section~\ref{sec:ecdev}. The master module knows the devices to choose from the
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   912
module parameters (see section~\ref{sec:mastermod}). If the init script is used
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   913
to start the master, the drivers and devices to use can be specified in the
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   914
sysconfig file (see section~\ref{sec:sysconfig}).
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   915
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   916
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   917
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
   918
\section{EtherCAT Device Interface}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   919
\label{sec:ecdev}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   920
\index{Device interface}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   921
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   922
An anticipation to the section about the master module
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   923
(section~\ref{sec:mastermod}) has to be made in order to understand
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   924
the way, a network device driver module can connect a device to a
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   925
specific EtherCAT master.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   926
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   927
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
   928
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
   929
\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
   930
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
   931
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
   932
\lstinline+ecdev+.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   933
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   934
The documentation of the device interface can be found in the header file or in
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   935
the appropriate module of the interface documentation (see
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   936
section~\ref{sec:gendoc} for generation instructions).
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   937
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   938
\ldots % FIXME general description of the device interface
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   939
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   940
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   941
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   942
\section{Patching Network Drivers}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   943
\label{sec:patching}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   944
\index{Network drivers}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   945
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   946
This section will describe, how to make a standard Ethernet driver
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   947
EtherCAT-capable. Unfortunately, there is no standard procedure to enable an
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   948
Ethernet driver for use with the EtherCAT master, but there are a few common
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   949
techniques.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   950
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   951
\begin{enumerate}
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   952
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   953
\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
   954
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
   955
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
   956
functions.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   957
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   958
\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
   959
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
   960
interrupts at hardware level must be avoided, too.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   961
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   962
\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
   963
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
   964
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
   965
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
   966
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
   967
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   968
\end{enumerate}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   969
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   970
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
   971
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
   972
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
   973
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
   974
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
   975
\lstinline+ec_device_t+ object returned by \lstinline+ecdev_offer()+ (see
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   976
section~\ref{sec:ecdev}) if the device is used by a master and otherwise is
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   977
zero.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   978
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
   979
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
   980
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
   981
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
   982
\textit{devices/8139too-2.6.24-ethercat.c}.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   983
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   984
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   985
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   986
\chapter{State Machines}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   987
\label{sec:fsm}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   988
\index{FSM}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   989
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   990
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
   991
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
   992
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
   993
possibilities.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   994
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   995
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
   996
states and moreover illustrates the restrictions of ``sequential''
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   997
coding:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   998
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   999
\begin{lstlisting}[gobble=2,language=C,numbers=left]
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1000
  ec_datagram_brd(datagram, 0x0130, 2); // prepare datagram
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1001
  if (ec_master_simple_io(master, datagram)) return -1;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1002
  slave_states = EC_READ_U8(datagram->data); // process datagram
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1003
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1004
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1005
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
  1006
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
  1007
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
  1008
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
  1009
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
  1010
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
  1011
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
  1012
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1013
This sequential approach is very simple, reflecting in only three
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1014
lines of code. The disadvantage is, that the master is blocked for the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1015
time it waits for datagram reception. There is no difficulty when only
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1016
one instance is using the master, but if more instances want to
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1017
(synchronously\footnote{At this time, synchronous master access will
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1018
  be adequate to show the advantages of an FSM. The asynchronous
1269
fe4688f2c9e7 sec:ecrt is a chapter; sec:eoeimp -> sec:eoe, ...
Florian Pose <fp@igh-essen.com>
parents: 1235
diff changeset
  1019
  approach will be discussed in section~\ref{sec:eoe}}) use the
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1020
master, it is inevitable to think about an alternative to the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1021
sequential model.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1022
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1023
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
  1024
wanting to send and receive datagrams synchronously. With the present
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1025
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
  1026
each instance, which would be non-acceptable especially in realtime
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1027
circumstances, because of the huge time overhead.
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
A possible solution is, that all instances would be executed
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1030
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
  1031
next instance instead of waiting for the datagram reception. Finally,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1032
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
  1033
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
  1034
instances again, which then process their received datagrams and issue
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1035
new ones.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1036
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1037
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
  1038
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
  1039
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
  1040
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
  1041
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
  1042
from above as a state machine:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1043
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1044
\begin{lstlisting}[gobble=2,language=C,numbers=left]
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1045
  // state 1
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1046
  ec_datagram_brd(datagram, 0x0130, 2); // prepare datagram
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1047
  ec_master_queue(master, datagram); // queue datagram
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1048
  next_state = state_2;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1049
  // state processing finished
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1050
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1051
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1052
After all instances executed their current state and queued their
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1053
datagrams, these are sent and received. Then the respective next
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1054
states are executed:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1055
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1056
\begin{lstlisting}[gobble=2,language=C,numbers=left]
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1057
  // state 2
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1058
  if (datagram->state != EC_DGRAM_STATE_RECEIVED) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1059
          next_state = state_error;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1060
          return; // state processing finished
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1061
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1062
  slave_states = EC_READ_U8(datagram->data); // process datagram
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1063
  // state processing finished.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1064
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1065
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1066
See section~\ref{sec:statemodel} for an introduction to the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1067
state machine programming concept used in the master code.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1068
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1069
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1070
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1071
\section{State Machine Theory}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1072
\label{sec:fsmtheory}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1073
\index{FSM!Theory}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1074
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1075
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
  1076
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
  1077
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
  1078
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
  1079
S, s_0, \delta, \omega)$, with
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1080
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1081
\begin{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1082
\item the input alphabet $\Sigma$, with $\Sigma \neq
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1083
  \emptyset$, containing all input symbols,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1084
\item the output alphabet $\Gamma$, with $\Gamma \neq
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1085
  \emptyset$, containing all output symbols,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1086
\item the set of states $S$, with $S \neq \emptyset$,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1087
\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
  1088
  \emptyset$
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1089
\item the transition function $\delta: S \times \Sigma \rightarrow S
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1090
  \times \Gamma$
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1091
\item the output function $\omega$.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1092
\end{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1093
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1094
The state transition function $\delta$ is often specified by a
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1095
\textit{state transition table}, or by a \textit{state transition
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1096
  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
  1097
machine behavior (see table~\ref{tab:statetrans}). The matrix rows
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1098
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
  1099
correspond to the input symbols ($\Gamma = \{a, b, \varepsilon\}$).
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1100
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
  1101
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
  1102
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
  1103
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1104
\begin{table}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1105
  \caption{A typical state transition table}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1106
  \label{tab:statetrans}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1107
  \vspace{2mm}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1108
  \centering
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1109
  \begin{tabular}{l|ccc}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1110
    & $a$ & $b$ & $\varepsilon$\\ \hline
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1111
    $s_0$ & $s_1$ & $s_1$ & $s_2$\\
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1112
    $s_1$ & $s_2$ & $s_1$ & $s_0$\\
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1113
    $s_2$ & $s_0$ & $s_0$ & $s_0$\\ \hline
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1114
  \end{tabular}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1115
\end{table}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1116
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1117
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
  1118
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
  1119
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
  1120
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
  1121
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
  1122
circle with an arrow pointing to the respective state.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1123
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1124
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1125
  \centering
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1126
  \includegraphics[width=.5\textwidth]{images/statetrans}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1127
  \caption{A typical state transition diagram}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1128
  \label{fig:statetrans}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1129
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1130
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1131
\paragraph{Deterministic and non-deterministic state machines}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1132
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1133
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
  1134
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
  1135
state machine has exactly one starting state. Non-deterministic state
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1136
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
  1137
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
  1138
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1139
\paragraph{Moore and Mealy machines}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1140
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1141
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
  1142
\textit{Mealy machines}. Mathematically spoken, the distinction lies
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1143
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
  1144
state ($\omega: S \rightarrow \Gamma$), the machine corresponds to the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1145
``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
  1146
the input alphabet ($\omega: S \times \Sigma \rightarrow \Gamma$) the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1147
state machine corresponds to the ``Mealy model''. Mealy machines are
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1148
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
  1149
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
  1150
both models is often used.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1151
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1152
\paragraph{Misunderstandings about state machines}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1153
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1154
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
  1155
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
  1156
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
  1157
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
  1158
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
  1159
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
  1160
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
  1161
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
  1162
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1163
%------------------------------------------------------------------------------
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1164
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1165
\section{The Master's State Model}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1166
\label{sec:statemodel}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1167
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1168
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
  1169
implement state machines.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1170
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1171
\paragraph{State Machine Programming}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1172
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1173
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
  1174
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
  1175
by one big case differentiation:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1176
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1177
\begin{lstlisting}[gobble=2,language=C,numbers=left]
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1178
  enum {STATE_1, STATE_2, STATE_3};
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1179
  int state = STATE_1;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1180
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1181
  void state_machine_run(void *priv_data) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1182
          switch (state) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1183
                  case STATE_1:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1184
                          action_1();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1185
                          state = STATE_2;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1186
                          break;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1187
                  case STATE_2:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1188
                          action_2()
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1189
                          if (some_condition) state = STATE_1;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1190
                          else state = STATE_3;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1191
                          break;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1192
                  case STATE_3:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1193
                          action_3();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1194
                          state = STATE_1;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1195
                          break;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1196
          }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1197
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1198
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1199
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1200
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
  1201
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
  1202
additional case differentiation is executed each run. Besides, lots of
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1203
indentation is wasted.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1204
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1205
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
  1206
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
  1207
pointer:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1208
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1209
\begin{lstlisting}[gobble=2,language=C,numbers=left]
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1210
  void (*state)(void *) = state1;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1211
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1212
  void state_machine_run(void *priv_data) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1213
          state(priv_data);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1214
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1215
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1216
  void state1(void *priv_data) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1217
          action_1();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1218
          state = state2;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1219
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1220
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1221
  void state2(void *priv_data) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1222
          action_2();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1223
          if (some_condition) state = state1;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1224
          else state = state2;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1225
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1226
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1227
  void state3(void *priv_data) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1228
          action_3();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1229
          state = state1;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1230
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1231
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1232
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1233
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
  1234
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
  1235
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
  1236
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
  1237
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
  1238
available and can be started on demand.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1239
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1240
\paragraph{Mealy and Moore}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1241
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1242
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
  1243
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
  1244
current state. This accords to the ``Moore'' model introduced in
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1245
section~\ref{sec:fsmtheory}. As mentioned, the ``Mealy'' model offers a higher
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1246
flexibility, which can be seen in the listing below:
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1247
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1248
\begin{lstlisting}[gobble=2,language=C,numbers=left]
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1249
  void state7(void *priv_data) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1250
          if (some_condition) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1251
                  action_7a();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1252
                  state = state1;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1253
          }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1254
          else {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1255
                  action_7b();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1256
                  state = state8;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1257
          }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1258
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1259
\end{lstlisting}
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
\begin{description}
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1262
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1263
\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
  1264
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
  1265
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1266
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1267
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1268
The most flexible alternative is to execute certain actions depending
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1269
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
  1270
transition:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1271
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1272
\begin{lstlisting}[gobble=2,language=C,numbers=left]
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1273
  void state9(void *priv_data) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1274
          action_9();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1275
          if (some_condition) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1276
                  action_9a();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1277
                  state = state7;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1278
          }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1279
          else {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1280
                  action_9b();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1281
                  state = state10;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1282
          }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1283
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1284
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1285
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1286
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
  1287
approaches.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1288
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1289
\paragraph{Using Sub State Machines}
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
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
  1292
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
  1293
encapsulate the related workflows and moreover avoids the ``state explosion''
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1294
phenomenon described in section~\ref{sec:fsmtheory}. If the master would
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1295
instead use one big state machine, the number of states would be a multiple of
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1296
the actual number. This would increase the level of complexity to a
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1297
non-manageable grade.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1298
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1299
\paragraph{Executing Sub State Machines}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1300
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1301
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
  1302
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
  1303
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
  1304
slave configuration state machine code:
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
\begin{lstlisting}[gobble=2,language=C,numbers=left]
813
bfc3f1ab52de Fixed typo SAVEOP -> SAFEOP.
Florian Pose <fp@igh-essen.com>
parents: 487
diff changeset
  1307
  void ec_fsm_slaveconf_safeop(ec_fsm_t *fsm)
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1308
  {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1309
          fsm->change_state(fsm); // execute state change
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1310
                                  // sub state machine
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1311
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1312
          if (fsm->change_state == ec_fsm_error) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1313
                  fsm->slave_state = ec_fsm_end;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1314
                  return;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1315
          }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1316
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1317
          if (fsm->change_state != ec_fsm_end) return;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1318
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1319
          // continue state processing
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1320
          ...
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1321
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1322
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1323
\begin{description}
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1324
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1325
\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
  1326
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
  1327
executed\ldots
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1328
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1329
\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
  1330
error state \ldots
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1331
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1332
\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
  1333
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
  1334
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
  1335
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1336
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1337
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1338
\paragraph{State Machine Descriptions}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1339
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1340
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
  1341
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
  1342
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
  1343
with an arrow followed by the name of the successive state. Transitions caused
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1344
by trivial error cases (i.~e. no response from slave) are not described
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1345
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
  1346
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1347
%------------------------------------------------------------------------------
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1348
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1349
\section{The Master State Machine}
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1350
\label{sec:fsm-master}
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1351
\index{FSM!Master}
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1352
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1353
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
  1354
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
  1355
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1356
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1357
  \centering
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1358
  \includegraphics[width=\textwidth]{graphs/fsm_master}
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1359
  \caption{Transition diagram of the master state machine}
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1360
  \label{fig:fsm-master}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1361
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1362
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1363
\begin{description}
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1364
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1365
\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
  1366
(re-)scanned.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1367
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1368
\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
  1369
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
  1370
(re-)configured.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1371
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1372
\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
  1373
from external sources) are handled. A request is a job that the master shall
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1374
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
  1375
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1376
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1377
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1378
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1379
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1380
\section{The Slave Scan State Machine}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1381
\label{sec:fsm-scan}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1382
\index{FSM!Slave Scan}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1383
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1384
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
  1385
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
  1386
slave information.
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
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1389
  \centering
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1390
  \includegraphics[height=.8\textheight]{graphs/fsm_slave_scan}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1391
  \caption{Transition diagram of the slave scan state machine}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1392
  \label{fig:fsm-slavescan}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1393
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1394
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1395
The scan process includes the following steps:
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1396
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1397
\begin{description}
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1398
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1399
\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
  1400
node-addressed for all following operations.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1401
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1402
\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
  1403
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1404
\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
  1405
is read from the lower physical memory.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1406
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1407
\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
  1408
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1409
\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
  1410
image memory.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1411
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1412
\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
  1413
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1414
\item[PREOP] If the slave supports CoE, it is set to PREOP state using the
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1415
State change FSM (see section~\ref{sec:fsm-change}) to enable mailbox
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1416
communication and read the Pdo configuration via CoE.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1417
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1418
\item[Pdos] The Pdos are read via CoE (if supported) using the Pdo Reading FSM
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1419
(see section~\ref{sec:fsm-pdo}). If this is successful, the Pdo information
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1420
from the SII (if any) is overwritten.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1421
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1422
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1423
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1424
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1425
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1426
\section{The Slave Configuration State Machine}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1427
\label{sec:fsm-conf}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1428
\index{FSM!Slave Configuration}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1429
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1430
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
  1431
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
  1432
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
  1433
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1434
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1435
  \centering
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1436
  \includegraphics[height=.9\textheight]{graphs/fsm_slave_conf}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1437
  \caption{Transition diagram of the slave configuration state
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1438
    machine}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1439
  \label{fig:fsm-slaveconf}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1440
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1441
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1442
\begin{description}
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1443
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1444
\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
  1445
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1446
\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
  1447
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
  1448
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
  1449
finished.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1450
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1451
\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
  1452
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
  1453
is skipped.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1454
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1455
\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
  1456
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
  1457
1204
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
  1458
\item[Sdo Configuration] If there is a slave configuration attached (see
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
  1459
section~\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
  1460
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
  1461
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1462
\item[Pdo Configuration] The Pdo configuration state machine is executed to
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1463
apply all necessary Pdo configurations.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1464
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1465
\item[Pdo Sync Manager Configuration] If any Pdo sync managers exist, they are
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1466
configured.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1467
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1468
\item[FMMU Configuration] If there are FMMUs configurations supplied by the
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1469
application (i.~e. if the application registered Pdo entries), they are
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1470
applied. 
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1471
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1472
\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
  1473
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
  1474
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1475
\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
  1476
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
  1477
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1478
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1479
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1480
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1481
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1482
\section{The State Change State Machine}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1483
\label{sec:fsm-change}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1484
\index{FSM!State Change}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1485
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1486
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
  1487
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
  1488
application-layer state. This implements the states and transitions described
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1489
in \cite[section~6.4.1]{alspec}.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1490
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1491
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1492
  \centering
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1493
  \includegraphics[width=.6\textwidth]{graphs/fsm_change}
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1494
  \caption{Transition Diagram of the State Change State Machine}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1495
  \label{fig:fsm-change}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1496
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1497
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1498
\begin{description}
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1499
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1500
\item[Start] The new application-layer state is requested via the ``AL Control
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1501
Request'' register (see ~\cite[section 5.3.1]{alspec}).
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1502
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1503
\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
  1504
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
  1505
is issued again, until it is acknowledged.
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1506
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1507
\item[Check AL Status] If the AL State change datagram was acknowledged, the
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1508
``AL Control Response'' register (see~\cite[section 5.3.2]{alspec}) must be
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1509
read out until the slave changes the AL state.
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1510
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1511
\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
  1512
reason can be read from the ``AL Status Code'' field in the ``AL State
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1513
Changed'' registers (see~\cite[section 5.3.3]{alspec}).
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1514
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1515
\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
  1516
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
  1517
register again.
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1518
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1519
\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
  1520
out the ``AL Control Response'' register again.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1521
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1522
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1523
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1524
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
  1525
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
  1526
requested.
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1527
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1528
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1529
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1530
\section{The SII State Machine}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1531
\label{sec:fsm-sii}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1532
\index{FSM!SII}
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
The SII\index{SII} state machine (shown in figure~\ref{fig:fsm-sii})
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1535
implements the process of reading or writing SII data via the
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1536
Slave Information Interface described in \cite[section~6.4]{dlspec}.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1537
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1538
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1539
  \centering
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1540
  \includegraphics[width=.5\textwidth]{graphs/fsm_sii}
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1541
  \caption{Transition Diagram of the SII State Machine}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1542
  \label{fig:fsm-sii}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1543
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1544
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1545
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
  1546
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1547
\begin{description}
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1548
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1549
\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
  1550
written to the SII attribute.
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1551
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1552
\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
  1553
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
  1554
attribute for state and data.
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1555
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1556
\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
  1557
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
  1558
copied from the datagram.
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1559
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1560
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1561
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1562
The writing part works nearly similar:
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1563
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1564
\begin{description}
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1565
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1566
\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
  1567
written to the SII attribute.
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1568
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1569
\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
  1570
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
  1571
attribute for the state of the write operation.
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1572
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1573
\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
  1574
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
  1575
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
  1576
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1577
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1578
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
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1581
\section{The Pdo State Machines}
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1582
\label{sec:fsm-pdo}
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1583
\index{FSM!Pdo}
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1584
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1585
The Pdo state machines are a set of state machines that read or write the Pdo
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1586
assignment and the Pdo mapping via the ``CoE Communication Area'' described in
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1587
\cite[section 5.6.7.4]{alspec}. For the object access, the
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1588
CANopen-over-EtherCAT access primitives are used (see
1269
fe4688f2c9e7 sec:ecrt is a chapter; sec:eoeimp -> sec:eoe, ...
Florian Pose <fp@igh-essen.com>
parents: 1235
diff changeset
  1589
section~\ref{sec:coe}), so the slave must support the CoE mailbox protocol.
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1590
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1591
\paragraph{Pdo Reading FSM} This state machine (fig.~\ref{fig:fsm-pdo-read})
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1592
has the purpose to read the complete Pdo configuration of a slave. It reads
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1593
the Pdo assignment for each Sync Manager and uses the Pdo Entry Reading FSM
1204
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
  1594
(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
  1595
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1596
\begin{figure}[htbp]
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1597
  \centering
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1598
  \includegraphics[width=.4\textwidth]{graphs/fsm_pdo_read}
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1599
  \caption{Transition Diagram of the Pdo Reading State Machine}
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1600
  \label{fig:fsm-pdo-read}
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1601
\end{figure}
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1602
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1603
Basically it reads the every Sync manager's Pdo assignment Sdo's
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1604
(\lstinline+0x1C1x+) number of elements to determine the number of assigned
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1605
Pdos for this sync manager and then reads out the subindices of the Sdo to get
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1606
the assigned Pdo's indices. When a Pdo index is read, the Pdo Entry Reading
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1607
FSM is executed to read the Pdo's mapped Pdo entries.
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1608
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1609
\paragraph{Pdo Entry Reading FSM} This state machine
1204
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
  1610
(fig.~\ref{fig:fsm-pdo-entry-read}) reads the Pdo mapping (the Pdo entries) of
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
  1611
a Pdo. It reads the respective mapping Sdo (\lstinline+0x1600+ -
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1612
\lstinline+0x17ff+, or \lstinline+0x1a00+ - \lstinline+0x1bff+) for the given
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1613
Pdo by reading first the subindex zero (number of elements) to determine the
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1614
number of mapped Pdo entries. After that, each subindex is read to get the
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1615
mapped Pdo entry index, subindex and bit size.
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1616
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1617
\begin{figure}[htbp]
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1618
  \centering
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1619
  \includegraphics[width=.4\textwidth]{graphs/fsm_pdo_entry_read}
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1620
  \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
  1621
  \label{fig:fsm-pdo-entry-read}
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1622
\end{figure}
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1623
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1624
\begin{figure}[htbp]
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1625
  \centering
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1626
  \includegraphics[width=.9\textwidth]{graphs/fsm_pdo_conf}
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1627
  \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
  1628
  \label{fig:fsm-pdo-conf}
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1629
\end{figure}
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1630
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1631
\begin{figure}[htbp]
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1632
  \centering
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1633
  \includegraphics[width=.4\textwidth]{graphs/fsm_pdo_entry_conf}
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1634
  \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
  1635
  \label{fig:fsm-pdo-entry-conf}
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1636
\end{figure}
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1637
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1638
%------------------------------------------------------------------------------
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1639
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1640
\chapter{Mailbox Protocol Implementations}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1641
\index{Mailbox}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1642
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1643
The EtherCAT master implements the EoE and the CoE mailbox
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1644
protocols. See the below section for details.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1645
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1646
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1647
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1648
\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
  1649
\label{sec:eoe}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1650
\index{EoE}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1651
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1652
The EtherCAT master implements the Ethernet-over-EtherCAT mailbox protocol to
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1653
enable the tunneling of Ethernet frames to special slaves, that can either
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1654
have physical Ethernet ports to forward the frames to, or have an own IP stack
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1655
to receive the frames.
369
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{Virtual Network Interfaces}
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 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
  1660
slave. These interfaces are called either
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1661
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1662
\begin{description}
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1663
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1664
\item[eoeXsY] for a slave without an alias address (see
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1665
section~\ref{sec:alias}), where X is the master index and Y is the slave's
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1666
ring position, or
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
\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
  1669
index and Y is the decimal alias address.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1670
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1671
\end{description}
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1672
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1673
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
  1674
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
  1675
forwarded to the virtual interfaces.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1676
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1677
This bears the following advantages:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1678
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1679
\begin{itemize}
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1680
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1681
\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
  1682
interconnected with the rest of the world.
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 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
  1685
the EoE interfaces.
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 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
  1688
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
  1689
traffic between EoE-capable slaves.
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 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
  1692
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
  1693
network interfaces.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1694
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1695
\end{itemize}
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
\paragraph{EoE Handlers}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1698
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1699
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
  1700
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
  1701
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
  1702
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
  1703
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
  1704
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
  1705
\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
  1706
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
  1707
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
  1708
\lstinline+netif_stop_queue()+.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1709
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1710
\paragraph{Creation of EoE Handlers}
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1711
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1712
During bus scanning (see section~\ref{sec:fsm-scan}), the master determines
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1713
the supported mailbox protocols foe each slave. This is done by examining the
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1714
``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
  1715
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
  1716
case, an EoE handler is created for that slave.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1717
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1718
\paragraph{EoE State Machine}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1719
\index{FSM!EoE}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1720
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1721
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
  1722
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
  1723
communication primitives. This state machine is showed in
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1724
figure~\ref{fig:fsm-eoe}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1725
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1726
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1727
  \centering
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1728
  \includegraphics[width=.7\textwidth]{images/fsm-eoe} % FIXME
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1729
  \caption{Transition Diagram of the EoE State Machine}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1730
  \label{fig:fsm-eoe}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1731
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1732
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1733
% FIXME
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1734
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1735
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1736
\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
  1737
  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
  1738
  frames. $\rightarrow$~RX\_CHECK
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1739
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1740
\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
  1741
  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
  1742
  $\rightarrow$~TX\_START
369
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
  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
  1745
  the new data. $\rightarrow$~RX\_FETCH
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1746
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1747
\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
  1748
  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
  1749
  dropped and a transmit sequence is started.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  1750
  $\rightarrow$~TX\_START
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1751
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1752
  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
  1753
  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
  1754
  the correct position of the socket buffer.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1755
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1756
  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
  1757
  to the network stack and a transmit sequence is started.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  1758
  $\rightarrow$~TX\_START
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1759
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1760
  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
  1761
  fragment. $\rightarrow$~RX\_\-START
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1762
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1763
\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
  1764
  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
  1765
  a receive sequence is started. $\rightarrow$~RX\_START
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1766
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1767
  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
  1768
  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
  1769
  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
  1770
  frame is sent. $\rightarrow$~TX\_SENT
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1771
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1772
\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
  1773
  successfully. If the current frame consists of further fragments,
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  1774
  the next one is sent. $\rightarrow$~TX\_SENT
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1775
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1776
  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
  1777
  $\rightarrow$~RX\_START
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1778
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1779
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1780
\paragraph{EoE Processing}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1781
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1782
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
  1783
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
  1784
machines synchronously with the master state machine (see
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1785
section~\ref{sec:fsm-master}). This approach has the following disadvantage:
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
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
  1788
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
  1789
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
  1790
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
  1791
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1792
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
  1793
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
  1794
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
  1795
poses the new problem of concurrent access to the master. The locking
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1796
mechanisms needed for this are introduced in section~\ref{sec:concurr}.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1797
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1798
\paragraph{Automatic Configuration}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1799
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1800
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
  1801
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
  1802
application-layer state is automatically set to OP.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1803
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
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1806
\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
  1807
\label{sec:coe}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1808
\index{CoE}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1809
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1810
The CANopen-over-EtherCAT protocol \cite[section~5.6]{alspec} is used to
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1811
configure slaves and exchange data objects on application level.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1812
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1813
% FIXME
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1814
%
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1815
% Download / Upload
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1816
% Expedited / Normal
1204
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
  1817
% Segmenting
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1818
% Sdo Info Services
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1819
%
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1820
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1821
\ldots
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1822
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  1823
\paragraph{Sdo Download State Machine}
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  1824
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  1825
The best time to apply Sdo configurations is during the slave's PREOP
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  1826
state, because mailbox communication is already possible and slave's
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  1827
application will start with updating input data in the succeeding
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  1828
SAFEOP state. Therefore the Sdo configuration has to be part of the
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  1829
slave configuration state machine (see section~\ref{sec:fsm-conf}): It
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  1830
is implemented via an Sdo download state machine, that is executed
813
bfc3f1ab52de Fixed typo SAVEOP -> SAFEOP.
Florian Pose <fp@igh-essen.com>
parents: 487
diff changeset
  1831
just before entering the slave's SAFEOP state. In this way, it is
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  1832
guaranteed that the Sdo configurations are applied each time, the
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  1833
slave is reconfigured.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1834
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  1835
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
  1836
in figure~\ref{fig:fsm-coedown}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1837
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1838
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1839
  \centering
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1840
  \includegraphics[width=.9\textwidth]{images/fsm-coedown} % FIXME
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1841
  \caption{Transition diagram of the CoE download state machine}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1842
  \label{fig:fsm-coedown}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1843
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1844
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1845
% FIXME
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1846
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1847
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1848
\item[START] The beginning state of the CoE download state
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  1849
  machine. The ``Sdo Download Normal Request'' mailbox command is
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  1850
  sent. $\rightarrow$~REQUEST
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1851
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1852
\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
  1853
  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
  1854
  and a timer is started. $\rightarrow$~CHECK
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1855
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1856
\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
  1857
  \begin{itemize}
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  1858
  \item If it timed out, the Sdo download is aborted.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  1859
    $\rightarrow$~ERROR
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1860
  \item Otherwise, the mailbox is queried again.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  1861
    $\rightarrow$~CHECK
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1862
  \end{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1863
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1864
  If the mailbox contains new data, the response is fetched.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  1865
  $\rightarrow$~RESPONSE
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1866
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1867
\item[RESPONSE] If the mailbox response could not be fetched, the data
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  1868
  is invalid, the wrong protocol was received, or a ``Abort Sdo
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  1869
  Transfer Request'' was received, the Sdo download is aborted.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  1870
  $\rightarrow$~ERROR
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1871
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  1872
  If a ``Sdo Download Normal Response'' acknowledgement was received,
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  1873
  the Sdo download was successful. $\rightarrow$~END
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  1874
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  1875
\item[END] The Sdo download was successful.
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  1876
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  1877
\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
  1878
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
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1881
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1882
1270
11f4b6e10d74 Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1269
diff changeset
  1883
\section{Vendor-specific-over-EtherCAT (VoE)}
11f4b6e10d74 Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1269
diff changeset
  1884
\label{sec:voe}
11f4b6e10d74 Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1269
diff changeset
  1885
\index{VoE}
11f4b6e10d74 Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1269
diff changeset
  1886
11f4b6e10d74 Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1269
diff changeset
  1887
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
  1888
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
  1889
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
  1890
constraints regarding this protocol.
11f4b6e10d74 Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1269
diff changeset
  1891
11f4b6e10d74 Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1269
diff changeset
  1892
The EtherCAT master allows to create multiple VoE handlers per slave
11f4b6e10d74 Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1269
diff changeset
  1893
configuration via the application interface (see chap.~\ref{sec:ecrt}). These
11f4b6e10d74 Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1269
diff changeset
  1894
handlers contain the state machine necessary for the communication via VoE.
11f4b6e10d74 Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1269
diff changeset
  1895
One read or write operation may be issued at a time. After the operation is
11f4b6e10d74 Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1269
diff changeset
  1896
initiated, the handler must be executed cyclically until it is finished. After
11f4b6e10d74 Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1269
diff changeset
  1897
that, the results of the operation can be retrieved.
11f4b6e10d74 Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1269
diff changeset
  1898
11f4b6e10d74 Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1269
diff changeset
  1899
A VoE handler has an own datagram structure, that is marked for exchange after
11f4b6e10d74 Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1269
diff changeset
  1900
each execution step. So the application can decide, how many handlers to
11f4b6e10d74 Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1269
diff changeset
  1901
execute before sending the corresponding EtherCAT frame(s).
11f4b6e10d74 Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1269
diff changeset
  1902
11f4b6e10d74 Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1269
diff changeset
  1903
For more information about using VoE handlers, see the application interface
11f4b6e10d74 Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1269
diff changeset
  1904
documentation (chap.~\ref{sec:ecrt}) or the example applications provided in
11f4b6e10d74 Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1269
diff changeset
  1905
the \textit{examples/} subdirectory.
11f4b6e10d74 Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1269
diff changeset
  1906
11f4b6e10d74 Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1269
diff changeset
  1907
%------------------------------------------------------------------------------
11f4b6e10d74 Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents: 1269
diff changeset
  1908
1275
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  1909
\chapter{Userspace Interfaces}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1910
\label{sec:user}
1275
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  1911
\index{Userspace}
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1912
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1913
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
  1914
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
  1915
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  1916
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
  1917
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
  1918
to view and to change special parameters at runtime.
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1919
1275
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  1920
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
  1921
is necessary to show the connected slaves with a single command, for instance
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  1922
(see sec.~\ref{sec:ethercat}).
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  1923
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  1924
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
  1925
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
  1926
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
  1927
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  1928
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
  1929
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
  1930
sec.~\ref{sec:system}).
1203
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1931
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1932
A last thing is monitoring EtherCAT communication. For debugging purposes,
acb649738601 Some more documentation...
Florian Pose <fp@igh-essen.com>
parents: 1202
diff changeset
  1933
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
  1934
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
  1935
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
  1936
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  1937
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
  1938
to make all that possible.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1939
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1940
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1941
1087
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  1942
\section{Command-line Tool}
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  1943
\label{sec:ethercat}
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  1944
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  1945
% --master
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  1946
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1947
\subsection{Character Devices}
1087
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  1948
\label{sec:cdev}
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  1949
1214
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  1950
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
  1951
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
  1952
the index of the master.
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  1953
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  1954
\paragraph{Device Node Creation} The character device nodes are automatically
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  1955
created, if the \lstinline+udev+ Package is installed. See section
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  1956
\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
  1957
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  1958
%------------------------------------------------------------------------------
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  1959
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1960
\subsection{Setting Alias Addresses}
1204
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
  1961
\label{sec:alias} % FIXME
1140
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  1962
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  1963
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_alias}
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  1964
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  1965
%------------------------------------------------------------------------------
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  1966
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1967
\subsection{Displaying the Bus Configuration}
1140
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  1968
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  1969
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_config}
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  1970
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  1971
%------------------------------------------------------------------------------
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  1972
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1973
\subsection{Displaying Process Data}
1140
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  1974
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  1975
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_data}
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  1976
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  1977
%------------------------------------------------------------------------------
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  1978
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1979
\subsection{Setting a Master's Debug Level}
1140
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  1980
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  1981
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_debug}
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  1982
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  1983
%------------------------------------------------------------------------------
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  1984
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1985
\subsection{Configured Domains}
1140
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  1986
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  1987
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_domains}
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  1988
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  1989
%------------------------------------------------------------------------------
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  1990
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1991
\subsection{Master and Ethernet Devices}
1140
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  1992
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  1993
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_master}
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  1994
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  1995
%------------------------------------------------------------------------------
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  1996
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  1997
\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
  1998
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  1999
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_pdos}
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2000
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2001
%------------------------------------------------------------------------------
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2002
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2003
\subsection{Sdo Dictionary}
1140
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2004
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2005
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_sdos}
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2006
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2007
%------------------------------------------------------------------------------
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2008
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2009
\subsection{Sdo Access}
1140
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2010
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2011
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_download}
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2012
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2013
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_upload}
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2014
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2015
%------------------------------------------------------------------------------
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2016
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2017
\subsection{Slaves on the Bus}
1087
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2018
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2019
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
  2020
1140
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2021
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_slaves}
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2022
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2023
Below is a typical output:
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2024
1087
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2025
\begin{lstlisting}
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2026
$ `\textbf{ethercat slaves}`
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2027
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
  2028
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
  2029
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
  2030
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
  2031
\end{lstlisting}
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2032
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2033
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2034
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2035
\subsection{SII Access}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2036
\label{sec:siiaccess}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2037
\index{SII!Access}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2038
1087
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2039
It is possible to directly read or write the complete SII contents of the
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2040
slaves. This was introduced for the reasons below:
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2041
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2042
\begin{itemize}
1087
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2043
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2044
\item The format of the SII data is still in development and categories can be
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2045
added in the future. With read and write access, the complete memory contents
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2046
can be easily backed up and restored.
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2047
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2048
\item Some SII data fields have to be altered (like the alias address). A quick
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2049
writing must be possible for that.
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2050
1275
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  2051
\item Through reading access, analyzing category data is possible from
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  2052
userspace.
1087
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2053
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2054
\end{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2055
1140
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2056
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_sii_read}
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2057
1087
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2058
Reading out SII data is as easy as other commands. Though the data are in
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2059
binary format, analysis is easier with a tool like \textit{hexdump}:
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2060
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2061
\begin{lstlisting}
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2062
$ `\textbf{ethercat sii\_read --position 3 | hexdump}`
1087
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2063
0000000 0103 0000 0000 0000 0000 0000 0000 008c
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2064
0000010 0002 0000 3052 07f0 0000 0000 0000 0000
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2065
0000020 0000 0000 0000 0000 0000 0000 0000 0000
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2066
...
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2067
\end{lstlisting}
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2068
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2069
Backing up SII contents can easily done with a redirection:
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2070
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2071
\begin{lstlisting}
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2072
$ `\textbf{ethercat sii\_read --position 3 > sii-of-slave3.bin}`
1087
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2073
\end{lstlisting}
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2074
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2075
To download SII contents to a slave, writing access to the master's character
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2076
device is necessary (see section~\ref{sec:cdev}).
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2077
1140
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2078
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_sii_write}
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2079
1087
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2080
\begin{lstlisting}
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2081
# `\textbf{ethercat sii\_write --position 3 sii-of-slave3.bin}`
1087
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2082
\end{lstlisting}
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2083
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2084
The SII contents will be checked for validity and then sent to the slave. The
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2085
write operation may take a few seconds.
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
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2088
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2089
\subsection{Requesting Application-Layer States}
1140
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2090
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2091
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_states}
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2092
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2093
%------------------------------------------------------------------------------
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2094
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2095
\subsection{Generating Slave Description XML}
1140
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2096
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2097
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_xml}
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2098
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2099
%------------------------------------------------------------------------------
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2100
1275
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  2101
\section{Userspace Library}
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  2102
\label{sec:userlib}
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  2103
1282
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2104
The native application interface (see chap.~\ref{sec:ecrt}) resides in
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2105
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
  2106
application interface available from userspace programs, a userspace library
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2107
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
  2108
conditions of the LGPL, version 2 \cite{lgpl}.
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2109
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2110
The library is named \textit{libethercat}. Its sources reside in the
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2111
\textit{lib/} subdirectory and are build by default when using
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2112
\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
  2113
installation prefix as \textit{libethercat.a} (for static linking),
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2114
\textit{libethercat.la} (for the use with \textit{libtool}) and
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2115
\textit{libethercat.so} (for dynamic linking).
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2116
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2117
\subsection{Usage}
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2118
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2119
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
  2120
and in user context.
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2121
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2122
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
  2123
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
  2124
path of the master sources.
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2125
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2126
\begin{lstlisting}[language=C]
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2127
#include <ecrt.h>
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2128
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2129
int main(void)
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2130
{
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2131
    ec_master_t *master = ecrt_request_master(0);
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2132
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2133
    if (!master)
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2134
        return 1; // error
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2135
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2136
    pause(); // wait for signal
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2137
    return 0;
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2138
}
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2139
\end{lstlisting}
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2140
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2141
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
  2142
below command:
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2143
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2144
\begin{lstlisting}
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2145
gcc ethercat.c -o ectest -I/opt/etherlab/include \
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2146
    -L/opt/etherlab/lib -lethercat \
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2147
    -Wl,--rpath -Wl,/opt/etherlab/lib
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2148
\end{lstlisting}
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2149
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2150
The library can also be linked statically to the program:
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2151
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2152
\begin{lstlisting}
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2153
gcc -static ectest.c -o ectest -I/opt/etherlab/include \
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2154
    /opt/etherlab/lib/libethercat.a
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2155
\end{lstlisting}
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2156
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2157
\subsection{Implementation}
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2158
\label{sec:userimp}
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2159
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2160
Basically the kernel API was transferred into userspace via the master
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2161
character device (see sec.~\ref{sec:cdev}).
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2162
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2163
The function calls of the kernel API are mapped to the userspace via an
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2164
\lstinline+ioctl()+ interface. Each function has its own \lstinline+ioctl()+
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2165
call. The kernel part of the interface calls the according API functions
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2166
directly, what results in a minimum additional delay (see
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2167
sec.~\ref{sec:usertiming}).
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2168
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2169
Also for performance reasons, the actual domain process data (see
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2170
chap.~ref{sec:ecrt}) are not copied between kernel and user memory on every
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2171
access: Instead, the data are memory-mapped to the userspace application. Once
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2172
the master is configured and activated, the master module creates one big
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2173
process data memory area for all domains and maps it to userspace, so that the
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2174
application can directly access the process data. For that, there is no
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2175
additional delay accessing the process data from userspace.
1275
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  2176
1281
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2177
\subsection{Timing}
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2178
\label{sec:usertiming}
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2179
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2180
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
  2181
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
  2182
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
  2183
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
  2184
kernel.
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2185
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2186
\begin{table}[htbp]
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2187
  \centering
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2188
  \caption{Application Interface Timing Comparison}
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2189
  \label{tab:usertiming}
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2190
  \vspace{2mm}
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2191
  \begin{tabular}{l|c|c|c|c}
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2192
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2193
    &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2194
    \multicolumn{2}{|c}{\textbf{Kernelspace}} &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2195
    \multicolumn{2}{|c}{\textbf{Userspace}}  \\
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2196
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2197
    \textbf{Function} &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2198
    $\mu(t)$ &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2199
    $\sigma(t)$ &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2200
    $\mu(t)$ &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2201
    $\sigma(t)$ \\
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2202
    \hline
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2203
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2204
    \lstinline+ecrt_master_receive()+ &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2205
    \unit{1.1}{\micro\second} &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2206
    \unit{0.3}{\micro\second} &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2207
    \unit{2.2}{\micro\second} &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2208
    \unit{0.5}{\micro\second} \\
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2209
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2210
    \lstinline+ecrt_domain_process()+ &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2211
    \unit{<0.1}{\micro\second} &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2212
    \unit{<0.1}{\micro\second} &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2213
    \unit{1.0}{\micro\second} &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2214
    \unit{0.2}{\micro\second} \\
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2215
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2216
    \lstinline+ecrt_domain_queue()+ &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2217
    \unit{<0.1}{\micro\second} &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2218
    \unit{<0.1}{\micro\second} &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2219
    \unit{1.0}{\micro\second} &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2220
    \unit{0.1}{\micro\second} \\
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2221
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2222
    \lstinline+ecrt_master_send()+ &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2223
    \unit{1.8}{\micro\second} &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2224
    \unit{0.2}{\micro\second} &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2225
    \unit{2.5}{\micro\second} &
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2226
    \unit{0.5}{\micro\second} \\
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2227
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2228
  \end{tabular}
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2229
\end{table}
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2230
1282
d494455b64a2 Completed library.
Florian Pose <fp@igh-essen.com>
parents: 1281
diff changeset
  2231
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
  2232
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
  2233
the kernel API.
1281
9e9393cfc4f7 Added userspace timing.
Florian Pose <fp@igh-essen.com>
parents: 1275
diff changeset
  2234
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
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2237
\section{System Integration}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2238
\label{sec:system}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2239
1086
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2240
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
  2241
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
  2242
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2243
\subsection{Init Script}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2244
\label{sec:init}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2245
\index{Init script}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2246
1086
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2247
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
  2248
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
  2249
\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
  2250
copied (or better: linked) to the appropriate location (see
1204
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
  2251
section~\ref{sec:installation}), before the master can be inserted as a
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
  2252
service.  Please note, that the init script depends on the sysconfig file
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
  2253
described below.
1086
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2254
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2255
To provide service dependencies (i.~e. which services have to be started before
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2256
others) inside the init script code, LSB defines a special comment block.
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2257
System tools can extract this information to insert the EtherCAT init script at
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2258
the correct place in the startup sequence:
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2259
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2260
\lstinputlisting[firstline=38,lastline=48]
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2261
    {../script/init.d/ethercat}
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2262
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2263
\subsection{Sysconfig File}
1086
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2264
\label{sec:sysconfig}
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2265
\index{Sysconfig file}
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2266
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2267
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
  2268
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
  2269
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
  2270
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
  2271
the file and included below:
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2272
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2273
\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
  2274
    {../script/sysconfig/ethercat}
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2275
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2276
\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
  2277
\label{sec:service}
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2278
\index{Service}
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2279
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2280
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
  2281
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
  2282
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
  2283
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
  2284
command:
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2285
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2286
\begin{lstlisting}
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2287
# `\textbf{insserv ethercat}`
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2288
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2289
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2290
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
  2291
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
  2292
\texttt{start}, \texttt{stop}, \texttt{restart} or \texttt{status}.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2293
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2294
\begin{lstlisting}[gobble=2]
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2295
  # `\textbf{/etc/init.d/ethercat restart}`
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2296
  Shutting down EtherCAT master                done
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2297
  Starting EtherCAT master                     done
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2298
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2299
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2300
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2301
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2302
\section{Monitoring and Debugging}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2303
\label{sec:debug}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2304
\index{Monitoring}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2305
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2306
% FIXME
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2307
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2308
For debugging purposes, every EtherCAT master registers a read-only network
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2309
interface \textit{ecX}, where X is a number, provided by the kernel on device
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2310
registration. While it is ``up'', the master forwards every frame sent and
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2311
received to this interface.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2312
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2313
This makes it possible to connect an network monitor (like Wireshark or
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2314
tcpdump) to the debug interface and monitor the EtherCAT frames.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2315
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2316
% FIXME schedule()
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2317
It has to be considered, that can be frame rate can be very high. The master
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2318
state machine usually runs every kernel timer interrupt (usually up to
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2319
\unit{1}{\kilo\hertz}) and with a connected application, the rate can be even
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2320
higher.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2321
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2322
\paragraph{Attention:} The socket buffers needed for the operation of
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2323
the debugging interface have to be allocated dynamically. Some Linux
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2324
realtime extensions do not allow this in realtime context!
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2325
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2326
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2327
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2328
\chapter{Timing Aspects}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2329
\label{sec:timing}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2330
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2331
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
  2332
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
  2333
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2334
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2335
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2336
\subsection{Application Interface Profiling}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2337
\label{sec:timing-profile}
1204
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
  2338
\index{Profiling}
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
  2339
% FIXME
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2340
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2341
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
  2342
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
  2343
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
  2344
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
  2345
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2346
\begin{lstlisting}[gobble=2,language=C]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2347
  c0 = get_cycles();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2348
  ecrt_master_receive(master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2349
  c1 = get_cycles();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2350
  ecrt_domain_process(domain1);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2351
  c2 = get_cycles();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2352
  ecrt_master_run(master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2353
  c3 = get_cycles();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2354
  ecrt_master_send(master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2355
  c4 = get_cycles();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2356
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2357
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2358
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
  2359
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
  2360
\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
  2361
\milli\second.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2362
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2363
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
  2364
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
  2365
\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
  2366
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
  2367
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2368
\begin{table}[htpb]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2369
  \centering
1204
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
  2370
  \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
  2371
  Processor}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2372
  \label{tab:profile}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2373
  \vspace{2mm}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2374
  \begin{tabular}{l|r|r}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2375
    Element & Mean Duration [\second] & Standard Deviancy [\micro\second] \\
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2376
    \hline
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2377
    \textit{ecrt\_master\_receive()} & 8.04 & 0.48\\
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2378
    \textit{ecrt\_domain\_process()} & 0.14 & 0.03\\
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2379
    \textit{ecrt\_master\_run()} & 0.29 & 0.12\\
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2380
    \textit{ecrt\_master\_send()} & 2.18 & 0.17\\ \hline
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2381
    Complete Cycle & 10.65 & 0.69\\ \hline
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2382
  \end{tabular}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2383
\end{table}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2384
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2385
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
  2386
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
  2387
the Ethernet device, analyzes datagrams and copies their contents into
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2388
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
  2389
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
  2390
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
  2391
receiving time.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2392
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2393
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
  2394
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
  2395
\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
  2396
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
  2397
\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
  2398
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
  2399
functions are more or less complex.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2400
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2401
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
  2402
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
  2403
keeps being theoretical:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2404
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2405
\begin{enumerate}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2406
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2407
\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
  2408
realtime cycles.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2409
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2410
\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
  2411
cycle begins. The determination of the bus cycle time is difficult and covered
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2412
in section~\ref{sec:timing-bus}.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2413
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2414
\end{enumerate}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2415
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2416
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2417
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2418
\subsection{Bus Cycle Measuring}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2419
\label{sec:timing-bus}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2420
\index{Bus cycle}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2421
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2422
For measuring the time, a frame is ``on the wire'', two timestamps
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2423
must be be taken:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2424
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2425
\begin{enumerate}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2426
\item The time, the Ethernet hardware begins with physically sending
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2427
  the frame.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2428
\item The time, the frame is completely received by the Ethernet
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2429
  hardware.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2430
\end{enumerate}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2431
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2432
Both times are difficult to determine. The first reason is, that the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2433
interrupts are disabled and the master is not notified, when a frame
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2434
is sent or received (polling would distort the results). The second
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2435
reason is, that even with interrupts enabled, the time from the event
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2436
to the notification is unknown. Therefore the only way to confidently
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2437
determine the bus cycle time is an electrical measuring.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2438
1204
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
  2439
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
  2440
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
  2441
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
  2442
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
  2443
limits of the system.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2444
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2445
The central question is: What happens, if the cycle frequency is too high? The
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2446
answer is, that the EtherCAT frames that have been sent at the end of the cycle
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2447
are not yet received, when the next cycle starts.  First this is noticed by
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2448
\textit{ecrt\_domain\_process()}, because the working counter of the process
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2449
data datagrams were not increased. The function will notify the user via
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2450
Syslog\footnote{To limit Syslog output, a mechanism has been implemented, that
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2451
outputs a summarized notification at maximum once a second.}. In this case, the
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2452
process data keeps being the same as in the last cycle, because it is not
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2453
erased by the domain. When the domain datagrams are queued again, the master
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2454
notices, that they are already queued (and marked as sent). The master will
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2455
mark them as unsent again and output a warning, that datagrams were
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2456
``skipped''.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2457
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2458
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
  2459
can be up to \unit{25}{\kilo\hertz} without skipped frames. This value can
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2460
surely be increased by choosing faster hardware. Especially the RealTek network
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2461
hardware could be replaced by a faster one. Besides, implementing a dedicated
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2462
ISR for EtherCAT devices would also contribute to increasing the latency. These
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2463
are two points on the author's to-do list.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2464
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2465
%------------------------------------------------------------------------------
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2466
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2467
\chapter{Installation}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2468
\label{sec:installation}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2469
\index{Master!Installation}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2470
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2471
\section{Building the Software}
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  2472
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  2473
The current EtherCAT master code is available at~\cite{etherlab} or can be
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  2474
obtained from the EtherLab CD. The \textit{tar.bz2} file has to be unpacked
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  2475
with the commands below (or similar):
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2476
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2477
\begin{lstlisting}[gobble=2]
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2478
  $ `\textbf{tar xjf ethercat-\masterversion.tar.bz2}`
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2479
  $ `\textbf{cd ethercat-\masterversion/}`
374
e43a29f9079e Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents: 371
diff changeset
  2480
\end{lstlisting}
e43a29f9079e Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents: 371
diff changeset
  2481
e43a29f9079e Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents: 371
diff changeset
  2482
The tarball was created with GNU Autotools, so the build process
487
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
  2483
follows the below commands:
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2484
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2485
\begin{lstlisting}[gobble=2]
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2486
  $ `\textbf{./configure}`
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2487
  $ `\textbf{make}`
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2488
  $ `\textbf{make modules}`
374
e43a29f9079e Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents: 371
diff changeset
  2489
\end{lstlisting}
e43a29f9079e Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents: 371
diff changeset
  2490
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2491
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
  2492
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2493
\begin{table}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2494
  \caption{Configuration options}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2495
  \label{tab:config}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2496
  \vspace{2mm}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2497
  \begin{tabular}{l|p{.3\textwidth}|l}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2498
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2499
\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
  2500
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2501
\lstinline+--prefix+ & Installation prefix & \textit{/opt/etherlab}\\
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2502
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2503
\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
  2504
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2505
\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
  2506
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2507
\hline
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2508
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2509
\lstinline+--enable-eoe+ & Enable EoE support & yes\\
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2510
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2511
\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
  2512
architecture to get finer timing calculation. & no\\
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2513
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2514
\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
  2515
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2516
\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
  2517
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2518
\hline
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2519
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2520
\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
  2521
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2522
\lstinline+--with-8139too-kernel+ & 8139too kernel & $\dagger$\\
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2523
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2524
\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
  2525
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2526
\lstinline+--with-e100-kernel+ & e100 kernel & $\dagger$\\
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2527
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2528
\lstinline+--enable-e1000+ & Enable e1000 driver & no\\
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2529
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2530
\lstinline+--with-e1000-kernel+ & e1000 kernel & $\dagger$\\
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2531
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2532
  \end{tabular}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2533
  \vspace{2mm}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2534
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2535
\begin{description}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2536
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2537
\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
  2538
extracted from the Linux kernel sources.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2539
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2540
\end{description}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2541
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2542
\end{table}
487
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
  2543
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2544
\section{Building the Interface Documentation}
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  2545
\label{sec:gendoc}
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  2546
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  2547
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
  2548
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
  2549
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
  2550
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  2551
\begin{lstlisting}
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  2552
$ `\textbf{make doc}`
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  2553
\end{lstlisting}
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  2554
1204
4e3e8400c338 Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents: 1203
diff changeset
  2555
The interface documentation can be viewed by pointing a browser to the file
1202
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2556
\textit{doxygen-output/html/index.html}.
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2557
91d190223daa Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents: 1140
diff changeset
  2558
\section{Installing the Software}
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  2559
1106
745a0cc03143 Added depmod call to docs.
Florian Pose <fp@igh-essen.com>
parents: 1095
diff changeset
  2560
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
  2561
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
  2562
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
  2563
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
  2564
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
  2565
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
  2566
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  2567
\begin{lstlisting}
1106
745a0cc03143 Added depmod call to docs.
Florian Pose <fp@igh-essen.com>
parents: 1095
diff changeset
  2568
# `\textbf{make install}`
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  2569
# `\textbf{make modules\_install}`
1106
745a0cc03143 Added depmod call to docs.
Florian Pose <fp@igh-essen.com>
parents: 1095
diff changeset
  2570
# `\textbf{depmod}`
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2571
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2572
1095
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  2573
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
  2574
different destination directory can be specified with the \lstinline+DESTDIR+
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  2575
make variable. For example:
487
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
  2576
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  2577
\begin{lstlisting}
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  2578
# `\textbf{make DESTDIR=/vol/nfs/root modules\_install}`
487
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
  2579
\end{lstlisting}
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
  2580
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
  2581
This command will install the compiled kernel modules to
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
  2582
\textit{/vol/nfs/root/lib/modules}, prepended by the kernel release.
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
  2583
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2584
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
  2585
master shall not be loaded on system startup, the use of the init script is
1086
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2586
recommended for manual (un-)loading.} (see section~\ref{sec:system}), the init
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2587
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
  2588
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
  2589
distributions.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2590
1107
Florian Pose <fp@igh-essen.com>
parents: 1106
diff changeset
  2591
% FIXME relative ln -s?
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  2592
\begin{lstlisting}
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  2593
# `\textbf{cd /opt/etherlab}`
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  2594
# `\textbf{cp etc/sysconfig/ethercat /etc/sysconfig/}`
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  2595
# `\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
  2596
# `\textbf{insserv ethercat}`
374
e43a29f9079e Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents: 371
diff changeset
  2597
\end{lstlisting}
e43a29f9079e Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents: 371
diff changeset
  2598
376
d1441d87f5c1 Documentation: EtherLab-CD; obtaining the DEVICE_INDEX.
Florian Pose <fp@igh-essen.com>
parents: 374
diff changeset
  2599
Now the sysconfig file \texttt{/etc/sysconfig/ethercat} (see
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2600
section~\ref{sec:sysconfig}) has to be customized. The minimal customization
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2601
is to set the \lstinline+MASTER0_DEVICE+ variable to the MAC address of the
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2602
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
  2603
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
  2604
\lstinline+DEVICE_MODULES+ variable.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2605
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2606
After the basic configuration is done, the master can be started with
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2607
the below command:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2608
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  2609
\begin{lstlisting}
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  2610
# `\textbf{/etc/init.d/ethercat start}`
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2611
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2612
1214
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  2613
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
  2614
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
  2615
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
  2616
indicators should begin to flash.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2617
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2618
\begin{lstlisting}[numbers=left]
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2619
EtherCAT: Master driver `\masterversion`
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2620
EtherCAT: 1 master waiting for devices.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2621
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
  2622
Copyright (c) 1999-2005 Intel Corporation.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2623
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
  2624
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
  2625
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
  2626
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
  2627
EtherCAT: Starting master thread.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2628
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
  2629
          Connection
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2630
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
  2631
          Full Duplex
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2632
EtherCAT: Link state changed to UP.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2633
EtherCAT: 7 slave(s) responding.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2634
EtherCAT: Slave states: PREOP.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2635
EtherCAT: Scanning bus.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2636
EtherCAT: Bus scanning completed in 431 ms.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2637
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2638
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2639
\begin{description}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2640
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2641
\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
  2642
is initialized.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2643
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2644
\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
  2645
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
  2646
\lstinline+00:0E:0C:DA:A2:20+.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2647
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2648
\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
  2649
state machine and begins scanning the bus.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2650
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2651
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2652
1214
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  2653
\section{Automatic Device Node Creation}
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  2654
\label{sec:autonode}
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  2655
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  2656
The \lstinline+ethercat+ command-line tool (see section~\ref{sec:ethercat})
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  2657
communicates with the master via a character device. The corresponding device
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  2658
nodes are created automatically, if the udev daemon is running.
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  2659
Note, that on some distributions, the \lstinline+udev+ package is not
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  2660
installed by default.
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  2661
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  2662
The device nodes will be created with mode \lstinline+0660+ and group
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  2663
\lstinline+root+ by default. If you want to give normal users reading access,
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  2664
create a udev rule file (for example
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  2665
\textit{/etc/udev/rules.d/99-EtherCAT.rules} with the following content:
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  2666
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  2667
\begin{lstlisting}
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  2668
KERNEL=="EtherCAT[0-9]*", MODE="0664"
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  2669
\end{lstlisting}
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  2670
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  2671
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
  2672
\lstinline[breaklines=true]+/etc/init.d/ethercat restart+, the device node
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  2673
will be automatically created with the desired rights:
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  2674
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  2675
\begin{lstlisting}
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  2676
# `\textbf{ls -l /dev/EtherCAT0}`
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  2677
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
  2678
\end{lstlisting}
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  2679
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  2680
Now, the \lstinline+ethercat+ tool can be used (see
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  2681
section~\ref{sec:ethercat}) even as a non-root user.
63802a52dd69 udev docs.
Florian Pose <fp@igh-essen.com>
parents: 1204
diff changeset
  2682
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2683
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2684
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2685
\begin{thebibliography}{99}
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  2686
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  2687
\bibitem{etherlab} Ingenieurgemeinschaft IgH: EtherLab -- Open Source Toolkit
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  2688
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
  2689
technology. \url{http://etherlab.org/en}, 2008.
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  2690
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2691
\bibitem{dlspec} IEC 61158-4-12: Data-link Protocol Specification.
1095
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  2692
International Electrotechnical Commission (IEC), 2005.
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  2693
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  2694
\bibitem{alspec} IEC 61158-6-12: Application Layer Protocol Specification.
1095
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  2695
International Electrotechnical Commission (IEC), 2005.
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  2696
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  2697
\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
  2698
\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
  2699
c9de1c0c1f51 *space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents: 1270
diff changeset
  2700
\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
  2701
\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
  2702
2008.
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  2703
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  2704
\bibitem{lsb} Linux Standard Base.
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  2705
\url{http://www.linuxfoundation.org/en/LSB}.  August~9, 2006.
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  2706
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  2707
\bibitem{wireshark} Wireshark. \url{http://www.wireshark.org}. 2008.
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  2708
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  2709
\bibitem{automata} {\it Hopcroft, J.~E. / Ullman, J.~D.}: Introduction to
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  2710
Automata Theory, Languages and Computation. Adison-Wesley, Reading,
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  2711
Mass.~1979.
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  2712
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2713
\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
  2714
misunderstandings. In: IEE journal ``Computing and Control Engineering'',
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  2715
2004.
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  2716
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  2717
\bibitem{rtai} RTAI. The RealTime Application Interface for Linux from DIAPM.
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  2718
\url{http://www.rtai.org}, 2006.
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  2719
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  2720
\bibitem{doxygen} Doxygen. Source code documentation generator tool.
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  2721
\url{http://www.stack.nl/~dimitri/doxygen}, 2008.
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  2722
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2723
\end{thebibliography}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2724
917
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
  2725
\printnomenclature
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2726
\addcontentsline{toc}{chapter}{\nomname}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2727
\markleft{\nomname}
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
\printindex
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2730
\markleft{Index}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2731
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2732
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2733
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2734
\end{document}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2735
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2736
%------------------------------------------------------------------------------