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