author | Florian Pose <fp@igh-essen.com> |
Fri, 08 Feb 2013 20:00:16 +0100 | |
branch | stable-1.5 |
changeset 2512 | a01947bc9ab6 |
parent 2421 | bc2d4bf9cbe5 |
child 2515 | 1f03f2543fc3 |
permissions | -rw-r--r-- |
369 | 1 |
%------------------------------------------------------------------------------ |
2 |
% |
|
3 |
% IgH EtherCAT Master Documentation |
|
4 |
% |
|
5 |
% $Id$ |
|
6 |
% |
|
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
7 |
% vi: spell spelllang=en tw=78 |
2421 | 8 |
% |
369 | 9 |
%------------------------------------------------------------------------------ |
10 |
||
11 |
\documentclass[a4paper,12pt,BCOR6mm,bibtotoc,idxtotoc]{scrbook} |
|
12 |
||
13 |
\usepackage[latin1]{inputenc} |
|
14 |
\usepackage[automark,headsepline]{scrpage2} |
|
15 |
\usepackage{graphicx} |
|
16 |
\usepackage{makeidx} |
|
17 |
\usepackage[refpage]{nomencl} |
|
18 |
\usepackage{listings} |
|
1588
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
19 |
\usepackage[nofancy]{rcsinfo} |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
20 |
\usepackage{SIunits} |
1517
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
21 |
\usepackage{amsmath} % for \text{} |
2297
0566476835d7
Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents:
2133
diff
changeset
|
22 |
\usepackage{longtable} |
1275
c9de1c0c1f51
*space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents:
1270
diff
changeset
|
23 |
\usepackage{hyperref} |
c9de1c0c1f51
*space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents:
1270
diff
changeset
|
24 |
|
c9de1c0c1f51
*space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents:
1270
diff
changeset
|
25 |
\hypersetup{pdfpagelabels,plainpages=false} |
c9de1c0c1f51
*space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents:
1270
diff
changeset
|
26 |
\hypersetup{linkcolor=blue,colorlinks=true,urlcolor=blue} |
369 | 27 |
|
28 |
\setlength{\parskip}{0.8ex plus 0.8ex minus 0.5ex} |
|
29 |
\setlength{\parindent}{0mm} |
|
30 |
||
31 |
\setcounter{secnumdepth}{\subsubsectionlevel} |
|
32 |
||
33 |
\DeclareFontShape{OT1}{cmtt}{bx}{n} |
|
34 |
{ |
|
35 |
<5><6><7><8><9><10><10.95><12><14.4><17.28><20.74><24.88>cmttb10 |
|
36 |
}{} |
|
37 |
||
38 |
\lstset{basicstyle=\ttfamily\small,numberstyle=\tiny,aboveskip=4mm, |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
39 |
belowskip=2mm,escapechar=`} |
369 | 40 |
\renewcommand\lstlistlistingname{List of Listings} |
41 |
||
917
07b0ad9722a1
Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents:
814
diff
changeset
|
42 |
% Workaround for lstlistoflistings bug |
07b0ad9722a1
Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents:
814
diff
changeset
|
43 |
\makeatletter% --> De-TeX-FAQ |
07b0ad9722a1
Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents:
814
diff
changeset
|
44 |
\renewcommand*{\lstlistoflistings}{% |
07b0ad9722a1
Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents:
814
diff
changeset
|
45 |
\begingroup |
07b0ad9722a1
Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents:
814
diff
changeset
|
46 |
\if@twocolumn |
07b0ad9722a1
Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents:
814
diff
changeset
|
47 |
\@restonecoltrue\onecolumn |
07b0ad9722a1
Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents:
814
diff
changeset
|
48 |
\else |
07b0ad9722a1
Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents:
814
diff
changeset
|
49 |
\@restonecolfalse |
07b0ad9722a1
Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents:
814
diff
changeset
|
50 |
\fi |
07b0ad9722a1
Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents:
814
diff
changeset
|
51 |
\lol@heading |
07b0ad9722a1
Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents:
814
diff
changeset
|
52 |
\setlength{\parskip}{\z@}% |
07b0ad9722a1
Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents:
814
diff
changeset
|
53 |
\setlength{\parindent}{\z@}% |
07b0ad9722a1
Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents:
814
diff
changeset
|
54 |
\setlength{\parfillskip}{\z@ \@plus 1fil}% |
07b0ad9722a1
Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents:
814
diff
changeset
|
55 |
\@starttoc{lol}% |
07b0ad9722a1
Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents:
814
diff
changeset
|
56 |
\if@restonecol\twocolumn\fi |
07b0ad9722a1
Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents:
814
diff
changeset
|
57 |
\endgroup |
07b0ad9722a1
Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents:
814
diff
changeset
|
58 |
} |
07b0ad9722a1
Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents:
814
diff
changeset
|
59 |
\makeatother% --> \makeatletter |
07b0ad9722a1
Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents:
814
diff
changeset
|
60 |
|
369 | 61 |
\renewcommand\nomname{Glossary} |
62 |
||
63 |
\newcommand{\IgH}{\raisebox{-0.7667ex} |
|
64 |
{\includegraphics[height=2.2ex]{images/ighsign}}} |
|
65 |
||
1589
ffe3cebd5d53
Revision and date on every page.
Florian Pose <fp@igh-essen.com>
parents:
1588
diff
changeset
|
66 |
\rcsInfo $RCSId$ |
369 | 67 |
|
1270
11f4b6e10d74
Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents:
1269
diff
changeset
|
68 |
\newcommand{\masterversion}{1.5.0} |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
69 |
\newcommand{\linenum}[1]{\normalfont\textcircled{\tiny #1}} |
487 | 70 |
|
369 | 71 |
\makeindex |
917
07b0ad9722a1
Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents:
814
diff
changeset
|
72 |
\makenomenclature |
369 | 73 |
|
1589
ffe3cebd5d53
Revision and date on every page.
Florian Pose <fp@igh-essen.com>
parents:
1588
diff
changeset
|
74 |
% Revision and date on inner footer |
ffe3cebd5d53
Revision and date on every page.
Florian Pose <fp@igh-essen.com>
parents:
1588
diff
changeset
|
75 |
\ifoot[\scriptsize\rcsInfoRevision, \rcsInfoDate] |
ffe3cebd5d53
Revision and date on every page.
Florian Pose <fp@igh-essen.com>
parents:
1588
diff
changeset
|
76 |
{\scriptsize\rcsInfoRevision, \rcsInfoDate} |
ffe3cebd5d53
Revision and date on every page.
Florian Pose <fp@igh-essen.com>
parents:
1588
diff
changeset
|
77 |
|
369 | 78 |
%------------------------------------------------------------------------------ |
79 |
||
80 |
\begin{document} |
|
81 |
||
82 |
\pagenumbering{roman} |
|
83 |
\pagestyle{empty} |
|
84 |
||
85 |
\begin{titlepage} |
|
86 |
\begin{center} |
|
87 |
\rule{\textwidth}{1.5mm} |
|
88 |
||
1917 | 89 |
{\Huge\sf\textbf{IgH \includegraphics[height=2.4ex]{images/ethercat} |
90 |
Master \masterversion}\\[1ex] |
|
91 |
\textbf{Documentation}} |
|
369 | 92 |
|
93 |
\vspace{1ex} |
|
94 |
\rule{\textwidth}{1.5mm} |
|
95 |
||
1204
4e3e8400c338
Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents:
1203
diff
changeset
|
96 |
\vspace{\fill} {\Large Dipl.-Ing. (FH) Florian Pose, |
4e3e8400c338
Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents:
1203
diff
changeset
|
97 |
\url{fp@igh-essen.com}\\[1ex] Ingenieurgemeinschaft \IgH} |
369 | 98 |
|
99 |
\vspace{\fill} |
|
1588
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
100 |
{\Large Essen, \rcsInfoLongDate\\[1ex] |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
101 |
Revision \rcsInfoRevision} |
369 | 102 |
\end{center} |
103 |
\end{titlepage} |
|
104 |
||
105 |
%------------------------------------------------------------------------------ |
|
106 |
||
1589
ffe3cebd5d53
Revision and date on every page.
Florian Pose <fp@igh-essen.com>
parents:
1588
diff
changeset
|
107 |
\pagestyle{scrplain} |
ffe3cebd5d53
Revision and date on every page.
Florian Pose <fp@igh-essen.com>
parents:
1588
diff
changeset
|
108 |
|
369 | 109 |
\tableofcontents |
110 |
\listoftables |
|
111 |
\listoffigures |
|
1204
4e3e8400c338
Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents:
1203
diff
changeset
|
112 |
%\lstlistoflistings |
369 | 113 |
|
114 |
%------------------------------------------------------------------------------ |
|
115 |
||
116 |
\newpage |
|
117 |
\pagestyle{scrheadings} |
|
118 |
||
119 |
\section*{Conventions} |
|
120 |
\addcontentsline{toc}{section}{Conventions} |
|
121 |
\markleft{Conventions} |
|
122 |
||
123 |
The following typographic conventions are used: |
|
124 |
||
125 |
\begin{itemize} |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
126 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
127 |
\item \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
|
128 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
129 |
\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
|
130 |
output. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
131 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
132 |
\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
|
133 |
lines. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
134 |
|
369 | 135 |
\end{itemize} |
136 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
137 |
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
|
138 |
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
|
139 |
\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
|
140 |
values are specified as byte addresses. |
369 | 141 |
|
142 |
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
|
143 |
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
|
144 |
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
|
145 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
146 |
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
|
147 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
148 |
\begin{lstlisting} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
149 |
$ |
369 | 150 |
\end{lstlisting} |
151 |
||
152 |
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
|
153 |
prompt is a mesh: |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
154 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
155 |
\begin{lstlisting} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
156 |
# |
369 | 157 |
\end{lstlisting} |
158 |
||
159 |
%------------------------------------------------------------------------------ |
|
160 |
||
161 |
\chapter{The IgH EtherCAT Master} |
|
162 |
\label{chapter:master} |
|
163 |
\pagenumbering{arabic} |
|
164 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
165 |
This chapter covers some general information about the EtherCAT master. |
369 | 166 |
|
167 |
%------------------------------------------------------------------------------ |
|
168 |
||
169 |
\section{Feature Summary} |
|
170 |
\label{sec:summary} |
|
171 |
\index{Master!Features} |
|
172 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
173 |
The list below gives a short summary of the master features. |
369 | 174 |
|
175 |
\begin{itemize} |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
176 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
177 |
\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
|
178 |
|
1086
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
179 |
\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
|
180 |
|
1588
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
181 |
\item Comes with EtherCAT-capable native drivers for several common Ethernet |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
182 |
chips, as well as a generic driver for all chips supported by the Linux |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
183 |
kernel. |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
184 |
|
369 | 185 |
\begin{itemize} |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
186 |
|
1588
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
187 |
\item The native drivers operate the hardware without interrupts. |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
188 |
|
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
189 |
\item Native drivers for additional Ethernet hardware can easily be |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
190 |
implemented using the common device interface (see sec.~\ref{sec:ecdev}) |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
191 |
provided by the master module. |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
192 |
|
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
193 |
\item For any other hardware, the generic driver can be used. It uses the |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
194 |
lower layers of the Linux network stack. |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
195 |
|
369 | 196 |
\end{itemize} |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
197 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
198 |
\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
|
199 |
parallel. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
200 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
201 |
\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
|
202 |
independent architecture. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
203 |
|
369 | 204 |
\begin{itemize} |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
205 |
|
1588
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
206 |
\item RTAI\nomenclature{RTAI}{Realtime Application Interface} \cite{rtai}, |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
207 |
ADEOS\nomenclature{ADEOS}{Adaptive Domain Environment for Operating |
1588
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
208 |
Systems}, RT-Preempt \cite{rt-preempt}, etc. |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
209 |
|
369 | 210 |
\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
|
211 |
|
369 | 212 |
\end{itemize} |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
213 |
|
1204
4e3e8400c338
Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents:
1203
diff
changeset
|
214 |
\item Common ``Application Interface'' for applications, that want to use |
1289
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
215 |
EtherCAT functionality (see chap.~\ref{chap:api}). |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
216 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
217 |
\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
|
218 |
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
|
219 |
|
369 | 220 |
\begin{itemize} |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
221 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
222 |
\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
|
223 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
224 |
\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
|
225 |
configuration within each domain. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
226 |
|
369 | 227 |
\end{itemize} |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
228 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
229 |
\item Communication through several finite state machines. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
230 |
|
369 | 231 |
\begin{itemize} |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
232 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
233 |
\item Automatic bus scanning after topology changes. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
234 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
235 |
\item Bus monitoring during operation. |
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 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
|
238 |
during operation. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
239 |
|
369 | 240 |
\end{itemize} |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
241 |
|
1517
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
242 |
\item Distributed Clocks support (see sec.~\ref{sec:dc}). |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
243 |
|
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
244 |
\begin{itemize} |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
245 |
|
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
246 |
\item Configuration of the slave's DC parameters through the application |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
247 |
interface. |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
248 |
|
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
249 |
\item Synchronization (offset and drift compensation) of the distributed |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
250 |
slave clocks to the reference clock. |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
251 |
|
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
252 |
\item Optional synchronization of the reference clock to the master clock. |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
253 |
|
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
254 |
\end{itemize} |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
255 |
|
1327
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
256 |
\item CANopen over EtherCAT (CoE) |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
257 |
|
369 | 258 |
\begin{itemize} |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
259 |
|
1327
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
260 |
\item SDO upload, download and information service. |
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
261 |
|
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
262 |
\item Slave configuration via SDOs. |
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
263 |
|
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
264 |
\item SDO access from userspace and from the application. |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
265 |
|
369 | 266 |
\end{itemize} |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
267 |
|
1327
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
268 |
\item Ethernet over EtherCAT (EoE) |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
269 |
|
369 | 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 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
|
273 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
274 |
\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
|
275 |
architecture. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
276 |
|
369 | 277 |
\end{itemize} |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
278 |
|
1364 | 279 |
\item Vendor-specific over EtherCAT (VoE) |
280 |
||
281 |
\begin{itemize} |
|
282 |
||
283 |
\item Communication with vendor-specific mailbox protocols via the API. |
|
284 |
||
285 |
\end{itemize} |
|
286 |
||
287 |
\item File Access over EtherCAT (FoE) |
|
288 |
||
289 |
\begin{itemize} |
|
290 |
||
291 |
\item Loading and storing files via the command-line tool. |
|
292 |
||
293 |
\item Updating a slave's firmware can be done easily. |
|
294 |
||
295 |
\end{itemize} |
|
296 |
||
1917 | 297 |
\item Servo Profile over EtherCAT (SoE) |
298 |
||
299 |
\begin{itemize} |
|
300 |
||
301 |
\item Implemented according to IEC 61800-7 \cite{soespec}. |
|
302 |
||
303 |
\item Storing IDN configurations, that are written to the slave during |
|
304 |
startup. |
|
305 |
||
306 |
\item Accessing IDNs via the command-line tool. |
|
307 |
||
308 |
\item Accessing IDNs at runtime via the the user-space library. |
|
309 |
||
310 |
\end{itemize} |
|
311 |
||
1517
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
312 |
\item Userspace command-line-tool ``ethercat'' (see sec.~\ref{sec:tool}) |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
313 |
|
369 | 314 |
\begin{itemize} |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
315 |
|
1364 | 316 |
\item Detailed information about master, slaves, domains and bus |
317 |
configuration. |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
318 |
\item Setting the master's debug level. |
1364 | 319 |
\item Reading/Writing alias addresses. |
320 |
\item Listing slave configurations. |
|
321 |
\item Viewing process data. |
|
322 |
\item SDO download/upload; listing SDO dictionaries. |
|
323 |
\item Loading and storing files via FoE. |
|
1917 | 324 |
\item SoE IDN access. |
1364 | 325 |
\item Access to slave registers. |
326 |
\item Slave SII (EEPROM) access. |
|
327 |
\item Controlling application-layer states. |
|
1517
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
328 |
\item Generation of slave description XML and C-code from existing slaves. |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
329 |
|
369 | 330 |
\end{itemize} |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
331 |
|
369 | 332 |
\item Seamless system integration though LSB\nomenclature{LSB}{Linux |
333 |
Standard Base} compliance. |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
334 |
|
369 | 335 |
\begin{itemize} |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
336 |
|
1095 | 337 |
\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
|
338 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
339 |
\item Init script for master control. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
340 |
|
369 | 341 |
\end{itemize} |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
342 |
|
369 | 343 |
\item Virtual read-only network interface for monitoring and debugging |
344 |
purposes. |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
345 |
|
369 | 346 |
\end{itemize} |
347 |
||
348 |
%------------------------------------------------------------------------------ |
|
349 |
||
350 |
\section{License} |
|
351 |
\label{sec:license} |
|
352 |
||
1275
c9de1c0c1f51
*space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents:
1270
diff
changeset
|
353 |
The master code is released under the terms and conditions of the GNU General |
c9de1c0c1f51
*space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents:
1270
diff
changeset
|
354 |
Public License (GPL \cite{gpl})\index{GPL}, version 2. Other developers, that |
c9de1c0c1f51
*space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents:
1270
diff
changeset
|
355 |
want to use EtherCAT with Linux systems, are invited to use the master code or |
c9de1c0c1f51
*space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents:
1270
diff
changeset
|
356 |
even participate on development. |
c9de1c0c1f51
*space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents:
1270
diff
changeset
|
357 |
|
c9de1c0c1f51
*space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents:
1270
diff
changeset
|
358 |
To allow static linking of userspace application against the master's |
1289
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
359 |
application interface (see chap.~\ref{chap:api}), the userspace library (see |
1275
c9de1c0c1f51
*space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents:
1270
diff
changeset
|
360 |
sec.~\ref{sec:userlib}) is licensed under the terms and conditions of the GNU |
c9de1c0c1f51
*space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents:
1270
diff
changeset
|
361 |
Lesser General Public License (LGPL \cite{lgpl})\index{LGPL}, version 2.1. |
369 | 362 |
|
363 |
%------------------------------------------------------------------------------ |
|
364 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
365 |
\chapter{Architecture} |
1299 | 366 |
\label{chap:arch} |
369 | 367 |
\index{Master!Architecture} |
368 |
||
369 |
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
|
370 |
an early design decision, which has been made for several reasons: |
369 | 371 |
|
372 |
\begin{itemize} |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
373 |
|
1306
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
374 |
\item Kernel code has significantly better realtime characteristics, i.\,e.\ |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
375 |
less latency than userspace code. It was foreseeable, that a fieldbus master |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
376 |
has a lot of cyclic work to do. Cyclic work is usually triggered by timer |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
377 |
interrupts inside the kernel. The execution delay of a function that processes |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
378 |
timer interrupts is less, when it resides in kernelspace, because there is no |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
379 |
need of time-consuming context switches to a userspace process. |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
380 |
|
369 | 381 |
\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
|
382 |
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
|
383 |
anyway (through network device drivers), which is one more reason for the |
1275
c9de1c0c1f51
*space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents:
1270
diff
changeset
|
384 |
master code being in kernelspace. |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
385 |
|
369 | 386 |
\end{itemize} |
387 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
388 |
Figure~\ref{fig:arch} gives a general overview of the master architecture. |
369 | 389 |
|
390 |
\begin{figure}[htbp] |
|
391 |
\centering |
|
1588
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
392 |
\includegraphics[width=\textwidth]{images/architecture} |
1291 | 393 |
\caption{Master Architecture} |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
394 |
\label{fig:arch} |
369 | 395 |
\end{figure} |
396 |
||
1291 | 397 |
The components of the master environment are described below: |
398 |
||
399 |
\begin{description} |
|
400 |
||
401 |
\item[Master Module]\index{Master Module} Kernel module containing one or more |
|
402 |
EtherCAT master instances (see sec.~\ref{sec:mastermod}), the ``Device |
|
403 |
Interface'' (see sec.~\ref{sec:ecdev}) and the ``Application Interface'' (see |
|
404 |
chap.~\ref{chap:api}). |
|
405 |
||
406 |
\item[Device Modules]\index{Device modules} EtherCAT-capable Ethernet device |
|
407 |
driver modules\index{Device modules}, that offer their devices to the EtherCAT |
|
408 |
master via the device interface (see sec.~\ref{sec:ecdev}). These modified |
|
409 |
network drivers can handle network devices used for EtherCAT operation and |
|
410 |
``normal'' Ethernet devices in parallel. A master can accept a certain device |
|
411 |
and then is able to send and receive EtherCAT frames. Ethernet devices |
|
412 |
declined by the master module are connected to the kernel's network stack as |
|
413 |
usual. |
|
414 |
||
415 |
\item[Application]\index{Application} A program that uses the EtherCAT master |
|
416 |
(usually for cyclic exchange of process data with EtherCAT slaves). These |
|
417 |
programs are not part of the EtherCAT master code\footnote{Although there are |
|
418 |
some examples provided in the \textit{examples/} directory.}, but have to be |
|
419 |
generated or written by the user. An application can ``request'' a master |
|
420 |
through the application interface (see chap.~\ref{chap:api}). If this |
|
421 |
succeeds, it has the control over the master: It can provide a bus |
|
422 |
configuration and exchange process data. Applications can be kernel modules |
|
423 |
(that use the kernel application interface directly) or userspace programs, |
|
424 |
that use the application interface via the EtherCAT library (see |
|
425 |
sec.~\ref{sec:userlib}). |
|
426 |
||
427 |
\end{description} |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
428 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
429 |
%------------------------------------------------------------------------------ |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
430 |
|
1306
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
431 |
\section{Master Module} |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
432 |
\label{sec:mastermod} |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
433 |
\index{Master module} |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
434 |
|
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
435 |
The EtherCAT master kernel module \textit{ec\_master} can contain multiple |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
436 |
master instances. Each master waits for a certain Ethernet device identified |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
437 |
by its MAC address\index{MAC address}. These addresses have to be specified on |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
438 |
module loading via the \textit{main\_devices} module parameter. The number of |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
439 |
master instances to initialize is taken from the number of MAC addresses |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
440 |
given. |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
441 |
|
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
442 |
The below command loads the master module with a single master instance that |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
443 |
waits for the Ethernet device with the MAC address |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
444 |
\lstinline+00:0E:0C:DA:A2:20+. The master will be accessible via index $0$. |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
445 |
|
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
446 |
\begin{lstlisting} |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
447 |
# `\textbf{modprobe ec\_master main\_devices=00:0E:0C:DA:A2:20}` |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
448 |
\end{lstlisting} |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
449 |
|
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
450 |
MAC addresses for multiple masters have to be separated by commas: |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
451 |
|
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
452 |
\begin{lstlisting} |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
453 |
# `\textbf{modprobe ec\_master main\_devices=00:0E:0C:DA:A2:20,00:e0:81:71:d5:1c}` |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
454 |
\end{lstlisting} |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
455 |
|
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
456 |
The two masters can be addressed by their indices 0 and 1 respectively (see |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
457 |
figure~\ref{fig:masters}). The master index is needed for the |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
458 |
\lstinline+ecrt_master_request()+ function of the application interface (see |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
459 |
chap.~\ref{chap:api}) and the \lstinline+--master+ option of the |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
460 |
\textit{ethercat} command-line tool (see sec.~\ref{sec:tool}), which defaults |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
461 |
to $0$. |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
462 |
|
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
463 |
\begin{figure}[htbp] |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
464 |
\centering |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
465 |
\includegraphics[width=.5\textwidth]{images/masters} |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
466 |
\caption{Multiple masters in one module} |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
467 |
\label{fig:masters} |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
468 |
\end{figure} |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
469 |
|
1399
f79d4bb5b23a
Added debug_level module parameter. debug_level is now unsigned int.
Florian Pose <fp@igh-essen.com>
parents:
1364
diff
changeset
|
470 |
\paragraph{Debug Level} The master module also has a parameter |
f79d4bb5b23a
Added debug_level module parameter. debug_level is now unsigned int.
Florian Pose <fp@igh-essen.com>
parents:
1364
diff
changeset
|
471 |
\textit{debug\_level} to set the initial debug level for all masters (see |
f79d4bb5b23a
Added debug_level module parameter. debug_level is now unsigned int.
Florian Pose <fp@igh-essen.com>
parents:
1364
diff
changeset
|
472 |
also~\ref{sec:ethercat-debug}). |
f79d4bb5b23a
Added debug_level module parameter. debug_level is now unsigned int.
Florian Pose <fp@igh-essen.com>
parents:
1364
diff
changeset
|
473 |
|
1306
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
474 |
\paragraph{Init Script} |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
475 |
\index{Init script} |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
476 |
|
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
477 |
In most cases it is not necessary to load the master module and the Ethernet |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
478 |
driver modules manually. There is an init script available, so the master can |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
479 |
be started as a service (see sec.~\ref{sec:system}). |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
480 |
|
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
481 |
\paragraph{Syslog} |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
482 |
|
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
483 |
The master module outputs information about its state and events to the kernel |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
484 |
ring buffer. These also end up in the system logs. The above module loading |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
485 |
command should result in the messages below: |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
486 |
|
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
487 |
\begin{lstlisting} |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
488 |
# `\textbf{dmesg | tail -2}` |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
489 |
EtherCAT: Master driver `\masterversion` |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
490 |
EtherCAT: 2 masters waiting for devices. |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
491 |
|
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
492 |
# `\textbf{tail -2 /var/log/messages}` |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
493 |
Jul 4 10:22:45 ethercat kernel: EtherCAT: Master driver `\masterversion` |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
494 |
Jul 4 10:22:45 ethercat kernel: EtherCAT: 2 masters waiting |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
495 |
for devices. |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
496 |
\end{lstlisting} |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
497 |
|
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
498 |
All EtherCAT master output is prefixed with \lstinline+EtherCAT+ which makes |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
499 |
searching the logs easier. |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
500 |
|
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
501 |
%------------------------------------------------------------------------------ |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
502 |
|
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
503 |
\section{Master Phases} |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
504 |
\index{Master phases} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
505 |
|
1306
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
506 |
Every EtherCAT master provided by the master module (see |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
507 |
sec.~\ref{sec:mastermod}) runs through several phases (see |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
508 |
fig.~\ref{fig:phases}): |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
509 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
510 |
\begin{figure}[htbp] |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
511 |
\centering |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
512 |
\includegraphics[width=.9\textwidth]{images/phases} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
513 |
\caption{Master phases and transitions} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
514 |
\label{fig:phases} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
515 |
\end{figure} |
1291 | 516 |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
517 |
\begin{description} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
518 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
519 |
\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
|
520 |
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
|
521 |
possible until then. |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
522 |
|
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
523 |
\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
|
524 |
an Ethernet device, but is not requested by any application yet. The master |
1289
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
525 |
runs its state machine (see sec.~\ref{sec:fsm-master}), that automatically |
1275
c9de1c0c1f51
*space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents:
1270
diff
changeset
|
526 |
scans the bus for slaves and executes pending operations from the userspace |
1327
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
527 |
interface (for example SDO access). The command-line tool can be used to |
1275
c9de1c0c1f51
*space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents:
1270
diff
changeset
|
528 |
access the bus, but there is no process data exchange because of the missing |
c9de1c0c1f51
*space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents:
1270
diff
changeset
|
529 |
bus configuration. |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
530 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
531 |
\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
|
532 |
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
|
533 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
534 |
\end{description} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
535 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
536 |
%------------------------------------------------------------------------------ |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
537 |
|
1293
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
538 |
\section{Process Data} |
369 | 539 |
\label{sec:processdata} |
540 |
||
1293
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
541 |
This section shall introduce a few terms and ideas how the master handles |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
542 |
process data. |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
543 |
|
369 | 544 |
\paragraph{Process Data Image} |
545 |
\index{Process data} |
|
546 |
||
1293
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
547 |
Slaves offer their inputs and outputs by presenting the master so-called |
1327
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
548 |
``Process Data Objects'' (PDOs\index{PDO}). The available PDOs can be either |
1293
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
549 |
determined by reading out the slave's TXPDO and RXPDO SII categories from the |
1327
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
550 |
E$^2$PROM (in case of fixed PDOs) or by reading out the appropriate CoE |
1293
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
551 |
objects (see sec.~\ref{sec:coe}), if available. The application can register |
1327
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
552 |
the PDOs' entries for exchange during cyclic operation. The sum of all |
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
553 |
registered PDO entries defines the ``process data image'', which is exchanged |
1293
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
554 |
via datagrams with ``logical'' memory access (like LWR, LRD or LRW) introduced |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
555 |
in~\cite[sec.~5.4]{dlspec}. |
369 | 556 |
|
557 |
\paragraph{Process Data Domains} |
|
558 |
\index{Domain} |
|
559 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
560 |
The process data image can be easily managed by creating so-called |
1327
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
561 |
``domains'', which allow grouped PDO exchange. They also take care of managing |
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
562 |
the datagram structures needed to exchange the PDOs. Domains are mandatory for |
1293
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
563 |
process data exchange, so there has to be at least one. They were introduced |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
564 |
for the following reasons: |
369 | 565 |
|
566 |
\begin{itemize} |
|
1293
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
567 |
|
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
568 |
\item The maximum size of a datagram is limited due to the limited size of an |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
569 |
Ethernet frame: The maximum data size is the Ethernet data field size minus |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
570 |
the EtherCAT frame header, EtherCAT datagram header and EtherCAT datagram |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
571 |
footer: $1500 - 2 - 12 - 2 = 1484$ octets. If the size of the process data |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
572 |
image exceeds this limit, multiple frames have to be sent, and the image has |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
573 |
to be partitioned for the use of multiple datagrams. A domain manages this |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
574 |
automatically. |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
575 |
|
1327
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
576 |
\item Not every PDO has to be exchanged with the same frequency: The values of |
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
577 |
PDOs can vary slowly over time (for example temperature values), so exchanging |
1293
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
578 |
them with a high frequency would just waste bus bandwidth. For this reason, |
1327
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
579 |
multiple domains can be created, to group different PDOs and so allow separate |
1293
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
580 |
exchange. |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
581 |
|
369 | 582 |
\end{itemize} |
583 |
||
1293
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
584 |
There is no upper limit for the number of domains, but each domain occupies |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
585 |
one FMMU in each slave involved, so the maximum number of domains is de facto |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
586 |
limited by the slaves. |
369 | 587 |
|
588 |
\paragraph{FMMU Configuration} |
|
589 |
\index{FMMU!Configuration} |
|
590 |
||
1327
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
591 |
An application can register PDO entries for exchange. Every PDO entry and its |
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
592 |
parent PDO is part of a memory area in the slave's physical memory, that is |
1293
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
593 |
protected by a sync manager \cite[sec.~6.7]{dlspec} for synchronized access. |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
594 |
In order to make a sync manager react on a datagram accessing its memory, it |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
595 |
is necessary to access the last byte covered by the sync manager. Otherwise |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
596 |
the sync manager will not react on the datagram and no data will be exchanged. |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
597 |
That is why the whole synchronized memory area has to be included into the |
1327
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
598 |
process data image: For example, if a certain PDO entry of a slave is |
1293
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
599 |
registered for exchange with a certain domain, one FMMU will be configured to |
1327
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
600 |
map the complete sync-manager-protected memory, the PDO entry resides in. If a |
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
601 |
second PDO entry of the same slave is registered for process data exchange |
1293
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
602 |
within the same domain, and it resides in the same sync-manager-protected |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
603 |
memory as the first one, the FMMU configuration is not altered, because the |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
604 |
desired memory is already part of the domain's process data image. If the |
1327
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
605 |
second PDO entry would belong to another sync-manager-protected area, this |
1293
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
606 |
complete area would also be included into the domains process data image. |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
607 |
|
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
608 |
Figure~\ref{fig:fmmus} gives an overview, how FMMUs are configured to map |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
609 |
physical memory to logical process data images. |
369 | 610 |
|
611 |
\begin{figure}[htbp] |
|
612 |
\centering |
|
613 |
\includegraphics[width=\textwidth]{images/fmmus} |
|
1293
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
614 |
\caption{FMMU Configuration} |
369 | 615 |
\label{fig:fmmus} |
616 |
\end{figure} |
|
617 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
618 |
%------------------------------------------------------------------------------ |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
619 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
620 |
\chapter{Application Interface} |
1289
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
621 |
\label{chap:api} |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
622 |
\index{Application interface} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
623 |
|
1297 | 624 |
% TODO |
625 |
% |
|
626 |
% Interface version |
|
627 |
% Master Requesting and Releasing |
|
628 |
% Master Locking |
|
1327
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
629 |
% Configuring PDO assignment and mapping |
1297 | 630 |
% Domains (memory) |
1327
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
631 |
% PDO entry registration |
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
632 |
% SDO configuration |
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
633 |
% SDO access |
1917 | 634 |
% IDN configurations |
635 |
% IDN access |
|
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
636 |
|
1094
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
637 |
The application interface provides functions and data structures for |
1292 | 638 |
applications to access an EtherCAT master. The complete documentation of the |
639 |
interface is included as Doxygen~\cite{doxygen} comments in the header file |
|
640 |
\textit{include/ecrt.h}. It can either be read directly from the file |
|
1293
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
641 |
comments, or as a more comfortable HTML documentation. The HTML generation is |
1292 | 642 |
described in sec.~\ref{sec:gendoc}. |
1094
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
643 |
|
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
644 |
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
|
645 |
interface. |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
646 |
|
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
647 |
Every application should use the master in two steps: |
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 |
\begin{description} |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
650 |
|
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
651 |
\item[Configuration] The master is requested and the configuration is applied. |
1327
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
652 |
For example, domains are created, slaves are configured and PDO entries are |
1293
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
653 |
registered (see sec.~\ref{sec:masterconfig}). |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
654 |
|
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
655 |
\item[Operation] Cyclic code is run and process data are exchanged (see |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
656 |
sec.~\ref{sec:cyclic}). |
1094
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 |
\end{description} |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
659 |
|
1293
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
660 |
\paragraph{Example Applications}\index{Example Applications} There are a few |
1204
4e3e8400c338
Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents:
1203
diff
changeset
|
661 |
example applications in the \textit{examples/} subdirectory of the master |
4e3e8400c338
Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents:
1203
diff
changeset
|
662 |
code. They are documented in the source code. |
4e3e8400c338
Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents:
1203
diff
changeset
|
663 |
|
1094
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
664 |
%------------------------------------------------------------------------------ |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
665 |
|
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
666 |
\section{Master Configuration} |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
667 |
\label{sec:masterconfig} |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
668 |
|
1293
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
669 |
The bus configuration is supplied via the application interface. |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
670 |
Figure~\ref{fig:app-config} gives an overview of the objects, that can be |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
671 |
configured by the application. |
1094
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
672 |
|
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
673 |
\begin{figure}[htbp] |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
674 |
\centering |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
675 |
\includegraphics[width=.8\textwidth]{images/app-config} |
1203
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
676 |
\caption{Master Configuration} |
1094
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
677 |
\label{fig:app-config} |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
678 |
\end{figure} |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
679 |
|
1293
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
680 |
\subsection{Slave Configuration} |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
681 |
|
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
682 |
The application has to tell the master about the expected bus topology. This |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
683 |
can be done by creating ``slave configurations''. A slave configuration can be |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
684 |
seen as an expected slave. When a slave configuration is created, the |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
685 |
application provides the bus position (see below), vendor id and product code. |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
686 |
|
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
687 |
When the bus configuration is applied, the master checks, if there is a slave |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
688 |
with the given vendor id and product code at the given position. If this is |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
689 |
the case, the slave configuration is ``attached'' to the real slave on the bus |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
690 |
and the slave is configured according to the settings provided by the |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
691 |
application. The state of a slave configuration can either be queried via the |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
692 |
application interface or via the command-line tool (see |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
693 |
sec.~\ref{sec:ethercat-config}). |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
694 |
|
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
695 |
\paragraph{Slave Position} The slave position has to be specified as a tuple |
1306
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
696 |
of ``alias'' and ``position''. This allows addressing slaves either via an |
1293
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
697 |
absolute bus position, or a stored identifier called ``alias'', or a mixture |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
698 |
of both. The alias is a 16-bit value stored in the slave's E$^2$PROM. It can |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
699 |
be modified via the command-line tool (see sec.~\ref{sec:ethercat-alias}). |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
700 |
Table~\ref{tab:slaveposition} shows, how the values are interpreted. |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
701 |
|
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
702 |
\begin{table}[htbp] |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
703 |
\centering |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
704 |
\caption{Specifying a Slave Position} |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
705 |
\label{tab:slaveposition} |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
706 |
\vspace{2mm} |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
707 |
\begin{tabular}{c|c|p{70mm}} |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
708 |
Alias & Position & Interpretation\\ |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
709 |
\hline |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
710 |
|
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
711 |
\lstinline+0+ & \lstinline+0+ -- \lstinline+65535+ & |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
712 |
|
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
713 |
Position addressing. The position parameter is interpreted as the absolute |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
714 |
ring position in the bus.\\ \hline |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
715 |
|
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
716 |
\lstinline+1+ -- \lstinline+65535+ & \lstinline+0+ -- \lstinline+65535+ & |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
717 |
|
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
718 |
Alias addressing. The position parameter is interpreted as relative |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
719 |
position after the first slave with the given alias address. \\ \hline |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
720 |
|
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
721 |
\end{tabular} |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
722 |
\end{table} |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
723 |
|
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
724 |
Figure~\ref{fig:attach} shows an example of how slave configurations are |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
725 |
attached. Some of the configurations were attached, while others remain |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
726 |
detached. The below lists gives the reasons beginning with the top slave |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
727 |
configuration. |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
728 |
|
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
729 |
\begin{figure}[htbp] |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
730 |
\centering |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
731 |
\includegraphics[width=.7\textwidth]{images/attach} |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
732 |
\caption{Slave Configuration Attachment} |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
733 |
\label{fig:attach} |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
734 |
\end{figure} |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
735 |
|
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
736 |
\begin{enumerate} |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
737 |
|
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
738 |
\item A zero alias means to use simple position addressing. Slave 1 exists and |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
739 |
vendor id and product code match the expected values. |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
740 |
|
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
741 |
\item Although the slave with position 0 is found, the product code does not |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
742 |
match, so the configuration is not attached. |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
743 |
|
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
744 |
\item The alias is non-zero, so alias addressing is used. Slave 2 is the first |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
745 |
slave with alias \lstinline+0x2000+. Because the position value is zero, the |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
746 |
same slave is used. |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
747 |
|
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
748 |
\item There is no slave with the given alias, so the configuration can not be |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
749 |
attached. |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
750 |
|
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
751 |
\item Slave 2 is again the first slave with the alias \lstinline+0x2000+, but |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
752 |
position is now 1, so slave 3 is attached. |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
753 |
|
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
754 |
\end{enumerate} |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
755 |
|
1094
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
756 |
%------------------------------------------------------------------------------ |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
757 |
|
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
758 |
\section{Cyclic Operation} |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
759 |
\label{sec:cyclic} |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
760 |
|
1293
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
761 |
|
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
762 |
To enter cyclic operation mode, the master has to be ``activated'' to |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
763 |
calculate the process data image and apply the bus configuration for the first |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
764 |
time. After activation, the application is in charge to send and receive |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
765 |
frames. |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
766 |
|
1297 | 767 |
% TODO |
768 |
% |
|
769 |
% PDO endianess |
|
770 |
% Datagram injection |
|
1094
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
771 |
|
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
772 |
%------------------------------------------------------------------------------ |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
773 |
|
1298 | 774 |
\section{VoE Handlers} |
775 |
\label{sec:api-voe} |
|
776 |
||
777 |
During the configuration phase, the application can create handlers for the |
|
778 |
VoE mailbox protocol described in sec.~\ref{sec:voe}. One VoE handler always |
|
779 |
belongs to a certain slave configuration, so the creation function is a method |
|
780 |
of the slave configuration. |
|
781 |
||
782 |
A VoE handler manages the VoE data and the datagram used to transmit and |
|
783 |
receive VoE messages. Is contains the state machine necessary to transfer VoE |
|
784 |
messages. |
|
785 |
||
786 |
The VoE state machine can only process one operation at a time. As a result, |
|
787 |
either a read or write operation may be issued at a time\footnote{If |
|
788 |
simultaneous sending and receiving is desired, two VoE handlers can be created |
|
789 |
for the slave configuration.}. After the operation is initiated, the handler |
|
790 |
must be executed cyclically until it is finished. After that, the results of |
|
791 |
the operation can be retrieved. |
|
792 |
||
793 |
A VoE handler has an own datagram structure, that is marked for exchange after |
|
794 |
each execution step. So the application can decide, how many handlers to |
|
795 |
execute before sending the corresponding EtherCAT frame(s). |
|
796 |
||
797 |
For more information about the use of VoE handlers see the documentation of |
|
798 |
the application interface functions and the example applications provided in |
|
799 |
the \textit{examples/} directory. |
|
800 |
||
801 |
%------------------------------------------------------------------------------ |
|
802 |
||
1294 | 803 |
\section{Concurrent Master Access} |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
804 |
\label{sec:concurr} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
805 |
\index{Concurrency} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
806 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
807 |
In some cases, one master is used by several instances, for example when an |
1289
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
808 |
application does cyclic process data exchange, and there are EoE-capable |
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
809 |
slaves that require to exchange Ethernet data with the kernel (see |
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
810 |
sec.~\ref{sec:eoe}). For this reason, the master is a shared resource, and |
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
811 |
access to it has to be sequentialized. This is usually done by locking with |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
812 |
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
|
813 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
814 |
The master itself can not provide locking mechanisms, because it has no chance |
1291 | 815 |
to know the appropriate kind of lock. For example if the application is in |
816 |
kernelspace and uses RTAI functionality, ordinary kernel semaphores would not |
|
817 |
be sufficient. For that, an important design decision was made: The |
|
818 |
application that reserved a master must have the total control, therefore it |
|
819 |
has to take responsibility for providing the appropriate locking mechanisms. |
|
1517
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
820 |
If another instance wants to access the master, it has to request the bus |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
821 |
access via callbacks, that have to be provided by the application. Moreover |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
822 |
the application can deny access to the master if it considers it to be awkward |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
823 |
at the moment. |
369 | 824 |
|
825 |
\begin{figure}[htbp] |
|
826 |
\centering |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
827 |
\includegraphics[width=.6\textwidth]{images/master-locks} |
1295 | 828 |
\caption{Concurrent Master Access} |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
829 |
\label{fig:locks} |
369 | 830 |
\end{figure} |
831 |
||
1204
4e3e8400c338
Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents:
1203
diff
changeset
|
832 |
Figure~\ref{fig:locks} exemplary shows, how two processes share one master: |
4e3e8400c338
Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents:
1203
diff
changeset
|
833 |
The application's cyclic task uses the master for process data exchange, while |
4e3e8400c338
Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents:
1203
diff
changeset
|
834 |
the master-internal EoE process uses it to communicate with EoE-capable |
1517
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
835 |
slaves. Both have to access the bus from time to time, but the EoE process |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
836 |
does this by ``asking'' the application to do the bus access for it. In this |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
837 |
way, the application can use the appropriate locking mechanism to avoid |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
838 |
accessing the bus at the same time. See the application interface |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
839 |
documentation (chap.~\ref{chap:api}) for how to use these callbacks. |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
840 |
|
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
841 |
%------------------------------------------------------------------------------ |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
842 |
|
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
843 |
\section{Distributed Clocks} |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
844 |
\label{sec:dc} |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
845 |
\index{Distributed Clocks} |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
846 |
|
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
847 |
From version 1.5, the master supports EtherCAT's ``Distributed Clocks'' |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
848 |
feature. It is possible to synchronize the slave clocks on the bus to the |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
849 |
``reference clock'' (which is the local clock of the first slave with DC |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
850 |
support) and to synchronize the reference clock to the ``master clock'' (which |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
851 |
is the local clock of the master). All other clocks on the bus (after the |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
852 |
reference clock) are considered as ``slave clocks'' (see fig.~\ref{fig:dc}). |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
853 |
|
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
854 |
\begin{figure}[htbp] |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
855 |
\centering |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
856 |
\includegraphics[width=.8\textwidth]{images/dc} |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
857 |
\caption{Distributed Clocks} |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
858 |
\label{fig:dc} |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
859 |
\end{figure} |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
860 |
|
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
861 |
\paragraph{Local Clocks} Any EtherCAT slave that supports DC has a local clock |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
862 |
register with nanosecond resolution. If the slave is powered, the clock starts |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
863 |
from zero, meaning that when slaves are powered on at different times, their |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
864 |
clocks will have different values. These ``offsets'' have to be compensated by |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
865 |
the distributed clocks mechanism. On the other hand, the clocks do not run |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
866 |
exactly with the same speed, since the used quarts units have a natural |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
867 |
frequency deviation. This deviation is usually very small, but over longer |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
868 |
periods, the error would accumulate and the difference between local clocks |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
869 |
would grow. This clock ``drift'' has also to be compensated by the DC |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
870 |
mechanism. |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
871 |
|
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
872 |
\paragraph{Application Time} The common time base for the bus has to be |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
873 |
provided by the application. This application time $t_\text{app}$ is used |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
874 |
|
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
875 |
\begin{enumerate} |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
876 |
\item to configure the slaves' clock offsets (see below), |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
877 |
\item to program the slave's start times for sync pulse generation (see |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
878 |
below). |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
879 |
\item to synchronize the reference clock to the master clock (optional). |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
880 |
\end{enumerate} |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
881 |
|
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
882 |
\paragraph{Offset Compensation} For the offset compensation, each slave |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
883 |
provides a ``System Time Offset'' register $t_\text{off}$, that is added to |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
884 |
the internal clock value $t_\text{int}$ to get the ``System Time'' |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
885 |
$t_\text{sys}$: |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
886 |
|
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
887 |
\begin{eqnarray} |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
888 |
t_\text{sys} & = & t_\text{int} + t_\text{off} \\ |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
889 |
\Rightarrow t_\text{int} & = & t_\text{sys} - t_\text{off} \nonumber |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
890 |
\end{eqnarray} |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
891 |
|
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
892 |
The master reads the values of both registers to calculate a new system time |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
893 |
offset in a way, that the resulting system time shall match the master's |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
894 |
application time $t_\text{app}$: |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
895 |
|
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
896 |
\begin{eqnarray} |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
897 |
t_\text{sys} & \stackrel{!}{=} & t_\text{app} \\ |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
898 |
\Rightarrow t_\text{int} + t_\text{off} & \stackrel{!}{=} & t_\text{app} \nonumber \\ |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
899 |
\Rightarrow t_\text{off} & = & t_\text{app} - t_\text{int} \nonumber \\ |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
900 |
\Rightarrow t_\text{off} & = & t_\text{app} - (t_\text{sys} - t_\text{off}) \nonumber \\ |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
901 |
\Rightarrow t_\text{off} & = & t_\text{app} - t_\text{sys} + t_\text{off} |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
902 |
\end{eqnarray} |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
903 |
|
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
904 |
The small time offset error resulting from the different times of reading and |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
905 |
writing the registers will be compensated by the drift compensation. |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
906 |
|
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
907 |
\paragraph{Drift Compensation} The drift compensation is possible due to a |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
908 |
special mechanism in each DC-capable slave: A write operation to the ``System |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
909 |
time'' register will cause the internal time control loop to compare the |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
910 |
written time (minus the programmed transmission delay, see below) to the |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
911 |
current system time. The calculated time error will be used as an input to the |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
912 |
time controller, that will tune the local clock speed to be a little faster or |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
913 |
slower\footnote{The local slave clock will be incremented either with |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
914 |
\unit{9}{\nano\second}, \unit{10}{\nano\second} or \unit{11}{\nano\second} |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
915 |
every \unit{10}{\nano\second}.}, according to the sign of the error. |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
916 |
|
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
917 |
\paragraph{Transmission Delays} The Ethernet frame needs a small amount of |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
918 |
time to get from slave to slave. The resulting transmission delay times |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
919 |
accumulate on the bus and can reach microsecond magnitude and thus have to be |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
920 |
considered during the drift compensation. EtherCAT slaves supporting DC |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
921 |
provide a mechanism to measure the transmission delays: For each of the four |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
922 |
slave ports there is a receive time register. A write operation to the receive |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
923 |
time register of port 0 starts the measuring and the current system time is |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
924 |
latched and stored in a receive time register once the frame is received on |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
925 |
the corresponding port. The master can read out the relative receive times, |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
926 |
then calculate time delays between the slaves (using its knowledge of the bus |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
927 |
topology), and finally calculate the time delays from the reference clock to |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
928 |
each slave. These values are programmed into the slaves' transmission delay |
2421 | 929 |
registers. In this way, the drift compensation can reach nanosecond synchrony. |
1517
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
930 |
|
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
931 |
\paragraph{Checking Synchrony} DC-capable slaves provide the 32-bit ``System |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
932 |
time difference'' register at address \lstinline+0x092c+, where the system |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
933 |
time difference of the last drift compensation is stored in nanosecond |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
934 |
resolution and in sign-and-magnitude coding\footnote{This allows |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
935 |
broadcast-reading all system time difference registers on the bus to get an |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
936 |
upper approximation}. To check for bus synchrony, the system time difference |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
937 |
registers can also be cyclically read via the command-line-tool (see |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
938 |
sec.~\ref{sec:regaccess}): |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
939 |
|
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
940 |
\begin{lstlisting} |
1917 | 941 |
$ `\textbf{watch -n0 "ethercat reg\_read -p4 -tsm32 0x92c"}` |
1517
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
942 |
\end{lstlisting} |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
943 |
|
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
944 |
\paragraph{Sync Signals} Synchronous clocks are only the prerequisite for |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
945 |
synchronous events on the bus. Each slave with DC support provides two ``sync |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
946 |
signals'', that can be programmed to create events, that will for example |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
947 |
cause the slave application to latch its inputs on a certain time. A sync |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
948 |
event can either be generated once or cyclically, depending on what makes |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
949 |
sense for the slave application. Programming the sync signals is a matter of |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
950 |
setting the so-called ``AssignActivate'' word and the sync signals' cycle- and |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
951 |
shift times. The AssignActivate word is slave-specific and has to be taken |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
952 |
from the XML slave description (\lstinline+Device+ $\rightarrow$ |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
953 |
\lstinline+Dc+), where also typical sync signal configurations ``OpModes'' can |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
954 |
be found. |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
955 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
956 |
%------------------------------------------------------------------------------ |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
957 |
|
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
958 |
\chapter{Ethernet Devices} |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
959 |
\label{sec:devices} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
960 |
|
1203
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
961 |
The EtherCAT protocol is based on the Ethernet standard, so a master relies on |
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
962 |
standard Ethernet hardware to communicate with the bus. |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
963 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
964 |
The term \textit{device} is used as a synonym for Ethernet network interface |
1588
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
965 |
hardware. |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
966 |
|
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
967 |
\paragraph{Native Ethernet Device Drivers} There are native device driver |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
968 |
modules (see sec.~\ref{sec:native-drivers}) that handle Ethernet hardware, |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
969 |
which a master can use to connect to an EtherCAT bus. They offer their |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
970 |
Ethernet hardware to the master module via the device interface (see |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
971 |
sec.~\ref{sec:ecdev}) and must be capable to prepare Ethernet devices either |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
972 |
for EtherCAT (realtime) operation or for ``normal'' operation using the |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
973 |
kernel's network stack. The advantage of this approach is that the master can |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
974 |
operate nearly directly on the hardware, which allows a high performance. The |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
975 |
disadvantage is, that there has to be an EtherCAT-capable version of the |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
976 |
original Ethernet driver. |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
977 |
|
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
978 |
\paragraph{Generic Ethernet Device Driver} From master version 1.5, there is a |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
979 |
generic Ethernet device driver module (see sec.~\ref{sec:generic-driver}), |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
980 |
that uses the lower layers of the network stack to connect to the hardware. |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
981 |
The advantage is, that arbitrary Ethernet hardware can be used for EtherCAT |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
982 |
operation, independently of the actual hardware driver (so all Linux Ethernet |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
983 |
drivers are supported without modifications). The disadvantage is, that this |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
984 |
approach does not support realtime extensions like RTAI, because the Linux |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
985 |
network stack is addressed. Moreover the performance is a little worse than |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
986 |
the native approach, because the Ethernet frame data have to traverse the |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
987 |
network stack. |
369 | 988 |
|
989 |
%------------------------------------------------------------------------------ |
|
990 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
991 |
\section{Network Driver Basics} |
369 | 992 |
\label{sec:networkdrivers} |
993 |
\index{Network drivers} |
|
994 |
||
995 |
EtherCAT relies on Ethernet hardware and the master needs a physical |
|
996 |
Ethernet device to communicate with the bus. Therefore it is necessary |
|
997 |
to understand how Linux handles network devices and their drivers, |
|
998 |
respectively. |
|
999 |
||
1588
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1000 |
\paragraph{Tasks of a Network Driver} Network device drivers usually handle |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1001 |
the lower two layers of the OSI model, that is the physical layer and the |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1002 |
data-link layer. A network device itself natively handles the physical layer |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1003 |
issues: It represents the hardware to connect to the medium and to send and |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1004 |
receive data in the way, the physical layer protocol describes. The network |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1005 |
device driver is responsible for getting data from the kernel's networking |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1006 |
stack and forwarding it to the hardware, that does the physical transmission. |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1007 |
If data is received by the hardware respectively, the driver is notified |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1008 |
(usually by means of an interrupt) and has to read the data from the hardware |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1009 |
memory and forward it to the network stack. There are a few more tasks, a |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1010 |
network device driver has to handle, including queue control, statistics and |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1011 |
device dependent features. |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1012 |
|
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1013 |
\paragraph{Driver Startup} Usually, a driver searches for compatible devices |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1014 |
on module loading. For PCI drivers, this is done by scanning the PCI bus and |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1015 |
checking for known device IDs. If a device is found, data structures are |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1016 |
allocated and the device is taken into operation. |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1017 |
|
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1018 |
\paragraph{Interrupt Operation}\index{Interrupt} A network device usually |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1019 |
provides a hardware interrupt that is used to notify the driver of received |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1020 |
frames and success of transmission, or errors, respectively. The driver has to |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1021 |
register an interrupt service routine |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1022 |
(ISR\index{ISR}\nomenclature{ISR}{Interrupt Service Routine}), that is |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1023 |
executed each time, the hardware signals such an event. If the interrupt was |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1024 |
thrown by the own device (multiple devices can share one hardware interrupt), |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1025 |
the reason for the interrupt has to be determined by reading the device's |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1026 |
interrupt register. For example, if the flag for received frames is set, frame |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1027 |
data has to be copied from hardware to kernel memory and passed to the network |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1028 |
stack. |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1029 |
|
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1030 |
\paragraph{The \lstinline+net_device+ Structure}\index{net\_device} The driver |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1031 |
registers a \lstinline+net_device+ structure for each device to communicate |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1032 |
with the network stack and to create a ``network interface''. In case of an |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1033 |
Ethernet driver, this interface appears as \textit{ethX}, where X is a number |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1034 |
assigned by the kernel on registration. The \lstinline+net_device+ structure |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1035 |
receives events (either from userspace or from the network stack) via several |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1036 |
callbacks, which have to be set before registration. Not every callback is |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1037 |
mandatory, but for reasonable operation the ones below are needed in any case: |
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1038 |
|
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1039 |
\newsavebox\boxopen |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1040 |
\sbox\boxopen{\lstinline+open()+} |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1041 |
\newsavebox\boxstop |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1042 |
\sbox\boxstop{\lstinline+stop()+} |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1043 |
\newsavebox\boxxmit |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1044 |
\sbox\boxxmit{\lstinline+hard_start_xmit()+} |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1045 |
\newsavebox\boxstats |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1046 |
\sbox\boxstats{\lstinline+get_stats()+} |
369 | 1047 |
|
1048 |
\begin{description} |
|
1095 | 1049 |
|
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1050 |
\item[\usebox\boxopen] This function is called when network communication has |
1275
c9de1c0c1f51
*space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents:
1270
diff
changeset
|
1051 |
to be started, for example after a command \lstinline+ip link set ethX up+ |
c9de1c0c1f51
*space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents:
1270
diff
changeset
|
1052 |
from userspace. Frame reception has to be enabled by the driver. |
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1053 |
|
1297 | 1054 |
\item[\usebox\boxstop] The purpose of this callback is to ``close'' the |
1306
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
1055 |
device, i.\,e.\ make the hardware stop receiving frames. |
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1056 |
|
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1057 |
\item[\usebox\boxxmit] This function is called for each frame that has to be |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1058 |
transmitted. The network stack passes the frame as a pointer to an |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1059 |
\lstinline+sk_buff+ structure (``socket buffer''\index{Socket buffer}, see |
1095 | 1060 |
below), which has to be freed after sending. |
1061 |
||
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1062 |
\item[\usebox\boxstats] This call has to return a pointer to the device's |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1063 |
\lstinline+net_device_stats+ structure, which permanently has to be filled with |
1095 | 1064 |
frame statistics. This means, that every time a frame is received, sent, or an |
1065 |
error happened, the appropriate counter in this structure has to be increased. |
|
1066 |
||
1067 |
\end{description} |
|
1068 |
||
1069 |
The actual registration is done with the \lstinline+register_netdev()+ call, |
|
1070 |
unregistering is done with \lstinline+unregister_netdev()+. |
|
369 | 1071 |
|
1588
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1072 |
\paragraph{The \lstinline+netif+ Interface}\index{netif} All other |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1073 |
communication in the direction interface $\to$ network stack is done via the |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1074 |
\lstinline+netif_*()+ calls. For example, on successful device opening, the |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1075 |
network stack has to be notified, that it can now pass frames to the |
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1076 |
interface. This is done by calling \lstinline+netif_start_queue()+. After this |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1077 |
call, the \lstinline+hard_start_xmit()+ callback can be called by the network |
1588
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1078 |
stack. Furthermore a network driver usually manages a frame transmission |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1079 |
queue. If this gets filled up, the network stack has to be told to stop |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1080 |
passing further frames for a while. This happens with a call to |
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1081 |
\lstinline+netif_stop_queue()+. If some frames have been sent, and there is |
1095 | 1082 |
enough space again to queue new frames, this can be notified with |
1083 |
\lstinline+netif_wake_queue()+. Another important call is |
|
1084 |
\lstinline+netif_receive_skb()+\footnote{This function is part of the NAPI |
|
1085 |
(``New API''), that replaces the kernel 2.4 technique for interfacing to the |
|
1086 |
network stack (with \lstinline+netif_rx()+). NAPI is a technique to improve |
|
1087 |
network performance on Linux. Read more in |
|
1088 |
\url{http://www.cyberus.ca/~hadi/usenix-paper.tgz}.}: It passes a frame to the |
|
1089 |
network stack, that was just received by the device. Frame data has to be |
|
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1090 |
included in a so-called ``socket buffer'' for that (see below). |
369 | 1091 |
|
1588
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1092 |
\paragraph{Socket Buffers}\index{Socket buffer} Socket buffers are the basic |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1093 |
data type for the whole network stack. They serve as containers for network |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1094 |
data and are able to quickly add data headers and footers, or strip them off |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1095 |
again. Therefore a socket buffer consists of an allocated buffer and several |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1096 |
pointers that mark beginning of the buffer (\lstinline+head+), beginning of |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1097 |
data (\lstinline+data+), end of data (\lstinline+tail+) and end of buffer |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1098 |
(\lstinline+end+). In addition, a socket buffer holds network header |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1099 |
information and (in case of received data) a pointer to the |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1100 |
\lstinline+net_device+, it was received on. There exist functions that create |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1101 |
a socket buffer (\lstinline+dev_alloc_skb()+), add data either from front |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1102 |
(\lstinline+skb_push()+) or back (\lstinline+skb_put()+), remove data from |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1103 |
front (\lstinline+skb_pull()+) or back (\lstinline+skb_trim()+), or delete the |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1104 |
buffer (\lstinline+kfree_skb()+). A socket buffer is passed from layer to |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1105 |
layer, and is freed by the layer that uses it the last time. In case of |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1106 |
sending, freeing has to be done by the network driver. |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1107 |
|
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1108 |
%------------------------------------------------------------------------------ |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1109 |
|
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1110 |
\section{Native EtherCAT Device Drivers} |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1111 |
\label{sec:native-drivers} |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1112 |
|
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1113 |
There are a few requirements, that applies to Ethernet hardware when used with |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1114 |
a native Ethernet driver with EtherCAT functionality. |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1115 |
|
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1116 |
\paragraph{Dedicated Hardware} For performance and realtime purposes, the |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1117 |
EtherCAT master needs direct and exclusive access to the Ethernet hardware. |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1118 |
This implies that the network device must not be connected to the kernel's |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1119 |
network stack as usual, because the kernel would try to use it as an ordinary |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1120 |
Ethernet device. |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1121 |
|
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1122 |
\paragraph{Interrupt-less Operation}\index{Interrupt} EtherCAT frames travel |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1123 |
through the logical EtherCAT ring and are then sent back to the master. |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1124 |
Communication is highly deterministic: A frame is sent and will be received |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1125 |
again after a constant time, so there is no need to notify the driver about |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1126 |
frame reception: The master can instead query the hardware for received |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1127 |
frames, if it expects them to be already received. |
1095 | 1128 |
|
1129 |
Figure~\ref{fig:interrupt} shows two workflows for cyclic frame transmission |
|
1130 |
and reception with and without interrupts. |
|
369 | 1131 |
|
1132 |
\begin{figure}[htbp] |
|
1133 |
\centering |
|
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1134 |
\includegraphics[width=.9\textwidth]{images/interrupt} |
369 | 1135 |
\caption{Interrupt Operation versus Interrupt-less Operation} |
1136 |
\label{fig:interrupt} |
|
1137 |
\end{figure} |
|
1138 |
||
1095 | 1139 |
In the left workflow ``Interrupt Operation'', the data from the last cycle is |
1140 |
first processed and a new frame is assembled with new datagrams, which is then |
|
1141 |
sent. The cyclic work is done for now. Later, when the frame is received |
|
1142 |
again by the hardware, an interrupt is triggered and the ISR is executed. The |
|
1143 |
ISR will fetch the frame data from the hardware and initiate the frame |
|
1144 |
dissection: The datagrams will be processed, so that the data is ready for |
|
1145 |
processing in the next cycle. |
|
1146 |
||
1147 |
In the right workflow ``Interrupt-less Operation'', there is no hardware |
|
1148 |
interrupt enabled. Instead, the hardware will be polled by the master by |
|
1149 |
executing the ISR. If the frame has been received in the meantime, it will be |
|
1150 |
dissected. The situation is now the same as at the beginning of the left |
|
1151 |
workflow: The received data is processed and a new frame is assembled and |
|
1152 |
sent. There is nothing to do for the rest of the cycle. |
|
1153 |
||
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1154 |
The interrupt-less operation is desirable, because hardware interrupts are not |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1155 |
conducive in improving the driver's realtime behaviour: Their indeterministic |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1156 |
incidences contribute to increasing the jitter. Besides, if a realtime |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1157 |
extension (like RTAI) is used, some additional effort would have to be made to |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1158 |
prioritize interrupts. |
369 | 1159 |
|
1588
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1160 |
\paragraph{Ethernet and EtherCAT Devices} Another issue lies in the way Linux |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1161 |
handles devices of the same type. For example, a |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1162 |
PCI\nomenclature{PCI}{Peripheral Component Interconnect, Computer Bus} driver |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1163 |
scans the PCI bus for devices it can handle. Then it registers itself as the |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1164 |
responsible driver for all of the devices found. The problem is, that an |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1165 |
unmodified driver can not be told to ignore a device because it will be used |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1166 |
for EtherCAT later. There must be a way to handle multiple devices of the same |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1167 |
type, where one is reserved for EtherCAT, while the other is treated as an |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1168 |
ordinary Ethernet device. |
369 | 1169 |
|
1095 | 1170 |
For all this reasons, the author decided that the only acceptable solution is |
1171 |
to modify standard Ethernet drivers in a way that they keep their normal |
|
1172 |
functionality, but gain the ability to treat one or more of the devices as |
|
1173 |
EtherCAT-capable. |
|
369 | 1174 |
|
1175 |
Below are the advantages of this solution: |
|
1176 |
||
1177 |
\begin{itemize} |
|
1178 |
\item No need to tell the standard drivers to ignore certain devices. |
|
1179 |
\item One networking driver for EtherCAT and non-EtherCAT devices. |
|
1180 |
\item No need to implement a network driver from scratch and running |
|
1181 |
into issues, the former developers already solved. |
|
1182 |
\end{itemize} |
|
1183 |
||
1184 |
The chosen approach has the following disadvantages: |
|
1185 |
||
1186 |
\begin{itemize} |
|
1187 |
\item The modified driver gets more complicated, as it must handle |
|
1188 |
EtherCAT and non-EtherCAT devices. |
|
1189 |
\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
|
1190 |
\item Changes and bug fixes on the standard drivers have to be ported |
369 | 1191 |
to the Ether\-CAT-capable versions from time to time. |
1192 |
\end{itemize} |
|
1193 |
||
1194 |
%------------------------------------------------------------------------------ |
|
1195 |
||
1588
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1196 |
\section{Generic EtherCAT Device Driver} |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1197 |
\label{sec:generic-driver} |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1198 |
|
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1199 |
Since there are approaches to enable the complete Linux kernel for realtime |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1200 |
operation \cite{rt-preempt}, it is possible to operate without native |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1201 |
implementations of EtherCAT-capable Ethernet device drivers and use the Linux |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1202 |
network stack instead. Fig.~\ref{fig:arch} shows the ``Generic Ethernet Driver |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1203 |
Module'', that connects to local Ethernet devices via the network stack. The |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1204 |
kernel module is named \lstinline+ec_generic+ and can be loaded after the |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1205 |
master module like a native EtherCAT-capable Ethernet driver. |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1206 |
|
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1207 |
The generic device driver scans the network stack for interfaces, that have |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1208 |
been registered by Ethernet device drivers. It offers all possible devices to |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1209 |
the EtherCAT master. If the master accepts a device, the generic driver |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1210 |
creates a packet socket (see \lstinline+man 7 packet+) with |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1211 |
\lstinline+socket_type+ set to \lstinline+SOCK_RAW+, bound to that device. All |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1212 |
functions of the device interface (see sec.~\ref{sec:ecdev}) will then operate |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1213 |
on that socket. |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1214 |
|
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1215 |
Below are the advantages of this solution: |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1216 |
|
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1217 |
\begin{itemize} |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1218 |
\item Any Ethernet hardware, that is covered by a Linux Ethernet driver can be |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1219 |
used for EtherCAT. |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1220 |
\item No modifications have to be made to the actual Ethernet drivers. |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1221 |
\end{itemize} |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1222 |
|
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1223 |
The generic approach has the following disadvantages: |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1224 |
|
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1225 |
\begin{itemize} |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1226 |
\item The performance is a little worse than the native approach, because the |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1227 |
frame data have to traverse the lower layers of the network stack. |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1228 |
\item It is not possible to use in-kernel realtime extensions like RTAI with |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1229 |
the generic driver, because the network stack code uses dynamic memory |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1230 |
allocations and other things, that could cause the system to freeze in |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1231 |
realtime context. |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1232 |
\end{itemize} |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1233 |
|
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1234 |
%------------------------------------------------------------------------------ |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1235 |
|
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1236 |
\section{Providing Ethernet Devices} |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1237 |
\label{sec:providing-devices} |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1238 |
|
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1239 |
After loading the master module, additional module(s) have to be loaded to |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1240 |
offer devices to the master(s) (see sec.~\ref{sec:ecdev}). The master module |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1241 |
knows the devices to choose from the module parameters (see |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1242 |
sec.~\ref{sec:mastermod}). If the init script is used to start the master, the |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1243 |
drivers and devices to use can be specified in the sysconfig file (see |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1244 |
sec.~\ref{sec:sysconfig}). |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1245 |
|
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1246 |
Modules offering Ethernet devices can be |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1247 |
|
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1248 |
\begin{itemize} |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1249 |
\item native EtherCAT-capable network driver modules (see |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1250 |
sec.~\ref{sec:native-drivers}) or |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1251 |
\item the generic EtherCAT device driver module (see |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1252 |
sec.~\ref{sec:generic-driver}). |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1253 |
\end{itemize} |
369 | 1254 |
|
1255 |
%------------------------------------------------------------------------------ |
|
1256 |
||
1203
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1257 |
\section{EtherCAT Device Interface} |
369 | 1258 |
\label{sec:ecdev} |
1259 |
\index{Device interface} |
|
1260 |
||
1261 |
An anticipation to the section about the master module |
|
1289
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
1262 |
(sec.~\ref{sec:mastermod}) has to be made in order to understand the way, a |
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
1263 |
network device driver module can connect a device to a specific EtherCAT |
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
1264 |
master. |
369 | 1265 |
|
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1266 |
The master module provides a ``device interface'' for network device drivers. |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1267 |
To use this interface, a network device driver module must include the header |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1268 |
\textit{devices/ecdev.h}\nomenclature{ecdev}{EtherCAT Device}, coming with the |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1269 |
EtherCAT master code. This header offers a function interface for EtherCAT |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1270 |
devices. All functions of the device interface are named with the prefix |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1271 |
\lstinline+ecdev+. |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1272 |
|
1289
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
1273 |
The documentation of the device interface can be found in the header file or |
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
1274 |
in the appropriate module of the interface documentation (see |
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
1275 |
sec.~\ref{sec:gendoc} for generation instructions). |
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1276 |
|
1296 | 1277 |
% TODO general description of the device interface |
369 | 1278 |
|
1279 |
%------------------------------------------------------------------------------ |
|
1280 |
||
1588
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1281 |
\section{Patching Native Network Drivers} |
369 | 1282 |
\label{sec:patching} |
1283 |
\index{Network drivers} |
|
1284 |
||
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1285 |
This section will describe, how to make a standard Ethernet driver |
1588
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1286 |
EtherCAT-capable, using the native approach (see |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1287 |
sec.~\ref{sec:native-drivers}). Unfortunately, there is no standard procedure |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1288 |
to enable an Ethernet driver for use with the EtherCAT master, but there are a |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
1289 |
few common techniques. |
369 | 1290 |
|
1291 |
\begin{enumerate} |
|
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1292 |
|
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1293 |
\item A first simple rule is, that \lstinline+netif_*()+ calls must be avoided |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1294 |
for all EtherCAT devices. As mentioned before, EtherCAT devices have no |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1295 |
connection to the network stack, and therefore must not call its interface |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1296 |
functions. |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1297 |
|
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1298 |
\item Another important thing is, that EtherCAT devices should be operated |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1299 |
without interrupts. So any calls of registering interrupt handlers and enabling |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1300 |
interrupts at hardware level must be avoided, too. |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1301 |
|
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1302 |
\item The master does not use a new socket buffer for each send operation: |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1303 |
Instead there is a fix one allocated on master initialization. This socket |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1304 |
buffer is filled with an EtherCAT frame with every send operation and passed to |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1305 |
the \lstinline+hard_start_xmit()+ callback. For that it is necessary, that the |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1306 |
socket buffer is not be freed by the network driver as usual. |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1307 |
|
369 | 1308 |
\end{enumerate} |
1309 |
||
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1310 |
An Ethernet driver usually handles several Ethernet devices, each described by |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1311 |
a \lstinline+net_device+ structure with a \lstinline+priv_data+ field to |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1312 |
attach driver-dependent data to the structure. To distinguish between normal |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1313 |
Ethernet devices and the ones used by EtherCAT masters, the private data |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1314 |
structure used by the driver could be extended by a pointer, that points to an |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1315 |
\lstinline+ec_device_t+ object returned by \lstinline+ecdev_offer()+ (see |
1289
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
1316 |
sec.~\ref{sec:ecdev}) if the device is used by a master and otherwise is zero. |
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1317 |
|
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1318 |
The RealTek RTL-8139 Fast Ethernet driver is a ``simple'' Ethernet driver and |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1319 |
can be taken as an example to patch new drivers. The interesting sections can |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1320 |
be found by searching the string ``ecdev" in the file |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1321 |
\textit{devices/8139too-2.6.24-ethercat.c}. |
369 | 1322 |
|
1323 |
%------------------------------------------------------------------------------ |
|
1324 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1325 |
\chapter{State Machines} |
369 | 1326 |
\label{sec:fsm} |
1327 |
\index{FSM} |
|
1328 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1329 |
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
|
1330 |
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
|
1331 |
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
|
1332 |
possibilities. |
369 | 1333 |
|
1334 |
The below short code example exemplary shows how to read all slave |
|
1335 |
states and moreover illustrates the restrictions of ``sequential'' |
|
1336 |
coding: |
|
1337 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1338 |
\begin{lstlisting}[gobble=2,language=C,numbers=left] |
369 | 1339 |
ec_datagram_brd(datagram, 0x0130, 2); // prepare datagram |
1340 |
if (ec_master_simple_io(master, datagram)) return -1; |
|
1341 |
slave_states = EC_READ_U8(datagram->data); // process datagram |
|
1342 |
\end{lstlisting} |
|
1343 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1344 |
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
|
1345 |
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
|
1346 |
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
|
1347 |
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
|
1348 |
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
|
1349 |
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
|
1350 |
a frame with the queued datagram and then waits actively for its reception. |
369 | 1351 |
|
1289
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
1352 |
This sequential approach is very simple, reflecting in only three lines of |
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
1353 |
code. The disadvantage is, that the master is blocked for the time it waits |
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
1354 |
for datagram reception. There is no difficulty when only one instance is using |
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
1355 |
the master, but if more instances want to (synchronously\footnote{At this |
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
1356 |
time, synchronous master access will be adequate to show the advantages of an |
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
1357 |
FSM. The asynchronous approach will be discussed in sec.~\ref{sec:eoe}}) use |
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
1358 |
the master, it is inevitable to think about an alternative to the sequential |
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
1359 |
model. |
369 | 1360 |
|
1361 |
Master access has to be sequentialized for more than one instance |
|
1362 |
wanting to send and receive datagrams synchronously. With the present |
|
1363 |
approach, this would result in having one phase of active waiting for |
|
1364 |
each instance, which would be non-acceptable especially in realtime |
|
1365 |
circumstances, because of the huge time overhead. |
|
1366 |
||
1367 |
A possible solution is, that all instances would be executed |
|
1368 |
sequentially to queue their datagrams, then give the control to the |
|
1369 |
next instance instead of waiting for the datagram reception. Finally, |
|
1370 |
bus IO is done by a higher instance, which means that all queued |
|
1371 |
datagrams are sent and received. The next step is to execute all |
|
1372 |
instances again, which then process their received datagrams and issue |
|
1373 |
new ones. |
|
1374 |
||
1375 |
This approach results in all instances having to retain their state, |
|
1376 |
when giving the control back to the higher instance. It is quite |
|
1377 |
obvious to use a \textit{finite state machine} model in this case. |
|
1378 |
Section~\ref{sec:fsmtheory} will introduce some of the theory used, |
|
1379 |
while the listings below show the basic approach by coding the example |
|
1380 |
from above as a state machine: |
|
1381 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1382 |
\begin{lstlisting}[gobble=2,language=C,numbers=left] |
369 | 1383 |
// state 1 |
1384 |
ec_datagram_brd(datagram, 0x0130, 2); // prepare datagram |
|
1385 |
ec_master_queue(master, datagram); // queue datagram |
|
1386 |
next_state = state_2; |
|
1387 |
// state processing finished |
|
1388 |
\end{lstlisting} |
|
1389 |
||
1390 |
After all instances executed their current state and queued their |
|
1391 |
datagrams, these are sent and received. Then the respective next |
|
1392 |
states are executed: |
|
1393 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1394 |
\begin{lstlisting}[gobble=2,language=C,numbers=left] |
369 | 1395 |
// state 2 |
1396 |
if (datagram->state != EC_DGRAM_STATE_RECEIVED) { |
|
1397 |
next_state = state_error; |
|
1398 |
return; // state processing finished |
|
1399 |
} |
|
1400 |
slave_states = EC_READ_U8(datagram->data); // process datagram |
|
1401 |
// state processing finished. |
|
1402 |
\end{lstlisting} |
|
1403 |
||
1289
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
1404 |
See sec.~\ref{sec:statemodel} for an introduction to the state machine |
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
1405 |
programming concept used in the master code. |
369 | 1406 |
|
1407 |
%------------------------------------------------------------------------------ |
|
1408 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1409 |
\section{State Machine Theory} |
369 | 1410 |
\label{sec:fsmtheory} |
1411 |
\index{FSM!Theory} |
|
1412 |
||
1413 |
A finite state machine \cite{automata} is a model of behavior with |
|
1414 |
inputs and outputs, where the outputs not only depend on the inputs, |
|
1415 |
but the history of inputs. The mathematical definition of a finite |
|
1416 |
state machine (or finite automaton) is a six-tuple $(\Sigma, \Gamma, |
|
1417 |
S, s_0, \delta, \omega)$, with |
|
1418 |
||
1419 |
\begin{itemize} |
|
1420 |
\item the input alphabet $\Sigma$, with $\Sigma \neq |
|
1421 |
\emptyset$, containing all input symbols, |
|
1422 |
\item the output alphabet $\Gamma$, with $\Gamma \neq |
|
1423 |
\emptyset$, containing all output symbols, |
|
1424 |
\item the set of states $S$, with $S \neq \emptyset$, |
|
1425 |
\item the set of initial states $s_0$ with $s_0 \subseteq S, s_0 \neq |
|
1426 |
\emptyset$ |
|
1427 |
\item the transition function $\delta: S \times \Sigma \rightarrow S |
|
1428 |
\times \Gamma$ |
|
1429 |
\item the output function $\omega$. |
|
1430 |
\end{itemize} |
|
1431 |
||
1432 |
The state transition function $\delta$ is often specified by a |
|
1433 |
\textit{state transition table}, or by a \textit{state transition |
|
1434 |
diagram}. The transition table offers a matrix view of the state |
|
1435 |
machine behavior (see table~\ref{tab:statetrans}). The matrix rows |
|
1436 |
correspond to the states ($S = \{s_0, s_1, s_2\}$) and the columns |
|
1437 |
correspond to the input symbols ($\Gamma = \{a, b, \varepsilon\}$). |
|
1438 |
The table contents in a certain row $i$ and column $j$ then represent |
|
1439 |
the next state (and possibly the output) for the case, that a certain |
|
1440 |
input symbol $\sigma_j$ is read in the state $s_i$. |
|
1441 |
||
1442 |
\begin{table}[htbp] |
|
1443 |
\caption{A typical state transition table} |
|
1444 |
\label{tab:statetrans} |
|
1445 |
\vspace{2mm} |
|
1446 |
\centering |
|
1447 |
\begin{tabular}{l|ccc} |
|
1448 |
& $a$ & $b$ & $\varepsilon$\\ \hline |
|
1449 |
$s_0$ & $s_1$ & $s_1$ & $s_2$\\ |
|
1450 |
$s_1$ & $s_2$ & $s_1$ & $s_0$\\ |
|
1451 |
$s_2$ & $s_0$ & $s_0$ & $s_0$\\ \hline |
|
1452 |
\end{tabular} |
|
1453 |
\end{table} |
|
1454 |
||
1455 |
The state diagram for the same example looks like the one in |
|
1456 |
figure~\ref{fig:statetrans}. The states are represented as circles or |
|
1457 |
ellipses and the transitions are drawn as arrows between them. Close |
|
1458 |
to a transition arrow can be the condition that must be fulfilled to |
|
1459 |
allow the transition. The initial state is marked by a filled black |
|
1460 |
circle with an arrow pointing to the respective state. |
|
1461 |
||
1462 |
\begin{figure}[htbp] |
|
1463 |
\centering |
|
1464 |
\includegraphics[width=.5\textwidth]{images/statetrans} |
|
1465 |
\caption{A typical state transition diagram} |
|
1466 |
\label{fig:statetrans} |
|
1467 |
\end{figure} |
|
1468 |
||
1469 |
\paragraph{Deterministic and non-deterministic state machines} |
|
1470 |
||
1471 |
A state machine can be deterministic, meaning that for one state and |
|
1472 |
input, there is one (and only one) following state. In this case, the |
|
1473 |
state machine has exactly one starting state. Non-deterministic state |
|
1474 |
machines can have more than one transitions for a single state-input |
|
1475 |
combination. There is a set of starting states in the latter case. |
|
1476 |
||
1477 |
\paragraph{Moore and Mealy machines} |
|
1478 |
||
1479 |
There is a distinction between so-called \textit{Moore machines}, and |
|
1480 |
\textit{Mealy machines}. Mathematically spoken, the distinction lies |
|
1481 |
in the output function $\omega$: If it only depends on the current |
|
1482 |
state ($\omega: S \rightarrow \Gamma$), the machine corresponds to the |
|
1483 |
``Moore Model''. Otherwise, if $\omega$ is a function of a state and |
|
1484 |
the input alphabet ($\omega: S \times \Sigma \rightarrow \Gamma$) the |
|
1485 |
state machine corresponds to the ``Mealy model''. Mealy machines are |
|
1486 |
the more practical solution in most cases, because their design allows |
|
1487 |
machines with a minimum number of states. In practice, a mixture of |
|
1488 |
both models is often used. |
|
1489 |
||
1490 |
\paragraph{Misunderstandings about state machines} |
|
1491 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1492 |
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
|
1493 |
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
|
1494 |
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
|
1495 |
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
|
1496 |
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
|
1497 |
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
|
1498 |
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
|
1499 |
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
|
1500 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1501 |
%------------------------------------------------------------------------------ |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1502 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1503 |
\section{The Master's State Model} |
369 | 1504 |
\label{sec:statemodel} |
1505 |
||
1506 |
This section will introduce the techniques used in the master to |
|
1507 |
implement state machines. |
|
1508 |
||
1509 |
\paragraph{State Machine Programming} |
|
1510 |
||
1511 |
There are certain ways to implement a state machine in \textit{C} |
|
1512 |
code. An obvious way is to implement the different states and actions |
|
1513 |
by one big case differentiation: |
|
1514 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1515 |
\begin{lstlisting}[gobble=2,language=C,numbers=left] |
369 | 1516 |
enum {STATE_1, STATE_2, STATE_3}; |
1517 |
int state = STATE_1; |
|
1518 |
||
1519 |
void state_machine_run(void *priv_data) { |
|
1520 |
switch (state) { |
|
1521 |
case STATE_1: |
|
1522 |
action_1(); |
|
1523 |
state = STATE_2; |
|
1524 |
break; |
|
1525 |
case STATE_2: |
|
1526 |
action_2() |
|
1527 |
if (some_condition) state = STATE_1; |
|
1528 |
else state = STATE_3; |
|
1529 |
break; |
|
1530 |
case STATE_3: |
|
1531 |
action_3(); |
|
1532 |
state = STATE_1; |
|
1533 |
break; |
|
1534 |
} |
|
1535 |
} |
|
1536 |
\end{lstlisting} |
|
1537 |
||
1538 |
For small state machines, this is an option. The disadvantage is, that |
|
1539 |
with an increasing number of states the code soon gets complex and an |
|
1540 |
additional case differentiation is executed each run. Besides, lots of |
|
1541 |
indentation is wasted. |
|
1542 |
||
1543 |
The method used in the master is to implement every state in an own |
|
1544 |
function and to store the current state function with a function |
|
1545 |
pointer: |
|
1546 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1547 |
\begin{lstlisting}[gobble=2,language=C,numbers=left] |
369 | 1548 |
void (*state)(void *) = state1; |
1549 |
||
1550 |
void state_machine_run(void *priv_data) { |
|
1551 |
state(priv_data); |
|
1552 |
} |
|
1553 |
||
1554 |
void state1(void *priv_data) { |
|
1555 |
action_1(); |
|
1556 |
state = state2; |
|
1557 |
} |
|
1558 |
||
1559 |
void state2(void *priv_data) { |
|
1560 |
action_2(); |
|
1561 |
if (some_condition) state = state1; |
|
1562 |
else state = state2; |
|
1563 |
} |
|
1564 |
||
1565 |
void state3(void *priv_data) { |
|
1566 |
action_3(); |
|
1567 |
state = state1; |
|
1568 |
} |
|
1569 |
\end{lstlisting} |
|
1570 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1571 |
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
|
1572 |
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
|
1573 |
parallel. For this reason each EoE handler object has its own state pointer.} |
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1574 |
are gathered in a single object of the \lstinline+ec_fsm_master_t+ class. This |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1575 |
is advantageous, because there is always one instance of every state machine |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1576 |
available and can be started on demand. |
369 | 1577 |
|
1578 |
\paragraph{Mealy and Moore} |
|
1579 |
||
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1580 |
If a closer look is taken to the above listing, it can be seen that the |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1581 |
actions executed (the ``outputs'' of the state machine) only depend on the |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1582 |
current state. This accords to the ``Moore'' model introduced in |
1289
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
1583 |
sec.~\ref{sec:fsmtheory}. As mentioned, the ``Mealy'' model offers a higher |
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1584 |
flexibility, which can be seen in the listing below: |
369 | 1585 |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1586 |
\begin{lstlisting}[gobble=2,language=C,numbers=left] |
369 | 1587 |
void state7(void *priv_data) { |
1588 |
if (some_condition) { |
|
1589 |
action_7a(); |
|
1590 |
state = state1; |
|
1591 |
} |
|
1592 |
else { |
|
1593 |
action_7b(); |
|
1594 |
state = state8; |
|
1595 |
} |
|
1596 |
} |
|
1597 |
\end{lstlisting} |
|
1598 |
||
1599 |
\begin{description} |
|
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1600 |
|
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1601 |
\item[\linenum{3} + \linenum{7}] The state function executes the actions |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1602 |
depending on the state transition, that is about to be done. |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1603 |
|
369 | 1604 |
\end{description} |
1605 |
||
1606 |
The most flexible alternative is to execute certain actions depending |
|
1607 |
on the state, followed by some actions dependent on the state |
|
1608 |
transition: |
|
1609 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1610 |
\begin{lstlisting}[gobble=2,language=C,numbers=left] |
369 | 1611 |
void state9(void *priv_data) { |
1612 |
action_9(); |
|
1613 |
if (some_condition) { |
|
1614 |
action_9a(); |
|
1615 |
state = state7; |
|
1616 |
} |
|
1617 |
else { |
|
1618 |
action_9b(); |
|
1619 |
state = state10; |
|
1620 |
} |
|
1621 |
} |
|
1622 |
\end{lstlisting} |
|
1623 |
||
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1624 |
This model is often used in the master. It combines the best aspects of both |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1625 |
approaches. |
369 | 1626 |
|
1627 |
\paragraph{Using Sub State Machines} |
|
1628 |
||
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1629 |
To avoid having too much states, certain functions of the EtherCAT master |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1630 |
state machine have been sourced out into sub state machines. This helps to |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1631 |
encapsulate the related workflows and moreover avoids the ``state explosion'' |
1289
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
1632 |
phenomenon described in sec.~\ref{sec:fsmtheory}. If the master would instead |
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
1633 |
use one big state machine, the number of states would be a multiple of the |
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
1634 |
actual number. This would increase the level of complexity to a non-manageable |
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
1635 |
grade. |
369 | 1636 |
|
1637 |
\paragraph{Executing Sub State Machines} |
|
1638 |
||
1639 |
If a state machine starts to execute a sub state machine, it usually |
|
1640 |
remains in one state until the sub state machine terminates. This is |
|
1641 |
usually done like in the listing below, which is taken out of the |
|
1642 |
slave configuration state machine code: |
|
1643 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1644 |
\begin{lstlisting}[gobble=2,language=C,numbers=left] |
813
bfc3f1ab52de
Fixed typo SAVEOP -> SAFEOP.
Florian Pose <fp@igh-essen.com>
parents:
487
diff
changeset
|
1645 |
void ec_fsm_slaveconf_safeop(ec_fsm_t *fsm) |
369 | 1646 |
{ |
1647 |
fsm->change_state(fsm); // execute state change |
|
1648 |
// sub state machine |
|
1649 |
||
1650 |
if (fsm->change_state == ec_fsm_error) { |
|
1651 |
fsm->slave_state = ec_fsm_end; |
|
1652 |
return; |
|
1653 |
} |
|
1654 |
||
1655 |
if (fsm->change_state != ec_fsm_end) return; |
|
1656 |
||
1657 |
// continue state processing |
|
1658 |
... |
|
1659 |
\end{lstlisting} |
|
1660 |
||
1661 |
\begin{description} |
|
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1662 |
|
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1663 |
\item[\linenum{3}] \lstinline+change_state+ is the state pointer of the state |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1664 |
change state machine. The state function, the pointer points on, is |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1665 |
executed\ldots |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1666 |
|
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1667 |
\item[\linenum{6}] \ldots either until the state machine terminates with the |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1668 |
error state \ldots |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1669 |
|
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1670 |
\item[\linenum{11}] \ldots or until the state machine terminates in the end |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1671 |
state. Until then, the ``higher'' state machine remains in the current state |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1672 |
and executes the sub state machine again in the next cycle. |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1673 |
|
369 | 1674 |
\end{description} |
1675 |
||
1676 |
\paragraph{State Machine Descriptions} |
|
1677 |
||
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1678 |
The below sections describe every state machine used in the EtherCAT master. |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1679 |
The textual descriptions of the state machines contain references to the |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1680 |
transitions in the corresponding state transition diagrams, that are marked |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1681 |
with an arrow followed by the name of the successive state. Transitions caused |
1306
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
1682 |
by trivial error cases (i.\,e.\ no response from slave) are not described |
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1683 |
explicitly. These transitions are drawn as dashed arrows in the diagrams. |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1684 |
|
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1685 |
%------------------------------------------------------------------------------ |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1686 |
|
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1687 |
\section{The Master State Machine} |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1688 |
\label{sec:fsm-master} |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1689 |
\index{FSM!Master} |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1690 |
|
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1691 |
The master state machine is executed in the context of the master thread. |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1692 |
Figure~\ref{fig:fsm-master} shows its transition diagram. Its purposes are: |
369 | 1693 |
|
1694 |
\begin{figure}[htbp] |
|
1695 |
\centering |
|
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1696 |
\includegraphics[width=\textwidth]{graphs/fsm_master} |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1697 |
\caption{Transition diagram of the master state machine} |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1698 |
\label{fig:fsm-master} |
369 | 1699 |
\end{figure} |
1700 |
||
1701 |
\begin{description} |
|
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1702 |
|
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1703 |
\item[Bus monitoring] The bus topology is monitored. If it changes, the bus is |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1704 |
(re-)scanned. |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1705 |
|
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1706 |
\item[Slave configuration] The application-layer states of the slaves are |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1707 |
monitored. If a slave is not in the state it supposed to be, the slave is |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1708 |
(re-)configured. |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1709 |
|
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1710 |
\item[Request handling] Requests (either originating from the application or |
1203
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1711 |
from external sources) are handled. A request is a job that the master shall |
1327
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
1712 |
process asynchronously, for example an SII access, SDO access, or similar. |
369 | 1713 |
|
1714 |
\end{description} |
|
1715 |
||
1716 |
%------------------------------------------------------------------------------ |
|
1717 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1718 |
\section{The Slave Scan State Machine} |
369 | 1719 |
\label{sec:fsm-scan} |
1720 |
\index{FSM!Slave Scan} |
|
1721 |
||
1722 |
The slave scan state machine, which can be seen in |
|
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1723 |
figure~\ref{fig:fsm-slavescan}, leads through the process of reading desired |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1724 |
slave information. |
369 | 1725 |
|
1726 |
\begin{figure}[htbp] |
|
1727 |
\centering |
|
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1728 |
\includegraphics[height=.8\textheight]{graphs/fsm_slave_scan} |
369 | 1729 |
\caption{Transition diagram of the slave scan state machine} |
1730 |
\label{fig:fsm-slavescan} |
|
1731 |
\end{figure} |
|
1732 |
||
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1733 |
The scan process includes the following steps: |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1734 |
|
369 | 1735 |
\begin{description} |
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1736 |
|
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1737 |
\item[Node Address] The node address is set for the slave, so that it can be |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1738 |
node-addressed for all following operations. |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1739 |
|
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1740 |
\item[AL State] The initial application-layer state is read. |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1741 |
|
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1742 |
\item[Base Information] Base information (like the number of supported FMMUs) |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1743 |
is read from the lower physical memory. |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1744 |
|
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1745 |
\item[Data Link] Information about the physical ports is read. |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1746 |
|
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1747 |
\item[SII Size] The size of the SII contents is determined to allocate SII |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1748 |
image memory. |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1749 |
|
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1750 |
\item[SII Data] The SII contents are read into the master's image. |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1751 |
|
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1752 |
\item[PREOP] If the slave supports CoE, it is set to PREOP state using the |
1289
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
1753 |
State change FSM (see sec.~\ref{sec:fsm-change}) to enable mailbox |
1327
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
1754 |
communication and read the PDO configuration via CoE. |
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
1755 |
|
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
1756 |
\item[PDOs] The PDOs are read via CoE (if supported) using the PDO Reading FSM |
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
1757 |
(see sec.~\ref{sec:fsm-pdo}). If this is successful, the PDO information from |
1289
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
1758 |
the SII (if any) is overwritten. |
369 | 1759 |
|
1760 |
\end{description} |
|
1761 |
||
1762 |
%------------------------------------------------------------------------------ |
|
1763 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1764 |
\section{The Slave Configuration State Machine} |
369 | 1765 |
\label{sec:fsm-conf} |
1766 |
\index{FSM!Slave Configuration} |
|
1767 |
||
1768 |
The slave configuration state machine, which can be seen in |
|
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1769 |
figure~\ref{fig:fsm-slaveconf}, leads through the process of configuring a |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1770 |
slave and bringing it to a certain application-layer state. |
369 | 1771 |
|
1772 |
\begin{figure}[htbp] |
|
1773 |
\centering |
|
1406
8686c5b3d14b
Clear DC assignment after going to INIT.
Florian Pose <fp@igh-essen.com>
parents:
1399
diff
changeset
|
1774 |
\includegraphics[height=\textheight]{graphs/fsm_slave_conf} |
369 | 1775 |
\caption{Transition diagram of the slave configuration state |
1776 |
machine} |
|
1777 |
\label{fig:fsm-slaveconf} |
|
1778 |
\end{figure} |
|
1779 |
||
1780 |
\begin{description} |
|
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1781 |
|
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1782 |
\item[INIT] The state change FSM is used to bring the slave to the INIT state. |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1783 |
|
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1784 |
\item[FMMU Clearing] To avoid that the slave reacts on any process data, the |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1785 |
FMMU configuration are cleared. If the slave does not support FMMUs, this |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1786 |
state is skipped. If INIT is the requested state, the state machine is |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1787 |
finished. |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1788 |
|
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1789 |
\item[Mailbox Sync Manager Configuration] If the slaves support mailbox |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1790 |
communication, the mailbox sync managers are configured. Otherwise this state |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1791 |
is skipped. |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1792 |
|
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1793 |
\item[PREOP] The state change FSM is used to bring the slave to PREOP state. |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1794 |
If this is the requested state, the state machine is finished. |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1795 |
|
1327
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
1796 |
\item[SDO Configuration] If there is a slave configuration attached (see |
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
1797 |
sec.~\ref{sec:masterconfig}), and there are any SDO configurations are |
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1798 |
provided by the application, these are sent to the slave. |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1799 |
|
1327
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
1800 |
\item[PDO Configuration] The PDO configuration state machine is executed to |
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
1801 |
apply all necessary PDO configurations. |
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
1802 |
|
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
1803 |
\item[PDO Sync Manager Configuration] If any PDO sync managers exist, they are |
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1804 |
configured. |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1805 |
|
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1806 |
\item[FMMU Configuration] If there are FMMUs configurations supplied by the |
1327
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
1807 |
application (i.\,e.\ if the application registered PDO entries), they are |
2421 | 1808 |
applied. |
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1809 |
|
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1810 |
\item[SAFEOP] The state change FSM is used to bring the slave to SAFEOP state. |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1811 |
If this is the requested state, the state machine is finished. |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1812 |
|
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1813 |
\item[OP] The state change FSM is used to bring the slave to OP state. |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1814 |
If this is the requested state, the state machine is finished. |
369 | 1815 |
|
1816 |
\end{description} |
|
1817 |
||
1818 |
%------------------------------------------------------------------------------ |
|
1819 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1820 |
\section{The State Change State Machine} |
369 | 1821 |
\label{sec:fsm-change} |
1822 |
\index{FSM!State Change} |
|
1823 |
||
1824 |
The state change state machine, which can be seen in |
|
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1825 |
figure~\ref{fig:fsm-change}, leads through the process of changing a slave's |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1826 |
application-layer state. This implements the states and transitions described |
1289
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
1827 |
in \cite[sec.~6.4.1]{alspec}. |
369 | 1828 |
|
1829 |
\begin{figure}[htbp] |
|
1830 |
\centering |
|
1203
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1831 |
\includegraphics[width=.6\textwidth]{graphs/fsm_change} |
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1832 |
\caption{Transition Diagram of the State Change State Machine} |
369 | 1833 |
\label{fig:fsm-change} |
1834 |
\end{figure} |
|
1835 |
||
1836 |
\begin{description} |
|
1203
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1837 |
|
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1838 |
\item[Start] The new application-layer state is requested via the ``AL Control |
1306
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
1839 |
Request'' register (see~\cite[sec. 5.3.1]{alspec}). |
1203
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1840 |
|
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1841 |
\item[Check for Response] Some slave need some time to respond to an AL state |
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1842 |
change command, and do not respond for some time. For this case, the command |
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1843 |
is issued again, until it is acknowledged. |
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1844 |
|
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1845 |
\item[Check AL Status] If the AL State change datagram was acknowledged, the |
1289
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
1846 |
``AL Control Response'' register (see~\cite[sec. 5.3.2]{alspec}) must be read |
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
1847 |
out until the slave changes the AL state. |
1203
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1848 |
|
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1849 |
\item[AL Status Code] If the slave refused the state change command, the |
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1850 |
reason can be read from the ``AL Status Code'' field in the ``AL State |
1289
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
1851 |
Changed'' registers (see~\cite[sec. 5.3.3]{alspec}). |
1203
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1852 |
|
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1853 |
\item[Acknowledge State] If the state change was not successful, the master |
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1854 |
has to acknowledge the old state by writing to the ``AL Control request'' |
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1855 |
register again. |
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1856 |
|
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1857 |
\item[Check Acknowledge] After sending the acknowledge command, it has to read |
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1858 |
out the ``AL Control Response'' register again. |
369 | 1859 |
|
1860 |
\end{description} |
|
1861 |
||
1203
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1862 |
The ``start\_ack'' state is a shortcut in the state machine for the case, that |
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1863 |
the master wants to acknowledge a spontaneous AL state change, that was not |
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1864 |
requested. |
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1865 |
|
369 | 1866 |
%------------------------------------------------------------------------------ |
1867 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1868 |
\section{The SII State Machine} |
369 | 1869 |
\label{sec:fsm-sii} |
1870 |
\index{FSM!SII} |
|
1871 |
||
1872 |
The SII\index{SII} state machine (shown in figure~\ref{fig:fsm-sii}) |
|
1289
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
1873 |
implements the process of reading or writing SII data via the Slave |
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
1874 |
Information Interface described in \cite[sec.~6.4]{dlspec}. |
369 | 1875 |
|
1876 |
\begin{figure}[htbp] |
|
1877 |
\centering |
|
1203
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1878 |
\includegraphics[width=.5\textwidth]{graphs/fsm_sii} |
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1879 |
\caption{Transition Diagram of the SII State Machine} |
369 | 1880 |
\label{fig:fsm-sii} |
1881 |
\end{figure} |
|
1882 |
||
1203
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1883 |
This is how the reading part of the state machine works: |
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
1884 |
|
369 | 1885 |
\begin{description} |
1203
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1886 |
|
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1887 |
\item[Start Reading] The read request and the requested word address are |
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1888 |
written to the SII attribute. |
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1889 |
|
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1890 |
\item[Check Read Command] If the SII read request command has been |
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1891 |
acknowledged, a timer is started. A datagram is issued, that reads out the SII |
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1892 |
attribute for state and data. |
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1893 |
|
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1894 |
\item[Fetch Data] If the read operation is still busy (the SII is usually |
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1895 |
implemented as an E$^2$PROM), the state is read again. Otherwise the data are |
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1896 |
copied from the datagram. |
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1897 |
|
369 | 1898 |
\end{description} |
1899 |
||
1203
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1900 |
The writing part works nearly similar: |
369 | 1901 |
|
1902 |
\begin{description} |
|
1203
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1903 |
|
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1904 |
\item[Start Writing] A write request, the target address and the data word are |
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1905 |
written to the SII attribute. |
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1906 |
|
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1907 |
\item[Check Write Command] If the SII write request command has been |
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1908 |
acknowledged, a timer is started. A datagram is issued, that reads out the SII |
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1909 |
attribute for the state of the write operation. |
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1910 |
|
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1911 |
\item[Wait while Busy] If the write operation is still busy (determined by a |
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1912 |
minimum wait time and the state of the busy flag), the state machine remains in |
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1913 |
this state to avoid that another write operation is issued too early. |
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1914 |
|
369 | 1915 |
\end{description} |
1916 |
||
1917 |
%------------------------------------------------------------------------------ |
|
1918 |
||
1327
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
1919 |
\section{The PDO State Machines} |
1203
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1920 |
\label{sec:fsm-pdo} |
1327
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
1921 |
\index{FSM!PDO} |
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
1922 |
|
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
1923 |
The PDO state machines are a set of state machines that read or write the PDO |
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
1924 |
assignment and the PDO mapping via the ``CoE Communication Area'' described in |
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
1925 |
\cite[sec. 5.6.7.4]{alspec}. For the object access, the CANopen over EtherCAT |
1289
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
1926 |
access primitives are used (see sec.~\ref{sec:coe}), so the slave must support |
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
1927 |
the CoE mailbox protocol. |
1203
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1928 |
|
1327
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
1929 |
\paragraph{PDO Reading FSM} This state machine (fig.~\ref{fig:fsm-pdo-read}) |
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
1930 |
has the purpose to read the complete PDO configuration of a slave. It reads |
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
1931 |
the PDO assignment for each Sync Manager and uses the PDO Entry Reading FSM |
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
1932 |
(fig.~\ref{fig:fsm-pdo-entry-read}) to read the mapping for each assigned PDO. |
1203
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1933 |
|
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1934 |
\begin{figure}[htbp] |
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1935 |
\centering |
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1936 |
\includegraphics[width=.4\textwidth]{graphs/fsm_pdo_read} |
1327
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
1937 |
\caption{Transition Diagram of the PDO Reading State Machine} |
1203
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1938 |
\label{fig:fsm-pdo-read} |
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1939 |
\end{figure} |
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1940 |
|
1327
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
1941 |
Basically it reads the every Sync manager's PDO assignment SDO's |
1203
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1942 |
(\lstinline+0x1C1x+) number of elements to determine the number of assigned |
1327
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
1943 |
PDOs for this sync manager and then reads out the subindices of the SDO to get |
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
1944 |
the assigned PDO's indices. When a PDO index is read, the PDO Entry Reading |
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
1945 |
FSM is executed to read the PDO's mapped PDO entries. |
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
1946 |
|
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
1947 |
\paragraph{PDO Entry Reading FSM} This state machine |
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
1948 |
(fig.~\ref{fig:fsm-pdo-entry-read}) reads the PDO mapping (the PDO entries) of |
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
1949 |
a PDO. It reads the respective mapping SDO (\lstinline+0x1600+ -- |
1293
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
1950 |
\lstinline+0x17ff+, or \lstinline+0x1a00+ -- \lstinline+0x1bff+) for the given |
1327
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
1951 |
PDO by reading first the subindex zero (number of elements) to determine the |
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
1952 |
number of mapped PDO entries. After that, each subindex is read to get the |
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
1953 |
mapped PDO entry index, subindex and bit size. |
1203
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1954 |
|
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1955 |
\begin{figure}[htbp] |
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1956 |
\centering |
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1957 |
\includegraphics[width=.4\textwidth]{graphs/fsm_pdo_entry_read} |
1327
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
1958 |
\caption{Transition Diagram of the PDO Entry Reading State Machine} |
1204
4e3e8400c338
Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents:
1203
diff
changeset
|
1959 |
\label{fig:fsm-pdo-entry-read} |
1203
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1960 |
\end{figure} |
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1961 |
|
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1962 |
\begin{figure}[htbp] |
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1963 |
\centering |
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1964 |
\includegraphics[width=.9\textwidth]{graphs/fsm_pdo_conf} |
1327
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
1965 |
\caption{Transition Diagram of the PDO Configuration State Machine} |
1204
4e3e8400c338
Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents:
1203
diff
changeset
|
1966 |
\label{fig:fsm-pdo-conf} |
1203
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1967 |
\end{figure} |
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1968 |
|
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1969 |
\begin{figure}[htbp] |
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1970 |
\centering |
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1971 |
\includegraphics[width=.4\textwidth]{graphs/fsm_pdo_entry_conf} |
1327
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
1972 |
\caption{Transition Diagram of the PDO Entry Configuration State Machine} |
1204
4e3e8400c338
Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents:
1203
diff
changeset
|
1973 |
\label{fig:fsm-pdo-entry-conf} |
1203
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1974 |
\end{figure} |
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1975 |
|
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1976 |
%------------------------------------------------------------------------------ |
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
1977 |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1978 |
\chapter{Mailbox Protocol Implementations} |
369 | 1979 |
\index{Mailbox} |
1980 |
||
1917 | 1981 |
The EtherCAT master implements the CANopen over EtherCAT (CoE), Ethernet over |
1982 |
EtherCAT (EoE), File-access over EtherCAT (FoE), Vendor-specific over EtherCAT |
|
1983 |
(VoE) and Servo Profile over EtherCAT (SoE) mailbox protocols. See the below |
|
1984 |
sections for details. |
|
369 | 1985 |
|
1986 |
%------------------------------------------------------------------------------ |
|
1987 |
||
1327
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
1988 |
\section{Ethernet over EtherCAT (EoE)} |
1269
fe4688f2c9e7
sec:ecrt is a chapter; sec:eoeimp -> sec:eoe, ...
Florian Pose <fp@igh-essen.com>
parents:
1235
diff
changeset
|
1989 |
\label{sec:eoe} |
369 | 1990 |
\index{EoE} |
1991 |
||
1306
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
1992 |
The EtherCAT master implements the |
1327
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
1993 |
Ethernet over EtherCAT\nomenclature{EoE}{Ethernet over EtherCAT, Mailbox |
1306
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
1994 |
Protocol} mailbox protocol~\cite[sec.~5.7]{alspec} to enable the tunneling of |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
1995 |
Ethernet frames to special slaves, that can either have physical Ethernet |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
1996 |
ports to forward the frames to, or have an own IP stack to receive the frames. |
369 | 1997 |
|
1998 |
\paragraph{Virtual Network Interfaces} |
|
1999 |
||
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2000 |
The master creates a virtual EoE network interface for every EoE-capable |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2001 |
slave. These interfaces are called either |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2002 |
|
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2003 |
\begin{description} |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2004 |
|
1293
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
2005 |
\item[eoeXsY] for a slave without an alias address (see |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
2006 |
sec.~\ref{sec:ethercat-alias}), where X is the master index and Y is the |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
2007 |
slave's ring position, or |
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2008 |
|
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2009 |
\item[eoeXaY] for a slave with a non-zero alias address, where X is the master |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2010 |
index and Y is the decimal alias address. |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2011 |
|
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2012 |
\end{description} |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2013 |
|
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2014 |
Frames sent to these interfaces are forwarded to the associated slaves by the |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2015 |
master. Frames, that are received by the slaves, are fetched by the master and |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2016 |
forwarded to the virtual interfaces. |
369 | 2017 |
|
2018 |
This bears the following advantages: |
|
2019 |
||
2020 |
\begin{itemize} |
|
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2021 |
|
369 | 2022 |
\item Flexibility: The user can decide, how the EoE-capable slaves are |
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2023 |
interconnected with the rest of the world. |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2024 |
|
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2025 |
\item Standard tools can be used to monitor the EoE activity and to configure |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2026 |
the EoE interfaces. |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2027 |
|
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2028 |
\item The Linux kernel's layer-2-bridging implementation (according to the |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2029 |
IEEE 802.1D MAC Bridging standard) can be used natively to bridge Ethernet |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2030 |
traffic between EoE-capable slaves. |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2031 |
|
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2032 |
\item The Linux kernel's network stack can be used to route packets between |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2033 |
EoE-capable slaves and to track security issues, just like having physical |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2034 |
network interfaces. |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2035 |
|
369 | 2036 |
\end{itemize} |
2037 |
||
2038 |
\paragraph{EoE Handlers} |
|
2039 |
||
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2040 |
The virtual EoE interfaces and the related functionality is encapsulated in |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2041 |
the \lstinline+ec_eoe_t+ class. An object of this class is called ``EoE |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2042 |
handler''. For example the master does not create the network interfaces |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2043 |
directly: This is done inside the constructor of an EoE handler. An EoE |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2044 |
handler additionally contains a frame queue. Each time, the kernel passes a |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2045 |
new socket buffer for sending via the interface's |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2046 |
\lstinline+hard_start_xmit()+ callback, the socket buffer is queued for |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2047 |
transmission by the EoE state machine (see below). If the queue gets filled |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2048 |
up, the passing of new socket buffers is suspended with a call to |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2049 |
\lstinline+netif_stop_queue()+. |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2050 |
|
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2051 |
\paragraph{Creation of EoE Handlers} |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2052 |
|
1289
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
2053 |
During bus scanning (see sec.~\ref{sec:fsm-scan}), the master determines the |
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
2054 |
supported mailbox protocols foe each slave. This is done by examining the |
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2055 |
``Supported Mailbox Protocols'' mask field at word address 0x001C of the |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2056 |
SII\index{SII}. If bit 1 is set, the slave supports the EoE protocol. In this |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2057 |
case, an EoE handler is created for that slave. |
369 | 2058 |
|
2059 |
\paragraph{EoE State Machine} |
|
2060 |
\index{FSM!EoE} |
|
2061 |
||
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2062 |
Every EoE handler owns an EoE state machine, that is used to send frames to |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2063 |
the corresponding slave and receive frames from the it via the EoE |
369 | 2064 |
communication primitives. This state machine is showed in |
2065 |
figure~\ref{fig:fsm-eoe}. |
|
2066 |
||
2067 |
\begin{figure}[htbp] |
|
2068 |
\centering |
|
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2069 |
\includegraphics[width=.7\textwidth]{images/fsm-eoe} % FIXME |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2070 |
\caption{Transition Diagram of the EoE State Machine} |
369 | 2071 |
\label{fig:fsm-eoe} |
2072 |
\end{figure} |
|
2073 |
||
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2074 |
% FIXME |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2075 |
|
369 | 2076 |
\begin{description} |
2077 |
\item[RX\_START] The beginning state of the EoE state machine. A |
|
2078 |
mailbox check datagram is sent, to query the slave's mailbox for new |
|
379 | 2079 |
frames. $\rightarrow$~RX\_CHECK |
369 | 2080 |
|
2081 |
\item[RX\_CHECK] The mailbox check datagram is received. If the |
|
2082 |
slave's mailbox did not contain data, a transmit cycle is started. |
|
379 | 2083 |
$\rightarrow$~TX\_START |
369 | 2084 |
|
2085 |
If there are new data in the mailbox, a datagram is sent to fetch |
|
379 | 2086 |
the new data. $\rightarrow$~RX\_FETCH |
369 | 2087 |
|
2088 |
\item[RX\_FETCH] The fetch datagram is received. If the mailbox data |
|
2089 |
do not contain a ``EoE Fragment request'' command, the data are |
|
2090 |
dropped and a transmit sequence is started. |
|
379 | 2091 |
$\rightarrow$~TX\_START |
369 | 2092 |
|
2093 |
If the received Ethernet frame fragment is the first fragment, a new |
|
2094 |
socket buffer is allocated. In either case, the data are copied into |
|
2095 |
the correct position of the socket buffer. |
|
2096 |
||
2097 |
If the fragment is the last fragment, the socket buffer is forwarded |
|
2098 |
to the network stack and a transmit sequence is started. |
|
379 | 2099 |
$\rightarrow$~TX\_START |
369 | 2100 |
|
2101 |
Otherwise, a new receive sequence is started to fetch the next |
|
379 | 2102 |
fragment. $\rightarrow$~RX\_\-START |
369 | 2103 |
|
2104 |
\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
|
2105 |
checked, if the transmission queue contains a frame to send. If not, |
379 | 2106 |
a receive sequence is started. $\rightarrow$~RX\_START |
369 | 2107 |
|
2108 |
If there is a frame to send, it is dequeued. If the queue was |
|
2109 |
inactive before (because it was full), the queue is woken up with a |
|
2110 |
call to \textit{netif\_wake\_queue()}. The first fragment of the |
|
379 | 2111 |
frame is sent. $\rightarrow$~TX\_SENT |
369 | 2112 |
|
2113 |
\item[TX\_SENT] It is checked, if the first fragment was sent |
|
2114 |
successfully. If the current frame consists of further fragments, |
|
379 | 2115 |
the next one is sent. $\rightarrow$~TX\_SENT |
369 | 2116 |
|
2117 |
If the last fragment was sent, a new receive sequence is started. |
|
379 | 2118 |
$\rightarrow$~RX\_START |
369 | 2119 |
\end{description} |
2120 |
||
2121 |
\paragraph{EoE Processing} |
|
2122 |
||
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2123 |
To execute the EoE state machine of every active EoE handler, there must be a |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2124 |
cyclic process. The easiest solution would be to execute the EoE state |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2125 |
machines synchronously with the master state machine (see |
1289
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
2126 |
sec.~\ref{sec:fsm-master}). This approach has the following disadvantage: |
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2127 |
|
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2128 |
Only one EoE fragment could be sent or received every few cycles. This |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2129 |
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
|
2130 |
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
|
2131 |
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
|
2132 |
|
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2133 |
To overcome this problem, an own cyclic process is needed to asynchronously |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2134 |
execute the EoE state machines. For that, the master owns a kernel timer, that |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2135 |
is executed each timer interrupt. This guarantees a constant bandwidth, but |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2136 |
poses the new problem of concurrent access to the master. The locking |
1289
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
2137 |
mechanisms needed for this are introduced in sec.~\ref{sec:concurr}. |
369 | 2138 |
|
2139 |
\paragraph{Automatic Configuration} |
|
2140 |
||
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2141 |
By default, slaves are left in PREOP state, if no configuration is applied. If |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2142 |
an EoE interface link is set to ``up'', the requested slave's |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2143 |
application-layer state is automatically set to OP. |
369 | 2144 |
|
2145 |
%------------------------------------------------------------------------------ |
|
2146 |
||
1327
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
2147 |
\section{CANopen over EtherCAT (CoE)} |
1269
fe4688f2c9e7
sec:ecrt is a chapter; sec:eoeimp -> sec:eoe, ...
Florian Pose <fp@igh-essen.com>
parents:
1235
diff
changeset
|
2148 |
\label{sec:coe} |
369 | 2149 |
\index{CoE} |
2150 |
||
1327
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
2151 |
The CANopen over EtherCAT\nomenclature{CoE}{CANopen over EtherCAT, Mailbox |
1306
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
2152 |
Protocol} protocol~\cite[sec.~5.6]{alspec} is used to configure slaves and |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
2153 |
exchange data objects on application level. |
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2154 |
|
1297 | 2155 |
% TODO |
1203
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
2156 |
% |
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
2157 |
% Download / Upload |
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
2158 |
% Expedited / Normal |
1204
4e3e8400c338
Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents:
1203
diff
changeset
|
2159 |
% Segmenting |
1327
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
2160 |
% SDO Info Services |
1203
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
2161 |
% |
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
2162 |
|
1327
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
2163 |
\paragraph{SDO Download State Machine} |
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
2164 |
|
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
2165 |
The best time to apply SDO configurations is during the slave's PREOP state, |
1289
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
2166 |
because mailbox communication is already possible and slave's application will |
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
2167 |
start with updating input data in the succeeding SAFEOP state. Therefore the |
1327
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
2168 |
SDO configuration has to be part of the slave configuration state machine (see |
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
2169 |
sec.~\ref{sec:fsm-conf}): It is implemented via an SDO download state machine, |
1289
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
2170 |
that is executed just before entering the slave's SAFEOP state. In this way, |
1327
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
2171 |
it is guaranteed that the SDO configurations are applied each time, the slave |
1289
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
2172 |
is reconfigured. |
369 | 2173 |
|
1327
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
2174 |
The transition diagram of the SDO Download state machine can be seen |
369 | 2175 |
in figure~\ref{fig:fsm-coedown}. |
2176 |
||
2177 |
\begin{figure}[htbp] |
|
2178 |
\centering |
|
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2179 |
\includegraphics[width=.9\textwidth]{images/fsm-coedown} % FIXME |
369 | 2180 |
\caption{Transition diagram of the CoE download state machine} |
2181 |
\label{fig:fsm-coedown} |
|
2182 |
\end{figure} |
|
2183 |
||
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2184 |
% FIXME |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2185 |
|
369 | 2186 |
\begin{description} |
2187 |
\item[START] The beginning state of the CoE download state |
|
1327
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
2188 |
machine. The ``SDO Download Normal Request'' mailbox command is |
379 | 2189 |
sent. $\rightarrow$~REQUEST |
369 | 2190 |
|
2191 |
\item[REQUEST] It is checked, if the CoE download request has been |
|
2192 |
received by the slave. After that, a mailbox check command is issued |
|
379 | 2193 |
and a timer is started. $\rightarrow$~CHECK |
369 | 2194 |
|
2195 |
\item[CHECK] If no mailbox data is available, the timer is checked. |
|
2196 |
\begin{itemize} |
|
1327
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
2197 |
\item If it timed out, the SDO download is aborted. |
379 | 2198 |
$\rightarrow$~ERROR |
369 | 2199 |
\item Otherwise, the mailbox is queried again. |
379 | 2200 |
$\rightarrow$~CHECK |
369 | 2201 |
\end{itemize} |
2202 |
||
2203 |
If the mailbox contains new data, the response is fetched. |
|
379 | 2204 |
$\rightarrow$~RESPONSE |
369 | 2205 |
|
2206 |
\item[RESPONSE] If the mailbox response could not be fetched, the data |
|
1327
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
2207 |
is invalid, the wrong protocol was received, or a ``Abort SDO |
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
2208 |
Transfer Request'' was received, the SDO download is aborted. |
379 | 2209 |
$\rightarrow$~ERROR |
369 | 2210 |
|
1327
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
2211 |
If a ``SDO Download Normal Response'' acknowledgement was received, |
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
2212 |
the SDO download was successful. $\rightarrow$~END |
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
2213 |
|
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
2214 |
\item[END] The SDO download was successful. |
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
2215 |
|
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
2216 |
\item[ERROR] The SDO download was aborted due to an error. |
369 | 2217 |
|
2218 |
\end{description} |
|
2219 |
||
2220 |
%------------------------------------------------------------------------------ |
|
2221 |
||
1327
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
2222 |
\section{Vendor specific over EtherCAT (VoE)} |
1270
11f4b6e10d74
Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents:
1269
diff
changeset
|
2223 |
\label{sec:voe} |
11f4b6e10d74
Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents:
1269
diff
changeset
|
2224 |
\index{VoE} |
11f4b6e10d74
Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents:
1269
diff
changeset
|
2225 |
|
11f4b6e10d74
Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents:
1269
diff
changeset
|
2226 |
The VoE protocol opens the possibility to implement a vendor-specific mailbox |
11f4b6e10d74
Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents:
1269
diff
changeset
|
2227 |
communication protocol. VoE mailbox messages are prepended by a VoE header |
11f4b6e10d74
Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents:
1269
diff
changeset
|
2228 |
containing a 32-bit vendor ID and a 16-bit vendor-type. There are no more |
11f4b6e10d74
Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents:
1269
diff
changeset
|
2229 |
constraints regarding this protocol. |
11f4b6e10d74
Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents:
1269
diff
changeset
|
2230 |
|
11f4b6e10d74
Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents:
1269
diff
changeset
|
2231 |
The EtherCAT master allows to create multiple VoE handlers per slave |
1289
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
2232 |
configuration via the application interface (see chap.~\ref{chap:api}). These |
1270
11f4b6e10d74
Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents:
1269
diff
changeset
|
2233 |
handlers contain the state machine necessary for the communication via VoE. |
1298 | 2234 |
|
2235 |
For more information about using VoE handlers, see sec.~\ref{sec:api-voe} or |
|
2236 |
the example applications provided in the \textit{examples/} subdirectory. |
|
1270
11f4b6e10d74
Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents:
1269
diff
changeset
|
2237 |
|
11f4b6e10d74
Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents:
1269
diff
changeset
|
2238 |
%------------------------------------------------------------------------------ |
11f4b6e10d74
Version 1.5.0; VoE documentation.
Florian Pose <fp@igh-essen.com>
parents:
1269
diff
changeset
|
2239 |
|
1917 | 2240 |
\section{Servo Profile over EtherCAT (SoE)} |
2241 |
\label{sec:soe} |
|
2242 |
\index{SoE} |
|
2243 |
||
2244 |
The SoE protocol implements the Service Channel layer, specified in IEC |
|
2245 |
61800-7 \cite{soespec} via EtherCAT mailboxes. |
|
2246 |
||
2247 |
The SoE protocol is quite similar to the CoE protocol (see |
|
2248 |
sec.~\ref{sec:coe}). Instead of SDO indices and subindices, so-called |
|
2249 |
identification numbers (IDNs) identify parameters. |
|
2250 |
||
2251 |
The implementation covers the ``SCC Read'' and ``SCC Write'' primitives, each |
|
2252 |
with the ability to fragment data. |
|
2253 |
||
2254 |
There are several ways to use the SoE implementation: |
|
2255 |
||
2256 |
\begin{itemize} |
|
2257 |
||
2258 |
\item Reading and writing IDNs via the command-line tool (see |
|
2259 |
sec.~\ref{sec:soeaccess}). |
|
2260 |
||
2261 |
\item Storing configurations for arbitrary IDNs via the application interface |
|
2262 |
(see chap.~\ref{chap:api}, i.\,e.~\lstinline+ecrt_slave_config_idn()+). These |
|
2263 |
configurations are written to the slave during configuration in PREOP state, |
|
2264 |
before going to SAFEOP. |
|
2265 |
||
2266 |
\item The user-space library (see sec.~\ref{sec:userlib}), offers functions to |
|
2267 |
read/write IDNs in blocking mode (\lstinline+ecrt_master_read_idn()+, |
|
2268 |
\lstinline+ecrt_master_write_idn()+). |
|
2269 |
||
2270 |
\end{itemize} |
|
2271 |
||
2272 |
%------------------------------------------------------------------------------ |
|
2273 |
||
1275
c9de1c0c1f51
*space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents:
1270
diff
changeset
|
2274 |
\chapter{Userspace Interfaces} |
369 | 2275 |
\label{sec:user} |
1275
c9de1c0c1f51
*space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents:
1270
diff
changeset
|
2276 |
\index{Userspace} |
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2277 |
|
1203
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
2278 |
For the master runs as a kernel module, accessing it is natively limited to |
1275
c9de1c0c1f51
*space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents:
1270
diff
changeset
|
2279 |
analyzing Syslog messages and controlling using \textit{modutils}. |
c9de1c0c1f51
*space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents:
1270
diff
changeset
|
2280 |
|
c9de1c0c1f51
*space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents:
1270
diff
changeset
|
2281 |
It was necessary to implement further interfaces, that make it easier to access |
c9de1c0c1f51
*space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents:
1270
diff
changeset
|
2282 |
the master from userspace and allow a finer influence. It should be possible |
1203
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
2283 |
to view and to change special parameters at runtime. |
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
2284 |
|
1275
c9de1c0c1f51
*space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents:
1270
diff
changeset
|
2285 |
Bus visualization is another point: For development and debugging purposes it |
c9de1c0c1f51
*space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents:
1270
diff
changeset
|
2286 |
is necessary to show the connected slaves with a single command, for instance |
1289
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
2287 |
(see sec.~\ref{sec:tool}). |
1275
c9de1c0c1f51
*space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents:
1270
diff
changeset
|
2288 |
|
c9de1c0c1f51
*space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents:
1270
diff
changeset
|
2289 |
The application interface has to be available in userspace, to allow userspace |
c9de1c0c1f51
*space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents:
1270
diff
changeset
|
2290 |
programs to use EtherCAT master functionality. This was implemented via a |
1282 | 2291 |
character device and a userspace library (see sec.~\ref{sec:userlib}). |
1275
c9de1c0c1f51
*space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents:
1270
diff
changeset
|
2292 |
|
c9de1c0c1f51
*space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents:
1270
diff
changeset
|
2293 |
Another aspect is automatic startup and configuration. The master must be able |
c9de1c0c1f51
*space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents:
1270
diff
changeset
|
2294 |
to automatically start up with a persistent configuration (see |
c9de1c0c1f51
*space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents:
1270
diff
changeset
|
2295 |
sec.~\ref{sec:system}). |
1203
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
2296 |
|
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
2297 |
A last thing is monitoring EtherCAT communication. For debugging purposes, |
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
2298 |
there had to be a way to analyze EtherCAT datagrams. The best way would be |
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
2299 |
with a popular network analyzer, like Wireshark \cite{wireshark} (the former |
1275
c9de1c0c1f51
*space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents:
1270
diff
changeset
|
2300 |
Ethereal) or others (see sec.~\ref{sec:debug}). |
c9de1c0c1f51
*space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents:
1270
diff
changeset
|
2301 |
|
c9de1c0c1f51
*space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents:
1270
diff
changeset
|
2302 |
This chapter covers all these points and introduces the interfaces and tools |
1203
acb649738601
Some more documentation...
Florian Pose <fp@igh-essen.com>
parents:
1202
diff
changeset
|
2303 |
to make all that possible. |
369 | 2304 |
|
2305 |
%------------------------------------------------------------------------------ |
|
2306 |
||
1087
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2307 |
\section{Command-line Tool} |
1289
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
2308 |
\label{sec:tool} |
1087
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2309 |
|
1297 | 2310 |
% TODO --master |
1087
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2311 |
|
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2312 |
\subsection{Character Devices} |
1087
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2313 |
\label{sec:cdev} |
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2314 |
|
1214 | 2315 |
Each master instance will get a character device as a userspace interface. |
2316 |
The devices are named \textit{/dev/EtherCATx}, where $x \in \{0 \ldots n\}$ is |
|
2317 |
the index of the master. |
|
2318 |
||
2319 |
\paragraph{Device Node Creation} The character device nodes are automatically |
|
1289
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
2320 |
created, if the \lstinline+udev+ Package is installed. See |
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
2321 |
sec.~\ref{sec:autonode} for how to install and configure it. |
1087
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2322 |
|
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2323 |
%------------------------------------------------------------------------------ |
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2324 |
|
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2325 |
\subsection{Setting Alias Addresses} |
1293
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
2326 |
\label{sec:ethercat-alias} |
1140
cc779f7d2496
Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents:
1107
diff
changeset
|
2327 |
|
cc779f7d2496
Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents:
1107
diff
changeset
|
2328 |
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_alias} |
cc779f7d2496
Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents:
1107
diff
changeset
|
2329 |
|
cc779f7d2496
Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents:
1107
diff
changeset
|
2330 |
%------------------------------------------------------------------------------ |
cc779f7d2496
Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents:
1107
diff
changeset
|
2331 |
|
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2332 |
\subsection{Displaying the Bus Configuration} |
1293
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
2333 |
\label{sec:ethercat-config} |
1140
cc779f7d2496
Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents:
1107
diff
changeset
|
2334 |
|
cc779f7d2496
Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents:
1107
diff
changeset
|
2335 |
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_config} |
cc779f7d2496
Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents:
1107
diff
changeset
|
2336 |
|
cc779f7d2496
Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents:
1107
diff
changeset
|
2337 |
%------------------------------------------------------------------------------ |
cc779f7d2496
Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents:
1107
diff
changeset
|
2338 |
|
1514
85ac1c91045d
Added 'ethercat cstruct' command to output PDO information in C language.
Florian Pose <fp@igh-essen.com>
parents:
1485
diff
changeset
|
2339 |
\subsection{Output PDO information in C Language} |
85ac1c91045d
Added 'ethercat cstruct' command to output PDO information in C language.
Florian Pose <fp@igh-essen.com>
parents:
1485
diff
changeset
|
2340 |
\label{sec:ethercat-cstruct} |
85ac1c91045d
Added 'ethercat cstruct' command to output PDO information in C language.
Florian Pose <fp@igh-essen.com>
parents:
1485
diff
changeset
|
2341 |
|
85ac1c91045d
Added 'ethercat cstruct' command to output PDO information in C language.
Florian Pose <fp@igh-essen.com>
parents:
1485
diff
changeset
|
2342 |
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_cstruct} |
85ac1c91045d
Added 'ethercat cstruct' command to output PDO information in C language.
Florian Pose <fp@igh-essen.com>
parents:
1485
diff
changeset
|
2343 |
|
85ac1c91045d
Added 'ethercat cstruct' command to output PDO information in C language.
Florian Pose <fp@igh-essen.com>
parents:
1485
diff
changeset
|
2344 |
%------------------------------------------------------------------------------ |
85ac1c91045d
Added 'ethercat cstruct' command to output PDO information in C language.
Florian Pose <fp@igh-essen.com>
parents:
1485
diff
changeset
|
2345 |
|
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2346 |
\subsection{Displaying Process Data} |
1140
cc779f7d2496
Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents:
1107
diff
changeset
|
2347 |
|
cc779f7d2496
Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents:
1107
diff
changeset
|
2348 |
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_data} |
cc779f7d2496
Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents:
1107
diff
changeset
|
2349 |
|
cc779f7d2496
Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents:
1107
diff
changeset
|
2350 |
%------------------------------------------------------------------------------ |
cc779f7d2496
Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents:
1107
diff
changeset
|
2351 |
|
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2352 |
\subsection{Setting a Master's Debug Level} |
1399
f79d4bb5b23a
Added debug_level module parameter. debug_level is now unsigned int.
Florian Pose <fp@igh-essen.com>
parents:
1364
diff
changeset
|
2353 |
\label{sec:ethercat-debug} |
1140
cc779f7d2496
Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents:
1107
diff
changeset
|
2354 |
|
cc779f7d2496
Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents:
1107
diff
changeset
|
2355 |
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_debug} |
cc779f7d2496
Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents:
1107
diff
changeset
|
2356 |
|
cc779f7d2496
Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents:
1107
diff
changeset
|
2357 |
%------------------------------------------------------------------------------ |
cc779f7d2496
Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents:
1107
diff
changeset
|
2358 |
|
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2359 |
\subsection{Configured Domains} |
1140
cc779f7d2496
Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents:
1107
diff
changeset
|
2360 |
|
cc779f7d2496
Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents:
1107
diff
changeset
|
2361 |
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_domains} |
cc779f7d2496
Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents:
1107
diff
changeset
|
2362 |
|
cc779f7d2496
Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents:
1107
diff
changeset
|
2363 |
%------------------------------------------------------------------------------ |
cc779f7d2496
Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents:
1107
diff
changeset
|
2364 |
|
1423 | 2365 |
\subsection{SDO Access} |
2366 |
||
2367 |
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_download} |
|
2368 |
||
2369 |
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_upload} |
|
2370 |
||
2371 |
%------------------------------------------------------------------------------ |
|
2372 |
||
1485 | 2373 |
\subsection{EoE Statistics} |
2374 |
||
2375 |
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_eoe} |
|
2376 |
||
2377 |
%------------------------------------------------------------------------------ |
|
2378 |
||
1423 | 2379 |
\subsection{File-Access over EtherCAT} |
2380 |
||
2381 |
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_foe_read} |
|
2382 |
||
2383 |
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_foe_write} |
|
2384 |
||
2385 |
%------------------------------------------------------------------------------ |
|
2386 |
||
2387 |
\subsection{Creating Topology Graphs} |
|
2388 |
||
2389 |
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_graph} |
|
2390 |
||
2391 |
%------------------------------------------------------------------------------ |
|
2392 |
||
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2393 |
\subsection{Master and Ethernet Devices} |
1140
cc779f7d2496
Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents:
1107
diff
changeset
|
2394 |
|
cc779f7d2496
Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents:
1107
diff
changeset
|
2395 |
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_master} |
cc779f7d2496
Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents:
1107
diff
changeset
|
2396 |
|
cc779f7d2496
Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents:
1107
diff
changeset
|
2397 |
%------------------------------------------------------------------------------ |
cc779f7d2496
Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents:
1107
diff
changeset
|
2398 |
|
1327
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
2399 |
\subsection{Sync Managers, PDOs and PDO Entries} |
1140
cc779f7d2496
Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents:
1107
diff
changeset
|
2400 |
|
cc779f7d2496
Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents:
1107
diff
changeset
|
2401 |
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_pdos} |
cc779f7d2496
Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents:
1107
diff
changeset
|
2402 |
|
cc779f7d2496
Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents:
1107
diff
changeset
|
2403 |
%------------------------------------------------------------------------------ |
cc779f7d2496
Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents:
1107
diff
changeset
|
2404 |
|
1423 | 2405 |
\subsection{Register Access} |
1517
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
2406 |
\label{sec:regaccess} |
1423 | 2407 |
|
2408 |
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_reg_read} |
|
2409 |
||
2410 |
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_reg_write} |
|
2411 |
||
2412 |
%------------------------------------------------------------------------------ |
|
2413 |
||
1327
4d179b06dd3c
merge -c1604 branches/stable-1.4: Fixed spelling of EtherCAT terms.
Florian Pose <fp@igh-essen.com>
parents:
1309
diff
changeset
|
2414 |
\subsection{SDO Dictionary} |
1140
cc779f7d2496
Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents:
1107
diff
changeset
|
2415 |
|
cc779f7d2496
Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents:
1107
diff
changeset
|
2416 |
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_sdos} |
cc779f7d2496
Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents:
1107
diff
changeset
|
2417 |
|
cc779f7d2496
Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents:
1107
diff
changeset
|
2418 |
%------------------------------------------------------------------------------ |
cc779f7d2496
Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents:
1107
diff
changeset
|
2419 |
|
1423 | 2420 |
\subsection{SII Access} |
2421 |
\label{sec:siiaccess} |
|
2422 |
\index{SII!Access} |
|
2423 |
||
2424 |
It is possible to directly read or write the complete SII contents of the |
|
2425 |
slaves. This was introduced for the reasons below: |
|
2426 |
||
2427 |
\begin{itemize} |
|
2428 |
||
2429 |
\item The format of the SII data is still in development and categories can be |
|
2430 |
added in the future. With read and write access, the complete memory contents |
|
2431 |
can be easily backed up and restored. |
|
2432 |
||
2433 |
\item Some SII data fields have to be altered (like the alias address). A quick |
|
2434 |
writing must be possible for that. |
|
2435 |
||
2436 |
\item Through reading access, analyzing category data is possible from |
|
2437 |
userspace. |
|
2438 |
||
2439 |
\end{itemize} |
|
2440 |
||
2441 |
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_sii_read} |
|
2442 |
||
2443 |
Reading out SII data is as easy as other commands. Though the data are in |
|
2444 |
binary format, analysis is easier with a tool like \textit{hexdump}: |
|
2445 |
||
2446 |
\begin{lstlisting} |
|
2447 |
$ `\textbf{ethercat sii\_read --position 3 | hexdump}` |
|
2448 |
0000000 0103 0000 0000 0000 0000 0000 0000 008c |
|
2449 |
0000010 0002 0000 3052 07f0 0000 0000 0000 0000 |
|
2450 |
0000020 0000 0000 0000 0000 0000 0000 0000 0000 |
|
2451 |
... |
|
2452 |
\end{lstlisting} |
|
2453 |
||
2454 |
Backing up SII contents can easily done with a redirection: |
|
2455 |
||
2456 |
\begin{lstlisting} |
|
2457 |
$ `\textbf{ethercat sii\_read --position 3 > sii-of-slave3.bin}` |
|
2458 |
\end{lstlisting} |
|
2459 |
||
2460 |
To download SII contents to a slave, writing access to the master's character |
|
2461 |
device is necessary (see sec.~\ref{sec:cdev}). |
|
2462 |
||
2463 |
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_sii_write} |
|
2464 |
||
2465 |
\begin{lstlisting} |
|
2466 |
# `\textbf{ethercat sii\_write --position 3 sii-of-slave3.bin}` |
|
2467 |
\end{lstlisting} |
|
2468 |
||
2469 |
The SII contents will be checked for validity and then sent to the slave. The |
|
2470 |
write operation may take a few seconds. |
|
1140
cc779f7d2496
Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents:
1107
diff
changeset
|
2471 |
|
cc779f7d2496
Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents:
1107
diff
changeset
|
2472 |
%------------------------------------------------------------------------------ |
cc779f7d2496
Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents:
1107
diff
changeset
|
2473 |
|
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2474 |
\subsection{Slaves on the Bus} |
1087
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2475 |
|
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2476 |
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
|
2477 |
|
1140
cc779f7d2496
Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents:
1107
diff
changeset
|
2478 |
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_slaves} |
cc779f7d2496
Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents:
1107
diff
changeset
|
2479 |
|
cc779f7d2496
Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents:
1107
diff
changeset
|
2480 |
Below is a typical output: |
cc779f7d2496
Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents:
1107
diff
changeset
|
2481 |
|
1087
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2482 |
\begin{lstlisting} |
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2483 |
$ `\textbf{ethercat slaves}` |
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2484 |
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
|
2485 |
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
|
2486 |
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
|
2487 |
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
|
2488 |
\end{lstlisting} |
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2489 |
|
369 | 2490 |
%------------------------------------------------------------------------------ |
2491 |
||
1917 | 2492 |
\subsection{SoE IDN Access} |
2493 |
\label{sec:soeaccess} |
|
2494 |
||
2495 |
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_soe_read} |
|
2496 |
||
2497 |
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_soe_write} |
|
2498 |
||
2499 |
%------------------------------------------------------------------------------ |
|
2500 |
||
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2501 |
\subsection{Requesting Application-Layer States} |
1140
cc779f7d2496
Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents:
1107
diff
changeset
|
2502 |
|
cc779f7d2496
Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents:
1107
diff
changeset
|
2503 |
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_states} |
cc779f7d2496
Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents:
1107
diff
changeset
|
2504 |
|
cc779f7d2496
Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents:
1107
diff
changeset
|
2505 |
%------------------------------------------------------------------------------ |
cc779f7d2496
Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents:
1107
diff
changeset
|
2506 |
|
1423 | 2507 |
\subsection{Displaying the Master Version} |
2508 |
||
2509 |
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_version} |
|
2510 |
||
2511 |
%------------------------------------------------------------------------------ |
|
2512 |
||
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2513 |
\subsection{Generating Slave Description XML} |
1140
cc779f7d2496
Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents:
1107
diff
changeset
|
2514 |
|
cc779f7d2496
Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents:
1107
diff
changeset
|
2515 |
\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_xml} |
cc779f7d2496
Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents:
1107
diff
changeset
|
2516 |
|
cc779f7d2496
Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents:
1107
diff
changeset
|
2517 |
%------------------------------------------------------------------------------ |
cc779f7d2496
Command-line help in the docs.
Florian Pose <fp@igh-essen.com>
parents:
1107
diff
changeset
|
2518 |
|
1275
c9de1c0c1f51
*space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents:
1270
diff
changeset
|
2519 |
\section{Userspace Library} |
c9de1c0c1f51
*space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents:
1270
diff
changeset
|
2520 |
\label{sec:userlib} |
c9de1c0c1f51
*space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents:
1270
diff
changeset
|
2521 |
|
1289
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
2522 |
The native application interface (see chap.~\ref{chap:api}) resides in |
1282 | 2523 |
kernelspace and hence is only accessible from inside the kernel. To make the |
2524 |
application interface available from userspace programs, a userspace library |
|
2525 |
has been created, that can be linked to programs under the terms and |
|
2526 |
conditions of the LGPL, version 2 \cite{lgpl}. |
|
2527 |
||
2528 |
The library is named \textit{libethercat}. Its sources reside in the |
|
2529 |
\textit{lib/} subdirectory and are build by default when using |
|
2530 |
\lstinline+make+. It is installed in the \textit{lib/} path below the |
|
2531 |
installation prefix as \textit{libethercat.a} (for static linking), |
|
2532 |
\textit{libethercat.la} (for the use with \textit{libtool}) and |
|
2533 |
\textit{libethercat.so} (for dynamic linking). |
|
2534 |
||
1299 | 2535 |
\subsection{Using the Library} |
1282 | 2536 |
|
2537 |
The application interface header \textit{ecrt.h} can be used both in kernel |
|
2538 |
and in user context. |
|
2539 |
||
2540 |
The following minimal example shows how to build a program with EtherCAT |
|
2541 |
functionality. An entire example can be found in the \textit{examples/user/} |
|
2542 |
path of the master sources. |
|
2543 |
||
2544 |
\begin{lstlisting}[language=C] |
|
2545 |
#include <ecrt.h> |
|
2546 |
||
2547 |
int main(void) |
|
2548 |
{ |
|
2549 |
ec_master_t *master = ecrt_request_master(0); |
|
2550 |
||
2551 |
if (!master) |
|
2552 |
return 1; // error |
|
2553 |
||
2554 |
pause(); // wait for signal |
|
2555 |
return 0; |
|
2556 |
} |
|
2557 |
\end{lstlisting} |
|
2558 |
||
2559 |
The program can be compiled and dynamically linked to the library with the |
|
2560 |
below command: |
|
2561 |
||
2562 |
\begin{lstlisting} |
|
2563 |
gcc ethercat.c -o ectest -I/opt/etherlab/include \ |
|
2564 |
-L/opt/etherlab/lib -lethercat \ |
|
2565 |
-Wl,--rpath -Wl,/opt/etherlab/lib |
|
2566 |
\end{lstlisting} |
|
2567 |
||
2568 |
The library can also be linked statically to the program: |
|
2569 |
||
2570 |
\begin{lstlisting} |
|
2571 |
gcc -static ectest.c -o ectest -I/opt/etherlab/include \ |
|
2572 |
/opt/etherlab/lib/libethercat.a |
|
2573 |
\end{lstlisting} |
|
2574 |
||
2575 |
\subsection{Implementation} |
|
2576 |
\label{sec:userimp} |
|
2577 |
||
2578 |
Basically the kernel API was transferred into userspace via the master |
|
1299 | 2579 |
character device (see chap.~\ref{chap:arch}, fig.~\ref{fig:arch} and |
2580 |
sec.~\ref{sec:cdev}). |
|
1282 | 2581 |
|
2582 |
The function calls of the kernel API are mapped to the userspace via an |
|
1517
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
2583 |
\lstinline+ioctl()+ interface. The userspace API functions share a set of |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
2584 |
generic \lstinline+ioctl()+ calls. The kernel part of the interface calls the |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
2585 |
according API functions directly, what results in a minimum additional delay |
b99f2f9cb73f
DC documentation; new callback mechanism; cstruct
Florian Pose <fp@igh-essen.com>
parents:
1514
diff
changeset
|
2586 |
(see sec.~\ref{sec:usertiming}). |
1282 | 2587 |
|
1299 | 2588 |
For performance reasons, the actual domain process data (see |
2589 |
sec.~\ref{sec:processdata}) are not copied between kernel and user memory on |
|
2590 |
every access: Instead, the data are memory-mapped to the userspace |
|
2591 |
application. Once the master is configured and activated, the master module |
|
2592 |
creates one process data memory area spanning all domains and maps it to |
|
2593 |
userspace, so that the application can directly access the process data. As a |
|
2594 |
result, there is no additional delay when accessing process data from |
|
2595 |
userspace. |
|
2596 |
||
2597 |
\paragraph{Kernel/User API Differences} Because of the memory-mapping of the |
|
2598 |
process data, the memory is managed internally by the library functions. As a |
|
2599 |
result, it is not possible to provide external memory for domains, like in the |
|
2600 |
kernel API. The corresponding functions are only available in kernelspace. |
|
2601 |
This is the only difference when using the application interface in userspace. |
|
1275
c9de1c0c1f51
*space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents:
1270
diff
changeset
|
2602 |
|
1281 | 2603 |
\subsection{Timing} |
2604 |
\label{sec:usertiming} |
|
2605 |
||
2606 |
An interesting aspect is the timing of the userspace library calls compared to |
|
2607 |
those of the kernel API. Table~\ref{tab:usertiming} shows the call times and |
|
2608 |
standard deviancies of typical (and time-critical) API functions measured on |
|
2609 |
an Intel Pentium 4 M CPU with \unit{2.2}{\giga\hertz} and a standard 2.6.26 |
|
2610 |
kernel. |
|
2611 |
||
2612 |
\begin{table}[htbp] |
|
2613 |
\centering |
|
2614 |
\caption{Application Interface Timing Comparison} |
|
2615 |
\label{tab:usertiming} |
|
2616 |
\vspace{2mm} |
|
2617 |
\begin{tabular}{l|c|c|c|c} |
|
2618 |
||
2619 |
& |
|
2620 |
\multicolumn{2}{|c}{\textbf{Kernelspace}} & |
|
2621 |
\multicolumn{2}{|c}{\textbf{Userspace}} \\ |
|
2622 |
||
2623 |
\textbf{Function} & |
|
2624 |
$\mu(t)$ & |
|
2625 |
$\sigma(t)$ & |
|
2626 |
$\mu(t)$ & |
|
2627 |
$\sigma(t)$ \\ |
|
2628 |
\hline |
|
2629 |
||
2630 |
\lstinline+ecrt_master_receive()+ & |
|
2631 |
\unit{1.1}{\micro\second} & |
|
2632 |
\unit{0.3}{\micro\second} & |
|
2633 |
\unit{2.2}{\micro\second} & |
|
2634 |
\unit{0.5}{\micro\second} \\ |
|
2635 |
||
2636 |
\lstinline+ecrt_domain_process()+ & |
|
2637 |
\unit{<0.1}{\micro\second} & |
|
2638 |
\unit{<0.1}{\micro\second} & |
|
2639 |
\unit{1.0}{\micro\second} & |
|
2640 |
\unit{0.2}{\micro\second} \\ |
|
2641 |
||
2642 |
\lstinline+ecrt_domain_queue()+ & |
|
2643 |
\unit{<0.1}{\micro\second} & |
|
2644 |
\unit{<0.1}{\micro\second} & |
|
2645 |
\unit{1.0}{\micro\second} & |
|
2646 |
\unit{0.1}{\micro\second} \\ |
|
2647 |
||
2648 |
\lstinline+ecrt_master_send()+ & |
|
2649 |
\unit{1.8}{\micro\second} & |
|
2650 |
\unit{0.2}{\micro\second} & |
|
2651 |
\unit{2.5}{\micro\second} & |
|
2652 |
\unit{0.5}{\micro\second} \\ |
|
2653 |
||
2654 |
\end{tabular} |
|
2655 |
\end{table} |
|
2656 |
||
1282 | 2657 |
The test results show, that for this configuration, the userspace API causes |
2658 |
about \unit{1}{\micro\second} additional delay for each function, compared to |
|
2659 |
the kernel API. |
|
1281 | 2660 |
|
1275
c9de1c0c1f51
*space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents:
1270
diff
changeset
|
2661 |
%------------------------------------------------------------------------------ |
c9de1c0c1f51
*space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents:
1270
diff
changeset
|
2662 |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2663 |
\section{System Integration} |
369 | 2664 |
\label{sec:system} |
2665 |
||
1086
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
2666 |
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
|
2667 |
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
|
2668 |
|
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
2669 |
\subsection{Init Script} |
369 | 2670 |
\label{sec:init} |
2671 |
\index{Init script} |
|
2672 |
||
1086
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
2673 |
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
|
2674 |
Standard Base'' (LSB\index{LSB}, \cite{lsb}). The script is installed to |
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2675 |
\textit{etc/init.d/ethercat} below the installation prefix and has to be |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2676 |
copied (or better: linked) to the appropriate location (see |
1289
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
2677 |
sec.~\ref{sec:installation}), before the master can be inserted as a service. |
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
2678 |
Please note, that the init script depends on the sysconfig file described |
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
2679 |
below. |
1086
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
2680 |
|
1306
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
2681 |
To provide service dependencies (i.\,e.\ which services have to be started |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
2682 |
before others) inside the init script code, LSB defines a special comment |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
2683 |
block. System tools can extract this information to insert the EtherCAT init |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
2684 |
script at the correct place in the startup sequence: |
1086
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
2685 |
|
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
2686 |
\lstinputlisting[firstline=38,lastline=48] |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
2687 |
{../script/init.d/ethercat} |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
2688 |
|
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2689 |
\subsection{Sysconfig File} |
1086
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
2690 |
\label{sec:sysconfig} |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
2691 |
\index{Sysconfig file} |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
2692 |
|
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
2693 |
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
|
2694 |
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
|
2695 |
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
|
2696 |
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
|
2697 |
the file and included below: |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
2698 |
|
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
2699 |
\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
|
2700 |
{../script/sysconfig/ethercat} |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
2701 |
|
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2702 |
\subsection{Starting the Master as a Service} |
1086
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
2703 |
\label{sec:service} |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
2704 |
\index{Service} |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
2705 |
|
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
2706 |
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
|
2707 |
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
|
2708 |
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
|
2709 |
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
|
2710 |
command: |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
2711 |
|
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
2712 |
\begin{lstlisting} |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
2713 |
# `\textbf{insserv ethercat}` |
369 | 2714 |
\end{lstlisting} |
2715 |
||
2716 |
The init script can also be used for manually starting and stopping |
|
2717 |
the EtherCAT master. It has to be executed with one of the parameters |
|
379 | 2718 |
\texttt{start}, \texttt{stop}, \texttt{restart} or \texttt{status}. |
369 | 2719 |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2720 |
\begin{lstlisting}[gobble=2] |
379 | 2721 |
# `\textbf{/etc/init.d/ethercat restart}` |
369 | 2722 |
Shutting down EtherCAT master done |
2723 |
Starting EtherCAT master done |
|
2724 |
\end{lstlisting} |
|
2725 |
||
2726 |
%------------------------------------------------------------------------------ |
|
2727 |
||
1307
45a82ad140f8
New debug interfaces docs.
Florian Pose <fp@igh-essen.com>
parents:
1306
diff
changeset
|
2728 |
\section{Debug Interfaces} |
369 | 2729 |
\label{sec:debug} |
1307
45a82ad140f8
New debug interfaces docs.
Florian Pose <fp@igh-essen.com>
parents:
1306
diff
changeset
|
2730 |
\index{Debug Interfaces} |
369 | 2731 |
|
1306
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
2732 |
EtherCAT buses can always be monitored by inserting a switch between master |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
2733 |
and slaves. This allows to connect another PC with a network monitor like |
1588
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
2734 |
Wireshark~\cite{wireshark}, for example. It is also possible to listen to |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
2735 |
local network interfaces on the machine running the EtherCAT master directly. |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
2736 |
If the generic Ethernet driver (see sec.~\ref{sec:generic-driver}) is used, |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
2737 |
the network monitor can directly listen on the network interface connected to |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
2738 |
the EtherCAT bus. |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
2739 |
|
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
2740 |
When using native Ethernet drivers (see sec.~\ref{sec:native-drivers}), there |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
2741 |
are no local network interfaces to listen to, because the Ethernet devices |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
2742 |
used for EtherCAT are not registered at the network stack. For that case, |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
2743 |
so-called ``debug interfaces'' are supported, which are virtual network |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
2744 |
interfaces allowing to capture EtherCAT traffic with a network monitor (like |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
2745 |
Wireshark or tcpdump) running on the master machine without using external |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
2746 |
hardware. To use this functionality, the master sources have to be configured |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
2747 |
with the \lstinline+--enable-debug-if+ switch (see |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
2748 |
sec.~\ref{sec:installation}). |
1307
45a82ad140f8
New debug interfaces docs.
Florian Pose <fp@igh-essen.com>
parents:
1306
diff
changeset
|
2749 |
|
45a82ad140f8
New debug interfaces docs.
Florian Pose <fp@igh-essen.com>
parents:
1306
diff
changeset
|
2750 |
Every EtherCAT master registers a read-only network interface per attached |
1308
c8b82c27b6df
Improved new debug interfaces again.
Florian Pose <fp@igh-essen.com>
parents:
1307
diff
changeset
|
2751 |
physical Ethernet device. The network interfaces are named \textit{ecdbgmX} |
c8b82c27b6df
Improved new debug interfaces again.
Florian Pose <fp@igh-essen.com>
parents:
1307
diff
changeset
|
2752 |
for the main device, and \textit{ecdbgbX} for the backup device (for future |
c8b82c27b6df
Improved new debug interfaces again.
Florian Pose <fp@igh-essen.com>
parents:
1307
diff
changeset
|
2753 |
use), where X is the master index. The below listing shows a debug interface |
c8b82c27b6df
Improved new debug interfaces again.
Florian Pose <fp@igh-essen.com>
parents:
1307
diff
changeset
|
2754 |
among some standard network interfaces: |
1306
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
2755 |
|
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
2756 |
\begin{lstlisting} |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
2757 |
# `\textbf{ip link}` |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
2758 |
1: lo: <LOOPBACK,UP> mtu 16436 qdisc noqueue |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
2759 |
link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00 |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
2760 |
4: eth0: <BROADCAST,MULTICAST> mtu 1500 qdisc noop qlen 1000 |
1307
45a82ad140f8
New debug interfaces docs.
Florian Pose <fp@igh-essen.com>
parents:
1306
diff
changeset
|
2761 |
link/ether 00:13:46:3b:ad:d7 brd ff:ff:ff:ff:ff:ff |
1308
c8b82c27b6df
Improved new debug interfaces again.
Florian Pose <fp@igh-essen.com>
parents:
1307
diff
changeset
|
2762 |
8: ecdbgm0: <BROADCAST,MULTICAST> mtu 1500 qdisc pfifo_fast |
c8b82c27b6df
Improved new debug interfaces again.
Florian Pose <fp@igh-essen.com>
parents:
1307
diff
changeset
|
2763 |
qlen 1000 |
1306
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
2764 |
link/ether 00:04:61:03:d1:01 brd ff:ff:ff:ff:ff:ff |
1307
45a82ad140f8
New debug interfaces docs.
Florian Pose <fp@igh-essen.com>
parents:
1306
diff
changeset
|
2765 |
\end{lstlisting} |
45a82ad140f8
New debug interfaces docs.
Florian Pose <fp@igh-essen.com>
parents:
1306
diff
changeset
|
2766 |
|
45a82ad140f8
New debug interfaces docs.
Florian Pose <fp@igh-essen.com>
parents:
1306
diff
changeset
|
2767 |
While a debug interface is enabled, all frames sent or received to or from the |
45a82ad140f8
New debug interfaces docs.
Florian Pose <fp@igh-essen.com>
parents:
1306
diff
changeset
|
2768 |
physical device are additionally forwarded to the debug interface by the |
1308
c8b82c27b6df
Improved new debug interfaces again.
Florian Pose <fp@igh-essen.com>
parents:
1307
diff
changeset
|
2769 |
corresponding master. Network interfaces can be enabled with the below |
c8b82c27b6df
Improved new debug interfaces again.
Florian Pose <fp@igh-essen.com>
parents:
1307
diff
changeset
|
2770 |
command: |
1306
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
2771 |
|
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
2772 |
\begin{lstlisting} |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
2773 |
# `\textbf{ip link set dev ecdbgm0 up}` |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
2774 |
\end{lstlisting} |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
2775 |
|
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
2776 |
Please note, that the frame rate can be very high. With an application |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
2777 |
connected, the debug interface can produce thousands of frames per second. |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
2778 |
|
1309 | 2779 |
\paragraph{Attention} The socket buffers needed for the operation of debug |
1588
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
2780 |
interfaces have to be allocated dynamically. Some Linux realtime extensions |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
2781 |
(like RTAI) do not allow this in realtime context! |
369 | 2782 |
|
2783 |
%------------------------------------------------------------------------------ |
|
2784 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2785 |
\chapter{Timing Aspects} |
369 | 2786 |
\label{sec:timing} |
2787 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2788 |
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
|
2789 |
are rare, there are a few aspects that can (and should be) dealt with. |
369 | 2790 |
|
2791 |
%------------------------------------------------------------------------------ |
|
2792 |
||
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2793 |
\subsection{Application Interface Profiling} |
369 | 2794 |
\label{sec:timing-profile} |
1204
4e3e8400c338
Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents:
1203
diff
changeset
|
2795 |
\index{Profiling} |
4e3e8400c338
Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents:
1203
diff
changeset
|
2796 |
% FIXME |
369 | 2797 |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2798 |
One of the most important timing aspects are the execution times of the |
1204
4e3e8400c338
Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents:
1203
diff
changeset
|
2799 |
application interface functions, that are called in cyclic context. These |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2800 |
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
|
2801 |
To measure the timing of the functions, the following code was used: |
369 | 2802 |
|
2803 |
\begin{lstlisting}[gobble=2,language=C] |
|
2804 |
c0 = get_cycles(); |
|
2805 |
ecrt_master_receive(master); |
|
2806 |
c1 = get_cycles(); |
|
2807 |
ecrt_domain_process(domain1); |
|
2808 |
c2 = get_cycles(); |
|
2809 |
ecrt_master_run(master); |
|
2810 |
c3 = get_cycles(); |
|
2811 |
ecrt_master_send(master); |
|
2812 |
c4 = get_cycles(); |
|
2813 |
\end{lstlisting} |
|
2814 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2815 |
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
|
2816 |
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
|
2817 |
\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
|
2818 |
\milli\second. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2819 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2820 |
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
|
2821 |
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
|
2822 |
\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
|
2823 |
results were averaged. These can be seen in table~\ref{tab:profile}. |
369 | 2824 |
|
2825 |
\begin{table}[htpb] |
|
2826 |
\centering |
|
1204
4e3e8400c338
Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents:
1203
diff
changeset
|
2827 |
\caption{Profiling of an Application Cycle on a \unit{2.0}{\giga\hertz} |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2828 |
Processor} |
369 | 2829 |
\label{tab:profile} |
2830 |
\vspace{2mm} |
|
2831 |
\begin{tabular}{l|r|r} |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2832 |
Element & Mean Duration [\second] & Standard Deviancy [\micro\second] \\ |
369 | 2833 |
\hline |
2834 |
\textit{ecrt\_master\_receive()} & 8.04 & 0.48\\ |
|
2835 |
\textit{ecrt\_domain\_process()} & 0.14 & 0.03\\ |
|
2836 |
\textit{ecrt\_master\_run()} & 0.29 & 0.12\\ |
|
2837 |
\textit{ecrt\_master\_send()} & 2.18 & 0.17\\ \hline |
|
2838 |
Complete Cycle & 10.65 & 0.69\\ \hline |
|
2839 |
\end{tabular} |
|
2840 |
\end{table} |
|
2841 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2842 |
It is obvious, that the functions accessing hardware make up the |
369 | 2843 |
lion's share. The \textit{ec\_master\_receive()} executes the ISR of |
2844 |
the Ethernet device, analyzes datagrams and copies their contents into |
|
2845 |
the memory of the datagram objects. The \textit{ec\_master\_send()} |
|
2846 |
assembles a frame out of different datagrams and copies it to the |
|
2847 |
hardware buffers. Interestingly, this makes up only a quarter of the |
|
2848 |
receiving time. |
|
2849 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2850 |
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
|
2851 |
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
|
2852 |
\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
|
2853 |
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
|
2854 |
\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
|
2855 |
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
|
2856 |
functions are more or less complex. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2857 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2858 |
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
|
2859 |
frequency can be up to \unit{100}{\kilo\hertz}. For two reasons, this frequency |
369 | 2860 |
keeps being theoretical: |
2861 |
||
2862 |
\begin{enumerate} |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2863 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2864 |
\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
|
2865 |
realtime cycles. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2866 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2867 |
\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
|
2868 |
cycle begins. The determination of the bus cycle time is difficult and covered |
1289
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
2869 |
in sec.~\ref{sec:timing-bus}. |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2870 |
|
369 | 2871 |
\end{enumerate} |
2872 |
||
2873 |
%------------------------------------------------------------------------------ |
|
2874 |
||
2875 |
\subsection{Bus Cycle Measuring} |
|
2876 |
\label{sec:timing-bus} |
|
2877 |
\index{Bus cycle} |
|
2878 |
||
1297 | 2879 |
For measuring the time, a frame is ``on the wire'', two timestamps must be |
2880 |
taken: |
|
369 | 2881 |
|
2882 |
\begin{enumerate} |
|
1297 | 2883 |
|
2884 |
\item The time, the Ethernet hardware begins with physically sending the |
|
2885 |
frame. |
|
2886 |
||
2887 |
\item The time, the frame is completely received by the Ethernet hardware. |
|
2888 |
||
369 | 2889 |
\end{enumerate} |
2890 |
||
2891 |
Both times are difficult to determine. The first reason is, that the |
|
1297 | 2892 |
interrupts are disabled and the master is not notified, when a frame is sent |
2893 |
or received (polling would distort the results). The second reason is, that |
|
2894 |
even with interrupts enabled, the time from the event to the notification is |
|
2895 |
unknown. Therefore the only way to confidently determine the bus cycle time is |
|
2896 |
an electrical measuring. |
|
369 | 2897 |
|
1204
4e3e8400c338
Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents:
1203
diff
changeset
|
2898 |
Anyway, the bus cycle time is an important factor when designing realtime |
4e3e8400c338
Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents:
1203
diff
changeset
|
2899 |
code, because it limits the maximum frequency for the cyclic task of the |
4e3e8400c338
Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents:
1203
diff
changeset
|
2900 |
application. In practice, these timing parameters are highly dependent on the |
4e3e8400c338
Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents:
1203
diff
changeset
|
2901 |
hardware and often a trial and error method must be used to determine the |
4e3e8400c338
Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents:
1203
diff
changeset
|
2902 |
limits of the system. |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2903 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2904 |
The central question is: What happens, if the cycle frequency is too high? The |
1297 | 2905 |
answer is, that the EtherCAT frames that have been sent at the end of the |
2906 |
cycle are not yet received, when the next cycle starts. First this is noticed |
|
2907 |
by \textit{ecrt\_domain\_process()}, because the working counter of the |
|
2908 |
process data datagrams were not increased. The function will notify the user |
|
2909 |
via Syslog\footnote{To limit Syslog output, a mechanism has been implemented, |
|
2910 |
that outputs a summarized notification at maximum once a second.}. In this |
|
2911 |
case, the process data keeps being the same as in the last cycle, because it |
|
2912 |
is not erased by the domain. When the domain datagrams are queued again, the |
|
2913 |
master notices, that they are already queued (and marked as sent). The master |
|
2914 |
will mark them as unsent again and output a warning, that datagrams were |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2915 |
``skipped''. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2916 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2917 |
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
|
2918 |
can be up to \unit{25}{\kilo\hertz} without skipped frames. This value can |
1297 | 2919 |
surely be increased by choosing faster hardware. Especially the RealTek |
2920 |
network hardware could be replaced by a faster one. Besides, implementing a |
|
2921 |
dedicated ISR for EtherCAT devices would also contribute to increasing the |
|
2922 |
latency. These are two points on the author's to-do list. |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2923 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2924 |
%------------------------------------------------------------------------------ |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2925 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2926 |
\chapter{Installation} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2927 |
\label{sec:installation} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2928 |
\index{Master!Installation} |
369 | 2929 |
|
1772
b4c85bedd68f
Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents:
1592
diff
changeset
|
2930 |
\section{Getting the Software} |
b4c85bedd68f
Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents:
1592
diff
changeset
|
2931 |
\label{sec:getting} |
b4c85bedd68f
Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents:
1592
diff
changeset
|
2932 |
|
b4c85bedd68f
Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents:
1592
diff
changeset
|
2933 |
There are several ways to get the master software: |
b4c85bedd68f
Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents:
1592
diff
changeset
|
2934 |
|
b4c85bedd68f
Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents:
1592
diff
changeset
|
2935 |
\begin{enumerate} |
b4c85bedd68f
Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents:
1592
diff
changeset
|
2936 |
|
b4c85bedd68f
Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents:
1592
diff
changeset
|
2937 |
\item An official release (for example \masterversion), can be downloaded from |
b4c85bedd68f
Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents:
1592
diff
changeset
|
2938 |
the master's website\footnote{\url{http://etherlab.org/en/ethercat/index.php}} |
b4c85bedd68f
Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents:
1592
diff
changeset
|
2939 |
at~the EtherLab project~\cite{etherlab} as a tarball. |
b4c85bedd68f
Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents:
1592
diff
changeset
|
2940 |
|
b4c85bedd68f
Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents:
1592
diff
changeset
|
2941 |
\item The most recent development revision (and moreover any other revision) |
b4c85bedd68f
Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents:
1592
diff
changeset
|
2942 |
can be obtained via the Mercurial~\cite{mercurial} repository on the master's |
b4c85bedd68f
Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents:
1592
diff
changeset
|
2943 |
project page on |
b4c85bedd68f
Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents:
1592
diff
changeset
|
2944 |
SourceForge.net\footnote{\url{http://sourceforge.net/projects/etherlabmaster}}. |
b4c85bedd68f
Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents:
1592
diff
changeset
|
2945 |
The whole repository can be cloned with the command |
b4c85bedd68f
Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents:
1592
diff
changeset
|
2946 |
|
b4c85bedd68f
Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents:
1592
diff
changeset
|
2947 |
\begin{lstlisting}[breaklines=true] |
b4c85bedd68f
Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents:
1592
diff
changeset
|
2948 |
hg clone http://etherlabmaster.hg.sourceforge.net/hgweb/etherlabmaster/etherlabmaster `\textit{local-dir}` |
b4c85bedd68f
Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents:
1592
diff
changeset
|
2949 |
\end{lstlisting} |
b4c85bedd68f
Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents:
1592
diff
changeset
|
2950 |
|
b4c85bedd68f
Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents:
1592
diff
changeset
|
2951 |
\item Without a local Mercurial installation, tarballs of arbitrary revisions |
b4c85bedd68f
Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents:
1592
diff
changeset
|
2952 |
can be downloaded via the ``bz2'' links in the browsable repository |
b4c85bedd68f
Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents:
1592
diff
changeset
|
2953 |
pages\footnote{\url{http://etherlabmaster.hg.sourceforge.net/hgweb/etherlabmaster/etherlabmaster}}. |
b4c85bedd68f
Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents:
1592
diff
changeset
|
2954 |
|
b4c85bedd68f
Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents:
1592
diff
changeset
|
2955 |
\end{enumerate} |
b4c85bedd68f
Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents:
1592
diff
changeset
|
2956 |
|
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2957 |
\section{Building the Software} |
1094
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
2958 |
|
1772
b4c85bedd68f
Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents:
1592
diff
changeset
|
2959 |
After downloading a tarball or cloning the repository as described in |
b4c85bedd68f
Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents:
1592
diff
changeset
|
2960 |
sec.~\ref{sec:getting}, the sources have to be prepared and configured for the |
b4c85bedd68f
Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents:
1592
diff
changeset
|
2961 |
build process. |
b4c85bedd68f
Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents:
1592
diff
changeset
|
2962 |
|
b4c85bedd68f
Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents:
1592
diff
changeset
|
2963 |
When a tarball was downloaded, it has to be extracted with the following |
b4c85bedd68f
Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents:
1592
diff
changeset
|
2964 |
commands: |
369 | 2965 |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2966 |
\begin{lstlisting}[gobble=2] |
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2967 |
$ `\textbf{tar xjf ethercat-\masterversion.tar.bz2}` |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2968 |
$ `\textbf{cd ethercat-\masterversion/}` |
374
e43a29f9079e
Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents:
371
diff
changeset
|
2969 |
\end{lstlisting} |
e43a29f9079e
Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents:
371
diff
changeset
|
2970 |
|
1772
b4c85bedd68f
Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents:
1592
diff
changeset
|
2971 |
The software configuration is managed with Autoconf~\cite{autoconf} so the |
b4c85bedd68f
Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents:
1592
diff
changeset
|
2972 |
released versions contain a \lstinline+configure+ shell script, that has to be |
b4c85bedd68f
Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents:
1592
diff
changeset
|
2973 |
executed for configuration (see below). |
b4c85bedd68f
Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents:
1592
diff
changeset
|
2974 |
|
b4c85bedd68f
Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents:
1592
diff
changeset
|
2975 |
\paragraph{Bootstrap} When downloading or cloning directly from the |
b4c85bedd68f
Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents:
1592
diff
changeset
|
2976 |
repository, the \lstinline+configure+ script does not yet exist. It can be |
b4c85bedd68f
Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents:
1592
diff
changeset
|
2977 |
created via the \lstinline+bootstrap.sh+ script in the master sources. The |
b4c85bedd68f
Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents:
1592
diff
changeset
|
2978 |
autoconf and automake packages are required for this. |
b4c85bedd68f
Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents:
1592
diff
changeset
|
2979 |
|
b4c85bedd68f
Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents:
1592
diff
changeset
|
2980 |
\paragraph{Configuration and Build} The configuration and the build process |
b4c85bedd68f
Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents:
1592
diff
changeset
|
2981 |
follow the below commands: |
369 | 2982 |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2983 |
\begin{lstlisting}[gobble=2] |
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2984 |
$ `\textbf{./configure}` |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2985 |
$ `\textbf{make}` |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
2986 |
$ `\textbf{make modules}` |
374
e43a29f9079e
Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents:
371
diff
changeset
|
2987 |
\end{lstlisting} |
e43a29f9079e
Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents:
371
diff
changeset
|
2988 |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2989 |
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
|
2990 |
|
2297
0566476835d7
Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents:
2133
diff
changeset
|
2991 |
\begin{longtable}{l|p{.4\textwidth}|l} |
0566476835d7
Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents:
2133
diff
changeset
|
2992 |
\caption{Configuration options}\rule[-5ex]{0mm}{0mm} |
0566476835d7
Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents:
2133
diff
changeset
|
2993 |
\label{tab:config}\\ |
0566476835d7
Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents:
2133
diff
changeset
|
2994 |
|
0566476835d7
Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents:
2133
diff
changeset
|
2995 |
\textbf{Option/Switch} & \textbf{Description} & \textbf{Default}\\\hline |
0566476835d7
Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents:
2133
diff
changeset
|
2996 |
\endfirsthead |
0566476835d7
Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents:
2133
diff
changeset
|
2997 |
|
0566476835d7
Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents:
2133
diff
changeset
|
2998 |
\textbf{Option/Switch} & \textbf{Description} & \textbf{Default}\\\hline |
0566476835d7
Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents:
2133
diff
changeset
|
2999 |
\endhead |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3000 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3001 |
\lstinline+--prefix+ & Installation prefix & \textit{/opt/etherlab}\\ |
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 |
\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
|
3004 |
|
2297
0566476835d7
Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents:
2133
diff
changeset
|
3005 |
\lstinline+--with-module-dir+ & Subdirectory in the kernel module tree, where |
0566476835d7
Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents:
2133
diff
changeset
|
3006 |
the EtherCAT kernel modules shall be installed. & \textit{ethercat}\\ |
0566476835d7
Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents:
2133
diff
changeset
|
3007 |
|
0566476835d7
Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents:
2133
diff
changeset
|
3008 |
\hline |
0566476835d7
Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents:
2133
diff
changeset
|
3009 |
|
0566476835d7
Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents:
2133
diff
changeset
|
3010 |
\lstinline+--enable-generic+ & Build the generic Ethernet driver (see |
2330
849d250e6a4c
Enable generic driver by default.
Florian Pose <fp@igh-essen.com>
parents:
2297
diff
changeset
|
3011 |
sec.~\ref{sec:generic-driver}). & yes\\ |
2297
0566476835d7
Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents:
2133
diff
changeset
|
3012 |
|
0566476835d7
Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents:
2133
diff
changeset
|
3013 |
\lstinline+--enable-8139too+ & Build the 8139too driver & yes\\ |
0566476835d7
Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents:
2133
diff
changeset
|
3014 |
|
0566476835d7
Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents:
2133
diff
changeset
|
3015 |
\lstinline+--with-8139too-kernel+ & 8139too kernel & $\dagger$\\ |
0566476835d7
Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents:
2133
diff
changeset
|
3016 |
|
0566476835d7
Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents:
2133
diff
changeset
|
3017 |
\lstinline+--enable-e100+ & Build the e100 driver & no\\ |
0566476835d7
Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents:
2133
diff
changeset
|
3018 |
|
0566476835d7
Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents:
2133
diff
changeset
|
3019 |
\lstinline+--with-e100-kernel+ & e100 kernel & $\dagger$\\ |
0566476835d7
Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents:
2133
diff
changeset
|
3020 |
|
0566476835d7
Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents:
2133
diff
changeset
|
3021 |
\lstinline+--enable-e1000+ & Enable e1000 driver & no\\ |
0566476835d7
Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents:
2133
diff
changeset
|
3022 |
|
0566476835d7
Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents:
2133
diff
changeset
|
3023 |
\lstinline+--with-e1000-kernel+ & e1000 kernel & $\dagger$\\ |
0566476835d7
Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents:
2133
diff
changeset
|
3024 |
|
2364
41ad0b0e55b0
Use 1.5 documentation/ethercat_doc.tex.
Florian Pose <fp@igh-essen.com>
parents:
2330
diff
changeset
|
3025 |
\lstinline+--enable-e1000e+ & Enable e1000e driver & no\\ |
41ad0b0e55b0
Use 1.5 documentation/ethercat_doc.tex.
Florian Pose <fp@igh-essen.com>
parents:
2330
diff
changeset
|
3026 |
|
41ad0b0e55b0
Use 1.5 documentation/ethercat_doc.tex.
Florian Pose <fp@igh-essen.com>
parents:
2330
diff
changeset
|
3027 |
\lstinline+--with-e1000e-kernel+ & e1000e kernel & $\dagger$\\ |
41ad0b0e55b0
Use 1.5 documentation/ethercat_doc.tex.
Florian Pose <fp@igh-essen.com>
parents:
2330
diff
changeset
|
3028 |
|
2297
0566476835d7
Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents:
2133
diff
changeset
|
3029 |
\lstinline+--enable-r8169+ & Enable r8169 driver & no\\ |
0566476835d7
Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents:
2133
diff
changeset
|
3030 |
|
0566476835d7
Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents:
2133
diff
changeset
|
3031 |
\lstinline+--with-r8169-kernel+ & r8169 kernel & $\dagger$\\ |
0566476835d7
Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents:
2133
diff
changeset
|
3032 |
|
0566476835d7
Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents:
2133
diff
changeset
|
3033 |
\hline |
0566476835d7
Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents:
2133
diff
changeset
|
3034 |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3035 |
\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
|
3036 |
|
2297
0566476835d7
Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents:
2133
diff
changeset
|
3037 |
\lstinline+--enable-debug-if+ & Create a debug interface for each master & no\\ |
0566476835d7
Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents:
2133
diff
changeset
|
3038 |
|
0566476835d7
Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents:
2133
diff
changeset
|
3039 |
\lstinline+--enable-debug-ring+ & Create a debug ring to record frames & no\\ |
0566476835d7
Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents:
2133
diff
changeset
|
3040 |
|
0566476835d7
Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents:
2133
diff
changeset
|
3041 |
\lstinline+--enable-eoe+ & Enable EoE support & yes\\ |
0566476835d7
Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents:
2133
diff
changeset
|
3042 |
|
0566476835d7
Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents:
2133
diff
changeset
|
3043 |
\lstinline+--enable-cycles+ & Use CPU timestamp counter. Enable this on Intel |
0566476835d7
Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents:
2133
diff
changeset
|
3044 |
architecture to get finer timing calculation. & no\\ |
0566476835d7
Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents:
2133
diff
changeset
|
3045 |
|
0566476835d7
Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents:
2133
diff
changeset
|
3046 |
\lstinline+--enable-hrtimer+ & Use high-resolution timer to let the master |
0566476835d7
Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents:
2133
diff
changeset
|
3047 |
state machine sleep between sending frames. & no\\ |
0566476835d7
Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents:
2133
diff
changeset
|
3048 |
|
0566476835d7
Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents:
2133
diff
changeset
|
3049 |
\lstinline+--enable-regalias+ & Read alias address from register. & no\\ |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3050 |
|
1588
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
3051 |
\lstinline+--enable-tool+ & Build the command-line tool ``ethercat'' (see |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
3052 |
sec.~\ref{sec:tool}). & yes\\ |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
3053 |
|
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
3054 |
\lstinline+--enable-userlib+ & Build the userspace library. & yes\\ |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
3055 |
|
2297
0566476835d7
Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents:
2133
diff
changeset
|
3056 |
\lstinline+--enable-tty+ & Build the TTY driver. & no\\ |
0566476835d7
Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents:
2133
diff
changeset
|
3057 |
|
0566476835d7
Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents:
2133
diff
changeset
|
3058 |
\lstinline+--enable-wildcards+ & Enable \textit{0xffffffff} to be wildcards |
0566476835d7
Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents:
2133
diff
changeset
|
3059 |
for vendor ID and product code. & no\\ |
1085
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 |
\hline |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3062 |
|
2297
0566476835d7
Updated configuration docs.
Florian Pose <fp@igh-essen.com>
parents:
2133
diff
changeset
|
3063 |
\end{longtable} |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3064 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3065 |
\begin{description} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3066 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3067 |
\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
|
3068 |
extracted from the Linux kernel sources. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3069 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3070 |
\end{description} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3071 |
|
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
3072 |
\section{Building the Interface Documentation} |
1094
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3073 |
\label{sec:gendoc} |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3074 |
|
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3075 |
The source code is documented using Doxygen~\cite{doxygen}. To build the HTML |
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
3076 |
documentation, the Doxygen software has to be installed. The below command |
1095 | 3077 |
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
|
3078 |
|
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3079 |
\begin{lstlisting} |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3080 |
$ `\textbf{make doc}` |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3081 |
\end{lstlisting} |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3082 |
|
1204
4e3e8400c338
Removed examples; fixed undefines references; preliminary version.
Florian Pose <fp@igh-essen.com>
parents:
1203
diff
changeset
|
3083 |
The interface documentation can be viewed by pointing a browser to the file |
1293
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
3084 |
\textit{doxygen-output/html/index.html}. The functions and data structures of |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
3085 |
the application interface a covered by an own module ``Application |
a2a03519ee47
Prcess data; slave configuration + attachment; typos.
Florian Pose <fp@igh-essen.com>
parents:
1292
diff
changeset
|
3086 |
Interface''. |
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
3087 |
|
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
3088 |
\section{Installing the Software} |
1094
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3089 |
|
1106
745a0cc03143
Added depmod call to docs.
Florian Pose <fp@igh-essen.com>
parents:
1095
diff
changeset
|
3090 |
The below commands have to be entered as \textit{root}: The first one will |
1275
c9de1c0c1f51
*space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents:
1270
diff
changeset
|
3091 |
install the EtherCAT header, init script, sysconfig file and the userspace |
1202
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
3092 |
tool to the prefix path. The second one will install the kernel modules to the |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
3093 |
kernel's modules directory. The final \lstinline+depmod+ call is necessary to |
91d190223daa
Next changes for the documentation.
Florian Pose <fp@igh-essen.com>
parents:
1140
diff
changeset
|
3094 |
include the kernel modules into the \textit{modules.dep} file to make it |
2421 | 3095 |
available to the \lstinline+modprobe+ command, used in the init script. |
369 | 3096 |
|
1094
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3097 |
\begin{lstlisting} |
1106
745a0cc03143
Added depmod call to docs.
Florian Pose <fp@igh-essen.com>
parents:
1095
diff
changeset
|
3098 |
# `\textbf{make install}` |
1094
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3099 |
# `\textbf{make modules\_install}` |
1106
745a0cc03143
Added depmod call to docs.
Florian Pose <fp@igh-essen.com>
parents:
1095
diff
changeset
|
3100 |
# `\textbf{depmod}` |
369 | 3101 |
\end{lstlisting} |
3102 |
||
1095 | 3103 |
If the target kernel's modules directory is not under \textit{/lib/modules}, a |
3104 |
different destination directory can be specified with the \lstinline+DESTDIR+ |
|
3105 |
make variable. For example: |
|
487 | 3106 |
|
1094
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3107 |
\begin{lstlisting} |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3108 |
# `\textbf{make DESTDIR=/vol/nfs/root modules\_install}` |
487 | 3109 |
\end{lstlisting} |
3110 |
||
3111 |
This command will install the compiled kernel modules to |
|
3112 |
\textit{/vol/nfs/root/lib/modules}, prepended by the kernel release. |
|
3113 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3114 |
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
|
3115 |
master shall not be loaded on system startup, the use of the init script is |
1289
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
3116 |
recommended for manual (un-)loading.} (see sec.~\ref{sec:system}), the init |
1086
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
3117 |
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
|
3118 |
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
|
3119 |
distributions. |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3120 |
|
1107 | 3121 |
% FIXME relative ln -s? |
1094
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3122 |
\begin{lstlisting} |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3123 |
# `\textbf{cd /opt/etherlab}` |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3124 |
# `\textbf{cp etc/sysconfig/ethercat /etc/sysconfig/}` |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3125 |
# `\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
|
3126 |
# `\textbf{insserv ethercat}` |
374
e43a29f9079e
Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents:
371
diff
changeset
|
3127 |
\end{lstlisting} |
e43a29f9079e
Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents:
371
diff
changeset
|
3128 |
|
376
d1441d87f5c1
Documentation: EtherLab-CD; obtaining the DEVICE_INDEX.
Florian Pose <fp@igh-essen.com>
parents:
374
diff
changeset
|
3129 |
Now the sysconfig file \texttt{/etc/sysconfig/ethercat} (see |
1289
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
3130 |
sec.~\ref{sec:sysconfig}) has to be customized. The minimal customization is |
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
3131 |
to set the \lstinline+MASTER0_DEVICE+ variable to the MAC address of the |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3132 |
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
|
3133 |
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
|
3134 |
\lstinline+DEVICE_MODULES+ variable. |
369 | 3135 |
|
1297 | 3136 |
After the basic configuration is done, the master can be started with the |
3137 |
below command: |
|
369 | 3138 |
|
1094
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3139 |
\begin{lstlisting} |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3140 |
# `\textbf{/etc/init.d/ethercat start}` |
369 | 3141 |
\end{lstlisting} |
3142 |
||
1214 | 3143 |
At this time, the operation of the master can be observed by viewing the |
3144 |
Syslog\index{Syslog} messages, which should look like the ones below. If |
|
3145 |
EtherCAT slaves are connected to the master's EtherCAT device, the activity |
|
3146 |
indicators should begin to flash. |
|
369 | 3147 |
|
3148 |
\begin{lstlisting}[numbers=left] |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3149 |
EtherCAT: Master driver `\masterversion` |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3150 |
EtherCAT: 1 master waiting for devices. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3151 |
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
|
3152 |
Copyright (c) 1999-2005 Intel Corporation. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3153 |
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
|
3154 |
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
|
3155 |
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
|
3156 |
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
|
3157 |
EtherCAT: Starting master thread. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3158 |
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
|
3159 |
Connection |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3160 |
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
|
3161 |
Full Duplex |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3162 |
EtherCAT: Link state changed to UP. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3163 |
EtherCAT: 7 slave(s) responding. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3164 |
EtherCAT: Slave states: PREOP. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3165 |
EtherCAT: Scanning bus. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3166 |
EtherCAT: Bus scanning completed in 431 ms. |
369 | 3167 |
\end{lstlisting} |
3168 |
||
3169 |
\begin{description} |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3170 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3171 |
\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
|
3172 |
is initialized. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3173 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3174 |
\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
|
3175 |
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
|
3176 |
\lstinline+00:0E:0C:DA:A2:20+. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3177 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3178 |
\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
|
3179 |
state machine and begins scanning the bus. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3180 |
|
369 | 3181 |
\end{description} |
3182 |
||
1214 | 3183 |
\section{Automatic Device Node Creation} |
3184 |
\label{sec:autonode} |
|
3185 |
||
1289
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
3186 |
The \lstinline+ethercat+ command-line tool (see sec.~\ref{sec:tool}) |
1214 | 3187 |
communicates with the master via a character device. The corresponding device |
1289
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
3188 |
nodes are created automatically, if the udev daemon is running. Note, that on |
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
3189 |
some distributions, the \lstinline+udev+ package is not installed by default. |
1214 | 3190 |
|
3191 |
The device nodes will be created with mode \lstinline+0660+ and group |
|
1292 | 3192 |
\lstinline+root+ by default. If ``normal'' users shall have reading access, a |
3193 |
udev rule file (for example \textit{/etc/udev/rules.d/99-EtherCAT.rules}) has |
|
3194 |
to be created with the following contents: |
|
1214 | 3195 |
|
3196 |
\begin{lstlisting} |
|
3197 |
KERNEL=="EtherCAT[0-9]*", MODE="0664" |
|
3198 |
\end{lstlisting} |
|
3199 |
||
3200 |
After the udev rule file is created and the EtherCAT master is restarted with |
|
3201 |
\lstinline[breaklines=true]+/etc/init.d/ethercat restart+, the device node |
|
3202 |
will be automatically created with the desired rights: |
|
3203 |
||
3204 |
\begin{lstlisting} |
|
3205 |
# `\textbf{ls -l /dev/EtherCAT0}` |
|
3206 |
crw-rw-r-- 1 root root 252, 0 2008-09-03 16:19 /dev/EtherCAT0 |
|
3207 |
\end{lstlisting} |
|
3208 |
||
1289
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
3209 |
Now, the \lstinline+ethercat+ tool can be used (see sec.~\ref{sec:tool}) even |
5b82b6b39c2d
Removed unnecessary modules; renamed references.
Florian Pose <fp@igh-essen.com>
parents:
1283
diff
changeset
|
3210 |
as a non-root user. |
1214 | 3211 |
|
1306
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
3212 |
If non-root users shall have writing access, the following udev rule can be |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
3213 |
used instead: |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
3214 |
|
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
3215 |
\begin{lstlisting} |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
3216 |
KERNEL=="EtherCAT[0-9]*", MODE="0664", GROUP="users" |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
3217 |
\end{lstlisting} |
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
3218 |
|
369 | 3219 |
%------------------------------------------------------------------------------ |
3220 |
||
3221 |
\begin{thebibliography}{99} |
|
1094
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3222 |
|
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3223 |
\bibitem{etherlab} Ingenieurgemeinschaft IgH: EtherLab -- Open Source Toolkit |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3224 |
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
|
3225 |
technology. \url{http://etherlab.org/en}, 2008. |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3226 |
|
369 | 3227 |
\bibitem{dlspec} IEC 61158-4-12: Data-link Protocol Specification. |
1095 | 3228 |
International Electrotechnical Commission (IEC), 2005. |
1094
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3229 |
|
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3230 |
\bibitem{alspec} IEC 61158-6-12: Application Layer Protocol Specification. |
1095 | 3231 |
International Electrotechnical Commission (IEC), 2005. |
1094
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3232 |
|
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3233 |
\bibitem{gpl} GNU General Public License, Version 2. |
1275
c9de1c0c1f51
*space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents:
1270
diff
changeset
|
3234 |
\url{http://www.gnu.org/licenses/gpl-2.0.html}. October~15, 2008. |
c9de1c0c1f51
*space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents:
1270
diff
changeset
|
3235 |
|
c9de1c0c1f51
*space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents:
1270
diff
changeset
|
3236 |
\bibitem{lgpl} GNU Lesser General Public License, Version 2.1. |
c9de1c0c1f51
*space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents:
1270
diff
changeset
|
3237 |
\url{http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html}. October~15, |
c9de1c0c1f51
*space without whitespace; licensing; userspace interfaces.
Florian Pose <fp@igh-essen.com>
parents:
1270
diff
changeset
|
3238 |
2008. |
1094
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3239 |
|
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3240 |
\bibitem{lsb} Linux Standard Base. |
1306
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
3241 |
\url{http://www.linuxfoundation.org/en/LSB}. August~9, 2006. |
1094
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3242 |
|
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3243 |
\bibitem{wireshark} Wireshark. \url{http://www.wireshark.org}. 2008. |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3244 |
|
1306
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
3245 |
\bibitem{automata} {\it Hopcroft, J.\,E.\ / Ullman, J.\,D.}: Introduction to |
1094
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3246 |
Automata Theory, Languages and Computation. Adison-Wesley, Reading, |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3247 |
Mass.~1979. |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3248 |
|
1306
a27c839d043b
merge -r1566:1573 branches/stable-1.4: Documentation.
Florian Pose <fp@igh-essen.com>
parents:
1299
diff
changeset
|
3249 |
\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
|
3250 |
misunderstandings. In: IEE journal ``Computing and Control Engineering'', |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3251 |
2004. |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3252 |
|
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3253 |
\bibitem{rtai} RTAI. The RealTime Application Interface for Linux from DIAPM. |
1588
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
3254 |
\url{https://www.rtai.org}, 2010. |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
3255 |
|
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
3256 |
\bibitem{rt-preempt} RT PREEMPT HOWTO. |
2f6e6e7d31dd
Using rcsInfo; Documented generic Ethernet driver.
Florian Pose <fp@igh-essen.com>
parents:
1517
diff
changeset
|
3257 |
\url{http://rt.wiki.kernel.org/index.php/RT_PREEMPT_HOWTO}, 2010. |
1094
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3258 |
|
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3259 |
\bibitem{doxygen} Doxygen. Source code documentation generator tool. |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3260 |
\url{http://www.stack.nl/~dimitri/doxygen}, 2008. |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3261 |
|
1772
b4c85bedd68f
Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents:
1592
diff
changeset
|
3262 |
\bibitem{mercurial} Mercurial SCM. \url{http://mercurial.selenic.com}, 2010. |
b4c85bedd68f
Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents:
1592
diff
changeset
|
3263 |
|
b4c85bedd68f
Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents:
1592
diff
changeset
|
3264 |
\bibitem{autoconf} Autoconf -- GNU Project -- Free Software Foundation (FSF). |
b4c85bedd68f
Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents:
1592
diff
changeset
|
3265 |
\url{http://www.gnu.org/software/autoconf}, 2010. |
b4c85bedd68f
Improved installation chapter.
Florian Pose <fp@igh-essen.com>
parents:
1592
diff
changeset
|
3266 |
|
1917 | 3267 |
\bibitem{soespec} IEC 61800-7-304: Adjustable speed electrical power drive |
3268 |
systems - Part 7-300: Generic interface and use of profiles for power drive |
|
3269 |
systems - Mapping of profiles to network technologies. International |
|
3270 |
Electrotechnical Commission (IEC), 2007. |
|
3271 |
||
369 | 3272 |
\end{thebibliography} |
3273 |
||
917
07b0ad9722a1
Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents:
814
diff
changeset
|
3274 |
\printnomenclature |
369 | 3275 |
\addcontentsline{toc}{chapter}{\nomname} |
3276 |
\markleft{\nomname} |
|
3277 |
||
3278 |
\printindex |
|
3279 |
\markleft{Index} |
|
3280 |
||
3281 |
%------------------------------------------------------------------------------ |
|
3282 |
||
3283 |
\end{document} |
|
3284 |
||
3285 |
%------------------------------------------------------------------------------ |