documentation/ethercat_doc.tex
author Florian Pose <fp@igh-essen.com>
Wed, 13 Aug 2008 13:19:51 +0000
branchstable-1.4
changeset 1627 22954d039fa5
parent 1140 cc779f7d2496
child 1202 91d190223daa
child 1630 ffa89570d84f
permissions -rw-r--r--
Created branch stable-1.4.
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
%
1095
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
     7
%  vi: spell spelllang=en
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
     8
% 
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
     9
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    10
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
    11
%
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
    12
%   Conventions
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
    13
% The IgH EtherCAT Master
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
    14
%   Feature Summary
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
    15
%   License
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
    16
% Architecture
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
    17
%   Phases
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
    18
%   Behavior (Scanning) TODO
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
    19
% Application Interface
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
    20
%   Interface version
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
    21
%   Master Requesting and Releasing
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
    22
%   Master Locking
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
    23
%   Slave configuration
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
    24
%   Configuring Pdo assignment and mapping
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
    25
%   Domains (memory)
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
    26
%   Pdo entry registration
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
    27
%   Sdo configuration
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
    28
%   Sdo access
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
    29
%   Cyclic operation
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
    30
% Ethernet Devices
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
    31
%   Device Interface
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
    32
%   Device Modules
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
    33
%   Network Driver Basics
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
    34
%   EtherCAT Network Drivers
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
    35
%   Device Selection
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
    36
%   The Device Interface
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
    37
%   Patching Network Drivers
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
    38
% The Master's State Machines
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
    39
%   Master
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
    40
%   Slave scanning
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
    41
%     SII
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
    42
%     Pdo assign/mapping
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
    43
%   Slave configuration
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
    44
%     State change
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
    45
%     Pdo assign/mapping
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
    46
%   CoE upload/download/information
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
    47
% Mailbox Protocol Implementations
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
    48
%     Ethernet-over-EtherCAT (EoE)
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
    49
%     CANopen-over-EtherCAT (CoE)
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
    50
% User Space
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
    51
%     The ethercat command
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
    52
%     System Integration
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
    53
%         The EtherCAT Init Script
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
    54
%         The EtherCAT Sysconfig File
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
    55
%     Monitoring and Debugging
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
    56
% Installation
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
    57
% Example applications
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
    58
% Bibliography
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
    59
% Glossary
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
    60
%
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
    61
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    62
\documentclass[a4paper,12pt,BCOR6mm,bibtotoc,idxtotoc]{scrbook}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    63
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    64
\usepackage[latin1]{inputenc}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    65
\usepackage[automark,headsepline]{scrpage2}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    66
\usepackage{graphicx}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    67
\usepackage{makeidx}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    68
\usepackage[refpage]{nomencl}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    69
\usepackage{listings}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    70
\usepackage{svn}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    71
\usepackage{textcomp}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    72
\usepackage{url}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
    73
\usepackage{SIunits}
371
97f684433d3b Improved documentation makefile, removed svn.sty, fixed LaTeX penalties.
Florian Pose <fp@igh-essen.com>
parents: 370
diff changeset
    74
\usepackage[pdfpagelabels,plainpages=false]{hyperref}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    75
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    76
\setlength{\parskip}{0.8ex plus 0.8ex minus 0.5ex}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    77
\setlength{\parindent}{0mm}
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
\setcounter{secnumdepth}{\subsubsectionlevel}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    80
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    81
\DeclareFontShape{OT1}{cmtt}{bx}{n}
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
  <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
    84
}{}
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
\lstset{basicstyle=\ttfamily\small,numberstyle=\tiny,aboveskip=4mm,
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
    87
  belowskip=2mm,escapechar=`}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    88
\renewcommand\lstlistlistingname{List of Listings}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
    89
917
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    90
% Workaround for lstlistoflistings bug
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    91
\makeatletter% --> De-TeX-FAQ
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    92
\renewcommand*{\lstlistoflistings}{%
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    93
  \begingroup
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    94
    \if@twocolumn
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    95
      \@restonecoltrue\onecolumn
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    96
    \else
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    97
      \@restonecolfalse
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    98
    \fi
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
    99
    \lol@heading
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
   100
    \setlength{\parskip}{\z@}%
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
   101
    \setlength{\parindent}{\z@}%
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
   102
    \setlength{\parfillskip}{\z@ \@plus 1fil}%
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
   103
    \@starttoc{lol}%
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
   104
    \if@restonecol\twocolumn\fi
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
   105
  \endgroup
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
   106
}
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
   107
\makeatother% --> \makeatletter
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
   108
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   109
\renewcommand\nomname{Glossary}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   110
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   111
\newcommand{\IgH}{\raisebox{-0.7667ex}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   112
  {\includegraphics[height=2.2ex]{images/ighsign}}}
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
\SVN $Date$
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   115
\SVN $Revision$
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   116
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   117
\newcommand{\masterversion}{1.4.0}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   118
\newcommand{\linenum}[1]{\normalfont\textcircled{\tiny #1}}
487
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
   119
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   120
\makeindex
917
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
   121
\makenomenclature
369
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
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   124
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   125
\begin{document}
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
\pagenumbering{roman}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   128
\pagestyle{empty}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   129
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   130
\begin{titlepage}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   131
  \begin{center}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   132
    \rule{\textwidth}{1.5mm}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   133
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   134
    {\Huge\bf IgH \includegraphics[height=2.4ex]{images/ethercat}
487
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
   135
      Master \masterversion\\[1ex]
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   136
      Documentation}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   137
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   138
    \vspace{1ex}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   139
    \rule{\textwidth}{1.5mm}
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
    \vspace{\fill}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   142
    {\Large Florian Pose, \url{fp@igh-essen.com}\\[1ex]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   143
      Ingenieurgemeinschaft \IgH}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   144
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   145
    \vspace{\fill}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   146
    {\Large Essen, \SVNDate\\[1ex]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   147
      Revision \SVNRevision}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   148
  \end{center}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   149
\end{titlepage}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   150
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   151
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   152
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   153
\tableofcontents
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   154
\listoftables
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   155
\listoffigures
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   156
\lstlistoflistings
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   157
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   158
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   159
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   160
\newpage
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   161
\pagestyle{scrheadings}
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*{Conventions}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   164
\addcontentsline{toc}{section}{Conventions}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   165
\markleft{Conventions}
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 following typographic conventions are used:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   168
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   169
\begin{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   170
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   171
\item \textit{Italic face} is used for newly introduced terms and file names.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   172
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   173
\item \texttt{Typewriter face} is used for code examples and command line
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   174
output.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   175
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   176
\item \texttt{\textbf{Bold typewriter face}} is used for user input in command
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   177
lines.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   178
369
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
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   181
Data values and addresses are usually specified as hexadecimal values. These
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   182
are marked in the \textit{C} programming language style with the prefix
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   183
\lstinline+0x+ (example: \lstinline+0x88A4+). Unless otherwise noted, address
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   184
values are specified as byte addresses.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   185
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   186
Function names are always printed with parentheses, but without
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   187
parameters. So, if a function \lstinline+ecrt_request_master()+ has
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   188
empty parentheses, this shall not imply that it has no parameters.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   189
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   190
If shell commands have to be entered, this is marked by a dollar prompt:
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   191
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   192
\begin{lstlisting}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   193
$
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   194
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   195
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   196
Further, if a shell command has to be entered as the superuser, the
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   197
prompt is a mesh:
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   198
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   199
\begin{lstlisting}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   200
#
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   201
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   202
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   203
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   204
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   205
\chapter{The IgH EtherCAT Master}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   206
\label{chapter:master}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   207
\pagenumbering{arabic}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   208
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   209
This chapter covers some general information about the EtherCAT master.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   210
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   211
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   212
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   213
\section{Feature Summary}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   214
\label{sec:summary}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   215
\index{Master!Features}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   216
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   217
The list below gives a short summary of the master features.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   218
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   219
\begin{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   220
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   221
\item Designed as a kernel module for Linux 2.6.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   222
1086
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   223
\item Implemented according to IEC 61158-12 \cite{dlspec} \cite{alspec}.
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   224
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   225
\item Comes with EtherCAT-capable drivers for several common Ethernet devices.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   226
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   227
  \begin{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   228
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   229
  \item The Ethernet hardware is operated without interrupts.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   230
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   231
  \item Drivers for additional Ethernet hardware can easily be implemented
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   232
  using the common device interface (see section~\ref{sec:ecdev}) provided by
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   233
  the master module.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   234
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   235
  \end{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   236
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   237
\item The master module supports multiple EtherCAT masters running in
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   238
parallel.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   239
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   240
\item The master code supports any Linux realtime extension through its
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   241
independent architecture.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   242
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   243
  \begin{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   244
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   245
  \item RTAI\nomenclature{RTAI}{Realtime Application Interface},
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   246
  ADEOS\nomenclature{ADEOS}{Adaptive Domain Environment for Operating
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   247
  Systems}, etc.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   248
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   249
  \item It runs well even without realtime extensions.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   250
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   251
  \end{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   252
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   253
\item Common ``realtime interface'' for applications, that want to use
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   254
EtherCAT functionality (see section~\ref{sec:ecrt}).
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   255
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   256
\item \textit{Domains} are introduced, to allow grouping of process
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   257
  data transfers with different slave groups and task periods.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   258
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   259
  \begin{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   260
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   261
  \item Handling of multiple domains with different task periods.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   262
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   263
  \item Automatic calculation of process data mapping, FMMU and sync manager
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   264
  configuration within each domain.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   265
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   266
  \end{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   267
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   268
\item Communication through several finite state machines.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   269
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   270
  \begin{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   271
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   272
  \item Automatic bus scanning after topology changes.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   273
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   274
  \item Bus monitoring during operation.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   275
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   276
  \item Automatic reconfiguration of slaves (for example after power failure)
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   277
  during operation.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   278
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   279
  \end{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   280
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   281
\item CANopen-over-EtherCAT (CoE)
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   282
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   283
  \begin{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   284
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   285
  \item Sdo upload, download and information service.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   286
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   287
  \item Slave configuration via Sdos.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   288
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   289
  \item Sdo access from user-space and from the application.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   290
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   291
  \end{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   292
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   293
\item Ethernet-over-EtherCAT (EoE)
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   294
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   295
  \begin{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   296
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   297
  \item Transparent use of EoE slaves via virtual network interfaces.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   298
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   299
  \item Natively supports either a switched or a routed EoE network
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   300
  architecture.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   301
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   302
  \end{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   303
1140
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
   304
\item User space command-line-tool ``ethercat`` (see
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
   305
section~\ref{sec:ethercat})
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   306
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   307
  \begin{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   308
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   309
  \item Showing the current bus with slaves, Pdos and Sdos.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   310
  \item Showing the bus configuration.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   311
  \item Showing domains and process data.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   312
  \item Setting the master's debug level.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   313
  \item Writing alias addresses.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   314
  \item Sdo uploading/downloading.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   315
  \item Reading/writing a slave's SII.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   316
  \item Setting slave states.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   317
  \item Generate slave description XML.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   318
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   319
  \end{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   320
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   321
\item Seamless system integration though LSB\nomenclature{LSB}{Linux
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   322
    Standard Base} compliance.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   323
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   324
  \begin{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   325
1095
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   326
  \item Master and network device configuration via sysconfig files.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   327
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   328
  \item Init script for master control.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   329
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   330
  \end{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   331
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   332
\item Virtual read-only network interface for monitoring and debugging
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   333
  purposes.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   334
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   335
\end{itemize}
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
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   339
\section{License}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   340
\label{sec:license}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   341
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   342
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
   343
General Public License\index{GPL} \cite{gpl} (version 2). Other
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   344
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
   345
to use the master code or even participate on development.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   346
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   347
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   348
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   349
\chapter{Architecture}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   350
\label{sec:arch}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   351
\index{Master!Architecture}
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
The EtherCAT master is integrated into the Linux 2.6 kernel. This was
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   354
an early design decision, which has been made for several reasons:
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   355
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   356
\begin{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   357
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   358
\item Kernel code has significantly better realtime characteristics, i.~e.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   359
less latency than user space code. It was foreseeable, that a fieldbus master
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   360
has a lot of cyclic work to do. Cyclic work is usually triggered by timer
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   361
interrupts inside the kernel. The execution delay of a function that processes
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   362
timer interrupts is less, when it resides in kernel space, because there is no
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   363
need of time-consuming context switches to a user space process.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   364
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   365
\item It was also foreseeable, that the master code has to directly
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   366
communicate with the Ethernet hardware. This has to be done in the kernel
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   367
anyway (through network device drivers), which is one more reason for the
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   368
master code being in kernel space.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   369
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   370
\end{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   371
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   372
Figure~\ref{fig:arch} gives a general overview of the master architecture.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   373
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   374
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   375
  \centering
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   376
  \includegraphics[width=.9\textwidth]{images/architecture}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   377
  \caption{Master architecture}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   378
  \label{fig:arch}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   379
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   380
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   381
\paragraph{Master Module}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   382
\index{Master module}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   383
1086
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   384
Kernel module containing one or more EtherCAT master instances (see
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   385
section~\ref{sec:mastermod}), the ``Device Interface'' (see
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   386
section~\ref{sec:ecdev}) and the ``Realtime Interface'' (see
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   387
section~\ref{sec:ecrt}).
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   388
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   389
\paragraph{Device Modules}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   390
\index{Device modules}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   391
1086
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   392
EtherCAT-capable Ethernet device driver modules\index{Device modules}, that
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   393
offer their devices to the EtherCAT master via the device interface (see
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   394
section~\ref{sec:ecdev}). These modified network drivers can handle network
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   395
devices used for EtherCAT operation and ``normal'' Ethernet devices in
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   396
parallel. A master can accept a certain device and then is able to send and
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   397
receive EtherCAT frames. Ethernet devices declined by the master module are
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   398
connected to the kernel's network stack as usual.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   399
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   400
\paragraph{Application Modules}
1086
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   401
\index{Application module}
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   402
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   403
Kernel modules, that use the EtherCAT master (usually for cyclic exchange of
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   404
process data with EtherCAT slaves). These modules are not part of the EtherCAT
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   405
master code\footnote{Although there are some examples provided in the
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   406
\textit{examples} directory, see chapter~\ref{chapter:examples}}, but have to
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   407
be generated or written by the user. An application module can ``request'' a
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   408
master through the realtime interface (see section~\ref{sec:ecrt}). If this
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   409
succeeds, the module has the control over the master: It can provide a bus
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   410
configuration and exchange process data.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   411
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   412
%------------------------------------------------------------------------------
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   413
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   414
\section{Phases}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   415
\index{Master phases}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   416
1086
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   417
The EtherCAT master runs through several phases (see fig.~\ref{fig:phases}):
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   418
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   419
\begin{figure}[htbp]
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   420
  \centering
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   421
  \includegraphics[width=.9\textwidth]{images/phases}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   422
  \caption{Master phases and transitions}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   423
  \label{fig:phases}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   424
\end{figure}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   425
\begin{description}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   426
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   427
\item[Orphaned phase]\index{Orphaned phase} This mode takes effect, when the
1086
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   428
master still waits for its Ethernet device to connect. No bus communication is
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   429
possible until then.
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   430
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   431
\item[Idle phase]\index{Idle phase} takes effect when the master has accepted
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   432
an Ethernet device, but is not requested by any application yet. The master
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   433
runs its state machine (see section~\ref{sec:fsm-master}), that automatically
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   434
scans the bus for slaves and executes pending operations from the user space
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   435
interface (for example Sdo access). The command-line tool can be used to access
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   436
the bus, but there is no process data exchange because of the missing bus
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   437
configuration.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   438
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   439
\item[Operation phase]\index{Operation phase} The master is requested by an
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   440
application that can provide a bus configuration and exchange process data.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   441
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   442
\end{description}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   443
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   444
%------------------------------------------------------------------------------
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   445
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   446
\section{General behavior} % FIXME
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   447
\index{Master behavior}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   448
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   449
\ldots
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   450
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   451
%------------------------------------------------------------------------------
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   452
1086
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   453
\section{Master Module}
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   454
\label{sec:mastermodule}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   455
\index{Master module}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   456
1086
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   457
The EtherCAT master kernel module \textit{ec\_master} can contain multiple
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   458
master instances. Each master waits for a certain Ethernet device identified
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   459
by its MAC address\index{MAC address}. These addresses have to be specified on
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   460
module loading via the \textit{main\_devices} module parameter. The number of
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   461
master instances to initialize is taken from the number of MAC addresses
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   462
given.
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   463
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   464
The below command loads the master module with a single master instance that
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   465
waits for the Ethernet device with the MAC address
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   466
\lstinline+00:0E:0C:DA:A2:20+. The master will be accessible via index $0$.
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   467
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   468
\begin{lstlisting}
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   469
# `\textbf{modprobe ec\_master main\_devices=00:0E:0C:DA:A2:20}`
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   470
\end{lstlisting}
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   471
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   472
MAC addresses for multiple masters have to be separated by commas:
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   473
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   474
\begin{lstlisting}
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   475
# `\textbf{modprobe ec\_master main\_devices=00:0E:0C:DA:A2:20,00:e0:81:71:d5:1c}`
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   476
\end{lstlisting}
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   477
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   478
The two masters can be addressed by their indices 0 and 1 respectively (see
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   479
figure~\ref{fig:masters}). The master index is needed for the
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   480
\lstinline+ecrt_master_request()+ function of the realtime interface (see
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   481
section~\ref{sec:ecrt}) and the \lstinline+--master+ option of the
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   482
\textit{ethercat} command-line tool (see section~\ref{sec:ethercat}), which
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   483
defaults to $0$.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   484
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   485
\begin{figure}[htbp]
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   486
  \centering
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   487
  \includegraphics[width=.5\textwidth]{images/masters}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   488
  \caption{Multiple masters in one module}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   489
  \label{fig:masters}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   490
\end{figure}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   491
1086
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   492
\paragraph{Init script}
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   493
\index{Init script}
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   494
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   495
Most probably you won't want to load the master module and the Ethernet driver
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   496
modules manually, but start the master as a service. See
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   497
section~\ref{sec:system} on how to do this.
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   498
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   499
\paragraph{Syslog}
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   500
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   501
The master module outputs information about it's state and events to the
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   502
kernel ring buffer. These also end up in the system logs.  The above module
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   503
loading command should result in the messages below:
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   504
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   505
\begin{lstlisting}
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   506
# `\textbf{dmesg | tail -2}`
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   507
EtherCAT: Master driver `\masterversion`
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   508
EtherCAT: 2 masters waiting for devices.
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   509
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   510
# `\textbf{tail -2 /var/log/messages}`
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   511
Jul  4 10:22:45 ethercat kernel: EtherCAT: Master driver `\masterversion`
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   512
Jul  4 10:22:45 ethercat kernel: EtherCAT: 2 masters waiting
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   513
                                 for devices.
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   514
\end{lstlisting}
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   515
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   516
All EtherCAT master output is prefixed with \lstinline+EtherCAT+ which makes
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
   517
searching the logs easier.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   518
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   519
%------------------------------------------------------------------------------
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   520
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   521
\section{Handling of Process Data} % FIXME
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   522
\label{sec:processdata}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   523
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   524
\ldots
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   525
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   526
\paragraph{Process Data Image}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   527
\index{Process data}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   528
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   529
The slaves offer their inputs and outputs by presenting the master so-called
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   530
``Process Data Objects'' (Pdos\index{Pdo}). The available Pdos can be
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   531
determined by reading out the slave's TXPDO and RXPDO E$^2$PROM categories. The
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   532
application can register the Pdos for data exchange during cyclic operation.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   533
The sum of all registered Pdos defines the ``process data image'', which is
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   534
exchanged via the ``Logical ReadWrite'' datagrams introduced
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   535
in~\cite[section~5.4.2.4]{dlspec}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   536
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   537
\paragraph{Process Data Domains}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   538
\index{Domain}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   539
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   540
The process data image can be easily managed by creating so-called
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
   541
``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
   542
exchange them. Domains are mandatory for process data exchange, so
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   543
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
   544
reasons:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   545
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   546
\begin{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   547
\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
   548
  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
   549
  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
   550
  EtherCAT datagram header and EtherCAT datagram footer: $1500 - 2 -
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   551
  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
   552
  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
   553
  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
   554
  automatically.
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
   555
\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
   556
  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
   557
  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
   558
  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
   559
  group different Pdos and so allow separate exchange.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   560
\end{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   561
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   562
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
   563
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
   564
domains is also limited by the slaves' capabilities.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   565
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   566
\paragraph{FMMU Configuration}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   567
\index{FMMU!Configuration}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   568
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   569
An application can register Pdos for process data exchange. Every
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
   570
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
   571
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
   572
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
   573
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
   574
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
   575
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
   576
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
   577
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
   578
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
   579
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
   580
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
   581
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
   582
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
   583
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
   584
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
   585
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
   586
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
   587
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
   588
process data images.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   589
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   590
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   591
  \centering
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   592
  \includegraphics[width=\textwidth]{images/fmmus}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   593
  \caption{FMMU configuration for several domains}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   594
  \label{fig:fmmus}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   595
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   596
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   597
\paragraph{Process Data Pointers} % FIXME
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   598
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   599
The figure also demonstrates the way, the application can access the exchanged
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   600
process data: At Pdo registration, the application has to provide the address
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   601
of a process data pointer. Upon calculation of the domain image and allocation
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   602
of process data memory, this pointer is redirected to the appropriate location
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   603
inside the domain's process data memory and can later be easily dereferenced by
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   604
the module code.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   605
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   606
%------------------------------------------------------------------------------
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   607
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   608
\chapter{Application Interface}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   609
\label{sec:ecrt}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   610
\index{Application interface}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   611
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   612
The application interface provides functions and data structures for
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   613
applications to access and use an EtherCAT master. The complete documentation
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   614
of the interface is included as Doxygen~\cite{doxygen} comments in the header
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   615
file \textit{include/ecrt.h}. You can either directly view the file comments
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   616
or generate an HTML documentation as described in section~\ref{sec:gendoc}.
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   617
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   618
The following sections cover a general description of the application
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   619
interface.
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   620
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   621
Every application should use the master in two steps:
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   622
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   623
\begin{description}
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   624
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   625
\item[Configuration] The master is requested and the configuration is applied.
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   626
Domains are created Slaves are configured and Pdo entries are registered (see
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   627
section~\ref{sec:masterconfig}).
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   628
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   629
\item[Operation] Cyclic code is run, process data is exchanged (see
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   630
section~\ref{sec:cyclic}).
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   631
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   632
\end{description}
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   633
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   634
%------------------------------------------------------------------------------
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   635
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   636
\section{Master Configuration}
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   637
\label{sec:masterconfig}
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   638
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   639
\ldots
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   640
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   641
\begin{figure}[htbp]
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   642
  \centering
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   643
  \includegraphics[width=.8\textwidth]{images/app-config}
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   644
  \caption{Master configuration structures}
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   645
  \label{fig:app-config}
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   646
\end{figure}
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   647
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   648
%------------------------------------------------------------------------------
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   649
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   650
\section{Cyclic Operation}
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   651
\label{sec:cyclic}
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   652
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   653
\ldots
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   654
% FIXME PDOS endianess
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   655
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   656
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   657
%------------------------------------------------------------------------------
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   658
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
   659
\section{Concurrent Master Access} % FIXME
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   660
\label{sec:concurr}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   661
\index{Concurrency}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   662
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   663
In some cases, one master is used by several instances, for example when an
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   664
application does cyclic process data exchange, and there are EoE-capable slaves
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   665
that require to exchange Ethernet data with the kernel (see
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   666
section~\ref{sec:eoeimp}). For this reason, the master is a shared resource,
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   667
and access to it has to be sequentialized. This is usually done by locking with
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   668
semaphores, or other methods to protect critical sections.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   669
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   670
The master itself can not provide locking mechanisms, because it has no chance
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   671
to know the appropriate kind of lock. Imagine, the application uses RTAI
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   672
functionality, then ordinary kernel semaphores would not be sufficient. For
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   673
that, an important design decision was made: The application that reserved a
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   674
master must have the total control, therefore it has to take responsibility for
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   675
providing the appropriate locking mechanisms. If another instance wants to
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   676
access the master, it has to request the master lock by callbacks, that have to
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   677
be set by the application. Moreover the application can deny access to the
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   678
master if it considers it to be awkward at the moment.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   679
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   680
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   681
  \centering
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   682
  \includegraphics[width=.6\textwidth]{images/master-locks}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   683
  \caption{Concurrent master access}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   684
  \label{fig:locks}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   685
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   686
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   687
Figure~\ref{fig:locks} exemplary shows, how two processes share one master: The
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   688
application's cyclic task uses the master for process data exchange, while the
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   689
master-internal EoE process uses it to communicate with EoE-capable slaves.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   690
Both have to acquire the master lock before access: The application task can
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   691
access the lock natively, while the EoE process has to use the callbacks.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   692
Section~\ref{sec:concurrency} gives an example, of how to implement this.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   693
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   694
%------------------------------------------------------------------------------
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   695
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   696
\chapter{Ethernet devices}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   697
\label{sec:devices}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   698
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   699
The EtherCAT protocol is based on the Ethernet standard. That's why the master
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   700
relies on standard Ethernet hardware to communicate with the bus.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   701
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   702
The term \textit{device} is used as a synonym for Ethernet network interface
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   703
hardware. There are device driver modules that handle Ethernet hardware, which
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   704
the master can use to connect to an EtherCAT bus.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   705
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   706
Section~\ref{sec:networkdrivers} offers an overview of general Linux
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   707
network driver modules, while section~\ref{sec:requirements} will show
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   708
the requirements to an EtherCAT-enabled network driver. Finally,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   709
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
   710
these requirements and implement such a driver module.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   711
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   712
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   713
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   714
\section{Network Driver Basics}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   715
\label{sec:networkdrivers}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   716
\index{Network drivers}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   717
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   718
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
   719
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
   720
to understand how Linux handles network devices and their drivers,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   721
respectively.
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
\paragraph{Tasks of a Network Driver}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   724
1095
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   725
Network device drivers usually handle the lower two layers of the OSI model,
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   726
that is the physical layer and the data-link layer. A network device itself
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   727
natively handles the physical layer issues: It represents the hardware to
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   728
connect to the medium and to send and receive data in the way, the physical
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   729
layer protocol describes. The network device driver is responsible for getting
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   730
data from the kernel's networking stack and forwarding it to the hardware,
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   731
that does the physical transmission.  If data is received by the hardware
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   732
respectively, the driver is notified (usually by means of an interrupt) and
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   733
has to read the data from the hardware memory and forward it to the network
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   734
stack. There are a few more tasks, a network device driver has to handle,
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   735
including queue control, statistics and device dependent features.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   736
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   737
\paragraph{Driver Startup}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   738
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   739
Usually, a driver searches for compatible devices on module loading.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   740
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
   741
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
   742
and the device is taken into operation.
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
\paragraph{Interrupt Operation}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   745
\index{Interrupt}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   746
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   747
A network device usually provides a hardware interrupt that is used to
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   748
notify the driver of received frames and success of transmission, or
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   749
errors, respectively. The driver has to register an interrupt service
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   750
routine (ISR\index{ISR}\nomenclature{ISR}{Interrupt Service Routine}),
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   751
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
   752
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
   753
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
   754
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
   755
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
   756
to kernel memory and passed to the network stack.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   757
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   758
\paragraph{The net\_device structure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   759
\index{net\_device}
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
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
   762
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
   763
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
   764
\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
   765
registration. The \textit{net\_device} structure receives events
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   766
(either from user space or from the network stack) via several
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   767
callbacks, which have to be set before registration. Not every
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   768
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
   769
needed in any case:
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
\begin{description}
1095
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   772
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   773
\item[open()] This function is called when network communication has to be
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   774
started, for example after a command \textit{ifconfig ethX up} from user
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   775
space. Frame reception has to be enabled by the driver.
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   776
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   777
\item[stop()] The purpose of this callback is to ``close'' the device, i.~e.
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   778
make the hardware stop receiving frames.
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   779
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   780
\item[hard\_start\_xmit()] This function is cal\-led for each frame that has
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   781
to be transmitted. The network stack passes the frame as a pointer to an
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   782
\textit{sk\_buff} structure (``socket buffer''\index{Socket buffer}, see
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   783
below), which has to be freed after sending.
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   784
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   785
\item[get\_stats()] This call has to return a pointer to the device's
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   786
\textit{net\_device\_stats} structure, which permanently has to be filled with
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   787
frame statistics. This means, that every time a frame is received, sent, or an
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   788
error happened, the appropriate counter in this structure has to be increased.
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   789
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   790
\end{description}
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   791
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   792
The actual registration is done with the \lstinline+register_netdev()+ call,
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   793
unregistering is done with \lstinline+unregister_netdev()+.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   794
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   795
\paragraph{The netif Interface}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   796
\index{netif}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   797
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   798
All other communication in the direction interface $\to$ network stack is done
1095
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   799
via the \lstinline+netif_*()+ calls. For example, on successful device
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   800
opening, the network stack has to be notified, that it can now pass frames to
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   801
the interface.  This is done by calling \lstinline+netif_start_queue()+. After
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   802
this call, the \lstinline+hard_start_xmit()+ callback can be called by the
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   803
network stack.  Furthermore a network driver usually manages a frame
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   804
transmission queue. If this gets filled up, the network stack has to be told
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   805
to stop passing further frames for a while. This happens with a call to
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   806
\lstinline+netif_stop_queue()+.  If some frames have been sent, and there is
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   807
enough space again to queue new frames, this can be notified with
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   808
\lstinline+netif_wake_queue()+. Another important call is
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   809
\lstinline+netif_receive_skb()+\footnote{This function is part of the NAPI
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   810
(``New API''), that replaces the kernel 2.4 technique for interfacing to the
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   811
network stack (with \lstinline+netif_rx()+). NAPI is a technique to improve
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   812
network performance on Linux. Read more in
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   813
\url{http://www.cyberus.ca/~hadi/usenix-paper.tgz}.}: It passes a frame to the
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   814
network stack, that was just received by the device. Frame data has to be
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   815
packed into a so-called ``socket buffer'' for that (see below).
369
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
\paragraph{Socket Buffers}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   818
\index{Socket buffer}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   819
1095
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   820
Socket buffers are the basic data type for the whole network stack.  They
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   821
serve as containers for network data and are able to quickly add data headers
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   822
and footers, or strip them off again. Therefore a socket buffer consists of an
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   823
allocated buffer and several pointers that mark beginning of the buffer
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   824
(\textit{head}), beginning of data (\textit{data}), end of data
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   825
(\textit{tail}) and end of buffer (\textit{end}). In addition, a socket buffer
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   826
holds network header information and (in case of received data) a pointer to
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   827
the \textit{net\_device}, it was received on. There exist functions that
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   828
create a socket buffer (\lstinline+dev_alloc_skb()+), add data either from
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   829
front (\lstinline+skb_push()+) or back (\lstinline+skb_put()+), remove data
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   830
from front (\lstinline+skb_pull()+) or back (\lstinline+skb_trim()+), or
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   831
delete the buffer (\lstinline+kfree_skb()+).  A socket buffer is passed from
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   832
layer to layer, and is freed by the layer that uses it the last time. In case
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   833
of sending, freeing has to be done by the network driver.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   834
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   835
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   836
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   837
\section{EtherCAT Device Drivers}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   838
\label{sec:requirements}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   839
1095
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   840
There are a few requirements for Ethernet network devices to function as
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   841
EtherCAT devices, when connected to an EtherCAT bus.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   842
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   843
\paragraph{Dedicated Interfaces}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   844
1095
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   845
For performance and realtime purposes, the EtherCAT master needs direct and
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   846
exclusive access to the Ethernet hardware. This implies that the network
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   847
device must not be connected to the kernel's network stack as usual, because
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   848
the kernel would try to use it as an ordinary Ethernet device.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   849
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   850
\paragraph{Interrupt-less Operation}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   851
\index{Interrupt}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   852
1095
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   853
EtherCAT frames travel through the logical EtherCAT ring and are then sent
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   854
back to the master. Communication is highly deterministic: A frame is sent and
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   855
will be received again after a constant time.  Therefore, there is no need to
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   856
notify the driver about frame reception: The master can instead query the
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   857
hardware for received frames.
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   858
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   859
Figure~\ref{fig:interrupt} shows two workflows for cyclic frame transmission
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   860
and reception with and without interrupts.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   861
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   862
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   863
  \centering
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   864
  \includegraphics[width=.8\textwidth]{images/interrupt}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   865
  \caption{Interrupt Operation versus Interrupt-less Operation}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   866
  \label{fig:interrupt}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   867
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   868
1095
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   869
In the left workflow ``Interrupt Operation'', the data from the last cycle is
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   870
first processed and a new frame is assembled with new datagrams, which is then
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   871
sent.  The cyclic work is done for now.  Later, when the frame is received
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   872
again by the hardware, an interrupt is triggered and the ISR is executed. The
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   873
ISR will fetch the frame data from the hardware and initiate the frame
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   874
dissection: The datagrams will be processed, so that the data is ready for
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   875
processing in the next cycle.
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   876
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   877
In the right workflow ``Interrupt-less Operation'', there is no hardware
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   878
interrupt enabled.  Instead, the hardware will be polled by the master by
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   879
executing the ISR. If the frame has been received in the meantime, it will be
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   880
dissected. The situation is now the same as at the beginning of the left
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   881
workflow: The received data is processed and a new frame is assembled and
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   882
sent. There is nothing to do for the rest of the cycle.
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   883
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   884
The interrupt-less operation is desirable, because there is simply no need for
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   885
an interrupt. Moreover hardware interrupts are not conducive in improving the
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   886
driver's realtime behaviour: Their indeterministic incidences contribute to
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   887
increasing the jitter. Besides, if a realtime extension (like RTAI) is used,
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   888
some additional effort would have to be made to prioritize interrupts.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   889
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   890
\paragraph{Ethernet and EtherCAT Devices}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   891
1095
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   892
Another issue lies in the way Linux handles devices of the same type.  For
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   893
example, a PCI\nomenclature{PCI}{Peripheral Component Interconnect, Computer
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   894
Bus} driver scans the PCI bus for devices it can handle. Then it registers
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   895
itself as the responsible driver for all of the devices found. The problem is,
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   896
that an unmodified driver can not be told to ignore a device because it will
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   897
be used for EtherCAT later. There must be a way to handle multiple devices of
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   898
the same type, where one is reserved for EtherCAT, while the other is treated
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   899
as an ordinary Ethernet device.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   900
1095
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   901
For all this reasons, the author decided that the only acceptable solution is
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   902
to modify standard Ethernet drivers in a way that they keep their normal
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   903
functionality, but gain the ability to treat one or more of the devices as
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
   904
EtherCAT-capable.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   905
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   906
Below are the advantages of this solution:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   907
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   908
\begin{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   909
\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
   910
\item One networking driver for EtherCAT and non-EtherCAT devices.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   911
\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
   912
  into issues, the former developers already solved.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   913
\end{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   914
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   915
The chosen approach has the following disadvantages:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   916
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   917
\begin{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   918
\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
   919
  EtherCAT and non-EtherCAT devices.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   920
\item Many additional case differentiations in the driver code.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   921
\item Changes and bug fixes on the standard drivers have to be ported
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   922
  to the Ether\-CAT-capable versions from time to time.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   923
\end{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   924
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   925
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   926
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   927
\section{Device Selection}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   928
\label{sec:deviceselection}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   929
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   930
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
   931
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
   932
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
   933
to, all EtherCAT-capable network driver modules should provide two
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   934
module parameters:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   935
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   936
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   937
\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
   938
  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
   939
  devices found are treated as ordinary Ethernet devices. Default:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   940
  $-1$
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   941
\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
   942
  $0$
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   943
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   944
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   945
The following command loads the EtherCAT-capable RTL8139 device
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   946
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
   947
and connecting it to the first master:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   948
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   949
\begin{lstlisting}[gobble=2]
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
   950
  # `\textbf{modprobe ec\_8139too ec\_device\_index=1}`
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   951
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   952
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   953
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
   954
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
   955
more information.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   956
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   957
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   958
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   959
\section{The Device Interface}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   960
\label{sec:ecdev}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   961
\index{Device interface}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   962
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   963
An anticipation to the section about the master module
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   964
(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
   965
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
   966
specific EtherCAT master.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   967
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   968
The master module provides a ``device interface'' for network device
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   969
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
   970
include the header
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   971
\textit{devices/ecdev.h}\nomenclature{ecdev}{EtherCAT Device}, coming
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   972
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
   973
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
   974
device interface are named with the prefix \textit{ecdev}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   975
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   976
\paragraph{Device Registration}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   977
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   978
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
   979
master with the \textit{ecdev\_register()} function.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   980
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
   981
\begin{lstlisting}[gobble=2,language=C]
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   982
  ec_device_t *ecdev_register(unsigned int master_index,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   983
                              struct net_device *net_dev,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   984
                              ec_isr_t isr,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   985
                              struct module *module);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   986
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   987
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   988
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
   989
EtherCAT master to connect to (see section~\ref{sec:mastermod}),
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   990
followed by \textit{net\_dev}, the pointer to the corresponding
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   991
net\_device structure, which represents the network device to connect.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   992
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
   993
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
   994
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
   995
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
   996
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
   997
\textit{THIS\_MODULE} (see next paragraph). On success, the function
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
   998
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
   999
specified when calling further functions of the device interface.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1000
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
  1001
In error case, the \textit{ecdev\_register()} returns \textit{NULL},
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1002
which means that the device could not be registered.  The reason for
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1003
this is printed to \textit{Syslog}\index{Syslog}. In this case, the
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1004
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
  1005
the \textit{insmod} command fail.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1006
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1007
\paragraph{Implicit Dependencies}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1008
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1009
The reason for the module pointer has to be specified at device registration is
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1010
a non-trivial one: The master has to know about the module, because there will
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1011
be an implicit dependency between the device module and a later connected
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1012
application module: When an application module connects to the master, the use
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1013
count of the master module will be increased, so that the master module can not
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1014
be unloaded for the time of the connection. This is reasonable, and so
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1015
automatically done by the kernel. The kernel knows about this dependency,
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1016
because the application module uses kernel symbols provided by the master
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1017
module.  Moreover it is mandatory, that the device module can be unloaded
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1018
neither, because it is implicitly used by the application module, too.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1019
Unloading it would lead to a fatal situation, because the master would have no
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1020
device to send and receive frames for the application. This dependency can not
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1021
be detected automatically, because the application module does not use any
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1022
symbols of the device module. Therefore the master explicitly increments the
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1023
use counter of the connected device module upon connection of an application
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1024
and decrements it, if it disconnects again. In this manner, it is impossible to
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1025
unload a device module while the master is in use. This is done with the kernel
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1026
function pair \textit{try\_module\_get()}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1027
\index{try\_module\_get@\textit{try\_module\_get()}} and \textit{module\_put()}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1028
\index{module\_put@\textit{module\_put()}}. The first one increases the use
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1029
count of a module and only fails, if the module is currently being unloaded.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1030
The last one decreases the use count again and never fails. Both functions take
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1031
a pointer to the module as their argument, which the device module therefore
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1032
has to specify upon device registration.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1033
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1034
\paragraph{Device Unregistering}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1035
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1036
The deregistration of a device is usually done in the device module's cleanup
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1037
function, by calling the \textit{ecdev\_unregister()} function and specifying
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1038
the master index and a pointer to the device object again.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1039
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1040
\begin{lstlisting}[gobble=2,language=C]
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1041
  void ecdev_unregister(unsigned int master_index,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1042
                        ec_device_t *device);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1043
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1044
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1045
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
  1046
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
  1047
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
  1048
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
  1049
the function has a void return value.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1050
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1051
\paragraph{Starting the Master}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1052
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1053
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
  1054
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
  1055
the \textit{ecdev\_start()} function.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1056
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1057
\begin{lstlisting}[gobble=2,language=C]
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1058
  int ecdev_start(unsigned int master_index);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1059
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1060
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1061
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
  1062
(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
  1063
accessible via Sysfs interface and react to user interactions. The
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1064
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
  1065
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
  1066
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
  1067
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
  1068
init function return an error code.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1069
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1070
\paragraph{Stopping the Master}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1071
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1072
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
  1073
calling the \textit{ecdev\_stop()} function. It will stop processing
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1074
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
  1075
\textit{master\_index}. This function can not fail.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1076
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1077
\begin{lstlisting}[gobble=2,language=C]
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1078
  void ecdev_stop(unsigned int master_index);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1079
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1080
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1081
A subsequent call to \textit{ecdev\_unregister()} will now unregister
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1082
the device savely.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1083
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1084
\paragraph{Receiving Frames}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1085
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1086
The interrupt service routine handling device events usually has a
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1087
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
  1088
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
  1089
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
  1090
\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
  1091
connected EtherCAT master instead.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1092
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1093
\begin{lstlisting}[gobble=2,language=C]
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1094
  void ecdev_receive(ec_device_t *device,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1095
                     const void *data,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1096
                     size_t size);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1097
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1098
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1099
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
  1100
(\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
  1101
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
  1102
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
  1103
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
  1104
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
  1105
doesn't have to be cut off manually.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1106
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1107
\paragraph{Handling the Link Status}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1108
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1109
Information about the link status (i.~e. if there is a carrier signal detected
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1110
on the physical port) is also important to the master. This information is
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1111
usually gathered by the ISR and should be forwarded to the master by calling
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1112
the \textit{ecdev\_link\_state()} function. The master then can react on this
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1113
and warn the application of a lost link.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1114
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1115
\begin{lstlisting}[gobble=2,language=C]
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1116
  void ecdev_link_state(ec_device_t *device,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1117
                        uint8_t new_state);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1118
\end{lstlisting}
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
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
  1121
returned by \textit{ecdev\_\-register()}. With the second parameter
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1122
\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
  1123
up, and 0, if it went down.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1124
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
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1127
\section{Patching Network Drivers}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1128
\label{sec:patching}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1129
\index{Network drivers}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1130
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1131
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
  1132
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
  1133
modified RealTek RTL8139 driver coming with the EtherCAT master
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1134
(\textit{devices/8139too.c}). The driver was originally developed by
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1135
Donald Becker, and is currently maintained by Jeff Garzik.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1136
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1137
Unfortunately, there is no standard procedure to enable an Ethernet
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1138
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
  1139
techniques, that are described in this section.
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{enumerate}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1142
\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
  1143
  strictly avoided for all EtherCAT devices. As mentioned before,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1144
  EtherCAT devices have no connection to the network stack, and
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1145
  therefore must not call its interface functions.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1146
\item Another important thing is, that EtherCAT devices should be
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1147
  operated without interrupts. So any calls of registering interrupt
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1148
  handlers and enabling interrupts at hardware level must be avoided,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1149
  too.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1150
\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
  1151
  operation: Instead there is a fix one allocated on master
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1152
  initialization. This socket buffer is filled with an EtherCAT frame
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1153
  with every send operation and passed to the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1154
  \textit{hard\_start\_xmit()} callback. For that it is necessary,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1155
  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
  1156
  usual.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1157
\end{enumerate}
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
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
  1160
Ethernet devices. This implies, that for each device-dependent
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1161
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
  1162
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
  1163
will only handle one EtherCAT device. This makes the case
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1164
differentiations easier.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1165
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1166
\paragraph{Global Variables}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1167
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1168
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
  1169
as shown in the listing:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1170
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1171
\begin{lstlisting}[gobble=2,language=C,numbers=left]
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1172
  static int ec_device_index = -1;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1173
  static int ec_device_master_index = 0;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1174
  static ec_device_t *rtl_ec_dev;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1175
  struct net_device *rtl_ec_net_dev = NULL;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1176
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1177
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1178
\begin{description}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1179
\item[\linenum{1} -- \linenum{2}] To
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1180
  comply to the requirements for parameters of EtherCAT device modules
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1181
  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
  1182
  parameter variables: \textit{ec\_\-device\_\-index} holds the index
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1183
  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
  1184
  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
  1185
  the single device will be connected to. Default: $0$
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1186
\item[\linenum{3}] \textit{rtl\_ec\_dev} will be
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1187
  the pointer to the later registered RealTek EtherCAT device, which
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1188
  can be used as a parameter for device methods.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1189
\item[\linenum{4}] \textit{rtl\_ec\_net\_dev} is
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1190
  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
  1191
  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
  1192
  with the specified index. This is done inside the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1193
  \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
  1194
  module loading.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1195
\end{description}
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
\paragraph{Module Initialization}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1198
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1199
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
  1200
function:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1201
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1202
\begin{lstlisting}[gobble=2,language=C,numbers=left]
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1203
  static int __init rtl8139_init_module(void)
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1204
  {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1205
          if (pci_module_init(&rtl8139_pci_driver) < 0) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1206
                  printk(KERN_ERR "Failed to init PCI mod.\n");
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1207
                  goto out_return;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1208
          }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1209
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1210
          if (rtl_ec_net_dev) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1211
                  printk(KERN_INFO "Registering"
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1212
                         " EtherCAT device...\n");
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1213
                  if (!(rtl_ec_dev =
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1214
                          ecdev_register(ec_device_master_index,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1215
                                         rtl_ec_net_dev,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1216
                                         rtl8139_interrupt,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1217
                                         THIS_MODULE))) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1218
                          printk(KERN_ERR "Failed to reg."
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1219
                                          " EtherCAT device!\n");
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1220
                          goto out_unreg_pci;
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
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1223
                  printk(KERN_INFO "Starting EtherCAT"
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1224
                         " device...\n");
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1225
                  if (ecdev_start(ec_device_master_index)) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1226
                          printk(KERN_ERR "Failed to start"
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1227
                                 " EtherCAT device!\n");
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1228
                          goto out_unreg_ec;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1229
                  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1230
          } else {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1231
                  printk(KERN_WARNING "No EtherCAT device"
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1232
                         " registered!\n");
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
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1235
          return 0;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1236
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1237
      out_unreg_ec:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1238
          ecdev_unregister(ec_device_master_index, rtl_ec_dev);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1239
      out_unreg_pci:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1240
          pci_unregister_driver(&rtl8139_pci_driver);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1241
      out_return:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1242
          return -1;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1243
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1244
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1245
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1246
\begin{description}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1247
\item[\linenum{3}] This call initializes all
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1248
  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
  1249
  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
  1250
  \textit{net\_device} structure is stored in
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1251
  \textit{rtl\_ec\_net\_dev} for later use (see next listings).
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1252
\item[\linenum{8}] If the specified device was
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1253
  found, \textit{rtl\_ec\_net\_dev} is non-zero.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1254
\item[\linenum{11}] The device is connected to
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1255
  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
  1256
  this fails, module loading is aborted.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1257
\item[\linenum{23}] The device registration was
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1258
  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
  1259
  module loading.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1260
\item[\linenum{29}] If no EtherCAT device was
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1261
  found, a warning is output.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1262
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1263
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1264
\paragraph{Device Searching}
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
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
  1267
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
  1268
executed for each device:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1269
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1270
\begin{lstlisting}[gobble=2,language=C,numbers=left]
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1271
  if (board_idx == ec_device_index) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1272
          rtl_ec_net_dev = dev;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1273
          strcpy(dev->name, "ec0");
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1274
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1275
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1276
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1277
\begin{description}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1278
\item[\linenum{1}] The device with the specified
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1279
  index will be the EtherCAT device.
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
\paragraph{Avoiding Device Registration}
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
Later in the PCI initialization phase, the net\_devices get
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1285
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
  1286
a typical example for an EtherCAT case differentiation:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1287
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1288
\begin{lstlisting}[gobble=2,language=C,numbers=left]
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1289
  if (dev != rtl_ec_net_dev) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1290
          i = register_netdev(dev);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1291
          if (i) goto err_out;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1292
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1293
\end{lstlisting}
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{description}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1296
\item[\linenum{1}] If the current net\_device is
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1297
  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
  1298
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1299
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1300
\paragraph{Avoiding Interrupt Registration}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1301
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1302
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
  1303
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
  1304
if-clauses, because interrupt operation is not wanted for EtherCAT
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1305
devices.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1306
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1307
\begin{lstlisting}[gobble=2,language=C,numbers=left]
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1308
  if (dev != rtl_ec_net_dev) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1309
          retval = request_irq(dev->irq, rtl8139_interrupt,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1310
                               SA_SHIRQ, dev->name, dev);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1311
          if (retval) return retval;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1312
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1313
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1314
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1315
\begin{lstlisting}[gobble=2,language=C,numbers=left]
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1316
  if (dev != rtl_ec_net_dev) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1317
          /* Enable all known interrupts by setting
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1318
             the interrupt mask. */
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1319
          RTL_W16(IntrMask, rtl8139_intr_mask);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1320
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1321
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1322
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1323
\paragraph{Frame Sending}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1324
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1325
The listing below shows an excerpt of the function representing the
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1326
\textit{hard\_start\_xmit()} callback of the net\_device.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1327
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1328
\begin{lstlisting}[gobble=2,language=C,numbers=left]
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1329
  /* Note: the chip doesn't have auto-pad! */
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1330
  if (likely(len < TX_BUF_SIZE)) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1331
          if (len < ETH_ZLEN)
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1332
                  memset(tp->tx_buf[entry], 0, ETH_ZLEN);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1333
          skb_copy_and_csum_dev(skb, tp->tx_buf[entry]);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1334
          if (dev != rtl_ec_net_dev) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1335
                  dev_kfree_skb(skb);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1336
          }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1337
  } else {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1338
          if (dev != rtl_ec_net_dev) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1339
                  dev_kfree_skb(skb);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1340
          }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1341
          tp->stats.tx_dropped++;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1342
          return 0;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1343
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1344
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1345
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1346
\begin{description}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1347
\item[\linenum{6} + \linenum{10}] The
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1348
  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
  1349
  and may not be freed.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1350
\end{description}
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
\paragraph{Frame Receiving}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1353
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1354
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
  1355
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
  1356
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1357
\begin{lstlisting}[gobble=2,language=C,numbers=left]
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1358
  if (dev != rtl_ec_net_dev) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1359
          /* Malloc up new buffer, compatible with net-2e. */
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1360
          /* Omit the four octet CRC from the length. */
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1361
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1362
          skb = dev_alloc_skb (pkt_size + 2);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1363
          if (likely(skb)) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1364
                  skb->dev = dev;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1365
                  skb_reserve(skb, 2); /* 16 byte align
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1366
                                          the IP fields. */
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1367
                  eth_copy_and_sum(skb, &rx_ring[ring_off + 4],
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1368
                                   pkt_size, 0);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1369
                  skb_put(skb, pkt_size);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1370
                  skb->protocol = eth_type_trans(skb, dev);
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
                  dev->last_rx = jiffies;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1373
                  tp->stats.rx_bytes += pkt_size;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1374
                  tp->stats.rx_packets++;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1375
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1376
                  netif_receive_skb (skb);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1377
          } else {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1378
                  if (net_ratelimit())
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1379
                          printk(KERN_WARNING
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1380
                                 "%s: Memory squeeze, dropping"
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1381
                                 " packet.\n", dev->name);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1382
                  tp->stats.rx_dropped++;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1383
          }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1384
  } else {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1385
          ecdev_receive(rtl_ec_dev,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1386
                        &rx_ring[ring_offset + 4], pkt_size);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1387
          dev->last_rx = jiffies;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1388
          tp->stats.rx_bytes += pkt_size;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1389
          tp->stats.rx_packets++;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1390
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1391
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1392
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1393
\begin{description}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1394
\item[\linenum{28}] If the device is an EtherCAT
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1395
  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
  1396
  (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
  1397
  EtherCAT master. Unnecessary copy operations are avoided.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1398
\item[\linenum{30} -- \linenum{32}] The
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1399
  device's statistics are updated as usual.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1400
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1401
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1402
\paragraph{Link State}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1403
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1404
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
  1405
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
  1406
below shows the different processing for Ethernet and EtherCAT
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1407
devices:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1408
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1409
\begin{lstlisting}[gobble=2,language=C,numbers=left]
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1410
  if (dev != rtl_ec_net_dev) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1411
          if (tp->phys[0] >= 0) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1412
                  mii_check_media(&tp->mii, netif_msg_link(tp),
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1413
                                  init_media);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1414
          }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1415
  } else {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1416
          void __iomem *ioaddr = tp->mmio_addr;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1417
          uint16_t link = RTL_R16(BasicModeStatus)
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1418
                          & BMSR_LSTATUS;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1419
          ecdev_link_state(rtl_ec_dev, link ? 1 : 0);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1420
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1421
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1422
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1423
\begin{description}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1424
\item[\linenum{3}] The ``media check'' is done
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1425
  via the media independent interface (MII\nomenclature{MII}{Media
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1426
    Independent Interface}), a standard interface for Fast Ethernet
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1427
  devices.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1428
\item[\linenum{7} -- \linenum{10}] For
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1429
  EtherCAT devices, the link state is fetched manually from the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1430
  appropriate device register, and passed to the EtherCAT master by
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1431
  calling \textit{ecdev\_\-link\_\-state()}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1432
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1433
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1434
\paragraph{Module Cleanup}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1435
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1436
Below is the module's cleanup function:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1437
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1438
\begin{lstlisting}[gobble=2,language=C,numbers=left]
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1439
  static void __exit rtl8139_cleanup_module (void)
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1440
  {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1441
          printk(KERN_INFO "Cleaning up RTL8139-EtherCAT"
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1442
                 " module...\n");
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1443
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1444
          if (rtl_ec_net_dev) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1445
                  printk(KERN_INFO "Stopping device...\n");
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1446
                  ecdev_stop(ec_device_master_index);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1447
                  printk(KERN_INFO "Unregistering device...\n");
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1448
                  ecdev_unregister(ec_device_master_index,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1449
                                   rtl_ec_dev);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1450
                  rtl_ec_dev = NULL;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1451
          }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1452
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1453
          pci_unregister_driver(&rtl8139_pci_driver);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1454
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1455
          printk(KERN_INFO "RTL8139-EtherCAT module"
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1456
                 " cleaned up.\n");
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1457
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1458
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1459
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1460
\begin{description}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1461
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1462
\item[\linenum{6}] Stopping and deregistration is only done, if a device was
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1463
registered before.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1464
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1465
\item[\linenum{8}] The master is first stopped, so it does not access the
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1466
device any more.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1467
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1468
\item[\linenum{10}] After this, the device is unregistered. The master is now
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1469
``orphaned''.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1470
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1471
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1472
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1473
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1474
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1475
\chapter{State Machines}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1476
\label{sec:fsm}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1477
\index{FSM}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1478
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1479
Many parts of the EtherCAT master are implemented as \textit{finite state
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1480
machines} (FSMs\nomenclature{FSM}{Finite State Machine}). Though this leads
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1481
to a higher grade of complexity in some aspects, is opens many new
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1482
possibilities.
369
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 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
  1485
states and moreover illustrates the restrictions of ``sequential''
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1486
coding:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1487
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1488
\begin{lstlisting}[gobble=2,language=C,numbers=left]
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1489
  ec_datagram_brd(datagram, 0x0130, 2); // prepare datagram
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1490
  if (ec_master_simple_io(master, datagram)) return -1;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1491
  slave_states = EC_READ_U8(datagram->data); // process datagram
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1492
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1493
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1494
The \textit{ec\_master\_simple\_io()} function provides a simple interface for
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1495
synchronously sending a single datagram and receiving the result\footnote{For
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1496
all communication issues have been meanwhile sourced out into state machines,
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1497
the function is deprecated and stopped existing. Nevertheless it is adequate
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1498
for showing it's own restrictions.}. Internally, it queues the specified
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1499
datagram, invokes the \textit{ec\_master\_send\_datagrams()} function to send
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1500
a frame with the queued datagram and then waits actively for its reception.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1501
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1502
This sequential approach is very simple, reflecting in only three
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1503
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
  1504
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
  1505
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
  1506
(synchronously\footnote{At this time, synchronous master access will
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1507
  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
  1508
  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
  1509
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
  1510
sequential model.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1511
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1512
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
  1513
wanting to send and receive datagrams synchronously. With the present
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1514
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
  1515
each instance, which would be non-acceptable especially in realtime
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1516
circumstances, because of the huge time overhead.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1517
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1518
A possible solution is, that all instances would be executed
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1519
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
  1520
next instance instead of waiting for the datagram reception. Finally,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1521
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
  1522
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
  1523
instances again, which then process their received datagrams and issue
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1524
new ones.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1525
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1526
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
  1527
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
  1528
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
  1529
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
  1530
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
  1531
from above as a state machine:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1532
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1533
\begin{lstlisting}[gobble=2,language=C,numbers=left]
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1534
  // state 1
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1535
  ec_datagram_brd(datagram, 0x0130, 2); // prepare datagram
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1536
  ec_master_queue(master, datagram); // queue datagram
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1537
  next_state = state_2;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1538
  // state processing finished
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1539
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1540
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1541
After all instances executed their current state and queued their
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1542
datagrams, these are sent and received. Then the respective next
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1543
states are executed:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1544
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1545
\begin{lstlisting}[gobble=2,language=C,numbers=left]
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1546
  // state 2
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1547
  if (datagram->state != EC_DGRAM_STATE_RECEIVED) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1548
          next_state = state_error;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1549
          return; // state processing finished
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1550
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1551
  slave_states = EC_READ_U8(datagram->data); // process datagram
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1552
  // state processing finished.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1553
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1554
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1555
See section~\ref{sec:statemodel} for an introduction to the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1556
state machine programming concept used in the master code.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1557
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1558
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1559
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1560
\section{State Machine Theory}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1561
\label{sec:fsmtheory}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1562
\index{FSM!Theory}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1563
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1564
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
  1565
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
  1566
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
  1567
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
  1568
S, s_0, \delta, \omega)$, with
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1569
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1570
\begin{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1571
\item the input alphabet $\Sigma$, with $\Sigma \neq
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1572
  \emptyset$, containing all input symbols,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1573
\item the output alphabet $\Gamma$, with $\Gamma \neq
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1574
  \emptyset$, containing all output symbols,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1575
\item the set of states $S$, with $S \neq \emptyset$,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1576
\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
  1577
  \emptyset$
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1578
\item the transition function $\delta: S \times \Sigma \rightarrow S
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1579
  \times \Gamma$
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1580
\item the output function $\omega$.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1581
\end{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1582
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1583
The state transition function $\delta$ is often specified by a
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1584
\textit{state transition table}, or by a \textit{state transition
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1585
  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
  1586
machine behavior (see table~\ref{tab:statetrans}). The matrix rows
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1587
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
  1588
correspond to the input symbols ($\Gamma = \{a, b, \varepsilon\}$).
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1589
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
  1590
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
  1591
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
  1592
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1593
\begin{table}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1594
  \caption{A typical state transition table}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1595
  \label{tab:statetrans}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1596
  \vspace{2mm}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1597
  \centering
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1598
  \begin{tabular}{l|ccc}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1599
    & $a$ & $b$ & $\varepsilon$\\ \hline
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1600
    $s_0$ & $s_1$ & $s_1$ & $s_2$\\
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1601
    $s_1$ & $s_2$ & $s_1$ & $s_0$\\
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1602
    $s_2$ & $s_0$ & $s_0$ & $s_0$\\ \hline
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1603
  \end{tabular}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1604
\end{table}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1605
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1606
The 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
  1607
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
  1608
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
  1609
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
  1610
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
  1611
circle with an arrow pointing to the respective state.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1612
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1613
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1614
  \centering
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1615
  \includegraphics[width=.5\textwidth]{images/statetrans}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1616
  \caption{A typical state transition diagram}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1617
  \label{fig:statetrans}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1618
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1619
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1620
\paragraph{Deterministic and non-deterministic state machines}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1621
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1622
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
  1623
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
  1624
state machine has exactly one starting state. Non-deterministic state
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1625
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
  1626
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
  1627
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1628
\paragraph{Moore and Mealy machines}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1629
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1630
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
  1631
\textit{Mealy machines}. Mathematically spoken, the distinction lies
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1632
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
  1633
state ($\omega: S \rightarrow \Gamma$), the machine corresponds to the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1634
``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
  1635
the input alphabet ($\omega: S \times \Sigma \rightarrow \Gamma$) the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1636
state machine corresponds to the ``Mealy model''. Mealy machines are
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1637
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
  1638
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
  1639
both models is often used.
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{Misunderstandings about state machines}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1642
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1643
There is a phenomenon called ``state explosion'', that is often taken as a
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1644
counter-argument against general use of state machines in complex environments.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1645
It has to be mentioned, that this point is misleading~\cite{fsmmis}. State
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1646
explosions happen usually as a result of a bad state machine design: Common
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1647
mistakes are storing the present values of all inputs in a state, or not
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1648
dividing a complex state machine into simpler sub state machines. The EtherCAT
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1649
master uses several state machines, that are executed hierarchically and so
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1650
serve as sub state machines. These are also described below.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1651
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1652
%------------------------------------------------------------------------------
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1653
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1654
\section{The Master's State Model}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1655
\label{sec:statemodel}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1656
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1657
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
  1658
implement state machines.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1659
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1660
\paragraph{State Machine Programming}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1661
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1662
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
  1663
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
  1664
by one big case differentiation:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1665
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1666
\begin{lstlisting}[gobble=2,language=C,numbers=left]
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1667
  enum {STATE_1, STATE_2, STATE_3};
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1668
  int state = STATE_1;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1669
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1670
  void state_machine_run(void *priv_data) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1671
          switch (state) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1672
                  case STATE_1:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1673
                          action_1();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1674
                          state = STATE_2;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1675
                          break;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1676
                  case STATE_2:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1677
                          action_2()
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1678
                          if (some_condition) state = STATE_1;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1679
                          else state = STATE_3;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1680
                          break;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1681
                  case STATE_3:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1682
                          action_3();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1683
                          state = STATE_1;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1684
                          break;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1685
          }
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
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1688
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1689
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
  1690
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
  1691
additional case differentiation is executed each run. Besides, lots of
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1692
indentation is wasted.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1693
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1694
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
  1695
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
  1696
pointer:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1697
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1698
\begin{lstlisting}[gobble=2,language=C,numbers=left]
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1699
  void (*state)(void *) = state1;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1700
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1701
  void state_machine_run(void *priv_data) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1702
          state(priv_data);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1703
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1704
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1705
  void state1(void *priv_data) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1706
          action_1();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1707
          state = state2;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1708
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1709
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1710
  void state2(void *priv_data) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1711
          action_2();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1712
          if (some_condition) state = state1;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1713
          else state = state2;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1714
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1715
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1716
  void state3(void *priv_data) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1717
          action_3();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1718
          state = state1;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1719
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1720
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1721
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1722
In the master code, state pointers of all state machines\footnote{All except
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1723
for the EoE state machine, because multiple EoE slaves have to be handled in
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1724
parallel. For this reason each EoE handler object has its own state pointer.}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1725
are gathered in a single object of the \textit{ec\_fsm\_t} class. This is
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1726
advantageous, because there is always one instance of every state machine
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1727
available and can be started on demand.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1728
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1729
\paragraph{Mealy and Moore}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1730
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1731
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
  1732
the actions executed (the ``outputs'' of the state machine) only
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1733
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
  1734
introduced in section~\ref{sec:fsmtheory}. As mentioned, the ``Mealy''
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1735
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
  1736
below:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1737
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1738
\begin{lstlisting}[gobble=2,language=C,numbers=left]
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1739
  void state7(void *priv_data) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1740
          if (some_condition) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1741
                  action_7a();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1742
                  state = state1;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1743
          }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1744
          else {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1745
                  action_7b();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1746
                  state = state8;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1747
          }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1748
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1749
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1750
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1751
\begin{description}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1752
\item[\linenum{3} + \linenum{7}] The
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1753
  state function executes the actions depending on the state
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1754
  transition, that is about to be done.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1755
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1756
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1757
The most flexible alternative is to execute certain actions depending
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1758
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
  1759
transition:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1760
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1761
\begin{lstlisting}[gobble=2,language=C,numbers=left]
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1762
  void state9(void *priv_data) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1763
          action_9();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1764
          if (some_condition) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1765
                  action_9a();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1766
                  state = state7;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1767
          }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1768
          else {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1769
                  action_9b();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1770
                  state = state10;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1771
          }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1772
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1773
\end{lstlisting}
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
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
  1776
of both approaches.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1777
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1778
\paragraph{Using Sub State Machines}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1779
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1780
To avoid having too much states, certain functions of the EtherCAT master state
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1781
machine have been sourced out into sub state machines.  This helps to
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1782
encapsulate the related workflows and moreover avoids the ``state explosion''
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1783
phenomenon described in section~\ref{sec:fsmtheory}. If the master would
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1784
instead use one big state machine, the number of states would be a multiple of
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1785
the actual number. This would increase the level of complexity to a
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1786
non-manageable grade.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1787
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1788
\paragraph{Executing Sub State Machines}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1789
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1790
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
  1791
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
  1792
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
  1793
slave configuration state machine code:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1794
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1795
\begin{lstlisting}[gobble=2,language=C,numbers=left]
813
bfc3f1ab52de Fixed typo SAVEOP -> SAFEOP.
Florian Pose <fp@igh-essen.com>
parents: 487
diff changeset
  1796
  void ec_fsm_slaveconf_safeop(ec_fsm_t *fsm)
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1797
  {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1798
          fsm->change_state(fsm); // execute state change
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1799
                                  // sub state machine
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1800
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1801
          if (fsm->change_state == ec_fsm_error) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1802
                  fsm->slave_state = ec_fsm_end;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1803
                  return;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1804
          }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1805
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1806
          if (fsm->change_state != ec_fsm_end) return;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1807
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1808
          // continue state processing
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1809
          ...
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1810
\end{lstlisting}
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
\begin{description}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1813
\item[\linenum{3}] \textit{change\_state} is the
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1814
  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
  1815
  the pointer points on, is executed\ldots
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1816
\item[\linenum{6}] \ldots either until the state
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1817
  machine terminates with the error state \ldots
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1818
\item[\linenum{11}] \ldots or until the state
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1819
  machine terminates in the end state. Until then, the ``higher''
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1820
  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
  1821
  state machine again in the next cycle.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1822
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1823
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1824
\paragraph{State Machine Descriptions}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1825
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1826
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
  1827
master. The textual descriptions of the state machines contain
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1828
references to the transitions in the corresponding state transition
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1829
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
  1830
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
  1831
response from slave) are not described explicitly. These transitions
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1832
are drawn as dashed arrows in the diagrams.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1833
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1834
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1835
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1836
\section{The Operation State Machine}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1837
\label{sec:fsm-op}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1838
\index{FSM!Operation}
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 Operation state machine is executed by calling the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1841
\textit{ecrt\_master\_run()} method in cyclic realtime code. Its
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1842
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
  1843
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
  1844
diagram.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1845
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1846
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1847
  \centering
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1848
  \includegraphics[width=.8\textwidth]{images/fsm-op}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1849
  \caption{Transition diagram of the operation state machine}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1850
  \label{fig:fsm-op}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1851
\end{figure}
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{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1854
\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
  1855
  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
  1856
  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
  1857
  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
  1858
  responding can be determined.  $\rightarrow$~BROADCAST
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1859
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1860
\item[BROADCAST] The broadcast datagram is evaluated. A change in the number of
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1861
responding slaves is treated as a topology change. If the number of slaves is
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1862
not as expected, the bus is marked as ``tainted''. In this state, no slave
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1863
reconfiguration is possible, because the assignment of known slaves and those
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1864
present on the bus is ambiguous. If the number of slaves is considered as
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1865
right, the bus is marked for validation, because it turned from tainted to
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1866
normal state and it has to be checked, if all slaves are valid. Now, the state
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1867
of every single slave has to be determined. For that, a (unicast) datagram is
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1868
issued, that queries the first slave's ``AL Control Response'' attribute.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1869
$\rightarrow$~READ STATES
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1870
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1871
\item[READ STATES] If the current slave did not respond to its configured
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1872
station address, it is marked as offline, and the next slave is queried.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1873
$\rightarrow$~READ STATES
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1874
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1875
  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
  1876
  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
  1877
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1878
  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
  1879
  validation, the validation is started by checking the first slaves
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  1880
  vendor ID. $\rightarrow$~VALIDATE VENDOR
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1881
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1882
  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
  1883
  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
  1884
  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
  1885
  $\rightarrow$~CONFIGURE SLAVES
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1886
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1887
  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
  1888
  restarted. $\rightarrow$~START
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1889
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1890
\item[CONFIGURE SLAVES] The slave configuration state machine is
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  1891
  executed until termination. $\rightarrow$~CONFIGURE SLAVES
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1892
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1893
  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
  1894
  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
  1895
  state again. $\rightarrow$~CONFIGURE SLAVES
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1896
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1897
  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
  1898
  restarted. $\rightarrow$~START
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1899
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1900
\item[VALIDATE VENDOR] The SII state machine is executed until
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1901
  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
  1902
  is restarted. $\rightarrow$~START
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1903
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1904
  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
  1905
  $\rightarrow$~VALIDATE PRODUCT
369
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
\item[VALIDATE PRODUCT] The SII state machine is executed until
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1908
  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
  1909
  machine is restarted. $\rightarrow$~START
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1910
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1911
  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
  1912
  is queried. $\rightarrow$~VALIDATE VENDOR
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1913
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1914
  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
  1915
  configured station addresses can be safely rewritten. This is done
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1916
  for the first slave marked as offline.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  1917
  $\rightarrow$~REWRITE ADDRESSES
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1918
1095
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  1919
\item[REWRITE ADDRESSES] If the station address was successfully written, it is
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  1920
searched for the next slave marked as offline. If there is one, its address is
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  1921
reconfigured, too.  $\rightarrow$~REWRITE ADDRESSES
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1922
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1923
  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
  1924
  restarted. $\rightarrow$~START
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1925
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1926
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1927
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1928
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1929
\section{The Idle State Machine}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1930
\label{sec:fsm-idle}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1931
\index{FSM!Idle}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1932
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1933
The Idle state machine is executed by a kernel thread, if no application is
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1934
connected. Its purpose is to make slave information available to user space,
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1935
operate EoE-capable slaves, read and write SII contents and test slave
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  1936
functionality.  Figure~\ref{fig:fsm-idle} shows its transition diagram.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1937
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1938
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1939
  \centering
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1940
  \includegraphics[width=.8\textwidth]{images/fsm-idle}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1941
  \caption{Transition diagram of the idle state machine}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1942
  \label{fig:fsm-idle}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1943
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1944
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1945
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1946
\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
  1947
  the operation state machine, a broadcast datagram is issued, to
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1948
  query all slave states and the number of slaves.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  1949
  $\rightarrow$~BROADCAST
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1950
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1951
\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
  1952
  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
  1953
  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
  1954
  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
  1955
  slave. $\rightarrow$~SCAN FOR SLAVES
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1956
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1957
  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
  1958
  $\rightarrow$~READ STATES
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1959
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1960
\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
  1961
  termination. $\rightarrow$~SCAN FOR SLAVES
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1962
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1963
  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
  1964
  started again. $\rightarrow$~SCAN FOR SLAVES
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1965
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1966
  If all slave information has been fetched, slave addresses are
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1967
  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
  1968
  restarted. $\rightarrow$~START
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1969
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1970
\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
  1971
  marked as offline. The next slave is queried.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  1972
  $\rightarrow$~READ STATES
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1973
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1974
  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
  1975
  is queried. $\rightarrow$~READ STATES
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1976
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1977
  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
  1978
  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
  1979
  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
  1980
  them. $\rightarrow$~CONFIGURE SLAVES
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1981
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1982
  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
  1983
  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
  1984
  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
  1985
  writing access. $\rightarrow$~WRITE EEPROM
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1986
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1987
  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
  1988
  state machine is restarted. $\rightarrow$~START
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1989
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1990
\item[CONFIGURE SLAVES] The slave configuration state machine is
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  1991
  executed until termination. $\rightarrow$~CONFIGURE SLAVES
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1992
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1993
  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
  1994
  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
  1995
  this slave. $\rightarrow$~CONFIGURE SLAVES
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1996
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  1997
  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
  1998
  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
  1999
  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
  2000
  writing access. $\rightarrow$~WRITE EEPROM
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2001
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2002
  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
  2003
  $\rightarrow$~START
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2004
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2005
\item[WRITE EEPROM] The SII state machine is executed until
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2006
  termination. $\rightarrow$~WRITE EEPROM
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2007
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2008
  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
  2009
  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
  2010
  word. $\rightarrow$~WRITE EEPROM
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2011
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2012
  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
  2013
  contents are evaluated and the state machine is restarted.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2014
  $\rightarrow$~START
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2015
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2016
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2017
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2018
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2019
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2020
\section{The Slave Scan State Machine}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2021
\label{sec:fsm-scan}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2022
\index{FSM!Slave Scan}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2023
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2024
The slave scan state machine, which can be seen in
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2025
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
  2026
all slave information.
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
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2029
  \centering
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2030
  \includegraphics[width=.6\textwidth]{images/fsm-slavescan}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2031
  \caption{Transition diagram of the slave scan state machine}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2032
  \label{fig:fsm-slavescan}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2033
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2034
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2035
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2036
\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
  2037
  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
  2038
  ring position~+~$1$. In this way, the address 0x0000 (default
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2039
  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
  2040
  slaves.  $\rightarrow$~ADDRESS
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2041
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2042
\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
  2043
  that, the slave's ``AL Control Response'' attribute is queried.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2044
  $\rightarrow$~STATE
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2045
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2046
\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
  2047
  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
  2048
  ``DL Information'' attribute is queried.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2049
  $\rightarrow$~BASE
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2050
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2051
\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
  2052
  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
  2053
  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
  2054
  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
  2055
  address 0x0110. $\rightarrow$~DATALINK
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2056
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2057
\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
  2058
  information about the communication ports contains, if the link is
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2059
  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
  2060
  on the RX side of each port.
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
  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
  2063
  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
  2064
  category header, until the last category is reached (type 0xFFFF).
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2065
  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
  2066
  word address 0x0040 via the SII state machine.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2067
  $\rightarrow$~EEPROM SIZE
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2068
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2069
\item[EEPROM SIZE] The SII state machine is executed until
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2070
  termination. $\rightarrow$~EEPROM SIZE
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2071
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2072
  If the 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
  2073
  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
  2074
  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
  2075
  $\rightarrow$~EEPROM SIZE
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2076
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2077
  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
  2078
  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
  2079
  started to read the first word. $\rightarrow$~EEPROM DATA
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2080
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2081
\item[EEPROM DATA] The SII state machine is executed until
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2082
  termination. $\rightarrow$~EEPROM DATA
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2083
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2084
  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
  2085
  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
  2086
  (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
  2087
  machine is started again to read the next two words.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2088
  $\rightarrow$~EEPROM DATA
369
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
  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
  2091
  object and mailbox information are evaluated. Moreover the category
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2092
  types STRINGS, GENERAL, SYNC and PDO are evaluated. The slave
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2093
  scanning has been completed. $\rightarrow$~END
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2094
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2095
\item[END] Slave scanning has been finished.
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
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2098
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2099
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2100
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2101
\section{The Slave Configuration State Machine}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2102
\label{sec:fsm-conf}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2103
\index{FSM!Slave Configuration}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2104
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2105
The slave configuration state machine, which can be seen in
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2106
figure~\ref{fig:fsm-slaveconf}, leads through the process of
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2107
configuring a slave and bringing it to a certain state.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2108
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2109
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2110
  \centering
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2111
  \includegraphics[width=.6\textwidth]{images/fsm-slaveconf}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2112
  \caption{Transition diagram of the slave configuration state
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2113
    machine}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2114
  \label{fig:fsm-slaveconf}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2115
\end{figure}
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
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2118
\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
  2119
  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
  2120
  state machine is executed until termination. $\rightarrow$~INIT
369
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
  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
  2123
  aborted. $\rightarrow$~END
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2124
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2125
  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
  2126
  If this is the target state, the configuration is finished.
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2127
  $\rightarrow$~END
369
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
  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
  2130
  configuration can be skipped. The state change state machine is
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2131
  started to bring the slave into PREOP state.
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2132
  $\rightarrow$~PREOP
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2133
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2134
  Sync managers are configured conforming to the sync manager category
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2135
  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
  2136
  datagram is issued. $\rightarrow$~SYNC
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2137
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2138
\item[SYNC] If the sync manager configuration datagram is accepted,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2139
  the sync manager configuration was successful. The slave may now
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2140
  enter the PREOP state, and the state change state machine is
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2141
  started. $\rightarrow$~PREOP
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2142
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2143
\item[PREOP] The state change state machine is executed until
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2144
  termination. $\rightarrow$~PREOP
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2145
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2146
  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
  2147
  $\rightarrow$~END
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2148
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2149
  If the PREOP state was the target state, the configuration is
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2150
  finished. $\rightarrow$~END
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2151
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2152
  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
  2153
  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
  2154
  sending the first Sdo. $\rightarrow$~SDO\_CONF
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  2155
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  2156
  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
  2157
  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
  2158
  started again. $\rightarrow$~SAFEOP
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2159
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  2160
  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
  2161
  requested via the master's realtime interface. The appropriate
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2162
  datagram is issued. $\rightarrow$~FMMU
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2163
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2164
\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
  2165
  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
  2166
  $\rightarrow$~SDO\_CONF
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2167
813
bfc3f1ab52de Fixed typo SAVEOP -> SAFEOP.
Florian Pose <fp@igh-essen.com>
parents: 487
diff changeset
  2168
  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
  2169
  state change state machine is started.
813
bfc3f1ab52de Fixed typo SAVEOP -> SAFEOP.
Florian Pose <fp@igh-essen.com>
parents: 487
diff changeset
  2170
  $\rightarrow$~SAFEOP
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2171
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2172
\item[SDO\_CONF] The CoE state machine is executed until termination.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2173
  $\rightarrow$~SDO\_CONF
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2174
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  2175
  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
  2176
  begun. $\rightarrow$~SDO\_CONF
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2177
813
bfc3f1ab52de Fixed typo SAVEOP -> SAFEOP.
Florian Pose <fp@igh-essen.com>
parents: 487
diff changeset
  2178
  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
  2179
  state change state machine is started.
813
bfc3f1ab52de Fixed typo SAVEOP -> SAFEOP.
Florian Pose <fp@igh-essen.com>
parents: 487
diff changeset
  2180
  $\rightarrow$~SAFEOP
bfc3f1ab52de Fixed typo SAVEOP -> SAFEOP.
Florian Pose <fp@igh-essen.com>
parents: 487
diff changeset
  2181
bfc3f1ab52de Fixed typo SAVEOP -> SAFEOP.
Florian Pose <fp@igh-essen.com>
parents: 487
diff changeset
  2182
\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
  2183
  termination. $\rightarrow$~SAFEOP
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2184
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2185
  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
  2186
  $\rightarrow$~END
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2187
813
bfc3f1ab52de Fixed typo SAVEOP -> SAFEOP.
Florian Pose <fp@igh-essen.com>
parents: 487
diff changeset
  2188
  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
  2189
  finished. $\rightarrow$~END
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2190
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2191
  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
  2192
  state change state machine is started a last time.
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2193
  $\rightarrow$~OP
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2194
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2195
\item[OP] The state change state machine is executed until
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2196
  termination. $\rightarrow$~OP
369
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
  If the state change state machine terminates, the slave
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2199
  configuration is finished, regardless of its success.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2200
  $\rightarrow$~END
369
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
\item[END] The termination state.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2203
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2204
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2205
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2206
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2207
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2208
\section{The State Change State Machine}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2209
\label{sec:fsm-change}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2210
\index{FSM!State Change}
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
The state change state machine, which can be seen in
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2213
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
  2214
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
  2215
\cite[section~6.4.1]{alspec}.
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
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2218
  \centering
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2219
  \includegraphics[width=.9\textwidth]{images/fsm-change}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2220
  \caption{Transition diagram of the state change state machine}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2221
  \label{fig:fsm-change}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2222
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2223
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2224
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2225
\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
  2226
  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
  2227
  attribute. Nothing can fail. $\rightarrow$~CHECK
369
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
\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
  2230
  Control Response'' attribute is queried with a second datagram.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2231
  $\rightarrow$~STATUS
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2232
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2233
\item[STATUS] The read memory contents are evaluated: While the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2234
  parameter \textit{State} still contains the old slave state, the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2235
  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
  2236
  case, the attribute has to be queried again.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2237
  $\rightarrow$~STATUS
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2238
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2239
  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
  2240
  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
  2241
  requested state.  $\rightarrow$~END
369
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
  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
  2244
  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
  2245
  querying the \textit{AL Status Code} parameter.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2246
  $\rightarrow$~CODE
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2247
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2248
\item[END] If the state machine ends in this state, the slave's state
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2249
  change has been successful.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2250
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2251
\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
  2252
  \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
  2253
  this parameter. Anyway, the master has to acknowledge the state
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2254
  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
  2255
  Request'' attribute with the \textit{Acknowledge} bit set.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2256
  $\rightarrow$~ACK
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2257
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2258
\item[ACK] After that, the ``AL Control Response'' attribute is
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2259
  queried for the state of the acknowledgement.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2260
  $\rightarrow$~CHECK ACK
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2261
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2262
\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
  2263
  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
  2264
  unsuccessful. $\rightarrow$~ERROR
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2265
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2266
  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
  2267
  In any case, the overall state change was unsuccessful.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2268
  $\rightarrow$~ERROR
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2269
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2270
  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
  2271
  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
  2272
  queried again.  $\rightarrow$~CHECK ACK
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2273
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2274
\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
  2275
  state change was unsuccessful.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2276
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2277
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2278
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2279
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2280
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2281
\section{The SII State Machine}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2282
\label{sec:fsm-sii}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2283
\index{FSM!SII}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2284
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2285
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
  2286
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
  2287
Slave Information Interface described in \cite[section~5.4]{alspec}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2288
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2289
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2290
  \centering
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2291
  \includegraphics[width=.9\textwidth]{images/fsm-sii}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2292
  \caption{Transition diagram of the SII state machine}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2293
  \label{fig:fsm-sii}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2294
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2295
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2296
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2297
\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
  2298
  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
  2299
  attribute. Nothing can fail up to now.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2300
  $\rightarrow$~READ\_CHECK
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2301
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2302
\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
  2303
  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
  2304
  that reads out the SII attribute for state and data.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2305
  $\rightarrow$~READ\_FETCH
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2306
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2307
\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
  2308
  \textit{Read Operation} and \textit{Busy} parameters are checked:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2309
  \begin{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2310
  \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
  2311
    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
  2312
    is aborted ($\rightarrow$~ERROR), if not, the check/fetch datagram
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2313
    is issued again. $\rightarrow$~READ\_FETCH
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2314
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2315
  \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
  2316
    the datagram and the read cycle is completed.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2317
    $\rightarrow$~END
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2318
  \end{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2319
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2320
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2321
The write access states behave nearly the same:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2322
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2323
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2324
\item[WRITE\_START] The beginning state for writing access,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2325
  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
  2326
  are written to the SII attribute. Nothing can fail.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2327
  $\rightarrow$~WRITE\_CHECK
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2328
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2329
\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
  2330
  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
  2331
  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
  2332
  $\rightarrow$~WRITE\_CHECK2
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2333
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2334
\item[WRITE\_CHECK2] Upon reception of the check datagram, the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2335
  \textit{Write Operation} and \textit{Busy} parameters are checked:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2336
  \begin{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2337
  \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
  2338
    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
  2339
    ($\rightarrow$~ERROR), if not, the check datagram is issued again.
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2340
    $\rightarrow$~WRITE\_CHECK2
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2341
  \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
  2342
    completed. $\rightarrow$~END
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2343
  \end{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2344
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2345
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2346
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2347
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2348
\chapter{Mailbox Protocol Implementations}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2349
\index{Mailbox}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2350
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2351
The EtherCAT master implements the EoE and the CoE mailbox
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2352
protocols. See the below section for details.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2353
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2354
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2355
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2356
\section{Ethernet-over-EtherCAT (EoE)}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2357
\label{sec:eoeimp}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2358
\index{EoE}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2359
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2360
The EtherCAT master implements the Ethernet-over-EtherCAT mailbox
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2361
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
  2362
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
  2363
or have an own IP stack to receive the frames.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2364
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2365
\paragraph{Virtual Network Interfaces}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2366
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2367
The master creates a virtual EoE network interface for every
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2368
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
  2369
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
  2370
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
  2371
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
  2372
master and forwarded to the virtual interfaces.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2373
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2374
This bears the following advantages:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2375
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2376
\begin{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2377
\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
  2378
  interconnected with the rest of the world.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2379
\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
  2380
  configure the EoE interfaces.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2381
\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
  2382
  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
  2383
  bridge Ethernet traffic between EoE-capable slaves.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2384
\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
  2385
  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
  2386
  having physical network interfaces.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2387
\end{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2388
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2389
\paragraph{EoE Handlers}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2390
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2391
The virtual EoE interfaces and the related functionality is encapsulated in the
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2392
\textit{ec\_eoe\_t} class (see section~\ref{sec:class-eoe}).  So the master
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2393
does not create the network interfaces directly: This is done inside the
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2394
constructor of the \textit{ec\_eoe\_t} class. An object of this class is called
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2395
``EoE handler'' below. An EoE handler additionally contains a frame queue. Each
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2396
time, the kernel passes a new socket buffer for sending via the interface's
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2397
\textit{hard\_start\_xmit()} callback, the socket buffer is queued for
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2398
transmission by the EoE state machine (see below). If the queue gets filled up,
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2399
the passing of new socket buffers is suspended with a call to
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2400
\textit{netif\_stop\_queue()}.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2401
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2402
\paragraph{Static Handler Creation}
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 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
  2405
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
  2406
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
  2407
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
  2408
demand (i.~e. on running across a new EoE-capable slave). The latter
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2409
approach was considered as difficult, because of several reasons:
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2410
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2411
\begin{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2412
\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
  2413
  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
  2414
  choosing an appropriate method for cyclic EoE processing.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2415
\item Unregistering network interfaces requires them to be ``down'',
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2416
  which can not be guaranteed upon sudden disappearing of an
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2417
  EoE-capable slave.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2418
\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
  2419
  as possible. Especially the transition from idle to operation mode
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2420
  (and vice versa) causes the rebuilding of the internal data
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2421
  structures. These transitions must be as transparent as possible for
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2422
  the instances using the network interfaces.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2423
\end{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2424
1095
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  2425
\paragraph{Number of Handlers} % FIXME
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2426
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2427
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
  2428
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
  2429
parameter can either be specified when manually loading the master
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2430
module, or (when using the init script) by setting the
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2431
\$EOE\_INTERFACES variable in the sysconfig file (see
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2432
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
  2433
virtual interfaces become available:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2434
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2435
\begin{lstlisting}[gobble=2]
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2436
  # `\textbf{ifconfig -a}`
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2437
  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
  2438
            BROADCAST MULTICAST  MTU:1500  Metric:1
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2439
            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
  2440
            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
  2441
            collisions:0 txqueuelen:1000
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2442
            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
  2443
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2444
  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
  2445
            BROADCAST MULTICAST  MTU:1500  Metric:1
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2446
            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
  2447
            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
  2448
            collisions:0 txqueuelen:1000
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2449
            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
  2450
  ...
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2451
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2452
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2453
\paragraph{Coupling of EoE Slaves}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2454
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2455
During execution of the slave scan state machine (see
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2456
section~\ref{sec:fsm-scan}), the master determines the supported
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2457
mailbox protocols. This is done by examining the ``Supported Mailbox
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2458
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
  2459
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
  2460
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
  2461
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
  2462
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
  2463
the number of EoE handlers must be increased accordingly.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2464
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2465
\paragraph{EoE State Machine}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2466
\index{FSM!EoE}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2467
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2468
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
  2469
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
  2470
communication primitives. This state machine is showed in
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2471
figure~\ref{fig:fsm-eoe}.
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
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2474
  \centering
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2475
  \includegraphics[width=.7\textwidth]{images/fsm-eoe}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2476
  \caption{Transition diagram of the EoE state machine}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2477
  \label{fig:fsm-eoe}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2478
\end{figure}
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
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2481
\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
  2482
  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
  2483
  frames. $\rightarrow$~RX\_CHECK
369
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
\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
  2486
  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
  2487
  $\rightarrow$~TX\_START
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2488
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2489
  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
  2490
  the new data. $\rightarrow$~RX\_FETCH
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2491
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2492
\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
  2493
  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
  2494
  dropped and a transmit sequence is started.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2495
  $\rightarrow$~TX\_START
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2496
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2497
  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
  2498
  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
  2499
  the correct position of the socket buffer.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2500
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2501
  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
  2502
  to the network stack and a transmit sequence is started.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2503
  $\rightarrow$~TX\_START
369
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
  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
  2506
  fragment. $\rightarrow$~RX\_\-START
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2507
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2508
\item[TX\_START] The beginning state of a transmit sequence. It is
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2509
  checked, if the transmission queue contains a frame to send. If not,
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2510
  a receive sequence is started. $\rightarrow$~RX\_START
369
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
  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
  2513
  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
  2514
  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
  2515
  frame is sent. $\rightarrow$~TX\_SENT
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2516
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2517
\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
  2518
  successfully. If the current frame consists of further fragments,
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2519
  the next one is sent. $\rightarrow$~TX\_SENT
369
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
  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
  2522
  $\rightarrow$~RX\_START
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2523
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2524
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2525
\paragraph{EoE Processing}
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
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
  2528
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
  2529
EoE state machines synchronously to the operation state machine (see
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2530
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
  2531
the following disadvantages:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2532
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2533
\begin{itemize}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2534
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2535
\item Only one EoE fragment can be sent or received every few cycles.  This
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2536
causes the data rate to be very low, because the EoE state machines are not
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2537
executed in the time between the application cycles. Moreover, the data rate
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2538
would be dependent on the period of the application task.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2539
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2540
\item The receiving and forwarding of frames to the kernel requires the dynamic
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2541
allocation of frames. Some realtime extensions do not support calling memory
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2542
allocation functions in realtime context, so the EoE state machine may not be
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2543
executed with each application cycle.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2544
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2545
\end{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2546
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2547
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
  2548
asynchronously execute the EoE state machines. For that, the master
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2549
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
  2550
guarantees a constant bandwidth, but poses the new problem of
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2551
concurrent access to the master. The locking mechanisms needed for
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2552
this are introduced in section~\ref{sec:concurr}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2553
Section~\ref{sec:concurrency} gives practical implementation examples.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2554
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2555
\paragraph{Idle phase}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2556
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2557
EoE data must also be exchanged in idle phase, to guarantee the continuous
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2558
availability of the connection to the EoE-capable slaves. Although there is no
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2559
application connected in this case, the master is still accessed by the master
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2560
state machine (see section~\ref{sec:fsm-master}). With the EoE timer running in
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2561
addition, there is still concurrency, that has to be protected by a lock.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2562
Therefore the master owns an internal spinlock that is used protect master
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2563
access during idle phase.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2564
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2565
\paragraph{Automatic Configuration}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2566
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2567
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
  2568
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
  2569
command), the requested slave state of the related slave is
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2570
automatically set to OP, whereupon the idle state machine will attempt
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2571
to configure the slave and put it into operation.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2572
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2573
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2574
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2575
\section{CANopen-over-EtherCAT (CoE)}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2576
\label{sec:coeimp}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2577
\index{CoE}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2578
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2579
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
  2580
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
  2581
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
  2582
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  2583
\paragraph{Sdo Configuration}
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  2584
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2585
The Sdo configurations have to be provided by the application.  This is done
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2586
via the \textit{ecrt\_slave\_conf\_sdo*()} methods (see
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2587
section~\ref{sec:ecrt-slave}), that are part of the realtime interface. The
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2588
slave stores the Sdo configurations in a linked list, but does not apply them
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2589
at once.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2590
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  2591
\paragraph{Sdo Download State Machine}
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  2592
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  2593
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
  2594
state, because mailbox communication is already possible and slave's
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2595
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
  2596
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
  2597
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
  2598
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
  2599
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
  2600
guaranteed that the Sdo configurations are applied each time, the
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2601
slave is reconfigured.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2602
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  2603
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
  2604
in figure~\ref{fig:fsm-coedown}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2605
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2606
\begin{figure}[htbp]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2607
  \centering
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2608
  \includegraphics[width=.9\textwidth]{images/fsm-coedown}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2609
  \caption{Transition diagram of the CoE download state machine}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2610
  \label{fig:fsm-coedown}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2611
\end{figure}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2612
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2613
\begin{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2614
\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
  2615
  machine. The ``Sdo Download Normal Request'' mailbox command is
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2616
  sent. $\rightarrow$~REQUEST
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2617
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2618
\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
  2619
  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
  2620
  and a timer is started. $\rightarrow$~CHECK
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2621
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2622
\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
  2623
  \begin{itemize}
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  2624
  \item If it timed out, the Sdo download is aborted.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2625
    $\rightarrow$~ERROR
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2626
  \item Otherwise, the mailbox is queried again.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2627
    $\rightarrow$~CHECK
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2628
  \end{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2629
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2630
  If the mailbox contains new data, the response is fetched.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2631
  $\rightarrow$~RESPONSE
369
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
\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
  2634
  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
  2635
  Transfer Request'' was received, the Sdo download is aborted.
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2636
  $\rightarrow$~ERROR
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2637
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  2638
  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
  2639
  the Sdo download was successful. $\rightarrow$~END
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  2640
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  2641
\item[END] The Sdo download was successful.
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  2642
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  2643
\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
  2644
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2645
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2646
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2647
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2648
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2649
\chapter{User Space}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2650
\label{sec:user}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2651
\index{User space}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2652
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2653
For the master runs as a kernel module, accessing it is natively
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2654
limited to analyzing Syslog messages and controlling using modutils.
369
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
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
  2657
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
  2658
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
  2659
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2660
Bus visualization is a second point: For development and debugging
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2661
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
  2662
a single command.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2663
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2664
Another aspect is automatic startup and configuration. If the master
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2665
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
  2666
automatically start with a persistent configuration.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2667
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2668
A last thing is monitoring EtherCAT communication. For debugging
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2669
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
  2670
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
  2671
\cite{wireshark} (the former Ethereal) or others.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2672
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2673
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
  2674
tools to make all that possible.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2675
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2676
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2677
1087
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2678
\section{Command-line Tool}
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2679
\label{sec:ethercat}
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2680
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2681
% --master
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2682
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2683
\subsection{Character devices}
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2684
\label{sec:cdev}
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2685
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2686
Each master instance will get a character device as a user-space interface.
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2687
The devices are named \textit{/dev/EtherCATX}, where $X$ is the index of the
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2688
master.
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2689
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2690
% FIXME
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2691
% udev
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2692
% rights
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2693
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2694
%------------------------------------------------------------------------------
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2695
1140
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2696
\subsection{Setting alias addresses}
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2697
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2698
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_alias}
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2699
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2700
%------------------------------------------------------------------------------
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2701
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2702
\subsection{Displaying the bus configuration}
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2703
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2704
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_config}
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2705
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2706
%------------------------------------------------------------------------------
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2707
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2708
\subsection{Displaying process data}
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2709
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2710
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_data}
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2711
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2712
%------------------------------------------------------------------------------
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2713
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2714
\subsection{Setting a master's debug level}
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2715
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2716
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_debug}
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2717
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2718
%------------------------------------------------------------------------------
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2719
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2720
\subsection{Configured domains}
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2721
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2722
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_domains}
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2723
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2724
%------------------------------------------------------------------------------
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2725
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2726
\subsection{Master and Ethernet device information}
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2727
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2728
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_master}
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2729
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2730
%------------------------------------------------------------------------------
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2731
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2732
\subsection{Showing slaves' sync managers, Pdos and Pdo entries}
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2733
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2734
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_pdos}
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2735
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2736
%------------------------------------------------------------------------------
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2737
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2738
\subsection{Displaying the Sdo dictionary}
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2739
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2740
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_sdos}
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2741
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2742
%------------------------------------------------------------------------------
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2743
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2744
\subsection{Sdo access}
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2745
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2746
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_download}
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2747
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2748
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_upload}
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2749
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2750
%------------------------------------------------------------------------------
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2751
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2752
\subsection{Displaying slaves on the bus}
1087
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2753
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2754
Slave information can be gathered with the subcommand \lstinline+slaves+:
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2755
1140
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2756
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_slaves}
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2757
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2758
Below is a typical output:
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2759
1087
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2760
\begin{lstlisting}
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2761
$ `\textbf{ethercat slaves}`
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2762
0     0:0  PREOP  +  EK1100 Ethernet Kopplerklemme (2A E-Bus)
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2763
1  5555:0  PREOP  +  EL3162 2K. Ana. Eingang 0-10V
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2764
2  5555:1  PREOP  +  EL4102 2K. Ana. Ausgang 0-10V
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2765
3  5555:2  PREOP  +  EL2004 4K. Dig. Ausgang 24V, 0,5A
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2766
\end{lstlisting}
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2767
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2768
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2769
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2770
\subsection{SII Access}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2771
\label{sec:siiaccess}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2772
\index{SII!Access}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2773
1087
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2774
It is possible to directly read or write the complete SII contents of the
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2775
slaves. This was introduced for the reasons below:
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2776
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2777
\begin{itemize}
1087
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2778
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2779
\item The format of the SII data is still in development and categories can be
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2780
added in the future. With read and write access, the complete memory contents
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2781
can be easily backed up and restored.
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2782
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2783
\item Some SII data fields have to be altered (like the alias address). A quick
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2784
writing must be possible for that.
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2785
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2786
\item Through reading access, analyzing category data is possible from user
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2787
space.
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2788
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2789
\end{itemize}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2790
1140
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2791
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_sii_read}
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2792
1087
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2793
Reading out SII data is as easy as other commands. Though the data are in
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2794
binary format, analysis is easier with a tool like \textit{hexdump}:
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2795
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2796
\begin{lstlisting}
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2797
$ `\textbf{ethercat sii\_read --slave 3 | hexdump}`
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2798
0000000 0103 0000 0000 0000 0000 0000 0000 008c
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2799
0000010 0002 0000 3052 07f0 0000 0000 0000 0000
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2800
0000020 0000 0000 0000 0000 0000 0000 0000 0000
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2801
...
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2802
\end{lstlisting}
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2803
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2804
Backing up SII contents can easily done with a redirection:
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2805
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2806
\begin{lstlisting}
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2807
$ `\textbf{ethercat sii\_read --slave 3 > sii-of-slave3.bin}`
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2808
\end{lstlisting}
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2809
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2810
To download SII contents to a slave, writing access to the master's character
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2811
device is necessary (see section~\ref{sec:cdev}).
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2812
1140
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2813
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_sii_write}
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2814
1087
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2815
\begin{lstlisting}
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2816
# `\textbf{ethercat sii\_write --slave 3 sii-of-slave3.bin}`
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2817
\end{lstlisting}
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2818
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2819
The SII contents will be checked for validity and then sent to the slave. The
f1417824cee5 prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents: 1086
diff changeset
  2820
write operation may take a few seconds.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2821
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2822
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2823
1140
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2824
\subsection{Requesting application-layer states}
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2825
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2826
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_states}
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2827
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2828
%------------------------------------------------------------------------------
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2829
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2830
\subsection{Generating slave description XML}
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2831
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2832
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_xml}
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2833
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2834
%------------------------------------------------------------------------------
cc779f7d2496 Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents: 1107
diff changeset
  2835
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2836
\section{System Integration}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2837
\label{sec:system}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2838
1086
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2839
To integrate the EtherCAT master as a service into a running system, it comes
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2840
with an init script and a sysconfig file, that are described below.
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2841
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2842
\subsection{Init Script}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2843
\label{sec:init}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2844
\index{Init script}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2845
1086
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2846
The EtherCAT master init script conforms to the requirements of the ``Linux
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2847
Standard Base'' (LSB\index{LSB}, \cite{lsb}). The script is installed to
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2848
\textit{etc/init.d/ethercat} below the installation prefix and has to be copied
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2849
(or better: linked) to the appropriate location (see
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2850
section~\ref{sec:install}), before the master can be inserted as a service.
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2851
Please note, that the init script depends on the sysconfig file described
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2852
below.
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2853
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2854
To provide service dependencies (i.~e. which services have to be started before
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2855
others) inside the init script code, LSB defines a special comment block.
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2856
System tools can extract this information to insert the EtherCAT init script at
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2857
the correct place in the startup sequence:
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2858
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2859
\lstinputlisting[firstline=38,lastline=48]
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2860
    {../script/init.d/ethercat}
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2861
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2862
\subsection{Sysconfig}
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2863
\label{sec:sysconfig}
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2864
\index{Sysconfig file}
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2865
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2866
For persistent configuration, the init script uses a sysconfig file installed
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2867
to \textit{etc/sysconfig/ethercat} (below the installation prefix), that is
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2868
mandatory for the init script. The sysconfig file contains all configuration
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2869
variables needed to operate one or more masters. The documentation is inside
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2870
the file and included below:
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2871
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2872
\lstinputlisting[numbers=left,firstline=9,basicstyle=\ttfamily\scriptsize]
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2873
    {../script/sysconfig/ethercat}
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2874
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2875
\subsection{Service}
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2876
\label{sec:service}
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2877
\index{Service}
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2878
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2879
After the init script and the sysconfig file are placed into the right
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2880
location, the EtherCAT master can be inserted as a service. The different Linux
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2881
distributions offer different ways to mark a service for starting and stopping
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2882
in certain runlevels. For example, SUSE Linux provides the \textit{insserv}
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2883
command:
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2884
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2885
\begin{lstlisting}
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  2886
# `\textbf{insserv ethercat}`
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2887
\end{lstlisting}
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
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
  2890
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
  2891
\texttt{start}, \texttt{stop}, \texttt{restart} or \texttt{status}.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2892
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2893
\begin{lstlisting}[gobble=2]
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  2894
  # `\textbf{/etc/init.d/ethercat restart}`
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2895
  Shutting down EtherCAT master                done
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2896
  Starting EtherCAT master                     done
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2897
\end{lstlisting}
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
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2900
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2901
\section{Monitoring and Debugging}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2902
\label{sec:debug}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2903
\index{Monitoring}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2904
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2905
For debugging purposes, every EtherCAT master registers a read-only network
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2906
interface \textit{ecX}, where X is a number, provided by the kernel on device
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2907
registration. While it is ``up'', the master forwards every frame sent and
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2908
received to this interface.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2909
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2910
This makes it possible to connect an network monitor (like Wireshark or
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2911
tcpdump) to the debug interface and monitor the EtherCAT frames.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2912
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2913
% FIXME schedule()
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2914
It has to be considered, that can be frame rate can be very high. The master
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2915
state machine usually runs every kernel timer interrupt (usually up to
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2916
\unit{1}{\kilo\hertz}) and with a connected application, the rate can be even
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2917
higher.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2918
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2919
\paragraph{Attention:} The socket buffers needed for the operation of
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2920
the debugging interface have to be allocated dynamically. Some Linux
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2921
realtime extensions do not allow this in realtime context!
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2922
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2923
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2924
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2925
\chapter{Timing Aspects}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2926
\label{sec:timing}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2927
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2928
Although EtherCAT's timing is highly deterministic and therefore timing issues
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2929
are rare, there are a few aspects that can (and should be) dealt with.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2930
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
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2933
\subsection{Realtime Interface Profiling}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2934
\label{sec:timing-profile}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2935
\index{Realtime!Profiling}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2936
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2937
One of the most important timing aspects are the execution times of the
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2938
realtime interface functions, that are called in cyclic context. These
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2939
functions make up an important part of the overall timing of the application.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2940
To measure the timing of the functions, the following code was used:
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2941
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2942
\begin{lstlisting}[gobble=2,language=C]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2943
  c0 = get_cycles();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2944
  ecrt_master_receive(master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2945
  c1 = get_cycles();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2946
  ecrt_domain_process(domain1);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2947
  c2 = get_cycles();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2948
  ecrt_master_run(master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2949
  c3 = get_cycles();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2950
  ecrt_master_send(master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2951
  c4 = get_cycles();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2952
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2953
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2954
Between each call of an interface function, the CPU timestamp counter is read.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2955
The counter differences are converted to \micro\second\ with help of the
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2956
\lstinline+cpu_khz+ variable, that contains the number of increments per
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2957
\milli\second.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2958
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2959
For the actual measuring, a system with a \unit{2.0}{\giga\hertz} CPU was used,
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2960
that ran the above code in an RTAI thread with a period of
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2961
\unit{100}{\micro\second}. The measuring was repeated $n = 100$ times and the
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2962
results were averaged. These can be seen in table~\ref{tab:profile}.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2963
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2964
\begin{table}[htpb]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2965
  \centering
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2966
  \caption{Profiling of a Realtime Cycle on a \unit{2.0}{\giga\hertz}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2967
  Processor}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2968
  \label{tab:profile}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2969
  \vspace{2mm}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2970
  \begin{tabular}{l|r|r}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2971
    Element & Mean Duration [\second] & Standard Deviancy [\micro\second] \\
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2972
    \hline
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2973
    \textit{ecrt\_master\_receive()} & 8.04 & 0.48\\
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2974
    \textit{ecrt\_domain\_process()} & 0.14 & 0.03\\
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2975
    \textit{ecrt\_master\_run()} & 0.29 & 0.12\\
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2976
    \textit{ecrt\_master\_send()} & 2.18 & 0.17\\ \hline
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2977
    Complete Cycle & 10.65 & 0.69\\ \hline
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2978
  \end{tabular}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2979
\end{table}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2980
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2981
It is obvious, that the functions accessing hardware make up the
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2982
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
  2983
the Ethernet device, analyzes datagrams and copies their contents into
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2984
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
  2985
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
  2986
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
  2987
receiving time.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2988
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2989
The functions that only operate on the masters internal data structures are
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2990
very fast ($\Delta t < \unit{1}{\micro\second}$). Interestingly the runtime of
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2991
\textit{ec\_domain\_process()} has a small standard deviancy relative to the
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2992
mean value, while this ratio is about twice as big for
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2993
\textit{ec\_master\_run()}: This probably results from the latter function
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2994
having to execute code depending on the current state and the different state
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2995
functions are more or less complex.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2996
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2997
For a realtime cycle makes up about \unit{10}{\micro\second}, the theoretical
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  2998
frequency can be up to \unit{100}{\kilo\hertz}. For two reasons, this frequency
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  2999
keeps being theoretical:
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{enumerate}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3002
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3003
\item The processor must still be able to run the operating system between the
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3004
realtime cycles.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3005
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3006
\item The EtherCAT frame must be sent and received, before the next realtime
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3007
cycle begins. The determination of the bus cycle time is difficult and covered
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3008
in section~\ref{sec:timing-bus}.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3009
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3010
\end{enumerate}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3011
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
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3014
\subsection{Bus Cycle Measuring}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3015
\label{sec:timing-bus}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3016
\index{Bus cycle}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3017
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3018
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
  3019
must be be taken:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3020
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3021
\begin{enumerate}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3022
\item The time, the Ethernet hardware begins with physically sending
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3023
  the frame.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3024
\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
  3025
  hardware.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3026
\end{enumerate}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3027
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3028
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
  3029
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
  3030
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
  3031
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
  3032
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
  3033
determine the bus cycle time is an electrical measuring.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3034
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3035
Anyway, the bus cycle time is an important factor when designing realtime code,
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3036
because it limits the maximum frequency for the cyclic task of the application.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3037
In practice, these timing parameters are highly dependent on the hardware and
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3038
often a trial and error method must be used to determine the limits of the
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3039
system.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3040
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3041
The central question is: What happens, if the cycle frequency is too high? The
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3042
answer is, that the EtherCAT frames that have been sent at the end of the cycle
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3043
are not yet received, when the next cycle starts.  First this is noticed by
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3044
\textit{ecrt\_domain\_process()}, because the working counter of the process
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3045
data datagrams were not increased. The function will notify the user via
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3046
Syslog\footnote{To limit Syslog output, a mechanism has been implemented, that
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3047
outputs a summarized notification at maximum once a second.}. In this case, the
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3048
process data keeps being the same as in the last cycle, because it is not
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3049
erased by the domain. When the domain datagrams are queued again, the master
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3050
notices, that they are already queued (and marked as sent). The master will
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3051
mark them as unsent again and output a warning, that datagrams were
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3052
``skipped''.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3053
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3054
On the mentioned \unit{2.0}{\giga\hertz} system, the possible cycle frequency
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3055
can be up to \unit{25}{\kilo\hertz} without skipped frames. This value can
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3056
surely be increased by choosing faster hardware. Especially the RealTek network
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3057
hardware could be replaced by a faster one. Besides, implementing a dedicated
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3058
ISR for EtherCAT devices would also contribute to increasing the latency. These
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3059
are two points on the author's to-do list.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3060
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3061
%------------------------------------------------------------------------------
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3062
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3063
\chapter{Installation}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3064
\label{sec:installation}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3065
\index{Master!Installation}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3066
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3067
\section{Building the software}
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3068
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3069
The current EtherCAT master code is available at~\cite{etherlab} or can be
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3070
obtained from the EtherLab CD. The \textit{tar.bz2} file has to be unpacked
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3071
with the commands below (or similar):
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3072
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3073
\begin{lstlisting}[gobble=2]
487
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
  3074
  `\$` `\textbf{tar xjf ethercat-\masterversion.tar.bz2}`
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
  3075
  `\$` `\textbf{cd ethercat-\masterversion/}`
374
e43a29f9079e Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents: 371
diff changeset
  3076
\end{lstlisting}
e43a29f9079e Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents: 371
diff changeset
  3077
e43a29f9079e Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents: 371
diff changeset
  3078
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
  3079
follows the below commands:
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3080
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3081
\begin{lstlisting}[gobble=2]
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3082
  `\$` `\textbf{./configure}`
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3083
  `\$` `\textbf{make}`
487
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
  3084
  `\$` `\textbf{make modules}`
374
e43a29f9079e Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents: 371
diff changeset
  3085
\end{lstlisting}
e43a29f9079e Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents: 371
diff changeset
  3086
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3087
Table~\ref{tab:config} lists important configuration switches and options.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3088
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3089
\begin{table}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3090
  \caption{Configuration options}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3091
  \label{tab:config}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3092
  \vspace{2mm}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3093
  \begin{tabular}{l|p{.3\textwidth}|l}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3094
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3095
\bf Option/Switch & \bf Description & \bf Default\\\hline
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3096
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3097
\lstinline+--prefix+ & Installation prefix & \textit{/opt/etherlab}\\
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3098
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3099
\lstinline+--with-linux-dir+ & Linux kernel sources & Use running kernel\\
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3100
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3101
\lstinline+--with-rtai-dir+ & RTAI path (only for RTAI example) & \\
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3102
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3103
\hline
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3104
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3105
\lstinline+--enable-eoe+ & Enable EoE support & yes\\
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3106
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3107
\lstinline+--enable-cycles+ & Use CPU timestamp counter. Enable this on Intel
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3108
architecture to get finer timing calculation. & no\\
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3109
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3110
\lstinline+--enable-debug-if+ & Create a debug interface for each master & no\\
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3111
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3112
\lstinline+--enable-debug-ring+ & Create a debug ring to record frames & no\\
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3113
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3114
\hline
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3115
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3116
\lstinline+--enable-8139too+ & Build the 8139too driver & yes\\
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3117
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3118
\lstinline+--with-8139too-kernel+ & 8139too kernel & $\dagger$\\
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3119
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3120
\lstinline+--enable-e100+ & Build the e100 driver & no\\
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3121
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3122
\lstinline+--with-e100-kernel+ & e100 kernel & $\dagger$\\
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3123
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3124
\lstinline+--enable-forcedeth+ & Enable forcedeth driver & no\\
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3125
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3126
\lstinline+--with-forcedeth-kernel+ & forcedeth kernel & $\dagger$\\
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3127
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3128
\lstinline+--enable-e1000+ & Enable e1000 driver & no\\
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3129
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3130
\lstinline+--with-e1000-kernel+ & e1000 kernel & $\dagger$\\
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3131
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3132
\lstinline+--enable-r8169+ & Enable r8169 driver & no\\
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3133
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3134
\lstinline+--with-r8169-kernel+ & r8169 kernel & $\dagger$\\
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3135
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3136
  \end{tabular}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3137
  \vspace{2mm}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3138
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3139
\begin{description}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3140
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3141
\item[$\dagger$] If this option is not specified, the kernel version to use is
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3142
extracted from the Linux kernel sources.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3143
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3144
\end{description}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3145
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3146
\end{table}
487
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
  3147
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3148
\section{Building the documentation}
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3149
\label{sec:gendoc}
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3150
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3151
The source code is documented using Doxygen~\cite{doxygen}. To build the HTML
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3152
documentation, you must have the Doxygen software installed. The below command
1095
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  3153
will generate the documents in the subdirectory \textit{doxygen-output}:
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3154
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3155
\begin{lstlisting}
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3156
$ `\textbf{make doc}`
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3157
\end{lstlisting}
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3158
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3159
To view them, point your browser to \textit{doxygen-output/html/index.html}.
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3160
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3161
\section{Installation}
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3162
1106
745a0cc03143 Added depmod call to docs.
Florian Pose <fp@igh-essen.com>
parents: 1095
diff changeset
  3163
The below commands have to be entered as \textit{root}: The first one will
745a0cc03143 Added depmod call to docs.
Florian Pose <fp@igh-essen.com>
parents: 1095
diff changeset
  3164
install the EtherCAT header, init script, sysconfig file and the user space
745a0cc03143 Added depmod call to docs.
Florian Pose <fp@igh-essen.com>
parents: 1095
diff changeset
  3165
tools to the prefix path. The second one will install the kernel modules to the
745a0cc03143 Added depmod call to docs.
Florian Pose <fp@igh-essen.com>
parents: 1095
diff changeset
  3166
kernel's modules directory. The following \lstinline+depmod+ call is necessary
745a0cc03143 Added depmod call to docs.
Florian Pose <fp@igh-essen.com>
parents: 1095
diff changeset
  3167
to include the kernel modules into the \textit{modules.dep} file to make it
745a0cc03143 Added depmod call to docs.
Florian Pose <fp@igh-essen.com>
parents: 1095
diff changeset
  3168
available to the \lstinline+modprobe+ command, used in the init script. 
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3169
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3170
\begin{lstlisting}
1106
745a0cc03143 Added depmod call to docs.
Florian Pose <fp@igh-essen.com>
parents: 1095
diff changeset
  3171
# `\textbf{make install}`
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3172
# `\textbf{make modules\_install}`
1106
745a0cc03143 Added depmod call to docs.
Florian Pose <fp@igh-essen.com>
parents: 1095
diff changeset
  3173
# `\textbf{depmod}`
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3174
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3175
1095
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  3176
If the target kernel's modules directory is not under \textit{/lib/modules}, a
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  3177
different destination directory can be specified with the \lstinline+DESTDIR+
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  3178
make variable. For example:
487
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
  3179
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3180
\begin{lstlisting}
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3181
# `\textbf{make DESTDIR=/vol/nfs/root modules\_install}`
487
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
  3182
\end{lstlisting}
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
  3183
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
  3184
This command will install the compiled kernel modules to
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
  3185
\textit{/vol/nfs/root/lib/modules}, prepended by the kernel release.
448b0b23b905 Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 379
diff changeset
  3186
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3187
If the EtherCAT master shall be run as a service\footnote{Even if the EtherCAT
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3188
master shall not be loaded on system startup, the use of the init script is
1086
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  3189
recommended for manual (un-)loading.} (see section~\ref{sec:system}), the init
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  3190
script and the sysconfig file have to be copied (or linked) to the appropriate
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  3191
locations. The below example is suitable for SUSE Linux. It may vary for other
722ead4ecc22 Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents: 1085
diff changeset
  3192
distributions.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3193
1107
Florian Pose <fp@igh-essen.com>
parents: 1106
diff changeset
  3194
% FIXME relative ln -s?
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3195
\begin{lstlisting}
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3196
# `\textbf{cd /opt/etherlab}`
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3197
# `\textbf{cp etc/sysconfig/ethercat /etc/sysconfig/}`
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3198
# `\textbf{ln -s etc/init.d/ethercat /etc/init.d/}`
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3199
# `\textbf{insserv ethercat}`
374
e43a29f9079e Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents: 371
diff changeset
  3200
\end{lstlisting}
e43a29f9079e Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents: 371
diff changeset
  3201
376
d1441d87f5c1 Documentation: EtherLab-CD; obtaining the DEVICE_INDEX.
Florian Pose <fp@igh-essen.com>
parents: 374
diff changeset
  3202
Now the sysconfig file \texttt{/etc/sysconfig/ethercat} (see
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3203
section~\ref{sec:sysconfig}) has to be customized. The minimal customization
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3204
is to set the \lstinline+MASTER0_DEVICE+ variable to the MAC address of the
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3205
Ethernet device to use (or \lstinline+ff:ff:ff:ff:ff:ff+ to use the first
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3206
device offered) and selecting the driver(s) to load via the
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3207
\lstinline+DEVICE_MODULES+ variable.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3208
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3209
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
  3210
the below command:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3211
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3212
\begin{lstlisting}
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3213
# `\textbf{/etc/init.d/ethercat start}`
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3214
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3215
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3216
The operation of the master can be observed by looking at the
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3217
Syslog\index{Syslog} messages, which should look like the ones below.  If
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3218
EtherCAT slaves are connected to the master's EtherCAT device, the activity
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3219
indicators should begin to flash.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3220
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3221
\begin{lstlisting}[numbers=left]
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3222
EtherCAT: Master driver `\masterversion`
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3223
EtherCAT: 1 master waiting for devices.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3224
EtherCAT Intel(R) PRO/1000 Network Driver - version 6.0.60-k2
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3225
Copyright (c) 1999-2005 Intel Corporation.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3226
PCI: Found IRQ 12 for device 0000:01:01.0
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3227
PCI: Sharing IRQ 12 with 0000:00:1d.2
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3228
PCI: Sharing IRQ 12 with 0000:00:1f.1
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3229
EtherCAT: Accepting device 00:0E:0C:DA:A2:20 for master 0.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3230
EtherCAT: Starting master thread.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3231
ec_e1000: ec0: e1000_probe: Intel(R) PRO/1000 Network
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3232
          Connection
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3233
ec_e1000: ec0: e1000_watchdog_task: NIC Link is Up 100 Mbps
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3234
          Full Duplex
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3235
EtherCAT: Link state changed to UP.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3236
EtherCAT: 7 slave(s) responding.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3237
EtherCAT: Slave states: PREOP.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3238
EtherCAT: Scanning bus.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3239
EtherCAT: Bus scanning completed in 431 ms.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3240
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3241
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3242
\begin{description}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3243
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3244
\item[\linenum{1} -- \linenum{2}] The master module is loading, and one master
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3245
is initialized.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3246
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3247
\item[\linenum{3} -- \linenum{8}] The EtherCAT-capable e1000 driver is
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3248
loading. The master accepts the device with the address
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3249
\lstinline+00:0E:0C:DA:A2:20+.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3250
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3251
\item[\linenum{9} -- \linenum{16}] The master goes to idle phase, starts its
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3252
state machine and begins scanning the bus.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3253
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3254
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3255
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3256
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3257
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3258
\chapter{Application examples}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3259
\label{chapter:examples}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3260
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3261
This chapter will give practical examples of how to use the EtherCAT master via
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3262
the realtime interface by writing an application module.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3263
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3264
%------------------------------------------------------------------------------
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3265
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3266
\section{Minimal Example}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3267
\label{sec:mini}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3268
\index{Examples!Minimal}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3269
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3270
This section will explain the use of the EtherCAT master from a minimal kernel
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3271
module. The complete module code is obtainable as a part of the EtherCAT master
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3272
code release (see~\cite{etherlab}, file \textit{examples/mini/mini.c}).
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3273
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3274
The minimal example uses a kernel timer (software interrupt) to generate a
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3275
cyclic task. After the timer function is executed, it re-adds itself with a
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3276
delay of one \textit{jiffy}\index{jiffies}, which results in a timer frequency
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3277
of \textit{HZ}\nomenclature{HZ}{Kernel macro containing the timer interrupt
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3278
frequency}
369
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
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
  3281
in listing~\ref{lst:minivar}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3282
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3283
\begin{lstlisting}[gobble=2,language=C,numbers=left,caption={Minimal
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3284
    variables},label=lst:minivar]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3285
  struct timer_list timer;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3286
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3287
  ec_master_t *master = NULL;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3288
  ec_domain_t *domain1 = NULL;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3289
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3290
  void *r_dig_in, *r_ana_out;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3291
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3292
  ec_pdo_reg_t domain1_pdos[] = {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3293
          {"1", Beckhoff_EL1014_Inputs, &r_dig_in},
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3294
          {"2", Beckhoff_EL4132_Ouput1, &r_ana_out},
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3295
          {}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3296
  };
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3297
\end{lstlisting}
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
\begin{description}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3300
\item[\linenum{1}] There is a timer object
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3301
  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
  3302
  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
  3303
  variable of the \textit{timer\_list} structure.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3304
\item[\linenum{3} -- \linenum{4}] There
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3305
  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
  3306
  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
  3307
  that will manage process data IO.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3308
\item[\linenum{6}] The pointers \textit{r\_*}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3309
  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
  3310
  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
  3311
  call to \textit{ec\_\-master\_\-activate()}, that will create the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3312
  domain memory and configure the mapped process data image.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3313
\item[\linenum{8} -- \linenum{12}] The
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  3314
  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
  3315
  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
  3316
  \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
  3317
  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
  3318
  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
  3319
  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
  3320
  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
  3321
  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
  3322
  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
  3323
  be redirected appropriately. Attention: The initialization array
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3324
  must end with an empty record (\textit{\{\}})!
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3325
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3326
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3327
The initialization of the minimal application is done by the ``Minimal init
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3328
function'' in listing~\ref{lst:miniinit}.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3329
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3330
\begin{lstlisting}[gobble=2,language=C,numbers=left,caption={Minimal init
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3331
    function},label={lst:miniinit}]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3332
  int __init init_mini_module(void)
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3333
  {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3334
          if (!(master = ecrt_request_master(0))) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3335
                  goto out_return;
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
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3338
          if (!(domain1 = ecrt_master_create_domain(master))) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3339
                  goto out_release_master;
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
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3342
          if (ecrt_domain_register_pdo_list(domain1,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3343
                                            domain1_pdos)) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3344
                  goto out_release_master;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3345
          }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3346
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3347
          if (ecrt_master_activate(master)) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3348
                  goto out_release_master;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3349
          }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3350
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3351
          ecrt_master_prepare(master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3352
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3353
          init_timer(&timer);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3354
          timer.function = run;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3355
          timer.expires = jiffies + 10;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3356
          add_timer(&timer);
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
          return 0;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3359
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3360
        out_release_master:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3361
          ecrt_release_master(master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3362
        out_return:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3363
          return -1;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3364
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3365
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3366
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3367
\begin{description}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3368
\item[\linenum{3}] It is tried to request the
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3369
  first EtherCAT master (index 0). On success, the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3370
  \textit{ecrt\_\-request\_\-master()} function returns a pointer to
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3371
  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
  3372
  functions calls. On failure, the function returns \textit{NULL}.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3373
\item[\linenum{7}] In order to exchange process
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3374
  data, a domain object has to be created. The
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3375
  \textit{ecrt\_\-master\_\-create\_domain()} function also returns a
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3376
  pointer to the created domain, or \textit{NULL} in error case.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3377
\item[\linenum{11}] The registration of domain
814
a51f857b1b2d Renamed [PS]DO to [PS]do.
Florian Pose <fp@igh-essen.com>
parents: 813
diff changeset
  3378
  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
  3379
  Alternatively the data fields could be registered with individual
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3380
  calls of \textit{ecrt\_domain\_register\_pdo()}.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3381
\item[\linenum{16}] After the configuration of
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3382
  process data mapping, the master can be activated for cyclic
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3383
  operation. This will configure all slaves and bring them into
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3384
  OP state.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3385
\item[\linenum{20}] This call is needed to avoid
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3386
  a case differentiation in cyclic operation: The first operation in
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3387
  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
  3388
  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
  3389
  \textit{if}-statement to avoid a warning. A call to
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3390
  \textit{ec\_master\_prepare()} sends a first datagram containing a
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3391
  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
  3392
  not fail.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3393
\item[\linenum{22} -- \linenum{25}] The
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3394
  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
  3395
  cyclically executes the \textit{run()} function is initialized and
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3396
  started.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3397
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3398
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3399
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
  3400
listing~\ref{lst:miniclean}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3401
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3402
\begin{lstlisting}[gobble=2,language=C,numbers=left,caption={Minimal cleanup
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3403
    function},label={lst:miniclean}]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3404
  void __exit cleanup_mini_module(void)
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3405
  {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3406
          del_timer_sync(&timer);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3407
          ecrt_master_deactivate(master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3408
          ecrt_release_master(master);
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
\end{lstlisting}
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
\begin{description}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3413
\item[\linenum{3}] To cleanup the module, it it
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3414
  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
  3415
  \textit{del\_timer\_sync()} which safely removes a queued timer
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3416
  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
  3417
  call returns.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3418
\item[\linenum{4}] This call deactivates the
379
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3419
  master, which results in all slaves being brought to their INIT
7db3d4f573fa Updated documentation.
Florian Pose <fp@igh-essen.com>
parents: 376
diff changeset
  3420
  state again.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3421
\item[\linenum{5}] This call releases the master,
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3422
  removes any existing configuration and silently starts the idle
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3423
  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
  3424
  the module can be safely unloaded.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3425
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3426
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3427
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
  3428
coding can be seen in listing~\ref{lst:minirun}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3429
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3430
\begin{lstlisting}[gobble=2,language=C,numbers=left,caption={Minimal cyclic
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3431
    function},label={lst:minirun}]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3432
  void run(unsigned long data)
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3433
  {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3434
          static uint8_t dig_in_0;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3435
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3436
          ecrt_master_receive(master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3437
          ecrt_domain_process(domain1);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3438
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3439
          dig_in_0 = EC_READ_BIT(r_dig_in, 0);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3440
          EC_WRITE_S16(r_ana_out, dig_in_0 * 0x3FFF);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3441
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3442
          ecrt_master_run(master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3443
          ecrt_master_send(master);
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
          timer.expires += 1; // frequency = HZ
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3446
          add_timer(&timer);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3447
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3448
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3449
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3450
\begin{description}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3451
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3452
\item[\linenum{5}] The cyclic processing starts with receiving datagrams, that
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3453
were sent in the last cycle. The frames containing these datagrams have to be
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3454
received by the network interface card prior to this call.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3455
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3456
\item[\linenum{6}] The process data of domain 1 has been automatically copied
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3457
into domain memory while datagram reception. This call checks the working
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3458
counter for changes and re-queues the domain's datagram for sending.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3459
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3460
\item[\linenum{8}] This is an example for reading out a bit-oriented process
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3461
data value (i.~e. bit 0) via the \textit{EC\_READ\_BIT()} macro. See
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3462
section~\ref{sec:macros} for more information about those macros.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3463
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3464
\item[\linenum{9}] This line shows how to write a signed, 16-bit process data
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3465
value. In this case, the slave is able to output voltages of
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3466
\unit{-10--+10}{\volt} with a resolution of \unit{16}{bit}.  This write command
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3467
outputs either \unit{0}{\volt} or \unit{+5}{\volt}, depending of the value of
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3468
\textit{dig\_in\_0}.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3469
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3470
\item[\linenum{11}] This call runs the master's operation state machine (see
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3471
section~\ref{sec:fsm-op}). A single state is processed, and datagrams are
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3472
queued. Mainly bus observation is done: The bus state is determined and in case
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3473
of slaves that lost their configuration, reconfiguration is tried.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3474
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3475
\item[\linenum{12}] This method sends all queued datagrams, in this case the
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3476
domain's datagram and one of the master state machine. In best case, all
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3477
datagrams fit into one frame.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3478
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3479
\item[\linenum{14} -- \linenum{15}] Kernel timers are implemented as
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3480
``one-shot'' timers, so they have to be re-added after each execution. The time
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3481
of the next execution is specified in \textit{jiffies} and will happen at the
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3482
time of the next system timer interrupt. This results in the \textit{run()}
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3483
function being executed with a frequency of \textit{HZ}.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3484
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3485
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3486
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3487
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3488
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3489
\section{RTAI Example}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3490
\label{sec:rtai}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3491
\index{Examples!RTAI}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3492
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3493
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
  3494
(see~\cite{etherlab}, file \textit{examples/rtai/rtai\_sample.c}).
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3495
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3496
Listing~\ref{lst:rtaivar} shows the defines and global variables
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3497
needed for a minimal RTAI module with EtherCAT processing.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3498
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3499
\begin{lstlisting}[gobble=2,language=C,numbers=left,caption={RTAI task
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3500
    declaration},label={lst:rtaivar}]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3501
  #define FREQUENCY 10000
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3502
  #define TIMERTICKS (1000000000 / FREQUENCY)
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3503
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3504
  RT_TASK task;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3505
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3506
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3507
\begin{description}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3508
\item[\linenum{1} -- \linenum{2}] RTAI
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3509
  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
  3510
  define a frequency and convert it to a cycle time in nanoseconds.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3511
\item[\linenum{4}] The \textit{task} variable
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3512
  later contains information about the running RTAI task.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3513
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3514
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3515
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
  3516
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
  3517
differences come up when starting the cyclic code.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3518
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3519
\begin{lstlisting}[gobble=2,language=C,numbers=left,caption={RTAI module init
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3520
    function},label={lst:rtaiinit}]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3521
  int __init init_mod(void)
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3522
  {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3523
          RTIME requested_ticks, tick_period, now;
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
          if (!(master = ecrt_request_master(0))) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3526
                  goto out_return;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3527
          }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3528
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3529
          if (!(domain1 = ecrt_master_create_domain(master))) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3530
                  goto out_release_master;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3531
          }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3532
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3533
          if (ecrt_domain_register_pdo_list(domain1,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3534
                                            domain1_pdos)) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3535
                  goto out_release_master;
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
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3538
          if (ecrt_master_activate(master)) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3539
                  goto out_release_master;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3540
          }
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
          ecrt_master_prepare(master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3543
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3544
          requested_ticks = nano2count(TIMERTICKS);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3545
          tick_period = start_rt_timer(requested_ticks);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3546
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3547
          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
  3548
                  goto out_stop_timer;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3549
          }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3550
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3551
          now = rt_get_time();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3552
          if (rt_task_make_periodic(&task, now + tick_period,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3553
                                    tick_period)) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3554
                  goto out_stop_task;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3555
          }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3556
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3557
          return 0;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3558
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3559
      out_stop_task:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3560
          rt_task_delete(&task);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3561
      out_stop_timer:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3562
          stop_rt_timer();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3563
      out_deactivate:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3564
          ecrt_master_deactivate(master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3565
      out_release_master:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3566
          ecrt_release_master(master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3567
      out_return:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3568
          return -1;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3569
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3570
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3571
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3572
\begin{description}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3573
\item[\linenum{24} -- \linenum{25}] The
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3574
  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
  3575
  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
  3576
  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
  3577
  one).
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3578
\item[\linenum{27}] The RTAI task is initialized
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3579
  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
  3580
  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
  3581
  floating point operations and a signal handler.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3582
\item[\linenum{32}] The task is made periodic by
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3583
  specifying a start time and a period.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3584
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3585
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3586
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
  3587
is nearly as simple as that of the minimal module.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3588
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3589
\begin{lstlisting}[gobble=2,language=C,numbers=left,caption={RTAI module
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3590
    cleanup function},label={lst:rtaiclean}]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3591
  void __exit cleanup_mod(void)
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3592
  {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3593
          rt_task_delete(&task);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3594
          stop_rt_timer();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3595
          ecrt_master_deactivate(master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3596
          ecrt_release_master(master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3597
          rt_sem_delete(&master_sem);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3598
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3599
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3600
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3601
\begin{description}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3602
\item[\linenum{2}] The RTAI task will be stopped
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3603
  and deleted.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3604
\item[\linenum{3}] After that, the RTAI timer can
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3605
  be stopped.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3606
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3607
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3608
The rest is the same as for the minimal module.
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
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
  3611
(listing~\ref{lst:rtairun}) has a slightly different architecture. The
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3612
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
  3613
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
  3614
each cycle.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3615
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3616
\begin{lstlisting}[gobble=2,language=C,numbers=left,caption={RTAI module cyclic
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3617
    function},label={lst:rtairun}]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3618
  void run(long data)
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3619
  {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3620
          while (1) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3621
                  ecrt_master_receive(master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3622
                  ecrt_domain_process(domain1);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3623
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3624
                  k_pos = EC_READ_U32(r_ssi_input);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3625
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3626
                  ecrt_master_run(master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3627
                  ecrt_master_send(master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3628
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3629
                  rt_task_wait_period();
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
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3633
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3634
\begin{description}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3635
\item[\linenum{3}] The \textit{while (1)} loop
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3636
  executes for the lifetime of the RTAI task.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3637
\item[\linenum{12}] The
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3638
  \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
  3639
  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
  3640
  checks, if the cyclic function has to be terminated.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3641
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3642
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3643
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3644
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3645
\section{Concurrency Example}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3646
\label{sec:concurrency}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3647
\index{Examples!Concurrency}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3648
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3649
As mentioned before, there can be concurrent access to the EtherCAT master. The
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3650
application and a EoE\index{EoE} process can compete for master access, for
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3651
example. In this case, the module has to provide the locking mechanism, because
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3652
it depends on the module's architecture which lock has to be used. The module
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3653
makes this locking mechanism available to the master through the master's
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3654
locking callbacks.
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3655
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3656
In case of RTAI, the lock can be an RTAI semaphore, as shown in
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3657
listing~\ref{lst:convar}. A normal Linux semaphore would not be appropriate,
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3658
because it could not block the RTAI task due to RTAI running in a higher domain
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3659
than the Linux kernel (see~\cite{rtai}).
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3660
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3661
\begin{lstlisting}[gobble=2,language=C,numbers=left,caption={RTAI semaphore for
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3662
    concurrent access},label={lst:convar}]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3663
  SEM master_sem;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3664
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3665
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3666
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
  3667
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
  3668
listing~\ref{lst:conlock}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3669
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3670
\begin{lstlisting}[gobble=2,language=C,numbers=left,caption={RTAI locking
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3671
    callbacks for concurrent access},label={lst:conlock}]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3672
  int request_lock(void *data)
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3673
  {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3674
          rt_sem_wait(&master_sem);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3675
          return 0;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3676
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3677
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3678
  void release_lock(void *data)
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3679
  {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3680
          rt_sem_signal(&master_sem);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3681
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3682
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3683
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3684
\begin{description}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3685
\item[\linenum{1}] The \textit{request\_lock()}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3686
  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
  3687
  that was specified when registering the callback function. This can
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3688
  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
  3689
  integer return value (see line 4).
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3690
\item[\linenum{3}] The call to
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3691
  \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
  3692
  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
  3693
  the semaphore finally is reserved for the process calling the
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3694
  request function.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3695
\item[\linenum{4}] When the lock was requested
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3696
  successfully, the function should return 0. The module can prohibit
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3697
  requesting the lock by returning non-zero (see paragraph ``Tuning
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3698
  the jitter'' below).
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3699
\item[\linenum{7}] The \textit{release\_lock()}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3700
  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
  3701
  because is always succeeds.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3702
\item[\linenum{9}] The \textit{rt\_sem\_signal()}
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3703
  function frees the semaphore, that was prior reserved with
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3704
  \textit{rt\_sem\_wait()}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3705
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3706
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3707
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
  3708
the callbacks must be passed to the EtherCAT master:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3709
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3710
\begin{lstlisting}[gobble=2,language=C,numbers=left,caption={Module init
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3711
    function for concurrent access},label={lst:coninit}]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3712
  int __init init_mod(void)
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3713
  {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3714
          RTIME tick_period, requested_ticks, now;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3715
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3716
          rt_sem_init(&master_sem, 1);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3717
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3718
          if (!(master = ecrt_request_master(0))) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3719
                  goto out_return;
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
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3722
          ecrt_master_callbacks(master, request_lock,
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3723
                                release_lock, NULL);
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
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3726
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3727
\begin{description}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3728
\item[\linenum{5}] The call to
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3729
  \textit{rt\_sem\_init()} initializes the semaphore and sets its
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3730
  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
  3731
  without blocking.
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3732
\item[\linenum{11}] The callbacks are passed to
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3733
  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
  3734
  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
  3735
  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
  3736
  \textit{NULL}.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3737
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3738
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3739
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
  3740
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
  3741
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
  3742
so it can access the semaphore directly:
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3743
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3744
\begin{lstlisting}[gobble=2,language=C,numbers=left,caption={RTAI cyclic
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3745
    function for concurrent access},label={lst:conrun}]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3746
  void run(long data)
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3747
  {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3748
          while (1) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3749
                  rt_sem_wait(&master_sem);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3750
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3751
                  ecrt_master_receive(master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3752
                  ecrt_domain_process(domain1);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3753
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3754
                  k_pos = EC_READ_U32(r_ssi_input);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3755
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3756
                  ecrt_master_run(master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3757
                  ecrt_master_send(master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3758
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3759
                  rt_sem_signal(&master_sem);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3760
                  rt_task_wait_period();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3761
          }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3762
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3763
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3764
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3765
\begin{description}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3766
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3767
\item[\linenum{4}] Every access to the master has to be preceded by a call to
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3768
\textit{rt\_sem\_wait()}, because another instance might currently access the
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3769
master.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3770
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3771
\item[\linenum{14}] When cyclic processing finished, the semaphore has to be
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3772
freed again, so that other processes have the possibility to access the master.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3773
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3774
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3775
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3776
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
  3777
concurrent master access.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3778
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3779
\begin{lstlisting}[gobble=2,language=C,numbers=left,caption={RTAI module
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3780
    cleanup function for concurrent access},label={lst:conclean}]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3781
  void __exit cleanup_mod(void)
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3782
  {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3783
          rt_task_delete(&task);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3784
          stop_rt_timer();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3785
          ecrt_master_deactivate(master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3786
          ecrt_release_master(master);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3787
          rt_sem_delete(&master_sem);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3788
  }
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3789
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3790
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3791
\begin{description}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3792
\item[\linenum{7}] Upon module cleanup, the
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3793
  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
  3794
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3795
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3796
\paragraph{Tuning the Jitter}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3797
\index{Jitter}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3798
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3799
Concurrent access leads to higher jitter for the application task, because
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3800
there are situations, in which the task has to wait for a process of lower
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3801
priority to finish accessing the master.  In most cases this is acceptable,
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3802
because a master access cycle (receive/process/send) only takes
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3803
\unit{10-20}{\micro\second} on recent systems, what would be the maximum
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3804
additional jitter. However some applications demand a minimum jitter. For this
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3805
reason the master access can be prohibited by the application: If the time,
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3806
another process wants to access the master, is to close to the beginning of the
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3807
next application cycle, the module can disallow, that the lock is taken. In
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3808
this case, the request callback has to return $1$, meaning that the lock has
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3809
not been taken. The foreign process must abort its master access and try again
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3810
next time.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3811
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3812
This measure helps to significantly reducing the jitter produced by concurrent
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3813
master access. Below are excerpts of an example coding:
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3814
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3815
\begin{lstlisting}[gobble=2,language=C,numbers=left,caption={Variables for
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3816
    jitter reduction},label={lst:redvar}]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3817
  #define FREQUENCY 10000 // RTAI task frequency in Hz
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
  cycles_t t_last_cycle = 0;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3820
  const cycles_t t_critical = cpu_khz * 1000 / FREQUENCY
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3821
                              - cpu_khz * 30 / 1000;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3822
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3823
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3824
\begin{description}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3825
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3826
\item[\linenum{3}] The variable \textit{t\_last\_cycle} holds the timer ticks
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3827
at the beginning of the last realtime cycle.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3828
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3829
\item[\linenum{4}] \textit{t\_critical} contains the number of ticks, that may
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3830
have passed since the beginning of the last cycle, until there is no more
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3831
foreign access possible. It is calculated by subtracting the ticks for
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3832
\unit{30}{\micro\second} from the ticks for a complete cycle.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3833
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3834
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3835
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3836
\begin{lstlisting}[gobble=2,language=C,numbers=left,caption={Cyclic function
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3837
    with reduced jitter},label={lst:redrun}]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3838
  void run(long data)
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
          while (1) {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3841
                  t_last_cycle = get_cycles();
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3842
                  rt_sem_wait(&master_sem);
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
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3845
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3846
\begin{description}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3847
\item[\linenum{4}] The ticks of the beginning of
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3848
  the current realtime cycle are taken before reserving the semaphore.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3849
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3850
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3851
\begin{lstlisting}[gobble=2,language=C,numbers=left,caption={Request callback
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3852
    for reduced jitter},label={lst:redreq}]
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3853
  int request_lock(void *data)
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3854
  {
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3855
          // too close to the next RT cycle: deny access.
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3856
          if (get_cycles() - t_last_cycle > t_critical)
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3857
                  return -1;
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3858
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3859
          // allow access
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3860
          rt_sem_wait(&master_sem);
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3861
          return 0;
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
\end{lstlisting}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3864
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3865
\begin{description}
1085
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3866
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3867
\item[\linenum{4}] If the time of request is too close to the next realtime
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3868
cycle (here: \unit{<30}{\micro\second} before the estimated beginning), the
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3869
locking is denied. The requesting process must abort its cycle.
c75cdcc5ce87 Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents: 917
diff changeset
  3870
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3871
\end{description}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3872
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
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3875
\begin{thebibliography}{99}
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3876
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3877
\bibitem{etherlab} Ingenieurgemeinschaft IgH: EtherLab -- Open Source Toolkit
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3878
for rapid realtime code generation under Linux with Simulink/RTW and EtherCAT
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3879
technology. \url{http://etherlab.org/en}, 2008.
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3880
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3881
\bibitem{dlspec} IEC 61158-4-12: Data-link Protocol Specification.
1095
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  3882
International Electrotechnical Commission (IEC), 2005.
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3883
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3884
\bibitem{alspec} IEC 61158-6-12: Application Layer Protocol Specification.
1095
a3ca9a8a223e Ethernet devices.
Florian Pose <fp@igh-essen.com>
parents: 1094
diff changeset
  3885
International Electrotechnical Commission (IEC), 2005.
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3886
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3887
\bibitem{gpl} GNU General Public License, Version 2.
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3888
\url{http://www.gnu.org/licenses/gpl.txt}. August~9, 2006.
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3889
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3890
\bibitem{lsb} Linux Standard Base.
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3891
\url{http://www.linuxfoundation.org/en/LSB}.  August~9, 2006.
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3892
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3893
\bibitem{wireshark} Wireshark. \url{http://www.wireshark.org}. 2008.
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3894
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3895
\bibitem{automata} {\it Hopcroft, J.~E. / Ullman, J.~D.}: Introduction to
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3896
Automata Theory, Languages and Computation. Adison-Wesley, Reading,
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3897
Mass.~1979.
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3898
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3899
\bibitem{fsmmis} {\it Wagner, F. / Wolstenholme, P.}: State machine
1094
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3900
misunderstandings. In: IEE journal ``Computing and Control Engineering'',
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3901
2004.
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3902
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3903
\bibitem{rtai} RTAI. The RealTime Application Interface for Linux from DIAPM.
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3904
\url{http://www.rtai.org}, 2006.
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3905
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3906
\bibitem{doxygen} Doxygen. Source code documentation generator tool.
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3907
\url{http://www.stack.nl/~dimitri/doxygen}, 2008.
eb0258e53236 App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents: 1087
diff changeset
  3908
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3909
\end{thebibliography}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3910
917
07b0ad9722a1 Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents: 814
diff changeset
  3911
\printnomenclature
369
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3912
\addcontentsline{toc}{chapter}{\nomname}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3913
\markleft{\nomname}
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
\printindex
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3916
\markleft{Index}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3917
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3918
%------------------------------------------------------------------------------
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3919
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3920
\end{document}
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3921
7920ca086e5c Moved doc into trunk
Florian Pose <fp@igh-essen.com>
parents:
diff changeset
  3922
%------------------------------------------------------------------------------