documentation/ethercat_doc.tex
author Florian Pose <fp@igh-essen.com>
Wed, 04 Jun 2008 13:17:15 +0000
changeset 950 8b00e63fff90
parent 917 07b0ad9722a1
child 1085 c75cdcc5ce87
permissions -rw-r--r--
'ethercat domain' shows domain contents and process data.
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
%
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
     7
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
     8
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
     9
\documentclass[a4paper,12pt,BCOR6mm,bibtotoc,idxtotoc]{scrbook}
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
\usepackage[latin1]{inputenc}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    12
\usepackage[automark,headsepline]{scrpage2}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    13
\usepackage{graphicx}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    14
\usepackage{makeidx}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    15
\usepackage[refpage]{nomencl}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    16
\usepackage{listings}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    17
\usepackage{svn}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    18
\usepackage{textcomp}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    19
\usepackage{url}
371
97f684433d3b Improved documentation makefile, removed svn.sty, fixed LaTeX penalties.
Florian Pose <fp@igh-essen.com>
parents: 370
diff changeset
    20
\usepackage[pdfpagelabels,plainpages=false]{hyperref}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    21
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    22
\setlength{\parskip}{0.8ex plus 0.8ex minus 0.5ex}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    23
\setlength{\parindent}{0mm}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    24
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    25
\setcounter{secnumdepth}{\subsubsectionlevel}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    26
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    27
\DeclareFontShape{OT1}{cmtt}{bx}{n}
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
  <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
    30
}{}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    31
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    32
\lstset{basicstyle=\ttfamily\small,numberstyle=\tiny,aboveskip=4mm,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    33
  belowskip=2mm,gobble=2,escapechar=`}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    34
\renewcommand\lstlistlistingname{List of Listings}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    35
917
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    36
% Workaround for lstlistoflistings bug
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    37
\makeatletter% --> De-TeX-FAQ
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    38
\renewcommand*{\lstlistoflistings}{%
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    39
  \begingroup
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    40
    \if@twocolumn
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    41
      \@restonecoltrue\onecolumn
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    42
    \else
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    43
      \@restonecolfalse
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    44
    \fi
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    45
    \lol@heading
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    46
    \setlength{\parskip}{\z@}%
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    47
    \setlength{\parindent}{\z@}%
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    48
    \setlength{\parfillskip}{\z@ \@plus 1fil}%
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    49
    \@starttoc{lol}%
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    50
    \if@restonecol\twocolumn\fi
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    51
  \endgroup
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    52
}
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    53
\makeatother% --> \makeatletter
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    54
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    55
\renewcommand\nomname{Glossary}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    56
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    57
\newcommand{\IgH}{\raisebox{-0.7667ex}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    58
  {\includegraphics[height=2.2ex]{images/ighsign}}}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    59
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    60
\SVN $Date$
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    61
\SVN $Revision$
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    62
487
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
    63
\newcommand{\masterversion}{1.1.1}
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
    64
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    65
\makeindex
917
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    66
\makenomenclature
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    67
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    68
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    69
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    70
\begin{document}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    71
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    72
\pagenumbering{roman}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    73
\pagestyle{empty}
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{titlepage}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    76
  \begin{center}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    77
    \rule{\textwidth}{1.5mm}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    78
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    79
    {\Huge\bf IgH \includegraphics[height=2.4ex]{images/ethercat}
487
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
    80
      Master \masterversion\\[1ex]
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    81
      Documentation}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    82
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    83
    \vspace{1ex}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    84
    \rule{\textwidth}{1.5mm}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    85
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    86
    \vspace{\fill}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    87
    {\Large Florian Pose, \url{fp@igh-essen.com}\\[1ex]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    88
      Ingenieurgemeinschaft \IgH}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    89
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    90
    \vspace{\fill}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    91
    {\Large Essen, \SVNDate\\[1ex]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    92
      Revision \SVNRevision}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    93
  \end{center}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    94
\end{titlepage}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    95
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    96
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    97
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    98
\tableofcontents
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    99
\listoftables
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   100
\listoffigures
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   101
\lstlistoflistings
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   102
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   103
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   104
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   105
\newpage
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   106
\pagestyle{scrheadings}
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
\section*{Conventions}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   109
\addcontentsline{toc}{section}{Conventions}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   110
\markleft{Conventions}
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
The following typographic conventions are used:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   113
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   114
\begin{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   115
\item \textit{Italic face} is used for newly introduced terms, file
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   116
  names, parameter names and in-text source code elements.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   117
\item \texttt{Typewriter face} is used for code examples and
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   118
  command line output.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   119
\item \texttt{\textbf{Bold typewriter face}} is used for user input in
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   120
  command lines.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   121
\end{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   122
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   123
Data values and addresses are specified as hexadecimal values with the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   124
prefix 0x. Example: 0x88A4. Unless otherwise noted, address values are
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   125
specified as byte addresses.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   126
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   127
Concerning bit operations, the phrase ``setting a bit'', stands for
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   128
setting the bit to $1$, ``clearing a bit'' means setting it to $0$,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   129
respectively.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   130
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   131
Function names are always printed with parentheses, but without
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   132
parameters. So, if a function \textit{ecrt\_request\_master()} has
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   133
empty parentheses, this does not mean, that it has no parameters.
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
If shell commands have to be entered, this is marked by a prompt:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   136
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   137
\begin{lstlisting}[gobble=2]
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
   138
  `\$`
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   139
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   140
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   141
Further, if a shell command has to be entered as the superuser, the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   142
prompt ends with a mesh:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   143
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   144
\begin{lstlisting}[gobble=2]
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
   145
  #
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   146
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   147
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   148
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   149
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   150
\chapter{The IgH EtherCAT Master}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   151
\label{chapter:master}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   152
\pagenumbering{arabic}
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
This section will first introduce the master's general features and
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   155
the concepts used for master development and will then explain the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   156
master's general architecture and offer details of the different
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   157
modules. In addition, it will cover state machine definitions, mailbox
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   158
protocol implementation and the user space interface. The last section
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   159
will deal with timing aspects.
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
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   163
\section{Feature Summary}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   164
\label{sec:summary}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   165
\index{Master!Features}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   166
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   167
The list below gives a short summary of the features of the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   168
implemented EtherCAT master.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   169
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   170
\begin{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   171
\item The master runs as a kernel module for Linux 2.6.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   172
\item It comes with EtherCAT-capable network driver for RealTek
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   173
  RTL8139 (and compatible) network interface cards.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   174
  \begin{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   175
  \item The Ethernet hardware is operated without interrupts.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   176
  \item Drivers for additional Ethernet hardware can easily be
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   177
    implemented due to a common device interface provided by the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   178
    master.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   179
  \end{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   180
\item The master module supports multiple EtherCAT masters on one
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   181
  machine.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   182
\item The master code supports any Linux realtime extension through
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   183
  its independent architecture.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   184
  \begin{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   185
  \item RTAI\nomenclature{RTAI}{RealTime Application Interface},
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   186
    ADEOS\nomenclature{ADEOS}{Adaptive Domain Environment for
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   187
      Operating Systems}, etc.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   188
  \item It runs well even without realtime extensions.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   189
  \end{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   190
\item Common ``realtime interface'' for modules, that want to use
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   191
  EtherCAT functionality.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   192
  \begin{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   193
  \item Synchronous and asynchronous sending and receiving of frames
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   194
    is supported.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   195
  \item Avoidance of unnecessary copy operations for process data.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   196
  \end{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   197
\item \textit{Domains} are introduced, to allow grouping of process
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   198
  data objects.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   199
  \begin{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   200
  \item Handling of multiple domains with different sampling rates.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   201
  \item Automatic calculation of process data mapping, FMMU and sync manager
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   202
    configuration within each domain.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   203
  \end{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   204
\item Communication through serveral finite state machines.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   205
  \begin{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   206
  \item Bus monitoring possible during realtime operation.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   207
  \item Automatic reconfiguration of slaves on bus power failure
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   208
    during realtime operation.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   209
  \item Controlling of single slaves during realtime operation.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   210
  \end{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   211
\item Master idle mode.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   212
  \begin{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   213
  \item Automatic scanning of slaves upon topology changes.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   214
  \item Bus visualisation and EoE processing without a realtime module
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   215
    connected.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   216
  \end{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   217
\item Implementation of the CANopen-over-EtherCAT (CoE) protocol.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   218
  \begin{itemize}
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
   219
  \item Configuration of CoE-capable slaves via Sdo interface.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   220
  \end{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   221
\item Implementation of the Ethernet-over-EtherCAT (EoE) protocol.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   222
  \begin{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   223
  \item Each master creates virtual network devices that are
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   224
    automatically coupled to EoE-cap\-able slaves found.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   225
  \item This implementation natively supports either a switched or a
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   226
    routed EoE network architecture.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   227
  \end{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   228
\item User space interface via the System Filesystem
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   229
  (Sysfs)\nomenclature{Sysfs}{System Filesystem}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   230
  \begin{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   231
  \item User space tool for bus visualisation.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   232
  \item Slave E$^2$PROM image reading and writing.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   233
  \end{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   234
\item Seamless system integration though LSB\nomenclature{LSB}{Linux
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   235
    Standard Base} compliance.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   236
  \begin{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   237
  \item Master and network device configuration via Sysconfig files.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   238
  \item Linux Standard Base compatible init script for master control.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   239
  \end{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   240
\item Virtual read-only network interface for monitoring and debugging
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   241
  purposes.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   242
\end{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   243
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   244
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   245
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   246
\section{License}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   247
\label{sec:license}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   248
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   249
The master code is released under the terms and conditions of the GNU
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   250
General Public License\index{GPL} \cite{gpl} (version 2). Other
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   251
developers, that want to use EtherCAT with Linux systems, are invited
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   252
to use the master code or even participate on development.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   253
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   254
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   255
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   256
\section{General Master Architecture}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   257
\label{sec:masterarch}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   258
\index{Master!Architecture}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   259
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   260
The EtherCAT master is integrated into the Linux 2.6 kernel. This was
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   261
an early design decision, which has been made for serveral reasons:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   262
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   263
\begin{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   264
\item Kernel code has significantly better realtime characteristics,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   265
  i.~e. less jitter than user space code. It was foreseeable, that a
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   266
  fieldbus master has a lot of cyclic work to do. Cyclic work is
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   267
  usually triggered by timer interrupts inside the kernel. The
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   268
  execution delay of a function that processes timer interrupts is
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   269
  less, when it resides in kernel space, because there is no need of
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   270
  time-consuming context switches to a user space process.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   271
\item It was also foreseeable, that the master code has to directly
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   272
  communicate with the Ethernet hardware. This has to be done in the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   273
  kernel anyway (through network device drivers), which is one more
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   274
  reason for the master code being in kernel space.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   275
\end{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   276
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   277
A general overview of the master architecture can be seen in
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   278
figure~\ref{fig:masterarch}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   279
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   280
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   281
  \centering
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   282
  \includegraphics[width=.9\textwidth]{images/masterarch}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   283
  \caption{Master architecture}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   284
  \label{fig:masterarch}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   285
\end{figure}
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
\paragraph{Master Module}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   288
\index{Master module}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   289
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   290
The EtherCAT master mainly consists of the master module, containing
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   291
one or more EtherCAT masters (section~\ref{sec:mastermod}), the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   292
``Device Interface'' (section~\ref{sec:ecdev}) and the ``Realtime
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   293
Interface'' (section~\ref{sec:ecrt}).
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   294
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   295
\paragraph{Device Modules}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   296
\index{Device modules}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   297
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   298
Furthermore there are EtherCAT-capable network device driver
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   299
modules\index{Device modules}, that connect to the EtherCAT master via
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   300
the device interface. These modified network drivers can handle both
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   301
network devices used for EtherCAT operation and ``normal'' Ethernet
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   302
devices. The common case is, that the master module offers a single
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   303
EtherCAT master: An EtherCAT-capable network device driver module
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   304
connects one network device to this master, that is now able to send
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   305
and receive EtherCAT frames, while all other network devices handled
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   306
by the network driver get connected to the kernel's network stack as
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   307
usual.
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
\paragraph{Realtime Modules}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   310
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   311
A ``realtime module''\index{Realtime module} is a kernel module, that
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   312
uses the EtherCAT master for cyclic exchange of process data with
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   313
EtherCAT slaves. Realtime modules are not part of the EtherCAT master
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   314
code\footnote{Although there are serveral examples provided in the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   315
  \textit{examples} directory, see chapter~\ref{chapter:usage} for
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   316
  more information}, so anybody wanting to use the master has to write
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   317
one. A realtime module can ``request'' a master through the realtime
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   318
interface. If this succeeds, the module has the control over the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   319
master. It can now configure slaves and set up a process data image
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   320
(see section~\ref{sec:processdata}) for cyclic exchange. This cyclic
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   321
code has to be provided by the realtime module, so it is in hands of
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   322
the developer, which mechanism to use for this. Moreover he has to
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   323
decide, whether or not using a Linux realtime extension.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   324
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   325
\paragraph{Why ``Realtime'' Module?}
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
The name shall not imply, that a linux realtime extension is
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   328
mandatory: The master runs well even without realtime extensions, as
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   329
section~\ref{sec:mini} shows. However, the code using the master is
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   330
time-critical, because process data IO has to be done in cyclic work.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   331
Some EtherCAT slaves support watchdog units, that stop driving the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   332
outputs when process data was not exchanged for some time. So the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   333
names ``realtime interface'' and ``realtime module'' are quite
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   334
appropriate.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   335
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   336
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   337
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   338
\subsection{Handling of Process Data}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   339
\label{sec:processdata}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   340
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   341
\paragraph{Process Data Image}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   342
\index{Process data}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   343
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   344
The slaves offer their inputs and outputs by presenting the master
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
   345
so-called ``Process Data Objects'' (Pdos\index{Pdo}). The available
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
   346
Pdos can be determined by reading out the slave's TXPDO and RXPDO
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
   347
E$^2$PROM categories. The realtime module can register the Pdos for
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
   348
data exchange during cyclic operation. The sum of all registered Pdos
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   349
defines the ``process data image'', which is exchanged via the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   350
``Logical ReadWrite'' datagrams introduced
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   351
in~\cite[section~5.4.2.4]{dlspec}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   352
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   353
\paragraph{Process Data Domains}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   354
\index{Domain}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   355
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   356
The process data image can be easily managed by creating co-called
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
   357
``domains'', which group Pdos and allocate the datagrams needed to
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   358
exchange them. Domains are mandatory for process data exchange, so
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   359
there has to be at least one. They were introduced for the following
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   360
reasons:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   361
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   362
\begin{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   363
\item The maximum size of a ``Logical ReadWrite'' datagram is limited
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   364
  due to the limited size of an Ethernet frame: The maximum data size
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   365
  is the Ethernet data field size minus the EtherCAT frame header,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   366
  EtherCAT datagram header and EtherCAT datagram footer: $1500 - 2 -
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   367
  12 - 2 = 1484$ octets. If the size of the process data image exceeds
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   368
  this limit, multiple frames have to be sent, and the image has to be
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   369
  partitioned for the use of multiple datagrams. A domain manages this
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   370
  automatically.
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
   371
\item Not every Pdo has to be exchanged with the same frequency: The
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
   372
  values of Pdos can vary slowly over time (for example temperature
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   373
  values), so exchanging them with a high frequency would just waste
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   374
  bus bandwidth. For this reason, multiple domains can be created, to
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
   375
  group different Pdos and so allow separate exchange.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   376
\end{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   377
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   378
There is no upper limit for the number of domains, but each domain
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   379
occupies one FMMU in each slave involved, so the maximum number of
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   380
domains is also limited by the slaves' capabilities.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   381
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   382
\paragraph{FMMU Configuration}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   383
\index{FMMU!Configuration}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   384
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
   385
A realtime module can register Pdos for process data exchange. Every
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
   386
Pdo is part of a memory area in the slave's physical memory, that is
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   387
protected by a sync manager \cite[section~6.7]{dlspec} for
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   388
synchronized access. In order to make a sync manager react on a
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   389
datagram accessing its memory, it is necessary to access the last byte
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   390
covered by the sync manager. Otherwise the sync manager will not react
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   391
on the datagram and no data will be exchanged. That is why the whole
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   392
synchronized memory area has to be included into the process data
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
   393
image: For example, if a certain Pdo of a slave is registered for
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   394
exchange with a certain domain, one FMMU will be configured to map the
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
   395
complete sync-manager-protected memory, the Pdo resides in. If a
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
   396
second Pdo of the same slave is registered for process data exchange
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
   397
within the same domain, and this Pdo resides in the same
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
   398
sync-manager-protected memory as the first Pdo, the FMMU configuration
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   399
is not touched, because the appropriate memory is already part of the
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
   400
domain's process data image.  If the second Pdo belongs to another
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   401
sync-manager-protected area, this complete area is also included into
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   402
the domains process data image. See figure~\ref{fig:fmmus} for an
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   403
overview, how FMMU's are configured to map physical memory to logical
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   404
process data images.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   405
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   406
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   407
  \centering
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   408
  \includegraphics[width=\textwidth]{images/fmmus}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   409
  \caption{FMMU configuration for serveral domains}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   410
  \label{fig:fmmus}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   411
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   412
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   413
\paragraph{Process Data Pointers}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   414
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   415
The figure also demonstrates the way, the realtime module can access the
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
   416
exchanged process data: At Pdo registration, the realtime module has
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   417
to provide the address of a process data pointer. Upon calculation of
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   418
the domain image and allocation of process data memory, this pointer
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   419
is redirected to the appropriate location inside the domain's process
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   420
data memory and can later be easily dereferenced by the module code.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   421
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   422
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   423
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   424
\subsection{Operation Modes}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   425
\index{Master modes}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   426
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   427
The EtherCAT master has serveral modes of operation:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   428
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   429
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   430
\item[Orphaned Mode] This mode takes effect, when the master has no
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   431
  EtherCAT-capable network device connected. No bus communication is
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   432
  possible, so this mode is not of further interest.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   433
\item[Idle Mode]\index{Idle mode} takes effect when the master is
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   434
  unused (i.~e. there is no realtime module, that reserved the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   435
  master). In this case, the master has the ability to scan the bus by
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   436
  itsself and generously allow bus access from user space.  This mode
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   437
  is meant for maintenance and visualisation.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   438
\item[Operation Mode]\index{Operation mode} The master is reserved for
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   439
  exclusive access by a realtime module. In this mode, the master is
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   440
  adjusted for availability and monitoring. Access from user space is
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   441
  very restrictive and mostly limited to reading direction.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   442
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   443
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   444
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   445
Figure~\ref{fig:modes} shows the three modes and the possible mode
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   446
transitions.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   447
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   448
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   449
  \centering
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   450
  \includegraphics[width=.9\textwidth]{images/modes}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   451
  \caption{Master modes and transitions}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   452
  \label{fig:modes}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   453
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   454
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   455
\subsubsection{Idle Mode}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   456
\index{Idle mode}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   457
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   458
The master enters idle mode upon connection of a device module (see
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   459
section~\ref{sec:device}) or releasing by a realtime module. The
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   460
master owns a kernel workqueue and a suitable work structure, which is
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   461
used to cyclically process the ``Idle state machine'' (see
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   462
section~\ref{sec:fsm-idle}). This state machine automatically scans
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   463
the bus for slaves (and re-scans upon topology changes), configures
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   464
slaves for idle operation and executes pending operations from the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   465
user space interface (for example E$^2$PROM writing). On device
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   466
disconnection or realtime request, the idle mode is stopped by
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   467
cancelling the work and flushing the workqueue.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   468
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   469
\subsubsection{Operation Mode}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   470
\index{Operation mode}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   471
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   472
Operation mode is entered when a realtime module requests the master.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   473
The idle mode is stopped and the bus is scanned by getting the number
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   474
of slaves and executing the ``Slave scan state machine'' (see
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   475
section~\ref{sec:fsm-scan}) for each slave. The master is now ready to
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
   476
create domains and accept Pdo registrations and slave configurations.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   477
After that, cyclic communication can be done by the realtime module.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   478
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   479
\paragraph{Master Phases}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   480
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   481
Every realtime module should use the master in three phases:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   482
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   483
\begin{enumerate}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   484
\item \textit{Startup} - The master is requested and the bus is
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
   485
  validated. Domains are created and Pdos are registered. Slave
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   486
  configurations are applied.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   487
\item \textit{Operation} - Cyclic code is run, process data is
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   488
  exchanged and the master state machine is executed.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   489
\item \textit{Shutdown} - Cyclic code is stopped and the master
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   490
  is released.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   491
\end{enumerate}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   492
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   493
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   494
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   495
\section{Device Modules}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   496
\label{sec:device}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   497
\index{Device modules}
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
Device modules are network device driver modules that handle Ethernet
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   500
devices, which the master can use to connect to an EtherCAT bus.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   501
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   502
Section~\ref{sec:networkdrivers} offers an overview of general Linux
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   503
network driver modules, while section~\ref{sec:requirements} will show
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   504
the requirements to an EtherCAT-enabled network driver. Finally,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   505
sections~\ref{sec:seldev} to~\ref{sec:patching} show how to fulfill
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   506
these requirements and implement such a driver module.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   507
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   508
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   509
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   510
\subsection{Network Driver Basics}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   511
\label{sec:networkdrivers}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   512
\index{Network drivers}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   513
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   514
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
   515
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
   516
to understand how Linux handles network devices and their drivers,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   517
respectively.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   518
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   519
\paragraph{Tasks of a Network Driver}
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
Network device drivers handle the lower two layers of the OSI model,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   522
that is the physical layer and the data-link layer. A network device
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   523
itself natively handles the physical layer issues: It represents the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   524
hardware to connect to the medium and to send and receive data in the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   525
way, the physical layer protocol describes. The network device driver
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   526
is responsible for getting data from the kernel's networking stack and
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   527
forwarding it to the hardware, that does the physical transmission.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   528
If data is received by the hardware respectively, the driver is
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   529
notified (usually by means of an interrupt) and has to read the data
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   530
from the hardware memory and forward it to the network stack. There
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   531
are a few more tasks, a network device driver has to handle, including
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   532
queue control, statistics and device dependent features.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   533
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   534
\paragraph{Driver Startup}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   535
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   536
Usually, a driver searches for compatible devices on module loading.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   537
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
   538
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
   539
and the device is taken into operation.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   540
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   541
\paragraph{Interrupt Operation}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   542
\index{Interrupt}
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
A network device usually provides a hardware interrupt that is used to
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   545
notify the driver of received frames and success of transmittion, or
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   546
errors, respectively. The driver has to register an interrupt service
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   547
routine (ISR\index{ISR}\nomenclature{ISR}{Interrupt Service Routine}),
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   548
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
   549
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
   550
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
   551
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
   552
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
   553
to kernel memory and passed to the network stack.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   554
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   555
\paragraph{The net\_device structure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   556
\index{net\_device}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   557
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   558
The driver registers a \textit{net\_device} structure for each device
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   559
to communicate with the network stack and to create a ``network
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   560
interface''. In case of an Ethernet driver, this interface appears as
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   561
\textit{ethX}, where X is a number assigned by the kernel on
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   562
registration. The \textit{net\_device} structure receives events
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   563
(either from user space or from the network stack) via serveral
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   564
callbacks, which have to be set before registration. Not every
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   565
callback is mandatory, but for reasonable operation the ones below are
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   566
needed in any case:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   567
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   568
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   569
\item[int (*open)(struct net\_device *)] This function is called when
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   570
  network communication has to be started, for example after a command
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   571
  \textit{ifconfig ethX up} from user space. Frame reception has to be
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   572
  enabled by the driver.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   573
\item[int (*stop)(struct net\_device *)] The purpose of this callback
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   574
  is to ``close'' the device, i.~e. make the hardware stop receiving
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   575
  frames.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   576
\item[int (*hard\_start\_xmit)(struct sk\_buff *, struct net\_device
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   577
  *)] This function is cal\-led for each frame that has to be
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   578
  transmitted.  The network stack passes the frame as a pointer to an
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   579
  \textit{sk\_buff} structure (``socket buffer''\index{Socket buffer},
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   580
  see below), which has to be freed after sending.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   581
\item[struct net\_device\_stats *(*get\_stats)(struct net\_device *)]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   582
  This call has to return a pointer to the device's
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   583
  \textit{net\_device\_stats} structure, which permanently has to be
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   584
  filled with frame statistics. This means, that everytime a frame is
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   585
  received, sent, or an error happened, the appropriate counter in
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   586
  this structure has to be increased.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   587
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   588
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   589
The actual registration is done with the \textit{register\_netdev()}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   590
call, unregistering is done with \textit{unregister\_netdev()}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   591
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   592
\paragraph{The netif Interface}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   593
\index{netif}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   594
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   595
All other communication in the direction interface $\to$ network stack
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   596
is done via the \textit{netif\_*} calls. For example, on successful
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   597
device opening, the network stack has to be notified, that it can now
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   598
pass frames to the interface. This is done by calling
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   599
\textit{netif\_start\_queue()}. After this call, the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   600
\textit{hard\_start\_xmit()} callback can be called by the network
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   601
stack. Furthermore a network driver usually manages a frame
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   602
transmission queue. If this gets filled up, the network stack has to
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   603
be told to stop passing further frames for a while. This happens with
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   604
a call to \textit{netif\_stop\_queue()}. If some frames have been
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   605
sent, and there is enough space again to queue new frames, this can be
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   606
notified with \textit{netif\_wake\_queue()}. Another important call is
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   607
\textit{netif\_receive\_skb()}\footnote{This function is part of the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   608
  NAPI (``New API''), that replaces the ``old'' kernel 2.4 technique
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   609
  for interfacing to the network stack (with \textit{netif\_rx()}).
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   610
  NAPI is a technique to improve network performance on Linux. Read
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   611
  more in
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   612
  http://www.cyberus.ca/\textasciitilde{}hadi/usenix-paper.tgz}: It
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   613
passes a frame to the network stack, that was just received by the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   614
device.  Frame data has to be packed into a so-called ``socket
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   615
buffer'' for that (see below).
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   616
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   617
\paragraph{Socket Buffers}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   618
\index{Socket buffer}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   619
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   620
Socket buffers are the basic data type for the whole network stack.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   621
They serve as containers for network data and are able to quickly add
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   622
data headers and footers, or strip them off again. Therefore a socket
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   623
buffer consists of an allocated buffer and serveral pointers that mark
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   624
beginning of the buffer (\textit{head}), beginning of data
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   625
(\textit{data}), end of data (\textit{tail}) and end of buffer
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   626
(\textit{end}). In addition, a socket buffer holds network header
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   627
information and (in case of received data) a pointer to the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   628
\textit{net\_device}, it was received on. There exist functions that
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   629
create a socket buffer (\textit{dev\_alloc\_skb()}), add data either
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   630
from front (\textit{skb\_push()}) or back (\textit{skb\_put()}),
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   631
remove data from front (\textit{skb\_pull()}) or back
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   632
(\textit{skb\_trim()}), or delete the buffer (\textit{kfree\_skb()}).
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   633
A socket buffer is passed from layer to layer, and is freed by the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   634
layer that uses it the last time. In case of sending, freeing has to
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   635
be done by the network driver.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   636
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   637
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   638
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   639
\subsection{EtherCAT Network Drivers}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   640
\label{sec:requirements}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   641
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   642
There are a few requirements for Ethernet network devices to function
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   643
as EtherCAT devices, when connected to an EtherCAT bus.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   644
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   645
\paragraph{Dedicated Interfaces}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   646
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   647
For performance and realtime purposes, the EtherCAT master needs
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   648
direct and exclusive access to the Ethernet hardware. This implies
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   649
that the network device must not be connected to the kernel's network
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   650
stack as usual, because the kernel would try to use it as an ordinary
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   651
Ethernet device.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   652
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   653
\paragraph{Interrupt-less Operation}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   654
\index{Interrupt}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   655
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   656
EtherCAT frames travel through the logical EtherCAT ring and are then
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   657
sent back to the master. Communication is highly deterministic: A
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   658
frame is sent and will be received again after a constant time.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   659
Therefore, there is no need to notify the driver about frame
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   660
reception: The master can instead query the hardware for received
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   661
frames.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   662
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   663
Figure~\ref{fig:interrupt} shows two workflows for cyclic frame
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   664
transmittion and reception with and without interrupts.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   665
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   666
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   667
  \centering
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   668
  \includegraphics[width=.8\textwidth]{images/interrupt}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   669
  \caption{Interrupt Operation versus Interrupt-less Operation}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   670
  \label{fig:interrupt}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   671
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   672
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   673
In the left workflow ``Interrupt Operation'', the data from the last
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   674
cycle is first processed and a new frame is assembled with new
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   675
datagrams, which is then sent.  The cyclic work is done for now.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   676
Later, when the frame is received again by the hardware, an interrupt
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   677
is triggered and the ISR is executed. The ISR will fetch the frame
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   678
data from the hardware and initiate the frame dissection: The
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   679
datagrams will be processed, so that the data is ready for processing
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   680
in the next cycle.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   681
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   682
In the right workflow ``Interrupt-less Operation'', there is no
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   683
hardware interrupt enabled.  Instead, the hardware will be polled by
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   684
the master by executing the ISR. If the frame has been received in the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   685
meantime, it will be dissected. The situation is now the same as at
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   686
the beginning of the left workflow: The received data is processed and
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   687
a new frame is assembled and sent. There is nothing to do for the rest
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   688
of the cycle.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   689
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   690
The interrupt-less operation is desirable, because there is simply no
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   691
need for an interrupt. Moreover hardware interrupts are not conducive
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   692
in improving the driver's realtime behaviour: Their undeterministic
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   693
incidences contribute to increasing the jitter. Besides, if a realtime
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   694
extension (like RTAI) is used, some additional effort would have to be
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   695
made to priorize interrupts.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   696
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   697
\paragraph{Ethernet and EtherCAT Devices}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   698
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   699
Another issue lies in the way Linux handles devices of the same type.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   700
For example, a PCI\nomenclature{PCI}{Peripheral Component
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   701
  Interconnect, Computer Bus} driver scans the PCI bus for devices it
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   702
can handle. Then it registers itself as the responsible driver for all
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   703
of the devices found. The problem is, that an unmodified driver can
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   704
not be told to ignore a device because it will be used for EtherCAT
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   705
later. There must be a way to handle multiple devices of the same
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   706
type, where one is reserved for EtherCAT, while the other is treated
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   707
as an ordinary Ethernet device.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   708
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   709
For all this reasons, the author has decided that the only acceptable
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   710
solution is to modify standard Ethernet drivers in a way that they
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   711
keep their normal functionality, but gain the ability to treat one or
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   712
more of the devices as EtherCAT-capable.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   713
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   714
Below are the advantages of this solution:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   715
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   716
\begin{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   717
\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
   718
\item One networking driver for EtherCAT and non-EtherCAT devices.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   719
\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
   720
  into issues, the former developers already solved.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   721
\end{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   722
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   723
The chosen approach has the following disadvantages:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   724
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   725
\begin{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   726
\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
   727
  EtherCAT and non-EtherCAT devices.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   728
\item Many additional case differentiations in the driver code.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   729
\item Changes and bugfixes on the standard drivers have to be ported
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   730
  to the Ether\-CAT-capable versions from time to time.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   731
\end{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   732
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   733
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   734
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   735
\subsection{Device Selection}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   736
\label{sec:seldev}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   737
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   738
After loading the master module, at least one EtherCAT-capable network
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   739
driver module has to be loaded, that connects one of its devices to
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   740
the master. To specify an EtherCAT device and the master to connect
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   741
to, all EtherCAT-capable network driver modules should provide two
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   742
module parameters:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   743
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   744
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   745
\item[ec\_device\_index] PCI device index of the device that is
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   746
  connected to the EtherCAT bus. If this parameter is left away, all
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   747
  devices found are treated as ordinary Ethernet devices. Default:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   748
  $-1$
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   749
\item[ec\_master\_index] Index of the master to connect to. Default:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   750
  $0$
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   751
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   752
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   753
The following command loads the EtherCAT-capable RTL8139 device
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   754
driver, telling it to handle the second device as an EtherCAT device
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   755
and connecting it to the first master:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   756
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   757
\begin{lstlisting}
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
   758
  # `\textbf{modprobe ec\_8139too ec\_device\_index=1}`
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   759
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   760
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   761
Usually, this command does not have to be entered manually, but is
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   762
called by the EtherCAT init script. See section~\ref{sec:init} for
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   763
more information.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   764
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   765
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   766
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   767
\subsection{The Device Interface}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   768
\label{sec:ecdev}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   769
\index{Device interface}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   770
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   771
An anticipation to the section about the master module
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   772
(section~\ref{sec:mastermod}) has to be made in order to understand
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   773
the way, a network device driver module can connect a device to a
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   774
specific EtherCAT master.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   775
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   776
The master module provides a ``device interface'' for network device
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   777
drivers. To use this interface, a network device driver module must
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   778
include the header
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   779
\textit{devices/ecdev.h}\nomenclature{ecdev}{EtherCAT Device}, coming
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   780
with the EtherCAT master code. This header offers a function interface
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   781
for EtherCAT devices which is explained below. All functions of the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   782
device interface are named with the prefix \textit{ecdev}.
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
\paragraph{Device Registration}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   785
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   786
A network device driver can connect a physical device to an EtherCAT
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   787
master with the \textit{ecdev\_register()} function.
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
\begin{lstlisting}[language=C]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   790
  ec_device_t *ecdev_register(unsigned int master_index,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   791
                              struct net_device *net_dev,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   792
                              ec_isr_t isr,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   793
                              struct module *module);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   794
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   795
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   796
The first parameter \textit{master\_index} must be the index of the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   797
EtherCAT master to connect to (see section~\ref{sec:mastermod}),
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   798
followed by \textit{net\_dev}, the pointer to the corresponding
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   799
net\_device structure, which represents the network device to connect.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   800
The third parameter \textit{isr} must be a pointer to the interrupt
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   801
service routine (ISR\index{ISR}) handling the device. The master will
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   802
later execute the ISR in order to receive frames and to update the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   803
device status. The last parameter \textit{module} must be the pointer
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   804
to the device driver module, which is usually accessible via the macro
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   805
\textit{THIS\_MODULE} (see next paragraph). On success, the function
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   806
returns a pointer to an \textit{ec\_device\_t} object, which has to be
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   807
specified when calling further functions of the device interface.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   808
Therefore the device module has to store this pointer for future use.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   809
In error case, the \textit{ecdev\_register()} returns \textit{NULL},
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   810
which means that the device could not be registered.  The reason for
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   811
this is printed to \textit{syslog}\index{syslog}. In this case, the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   812
device module is supposed to abort the module initialisation and let
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   813
the \textit{insmod} command fail.
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{Implicit Dependencies}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   816
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   817
The reason for the module pointer has to be specified at device
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   818
registration is a non-trivial one: The master has to know about the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   819
module, because there will be an implicit dependency between the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   820
device module and a later connected realtime module: When a realtime
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   821
module connects to the master, the use count of the master module will
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   822
be increased, so that the master module can not be unloaded for the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   823
time of the connection. This is reasonable, and so automatically done
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   824
by the kernel. The kernel knows about this dependency, because the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   825
realtime module uses kernel symbols provided by the master module.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   826
Moreover it is mandatory, that the device module can be unloaded
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   827
neither, because it is implicitely used by the realtime module, too.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   828
Unloading it would lead to a fatal situation, because the master would
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   829
have no device to send and receive frames for the realtime module.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   830
This dependency can not be detected automatically, because the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   831
realtime module does not use any symbols of the device module.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   832
Therefore the master explicitly increments the use counter of the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   833
connected device module upon connection of a realtime module and
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   834
decrements it, if the realtime module disconnects. In this manner, it
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   835
is impossible to unload a device module while the master is in use.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   836
This is done with the kernel function pair \textit{try\_module\_get()}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   837
\index{try\_module\_get@\textit{try\_module\_get()}} and
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   838
\textit{module\_put()} \index{module\_put@\textit{module\_put()}}. The
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   839
first one increases the use count of a module and only fails, if the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   840
module is currenly being unloaded. The last one decreases the use
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   841
count again and never fails. Both functions take a pointer to the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   842
module as their argument, which the device module therefore has to
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   843
specify upon device registration.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   844
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   845
\paragraph{Device Unregistering}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   846
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   847
The unregistration of a device is usually done in the device module's
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   848
cleanup function, by calling the \textit{ecdev\_unregister()} function
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   849
and specifying the master index and a pointer to the device object
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   850
again.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   851
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   852
\begin{lstlisting}[language=C]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   853
  void ecdev_unregister(unsigned int master_index,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   854
                        ec_device_t *device);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   855
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   856
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   857
This function can fail too (if the master index is invalid, or the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   858
given device was not registered), but due to the fact, that this
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   859
failure can not be dealt with appropriately, because the device module
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   860
is unloading anyway, the failure code would not be of any interest. So
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   861
the function has a void return value.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   862
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   863
\paragraph{Starting the Master}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   864
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   865
When a device has been initialized completely and is ready to send and
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   866
receive frames, the master has to be notified about this by calling
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   867
the \textit{ecdev\_start()} function.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   868
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   869
\begin{lstlisting}[language=C]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   870
  int ecdev_start(unsigned int master_index);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   871
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   872
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   873
The master will then enter ``Idle Mode'' and start scanning the bus
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   874
(and possibly handling EoE slaves). Moreover it will make the bus
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   875
accessible via Sysfs interface and react to user interactions. The
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   876
function takes one parameter \textit{master\_index}, which has to be
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   877
the same as at the call to \textit{ecdev\_register()}. The return
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   878
value will be non-zero if the starting process failed. In this case
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   879
the device module is supposed to abort the init sequence and make the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   880
init function return an error code.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   881
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   882
\paragraph{Stopping the Master}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   883
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   884
Before a device can be unregistered, the master has to be stopped by
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   885
calling the \textit{ecdev\_stop()} function. It will stop processing
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   886
messages of EoE slaves and leave ``Idle Mode''. The only parameter is
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   887
\textit{master\_index}. This function can not fail.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   888
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   889
\begin{lstlisting}[language=C]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   890
  void ecdev_stop(unsigned int master_index);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   891
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   892
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   893
A subsequent call to \textit{ecdev\_unregister()} will now unregister
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   894
the device savely.
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{Receiving Frames}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   897
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   898
The interrupt service routine handling device events usually has a
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   899
section where new frames are fetched from the hardware and forwarded
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   900
to the kernel network stack via \textit{netif\_receive\_skb()}. For an
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   901
EtherCAT-capable device, this has to be replaced by calling the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   902
\textit{ecdev\_receive()} function to forward the received data to the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   903
connected EtherCAT master instead.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   904
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   905
\begin{lstlisting}[language=C]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   906
  void ecdev_receive(ec_device_t *device,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   907
                     const void *data,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   908
                     size_t size);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   909
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   910
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   911
This function takes 3 arguments, a pointer to the device object
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   912
(\textit{device}), a pointer to the received data, and the size of the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   913
received data. The data range has to include the Ethernet headers
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   914
starting with the destination address and reach up to the last octet
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   915
of EtherCAT data, excluding the FCS. Most network devices handle the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   916
FCS in hardware, so it is not seen by the driver code and therefore
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   917
doesn't have to be cut off manually.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   918
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   919
\paragraph{Handling the Link Status}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   920
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   921
Information about the link status (i.~e. if there is a carrier signal
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   922
detected on the physical port) is also important to the master. This
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   923
information is usually gathered by the ISR and should be forwarded to
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   924
the master by calling the \textit{ecdev\_link\_state()} function. The
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   925
master then can react on this and warn the realtime module of a lost
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   926
link.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   927
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   928
\begin{lstlisting}[language=C]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   929
  void ecdev_link_state(ec_device_t *device,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   930
                        uint8_t new_state);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   931
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   932
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   933
The parameter \textit{device} has to be a pointer to the device object
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   934
returned by \textit{ecdev\_\-register()}. With the second parameter
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   935
\textit{new\_state}, the new link state is passed: 1, if the link went
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   936
up, and 0, if it went down.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   937
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   938
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   939
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   940
\subsection{Patching Network Drivers}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   941
\label{sec:patching}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   942
\index{Network drivers}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   943
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   944
This section will demonstrate, how to make a standard Ethernet driver
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   945
EtherCAT-capable. The below code examples are taken out of the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   946
modified RealTek RTL8139 driver coming with the EtherCAT master
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   947
(\textit{devices/8139too.c}). The driver was originally developed by
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   948
Donald Becker, and is currently maintained by Jeff Garzik.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   949
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   950
Unfortunately, there is no standard procedure to enable an Ethernet
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   951
driver for use with the EtherCAT master, but there are a few common
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   952
techniques, that are described in this section.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   953
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   954
\begin{enumerate}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   955
\item A first simple rule is, that \textit{netif\_*()}-calls must be
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   956
  strictly avoided for all EtherCAT devices. As mentioned before,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   957
  EtherCAT devices have no connection to the network stack, and
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   958
  therefore must not call its interface functions.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   959
\item Another important thing is, that EtherCAT devices should be
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   960
  operated without interrupts. So any calls of registering interrupt
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   961
  handlers and enabling interrupts at hardware level must be avoided,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   962
  too.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   963
\item The master does not use a new socket buffer for each send
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   964
  operation: Instead there is a fix one allocated on master
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   965
  initialization. This socket buffer is filled with an EtherCAT frame
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   966
  with every send operation and passed to the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   967
  \textit{hard\_start\_xmit()} callback. For that it is necessary,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   968
  that the socket buffer is not be freed by the network driver as
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   969
  usual.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   970
\end{enumerate}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   971
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   972
As mentioned before, the driver will handle both EtherCAT and ordinary
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   973
Ethernet devices. This implies, that for each device-dependent
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   974
operation, it has to be checked if an EtherCAT device is involved, or
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   975
just an Ethernet device. For means of simplicity, this example driver
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   976
will only handle one EtherCAT device. This makes the case
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   977
differentiations easier.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   978
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   979
\paragraph{Global Variables}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   980
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   981
First of all, there have to be additional global variables declared,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   982
as shown in the listing:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   983
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   984
\begin{lstlisting}[language=C,numbers=left]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   985
  static int ec_device_index = -1;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   986
  static int ec_device_master_index = 0;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   987
  static ec_device_t *rtl_ec_dev;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   988
  struct net_device *rtl_ec_net_dev = NULL;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   989
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   990
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   991
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   992
\item[\normalfont\textcircled{\tiny 1} -- \textcircled{\tiny 2}] To
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   993
  comply to the requirements for parameters of EtherCAT device modules
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   994
  described in section~\ref{sec:seldev}, there have to be additional
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   995
  parameter variables: \textit{ec\_\-device\_\-index} holds the index
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   996
  of the EtherCAT device and defaults to $-1$ (no EtherCAT device),
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   997
  while \textit{ec\_device\_master\_index} stores index of the master,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   998
  the single device will be connected to. Default: $0$
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   999
\item[\normalfont\textcircled{\tiny 3}] \textit{rtl\_ec\_dev} will be
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1000
  the pointer to the later registered RealTek EtherCAT device, which
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1001
  can be used as a parameter for device methods.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1002
\item[\normalfont\textcircled{\tiny 4}] \textit{rtl\_ec\_net\_dev} is
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1003
  a pointer to the \textit{net\_device} structure of the dedicated
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1004
  device and is set while scanning the PCI bus and finding the device
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1005
  with the specified index. This is done inside the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1006
  \textit{pci\_module\_init()} function executed as the first thing on
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1007
  module loading.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1008
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1009
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1010
\paragraph{Module Initialization}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1011
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1012
Below is the (shortened) coding of the device driver's module init
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1013
function:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1014
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1015
\begin{lstlisting}[language=C,numbers=left]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1016
  static int __init rtl8139_init_module(void)
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
          if (pci_module_init(&rtl8139_pci_driver) < 0) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1019
                  printk(KERN_ERR "Failed to init PCI mod.\n");
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1020
                  goto out_return;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1021
          }
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
          if (rtl_ec_net_dev) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1024
                  printk(KERN_INFO "Registering"
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1025
                         " EtherCAT device...\n");
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1026
                  if (!(rtl_ec_dev =
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1027
                          ecdev_register(ec_device_master_index,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1028
                                         rtl_ec_net_dev,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1029
                                         rtl8139_interrupt,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1030
                                         THIS_MODULE))) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1031
                          printk(KERN_ERR "Failed to reg."
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1032
                                          " EtherCAT device!\n");
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1033
                          goto out_unreg_pci;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1034
                  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1035
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1036
                  printk(KERN_INFO "Starting EtherCAT"
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1037
                         " device...\n");
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1038
                  if (ecdev_start(ec_device_master_index)) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1039
                          printk(KERN_ERR "Failed to start"
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1040
                                 " EtherCAT device!\n");
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1041
                          goto out_unreg_ec;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1042
                  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1043
          } else {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1044
                  printk(KERN_WARNING "No EtherCAT device"
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1045
                         " registered!\n");
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1046
          }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1047
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1048
          return 0;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1049
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1050
      out_unreg_ec:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1051
          ecdev_unregister(ec_device_master_index, rtl_ec_dev);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1052
      out_unreg_pci:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1053
          pci_unregister_driver(&rtl8139_pci_driver);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1054
      out_return:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1055
          return -1;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1056
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1057
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1058
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1059
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1060
\item[\normalfont\textcircled{\tiny 3}] This call initializes all
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1061
  RTL8139-compatible devices found on the pci bus. If a device with
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1062
  index \textit{ec\_device\_index} is found, a pointer to its
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1063
  \textit{net\_device} structure is stored in
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1064
  \textit{rtl\_ec\_net\_dev} for later use (see next listings).
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1065
\item[\normalfont\textcircled{\tiny 8}] If the specified device was
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1066
  found, \textit{rtl\_ec\_net\_dev} is non-zero.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1067
\item[\normalfont\textcircled{\tiny 11}] The device is connected to
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1068
  the specified master with a call to \textit{ecdev\_register()}. If
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1069
  this fails, module loading is aborted.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1070
\item[\normalfont\textcircled{\tiny 23}] The device registration was
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1071
  successful and the master is started. This can fail, which aborts
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1072
  module loading.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1073
\item[\normalfont\textcircled{\tiny 29}] If no EtherCAT device was
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1074
  found, a warning is output.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1075
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1076
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1077
\paragraph{Device Searching}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1078
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1079
During the PCI initialization phase, a variable \textit{board\_idx} is
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1080
increased for each RTL8139-compatible device found. The code below is
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1081
executed for each device:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1082
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1083
\begin{lstlisting}[language=C,numbers=left]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1084
  if (board_idx == ec_device_index) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1085
          rtl_ec_net_dev = dev;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1086
          strcpy(dev->name, "ec0");
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1087
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1088
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1089
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1090
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1091
\item[\normalfont\textcircled{\tiny 1}] The device with the specified
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1092
  index will be the EtherCAT device.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1093
\end{description}
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
\paragraph{Avoiding Device Registration}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1096
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1097
Later in the PCI initialization phase, the net\_devices get
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1098
registered. This has to be avoided for EtherCAT devices and so this is
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1099
a typical example for an EtherCAT case differentiation:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1100
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1101
\begin{lstlisting}[language=C,numbers=left]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1102
  if (dev != rtl_ec_net_dev) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1103
          i = register_netdev(dev);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1104
          if (i) goto err_out;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1105
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1106
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1107
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1108
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1109
\item[\normalfont\textcircled{\tiny 1}] If the current net\_device is
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1110
  not the EtherCAT device, it is registered at the network stack.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1111
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1112
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1113
\paragraph{Avoiding Interrupt Registration}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1114
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1115
In the next two listings, there is an interrupt requested and the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1116
device's interrupts are enabled. This also has to be encapsulated by
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1117
if-clauses, because interrupt operation is not wanted for EtherCAT
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1118
devices.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1119
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1120
\begin{lstlisting}[language=C,numbers=left]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1121
  if (dev != rtl_ec_net_dev) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1122
          retval = request_irq(dev->irq, rtl8139_interrupt,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1123
                               SA_SHIRQ, dev->name, dev);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1124
          if (retval) return retval;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1125
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1126
\end{lstlisting}
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
\begin{lstlisting}[language=C,numbers=left]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1129
  if (dev != rtl_ec_net_dev) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1130
          /* Enable all known interrupts by setting
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1131
             the interrupt mask. */
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1132
          RTL_W16(IntrMask, rtl8139_intr_mask);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1133
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1134
\end{lstlisting}
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
\paragraph{Frame Sending}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1137
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1138
The listing below shows an exerpt of the function representing the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1139
\textit{hard\_start\_xmit()} callback of the net\_device.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1140
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1141
\begin{lstlisting}[language=C,numbers=left]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1142
  /* Note: the chip doesn't have auto-pad! */
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1143
  if (likely(len < TX_BUF_SIZE)) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1144
          if (len < ETH_ZLEN)
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1145
                  memset(tp->tx_buf[entry], 0, ETH_ZLEN);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1146
          skb_copy_and_csum_dev(skb, tp->tx_buf[entry]);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1147
          if (dev != rtl_ec_net_dev) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1148
                  dev_kfree_skb(skb);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1149
          }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1150
  } else {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1151
          if (dev != rtl_ec_net_dev) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1152
                  dev_kfree_skb(skb);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1153
          }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1154
          tp->stats.tx_dropped++;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1155
          return 0;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1156
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1157
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1158
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1159
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1160
\item[\normalfont\textcircled{\tiny 6} + \textcircled{\tiny 10}] The
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1161
  master uses a fixed socket buffer for transmission, which is reused
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1162
  and may not be freed.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1163
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1164
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1165
\paragraph{Frame Receiving}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1166
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1167
During ordinary frame reception, a socket buffer is created and filled
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1168
with the received data. This is not necessary for an EtherCAT device:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1169
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1170
\begin{lstlisting}[language=C,numbers=left]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1171
  if (dev != rtl_ec_net_dev) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1172
          /* Malloc up new buffer, compatible with net-2e. */
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1173
          /* Omit the four octet CRC from the length. */
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1174
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1175
          skb = dev_alloc_skb (pkt_size + 2);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1176
          if (likely(skb)) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1177
                  skb->dev = dev;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1178
                  skb_reserve(skb, 2); /* 16 byte align
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1179
                                          the IP fields. */
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1180
                  eth_copy_and_sum(skb, &rx_ring[ring_off + 4],
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1181
                                   pkt_size, 0);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1182
                  skb_put(skb, pkt_size);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1183
                  skb->protocol = eth_type_trans(skb, dev);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1184
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1185
                  dev->last_rx = jiffies;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1186
                  tp->stats.rx_bytes += pkt_size;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1187
                  tp->stats.rx_packets++;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1188
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1189
                  netif_receive_skb (skb);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1190
          } else {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1191
                  if (net_ratelimit())
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1192
                          printk(KERN_WARNING
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1193
                                 "%s: Memory squeeze, dropping"
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1194
                                 " packet.\n", dev->name);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1195
                  tp->stats.rx_dropped++;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1196
          }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1197
  } else {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1198
          ecdev_receive(rtl_ec_dev,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1199
                        &rx_ring[ring_offset + 4], pkt_size);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1200
          dev->last_rx = jiffies;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1201
          tp->stats.rx_bytes += pkt_size;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1202
          tp->stats.rx_packets++;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1203
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1204
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1205
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1206
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1207
\item[\normalfont\textcircled{\tiny 28}] If the device is an EtherCAT
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1208
  device, no socket buffer is allocated. Instead a pointer to the data
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1209
  (which is still in the device's receive ring) is passed to the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1210
  EtherCAT master. Unnecessary copy operations are avoided.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1211
\item[\normalfont\textcircled{\tiny 30} -- \textcircled{\tiny 32}] The
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1212
  device's statistics are updated as usual.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1213
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1214
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1215
\paragraph{Link State}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1216
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1217
The link state (i.~e. if there is a carrier signal detected on the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1218
receive port) is determined during execution of the ISR. The listing
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1219
below shows the different processing for Ethernet and EtherCAT
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1220
devices:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1221
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1222
\begin{lstlisting}[language=C,numbers=left]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1223
  if (dev != rtl_ec_net_dev) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1224
          if (tp->phys[0] >= 0) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1225
                  mii_check_media(&tp->mii, netif_msg_link(tp),
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1226
                                  init_media);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1227
          }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1228
  } else {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1229
          void __iomem *ioaddr = tp->mmio_addr;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1230
          uint16_t link = RTL_R16(BasicModeStatus)
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1231
                          & BMSR_LSTATUS;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1232
          ecdev_link_state(rtl_ec_dev, link ? 1 : 0);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1233
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1234
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1235
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1236
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1237
\item[\normalfont\textcircled{\tiny 3}] The ``media check'' is done
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1238
  via the media independent interface (MII\nomenclature{MII}{Media
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1239
    Independent Interface}), a standard interface for Fast Ethernet
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1240
  devices.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1241
\item[\normalfont\textcircled{\tiny 7} -- \textcircled{\tiny 10}] For
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1242
  EtherCAT devices, the link state is fetched manually from the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1243
  appropriate device register, and passed to the EtherCAT master by
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1244
  calling \textit{ecdev\_\-link\_\-state()}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1245
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1246
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1247
\paragraph{Module Cleanup}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1248
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1249
Below is the module's cleanup function:
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
\begin{lstlisting}[language=C,numbers=left]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1252
  static void __exit rtl8139_cleanup_module (void)
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1253
  {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1254
          printk(KERN_INFO "Cleaning up RTL8139-EtherCAT"
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1255
                 " module...\n");
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1256
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1257
          if (rtl_ec_net_dev) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1258
                  printk(KERN_INFO "Stopping device...\n");
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1259
                  ecdev_stop(ec_device_master_index);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1260
                  printk(KERN_INFO "Unregistering device...\n");
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1261
                  ecdev_unregister(ec_device_master_index,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1262
                                   rtl_ec_dev);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1263
                  rtl_ec_dev = NULL;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1264
          }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1265
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1266
          pci_unregister_driver(&rtl8139_pci_driver);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1267
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1268
          printk(KERN_INFO "RTL8139-EtherCAT module"
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1269
                 " cleaned up.\n");
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1270
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1271
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1272
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1273
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1274
\item[\normalfont\textcircled{\tiny 6}] Stopping and unregistration is
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1275
  only done, if a device was registered before.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1276
\item[\normalfont\textcircled{\tiny 8}] The master is first stopped,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1277
  so it does not access the device any more.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1278
\item[\normalfont\textcircled{\tiny 10}] After this, the device is
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1279
  unregistered. The master is now ``ophaned''.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1280
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1281
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1282
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1283
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1284
\section{The Master Module}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1285
\label{sec:mastermod}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1286
\index{Master module}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1287
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1288
The EtherCAT master is designed to run as a kernel module. Moreover
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1289
the master kernel module \textit{ec\_master} can handle multiple
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1290
masters at the same time: The number of masters has to be passed to
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1291
the module with the parameter \textit{ec\_master\_count}, that
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1292
defaults to $1$. A certain master can later be addressed by its index.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1293
For example, if the master module has been loaded with the command
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1294
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1295
\begin{lstlisting}
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  1296
  # `\textbf{modprobe ec\_master ec\_master\_count=2}`
369
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
the two masters can be addressed by their indices 0 and 1 respectively
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1300
(see figure~\ref{fig:masters}). This master index mandatory for
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1301
certain functions of the master interfaces.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1302
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1303
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1304
  \centering
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1305
  \includegraphics[width=.5\textwidth]{images/masters}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1306
  \caption{Multiple masters in one module}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1307
  \label{fig:masters}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1308
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1309
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1310
\paragraph{Master Log Messages}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1311
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1312
The master module gives information about it's state and events via
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1313
the syslog interface. The module loading command above should result
487
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
  1314
in the syslog messages below (or similar):
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1315
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1316
\begin{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1317
  EtherCAT: Master driver, 1.1 (stable) - rev. 513,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1318
            compiled by fp at Aug  09 2006 09:43:50
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1319
  EtherCAT: Initializing 2 EtherCAT master(s)...
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1320
  EtherCAT: Initializing master 0.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1321
  EtherCAT: Initializing master 1.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1322
  EtherCAT: Master driver initialized.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1323
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1324
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1325
The master provides information about it's version number, subversion
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1326
revision number and compile information, like the date of compilation
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1327
and the user, who compiled. All messages are prefixed either with
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1328
\texttt{EtherCAT:}, \texttt{EtherCAT WARNING:} or \texttt{EtherCAT
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1329
  ERROR:}, which makes searching the logs easier.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1330
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1331
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1332
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1333
\subsection{Class Reference}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1334
\label{sec:classes}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1335
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1336
This section is not intended to be a complete reference of master
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1337
classes and functions\footnote{The comprehensive master reference can
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1338
  be obtained at http://etherlab.org/download/download-en.html}, but
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1339
will give a general survey of the master's classes, and how they
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1340
interact.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1341
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1342
Figure~\ref{fig:uml-all} shows an UML class diagram of the master
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1343
classes.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1344
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1345
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1346
  \centering
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1347
  \includegraphics[width=\textwidth]{images/uml-all}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1348
  \caption{UML class diagram with associations}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1349
  \label{fig:uml-all}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1350
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1351
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1352
The following subsections introduce serveral classes with their
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1353
attributes and methods.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1354
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1355
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1356
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1357
\subsubsection{The Master Class}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1358
\label{sec:class-master}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1359
\index{Master!Class}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1360
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1361
Figure~\ref{fig:uml-master} shows an UML class diagram of the master
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1362
class. There is a short explanation of the attributes and methods
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1363
below.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1364
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1365
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1366
  \centering
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1367
  \includegraphics[width=.8\textwidth]{images/uml-master}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1368
  \caption{Master UML class diagram}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1369
  \label{fig:uml-master}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1370
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1371
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1372
\paragraph{Master Attributes}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1373
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1374
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1375
\item[list] is a listhead structure that is needed to manage the list
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1376
  of masters in the master module (see section~\ref{sec:mastermod}).
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1377
\item[reserved] is a flag, that marks the master as reserved for a
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1378
  realtime module, so that a call to \textit{ecrt\_request\_master()}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1379
  fails, if another module is already using the master.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1380
\item[index] contains the number of the master. The first master will
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1381
  get index 0, the second index 1, and so on.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1382
\item[kobj] In order to make the master object available via Sysfs
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1383
  (see section~\ref{sec:sysfs}), this structure is needed inside the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1384
  master object (see section~\ref{sec:sysfs}).
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1385
\item[slaves] is the list of slaves. It consists of objects of the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1386
  \textit{ec\_slave\_t} class (see section~\ref{sec:class-slave}).
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1387
\item[slave\_count] is the number of slaves in the list.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1388
\item[device] points to the network device that is used by the master
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1389
  to send and receive frames (see section~\ref{sec:class-device}). It
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1390
  is \textit{NULL}, if no device is connected.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1391
\item[datagram\_queue] is a list of datagrams (see
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1392
  section~\ref{sec:class-datagram}) that have to be sent by the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1393
  master, or have already been sent and wait to be received again.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1394
  Upon reception or error, the datagrams are dequeued.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1395
\item[datagram\_index] contains the index value for the next datagram.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1396
  The master stores this incrementing index into every datagram, to
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1397
  make it easier to assign a received datagram to the one sent before.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1398
\item[domains] contains the list of domains created by the realtime
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1399
  module (section~\ref{sec:class-domain}).
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1400
\item[debug\_level] controls, how much debugging output is printed by
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1401
  the master: 0 means no debugging output, 1 means to output certain
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1402
  executing marks and actions, and 2 means to output frame contents in
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1403
  addition. This value can be changed at runtime via the Sysfs
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1404
  interface (see section~\ref{sec:sysfs}).
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1405
\item[stats] is a statistics object that contains certain counters
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1406
  (like the number of missed frames).  These statistics are output on
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1407
  demand, but at most once a second.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1408
\item[workqueue] is the kernel workqueue used for idle mode.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1409
\item[idle\_work] is the work object, that is queued.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1410
\item[fsm] The attribute \textit{fsm} represents the master's finite
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1411
  state machine, that does all the slave processing. See
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1412
  sections~\ref{sec:class-fsm} and~\ref{sec:fsm} for further details.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1413
\item[mode] contains the current master mode, if it is orphaned, idle,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1414
  or in operation mode.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1415
\item[eoe\_timer] is the kernel timer used for EoE\index{EoE}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1416
  processing.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1417
\item[eoe\_running] marks the state of EoE processing.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1418
\item[eoe\_handlers] is the list of EoE handlers (see
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1419
  section~\ref{sec:class-eoe}).
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1420
\item[internal\_lock] is a spinlock used in idle mode, that controls
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1421
  the concurrency of the idle and EoE processes.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1422
\item[request\_cb] The ``request lock'' callback function, the master
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1423
  has to provide for foreign instances, which want to access the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1424
  master (see section~\ref{sec:concurr}).
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1425
\item[release\_cb] The callback function that will release the master
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1426
  lock.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1427
\item[cb\_data] This value will be passed as an argument to each
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1428
  callback.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1429
\item[eeprom\_write\_enable] flag can be written via Sysfs to enable
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1430
  the general writing of E$^2$PROM contents.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1431
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1432
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1433
\paragraph{Public Master Methods}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1434
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1435
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1436
\item[ec\_master\_init()] is the master's constructor. It initializes
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1437
  all attributes, creates the workqueue, creates EoE handlers and the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1438
  state machine object, and adds the kernel object to the Sysfs
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1439
  hierarchy.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1440
\item[ec\_master\_clear()] is the destructor and undoes all these
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1441
  actions.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1442
\item[ec\_master\_reset()] clears the master, but initializes it
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1443
  again. This is needed, when a realtime module disconnects: Slaves
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1444
  and other attributes are cleared and are later rebuilt by the idle
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1445
  process.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1446
\item[ec\_master\_idle\_start/stop()] These methods enable or disable
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1447
  the idle process.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1448
\item[ec\_master\_eoe\_start/stop()] These methods do the same for the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1449
  EoE timer.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1450
\item[ec\_master\_receive\_datagrams()] This method is called by the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1451
  device, which uses it to pass received frames to the master.  The
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1452
  frame is dissected and the contained datagrams are assigned to the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1453
  datagram objects in the datagram queue, which are dequeued on
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1454
  reception or error.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1455
\item[ec\_master\_queue\_datagram()] This method is used to queue a
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1456
  new datagram for sending and receiving.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1457
\item[ec\_master\_output\_stats()] This method is cyclically called to
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1458
  output a summary of the \textit{stats} attribute at most once a
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1459
  second.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1460
\item[ec\_master\_clear\_slaves()] clears the list of slaves. This is
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1461
  needed on connection/disconnection of a realtime module or at a
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1462
  topology change in idle mode, when all slaves objects are rebuilt.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1463
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1464
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1465
\paragraph{Private Master Methods}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1466
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1467
A few of a master's methods are private, meaning, that they can only
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1468
be called from other master methods:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1469
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1470
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1471
\item[ec\_master\_send\_datagrams()] searches the datagram queue for
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1472
  unsent datagrams, allocates frames to send them, does the actual
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1473
  sending and marks the datagrams as sent.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1474
\item[ec\_master\_idle\_run()] is the work function for the idle mode.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1475
  It executes the idle state machine, described in
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1476
  section~\ref{sec:fsm-idle}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1477
\item[ec\_master\_eoe\_run()] is called by the EoE timer and is
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1478
  responsible for communicating with EoE-capable slaves. See
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1479
  section~\ref{sec:eoeimp} for more information.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1480
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1481
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1482
\paragraph{Master Methods (Realtime Interface)}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1483
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1484
The master methods belonging to the Eth\-er\-CAT realtime
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1485
interface\index{ecrt@\textit{ecrt}}\nomenclature{ecrt}{EtherCAT
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1486
  Realtime Interface} begin with the prefix \textit{ecrt} instead of
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1487
\textit{ec}. The functions of the realtime interface are explained in
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1488
section~\ref{sec:ecrt-master}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1489
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1490
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1491
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1492
\subsubsection{The Slave Class}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1493
\label{sec:class-slave}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1494
\index{Slave!Class}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1495
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1496
Figure~\ref{fig:uml-slave} shows an UML class diagram of the slave
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1497
class. There is a short explanation of the attributes and methods
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1498
below.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1499
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1500
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1501
  \centering
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1502
  \includegraphics[width=.8\textwidth]{images/uml-slave}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1503
  \caption{Slave UML class diagram}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1504
  \label{fig:uml-slave}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1505
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1506
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1507
\paragraph{Slave Attributes}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1508
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1509
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1510
\item[list] The master holds a slave list, therefore the slave class
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1511
  must contain this structure used as an anchor for the linked
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1512
  list.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1513
\item[kobj] This pointer serves as base object for the slave's Sysfs
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1514
  representation.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1515
\item[master] is the pointer to the master owning this slave object.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1516
\item[ring\_position] is the logical position in the logical ring
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1517
  topology.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1518
\item[station\_address] is the configured station address. This is
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1519
  always the ring position~+~$1$).
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1520
\item[coupler\_index] is the index of the last bus coupler.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1521
\item[coupler\_subindex] is the slave's position, counted from the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1522
  last bus coupler. See section~\ref{sec:addr} for more information.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1523
\item[base\_*] These attributes contain base information about the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1524
  slave, that are read from the ``DL Information'' attribute.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1525
\item[dl\_*] These fields store information of the ``DL Status''
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1526
  attribute, for example states of the the communication ports.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1527
\item[sii\_*] These attributes contain values from the ``Slave
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1528
  Information Interface'' \cite[section~6.4]{dlspec}, mostly identity
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1529
  and mailbox information, but also the list of sync manager
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  1530
  configurations and Pdos.
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  1531
\item[registered] This flag is set, if one or more Pdos of the slave
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1532
  have been registered for process data exchange. Otherwise a warning
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1533
  is output, because the slave is unused.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1534
\item[fmmus] Is an array of FMMU configurations, that have to be
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1535
  applied to the slave.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1536
\item[fmmu\_count] contains number of FMMUs used.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1537
\item[eeprom\_*] These fields contain E$^2$PROM contents and the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1538
  extracted category information \cite[section~5.4]{alspec}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1539
\item[new\_eeprom\_data] If this pointer is not \textit{NULL}, it
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1540
  points to new E$^2$PROM contents, that have to be written to the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1541
  slave.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1542
\item[new\_eeprom\_size] This field represents the size of the new
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1543
  E$^2$PROM data.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1544
\item[requested\_state] is the requested slave state.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1545
\item[current\_state] is the current slave state.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1546
\item[error\_flag] is used by the operation and idle state machines
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1547
  to indicate, that a state transisition has failed and should not be
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1548
  tried again until an external event happens.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1549
\item[online] This flag contains the online state of the slave (i.~e.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1550
  if it currently responds to the masters commands). Changes of the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1551
  online state are always reported.
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  1552
\item[varsize\_fields] is only suitable for slaves that provide Pdos
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1553
  of variable size (like slaves that manage a sub-fieldbus) and
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1554
  contains information about what size this fields actually should
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1555
  have.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1556
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1557
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1558
\paragraph{Public Slave Methods}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1559
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1560
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1561
\item[ec\_slave\_init()] The slave's constructor.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1562
\item[ec\_slave\_clear()] The slave's destructor.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1563
\item[ec\_prepare\_fmmu()] prepares an FMMU configuration. The FMMU is
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1564
  configured for a certain sync manager and domain.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1565
\item[ec\_fetch\_*()] Serveral methods to extract information of the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1566
  E$^2$PROM category contents.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1567
\item[ec\_slave\_locate\_string()] extracts a string out of a STRING
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1568
  category and allocates string memory.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1569
\item[ec\_slave\_calc\_sync\_size()] calculates the size of sync
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1570
  manager contents, because they can be variable due to variable-sized
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  1571
  Pdos.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1572
\item[ec\_slave\_info()] This method prints all slave information into
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1573
  a buffer for Sysfs reading.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1574
\item[ec\_slave\_mbox\_*()] These functions prepare datagrams for
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1575
  mailbox communication, or process mailbox responses, respectively.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1576
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1577
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1578
\paragraph{Private Slave Methods}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1579
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1580
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1581
\item[ec\_slave\_write\_eeprom()] This function accepts E$^2$PROM data
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1582
  from user space, does a quick validation of the contents and
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1583
  schedules them for writing through the idle state machine.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1584
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1585
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1586
\paragraph{Slave Methods (Realtime Interface)}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1587
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1588
\begin{description}
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  1589
\item[ecrt\_slave\_conf\_sdo*()] These methods accept Sdo
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1590
  configurations, that are applied on slave activation (i.~e.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1591
  everytime the slave is configured). The methods differ only in the
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  1592
  data size of the Sdo (8, 16 or 32 bit).
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1593
\item[ecrt\_slave\_pdo\_size()] This method specifies the size of a
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  1594
  variable-sized Pdo.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1595
\end{description}
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
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1598
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1599
\subsubsection{The Device Class}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1600
\label{sec:class-device}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1601
\index{Device!Class}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1602
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1603
The device class is responsible for communicating with the connected
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1604
EtherCAT-enabled network driver. Figure~\ref{fig:uml-device} shows its
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1605
UML class diagram.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1606
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1607
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1608
  \centering
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1609
  \includegraphics[width=.3\textwidth]{images/uml-device}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1610
  \caption{Device UML class diagram}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1611
  \label{fig:uml-device}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1612
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1613
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1614
\paragraph{Device Attributes}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1615
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1616
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1617
\item[master] A pointer to the master, which owns the device object.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1618
\item[dev] This is the pointer to the \textit{net\_device} structure
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1619
  of the connected network device driver.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1620
\item[open] This flag stores, if the network device is ``opened'' and
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1621
  ready for transmitting and receiving frames.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1622
\item[tx\_skb] The transmittion socket buffer. Instead of allocating a
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1623
  new socket buffer for each frame, the same socket buffer is recycled
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1624
  and used for every frame.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1625
\item[isr] The pointer to the network device's interrupt service
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1626
  routine. \textit{ec\_isr\_t} is a type definition in the device
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1627
  interface, which looks like below:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1628
  \begin{lstlisting}[gobble=4,language=C]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1629
    typedef irqreturn_t (*ec_isr_t)(int, void *,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1630
                                    struct pt_regs *);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1631
  \end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1632
\item[module] A pointer to the network driver module, to increase and
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1633
  decrease the use counter (see paragraph ``Implicit Dependencies'' in
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1634
  section~\ref{sec:ecdev}).
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1635
\item[link\_state] The current link state. It can be 0 ``down'' or 1
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1636
  ``up''.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1637
\item[dbg] Every device objects contains a debugging interface (see
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1638
  sectios~\ref{sec:class-debug} and~\ref{sec:debug}).
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1639
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1640
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1641
\paragraph{Public Device Methods}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1642
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1643
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1644
\item[ec\_device\_init()] The device constructor.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1645
\item[ec\_device\_clear()] The device destructor.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1646
\item[ec\_device\_open()] ``Opens'' the device for transmittion and
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1647
  reception of frames. This is equivalent to the \textit{ifconfig up}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1648
  command for ordinary Ethernet devices.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1649
\item[ec\_device\_close()] Stops frame transmittion and reception.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1650
  This is equivalent to the \textit{ifconfig down} command for
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1651
  ordinary Ethernet devices.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1652
\item[ec\_device\_call\_isr()] Calls the interrupt service routine of
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1653
  the device.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1654
\item[ec\_device\_tx\_data()] Returns a pointer into the memory of the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1655
  transmittion socket buffer \textit{tx\_skb}. This is used by the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1656
  master to assemble a new EtherCAT frame.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1657
\item[ec\_device\_send()] Sends an assembled frame by passing it to
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1658
  the device's \textit{hard\_\-start\_\-xmit()} callback.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1659
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1660
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1661
\paragraph{Device Methods (Device Interface)}
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
The device methods belonging to the device interface are explained in
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1664
section~\ref{sec:ecdev}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1665
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1666
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1667
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1668
\subsubsection{The Datagram Class}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1669
\label{sec:class-datagram}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1670
\index{Datagram!Class}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1671
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1672
So send and receive a datagram, an object of the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1673
\textit{ec\_datagram\_t} class is needed. It can be initialized with a
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1674
datagram type \cite[section~5.4]{dlspec} and length (optionally filled
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1675
with data) and appended to the master's datagram queue.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1676
Figure~\ref{fig:uml-datagram} shows its UML class diagram.
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
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1679
  \centering
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1680
  \includegraphics[width=.3\textwidth]{images/uml-datagram}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1681
  \caption{Datagram UML class diagram}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1682
  \label{fig:uml-datagram}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1683
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1684
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1685
\paragraph{Datagram Attributes}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1686
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1687
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1688
\item[list] This attribute is needed to make a list of datagrams, as
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1689
  used in the domain class (see section~\ref{sec:class-domain}).
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1690
\item[queue] This attribute is the anchor to the master's datagram
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1691
  queue, which is implemented as a linked list.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1692
\item[type] The datagram type. \textit{ec\_\-datagram\_\-type\_\-t} is
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1693
  an enumeration, which can have the values
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1694
  \textit{EC\_\-DATAGRAM\_\-APRD}, \textit{EC\_\-DATAGRAM\_\-APWR},
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1695
  \textit{EC\_\-DATAGRAM\_\-NPRD}, \textit{EC\_\-DATAGRAM\_\-NPWR},
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1696
  \textit{EC\_\-DATAGRAM\_\-BRD}, \textit{EC\_\-DATAGRAM\_\-BWR} or
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1697
  \textit{EC\_\-DATAGRAM\_\-LRW}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1698
\item[address] The slave address. For all addressing schemes take 4
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1699
  bytes, \textit{ec\_address\_t} is a union type:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1700
  \begin{lstlisting}[gobble=4,language=C]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1701
    typedef union {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1702
            struct {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1703
                    uint16_t slave; /**< configured or
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1704
                                         autoincrement
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1705
                                         address */
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1706
                    uint16_t mem; /**< physical memory
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1707
                                       address */
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1708
            } physical; /**< physical address */
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1709
            uint32_t logical; /**< logical address */
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1710
    } ec_address_t;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1711
  \end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1712
\item[data] The actual data of the datagram. These are either filled
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1713
  in before sending (at writing access) or are inserted by the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1714
  adressed slave(s) (at reading access). In any case, the data memory
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1715
  must be dynamically allocated. Besides, this can be done before
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1716
  cyclic processing with the \textit{ec\_datagram\_prealloc()} method
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1717
  (see below).
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1718
\item[mem\_size] The size of the allocated memory, \textit{data}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1719
  points to.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1720
\item[data\_size] The size of the actual data in the \textit{data}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1721
  memory.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1722
\item[index] The sequential EtherCAT datagram index. This value is set
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1723
  by the master on sending, to easier assign a received datagram to a
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1724
  queued datagram object.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1725
\item[working\_counter] The working counter of the datagram. This is
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1726
  set to zero on sending and filled with the real value of the working
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1727
  counter on datagram reception.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1728
\item[state] The state of the datagram.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1729
  \textit{ec\_\-datagram\_\-state\_\-t} is an enumeration and can be
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1730
  \textit{EC\_\-DATA\-GRAM\_\-INIT},
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1731
  \textit{EC\_\-DATA\-GRAM\_\-QUEU\-ED},
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1732
  \textit{EC\_\-DATA\-GR\-AM\_\-SEN\-T},
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1733
  \textit{EC\_\-DATA\-GRAM\_\-REC\-EIVED},
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1734
  \textit{EC\_\-DATA\-GRAM\_\-TIMED\_\-OUT} or
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1735
  \textit{EC\_\-DA\-TA\-GRAM\_\-ERR\-OR}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1736
\item[t\_sent] This attribute is set to the timestamp, when the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1737
  datagram was sent, to later detect a timeout.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1738
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1739
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1740
\paragraph{Public Datagram Methods}
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
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1743
\item[ec\_datagram\_init()] The datagram's constructor.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1744
\item[ec\_datagram\_clear()] The datagram's destructor.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1745
\item[ec\_datagram\_prealloc()] Allocates memory for the datagram
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1746
  data. This is especially needed, if the datagram structure will
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1747
  later be used in a context, where no dynamic memory allocation is
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1748
  allowed.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1749
\item[ec\_datagram\_nprd()] Initializes a ``Node-Addressed Physical
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1750
  Read'' datagram \cite[section~5.4.1.2]{dlspec}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1751
\item[ec\_datagram\_npwr()] Initializes a ``Node-Addressed Physical
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1752
  Write'' datagram \cite[section~5.4.2.2]{dlspec}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1753
\item[ec\_datagram\_aprd()] Initializes a ``Auto-Increment Physical
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1754
  Read'' datagram \cite[section~5.4.1.1]{dlspec}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1755
\item[ec\_datagram\_apwr()] Initializes a ``Auto-Increment Physical
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1756
  Write'' datagram \cite[section~5.4.2.1]{dlspec}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1757
\item[ec\_datagram\_brd()] Initializes a ``Broadcast Read'' datagram
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1758
  \cite[section~5.4.1.3]{dlspec}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1759
\item[ec\_datagram\_bwr()] Initializes a ``Broadcast Write'' datagram
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1760
  \cite[section~5.4.2.3]{dlspec}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1761
\item[ec\_datagram\_lrw()] Initializes a ``Logical ReadWrite''
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1762
  datagram \cite[section~5.4.3.4]{dlspec}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1763
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1764
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1765
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1766
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1767
\subsubsection{The Domain Class}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1768
\label{sec:class-domain}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1769
\index{Domain!Class}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1770
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  1771
The domain class encapsules Pdo registration and management of the
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1772
process data image and its exchange. The UML class diagram can be seen
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1773
in figure~\ref{fig:uml-domain}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1774
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1775
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1776
  \centering
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1777
  \includegraphics[width=.4\textwidth]{images/uml-domain}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1778
  \caption{Domain UML class diagram}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1779
  \label{fig:uml-domain}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1780
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1781
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1782
\paragraph{Domain Attributes}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1783
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1784
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1785
\item[kobj] This \textit{kobject} structure is needed for the Sysfs
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1786
  representation of the domain.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1787
\item[list] The master manages a list of domains, so this list anchor
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1788
  is needed.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1789
\item[index] The domain's index. The first domain will get index 0,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1790
  the second index 1, and so on.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1791
\item[master] A pointer to the master owning the domain.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1792
\item[data\_size] The size of the domain's process data image.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1793
\item[datagram] A linked list with the datagram objects, the domain
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1794
  needs for process data exchange (see
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1795
  section~\ref{sec:class-datagram}).
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1796
\item[base\_address] This attribute stores the logical offset, to
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1797
  which the domain's process data are mapped.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1798
\item[response\_count] The sum of the datagrams' working counters at
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1799
  the last process data exchange. Changes are always reported.
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  1800
\item[data\_regs] The (linked) list of Pdo registrations. The realtime
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  1801
  module requests the exchange of certain Pdos and supplies the
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1802
  address of process data pointers, that will later point to the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1803
  respective locations in the process data image. These ``data
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1804
  registrations'' are saved in the \textit{data\_regs} list.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1805
\item[working\_counter\_changes] This field stores the number of
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1806
  working counter changes since the last notification. This helps to
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1807
  reduce syslog output in case of frequent changes.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1808
\item[t\_last] The timestamp of the last working counter change
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1809
  notification.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1810
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1811
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1812
\paragraph{Public Domain Methods}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1813
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1814
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1815
\item[ec\_domain\_init()] The domain's constructor.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1816
\item[ec\_domain\_clear()] The domain's destructor.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1817
\item[ec\_domain\_alloc()] Allocates the process data image and the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1818
  respective datagrams based on the process data registrations.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1819
\item[ec\_domain\_queue()] Queues the domain's datagrams for exchange
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1820
  via the master.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1821
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1822
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1823
\paragraph{Private Domain Methods}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1824
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1825
\begin{description}
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  1826
\item[ec\_domain\_reg\_pdo\_entry()] This method is used to do a Pdo
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  1827
  registration. It finds the appropriate sync manager covering the Pdo
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1828
  data, calculates its offset in the sync-manager-protected memory and
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  1829
  prepares the FMMU configurations for the related slave. Then the Pdo
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1830
  registration is appended to the list.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1831
\item[ec\_domain\_clear\_data\_regs()] Clearing all process data
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1832
  registrations is needed in serveral places and therefore has been
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1833
  sourced out to an own method.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1834
\item[ec\_domain\_add\_datagram()] This methods allocates a datagram
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1835
  and appends it to the list. This is done during domain allocation.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1836
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1837
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1838
\paragraph{Domain Methods (Realtime Interface)}
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
The domain methods belonging to the realtime interface are introduced
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1841
in section~\ref{sec:ecrt-domain}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1842
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
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1845
\subsubsection{The Finite State Machine Class}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1846
\label{sec:class-fsm}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1847
\index{FSM!Class}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1848
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1849
This class encapsules all state machines, except the EoE state
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1850
machine. Its UML class diagram can be seen in
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1851
figure~\ref{fig:uml-fsm}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1852
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1853
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1854
  \centering
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1855
  \includegraphics[width=.9\textwidth]{images/uml-fsm}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1856
  \caption{Finite State Machine UML class diagram}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1857
  \label{fig:uml-fsm}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1858
\end{figure}
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
\paragraph{FSM Attributes}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1861
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1862
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1863
\item[master] A pointer to the master owning the FSM object.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1864
\item[slave] Serveral sub state machines are executed for single
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1865
  slaves. This pointer stores the current slave for these FSMs.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1866
\item[datagram] The FSM class has its own datagram, which is used in
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1867
  every state and sub-state.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1868
\item[master\_state] This function pointer stores the current state
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1869
  function for one of the master's state machines.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1870
\item[master\_slaves\_responding] This attribute is used in the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1871
  operation state machine (see section~\ref{sec:fsm-op}) to store the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1872
  number of slaves, that responded to the last broadcast command.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1873
\item[master\_slave\_states] This attribute stores the slave states,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1874
  that were determined by the last broadcast command.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1875
\item[master\_validation] This flag is used by the operation state
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1876
  machine and is non-zero, if a bus validation has to be done.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1877
\item[slave\_state] This function pointer stores the current state of
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1878
  the slave scan state machine (see section~\ref{sec:fsm-scan}) or the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1879
  slave configuration state machine (see section~\ref{sec:fsm-conf}).
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1880
\item[sii\_state] This function pointer stores the current state of
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1881
  the SII state machine (see section~\ref{sec:fsm-sii}).
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1882
\item[sii\_offset] This attribute is used by the SII state machine to
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1883
  store the word address for the current read or write cycle.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1884
\item[sii\_mode] If this attribute is zero, the SII access is done
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1885
  with ``auto-increment'' datagrams \cite[section~5.4]{dlspec}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1886
  If it is non-zero, ``station-address'' datagrams are used.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1887
\item[sii\_value] This attribute stores the value to write, or the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1888
  read value, respectively.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1889
\item[sii\_start] A timestamp attribute, that stores the beginning
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1890
  time of an SII operation to detect a timeout.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1891
\item[change\_state] This function pointer stores the current state of
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1892
  the state change state machine.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1893
\item[change\_new] This attribute stores the requested state for the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1894
  state change state machine.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1895
\item[change\_start] A timestamp attribute to detect a timeout while
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1896
  changing slave states.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1897
\item[coe\_state] This function pointer stores the current state of
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1898
  the CoE state machines.
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  1899
\item[sdodata] This is an Sdo data object that stores information
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  1900
  about the current Sdo to write.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1901
\item[coe\_start] A timestamp attribute to detect timeouts during CoE
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1902
  configuration.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1903
\end{description}
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
\paragraph{Public FSM Methods}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1906
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1907
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1908
\item[ec\_fsm\_init()] Constructor of the FSM class.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1909
\item[ec\_fsm\_clear()] Destructor of the FSM class.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1910
\item[ec\_fsm\_reset()] Resets the whole FSM object. This is needed to
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1911
  restart the master state machines.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1912
\item[ec\_fsm\_execute()] Executes one state of the current state
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1913
  machine and then returns.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1914
\item[ec\_fsm\_startup()] Initializes the master startup state
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1915
  machine, which determines the number of slaves and executes the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1916
  slave scan state machine for each slave.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1917
\item[ec\_fsm\_startup\_running()] Returns non-zero, if the startup
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1918
  state machine did not terminate yet.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1919
\item[ec\_fsm\_startup\_success()] Returns non-zero, if the startup
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1920
  state machine terminated with success.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1921
\item[ec\_fsm\_configuration()] Initializes the master configuration
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1922
  state machine, which executes the slave configuration state machine
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1923
  for each slave.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1924
\item[ec\_fsm\_configuration\_running()] Returns non-zero, if the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1925
  configuration state machine did not terminate yet.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1926
\item[ec\_fsm\_configuration\_success()] Returns non-zero, if the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1927
  configuration state machine terminated with success.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1928
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1929
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1930
\paragraph{FSM State Methods}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1931
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1932
The rest of the methods showed in the UML class diagram are state
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1933
methods of the state machines. These states are described in
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1934
section~\ref{sec:fsm}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1935
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1936
%------------------------------------------------------------------------------
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
\subsubsection{The EoE Class}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1939
\label{sec:class-eoe}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1940
\index{EoE!Class}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1941
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1942
Objects of the \textit{ec\_eoe\_t} class are called EoE handlers. Each
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1943
EoE handler represents a virtual network interface and can be coupled
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1944
to a EoE-capable slave on demand. The UML class diagram can be seen in
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1945
figure~\ref{fig:uml-eoe}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1946
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1947
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1948
  \centering
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1949
  \includegraphics[width=.4\textwidth]{images/uml-eoe}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1950
  \caption{EoE UML class diagram}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1951
  \label{fig:uml-eoe}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1952
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1953
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1954
\paragraph{EoE Attributes}
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
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1957
\item[list] The master class maintains a list of EoE handlers.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1958
  Therefore this list anchor is needed.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1959
\item[slave] If an EoE handler is coupled to a slave, this pointer
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1960
  points to the related slave object. Otherwise it is \textit{NULL}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1961
\item[datagram] Every EoE handler owns a datagram object to exchange
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1962
  data with the coupled slave via its state machine.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1963
\item[state] This function pointer points to the current state of the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1964
  EoE state machine (see section~\ref{sec:eoeimp}).
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1965
\item[dev] A pointer to the \textit{net\_device} structure that
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1966
  represents the network interface to the kernel.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1967
\item[stats] The statistics object for the network interface.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1968
\item[opened] This flag stores, if the network interface was opened.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1969
  No EoE processing will be done, if the device is not opened.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1970
\item[t\_last] This timestamp attribute stores the time of the last
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1971
  bit rate measurement.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1972
\item[rx\_skb] A pointer to the current receive socket buffer. On
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1973
  every first fragment of a received frame, a new receive socket
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1974
  buffer is allocated. On every last fragment, this buffer will be
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1975
  passed to the network stack.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1976
\item[rx\_skb\_offset] This attribute stores the offset for the next
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1977
  fragment data in the receive socket buffer.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1978
\item[rx\_skb\_size] This attribute stores the current data size of
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1979
  the receive socket buffer.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1980
\item[rx\_expected\_fragment] The expected number of the next
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1981
  fragment. If a fragment with an invalid number is received, the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1982
  whole frame will be dropped.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1983
\item[rx\_counter] This is the sum of the octets received since the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1984
  last bit rate measurement.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1985
\item[rx\_rate] This attribute stores the receive bit rate in bps.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1986
\item[tx\_queue] Each EoE handler maintains a transmittion queue for
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1987
  frames, that come in via the network interface. This queue is
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1988
  implemented with a linked list and protected by a spinlock.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1989
\item[tx\_queue\_active] This flag stores, if the transmittion queue
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1990
  is currently accepting frames from the network stack. If the queue
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1991
  gets filled up, frame transmittion is suspended with a call to
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1992
  \textit{netif\_stop\_queue()}. If the fill state decreases below the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1993
  half capacity, frame transmittion is restarted with
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1994
  \textit{netif\_wake\_queue()}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1995
\item[tx\_queued\_frames] The number of frames in the transmittion
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1996
  queue.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1997
\item[tx\_queue\_lock] The spinlock used to protect the transmittion
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1998
  queue. This is needed, because the queue is accessed both from
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1999
  network stack context and from the master's EoE timer.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2000
\item[tx\_frame] The frame that is currently sent. The
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2001
  \textit{ec\_eoe\_frame\_t} structure combines the socket buffer
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2002
  structure with a list head to append it to the transmittion queue.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2003
\item[tx\_frame\_number] The EoE protocol demands to maintain a
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2004
  sequencial frame number, that must be increased with every frame
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2005
  sent.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2006
\item[tx\_fragment\_number] The sequencial number of the next fragment
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2007
  to transmit.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2008
\item[tx\_offset] Current frame data offset for the next fragment to
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2009
  transmit.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2010
\item[tx\_counter] The number of octets transferred since the last bit
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2011
  rate measurement.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2012
\item[tx\_rate] The recent transmittion bit rate in bps.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2013
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2014
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2015
\paragraph{Public EoE Methods}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2016
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2017
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2018
\item[ec\_eoe\_init()] The EoE handler's constructor. The network
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2019
  interface is allocated and registered.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2020
\item[ec\_eoe\_clear()] The EoE handler's destructor. The network
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2021
  interface is unregistered and all allocated memory is freed.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2022
\item[ec\_eoe\_run()] Executes the EoE state machine (see
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2023
  section~\ref{sec:eoeimp}) for this handler.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2024
\item[ec\_eoe\_active()] Returns true, if the handler has a slave
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2025
  coupled and the network interface is opened.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2026
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2027
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2028
\paragraph{Private EoE Methods}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2029
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2030
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2031
\item[ec\_eoe\_flush()] Clears the transmittion queue and drops all
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2032
  frames queued for sending.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2033
\item[ec\_eoe\_send()] Sends one fragment of the current frame.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2034
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2035
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2036
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2037
\paragraph{EoE State Methods}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2038
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2039
The rest of the private methods are state functions for the EoE state
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2040
machine, which is discussed in section~\ref{sec:eoeimp}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2041
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2042
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2043
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2044
\subsubsection{The Debug Class}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2045
\label{sec:class-debug}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2046
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2047
The debug class maintains a virtual network interface. All frames that
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2048
are sent and received by the master will be forwarded to this network
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2049
interface, so that bus monitoring can be done with third party tools
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2050
(see section~\ref{sec:debug}). Figure~\ref{fig:uml-debug} shows the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2051
UML class diagram.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2052
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2053
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2054
  \centering
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2055
  \includegraphics[width=.3\textwidth]{images/uml-debug}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2056
  \caption{Debug UML class diagram}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2057
  \label{fig:uml-debug}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2058
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2059
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2060
\paragraph{Debug Attributes}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2061
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2062
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2063
\item[dev] A pointer to the allocated \textit{net\_device} structure
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2064
  that represents the network interface in the kernel.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2065
\item[stats] An object for interface statistics.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2066
\item[opened] Stores the state of the device. Frames will only be
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2067
  forwarded, if the device was opened with the \textit{ifconfig up}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2068
  command (or something similar).
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2069
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2070
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2071
\paragraph{Public Debug Methods}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2072
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2073
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2074
\item[ec\_debug\_init()] The constructor.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2075
\item[ec\_debug\_clear()] The destructor.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2076
\item[ec\_debug\_send()] This method forwards a frame to the virtual
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2077
  network interface. It dynamically allocates a new socket buffer and
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2078
  passes it to the network stack.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2079
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2080
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2081
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2082
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2083
\subsection{The Realtime Interface}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2084
\label{sec:ecrt}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2085
\index{Realtime interface}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2086
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2087
The realtime interface provides functions and data structures for
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2088
realtime modules to access and use an EtherCAT master.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2089
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2090
\subsubsection{Master Requesting and Releasing}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2091
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2092
Before a realtime module can access am EtherCAT master provided by the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2093
master module, it has to reserve one for exclusive use. After use, it
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2094
has to release the requested master and make it available for other
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2095
modules. This is done with the following functions:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2096
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2097
\begin{lstlisting}[language=C]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2098
  ec_master_t *ecrt_request_master(unsigned int master_index);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2099
  void ecrt_release_master(ec_master_t *master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2100
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2101
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2102
The \textit{ecrt\_request\_master()} function has to be the first
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2103
function a module has to call, when using EtherCAT. The function takes
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2104
the index of the master as its argument. The first master has index 0,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2105
the $n$th master has index $n - 1$. The number of existent masters has
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2106
to be specified when loading the master module (see
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2107
section~\ref{sec:mastermod}). The function tries to reserve the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2108
specified master and scans for slaves. It returns a pointer to the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2109
reserved master object upon success, or \textit{NULL} if an error
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2110
occured.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2111
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2112
The \textit{ecrt\_release\_master()} function releases a reserved
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2113
master after use. It takes the pointer to the master object returned
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2114
by \textit{ecrt\_request\_master()} as its argument and can never
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2115
fail.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2116
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2117
\subsubsection{Master Methods}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2118
\label{sec:ecrt-master}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2119
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2120
\paragraph{Domain Creation}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2121
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2122
For process data exchange, at least one process data domain is needed
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2123
(see section~\ref{sec:processdata}).
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2124
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2125
\begin{lstlisting}[language=C]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2126
  ec_domain_t *ecrt_master_create_domain(ec_master_t *master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2127
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2128
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2129
The \textit{ecrt\_master\_create\_domain()} method creates a new
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2130
process data domain and returns a pointer to the new domain object.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2131
This object can be used for registering process data objects and
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2132
exchange process data in cyclic operation. On failure, the function
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2133
returns \textit{NULL}.
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
\paragraph{Slave Handlers}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2136
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2137
To access a certain slave, there is a method to get a slave handler:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2138
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2139
\begin{lstlisting}[language=C]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2140
  ec_slave_t *ecrt_master_get_slave(const ec_master_t *,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2141
                                    const char *);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2142
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2143
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2144
The \textit{ecrt\_master\_get\_slave()} method returns a pointer to a
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2145
certain slave object, specified by its ASCII address (see
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2146
section~\ref{sec:addr}). If the address is invalid, \textit{NULL} is
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2147
returned.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2148
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2149
\paragraph{Master Activation}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2150
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2151
When all domains are created, and all process data objects are
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2152
registered, the master can be activated:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2153
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2154
\begin{lstlisting}[language=C]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2155
  int ecrt_master_activate(ec_master_t *master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2156
  void ecrt_master_deactivate(ec_master_t *master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2157
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2158
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2159
By calling the \textit{ecrt\_master\_activate()} method, all slaves
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2160
are configured according to the prior method calls and are brought
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2161
into OP state. In this case, the method has a return value of 0.
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2162
Otherwise (wrong configuration or bus failure) the method returns
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2163
non-zero.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2164
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2165
The \textit{ecrt\_master\_deactivate()} method is the counterpart to
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2166
the activate call: It brings all slaves back into INIT state again.
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2167
This method should be called prior to
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2168
\textit{ecrt\_\-master\_\-release()}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2169
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2170
\paragraph{Locking Callbacks}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2171
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2172
For concurrent master access, the realtime module has to provide a
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2173
locking mechanism (see section~\ref{sec:concurr}):
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2174
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2175
\begin{lstlisting}[language=C]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2176
  void ecrt_master_callbacks(ec_master_t *master,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2177
                             int (*request_cb)(void *),
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2178
                             void (*release_cb)(void *),
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2179
                             void *cb_data);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2180
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2181
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2182
The ``request lock'' and ``release lock'' callbacks can be set with
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2183
the \textit{ecrt\_master\_call\-backs()} method. It takes two function
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2184
pointers and a data value as additional arguments. The arbitrary data
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2185
value will be passed as argument on every callback. Asynchronous
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2186
master access (like EoE processing) is only possible if these
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2187
callbacks have been set.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2188
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2189
\paragraph{Preparation of Cyclic Data Exchange}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2190
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2191
Cyclic operation mostly consists of the three steps input, processing
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2192
and output. In EtherCAT terms this would mean: Receive datagrams,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2193
evaluate process data and send datagrams. The first cycle differs from
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2194
this principle, because no datagrams have been sent yet, so there is
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2195
nothing to receive. To avoid having a case differantiation (in terms
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2196
of an \textit{if} clause), the following method exists:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2197
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2198
\begin{lstlisting}[language=C]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2199
  void ecrt_master_prepare(ec_master_t *master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2200
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2201
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2202
As a last thing before cyclic operation, a call to the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2203
\textit{ecrt\_master\_prepare()} method should be issued. It makes all
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2204
process data domains queue their datagrams and issues a send command,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2205
so that the first receive call in cyclic operation will not fail.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2206
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2207
\paragraph{Frame Sending and Receiving}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2208
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2209
To send all queued datagrams and to later receive the sent datagrams
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2210
there are two methods:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2211
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2212
\begin{lstlisting}[language=C]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2213
  void ecrt_master_send(ec_master_t *master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2214
  void ecrt_master_receive(ec_master_t *master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2215
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2216
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2217
The \textit{ecrt\_master\_send()} method takes all datagrams, that
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2218
have been queued for transmission, packs them into frames, and passes
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2219
them to the network device for sending.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2220
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2221
The \textit{ecrt\_master\_receive()} queries the network device for
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2222
received frames (by calling the ISR\index{ISR}), extracts received
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2223
datagrams and dispatches the results to the datagram objects in the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2224
queue. Received datagrams, and the ones that timed out, will be
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2225
marked, and then dequeued.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2226
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2227
\paragraph{Running the Operation State Machine}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2228
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2229
The master's operation state machine (see section~\ref{sec:fsm-op})
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2230
monitors the bus in cyclic operation and reconfigures slaves, if
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2231
necessary. Therefore, the following method should be called
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2232
cyclically:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2233
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2234
\begin{lstlisting}[language=C]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2235
  void ecrt_master_run(ec_master_t *master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2236
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2237
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2238
The \textit{ecrt\_master\_run()} method executes the master's
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2239
operation state machine step by step. It returns after processing one
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2240
state and queuing a datagram. Calling this function is not mandatory,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2241
but highly recommended.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2242
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2243
\paragraph{Master Monitoring}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2244
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2245
It is also highly recommended to evaluate the master's error state. In
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2246
this way it is possible to notice lost network links, failed bus
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2247
segments, and other issues:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2248
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2249
\begin{lstlisting}[language=C]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2250
  int ecrt_master_state(const ec_master_t *master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2251
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2252
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2253
The \textit{ecrt\_master\_state()} method returns the master's error
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2254
state. The following states are defined as part of the realtime
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2255
interface:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2256
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2257
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2258
\item[EC\_MASTER\_OK] means, that no error has occurred.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2259
\item[EC\_MASTER\_LINK\_ERROR] means, that the network link is
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2260
  currently down.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2261
\item[EC\_MASTER\_BUS\_ERROR] means, that one or more slaves do not
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2262
  respond.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2263
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2264
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2265
\subsubsection{Domain Methods}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2266
\label{sec:ecrt-domain}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2267
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  2268
\paragraph{Pdo Registration}
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  2269
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  2270
To access data of a slave's Pdo in cyclic operation, it is necessary
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2271
to make it part of a process data domain:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2272
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2273
\begin{lstlisting}[language=C]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2274
  ec_slave_t *ecrt_domain_register_pdo(ec_domain_t *domain,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2275
                                       const char *address,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2276
                                       uint32_t vendor_id,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2277
                                       uint32_t product_code,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2278
                                       const char *pdo_name
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2279
                                       void **data_ptr);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2280
  int ecrt_domain_register_pdo_list(ec_domain_t *domain,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2281
                                    const ec_pdo_reg_t *pdos);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2282
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2283
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2284
The \textit{ecrt\_domain\_register\_pdo()} method registers a certain
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  2285
Pdo as part of the domain and takes the address of the process data
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2286
pointer. This pointer will be set on master activation and then can be
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2287
parameter to the \textit{EC\_READ\_*} and \textit{EC\_WRITE\_*} macros
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2288
described below.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2289
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  2290
A perhaps easier way to register multiple Pdos at the same time is to
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2291
fill an array of \textit{ec\_pdo\_reg\_t} and hand it to the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2292
\textit{ecrt\_domain\_register\_pdo\_list()} method. Attention: This
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2293
array has to be terminated by an empty structure (\textit{\{\}})!
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2294
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2295
\paragraph{Evaluating Domain Data}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2296
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2297
To evaluate domain data, the following method has to be used:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2298
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2299
\begin{lstlisting}[language=C]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2300
  void ecrt_domain_process(ec_domain_t *domain);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2301
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2302
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2303
The \textit{ecrt\_domain\_process()} method sets the domains state and
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2304
requeues its datagram for sending.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2305
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2306
\paragraph{Domain State}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2307
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2308
Similar to the master state, a domain has an own error state:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2309
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2310
\begin{lstlisting}[language=C]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2311
  int ecrt_domain_state(const ec_domain_t *domain);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2312
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2313
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2314
The \textit{ecrt\_domain\_state()} method returns the domain's error
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2315
state. It is non-zero if \underline{not} all process data values could
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2316
be exchanged, and zero otherwise.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2317
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2318
\subsubsection{Slave Methods}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2319
\label{sec:ecrt-slave}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2320
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  2321
\paragraph{Sdo Configuration}
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  2322
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  2323
To configure slave Sdos, the function interface below can be used:
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2324
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2325
\begin{lstlisting}[language=C]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2326
  int ecrt_slave_conf_sdo8(ec_slave_t *slave,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2327
                           uint16_t sdo_index,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2328
                           uint8_t sdo_subindex,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2329
                           uint8_t value);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2330
  int ecrt_slave_conf_sdo16(ec_slave_t *slave,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2331
                            uint16_t sdo_index,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2332
                            uint8_t sdo_subindex,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2333
                            uint16_t value);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2334
  int ecrt_slave_conf_sdo32(ec_slave_t *slave,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2335
                            uint16_t sdo_index,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2336
                            uint8_t sdo_subindex,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2337
                            uint32_t value);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2338
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2339
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2340
The \textit{ecrt\_slave\_conf\_sdo*()} methods prepare the
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  2341
configuration of a certain Sdo. The index and subindex of the Sdo, and
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2342
the value have to be specified. The configuration is done each time,
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  2343
the slave is reconfigured. The methods only differ in the Sdo's data
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2344
type. If the configuration could be prepared, zero is returned. If an
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2345
error occured, non-zero is returned.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2346
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  2347
\paragraph{Variable-sized Pdos}
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  2348
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  2349
For specifying the size of variable-sized Pdos, the following method
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2350
can be used:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2351
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2352
\begin{lstlisting}[language=C]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2353
  int ecrt_slave_pdo_size(ec_slave_t *slave,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2354
                          const char *pdo_name,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2355
                          size_t size);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2356
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2357
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  2358
The \textit{ecrt\_slave\_pdo\_size()} method takes the name of the Pdo
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2359
and the size. It returns zero on success, otherwise non-zero.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2360
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2361
\subsubsection{Process Data Access}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2362
\label{sec:macros}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2363
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2364
The endianess of the process data could differ from that of the CPU.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2365
Therefore, process data access has to be done by the macros below,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2366
that are also provided by the realtime interface:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2367
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2368
\begin{lstlisting}[language=C]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2369
  #define EC_READ_BIT(DATA, POS)
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2370
  #define EC_WRITE_BIT(DATA, POS, VAL)
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2371
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2372
  #define EC_READ_U8(DATA)
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2373
  #define EC_READ_S8(DATA)
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2374
  #define EC_READ_U16(DATA)
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2375
  #define EC_READ_S16(DATA)
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2376
  #define EC_READ_U32(DATA)
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2377
  #define EC_READ_S32(DATA)
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2378
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2379
  #define EC_WRITE_U8(DATA, VAL)
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2380
  #define EC_WRITE_S8(DATA, VAL)
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2381
  #define EC_WRITE_U16(DATA, VAL)
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2382
  #define EC_WRITE_S16(DATA, VAL)
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2383
  #define EC_WRITE_U32(DATA, VAL)
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2384
  #define EC_WRITE_S32(DATA, VAL)
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2385
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2386
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2387
There are macros for bitwise access (\textit{EC\_READ\_BIT()},
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2388
\textit{EC\_WRITE\_BIT()}), and bytewise access
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2389
(\textit{EC\_READ\_*()}, \textit{EC\_WRITE\_*()}). The bytewise macros
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2390
carry the data type in their name. Example: \textit{EC\_WRITE\_S16()}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2391
writes a 16 bit signed value to EtherCAT data. The \textit{DATA}
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  2392
parameter is supposed to be a process data pointer, as provided at Pdo
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2393
registration.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2394
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2395
The macros use the kernel's endianess conversion macros, that are
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2396
preprocessed to empty macros in case of equal endianess. This is the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2397
definition for the \textit{EC\_\-READ\_\-U16()} macro:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2398
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2399
\begin{lstlisting}[language=C]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2400
  #define EC_READ_U16(DATA) \
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2401
          ((uint16_t) le16_to_cpup((void *) (DATA)))
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2402
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2403
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2404
The \textit{le16\_to\_cpup()} macro converts a little-endian, 16 bit
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2405
value to the CPU's architecture and takes a pointer to the input value
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2406
as its argument. If the CPU's architecture is little-endian, too (for
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2407
example on X86 and compatible), nothing has to be converted. In this
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2408
case, the macro is replaced with an empty macro by the preprocessor
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2409
and so there is no unneeded function call or case differentiation in
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2410
the code.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2411
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2412
For keeping it portable, it is highly recommended to make use of these
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2413
macros.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2414
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2415
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2416
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2417
\subsection{Slave Addressing}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2418
\label{sec:addr}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2419
\index{Slave!Addressing}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2420
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  2421
The master offers the serveral slave addressing schemes (for Pdo
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2422
registration or configuration) via the realtime interface. For this
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2423
reason, slave addresses are ASCII\nomenclature{ASCII}{American
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2424
  Standard Code for Information Interchange}-coded and passed as a
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2425
string. The addressing schemes are independent of the EtherCAT
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2426
protocol and represent an additional feature of the master.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2427
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2428
Below, the allowed addressing schemes are described. The descriptions
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2429
are followed by a regular expression formally defining the addressing
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2430
scheme, and one or more examples.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2431
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2432
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2433
\item[Position Addressing] This is the normal addressing scheme, where
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2434
  each slave is addressed by its ring position. The first slave has
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2435
  address 0, and the $n$th slave has address $n - 1$. This addressing
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2436
  scheme is useful for small busses that have a fixed number of slaves.\\
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2437
  RegEx: \texttt{[0-9]+} --- Example: \texttt{"42"}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2438
\item[Advanced Position Addressing] Bus couplers segment the bus into
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2439
  (physical) blocks. Though the logical ring positions keep being the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2440
  same, it is easier to address a slave with its block number and the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2441
  relative position inside the block. This addressing is done by
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2442
  passing the (zero-based) index of the bus coupler (not the coupler's
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2443
  ring position), followed by a colon and the relative position of the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2444
  actual slave starting at the bus coupler.\\
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2445
  RegEx: \texttt{[0-9]+:[0-9]+} --- Examples: \texttt{"0:42"},
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2446
  \texttt{"2:7"}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2447
\item[Alias Addressing] Each slave can have a ``secondary slave
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2448
  address'' or ``alias address''\footnote{Information about how to set
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2449
    the alias can be found in section~\ref{sec:eepromaccess}} stored
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2450
  in its E$^2$PROM.  The alias is evaluated by the master and can be
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2451
  used to address the slave, which is useful when a clearly defined
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2452
  slave has to be addressed and the ring position is not known or can
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2453
  change over time. This scheme is used by starting the address string
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2454
  with a mesh (\#) followed by the alias address.  The latter can also
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2455
  be provided as hexadecimal value, prefixed with \textit{0x}.\\
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2456
  RegEx: \texttt{\#(0x[0-9A-F]+|[0-9]+)} --- Examples:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2457
  \texttt{"\#6622"}, \texttt{"\#0xBEEF"}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2458
\item[Advanced Alias Addressing] This is a mixture of the ``Alias
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2459
  Addressing'' and ``Advanced Position Addressing'' schemes. A certain
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2460
  slave is addressed by specifying its relative position after an
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2461
  aliased slave. This is very useful, if a complete block of slaves
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2462
  can vary its position in the bus. The bus coupler preceeding the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2463
  block should get an alias. The block slaves can then be addressed by
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2464
  specifying this alias and their position inside the block. This
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2465
  scheme is used by starting the address string with a mesh (\#)
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2466
  followed by the alias address (which can be hexadecimal), then a
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2467
  colon and the relative posision of the slave to
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2468
  address.\\
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2469
  RegEx: \texttt{\#(0x[0-9A-F]+|[0-9]+):[0-9]+} --- Examples:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2470
  \texttt{"\#0xBEEF:7"}, \texttt{"\#6:2"}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2471
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2472
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2473
In anticipation of section~\ref{sec:ecrt}, the functions accepting
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2474
these address strings are \textit{ecrt\_\-master\_\-get\_slave()},
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2475
\textit{ecrt\_domain\_register\_pdo()} and
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2476
\textit{ecrt\_domain\_register\_pdo\_list()} (the latter through the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2477
\textit{ec\_pdo\_reg\_t} structure).
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2478
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2479
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2480
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2481
\subsection{Concurrent Master Access}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2482
\label{sec:concurr}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2483
\index{Concurrency}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2484
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2485
In some cases, one master is used by serveral instances, for example
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2486
when a realtime module does cyclic process data exchange, and there
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2487
are EoE-capable slaves that require to exchange Ethernet data with the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2488
kernel (see section~\ref{sec:eoeimp}). For this reason, the master is
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2489
a shared resource, and access to it has to be sequenctialized. This is
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2490
usually done by locking with semaphores, or other methods to protect
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2491
critical sections.
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
The master itself can not provide locking mechanisms, because it has
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2494
no chance to know the appropriate kind of lock. Imagine, the realtime
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2495
module uses RTAI functionality, then ordinary kernel semaphores would
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2496
not be sufficient. For that, an important design decision was made:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2497
The realtime module that reserved a master must have the total
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2498
control, therefore it has to take responsibility for providing the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2499
appropriate locking mechanisms. If another instance wants to access
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2500
the master, it has to request the master lock by callbacks, that have
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2501
to be set by the realtime module. Moreover the realtime module can
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2502
deny access to the master if it consideres it to be awkward at the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2503
moment.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2504
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2505
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2506
  \centering
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2507
  \includegraphics[width=.6\textwidth]{images/master-locks}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2508
  \caption{Concurrent master access}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2509
  \label{fig:locks}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2510
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2511
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2512
Figure~\ref{fig:locks} exemplary shows, how two processes share one
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2513
master: The realtime module's cyclic thread uses the master for
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2514
process data exchange, while the master-internal EoE process uses it
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2515
to communicate with EoE-capable slaves. Both have to aquire the master
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2516
lock before access: The realtime thread can access the lock natively,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2517
while the EoE process has to use the master callbacks.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2518
Section~\ref{sec:concurrency} gives an example, of how to implement
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2519
this.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2520
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2521
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2522
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2523
\section{The Master's State Machines}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2524
\label{sec:fsm}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2525
\index{FSM}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2526
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2527
Many parts of the EtherCAT master are implemented as \textit{finite
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2528
  state machines} (FSMs\nomenclature{FSM}{Finite State Machine}).
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2529
Though this leads to a higher grade of complexity in some aspects, is
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2530
opens many new possibilities.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2531
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2532
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
  2533
states and moreover illustrates the restrictions of ``sequential''
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2534
coding:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2535
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2536
\begin{lstlisting}[language=C,numbers=left]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2537
  ec_datagram_brd(datagram, 0x0130, 2); // prepare datagram
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2538
  if (ec_master_simple_io(master, datagram)) return -1;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2539
  slave_states = EC_READ_U8(datagram->data); // process datagram
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2540
\end{lstlisting}
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
The \textit{ec\_master\_simple\_io()} function provides a simple
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2543
interface for synchronously sending a single datagram and receiving
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2544
the result\footnote{For all communication issues have been meanwhile
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2545
  sourced out into state machines, the function is deprecated and
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2546
  stopped existing. Nevertheless it is adequate for showing it's own
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2547
  restrictions.}. Internally, it queues the specified datagram,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2548
invokes the \textit{ec\_master\_send\_datagrams()} function to send a
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2549
frame with the queued datagram and then waits actively for its
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2550
reception.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2551
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2552
This sequential approach is very simple, reflecting in only three
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2553
lines of code. The disadvantage is, that the master is blocked for the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2554
time it waits for datagram reception. There is no difficulty when only
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2555
one instance is using the master, but if more instances want to
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2556
(synchronously\footnote{At this time, synchronous master access will
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2557
  be adequate to show the advantages of an FSM. The asynchronous
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2558
  approach will be discussed in section~\ref{sec:eoeimp}}) use the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2559
master, it is inevitable to think about an alternative to the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2560
sequential model.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2561
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2562
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
  2563
wanting to send and receive datagrams synchronously. With the present
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2564
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
  2565
each instance, which would be non-acceptable especially in realtime
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2566
circumstances, because of the huge time overhead.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2567
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2568
A possible solution is, that all instances would be executed
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2569
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
  2570
next instance instead of waiting for the datagram reception. Finally,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2571
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
  2572
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
  2573
instances again, which then process their received datagrams and issue
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2574
new ones.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2575
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2576
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
  2577
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
  2578
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
  2579
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
  2580
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
  2581
from above as a state machine:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2582
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2583
\begin{lstlisting}[language=C,numbers=left]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2584
  // state 1
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2585
  ec_datagram_brd(datagram, 0x0130, 2); // prepare datagram
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2586
  ec_master_queue(master, datagram); // queue datagram
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2587
  next_state = state_2;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2588
  // state processing finished
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2589
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2590
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2591
After all instances executed their current state and queued their
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2592
datagrams, these are sent and received. Then the respective next
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2593
states are executed:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2594
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2595
\begin{lstlisting}[language=C,numbers=left]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2596
  // state 2
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2597
  if (datagram->state != EC_DGRAM_STATE_RECEIVED) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2598
          next_state = state_error;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2599
          return; // state processing finished
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2600
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2601
  slave_states = EC_READ_U8(datagram->data); // process datagram
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2602
  // state processing finished.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2603
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2604
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2605
See section~\ref{sec:statemodel} for an introduction to the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2606
state machine programming concept used in the master code.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2607
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2608
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2609
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2610
\subsection{State Machine Theory}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2611
\label{sec:fsmtheory}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2612
\index{FSM!Theory}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2613
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2614
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
  2615
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
  2616
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
  2617
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
  2618
S, s_0, \delta, \omega)$, with
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2619
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2620
\begin{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2621
\item the input alphabet $\Sigma$, with $\Sigma \neq
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2622
  \emptyset$, containing all input symbols,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2623
\item the output alphabet $\Gamma$, with $\Gamma \neq
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2624
  \emptyset$, containing all output symbols,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2625
\item the set of states $S$, with $S \neq \emptyset$,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2626
\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
  2627
  \emptyset$
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2628
\item the transition function $\delta: S \times \Sigma \rightarrow S
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2629
  \times \Gamma$
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2630
\item the output function $\omega$.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2631
\end{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2632
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2633
The state transition function $\delta$ is often specified by a
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2634
\textit{state transition table}, or by a \textit{state transition
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2635
  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
  2636
machine behavior (see table~\ref{tab:statetrans}). The matrix rows
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2637
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
  2638
correspond to the input symbols ($\Gamma = \{a, b, \varepsilon\}$).
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2639
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
  2640
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
  2641
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
  2642
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2643
\begin{table}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2644
  \caption{A typical state transition table}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2645
  \label{tab:statetrans}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2646
  \vspace{2mm}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2647
  \centering
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2648
  \begin{tabular}{l|ccc}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2649
    & $a$ & $b$ & $\varepsilon$\\ \hline
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2650
    $s_0$ & $s_1$ & $s_1$ & $s_2$\\
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2651
    $s_1$ & $s_2$ & $s_1$ & $s_0$\\
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2652
    $s_2$ & $s_0$ & $s_0$ & $s_0$\\ \hline
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2653
  \end{tabular}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2654
\end{table}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2655
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2656
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
  2657
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
  2658
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
  2659
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
  2660
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
  2661
circle with an arrow pointing to the respective state.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2662
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2663
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2664
  \centering
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2665
  \includegraphics[width=.5\textwidth]{images/statetrans}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2666
  \caption{A typical state transition diagram}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2667
  \label{fig:statetrans}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2668
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2669
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2670
\paragraph{Deterministic and non-deterministic state machines}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2671
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2672
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
  2673
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
  2674
state machine has exactly one starting state. Non-deterministic state
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2675
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
  2676
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
  2677
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2678
\paragraph{Moore and Mealy machines}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2679
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2680
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
  2681
\textit{Mealy machines}. Mathematically spoken, the distinction lies
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2682
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
  2683
state ($\omega: S \rightarrow \Gamma$), the machine corresponds to the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2684
``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
  2685
the input alphabet ($\omega: S \times \Sigma \rightarrow \Gamma$) the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2686
state machine corresponds to the ``Mealy model''. Mealy machines are
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2687
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
  2688
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
  2689
both models is often used.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2690
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2691
\paragraph{Misunderstandings about state machines}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2692
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2693
There is a phenomenon called ``state explosion'', that is oftenly
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2694
taken as a counter-argument against general use of state machines in
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2695
complex environments. It has to be mentioned, that this point is
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2696
misleading~\cite{fsmmis}. State explosions happen usually as a result
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2697
of a bad state machine design: Common mistakes are storing the present
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2698
values of all inputs in a state, or not dividing a complex state
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2699
machine into simpler sub state machines. The EtherCAT master uses
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2700
serveral state machines, that are executed hierarchically and so serve
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2701
as sub state machines. These are also described below.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2702
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2703
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2704
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2705
\subsection{The Master's State Model}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2706
\label{sec:statemodel}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2707
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2708
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
  2709
implement state machines.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2710
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2711
\paragraph{State Machine Programming}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2712
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2713
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
  2714
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
  2715
by one big case differentiation:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2716
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2717
\begin{lstlisting}[language=C,numbers=left]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2718
  enum {STATE_1, STATE_2, STATE_3};
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2719
  int state = STATE_1;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2720
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2721
  void state_machine_run(void *priv_data) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2722
          switch (state) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2723
                  case STATE_1:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2724
                          action_1();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2725
                          state = STATE_2;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2726
                          break;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2727
                  case STATE_2:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2728
                          action_2()
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2729
                          if (some_condition) state = STATE_1;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2730
                          else state = STATE_3;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2731
                          break;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2732
                  case STATE_3:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2733
                          action_3();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2734
                          state = STATE_1;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2735
                          break;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2736
          }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2737
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2738
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2739
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2740
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
  2741
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
  2742
additional case differentiation is executed each run. Besides, lots of
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2743
indentation is wasted.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2744
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2745
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
  2746
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
  2747
pointer:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2748
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2749
\begin{lstlisting}[language=C,numbers=left]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2750
  void (*state)(void *) = state1;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2751
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2752
  void state_machine_run(void *priv_data) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2753
          state(priv_data);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2754
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2755
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2756
  void state1(void *priv_data) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2757
          action_1();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2758
          state = state2;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2759
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2760
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2761
  void state2(void *priv_data) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2762
          action_2();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2763
          if (some_condition) state = state1;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2764
          else state = state2;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2765
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2766
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2767
  void state3(void *priv_data) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2768
          action_3();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2769
          state = state1;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2770
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2771
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2772
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2773
In the master code, state pointers of all state machines\footnote{All
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2774
  except for the EoE state machine, because multiple EoE slaves have
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2775
  to be handled in parallel. For this reason each EoE handler object
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2776
  has its own state pointer.} are gathered in a single object of the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2777
\textit{ec\_fsm\_t} class. This is advantageous, because there is
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2778
always one instance of every state machine available and can be
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2779
started on demand.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2780
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2781
\paragraph{Mealy and Moore}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2782
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2783
If a closer look is taken to the above listing, it can be seen that
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2784
the actions executed (the ``outputs'' of the state machine) only
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2785
depend on the current state. This accords to the ``Moore'' model
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2786
introduced in section~\ref{sec:fsmtheory}. As mentioned, the ``Mealy''
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2787
model offers a higher flexibility, which can be seen in the listing
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2788
below:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2789
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2790
\begin{lstlisting}[language=C,numbers=left]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2791
  void state7(void *priv_data) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2792
          if (some_condition) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2793
                  action_7a();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2794
                  state = state1;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2795
          }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2796
          else {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2797
                  action_7b();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2798
                  state = state8;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2799
          }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2800
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2801
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2802
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2803
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2804
\item[\normalfont\textcircled{\tiny 3} + \textcircled{\tiny 7}] The
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2805
  state function executes the actions depending on the state
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2806
  transition, that is about to be done.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2807
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2808
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2809
The most flexible alternative is to execute certain actions depending
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2810
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
  2811
transition:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2812
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2813
\begin{lstlisting}[language=C,numbers=left]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2814
  void state9(void *priv_data) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2815
          action_9();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2816
          if (some_condition) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2817
                  action_9a();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2818
                  state = state7;
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
          else {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2821
                  action_9b();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2822
                  state = state10;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2823
          }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2824
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2825
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2826
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2827
This model is oftenly used in the master. It combines the best aspects
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2828
of both approaches.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2829
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2830
\paragraph{Using Sub State Machines}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2831
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2832
To avoid having too much states, certain functions of the EtherCAT
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2833
master state machine have been sourced out into sub state machines.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2834
This helps to encapsule the related workflows and moreover avoids the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2835
``state explosion'' phenomenon described in
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2836
section~\ref{sec:fsmtheory}. If the master would instead use one big
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2837
state machine, the number of states would be a multiple of the actual
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2838
number. This would increase the level of complexity to a
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2839
non-manageable grade.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2840
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2841
\paragraph{Executing Sub State Machines}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2842
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2843
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
  2844
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
  2845
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
  2846
slave configuration state machine code:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2847
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2848
\begin{lstlisting}[language=C,numbers=left]
813
bfc3f1ab52de Fixed typo SAVEOP -> SAFEOP.
Florian Pose <fp@igh-essen.com>
parents: 487
diff changeset
  2849
  void ec_fsm_slaveconf_safeop(ec_fsm_t *fsm)
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2850
  {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2851
          fsm->change_state(fsm); // execute state change
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2852
                                  // sub state machine
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2853
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2854
          if (fsm->change_state == ec_fsm_error) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2855
                  fsm->slave_state = ec_fsm_end;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2856
                  return;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2857
          }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2858
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2859
          if (fsm->change_state != ec_fsm_end) return;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2860
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2861
          // continue state processing
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2862
          ...
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2863
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2864
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2865
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2866
\item[\normalfont\textcircled{\tiny 3}] \textit{change\_state} is the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2867
  state pointer of the state change state machine. The state function,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2868
  the pointer points on, is executed\ldots
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2869
\item[\normalfont\textcircled{\tiny 6}] \ldots either until the state
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2870
  machine terminates with the error state \ldots
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2871
\item[\normalfont\textcircled{\tiny 11}] \ldots or until the state
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2872
  machine terminates in the end state. Until then, the ``higher''
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2873
  state machine remains in the current state and executes the sub
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2874
  state machine again in the next cycle.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2875
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2876
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2877
\paragraph{State Machine Descriptions}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2878
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2879
The below sections describe every state machine used in the EtherCAT
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2880
master. The textual descriptions of the state machines contain
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2881
references to the transitions in the corresponding state transition
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2882
diagrams, that are marked with an arrow followed by the name of the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2883
successive state.  Transitions caused by trivial error cases (i.~e. no
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2884
response from slave) are not described explicitly. These transitions
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2885
are drawn as dashed arrows in the diagrams.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2886
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2887
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2888
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2889
\subsection{The Operation State Machine}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2890
\label{sec:fsm-op}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2891
\index{FSM!Operation}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2892
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2893
The Operation state machine is executed by calling the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2894
\textit{ecrt\_master\_run()} method in cyclic realtime code. Its
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2895
purpose is to monitor the bus and to reconfigure slaves after a bus
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2896
failure or power failure. Figure~\ref{fig:fsm-op} shows its transition
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2897
diagram.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2898
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2899
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2900
  \centering
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2901
  \includegraphics[width=.8\textwidth]{images/fsm-op}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2902
  \caption{Transition diagram of the operation state machine}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2903
  \label{fig:fsm-op}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2904
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2905
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2906
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2907
\item[START] This is the beginning state of the operation state
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2908
  machine. There is a datagram issued, that queries the ``AL Control
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2909
  Response'' attribute \cite[section~5.3.2]{alspec} of all slaves via
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2910
  broadcast. In this way, all slave states and the number of slaves
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2911
  responding can be determined.  $\rightarrow$~BROADCAST
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2912
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2913
\item[BROADCAST] The broadcast datagram is evaluated. A change in the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2914
  number of responding slaves is treates as a topology change. If the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2915
  number of slaves is not as expected, the bus is marked as
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2916
  ``tainted''. In this state, no slave reconfiguration is possible,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2917
  because the assignment of known slaves and those present on the bus
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2918
  is ambiguous. If the number of slaves is considered as right, the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2919
  bus is marked for validation, because it turned from tainted to
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2920
  normal state and it has to be checked, if all slaves are valid. Now,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2921
  the state of every single slave has to be determined. For that, a
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2922
  (unicast) datagram is issued, that queries the first slave's ``AL
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2923
  Control Response'' attribute. $\rightarrow$~READ STATES
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2924
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2925
\item[READ STATES] If the current slave did not respond to its
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2926
  configured station address, it is marked as offline, and the next
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2927
  slave is queried. $\rightarrow$~READ STATES
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2928
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2929
  If the slave responded, it is marked as online and its current state
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2930
  is stored. The next slave is queried. $\rightarrow$~READ STATES
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2931
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2932
  If all slaves have been queried, and the bus is marked for
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2933
  validation, the validation is started by checking the first slaves
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2934
  vendor ID. $\rightarrow$~VALIDATE VENDOR
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2935
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2936
  If no validation has to be done, it is checked, if all slaves are in
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2937
  the state they are supposed to be. If not, the first of slave with
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2938
  the wrong state is reconfigured and brought in the required state.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2939
  $\rightarrow$~CONFIGURE SLAVES
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2940
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2941
  If all slaves are in the correct state, the state machine is
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2942
  restarted. $\rightarrow$~START
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2943
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2944
\item[CONFIGURE SLAVES] The slave configuration state machine is
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2945
  executed until termination. $\rightarrow$~CONFIGURE SLAVES
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2946
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2947
  If there are still slaves in the wrong state after another check,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2948
  the first of these slaves is configured and brought into the correct
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2949
  state again. $\rightarrow$~CONFIGURE SLAVES
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2950
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2951
  If all slaves are in the correct state, the state machine is
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2952
  restarted. $\rightarrow$~START
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2953
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2954
\item[VALIDATE VENDOR] The SII state machine is executed until
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2955
  termination. If the slave has the wrong vendor ID, the state machine
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2956
  is restarted. $\rightarrow$~START
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2957
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2958
  If the slave has the correct vendor ID, its product ID is queried.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2959
  $\rightarrow$~VALIDATE PRODUCT
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2960
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2961
\item[VALIDATE PRODUCT] The SII state machine is executed until
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2962
  termination. If the slave has the wrong product ID, the state
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2963
  machine is restarted. $\rightarrow$~START
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2964
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2965
  If the slave has the correct product ID, the next slave's vendor ID
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2966
  is queried. $\rightarrow$~VALIDATE VENDOR
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2967
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2968
  If all slaves have the correct vendor IDs and product codes, the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2969
  configured station addresses can be safely rewritten. This is done
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2970
  for the first slave marked as offline.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2971
  $\rightarrow$~REWRITE ADDRESSES
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2972
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2973
\item[REWRITE ADDRESSES] If the station address was successfully
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2974
  written, it is sear\-ched for the next slave marked as offline. If
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2975
  there is one, its address is reconfigured, too.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2976
  $\rightarrow$~REWRITE ADDRESSES
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2977
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2978
  If there are no more slaves marked as offline, the state machine is
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2979
  restarted. $\rightarrow$~START
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2980
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2981
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2982
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2983
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2984
\subsection{The Idle State Machine}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2985
\label{sec:fsm-idle}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2986
\index{FSM!Idle}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2987
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2988
The Idle state machine is executed by a kernel workqueue, if no
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2989
realtime module is connected. Its purpose is to make slave information
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2990
available to user space, operate EoE-capable slaves, read and write
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2991
E$^2$PROM contents and test slave functionality.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2992
Figure~\ref{fig:fsm-idle} shows its transition diagram.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2993
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2994
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2995
  \centering
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2996
  \includegraphics[width=.8\textwidth]{images/fsm-idle}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2997
  \caption{Transition diagram of the idle state machine}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2998
  \label{fig:fsm-idle}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2999
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3000
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3001
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3002
\item[START] The beginning state of the idle state machine. Similar to
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3003
  the operation state machine, a broadcast datagram is issued, to
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3004
  query all slave states and the number of slaves.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3005
  $\rightarrow$~BROADCAST
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3006
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3007
\item[BROADCAST] The number of responding slaves is evaluated. If it
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3008
  has changed since the last time, this is treated as a topology
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3009
  change and the internal list of slaves is cleared and rebuild
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3010
  completely. The slave scan state machine is started for the first
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3011
  slave. $\rightarrow$~SCAN FOR SLAVES
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3012
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3013
  If no topology change happened, every single slave state is fetched.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3014
  $\rightarrow$~READ STATES
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3015
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3016
\item[SCAN FOR SLAVES] The slave scan state machine is executed until
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3017
  termination. $\rightarrow$~SCAN FOR SLAVES
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3018
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3019
  If there is another slave to scan, the slave scan state machine is
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3020
  started again. $\rightarrow$~SCAN FOR SLAVES
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3021
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3022
  If all slave information has been fetched, slave addresses are
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3023
  calculated and EoE processing is started. Then, the state machine is
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3024
  restarted. $\rightarrow$~START
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3025
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3026
\item[READ STATES] If the slave did not respond to the query, it is
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3027
  marked as offline. The next slave is queried.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3028
  $\rightarrow$~READ STATES
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3029
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3030
  If the slave responded, it is marked as online. And the next slave
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3031
  is queried. $\rightarrow$~READ STATES
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3032
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3033
  If all slave states have been determined, it is checked, if any
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3034
  slaves are not in the state they supposed to be. If this is true,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3035
  the slave configuration state machine is started for the first of
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3036
  them. $\rightarrow$~CONFIGURE SLAVES
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3037
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3038
  If all slaves are in the correct state, it is checked, if any
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3039
  E$^2$PROM write operations are pending. If this is true, the first
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3040
  pending operation is executed by starting the SII state machine for
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3041
  writing access. $\rightarrow$~WRITE EEPROM
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3042
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3043
  If all these conditions are false, there is nothing to do and the
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3044
  state machine is restarted. $\rightarrow$~START
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3045
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3046
\item[CONFIGURE SLAVES] The slave configuration state machine is
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3047
  executed until termination. $\rightarrow$~CONFIGURE SLAVES
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3048
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3049
  After this, it is checked, if another slave needs a state change. If
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3050
  this is true, the slave state change state machine is started for
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3051
  this slave. $\rightarrow$~CONFIGURE SLAVES
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3052
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3053
  If all slaves are in the correct state, it is determined, if any
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3054
  E$^2$PROM write operations are pending. If this is true, the first
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3055
  pending operation is executed by starting the SII state machine for
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3056
  writing access. $\rightarrow$~WRITE EEPROM
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3057
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3058
  If all prior conditions are false, the state machine is restarted.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3059
  $\rightarrow$~START
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3060
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3061
\item[WRITE EEPROM] The SII state machine is executed until
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3062
  termination. $\rightarrow$~WRITE EEPROM
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3063
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3064
  If the current word has been written successfully, and there are
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3065
  still word to write, the SII state machine is started for the next
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3066
  word. $\rightarrow$~WRITE EEPROM
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3067
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3068
  If all words have been written successfully, the new E$^2$PROM
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3069
  contents are evaluated and the state machine is restarted.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3070
  $\rightarrow$~START
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3071
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3072
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3073
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3074
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3075
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3076
\subsection{The Slave Scan State Machine}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3077
\label{sec:fsm-scan}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3078
\index{FSM!Slave Scan}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3079
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3080
The slave scan state machine, which can be seen in
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3081
figure~\ref{fig:fsm-slavescan}, leads through the process of fetching
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3082
all slave information.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3083
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3084
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3085
  \centering
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3086
  \includegraphics[width=.6\textwidth]{images/fsm-slavescan}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3087
  \caption{Transition diagram of the slave scan state machine}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3088
  \label{fig:fsm-slavescan}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3089
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3090
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3091
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3092
\item[START] In the beginning state of the slave scan state machine,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3093
  the station address is written to the slave, which is always the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3094
  ring position~+~$1$. In this way, the address 0x0000 (default
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3095
  address) is not used, which makes it easy to detect unconfigured
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3096
  slaves.  $\rightarrow$~ADDRESS
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3097
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3098
\item[ADDRESS] The writing of the station address is verified. After
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3099
  that, the slave's ``AL Control Response'' attribute is queried.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3100
  $\rightarrow$~STATE
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3101
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3102
\item[STATE] The AL state is evaluated. A warning is output, if the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3103
  slave has still the \textit{Change} bit set. After that, the slave's
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3104
  ``DL Information'' attribute is queried.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3105
  $\rightarrow$~BASE
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3106
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3107
\item[BASE] The queried base data are evaluated: Slave type, revision
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3108
  and build number, and even more important, the number of supported
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3109
  sync managers and FMMUs are stored. After that, the slave's data
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3110
  link layer information is read from the ``DL Status'' attribute at
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3111
  address 0x0110. $\rightarrow$~DATALINK
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3112
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3113
\item[DATALINK] In this state, the DL information is evaluated: This
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3114
  information about the communication ports contains, if the link is
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3115
  up, if the loop has been closed and if there is a carrier detected
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3116
  on the RX side of each port.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3117
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3118
  Then, the state machine starts measuring the size of the slave's
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3119
  E$^2$PROM contents. This is done by subsequently reading out each
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3120
  category header, until the last category is reached (type 0xFFFF).
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3121
  This procedure is started by querying the first category header at
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3122
  word address 0x0040 via the SII state machine.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3123
  $\rightarrow$~EEPROM SIZE
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3124
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3125
\item[EEPROM SIZE] The SII state machine is executed until
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3126
  termination. $\rightarrow$~EEPROM SIZE
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3127
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3128
  If the category type does not mark the end of the categories, the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3129
  position of the next category header is determined via the length of
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3130
  the current category, and the SII state machine is started again.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3131
  $\rightarrow$~EEPROM SIZE
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3132
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3133
  If the size of the E$^2$PROM contents has been determined, memory is
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3134
  allocated, to read all the contents. The SII state machine is
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3135
  started to read the first word. $\rightarrow$~EEPROM DATA
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3136
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3137
\item[EEPROM DATA] The SII state machine is executed until
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3138
  termination. $\rightarrow$~EEPROM DATA
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3139
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3140
  Two words have been read. If more than one word is needed, the two
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3141
  words are written in the allocated memory. Otherwise only one word
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3142
  (the last word) is copied. If more words are to read, the SII state
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3143
  machine is started again to read the next two words.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3144
  $\rightarrow$~EEPROM DATA
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3145
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3146
  The complete E$^2$PROM contents have been read. The slave's identity
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3147
  object and mailbox information are evaluated. Moreover the category
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3148
  types STRINGS, GENERAL, SYNC and PDO are evaluated. The slave
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3149
  scanning has been completed. $\rightarrow$~END
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3150
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3151
\item[END] Slave scanning has been finished.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3152
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3153
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3154
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3155
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3156
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3157
\subsection{The Slave Configuration State Machine}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3158
\label{sec:fsm-conf}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3159
\index{FSM!Slave Configuration}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3160
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3161
The slave configuration state machine, which can be seen in
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3162
figure~\ref{fig:fsm-slaveconf}, leads through the process of
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3163
configuring a slave and bringing it to a certain state.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3164
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3165
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3166
  \centering
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3167
  \includegraphics[width=.6\textwidth]{images/fsm-slaveconf}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3168
  \caption{Transition diagram of the slave configuration state
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3169
    machine}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3170
  \label{fig:fsm-slaveconf}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3171
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3172
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3173
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3174
\item[INIT] The state change state machine has been initialized to
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3175
  bring the slave into the INIT state. Now, the slave state change
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3176
  state machine is executed until termination. $\rightarrow$~INIT
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3177
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3178
  If the slave state change failed, the configuration has to be
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3179
  aborted. $\rightarrow$~END
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3180
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3181
  The slave state change succeeded and the slave is now in INIT state.
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3182
  If this is the target state, the configuration is finished.
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3183
  $\rightarrow$~END
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3184
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3185
  If the slave does not support any sync managers, the sync manager
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3186
  configuration can be skipped. The state change state machine is
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3187
  started to bring the slave into PREOP state.
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3188
  $\rightarrow$~PREOP
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3189
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3190
  Sync managers are configured conforming to the sync manager category
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3191
  information provided in the slave's E$^2$PROM. The corresponding
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3192
  datagram is issued. $\rightarrow$~SYNC
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3193
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3194
\item[SYNC] If the sync manager configuration datagram is accepted,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3195
  the sync manager configuration was successful. The slave may now
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3196
  enter the PREOP state, and the state change state machine is
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3197
  started. $\rightarrow$~PREOP
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3198
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3199
\item[PREOP] The state change state machine is executed until
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3200
  termination. $\rightarrow$~PREOP
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3201
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3202
  If the state change failed, the configuration has to be aborted.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3203
  $\rightarrow$~END
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3204
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3205
  If the PREOP state was the target state, the configuration is
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3206
  finished. $\rightarrow$~END
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3207
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3208
  If the slave supports no FMMUs, the FMMU configuration can be
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  3209
  skipped. If the slave has Sdos to configure, it is begun with
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  3210
  sending the first Sdo. $\rightarrow$~SDO\_CONF
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  3211
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  3212
  If no Sdo configurations are provided, the slave can now directly be
813
bfc3f1ab52de Fixed typo SAVEOP -> SAFEOP.
Florian Pose <fp@igh-essen.com>
parents: 487
diff changeset
  3213
  brought into the SAFEOP state and the state change state machine is
bfc3f1ab52de Fixed typo SAVEOP -> SAFEOP.
Florian Pose <fp@igh-essen.com>
parents: 487
diff changeset
  3214
  started again. $\rightarrow$~SAFEOP
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3215
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  3216
  Otherwise, all supported FMMUs are configured according to the Pdos
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3217
  requested via the master's realtime interface. The appropriate
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3218
  datagram is issued. $\rightarrow$~FMMU
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3219
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3220
\item[FMMU] The FMMU configuration datagram was accepted. If the slave
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  3221
  has Sdos to configure, it is begun with sending the first Sdo.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3222
  $\rightarrow$~SDO\_CONF
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3223
813
bfc3f1ab52de Fixed typo SAVEOP -> SAFEOP.
Florian Pose <fp@igh-essen.com>
parents: 487
diff changeset
  3224
  Otherwise, the slave can now be brought into the SAFEOP state. The
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3225
  state change state machine is started.
813
bfc3f1ab52de Fixed typo SAVEOP -> SAFEOP.
Florian Pose <fp@igh-essen.com>
parents: 487
diff changeset
  3226
  $\rightarrow$~SAFEOP
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3227
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3228
\item[SDO\_CONF] The CoE state machine is executed until termination.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3229
  $\rightarrow$~SDO\_CONF
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3230
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  3231
  If another Sdo has to be configured, a new Sdo download sequence is
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3232
  begun. $\rightarrow$~SDO\_CONF
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3233
813
bfc3f1ab52de Fixed typo SAVEOP -> SAFEOP.
Florian Pose <fp@igh-essen.com>
parents: 487
diff changeset
  3234
  Otherwise, the slave can now be brought into the SAFEOP state. The
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3235
  state change state machine is started.
813
bfc3f1ab52de Fixed typo SAVEOP -> SAFEOP.
Florian Pose <fp@igh-essen.com>
parents: 487
diff changeset
  3236
  $\rightarrow$~SAFEOP
bfc3f1ab52de Fixed typo SAVEOP -> SAFEOP.
Florian Pose <fp@igh-essen.com>
parents: 487
diff changeset
  3237
bfc3f1ab52de Fixed typo SAVEOP -> SAFEOP.
Florian Pose <fp@igh-essen.com>
parents: 487
diff changeset
  3238
\item[SAFEOP] The state change state machine is executed until
bfc3f1ab52de Fixed typo SAVEOP -> SAFEOP.
Florian Pose <fp@igh-essen.com>
parents: 487
diff changeset
  3239
  termination. $\rightarrow$~SAFEOP
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3240
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3241
  If the state change failed, the configuration has to be aborted.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3242
  $\rightarrow$~END
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3243
813
bfc3f1ab52de Fixed typo SAVEOP -> SAFEOP.
Florian Pose <fp@igh-essen.com>
parents: 487
diff changeset
  3244
  If the SAFEOP state was the target state, the configuration is
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3245
  finished. $\rightarrow$~END
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3246
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3247
  The slave can now directly be brought into the OP state and the
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3248
  state change state machine is started a last time.
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3249
  $\rightarrow$~OP
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3250
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3251
\item[OP] The state change state machine is executed until
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3252
  termination. $\rightarrow$~OP
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3253
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3254
  If the state change state machine terminates, the slave
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3255
  configuration is finished, regardless of its success.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3256
  $\rightarrow$~END
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3257
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3258
\item[END] The termination state.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3259
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3260
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3261
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3262
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3263
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3264
\subsection{The State Change State Machine}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3265
\label{sec:fsm-change}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3266
\index{FSM!State Change}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3267
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3268
The state change state machine, which can be seen in
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3269
figure~\ref{fig:fsm-change}, leads through the process of changing a
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3270
slave's state. This implements the states and transitions described in
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3271
\cite[section~6.4.1]{alspec}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3272
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3273
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3274
  \centering
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3275
  \includegraphics[width=.9\textwidth]{images/fsm-change}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3276
  \caption{Transition diagram of the state change state machine}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3277
  \label{fig:fsm-change}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3278
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3279
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3280
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3281
\item[START] The beginning state, where a datagram with the state
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3282
  change command is written to the slave's ``AL Control Request''
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3283
  attribute. Nothing can fail. $\rightarrow$~CHECK
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3284
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3285
\item[CHECK] After the state change datagram has been sent, the ``AL
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3286
  Control Response'' attribute is queried with a second datagram.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3287
  $\rightarrow$~STATUS
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3288
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3289
\item[STATUS] The read memory contents are evaluated: While the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3290
  parameter \textit{State} still contains the old slave state, the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3291
  slave is busy with reacting on the state change command. In this
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3292
  case, the attribute has to be queried again.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3293
  $\rightarrow$~STATUS
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3294
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3295
  In case of success, the \textit{State} parameter contains the new
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3296
  state and the \textit{Change} bit is cleared. The slave is in the
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3297
  requested state.  $\rightarrow$~END
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3298
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3299
  If the slave can not process the state change, the \textit{Change}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3300
  bit is set: Now the master tries to get the reason for this by
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3301
  querying the \textit{AL Status Code} parameter.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3302
  $\rightarrow$~CODE
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3303
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3304
\item[END] If the state machine ends in this state, the slaves's state
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3305
  change has been successful.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3306
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3307
\item[CODE] The status code query has been sent. Reading the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3308
  \textit{AL Status Code} might fail, because not all slaves support
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3309
  this parameter. Anyway, the master has to acknowledge the state
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3310
  change error by writing the current slave state to the ``AL Control
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3311
  Request'' attribute with the \textit{Acknowledge} bit set.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3312
  $\rightarrow$~ACK
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3313
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3314
\item[ACK] After that, the ``AL Control Response'' attribute is
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3315
  queried for the state of the acknowledgement.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3316
  $\rightarrow$~CHECK ACK
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3317
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3318
\item[CHECK ACK] If the acknowledgement has been accepted by the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3319
  slave, the old state is kept. Still, the state change was
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3320
  unsuccessful. $\rightarrow$~ERROR
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3321
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3322
  If the acknowledgement is ignored by the slave, a timeout happens.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3323
  In any case, the overall state change was unsuccessful.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3324
  $\rightarrow$~ERROR
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3325
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3326
  If there is still now response from the slave, but the timer did not
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3327
  run out yet, the slave's ``AL Control Response'' attribute is
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3328
  queried again.  $\rightarrow$~CHECK ACK
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3329
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3330
\item[ERROR] If the state machine ends in this state, the slave's
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3331
  state change was unsuccessful.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3332
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3333
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3334
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3335
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3336
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3337
\subsection{The SII State Machine}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3338
\label{sec:fsm-sii}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3339
\index{FSM!SII}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3340
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3341
The SII\index{SII} state machine (shown in figure~\ref{fig:fsm-sii})
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3342
implements the process of reading or writing E$^2$PROM data via the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3343
Slave Information Interface described in \cite[section~5.4]{alspec}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3344
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3345
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3346
  \centering
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3347
  \includegraphics[width=.9\textwidth]{images/fsm-sii}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3348
  \caption{Transition diagram of the SII state machine}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3349
  \label{fig:fsm-sii}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3350
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3351
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3352
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3353
\item[READ\_START] The beginning state for reading access, where the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3354
  read request and the requested address are written to the SII
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3355
  attribute. Nothing can fail up to now.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3356
  $\rightarrow$~READ\_CHECK
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3357
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3358
\item[READ\_CHECK] When the SII read request has been sent
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3359
  successfully, a timer is started. A check/fetch datagram is issued,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3360
  that reads out the SII attribute for state and data.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3361
  $\rightarrow$~READ\_FETCH
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3362
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3363
\item[READ\_FETCH] Upon reception of the check/fetch datagram, the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3364
  \textit{Read Operation} and \textit{Busy} parameters are checked:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3365
  \begin{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3366
  \item If the slave is still busy with fetching E$^2$PROM data into
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3367
    the interface, the timer is checked. If it timed out, the reading
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3368
    is aborted ($\rightarrow$~ERROR), if not, the check/fetch datagram
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3369
    is issued again. $\rightarrow$~READ\_FETCH
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3370
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3371
  \item If the slave is ready with reading data, these are copied from
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3372
    the datagram and the read cycle is completed.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3373
    $\rightarrow$~END
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3374
  \end{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3375
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3376
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3377
The write access states behave nearly the same:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3378
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3379
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3380
\item[WRITE\_START] The beginning state for writing access,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3381
  respectively. A write request, the target address and the data word
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3382
  are written to the SII attribute. Nothing can fail.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3383
  $\rightarrow$~WRITE\_CHECK
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3384
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3385
\item[WRITE\_CHECK] When the SII write request has been sent
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3386
  successfully, the timer is started. A check datagram is issued, that
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3387
  reads out the SII attribute for the state of the write operation.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3388
  $\rightarrow$~WRITE\_CHECK2
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3389
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3390
\item[WRITE\_CHECK2] Upon reception of the check datagram, the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3391
  \textit{Write Operation} and \textit{Busy} parameters are checked:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3392
  \begin{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3393
  \item If the slave is still busy with writing E$^2$PROM data, the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3394
    timer is checked. If it timed out, the operation is aborted
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3395
    ($\rightarrow$~ERROR), if not, the check datagram is issued again.
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3396
    $\rightarrow$~WRITE\_CHECK2
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3397
  \item If the slave is ready with writing data, the write cycle is
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3398
    completed. $\rightarrow$~END
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3399
  \end{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3400
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3401
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3402
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3403
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3404
\section{Mailbox Protocol Implementations}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3405
\index{Mailbox}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3406
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3407
The EtherCAT master implements the EoE and the CoE mailbox
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3408
protocols. See the below section for details.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3409
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3410
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3411
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3412
\subsection{Ethernet-over-EtherCAT (EoE)}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3413
\label{sec:eoeimp}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3414
\index{EoE}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3415
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3416
The EtherCAT master implements the Ethernet-over-EtherCAT mailbox
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3417
protocol to enable the tunneling of Ethernet frames to special slaves,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3418
that can either have physical Ethernet ports to forward the frames to,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3419
or have an own IP stack to receive the frames.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3420
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3421
\paragraph{Virtual Network Interfaces}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3422
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3423
The master creates a virtual EoE network interface for every
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3424
EoE-capable slave. These interfaces are called \textit{eoeX}, where X
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3425
is a number provided by the kernel on interface registration. Frames
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3426
sent to these interfaces are forwarded to the associated slaves by the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3427
master. Frames, that are received by the slaves, are fetched by the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3428
master and forwarded to the virtual interfaces.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3429
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3430
This bears the following advantages:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3431
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3432
\begin{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3433
\item Flexibility: The user can decide, how the EoE-capable slaves are
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3434
  interconnected with the rest of the world.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3435
\item Standard tools can be used to monitor the EoE activity and to
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3436
  configure the EoE interfaces.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3437
\item The Linux kernel's layer-2-bridging implementation (according to
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3438
  the IEEE 802.1D MAC Bridging standard) can be used natively to
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3439
  bridge Ethernet traffic between EoE-capable slaves.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3440
\item The Linux kernel's network stack can be used to route packets
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3441
  between EoE-capable slaves and to track security issues, just like
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3442
  having physical network interfaces.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3443
\end{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3444
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3445
\paragraph{EoE Handlers}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3446
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3447
The virtual EoE interfaces and the related functionality is encapsuled
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3448
in the \textit{ec\_eoe\_t} class (see section~\ref{sec:class-eoe}).
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3449
So the master does not create the network interfaces directly: This is
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3450
done inside the constructor of the \textit{ec\_eoe\_t} class. An
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3451
object of this class is called ``EoE handler'' below. An EoE handler
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3452
additionaly contains a frame queue. Each time, the kernel passes a new
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3453
socket buffer for sending via the interface's
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3454
\textit{hard\_start\_xmit()} callback, the socket buffer is queued for
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3455
transmittion by the EoE state machine (see below). If the queue gets
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3456
filled up, the passing of new socket buffers is suspended with a call
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3457
to \textit{netif\_stop\_queue()}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3458
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3459
\paragraph{Static Handler Creation}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3460
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3461
The master creates a pool of EoE handlers at startup, that are coupled
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3462
to EoE-capable slaves on demand. The lifetime of the corresponding
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3463
network interfaces is equal to the lifetime of the master module.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3464
This approach is opposed to creating the virtual network interfaces on
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3465
demand (i.~e. on running across a new EoE-capable slave). The latter
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3466
approach was considered as difficult, because of serveral reasons:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3467
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3468
\begin{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3469
\item The \textit{alloc\_netdev()} function can sleep and must be
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3470
  called from a non-interrupt context. This reduces the flexibility of
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3471
  choosing an appropriate method for cyclic EoE processing.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3472
\item Unregistering network interfaces requires them to be ``down'',
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3473
  which can not be guaranteed upon sudden disappearing of an
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3474
  EoE-capable slave.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3475
\item The connection to the EoE-capable slaves must be as continuous
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3476
  as possible. Especially the transition from idle to operation mode
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3477
  (and vice versa) causes the rebuilding of the internal data
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3478
  structures. These transitions must be as transparent as possible for
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3479
  the instances using the network interfaces.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3480
\end{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3481
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3482
\paragraph{Number of Handlers}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3483
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3484
The master module has a parameter \textit{ec\_eoeif\_count} to specify
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3485
the number of EoE interfaces (and handlers) per master to create. This
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3486
parameter can either be specified when manually loading the master
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3487
module, or (when using the init script) by setting the
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3488
\$EOE\_INTERFACES variable in the sysconfig file (see
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3489
section~\ref{sec:sysconfig}). Upon loading of the master module, the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3490
virtual interfaces become available:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3491
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3492
\begin{lstlisting}
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3493
  # `\textbf{ifconfig -a}`
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3494
  eoe0      Link encap:Ethernet  HWaddr 00:11:22:33:44:06
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3495
            BROADCAST MULTICAST  MTU:1500  Metric:1
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3496
            RX packets:0 errors:0 dropped:0 overruns:0 frame:0
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3497
            TX packets:0 errors:0 dropped:0 overruns:0 carrier:0
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3498
            collisions:0 txqueuelen:1000
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3499
            RX bytes:0 (0.0 b)  TX bytes:0 (0.0 b)
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3500
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3501
  eoe1      Link encap:Ethernet  HWaddr 00:11:22:33:44:07
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3502
            BROADCAST MULTICAST  MTU:1500  Metric:1
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3503
            RX packets:0 errors:0 dropped:0 overruns:0 frame:0
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3504
            TX packets:0 errors:0 dropped:0 overruns:0 carrier:0
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3505
            collisions:0 txqueuelen:1000
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3506
            RX bytes:0 (0.0 b)  TX bytes:0 (0.0 b)
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3507
  ...
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3508
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3509
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3510
\paragraph{Coupling of EoE Slaves}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3511
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3512
During execution of the slave scan state machine (see
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3513
section~\ref{sec:fsm-scan}), the master determines the supported
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3514
mailbox protocols. This is done by examining the ``Supported Mailbox
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3515
Protocols'' mask field at word address 0x001C of the SII\index{SII}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3516
If bit 1 is set, the slave supports the EoE protocol. After slave
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3517
scanning, the master runs through all slaves again and couples each
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3518
EoE-capable slave to a free EoE handler. It can happen, that there are
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3519
not enough EoE handlers to cover all EoE-capable slaves. In this case,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3520
the number of EoE handlers must be increased accordingly.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3521
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3522
\paragraph{EoE State Machine}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3523
\index{FSM!EoE}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3524
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3525
Every EoE handler owns an EoE state machine, that is used to send
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3526
frames to the coupled slave and receive frames from the it via the EoE
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3527
communication primitives. This state machine is showed in
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3528
figure~\ref{fig:fsm-eoe}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3529
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3530
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3531
  \centering
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3532
  \includegraphics[width=.7\textwidth]{images/fsm-eoe}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3533
  \caption{Transition diagram of the EoE state machine}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3534
  \label{fig:fsm-eoe}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3535
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3536
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3537
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3538
\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
  3539
  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
  3540
  frames. $\rightarrow$~RX\_CHECK
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3541
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3542
\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
  3543
  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
  3544
  $\rightarrow$~TX\_START
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3545
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3546
  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
  3547
  the new data. $\rightarrow$~RX\_FETCH
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3548
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3549
\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
  3550
  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
  3551
  dropped and a transmit sequence is started.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3552
  $\rightarrow$~TX\_START
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3553
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3554
  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
  3555
  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
  3556
  the correct position of the socket buffer.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3557
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3558
  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
  3559
  to the network stack and a transmit sequence is started.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3560
  $\rightarrow$~TX\_START
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3561
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3562
  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
  3563
  fragment. $\rightarrow$~RX\_\-START
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3564
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3565
\item[TX\_START] The beginning state of a transmit sequence. It is
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3566
  checked, if the transmittion queue contains a frame to send. If not,
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3567
  a receive sequence is started. $\rightarrow$~RX\_START
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3568
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3569
  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
  3570
  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
  3571
  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
  3572
  frame is sent. $\rightarrow$~TX\_SENT
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3573
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3574
\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
  3575
  successfully. If the current frame consists of further fragments,
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3576
  the next one is sent. $\rightarrow$~TX\_SENT
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3577
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3578
  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
  3579
  $\rightarrow$~RX\_START
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3580
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3581
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3582
\paragraph{EoE Processing}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3583
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3584
To execute the EoE state machine of every active EoE handler, there
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3585
must be a cyclic process. The easiest thing would be to execute the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3586
EoE state machines synchronously to the operation state machine (see
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3587
section~\ref{sec:fsm-op}) with every realtime cycle. This approach has
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3588
the following disadvantages:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3589
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3590
\begin{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3591
\item Only one EoE fragment can be sent or received every few cycles.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3592
  This causes the data rate to be very low, because the EoE state
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3593
  machines are not executed in the time between the realtime
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3594
  cycles. Moreover, the data rate would be dependent on the frequency
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3595
  of the realtime process.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3596
\item The receiving and forwarding of frames to the kernel requires
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3597
  the dynamic allocation of frames. Some realtime extensions do not
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3598
  support calling memory allocation functions in realtime context, so
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3599
  the EoE state machine may not be executed with each realtime cycle.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3600
\end{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3601
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3602
To overcome these problems, an own cyclic process is needed to
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3603
asynchronously execute the EoE state machines. For that, the master
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3604
owns a kernel timer, that is executed each timer interrupt. This
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3605
guarantees a constant bandwidth, but poses the new problem of
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3606
concurrent access to the master. The locking mechanisms needed for
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3607
this are introduced in section~\ref{sec:concurr}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3608
Section~\ref{sec:concurrency} gives practical implementation examples.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3609
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3610
\paragraph{Idle Mode}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3611
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3612
EoE data must also be exchanged idle mode, to guarantee the continuous
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3613
availability of the connection to the EoE-capable slaves. Although
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3614
there is no realtime module connected in this case, the master is
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3615
still accessed by the idle state machine (see
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3616
section~\ref{sec:fsm-idle}), that is executed by the master's
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3617
workqueue. With the EoE timer running in addition, there is still
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3618
concurrency, that has to be protected by a lock. Therefore the master
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3619
owns an internal spinlock that is used protect master access during
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3620
idle mode.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3621
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3622
\paragraph{Automatic Configuration}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3623
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3624
By default, slaves are left in INIT state during idle mode. If an EoE
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3625
interface is set to running state (i.~e. with the \textit{ifconfig up}
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3626
command), the requested slave state of the related slave is
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3627
automatically set to OP, whereupon the idle state machine will attempt
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3628
to configure the slave and put it into operation.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3629
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3630
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3631
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3632
\subsection{CANopen-over-EtherCAT (CoE)}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3633
\label{sec:coeimp}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3634
\index{CoE}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3635
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3636
The CANopen-over-EtherCAT protocol \cite[section~5.6]{alspec} is used
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3637
to configure slaves on application level. Each CoE-capable slave
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  3638
provides a list of Sdos for this reason.
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  3639
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  3640
\paragraph{Sdo Configuration}
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  3641
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  3642
The Sdo configurations have to be provided by the realtime module.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3643
This is done via the \textit{ecrt\_slave\_conf\_sdo*()} methods (see
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3644
section~\ref{sec:ecrt-slave}), that are part of the realtime
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  3645
interface. The slave stores the Sdo configurations in a linked list,
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3646
but does not apply them at once.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3647
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  3648
\paragraph{Sdo Download State Machine}
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  3649
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  3650
The best time to apply Sdo configurations is during the slave's PREOP
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3651
state, because mailbox communication is already possible and slave's
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3652
application will start with updating input data in the succeeding
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  3653
SAFEOP state. Therefore the Sdo configuration has to be part of the
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3654
slave configuration state machine (see section~\ref{sec:fsm-conf}): It
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  3655
is implemented via an Sdo download state machine, that is executed
813
bfc3f1ab52de Fixed typo SAVEOP -> SAFEOP.
Florian Pose <fp@igh-essen.com>
parents: 487
diff changeset
  3656
just before entering the slave's SAFEOP state. In this way, it is
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  3657
guaranteed that the Sdo configurations are applied each time, the
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3658
slave is reconfigured.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3659
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  3660
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
  3661
in figure~\ref{fig:fsm-coedown}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3662
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3663
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3664
  \centering
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3665
  \includegraphics[width=.9\textwidth]{images/fsm-coedown}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3666
  \caption{Transition diagram of the CoE download state machine}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3667
  \label{fig:fsm-coedown}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3668
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3669
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3670
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3671
\item[START] The beginning state of the CoE download state
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  3672
  machine. The ``Sdo Download Normal Request'' mailbox command is
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3673
  sent. $\rightarrow$~REQUEST
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3674
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3675
\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
  3676
  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
  3677
  and a timer is started. $\rightarrow$~CHECK
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3678
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3679
\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
  3680
  \begin{itemize}
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  3681
  \item If it timed out, the Sdo download is aborted.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3682
    $\rightarrow$~ERROR
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3683
  \item Otherwise, the mailbox is queried again.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3684
    $\rightarrow$~CHECK
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3685
  \end{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3686
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3687
  If the mailbox contains new data, the response is fetched.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3688
  $\rightarrow$~RESPONSE
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3689
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3690
\item[RESPONSE] If the mailbox response could not be fetched, the data
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  3691
  is invalid, the wrong protocol was received, or a ``Abort Sdo
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  3692
  Transfer Request'' was received, the Sdo download is aborted.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3693
  $\rightarrow$~ERROR
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3694
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  3695
  If a ``Sdo Download Normal Response'' acknowledgement was received,
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  3696
  the Sdo download was successful. $\rightarrow$~END
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  3697
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  3698
\item[END] The Sdo download was successful.
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  3699
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  3700
\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
  3701
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3702
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3703
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3704
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3705
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3706
\section{User Space}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3707
\label{sec:user}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3708
\index{User space}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3709
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3710
For the master runs as a kernel module, accessing it is natively
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3711
limited to analyzing syslog messages and controlling using modutils.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3712
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3713
It is necessary to implement further interfaces, that make it easier
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3714
to access the master from user space and allow a finer influence. It
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3715
should be possible to view and to change special parameters at runtime.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3716
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3717
Bus visualization is a second point: For development and debugging
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3718
purposes it would be nice, if one could show the connected slaves with
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3719
a single command.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3720
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3721
Another aspect is automatic startup and configuration. If the master
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3722
is to be integrated into a running system, it must be able to
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3723
automatically start with a persistent configuration.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3724
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3725
A last thing is monitoring EtherCAT communication. For debugging
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3726
purposes, there had to be a way to analyze EtherCAT datagrams. The
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3727
best way would be with a popular network analyzer, like Wireshark
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3728
\cite{wireshark} (the former Ethereal) or others.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3729
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3730
This section covers all those points and introduces the interfaces and
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3731
tools to make all that possible.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3732
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3733
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3734
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3735
\subsection{The Sysfs Interface}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3736
\label{sec:sysfs}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3737
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3738
The system filesystem (Sysfs\index{Sysfs}) was introduced with Linux
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3739
kernel 2.5 and is a well-defined interface for drivers to export
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3740
information to user space. It serves also as an relief for the process
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3741
filesystem (Procfs), where over the years much non-process information
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3742
was concentrated.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3743
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3744
Sysfs exports information about devices, classes and busses via a
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3745
virtual filesystem, usually mounted to \textit{/sys}. The EtherCAT
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3746
master slightly differs from this concept, because the only physical
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3747
device is the network adapter it uses for bus communication, which is
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3748
already represented in Sysfs. For the EtherCAT bus is no system bus
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3749
like PCI (with device and driver structures), it would not make any
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3750
sense to represent it as bus structure in Sysfs.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3751
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3752
Therefore, the EtherCAT master is represented as a new directory
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3753
directly unter the Sysfs root. Every master gets its own Sysfs entry
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3754
named \textit{ethercatX}, where X is the index of the master. Two
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3755
masters would result in the directories \textit{/sys/ethercat0} and
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3756
\textit{/sys/ethercat1}, respectively.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3757
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3758
The Sysfs base class in the kernel code is the \textit{kobject}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3759
structure. Each object structure, that is to be represented in Sysfs,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3760
has to contain such a structure, because due to the concurrent access
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3761
(through ``normal'' kernel code and Sysfs code) the object deletion
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3762
gets a little more complicated: The object may not be freed until no
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3763
instance uses it any more. Therefore, each kobject maintains a
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3764
reference counter. If the reference counter gets zero, the object is
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3765
finally freed. A kobject can be registered to appear as a directory in
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3766
Sysfs with a call to \textit{kobject\_add()}. Each kobject type can
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3767
define attributes, that appear as files in the kobject's
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3768
directory. Callback functions have to be provided for reading (and
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3769
perhaps writing) access.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3770
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3771
\subsubsection{Master Attributes}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3772
\label{sec:sysfs-master}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3773
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3774
Below is a typical listing of the masters Sysfs directory (that is a
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3775
file system representation of the master's kobject):
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3776
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3777
\begin{lstlisting}
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3778
  `\$` `\textbf{ls /sys/ethercat0}`
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3779
  debug_level          slave000  slave003  slave006
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3780
  eeprom_write_enable  slave001  slave004  slave007
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3781
  info                 slave002  slave005  slave008
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3782
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3783
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3784
The following attributes exist in the master directory:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3785
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3786
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3787
\item[debug\_level] (read/write) This attribute contains the master's
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3788
  debug level, which controls, how much information is printed into
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3789
  syslog. The values 0 (no additional debug messages), 1 (a few
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3790
  additional debug messages) and 2 (all additional debug messages) are
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3791
  defined. Writing is done with command like
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3792
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3793
  \begin{lstlisting}[gobble=4]
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3794
    # `\textbf{echo 1 > /sys/ethercat0/debug\_level}`
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3795
  \end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3796
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3797
  and is receipted with a syslog message by the master:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3798
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3799
  \begin{lstlisting}[gobble=4]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3800
    EtherCAT: Master debug level set to 1.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3801
  \end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3802
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3803
\item[enable\_eeprom\_writing] (read/write) See
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3804
  section~\ref{sec:eepromaccess} for how to use this attribute.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3805
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3806
\item[info] (read only) This attribute contains information about the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3807
  master. Example contents are below:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3808
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3809
  \begin{lstlisting}[gobble=4]
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3810
    `\$` `\textbf{cat /sys/ethercat0/info}`
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3811
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3812
    Mode: IDLE
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3813
    Slaves: 9
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3814
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3815
    Timing (min/avg/max) [us]:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3816
      Idle cycle: 4 / 4.38 / 34
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3817
      EoE cycle: 9 / 11.91 / 23
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3818
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3819
    EoE statistics (RX/TX) [bps]:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3820
      eoe0: 0 / 3184
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3821
  \end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3822
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3823
  The mode can be \textit{ORPHANED}, \textit{IDLE} or
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3824
  \textit{OPERATION}. The other parameters are self-explanatory.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3825
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3826
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3827
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3828
\subsubsection{Domain Attributes}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3829
\label{sec:sysfs-domain}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3830
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3831
In operation mode, each created domain is represented as a directory
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3832
\textit{domainX}, where X is the domain index. Below is a listing of
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3833
the domain directory contents:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3834
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3835
\begin{lstlisting}
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3836
  `\$` `\textbf{ls /sys/ethercat0/domain0}`
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3837
  image_size
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3838
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3839
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3840
The domain directories currently only export the domain's image size.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3841
It is planned to export the whole process data mapping for debugging
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3842
purposes.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3843
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3844
\subsubsection{Slave Attributes}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3845
\label{sec:sysfs-slave}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3846
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3847
Each slave on the bus is represented in its own directory
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3848
\textit{slaveXXX}, where XXX is the slave's 3-digit ring position in
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3849
the EtherCAT bus. Below is a listing of a slave directory:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3850
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3851
\begin{lstlisting}
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3852
  `\$` `\textbf{ls /sys/ethercat0/slave003}`
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3853
  eeprom  info  state
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3854
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3855
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3856
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3857
\item[eeprom] (read/write) See section~\ref{sec:eepromaccess} for how
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3858
  to use this attribute.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3859
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3860
\item[info] (read only) This attribute contains a bunch of information
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3861
  about the slave. Below is an example output:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3862
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3863
  \begin{lstlisting}[gobble=4]
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3864
    `\$` `\textbf{cat /sys/ethercat0/slave003/info}`
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3865
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3866
    Name: EL4132 2K. Ana. Ausgang +/-10V
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3867
    Vendor ID: 0x00000002
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3868
    Product code: 0x10243052
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3869
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3870
    State: INIT
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3871
    Ring position: 3
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3872
    Advanced position: 1:3
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3873
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3874
    Data link status:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3875
      Port 0 (EBUS) Link down, Loop open, Signal detected
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3876
      Port 1 (EBUS) Link down, Loop open, Signal detected
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3877
      Port 2 (EBUS) Link down, Loop closed, No signal
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3878
      Port 3 (EBUS) Link down, Loop closed, No signal
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3879
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3880
    Mailboxes:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3881
      RX mailbox: 0x1800/246, TX mailbox: 0x18F6/246
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3882
      Supported protocols: CoE, FoE
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3883
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3884
    SII data:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3885
      Group: AnaOut
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3886
      Image: TERM_AO
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3887
      Order#: EL4132
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3888
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3889
    Sync-Managers:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3890
      0: 0x1800, length 246, control 0x26, enable
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3891
      1: 0x18F6, length 246, control 0x22, enable
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3892
      2: 0x1000, length 0, control 0x24, enable
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3893
      3: 0x1100, length 0, control 0x20, enable
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3894
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  3895
    Pdos:
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3896
      RXPDO "Channel 1" (0x1600), Sync-Manager 2
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3897
        "Output" 0x6411:1, 16 bit
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3898
      RXPDO "Channel 2" (0x1601), Sync-Manager 2
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3899
        "Output" 0x6411:2, 16 bit
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3900
  \end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3901
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3902
  This is nearly all of the SII category information needed to
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3903
  configure the slave, supplemented with state and addressing
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3904
  information.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3905
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3906
\item[state] (read/write) This attribute contains the slave's state.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3907
  It can be read or written:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3908
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3909
  \begin{lstlisting}[gobble=4]
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3910
    # `\textbf{cat /sys/ethercat0/slave003/state}`
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3911
    OP
813
bfc3f1ab52de Fixed typo SAVEOP -> SAFEOP.
Florian Pose <fp@igh-essen.com>
parents: 487
diff changeset
  3912
    # `\textbf{echo SAFEOP > /sys/ethercat0/slave003/state}`
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3913
  \end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3914
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3915
  This command should also be receipted with a syslog message:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3916
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3917
  \begin{lstlisting}[gobble=4]
813
bfc3f1ab52de Fixed typo SAVEOP -> SAFEOP.
Florian Pose <fp@igh-essen.com>
parents: 487
diff changeset
  3918
    EtherCAT: Accepted new state SAFEOP for slave 3.
bfc3f1ab52de Fixed typo SAVEOP -> SAFEOP.
Florian Pose <fp@igh-essen.com>
parents: 487
diff changeset
  3919
    EtherCAT: Changing state of slave 3 from OP to SAFEOP.
bfc3f1ab52de Fixed typo SAVEOP -> SAFEOP.
Florian Pose <fp@igh-essen.com>
parents: 487
diff changeset
  3920
    EtherCAT: Slave states: INIT, SAFEOP, OP.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3921
  \end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3922
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3923
  After the new requested state was accepted from user space, the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3924
  operation state machine (see section~\ref{sec:fsm-op}) or the idle
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3925
  state machine (section~\ref{sec:fsm-idle}) notices, that the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3926
  requested slave state differs from the current one, and therefore
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3927
  executes the slave configuration state machine, until the slave has
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3928
  reached the requested state.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3929
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3930
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3931
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3932
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3933
\subsubsection{E$^2$PROM Access}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3934
\label{sec:eepromaccess}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3935
\index{E$^2$PROM!Access}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3936
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3937
It is possible to directly read or write the complete E$^2$PROM
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3938
contents of the slaves. This was introduced for the reasons below:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3939
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3940
\begin{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3941
\item The format of the E$^2$PROM data is still in development and
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3942
  categories can be added in the future. With read and write access,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3943
  the complete memory contents can be easily backed up and restored.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3944
\item Some E$^2$PROM data fields have to be altered (like the alias
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3945
  address). A quick writing must be possible for that.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3946
\item Through read access, analyzing category data is possible from
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3947
  user space.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3948
\end{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3949
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3950
Reading out E$^2$PROM data is as easy as reading other
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3951
attributes. Though the data are in binary format, analyzation is
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3952
easier with a tool like \textit{hexdump}:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3953
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3954
\begin{lstlisting}
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3955
  `\$` `\textbf{cat /sys/ethercat0/slave003/eeprom | hexdump}`
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3956
  0000000 0103 0000 0000 0000 0000 0000 0000 008c
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3957
  0000010 0002 0000 3052 07f0 0000 0000 0000 0000
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3958
  0000020 0000 0000 0000 0000 0000 0000 0000 0000
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3959
  ...
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3960
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3961
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3962
Backing up E$^2$PROM contents gets as easy as copying a file:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3963
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3964
\begin{lstlisting}
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3965
  `\$` `\textbf{cp /sys/ethercat0/slave003/eeprom slave003.eep}`
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3966
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3967
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3968
Writing access is only possible as \textit{root}. Moreover writing has
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3969
to be explicitly enabled and is only allowed in idle mode. This is a
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3970
safety measure, because without the correct memory contents, a slave
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3971
is unusable. Writing E$^2$PROM contents in operation mode is not
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3972
provided yet.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3973
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3974
E$^2$PROM writing is enabled with the command below:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3975
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3976
\begin{lstlisting}
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3977
  # `\textbf{echo 1 > /sys/ethercat0/eeprom\_write\_enable}`
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3978
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3979
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3980
The success can be seen in the syslog messages again:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3981
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3982
\begin{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3983
  EtherCAT: Slave EEPROM writing enabled.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3984
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3985
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3986
Now, it is possible to write E$^2$PROM contents to a slave. The master
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3987
will accept data through the \textit{eeprom} file and will perform a
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3988
short validation of the contents, before starting the write operation.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3989
This validation checks the complete size and the category headers.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3990
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3991
\begin{lstlisting}
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3992
  # `\textbf{cat slave003.eep > /sys/ethercat0/slave003/eeprom}`
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3993
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3994
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3995
The write operation can take a few seconds.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3996
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3997
\begin{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3998
  EtherCAT: EEPROM writing scheduled for slave 3, 88 words.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3999
  EtherCAT: Writing EEPROM of slave 3...
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4000
  EtherCAT: Finished writing EEPROM of slave 3.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4001
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4002
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4003
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4004
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4005
\subsection{User Space Tools}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4006
\index{User space!Tools}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4007
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4008
There is a user space tool called \textit{lsec}\index{lsec} (``List
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4009
EtherCAT'') to visualize the EtherCAT bus. Running it usually results
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4010
in an output like this:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4011
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4012
\begin{lstlisting}
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  4013
  `\$` `\textbf{lsec}`
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4014
  EtherCAT bus listing for master 0:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4015
     0  1:0  OP      EK1100 Ethernet Kopplerklemme (2A E-Bus)
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4016
     1  1:1  INIT    EL4132 2K. Ana. Ausgang +/-10V
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4017
     2  1:2  INIT    EL4132 2K. Ana. Ausgang +/-10V
813
bfc3f1ab52de Fixed typo SAVEOP -> SAFEOP.
Florian Pose <fp@igh-essen.com>
parents: 487
diff changeset
  4018
     3  1:3  SAFEOP  EL4132 2K. Ana. Ausgang +/-10V
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4019
     4  1:4  INIT    EL5101 Incremental Encoder Interface
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4020
     5  1:5  INIT    EL1014 4K. Dig. Eingang 24V, 10s
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4021
     6  1:6  OP      EL6601 1 Port Switch (Ethernet, CoE)
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4022
     7  1:7  INIT    EL5101 Incremental Encoder Interface
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4023
     8  1:8  INIT    EL5001 1K. SSI Encoder
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4024
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4025
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4026
Every slave is displayed as one text row. The first column shows its
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4027
ring position, the second displays the ``advanced position address''
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4028
(see section~\ref{sec:addr}) and the third column displays the current
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4029
slave state. The last column is the slave's name, as it appears in the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4030
``general'' E$^2$PROM category.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4031
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4032
The lsec program is a Perl script, that evaluates the Sysfs
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4033
\textit{info} attributes of the slaves (see
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4034
section~\ref{sec:sysfs-slave}). This is done for master $0$ by
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4035
default, but the master index can be specified via command line:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4036
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4037
\begin{lstlisting}
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  4038
  `\$` `\textbf{lsec -h}`
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4039
  Usage: ec_list [OPTIONS]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4040
          -m <IDX>    Query master <IDX>.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4041
          -h          Show this help.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4042
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4043
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4044
This script has proved as useful for troubleshooting: If it displays
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4045
slaves, the master is up and running, and the bus connection is
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4046
present, too. It is also useful when building up a bus: It can verify
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4047
the list of slaves and help to create a process data image (see
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4048
chapter~\ref{chapter:usage}).
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4049
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4050
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4051
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4052
\subsection{System Integration}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4053
\label{sec:system}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4054
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4055
To integrate the EtherCAT master into a running system, it has to be
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4056
guaranteed, that it is started on system startup. In addition, there has
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4057
to be a persistent configuration, that is also applied on startup.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4058
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4059
\subsubsection{The EtherCAT Init Script}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4060
\label{sec:init}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4061
\index{Init script}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4062
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4063
The EtherCAT master provides an ``init script'', that conforms to the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4064
requirements of the ``Linux Standard Base'' (LSB\index{LSB},
374
e43a29f9079e Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents: 371
diff changeset
  4065
\cite{lsb}). The script is installed to \textit{etc/init.d/ethercat}
e43a29f9079e Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents: 371
diff changeset
  4066
below the installation prefix and has to be copied to the appropriate
e43a29f9079e Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents: 371
diff changeset
  4067
location (see section~\ref{sec:make}), before the master can be
e43a29f9079e Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents: 371
diff changeset
  4068
inserted as a service. The different Linux distributions offer
e43a29f9079e Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents: 371
diff changeset
  4069
different ways to mark the service for starting and stopping in
e43a29f9079e Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents: 371
diff changeset
  4070
certain runlevels (for example, SUSE Linux provides the
e43a29f9079e Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents: 371
diff changeset
  4071
\textit{insserv} command).
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4072
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4073
To provide service dependencies (i.~e. which services have to be
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4074
started before) right inside the init script code, LSB defines a
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4075
special comment block. System tools can extract this information to
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4076
insert the EtherCAT init script at the correct place in the startup
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4077
sequence:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4078
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4079
\begin{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4080
  ### BEGIN INIT INFO
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4081
  # Provides:          ethercat
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4082
  # Required-Start:    $local_fs $syslog $network
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4083
  # Should-Start:      $time
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4084
  # Required-Stop:     $local_fs $syslog $network
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4085
  # Should-Stop:       $time
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4086
  # Default-Start:     3 5
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4087
  # Default-Stop:      0 1 2 6
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4088
  # Short-Description: EtherCAT master modules
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4089
  # Description:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4090
  ### END INIT INFO
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4091
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4092
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4093
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
  4094
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
  4095
\texttt{start}, \texttt{stop}, \texttt{restart} or \texttt{status}.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4096
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4097
\begin{lstlisting}
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  4098
  # `\textbf{/etc/init.d/ethercat restart}`
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4099
  Shutting down EtherCAT master                done
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4100
  Starting EtherCAT master                     done
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4101
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4102
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4103
\subsubsection{The EtherCAT Sysconfig File}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4104
\label{sec:sysconfig}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4105
\index{Sysconfig file}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4106
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4107
For persistent configuration, the init script uses a sysconfig file
374
e43a29f9079e Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents: 371
diff changeset
  4108
installed to \textit{etc/sysconfig/ethercat} (below the installation
e43a29f9079e Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents: 371
diff changeset
  4109
prefix), that is mandatory for the init script. The sysconfig file
e43a29f9079e Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents: 371
diff changeset
  4110
contains all configuration variables needed to operate a master:
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4111
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4112
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4113
\item[DEVICE\_INDEX] This variable must contain the PCI index of the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4114
  EtherCAT device.  Setting this is mandatory for the EtherCAT init
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4115
  script. Default: $-1$
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4116
\item[EOE\_INTERFACES] The number of virtual Ethernet-over-EtherCAT
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4117
  interfaces, every master creates on startup. See
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4118
  section~\ref{sec:eoeimp}. Default: $0$
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4119
\item[EOE\_BRIDGE] If this variable is set, all EoE interfaces will be
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4120
  added to a network bridge according to IEEE 802.1D after master
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4121
  startup. The variable must contain the name of the bridge. To use
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4122
  this functionality, the kernel must be configured with the
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  4123
  CONFIG\_BRIDGE option and the \textit{bridge-utils} package must be
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  4124
  installed (i.~e. the \textit{brctl} command is needed).
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4125
\item[EOE\_IP\_ADDRESS] The IP address of the EoE bridge. Setting this
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  4126
  together with \$EOE\_IP\_NETMASK will let the local host communicate
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  4127
  with devices on the EoE bridge.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4128
\item[EOE\_IP\_NETMASK] IP netmask of the EoE bridge.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4129
\item[EOE\_EXTRA\_INTERFACES] The list of extra interfaces to include
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4130
  in the EoE brid\-ge. Set this to interconnect the EoE bridge with
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  4131
  other local interfaces. If \$EOE\_\-BRIDGE is empty or undefined,
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  4132
  setting this variable has no effect. Important: The IP address of
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  4133
  the listed interfaces will be cleared. Setting
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  4134
  \$EOE\_\-IP\_\-ADDRESS and \$EOE\_IP\_NETMASK will re-enable them
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  4135
  for IP traffic.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4136
\item[EOE\_GATEWAY] The IP address of the default gateway. If this
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4137
  variable is set, the gateway will be renewed after bridge
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4138
  installation. This is necessary, if the default gateway's interface
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  4139
  is one of the \$EOE\_EXTRA\_INTERFACES.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4140
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4141
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4142
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4143
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4144
\subsection{Monitoring and Debugging}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4145
\label{sec:debug}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4146
\index{Monitoring}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4147
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4148
For debugging purposes, every EtherCAT master registeres a read-only
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4149
network interface \textit{ecX}, where X is a number, provided by the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4150
kernel on device registration. While it is ``up'', the master forwards
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4151
every frame sent and received to this interface.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4152
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4153
This makes it possible to connect an network monitor (like Wireshark
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4154
or tcpdump) to the debug interface and monitor the EtherCAT frames.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4155
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4156
It has to be considered, that can be frame rate can be very high. The
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4157
idle state machine usually runs every kernel timer interrupt (up to
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4158
$1$~kHz) and with a connected realtime module, the rate can be even
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4159
higher.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4160
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4161
\paragraph{Attention:} The socket buffers needed for the operation of
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4162
the debugging interface have to be allocated dynamically. Some Linux
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4163
realtime extensions do not allow this in realtime context!
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4164
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4165
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4166
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4167
\section{Timing Aspects}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4168
\label{sec:timing}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4169
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4170
Although EtherCAT's timing is highly deterministic and therefore
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4171
timing issues are rare, there are a few aspects that can (and should
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4172
be) dealt with.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4173
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4174
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4175
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4176
\subsection{Realtime Interface Profiling}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4177
\label{sec:timing-profile}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4178
\index{Realtime!Profiling}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4179
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4180
One of the most important timing aspects are the runtimes of the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4181
realtime interface functions, that are called in cyclic context. These
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4182
functions make up an important part of the overall timing of the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4183
realtime module. To measure the timing of the functions, the following
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4184
code was used:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4185
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4186
\begin{lstlisting}[gobble=2,language=C]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4187
  c0 = get_cycles();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4188
  ecrt_master_receive(master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4189
  c1 = get_cycles();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4190
  ecrt_domain_process(domain1);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4191
  c2 = get_cycles();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4192
  ecrt_master_run(master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4193
  c3 = get_cycles();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4194
  ecrt_master_send(master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4195
  c4 = get_cycles();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4196
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4197
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4198
Between each call of an interface function, the CPU timestamp counter
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4199
is read. The counter differences are converted to microseconds with
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4200
help of the \textit{cpu\_khz} variable, that contains the number of
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4201
increments per millisecond.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4202
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4203
For the actual measuring, a system with a $2.0$~GHz CPU was used, that
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4204
ran the above code in an RTAI thread with a cycle time of $100$
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4205
\textmu s.  The measuring was repeated $n = 100$ times and the results
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4206
were averaged. These can be seen in table~\ref{tab:profile}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4207
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4208
\begin{table}[htpb]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4209
  \centering
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4210
  \caption{Profiling of a Realtime Cycle on a $2.0$~GHz Processor}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4211
  \label{tab:profile}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4212
  \vspace{2mm}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4213
  \begin{tabular}{l|r|r}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4214
    Element & Mean Duration [\textmu s] & Standard Deviancy [\textmu s] \\
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4215
    \hline
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4216
    \textit{ecrt\_master\_receive()} & 8.04 & 0.48\\
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4217
    \textit{ecrt\_domain\_process()} & 0.14 & 0.03\\
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4218
    \textit{ecrt\_master\_run()} & 0.29 & 0.12\\
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4219
    \textit{ecrt\_master\_send()} & 2.18 & 0.17\\ \hline
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4220
    Complete Cycle & 10.65 & 0.69\\ \hline
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4221
  \end{tabular}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4222
\end{table}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4223
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4224
It is obvious, that the the functions accessing hardware make up the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4225
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
  4226
the Ethernet device, analyzes datagrams and copies their contents into
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4227
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
  4228
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
  4229
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
  4230
receiving time.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4231
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4232
The functions that only operate on the masters internal data
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4233
structures are very fast ($\Delta t < 1$~\textmu s). Interestingly the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4234
runtime of \textit{ec\_domain\_process()} has a small standard
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4235
deviancy relative to the mean value, while this ratio is about twice
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4236
as big for \textit{ec\_master\_run()}: This probably results from the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4237
latter function having to execute code depending on the current state
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4238
and the different state functions are more or less complex.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4239
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4240
For a realtime cycle makes up about $10$~\textmu s, the theoretical
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4241
frequency can be up to $100$~kHz. For two reasons, this frequency
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4242
keeps being theoretical:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4243
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4244
\begin{enumerate}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4245
\item The processor must still be able to run the operating system
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4246
  between the realtime cycles.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4247
\item The EtherCAT frame must be sent and received, before the next
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4248
  realtime cycle begins. The determination of the bus cycle time is
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4249
  difficult and covered in section~\ref{sec:timing-bus}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4250
\end{enumerate}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4251
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4252
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4253
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4254
\subsection{Bus Cycle Measuring}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4255
\label{sec:timing-bus}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4256
\index{Bus cycle}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4257
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4258
For measuring the time, a frame is ``on the wire'', two timestamps
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4259
must be be taken:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4260
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4261
\begin{enumerate}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4262
\item The time, the Ethernet hardware begins with physically sending
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4263
  the frame.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4264
\item The time, the frame is completely received by the Ethernet
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4265
  hardware.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4266
\end{enumerate}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4267
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4268
Both times are difficult to determine. The first reason is, that the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4269
interrupts are disabled and the master is not notified, when a frame
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4270
is sent or received (polling would distort the results). The second
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4271
reason is, that even with interrupts enabled, the time from the event
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4272
to the notification is unknown. Therefore the only way to confidently
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4273
determine the bus cycle time is an electrical measuring.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4274
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4275
Anyway, the bus cycle time is an important factor when designing
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4276
realtime code, because it limits the maximum frequency for the cyclic
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4277
part of the realtime module. In practice, these timing parameters are
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4278
highly dependent on the hardware and often a trial and error method
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4279
must be used to determine the limits of the system.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4280
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4281
The central question is: What happens, if the cycle frequency is too
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4282
high? The answer is, that the EtherCAT frames that have been sent at
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4283
the end of the cycle are not yet received, when the next cycle starts.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4284
First this is noticed by \textit{ecrt\_domain\_process()}, because the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4285
working counter of the process data datagrams were not increased. The
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4286
function will notify the user via syslog\footnote{To limit syslog
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4287
  output, a mechanism has been implementet, that outputs a summarized
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4288
  notification at maximum once a second.}. In this case, the process
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4289
data keeps being the same as in the last cycle, because it is not
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4290
erased by the domain. When the domain datagrams are queued again, the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4291
master notices, that they are already queued (and marked as sent). The
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4292
master will mark them as unsent again and output a warning, that
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4293
datagrams were ``skipped''.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4294
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4295
On the mentioned $2.0$~GHz system, the possible cycle frequency can be
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4296
up to $25$~kHz without skipped frames. This value can surely be
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4297
increased by choosing faster hardware. Especially the RealTek network
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4298
hardware could be replaced by a faster one. Besides, implementing a
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4299
dedicated ISR for EtherCAT devices would also contribute to increasing
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4300
the latency. These are two points on the author's to-do list.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4301
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4302
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4303
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4304
\chapter{Using the EtherCAT Master}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4305
\label{chapter:usage}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4306
\index{Master!Usage}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4307
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4308
This chapter will give practical examples of how to use the EtherCAT
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4309
master via the realtime interface by writing a realtime module.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4310
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4311
Section~\ref{sec:make} shows how to compile and install the master,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4312
while the sections~\ref{sec:mini} to~\ref{sec:concurrency} give
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4313
examples for different realtime modules.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4314
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4315
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4316
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4317
\section{Compiling and Installing}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4318
\label{sec:make}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4319
\index{Master!Compilation}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4320
376
d1441d87f5c1 Documentation: EtherLab-CD; obtaining the DEVICE_INDEX.
Florian Pose <fp@igh-essen.com>
parents: 374
diff changeset
  4321
The current EtherCAT master code is available at~\cite{etherlab} or
d1441d87f5c1 Documentation: EtherLab-CD; obtaining the DEVICE_INDEX.
Florian Pose <fp@igh-essen.com>
parents: 374
diff changeset
  4322
can be obtained from the EtherLab\textsuperscript{\textregistered} CD.
487
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
  4323
The \textit{tar.bz2} file has to be unpacked with the commands below
376
d1441d87f5c1 Documentation: EtherLab-CD; obtaining the DEVICE_INDEX.
Florian Pose <fp@igh-essen.com>
parents: 374
diff changeset
  4324
(or similar):
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4325
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4326
\begin{lstlisting}
487
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
  4327
  `\$` `\textbf{tar xjf ethercat-\masterversion.tar.bz2}`
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
  4328
  `\$` `\textbf{cd ethercat-\masterversion/}`
374
e43a29f9079e Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents: 371
diff changeset
  4329
\end{lstlisting}
e43a29f9079e Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents: 371
diff changeset
  4330
e43a29f9079e Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents: 371
diff changeset
  4331
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
  4332
follows the below commands:
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4333
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4334
\begin{lstlisting}
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  4335
  `\$` `\textbf{./configure}`
487
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
  4336
  `\$` `\textbf{make modules}`
374
e43a29f9079e Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents: 371
diff changeset
  4337
\end{lstlisting}
e43a29f9079e Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents: 371
diff changeset
  4338
e43a29f9079e Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents: 371
diff changeset
  4339
The default installation prefix is \textit{/opt/etherlab}. It can be
e43a29f9079e Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents: 371
diff changeset
  4340
changed with the \texttt{--prefix} argument.
e43a29f9079e Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents: 371
diff changeset
  4341
e43a29f9079e Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents: 371
diff changeset
  4342
Linux kernel sources are needed for compilation\footnote{If a realtime
e43a29f9079e Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents: 371
diff changeset
  4343
  extension shall to be used, the kernel should be patched before
e43a29f9079e Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents: 371
diff changeset
  4344
  compiling the EtherCAT master.}. To compile the EtherCAT master
e43a29f9079e Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents: 371
diff changeset
  4345
modules for a different kernel than the running kernel, the target
e43a29f9079e Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents: 371
diff changeset
  4346
kernel version can be specified with the \texttt{--with-linux}
e43a29f9079e Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents: 371
diff changeset
  4347
argument. Example:
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4348
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4349
\begin{lstlisting}
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  4350
  `\$` `\textbf{./configure --with-linux="2.6.17-ipipe"}`
487
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
  4351
  `\$` `\textbf{make modules}`
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
  4352
\end{lstlisting}
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
  4353
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
  4354
The below commands have to be entered as \textit{root}: The first one
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
  4355
will install the kernel modules to the kernel's modules directory. The
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
  4356
second one will install EtherCAT headers, the init script, the
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
  4357
sysconfig file and the user space tools to the prefix path.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4358
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4359
\begin{lstlisting}
487
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
  4360
  # `\textbf{make modules\_install}`
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  4361
  # `\textbf{make install}`
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4362
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4363
487
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
  4364
If the target kernel's modules directory is not under
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
  4365
\textit{/lib/modules}, a different destination directory can be
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
  4366
specified with the \textit{DESTDIR} make variable. For example:
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
  4367
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
  4368
\begin{lstlisting}
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
  4369
  # `\textbf{make DESTDIR=/vol/nfs/root modules\_install}`
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
  4370
\end{lstlisting}
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
  4371
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
  4372
This command will install the compiled kernel modules to
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
  4373
\textit{/vol/nfs/root/lib/modules}, prepended by the kernel release.
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
  4374
376
d1441d87f5c1 Documentation: EtherLab-CD; obtaining the DEVICE_INDEX.
Florian Pose <fp@igh-essen.com>
parents: 374
diff changeset
  4375
If the EtherCAT master shall be run as a service
d1441d87f5c1 Documentation: EtherLab-CD; obtaining the DEVICE_INDEX.
Florian Pose <fp@igh-essen.com>
parents: 374
diff changeset
  4376
(recommended\footnote{Even if the EtherCAT master shall not be loaded
d1441d87f5c1 Documentation: EtherLab-CD; obtaining the DEVICE_INDEX.
Florian Pose <fp@igh-essen.com>
parents: 374
diff changeset
  4377
  on system startup, the use of the init script is recommended for
d1441d87f5c1 Documentation: EtherLab-CD; obtaining the DEVICE_INDEX.
Florian Pose <fp@igh-essen.com>
parents: 374
diff changeset
  4378
  manual (un-)loading.}), the init script and the sysconfig file have
d1441d87f5c1 Documentation: EtherLab-CD; obtaining the DEVICE_INDEX.
Florian Pose <fp@igh-essen.com>
parents: 374
diff changeset
  4379
to be copied to the appropriate locations. The below example is
d1441d87f5c1 Documentation: EtherLab-CD; obtaining the DEVICE_INDEX.
Florian Pose <fp@igh-essen.com>
parents: 374
diff changeset
  4380
suitable for SUSE Linux.  It may vary for other distributions.
374
e43a29f9079e Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents: 371
diff changeset
  4381
e43a29f9079e Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents: 371
diff changeset
  4382
\begin{lstlisting}
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  4383
  # `\textbf{cd /opt/etherlab}`
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  4384
  # `\textbf{cp etc/sysconfig/ethercat /etc/sysconfig/}`
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  4385
  # `\textbf{cp etc/init.d/ethercat /etc/init.d/}`
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  4386
  # `\textbf{insserv ethercat}`
374
e43a29f9079e Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents: 371
diff changeset
  4387
\end{lstlisting}
e43a29f9079e Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents: 371
diff changeset
  4388
376
d1441d87f5c1 Documentation: EtherLab-CD; obtaining the DEVICE_INDEX.
Florian Pose <fp@igh-essen.com>
parents: 374
diff changeset
  4389
Now the sysconfig file \texttt{/etc/sysconfig/ethercat} (see
d1441d87f5c1 Documentation: EtherLab-CD; obtaining the DEVICE_INDEX.
Florian Pose <fp@igh-essen.com>
parents: 374
diff changeset
  4390
section~\ref{sec:sysconfig}) has to be customized: This is mainly done
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  4391
by uncommenting and adjusting the \$DEVICE\_INDEX variable. It has to
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  4392
be set to the index of the compatible network device to use with
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  4393
EtherCAT, where the order of devices is dependent on their position in
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  4394
the PCI bus:
376
d1441d87f5c1 Documentation: EtherLab-CD; obtaining the DEVICE_INDEX.
Florian Pose <fp@igh-essen.com>
parents: 374
diff changeset
  4395
d1441d87f5c1 Documentation: EtherLab-CD; obtaining the DEVICE_INDEX.
Florian Pose <fp@igh-essen.com>
parents: 374
diff changeset
  4396
\begin{lstlisting}[numbers=left,basicstyle=\ttfamily\scriptsize]
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  4397
  # `\textbf{lspci}`
376
d1441d87f5c1 Documentation: EtherLab-CD; obtaining the DEVICE_INDEX.
Florian Pose <fp@igh-essen.com>
parents: 374
diff changeset
  4398
  00:00.0 Host bridge: VIA Technologies, Inc. VT8363/8365 [KT133/KM133] (rev 03)
d1441d87f5c1 Documentation: EtherLab-CD; obtaining the DEVICE_INDEX.
Florian Pose <fp@igh-essen.com>
parents: 374
diff changeset
  4399
  00:01.0 PCI bridge: VIA Technologies, Inc. VT8363/8365 [KT133/KM133 AGP]
d1441d87f5c1 Documentation: EtherLab-CD; obtaining the DEVICE_INDEX.
Florian Pose <fp@igh-essen.com>
parents: 374
diff changeset
  4400
  00:04.0 ISA bridge: VIA Technologies, Inc. VT82C686 [Apollo Super South] (rev 40)
d1441d87f5c1 Documentation: EtherLab-CD; obtaining the DEVICE_INDEX.
Florian Pose <fp@igh-essen.com>
parents: 374
diff changeset
  4401
  00:04.1 IDE interface: VIA Technologies, Inc. VT82C586A/B/VT82C686/A/B/VT823x/A/C...
d1441d87f5c1 Documentation: EtherLab-CD; obtaining the DEVICE_INDEX.
Florian Pose <fp@igh-essen.com>
parents: 374
diff changeset
  4402
  00:04.2 USB Controller: VIA Technologies, Inc. VT82xxxxx UHCI USB 1.1 Controller...
d1441d87f5c1 Documentation: EtherLab-CD; obtaining the DEVICE_INDEX.
Florian Pose <fp@igh-essen.com>
parents: 374
diff changeset
  4403
  00:04.3 USB Controller: VIA Technologies, Inc. VT82xxxxx UHCI USB 1.1 Controller...
d1441d87f5c1 Documentation: EtherLab-CD; obtaining the DEVICE_INDEX.
Florian Pose <fp@igh-essen.com>
parents: 374
diff changeset
  4404
  00:04.4 Bridge: VIA Technologies, Inc. VT82C686 [Apollo Super ACPI] (rev 40)
d1441d87f5c1 Documentation: EtherLab-CD; obtaining the DEVICE_INDEX.
Florian Pose <fp@igh-essen.com>
parents: 374
diff changeset
  4405
  00:09.0 Ethernet controller: D-Link System Inc RTL8139 Ethernet (rev 10)
d1441d87f5c1 Documentation: EtherLab-CD; obtaining the DEVICE_INDEX.
Florian Pose <fp@igh-essen.com>
parents: 374
diff changeset
  4406
  00:0a.0 Ethernet controller: Intel Corporation 82557/8/9 [Ethernet Pro 100] (rev 08)
d1441d87f5c1 Documentation: EtherLab-CD; obtaining the DEVICE_INDEX.
Florian Pose <fp@igh-essen.com>
parents: 374
diff changeset
  4407
  00:0b.0 Ethernet controller: D-Link System Inc RTL8139 Ethernet (rev 10)
d1441d87f5c1 Documentation: EtherLab-CD; obtaining the DEVICE_INDEX.
Florian Pose <fp@igh-essen.com>
parents: 374
diff changeset
  4408
  00:0c.0 VGA compatible controller: ATI Technologies Inc Rage XL (rev 27)
d1441d87f5c1 Documentation: EtherLab-CD; obtaining the DEVICE_INDEX.
Florian Pose <fp@igh-essen.com>
parents: 374
diff changeset
  4409
  00:11.0 Unknown mass storage controller: Promise Technology, Inc. PDC20265...
d1441d87f5c1 Documentation: EtherLab-CD; obtaining the DEVICE_INDEX.
Florian Pose <fp@igh-essen.com>
parents: 374
diff changeset
  4410
\end{lstlisting}
d1441d87f5c1 Documentation: EtherLab-CD; obtaining the DEVICE_INDEX.
Florian Pose <fp@igh-essen.com>
parents: 374
diff changeset
  4411
d1441d87f5c1 Documentation: EtherLab-CD; obtaining the DEVICE_INDEX.
Florian Pose <fp@igh-essen.com>
parents: 374
diff changeset
  4412
In the above output of the \textit{lspci} command, two compatible
d1441d87f5c1 Documentation: EtherLab-CD; obtaining the DEVICE_INDEX.
Florian Pose <fp@igh-essen.com>
parents: 374
diff changeset
  4413
network devices can be found in lines~\textcircled{\tiny 9} and
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  4414
\textcircled{\tiny 11}. The \$DEVICE\_INDEX variable should be set to
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  4415
$0$ or $1$, respectively.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4416
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4417
After the basic configuration is done, the master can be started with
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4418
the below command:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4419
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4420
\begin{lstlisting}
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  4421
  # `\textbf{/etc/init.d/ethercat start}`
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4422
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4423
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4424
The operation of the master can be observed by looking at the
374
e43a29f9079e Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents: 371
diff changeset
  4425
syslog\index{syslog} messages, which should look like the ones below.
e43a29f9079e Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents: 371
diff changeset
  4426
If EtherCAT slaves are connected to the master's EtherCAT device, the
e43a29f9079e Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents: 371
diff changeset
  4427
activity indicators should begin to flash.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4428
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4429
\begin{lstlisting}[numbers=left]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4430
  EtherCAT: Master driver, 1.1 (stable) - rev. 513,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4431
      compiled by fp at Aug 09 2006 10:23:20
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4432
  EtherCAT: Initializing 1 EtherCAT master(s)...
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4433
  EtherCAT: Initializing master 0.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4434
  EtherCAT: Master driver initialized.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4435
  ec_8139too Fast Ethernet driver 0.9.27 Revision 513,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4436
      compiled by fp at Aug 09 2006 10:23:20
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4437
  ec_device_index is 0
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4438
  ACPI: PCI Interrupt 0000:01:00.0[A] -> Link [LNKC]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4439
      -> GSI 11 (level, low) -> IRQ 11
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4440
  ec0: RealTek RTL8139 at 0xd047c000, 00:c0:26:00:c6:aa, IRQ 11
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4441
  ec0:  Identified 8139 chip type 'RTL-8100B/8139D'
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4442
  Registering EtherCAT device...
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4443
  Starting EtherCAT device...
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4444
  EtherCAT: Link state changed to UP.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4445
  EtherCAT: Starting Idle mode.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4446
  EtherCAT: 11 slaves responding.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4447
  EtherCAT: Slave states: INIT, OP.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4448
  EtherCAT: Scanning bus.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4449
  EtherCAT: Bus scanning completed.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4450
  EtherCAT: No EoE handlers coupled.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4451
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4452
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4453
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4454
\item[\normalfont\textcircled{\tiny 1}] The master module is loaded,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4455
  and one master is initialized.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4456
\item[\normalfont\textcircled{\tiny 6}] The EtherCAT-capable RTL8139
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4457
  device driver is loaded. It connects its first network device to the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4458
  master.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4459
\item[\normalfont\textcircled{\tiny 16}] The master starts idle mode
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4460
  and begins scanning the bus for slaves.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4461
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4462
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4463
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4464
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4465
\section{A Minimal Example Module}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4466
\label{sec:mini}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4467
\index{Examples!Minimal}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4468
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4469
This section will explain the usage of the EtherCAT master from a
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4470
minimal kernel module. The complete module code is obtainable as a
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4471
part of the EtherCAT master code release (see~\cite{etherlab}, file
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4472
\textit{examples/mini/mini.c}).
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4473
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4474
The minimal example uses a kernel timer (software interrupt) to handle
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4475
cyclic code. After the timer function is executed, it re-adds itself
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4476
with a delay of one \textit{jiffy}\index{jiffies}, which results in a
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4477
timer frequency of \textit{HZ}\nomenclature{HZ}{Kernel macro
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4478
  containing the timer interrupt frequency}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4479
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4480
The module-global variables, needed to operate the master can be seen
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4481
in listing~\ref{lst:minivar}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4482
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4483
\begin{lstlisting}[language=C,numbers=left,caption={Minimal
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4484
    variables},label=lst:minivar]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4485
  struct timer_list timer;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4486
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4487
  ec_master_t *master = NULL;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4488
  ec_domain_t *domain1 = NULL;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4489
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4490
  void *r_dig_in, *r_ana_out;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4491
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4492
  ec_pdo_reg_t domain1_pdos[] = {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4493
          {"1", Beckhoff_EL1014_Inputs, &r_dig_in},
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4494
          {"2", Beckhoff_EL4132_Ouput1, &r_ana_out},
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4495
          {}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4496
  };
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4497
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4498
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4499
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4500
\item[\normalfont\textcircled{\tiny 1}] There is a timer object
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4501
  declared, that is needed to tell the kernel to install a timer and
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4502
  execute a certain function, if it runs out. This is done by a
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4503
  variable of the \textit{timer\_list} structure.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4504
\item[\normalfont\textcircled{\tiny 3} -- \textcircled{\tiny 4}] There
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4505
  is a pointer declared, that will later point to a requested EtherCAT
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4506
  master.  Additionally there is a pointer to a domain object needed,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4507
  that will manage process data IO.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4508
\item[\normalfont\textcircled{\tiny 6}] The pointers \textit{r\_*}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4509
  will later point to the \underline{r}aw process data values inside
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4510
  the domain memory. The addresses they point to will be set during a
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4511
  call to \textit{ec\_\-master\_\-activate()}, that will create the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4512
  domain memory and configure the mapped process data image.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4513
\item[\normalfont\textcircled{\tiny 8} -- \textcircled{\tiny 12}] The
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  4514
  configuration of the mapping of certain Pdos in a domain can easily
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4515
  be done with the help of an initialization array of the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4516
  \textit{ec\_pdo\_reg\_t} type, defined as part of the realtime
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4517
  interface. Each record must contain the ASCII bus-address of the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4518
  slave (see section~\ref{sec:addr}), the slave's vendor ID and
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  4519
  product code, and the index and subindex of the Pdo to map (these
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4520
  four fields can be specified in junction, by using one of the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4521
  defines out of the \textit{include/ecdb.h} header). The last field
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4522
  has to be the address of the process data pointer, so it can later
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4523
  be redirected appropriately. Attention: The initialization array
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4524
  must end with an empty record (\textit{\{\}})!
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4525
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4526
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4527
The initialization of the minimal realtime module is done by the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4528
``Minimal init function'' in listing~\ref{lst:miniinit}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4529
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4530
\begin{lstlisting}[language=C,numbers=left,caption={Minimal init
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4531
    function},label={lst:miniinit}]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4532
  int __init init_mini_module(void)
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4533
  {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4534
          if (!(master = ecrt_request_master(0))) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4535
                  goto out_return;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4536
          }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4537
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4538
          if (!(domain1 = ecrt_master_create_domain(master))) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4539
                  goto out_release_master;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4540
          }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4541
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4542
          if (ecrt_domain_register_pdo_list(domain1,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4543
                                            domain1_pdos)) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4544
                  goto out_release_master;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4545
          }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4546
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4547
          if (ecrt_master_activate(master)) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4548
                  goto out_release_master;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4549
          }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4550
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4551
          ecrt_master_prepare(master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4552
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4553
          init_timer(&timer);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4554
          timer.function = run;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4555
          timer.expires = jiffies + 10;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4556
          add_timer(&timer);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4557
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4558
          return 0;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4559
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4560
        out_release_master:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4561
          ecrt_release_master(master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4562
        out_return:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4563
          return -1;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4564
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4565
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4566
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4567
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4568
\item[\normalfont\textcircled{\tiny 3}] It is tried to request the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4569
  first EtherCAT master (index 0). On success, the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4570
  \textit{ecrt\_\-request\_\-master()} function returns a pointer to
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4571
  the reserved master, that can be used as an object to following
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4572
  functions calls. On failure, the function returns \textit{NULL}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4573
\item[\normalfont\textcircled{\tiny 7}] In order to exchange process
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4574
  data, a domain object has to be created. The
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4575
  \textit{ecrt\_\-master\_\-create\_domain()} function also returns a
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4576
  pointer to the created domain, or \textit{NULL} in error case.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4577
\item[\normalfont\textcircled{\tiny 11}] The registration of domain
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  4578
  Pdos with an initialization array results in a single function call.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4579
  Alternatively the data fields could be registered with individual
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4580
  calls of \textit{ecrt\_domain\_register\_pdo()}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4581
\item[\normalfont\textcircled{\tiny 16}] After the configuration of
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4582
  process data mapping, the master can be activated for cyclic
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4583
  operation. This will configure all slaves and bring them into
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  4584
  OP state.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4585
\item[\normalfont\textcircled{\tiny 20}] This call is needed to avoid
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4586
  a case differentiation in cyclic operation: The first operation in
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4587
  cyclic mode is a receive call. Due to the fact, that there is
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4588
  nothing to receive during the first cycle, there had to be an
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4589
  \textit{if}-statement to avoid a warning. A call to
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4590
  \textit{ec\_master\_prepare()} sends a first datagram containing a
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4591
  process data exchange datagram, so that the first receive call will
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4592
  not fail.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4593
\item[\normalfont\textcircled{\tiny 22} -- \textcircled{\tiny 25}] The
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4594
  master is now ready for cyclic operation. The kernel timer that
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4595
  cyclically executes the \textit{run()} function is initialized and
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4596
  started.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4597
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4598
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4599
The coding of a cleanup function fo the minimal module can be seen in
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4600
listing~\ref{lst:miniclean}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4601
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4602
\begin{lstlisting}[language=C,numbers=left,caption={Minimal cleanup
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4603
    function},label={lst:miniclean}]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4604
  void __exit cleanup_mini_module(void)
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4605
  {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4606
          del_timer_sync(&timer);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4607
          ecrt_master_deactivate(master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4608
          ecrt_release_master(master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4609
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4610
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4611
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4612
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4613
\item[\normalfont\textcircled{\tiny 3}] To cleanup the module, it it
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4614
  necessary to stop the cyclic processing. This is done by a call to
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4615
  \textit{del\_timer\_sync()} which safely removes a queued timer
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4616
  object. It is assured, that no cyclic work will be done after this
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4617
  call returns.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4618
\item[\normalfont\textcircled{\tiny 4}] This call deactivates the
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  4619
  master, which results in all slaves being brought to their INIT
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  4620
  state again.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4621
\item[\normalfont\textcircled{\tiny 5}] This call releases the master,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4622
  removes any existing configuration and silently starts the idle
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4623
  mode. The value of the master pointer is invalid after this call and
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4624
  the module can be safely unloaded.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4625
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4626
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4627
The final part of the minimal module is that for the cyclic work. Its
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4628
coding can be seen in listing~\ref{lst:minirun}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4629
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4630
\begin{lstlisting}[language=C,numbers=left,caption={Minimal cyclic
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4631
    function},label={lst:minirun}]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4632
  void run(unsigned long data)
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4633
  {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4634
          static uint8_t dig_in_0;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4635
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4636
          ecrt_master_receive(master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4637
          ecrt_domain_process(domain1);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4638
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4639
          dig_in_0 = EC_READ_BIT(r_dig_in, 0);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4640
          EC_WRITE_S16(r_ana_out, dig_in_0 * 0x3FFF);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4641
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4642
          ecrt_master_run(master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4643
          ecrt_master_send(master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4644
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4645
          timer.expires += 1; // frequency = HZ
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4646
          add_timer(&timer);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4647
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4648
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4649
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4650
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4651
\item[\normalfont\textcircled{\tiny 5}] The cyclic processing starts
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4652
  with receiving datagrams, that were sent in the last cycle. The
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4653
  frames containing these datagrams have to be received by the network
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4654
  interface card prior to this call.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4655
\item[\normalfont\textcircled{\tiny 6}] The process data of domain 1
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4656
  has been automatically copied into domain memory while datagram
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4657
  reception. This call checks the working counter for changes and
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4658
  re-queues the domain's datagram for sending.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4659
\item[\normalfont\textcircled{\tiny 8}] This is an example for reading
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4660
  out a bit-oriented process data value (i.~e. bit 0) via the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4661
  \textit{EC\_READ\_BIT()} macro. See section~\ref{sec:macros} for
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4662
  more information about those macros.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4663
\item[\normalfont\textcircled{\tiny 9}] This line shows how to write a
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4664
  signed, 16-bit process data value. In this case, the slave is able
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4665
  to output voltages of $-10$~V to $+10$~V with a resolution of 16
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4666
  bit.  This write command outputs either $0$~V or $+5$~V, depending
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4667
  of the value of \textit{dig\_in\_0}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4668
\item[\normalfont\textcircled{\tiny 11}] This call runs the master's
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4669
  operation state machine (see section~\ref{sec:fsm-op}). A single
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4670
  state is processed, and datagrams are queued. Mainly bus observation
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4671
  is done: The bus state is determined and in case of slaves that lost
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4672
  their configuration, reconfiguration is tried.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4673
\item[\normalfont\textcircled{\tiny 12}] This method sends all queued
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4674
  datagrams, in this case the domain's datagram and one of the master
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4675
  state machine. In best case, all datagrams fit into one frame.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4676
\item[\normalfont\textcircled{\tiny 14} -- \textcircled{\tiny 15}]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4677
  Kernel timers are implemented as ``one-shot'' timers, so they have
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4678
  to be re-added after each execution. The time of the next execution
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4679
  is specified in \textit{jiffies} and will happen at the time of the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4680
  next system timer interrupt. This results in the \textit{run()}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4681
  function being executed with a frequency of \textit{HZ}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4682
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4683
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4684
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4685
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4686
\section{An RTAI Example Module}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4687
\label{sec:rtai}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4688
\index{Examples!RTAI}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4689
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4690
The whole code can be seen in the EtherCAT master code release
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4691
(see~\cite{etherlab}, file \textit{examples/rtai/rtai\_sample.c}).
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4692
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4693
Listing~\ref{lst:rtaivar} shows the defines and global variables
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4694
needed for a minimal RTAI module with EtherCAT processing.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4695
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4696
\begin{lstlisting}[language=C,numbers=left,caption={RTAI task
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4697
    declaration},label={lst:rtaivar}]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4698
  #define FREQUENCY 10000
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4699
  #define TIMERTICKS (1000000000 / FREQUENCY)
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4700
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4701
  RT_TASK task;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4702
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4703
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4704
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4705
\item[\normalfont\textcircled{\tiny 1} -- \textcircled{\tiny 2}] RTAI
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4706
  takes the cycle period as nanoseconds, so the easiest way is to
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4707
  define a frequency and convert it to a cycle time in nanoseconds.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4708
\item[\normalfont\textcircled{\tiny 4}] The \textit{task} variable
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4709
  later contains information about the running RTAI task.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4710
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4711
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4712
Listing~\ref{lst:rtaiinit} shows the module init function for the RTAI
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4713
module. Most lines are the same as in listing~\ref{lst:miniinit},
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4714
differences come up when starting the cyclic code.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4715
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4716
\begin{lstlisting}[language=C,numbers=left,caption={RTAI module init
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4717
    function},label={lst:rtaiinit}]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4718
  int __init init_mod(void)
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4719
  {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4720
          RTIME requested_ticks, tick_period, now;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4721
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4722
          if (!(master = ecrt_request_master(0))) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4723
                  goto out_return;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4724
          }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4725
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4726
          if (!(domain1 = ecrt_master_create_domain(master))) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4727
                  goto out_release_master;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4728
          }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4729
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4730
          if (ecrt_domain_register_pdo_list(domain1,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4731
                                            domain1_pdos)) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4732
                  goto out_release_master;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4733
          }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4734
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4735
          if (ecrt_master_activate(master)) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4736
                  goto out_release_master;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4737
          }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4738
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4739
          ecrt_master_prepare(master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4740
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4741
          requested_ticks = nano2count(TIMERTICKS);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4742
          tick_period = start_rt_timer(requested_ticks);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4743
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4744
          if (rt_task_init(&task, run, 0, 2000, 0, 1, NULL)) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4745
                  goto out_stop_timer;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4746
          }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4747
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4748
          now = rt_get_time();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4749
          if (rt_task_make_periodic(&task, now + tick_period,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4750
                                    tick_period)) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4751
                  goto out_stop_task;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4752
          }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4753
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4754
          return 0;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4755
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4756
      out_stop_task:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4757
          rt_task_delete(&task);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4758
      out_stop_timer:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4759
          stop_rt_timer();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4760
      out_deactivate:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4761
          ecrt_master_deactivate(master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4762
      out_release_master:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4763
          ecrt_release_master(master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4764
      out_return:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4765
          return -1;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4766
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4767
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4768
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4769
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4770
\item[\normalfont\textcircled{\tiny 24} -- \textcircled{\tiny 25}] The
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4771
  nanoseconds are converted to RTAI timer ticks and an RTAI timer is
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4772
  started.  \textit{tick\_period} will be the ``real'' number of ticks
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4773
  used for the timer period (which can be different to the requested
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4774
  one).
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4775
\item[\normalfont\textcircled{\tiny 27}] The RTAI task is initialized
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4776
  by specifying the cyclic function, the parameter to hand over, the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4777
  stack size, priority, a flag that tells, if the function will use
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4778
  floating point operations and a signal handler.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4779
\item[\normalfont\textcircled{\tiny 32}] The task is made periodic by
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4780
  specifying a start time and a period.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4781
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4782
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4783
The cleanup function of the RTAI module in listing~\ref{lst:rtaiclean}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4784
is nearly as simple as that of the minimal module.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4785
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4786
\begin{lstlisting}[language=C,numbers=left,caption={RTAI module
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4787
    cleanup function},label={lst:rtaiclean}]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4788
  void __exit cleanup_mod(void)
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4789
  {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4790
          rt_task_delete(&task);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4791
          stop_rt_timer();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4792
          ecrt_master_deactivate(master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4793
          ecrt_release_master(master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4794
          rt_sem_delete(&master_sem);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4795
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4796
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4797
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4798
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4799
\item[\normalfont\textcircled{\tiny 2}] The RTAI task will be stopped
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4800
  and deleted.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4801
\item[\normalfont\textcircled{\tiny 3}] After that, the RTAI timer can
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4802
  be stopped.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4803
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4804
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4805
The rest is the same as for the minimal module.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4806
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4807
Worth to mention is, that the cyclic function of the RTAI module
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4808
(listing~\ref{lst:rtairun}) has a slightly different architecture. The
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4809
function is not executed until returning for every cycle, but has an
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4810
infinite loop in it, that is placed in a waiting state for the rest of
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4811
each cycle.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4812
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4813
\begin{lstlisting}[language=C,numbers=left,caption={RTAI module cyclic
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4814
    function},label={lst:rtairun}]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4815
  void run(long data)
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4816
  {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4817
          while (1) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4818
                  ecrt_master_receive(master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4819
                  ecrt_domain_process(domain1);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4820
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4821
                  k_pos = EC_READ_U32(r_ssi_input);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4822
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4823
                  ecrt_master_run(master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4824
                  ecrt_master_send(master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4825
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4826
                  rt_task_wait_period();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4827
          }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4828
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4829
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4830
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4831
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4832
\item[\normalfont\textcircled{\tiny 3}] The \textit{while (1)} loop
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4833
  executes for the lifetime of the RTAI task.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4834
\item[\normalfont\textcircled{\tiny 12}] The
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4835
  \textit{rt\_task\_wait\_period()} function sets the process into a
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4836
  sleeping state until the beginning of the next cycle. It also
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4837
  checks, if the cyclic function has to be terminated.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4838
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4839
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4840
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4841
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4842
\section{Concurrency Example}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4843
\label{sec:concurrency}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4844
\index{Examples!Concurrency}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4845
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4846
As mentioned before, there can be concurrent access to the EtherCAT
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4847
master. The realtime module and a EoE\index{EoE} process can compete
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4848
for master access, for example. In this case, the module has to
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4849
provide the locking mechanism, because it depends on the module's
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4850
architecture which lock has to be used. The module makes this locking
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4851
mechanism available to the master through the master's locking
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4852
callbacks.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4853
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4854
In case of RTAI, the lock can be an RTAI semaphore, as shown in
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4855
listing~\ref{lst:convar}. A normal linux semaphore would not be
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4856
appropriate, because it could not block the RTAI task due to RTAI
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4857
running in a higher domain than the linux kernel (see~\cite{rtai}).
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4858
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4859
\begin{lstlisting}[language=C,numbers=left,caption={RTAI semaphore for
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4860
    concurrent access},label={lst:convar}]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4861
  SEM master_sem;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4862
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4863
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4864
The module has to implement the two callbacks for requesting and
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4865
releasing the master lock. An exemplary coding can be seen in
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4866
listing~\ref{lst:conlock}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4867
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4868
\begin{lstlisting}[language=C,numbers=left,caption={RTAI locking
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4869
    callbacks for concurrent access},label={lst:conlock}]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4870
  int request_lock(void *data)
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4871
  {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4872
          rt_sem_wait(&master_sem);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4873
          return 0;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4874
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4875
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4876
  void release_lock(void *data)
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4877
  {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4878
          rt_sem_signal(&master_sem);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4879
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4880
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4881
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4882
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4883
\item[\normalfont\textcircled{\tiny 1}] The \textit{request\_lock()}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4884
  function has a data parameter. The master always passes the value,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4885
  that was specified when registering the callback function. This can
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4886
  be used for handing the master pointer. Notice, that it has an
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4887
  integer return value (see line 4).
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4888
\item[\normalfont\textcircled{\tiny 3}] The call to
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4889
  \textit{rt\_sem\_wait()} either returns at once, when the semaphore
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4890
  was free, or blocks until the semaphore is freed again. In any case,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4891
  the semaphore finally is reserved for the process calling the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4892
  request function.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4893
\item[\normalfont\textcircled{\tiny 4}] When the lock was requested
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4894
  successfully, the function should return 0. The module can prohibit
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4895
  requesting the lock by returning non-zero (see paragraph ``Tuning
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4896
  the jitter'' below).
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4897
\item[\normalfont\textcircled{\tiny 7}] The \textit{release\_lock()}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4898
  function gets the same argument passed, but has a void return value,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4899
  because is always succeeds.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4900
\item[\normalfont\textcircled{\tiny 9}] The \textit{rt\_sem\_signal()}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4901
  function frees the semaphore, that was prior reserved with
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4902
  \textit{rt\_sem\_wait()}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4903
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4904
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4905
In the module's init function, the semaphore must be initialized, and
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4906
the callbacks must be passed to the EtherCAT master:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4907
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4908
\begin{lstlisting}[language=C,numbers=left,caption={Module init
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4909
    function for concurrent access},label={lst:coninit}]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4910
  int __init init_mod(void)
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4911
  {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4912
          RTIME tick_period, requested_ticks, now;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4913
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4914
          rt_sem_init(&master_sem, 1);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4915
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4916
          if (!(master = ecrt_request_master(0))) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4917
                  goto out_return;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4918
          }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4919
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4920
          ecrt_master_callbacks(master, request_lock,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4921
                                release_lock, NULL);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4922
          // ...
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4923
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4924
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4925
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4926
\item[\normalfont\textcircled{\tiny 5}] The call to
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4927
  \textit{rt\_sem\_init()} initializes the semaphore and sets its
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4928
  value to 1, meaning that only one process can reserve the semaphore
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4929
  without blocking.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4930
\item[\normalfont\textcircled{\tiny 11}] The callbacks are passed to
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4931
  the master with a call to \textit{ecrt\_master\_callbacks()}. The
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4932
  last parameter is the argument, that the master should pass with
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4933
  each call to a callback function. Here it is not used and set to
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4934
  \textit{NULL}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4935
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4936
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4937
For the cyclic function being only one competitor for master access,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4938
it has to request the lock like any other process. There is no need to
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4939
use the callbacks (which are meant for processes of lower priority),
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4940
so it can access the semaphore directly:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4941
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4942
\begin{lstlisting}[language=C,numbers=left,caption={RTAI cyclic
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4943
    function for concurrent access},label={lst:conrun}]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4944
  void run(long data)
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4945
  {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4946
          while (1) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4947
                  rt_sem_wait(&master_sem);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4948
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4949
                  ecrt_master_receive(master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4950
                  ecrt_domain_process(domain1);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4951
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4952
                  k_pos = EC_READ_U32(r_ssi_input);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4953
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4954
                  ecrt_master_run(master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4955
                  ecrt_master_send(master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4956
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4957
                  rt_sem_signal(&master_sem);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4958
                  rt_task_wait_period();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4959
          }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4960
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4961
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4962
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4963
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4964
\item[\normalfont\textcircled{\tiny 4}] Every access to the master has
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4965
  to be preceeded by a call to \textit{rt\_sem\_wait()}, because
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4966
  another instance might currently access the master.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4967
\item[\normalfont\textcircled{\tiny 14}] When cyclic processing
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4968
  finished, the semaphore has to be freed again, so that other
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4969
  processes have the possibility to access the master.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4970
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4971
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4972
A little change has to be made to the cleanup function in case of
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4973
concurrent master access.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4974
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4975
\begin{lstlisting}[language=C,numbers=left,caption={RTAI module
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4976
    cleanup function for concurrent access},label={lst:conclean}]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4977
  void __exit cleanup_mod(void)
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4978
  {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4979
          rt_task_delete(&task);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4980
          stop_rt_timer();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4981
          ecrt_master_deactivate(master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4982
          ecrt_release_master(master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4983
          rt_sem_delete(&master_sem);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4984
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4985
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4986
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4987
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4988
\item[\normalfont\textcircled{\tiny 7}] Upon module cleanup, the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4989
  semaphore has to be deleted, so that memory can be freed.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4990
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4991
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4992
\paragraph{Tuning the Jitter}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4993
\index{Jitter}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4994
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4995
Concurrent access leads to higher jitter of the realtime process,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4996
because there are situations, in which the realtime process has to
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4997
wait for a process of lower priority to finish accessing the master.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4998
In most cases this is acceptable, because a master access cycle
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  4999
(receive/process/send) only takes $10$~\textmu s to $20$~\textmu s on
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5000
recent systems, what would be the maximum additional jitter. However
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5001
some applications demand a minimum jitter. For this reason the master
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5002
access can be prohibited by the realtime module: If the time, another
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5003
process wants to access the master, is to close to the beginning of
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5004
the next realtime cycle, the module can disallow, that the lock is
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5005
taken. In this case, the request callback has to return $1$, meaning
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5006
that the lock has not been taken. The foreign process must abort its
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5007
master access and try again next time.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5008
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5009
This measure helps to significantly reducing the jitter produced by
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5010
concurrent master access. Below are exerpts of an example coding:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5011
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5012
\begin{lstlisting}[language=C,numbers=left,caption={Variables for
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5013
    jitter reduction},label={lst:redvar}]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5014
  #define FREQUENCY 10000 // RTAI task frequency in Hz
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5015
  // ...
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5016
  cycles_t t_last_cycle = 0;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5017
  const cycles_t t_critical = cpu_khz * 1000 / FREQUENCY
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5018
                              - cpu_khz * 30 / 1000;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5019
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5020
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5021
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5022
\item[\normalfont\textcircled{\tiny 3}] The variable
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5023
  \textit{t\_last\_cycle} holds the timer ticks at the beginning of
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5024
  the last realtime cycle.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5025
\item[\normalfont\textcircled{\tiny 4}] \textit{t\_critical} contains
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5026
  the number of ticks, that may have passed since the beginning of the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5027
  last cycle, until there is no more foreign access possible. It is
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5028
  calculated by substracting the ticks for $30$~\textmu s from the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5029
  ticks for a complete cycle.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5030
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5031
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5032
\begin{lstlisting}[language=C,numbers=left,caption={Cyclic function
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5033
    with reduced jitter},label={lst:redrun}]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5034
  void run(long data)
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5035
  {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5036
          while (1) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5037
                  t_last_cycle = get_cycles();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5038
                  rt_sem_wait(&master_sem);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5039
                  // ...
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5040
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5041
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5042
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5043
\item[\normalfont\textcircled{\tiny 4}] The ticks of the beginning of
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5044
  the current realtime cycle are taken before reserving the semaphore.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5045
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5046
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5047
\begin{lstlisting}[language=C,numbers=left,caption={Request callback
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5048
    for reduced jitter},label={lst:redreq}]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5049
  int request_lock(void *data)
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5050
  {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5051
          // too close to the next RT cycle: deny access.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5052
          if (get_cycles() - t_last_cycle > t_critical)
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5053
                  return -1;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5054
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5055
          // allow access
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5056
          rt_sem_wait(&master_sem);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5057
          return 0;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5058
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5059
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5060
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5061
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5062
\item[\normalfont\textcircled{\tiny 4}] If the time of request is too
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5063
  close to the next realtime cycle (here: \textless~$30$~\textmu s
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5064
  before the estimated beginning), the locking is denied. The
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5065
  requesting process must abort its cycle.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5066
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5067
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5068
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5069
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5070
\begin{thebibliography}{99}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5071
\bibitem{etherlab} Ingenieurgemeinschaft IgH: EtherLab -- Open Source
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5072
  Toolkit for rapid realtime code generation under Linux with
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5073
  Simulink/RTW and EtherCAT technology. URL: http://etherlab.org,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5074
  July~31, 2006.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5075
\bibitem{dlspec} IEC 61158-4-12: Data-link Protocol Specification.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5076
  International Electrotechnical Comission (IEC), 2005.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5077
\bibitem{alspec} IEC 61158-6-12: Application Layer Protocol
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5078
  Specification. International Electrotechnical Comission (IEC), 2005.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5079
\bibitem{gpl} GNU General Public License, Version 2. URL:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5080
  http://www.gnu.org/licenses/gpl.txt. August~9, 2006.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5081
\bibitem{lsb} Linux Standard Base. URL:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5082
  http://www.freestandards.org/en/LSB. August~9, 2006.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5083
\bibitem{wireshark} Wireshark. URL: http://www.wireshark.org.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5084
  August~9, 2006.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5085
\bibitem{automata} {\it Hopcroft, J.~E. / Ullman, J.~D.}: Introduction
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5086
  to Automata Theory, Languages and Computation. Adison-Wesley,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5087
  Reading, Mass.~1979.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5088
\bibitem{fsmmis} {\it Wagner, F. / Wolstenholme, P.}: State machine
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5089
  misunderstandings. In: IEE journal ``Computing and Control
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5090
  Engineering'', 2004.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5091
\bibitem{rtai} RTAI. The RealTime Application Interface for Linux from
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5092
  DIAPM. URL: http://www.rtai.org, 2006.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5093
\end{thebibliography}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5094
917
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
  5095
\printnomenclature
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5096
\addcontentsline{toc}{chapter}{\nomname}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5097
\markleft{\nomname}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5098
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5099
\printindex
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5100
\markleft{Index}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5101
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5102
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5103
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5104
\end{document}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5105
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  5106
%------------------------------------------------------------------------------