author | Florian Pose <fp@igh-essen.com> |
Tue, 22 Jul 2008 14:23:41 +0000 | |
changeset 1127 | bd7aef6c310c |
parent 1107 | fccab40a5916 |
child 1140 | cc779f7d2496 |
permissions | -rw-r--r-- |
369 | 1 |
%------------------------------------------------------------------------------ |
2 |
% |
|
3 |
% IgH EtherCAT Master Documentation |
|
4 |
% |
|
5 |
% $Id$ |
|
6 |
% |
|
1095 | 7 |
% vi: spell spelllang=en |
8 |
% |
|
369 | 9 |
%------------------------------------------------------------------------------ |
10 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
11 |
% |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
12 |
% Conventions |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
13 |
% The IgH EtherCAT Master |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
14 |
% Feature Summary |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
15 |
% License |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
16 |
% Architecture |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
17 |
% Phases |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
18 |
% Behavior (Scanning) TODO |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
19 |
% Application Interface |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
20 |
% Interface version |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
21 |
% Master Requesting and Releasing |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
22 |
% Master Locking |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
23 |
% Slave configuration |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
24 |
% Configuring Pdo assignment and mapping |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
25 |
% Domains (memory) |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
26 |
% Pdo entry registration |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
27 |
% Sdo configuration |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
28 |
% Sdo access |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
29 |
% Cyclic operation |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
30 |
% Ethernet Devices |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
31 |
% Device Interface |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
32 |
% Device Modules |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
33 |
% Network Driver Basics |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
34 |
% EtherCAT Network Drivers |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
35 |
% Device Selection |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
36 |
% The Device Interface |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
37 |
% Patching Network Drivers |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
38 |
% The Master's State Machines |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
39 |
% Master |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
40 |
% Slave scanning |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
41 |
% SII |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
42 |
% Pdo assign/mapping |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
43 |
% Slave configuration |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
44 |
% State change |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
45 |
% Pdo assign/mapping |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
46 |
% CoE upload/download/information |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
47 |
% Mailbox Protocol Implementations |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
48 |
% Ethernet-over-EtherCAT (EoE) |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
49 |
% CANopen-over-EtherCAT (CoE) |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
50 |
% User Space |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
51 |
% The ethercat command |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
52 |
% System Integration |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
53 |
% The EtherCAT Init Script |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
54 |
% The EtherCAT Sysconfig File |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
55 |
% Monitoring and Debugging |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
56 |
% Installation |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
57 |
% Example applications |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
58 |
% Bibliography |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
59 |
% Glossary |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
60 |
% |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
61 |
|
369 | 62 |
\documentclass[a4paper,12pt,BCOR6mm,bibtotoc,idxtotoc]{scrbook} |
63 |
||
64 |
\usepackage[latin1]{inputenc} |
|
65 |
\usepackage[automark,headsepline]{scrpage2} |
|
66 |
\usepackage{graphicx} |
|
67 |
\usepackage{makeidx} |
|
68 |
\usepackage[refpage]{nomencl} |
|
69 |
\usepackage{listings} |
|
70 |
\usepackage{svn} |
|
71 |
\usepackage{textcomp} |
|
72 |
\usepackage{url} |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
73 |
\usepackage{SIunits} |
371
97f684433d3b
Improved documentation makefile, removed svn.sty, fixed LaTeX penalties.
Florian Pose <fp@igh-essen.com>
parents:
370
diff
changeset
|
74 |
\usepackage[pdfpagelabels,plainpages=false]{hyperref} |
369 | 75 |
|
76 |
\setlength{\parskip}{0.8ex plus 0.8ex minus 0.5ex} |
|
77 |
\setlength{\parindent}{0mm} |
|
78 |
||
79 |
\setcounter{secnumdepth}{\subsubsectionlevel} |
|
80 |
||
81 |
\DeclareFontShape{OT1}{cmtt}{bx}{n} |
|
82 |
{ |
|
83 |
<5><6><7><8><9><10><10.95><12><14.4><17.28><20.74><24.88>cmttb10 |
|
84 |
}{} |
|
85 |
||
86 |
\lstset{basicstyle=\ttfamily\small,numberstyle=\tiny,aboveskip=4mm, |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
87 |
belowskip=2mm,escapechar=`} |
369 | 88 |
\renewcommand\lstlistlistingname{List of Listings} |
89 |
||
917
07b0ad9722a1
Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents:
814
diff
changeset
|
90 |
% Workaround for lstlistoflistings bug |
07b0ad9722a1
Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents:
814
diff
changeset
|
91 |
\makeatletter% --> De-TeX-FAQ |
07b0ad9722a1
Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents:
814
diff
changeset
|
92 |
\renewcommand*{\lstlistoflistings}{% |
07b0ad9722a1
Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents:
814
diff
changeset
|
93 |
\begingroup |
07b0ad9722a1
Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents:
814
diff
changeset
|
94 |
\if@twocolumn |
07b0ad9722a1
Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents:
814
diff
changeset
|
95 |
\@restonecoltrue\onecolumn |
07b0ad9722a1
Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents:
814
diff
changeset
|
96 |
\else |
07b0ad9722a1
Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents:
814
diff
changeset
|
97 |
\@restonecolfalse |
07b0ad9722a1
Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents:
814
diff
changeset
|
98 |
\fi |
07b0ad9722a1
Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents:
814
diff
changeset
|
99 |
\lol@heading |
07b0ad9722a1
Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents:
814
diff
changeset
|
100 |
\setlength{\parskip}{\z@}% |
07b0ad9722a1
Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents:
814
diff
changeset
|
101 |
\setlength{\parindent}{\z@}% |
07b0ad9722a1
Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents:
814
diff
changeset
|
102 |
\setlength{\parfillskip}{\z@ \@plus 1fil}% |
07b0ad9722a1
Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents:
814
diff
changeset
|
103 |
\@starttoc{lol}% |
07b0ad9722a1
Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents:
814
diff
changeset
|
104 |
\if@restonecol\twocolumn\fi |
07b0ad9722a1
Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents:
814
diff
changeset
|
105 |
\endgroup |
07b0ad9722a1
Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents:
814
diff
changeset
|
106 |
} |
07b0ad9722a1
Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents:
814
diff
changeset
|
107 |
\makeatother% --> \makeatletter |
07b0ad9722a1
Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents:
814
diff
changeset
|
108 |
|
369 | 109 |
\renewcommand\nomname{Glossary} |
110 |
||
111 |
\newcommand{\IgH}{\raisebox{-0.7667ex} |
|
112 |
{\includegraphics[height=2.2ex]{images/ighsign}}} |
|
113 |
||
114 |
\SVN $Date$ |
|
115 |
\SVN $Revision$ |
|
116 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
117 |
\newcommand{\masterversion}{1.4.0} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
118 |
\newcommand{\linenum}[1]{\normalfont\textcircled{\tiny #1}} |
487 | 119 |
|
369 | 120 |
\makeindex |
917
07b0ad9722a1
Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents:
814
diff
changeset
|
121 |
\makenomenclature |
369 | 122 |
|
123 |
%------------------------------------------------------------------------------ |
|
124 |
||
125 |
\begin{document} |
|
126 |
||
127 |
\pagenumbering{roman} |
|
128 |
\pagestyle{empty} |
|
129 |
||
130 |
\begin{titlepage} |
|
131 |
\begin{center} |
|
132 |
\rule{\textwidth}{1.5mm} |
|
133 |
||
134 |
{\Huge\bf IgH \includegraphics[height=2.4ex]{images/ethercat} |
|
487 | 135 |
Master \masterversion\\[1ex] |
369 | 136 |
Documentation} |
137 |
||
138 |
\vspace{1ex} |
|
139 |
\rule{\textwidth}{1.5mm} |
|
140 |
||
141 |
\vspace{\fill} |
|
142 |
{\Large Florian Pose, \url{fp@igh-essen.com}\\[1ex] |
|
143 |
Ingenieurgemeinschaft \IgH} |
|
144 |
||
145 |
\vspace{\fill} |
|
146 |
{\Large Essen, \SVNDate\\[1ex] |
|
147 |
Revision \SVNRevision} |
|
148 |
\end{center} |
|
149 |
\end{titlepage} |
|
150 |
||
151 |
%------------------------------------------------------------------------------ |
|
152 |
||
153 |
\tableofcontents |
|
154 |
\listoftables |
|
155 |
\listoffigures |
|
156 |
\lstlistoflistings |
|
157 |
||
158 |
%------------------------------------------------------------------------------ |
|
159 |
||
160 |
\newpage |
|
161 |
\pagestyle{scrheadings} |
|
162 |
||
163 |
\section*{Conventions} |
|
164 |
\addcontentsline{toc}{section}{Conventions} |
|
165 |
\markleft{Conventions} |
|
166 |
||
167 |
The following typographic conventions are used: |
|
168 |
||
169 |
\begin{itemize} |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
170 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
171 |
\item \textit{Italic face} is used for newly introduced terms and file names. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
172 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
173 |
\item \texttt{Typewriter face} is used for code examples and command line |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
174 |
output. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
175 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
176 |
\item \texttt{\textbf{Bold typewriter face}} is used for user input in command |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
177 |
lines. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
178 |
|
369 | 179 |
\end{itemize} |
180 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
181 |
Data values and addresses are usually specified as hexadecimal values. These |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
182 |
are marked in the \textit{C} programming language style with the prefix |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
183 |
\lstinline+0x+ (example: \lstinline+0x88A4+). Unless otherwise noted, address |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
184 |
values are specified as byte addresses. |
369 | 185 |
|
186 |
Function names are always printed with parentheses, but without |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
187 |
parameters. So, if a function \lstinline+ecrt_request_master()+ has |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
188 |
empty parentheses, this shall not imply that it has no parameters. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
189 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
190 |
If shell commands have to be entered, this is marked by a dollar prompt: |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
191 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
192 |
\begin{lstlisting} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
193 |
$ |
369 | 194 |
\end{lstlisting} |
195 |
||
196 |
Further, if a shell command has to be entered as the superuser, the |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
197 |
prompt is a mesh: |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
198 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
199 |
\begin{lstlisting} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
200 |
# |
369 | 201 |
\end{lstlisting} |
202 |
||
203 |
%------------------------------------------------------------------------------ |
|
204 |
||
205 |
\chapter{The IgH EtherCAT Master} |
|
206 |
\label{chapter:master} |
|
207 |
\pagenumbering{arabic} |
|
208 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
209 |
This chapter covers some general information about the EtherCAT master. |
369 | 210 |
|
211 |
%------------------------------------------------------------------------------ |
|
212 |
||
213 |
\section{Feature Summary} |
|
214 |
\label{sec:summary} |
|
215 |
\index{Master!Features} |
|
216 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
217 |
The list below gives a short summary of the master features. |
369 | 218 |
|
219 |
\begin{itemize} |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
220 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
221 |
\item Designed as a kernel module for Linux 2.6. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
222 |
|
1086
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
223 |
\item Implemented according to IEC 61158-12 \cite{dlspec} \cite{alspec}. |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
224 |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
225 |
\item Comes with EtherCAT-capable drivers for several common Ethernet devices. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
226 |
|
369 | 227 |
\begin{itemize} |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
228 |
|
369 | 229 |
\item The Ethernet hardware is operated without interrupts. |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
230 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
231 |
\item Drivers for additional Ethernet hardware can easily be implemented |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
232 |
using the common device interface (see section~\ref{sec:ecdev}) provided by |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
233 |
the master module. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
234 |
|
369 | 235 |
\end{itemize} |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
236 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
237 |
\item The master module supports multiple EtherCAT masters running in |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
238 |
parallel. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
239 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
240 |
\item The master code supports any Linux realtime extension through its |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
241 |
independent architecture. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
242 |
|
369 | 243 |
\begin{itemize} |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
244 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
245 |
\item RTAI\nomenclature{RTAI}{Realtime Application Interface}, |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
246 |
ADEOS\nomenclature{ADEOS}{Adaptive Domain Environment for Operating |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
247 |
Systems}, etc. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
248 |
|
369 | 249 |
\item It runs well even without realtime extensions. |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
250 |
|
369 | 251 |
\end{itemize} |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
252 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
253 |
\item Common ``realtime interface'' for applications, that want to use |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
254 |
EtherCAT functionality (see section~\ref{sec:ecrt}). |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
255 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
256 |
\item \textit{Domains} are introduced, to allow grouping of process |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
257 |
data transfers with different slave groups and task periods. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
258 |
|
369 | 259 |
\begin{itemize} |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
260 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
261 |
\item Handling of multiple domains with different task periods. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
262 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
263 |
\item Automatic calculation of process data mapping, FMMU and sync manager |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
264 |
configuration within each domain. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
265 |
|
369 | 266 |
\end{itemize} |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
267 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
268 |
\item Communication through several finite state machines. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
269 |
|
369 | 270 |
\begin{itemize} |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
271 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
272 |
\item Automatic bus scanning after topology changes. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
273 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
274 |
\item Bus monitoring during operation. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
275 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
276 |
\item Automatic reconfiguration of slaves (for example after power failure) |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
277 |
during operation. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
278 |
|
369 | 279 |
\end{itemize} |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
280 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
281 |
\item CANopen-over-EtherCAT (CoE) |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
282 |
|
369 | 283 |
\begin{itemize} |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
284 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
285 |
\item Sdo upload, download and information service. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
286 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
287 |
\item Slave configuration via Sdos. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
288 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
289 |
\item Sdo access from user-space and from the application. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
290 |
|
369 | 291 |
\end{itemize} |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
292 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
293 |
\item Ethernet-over-EtherCAT (EoE) |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
294 |
|
369 | 295 |
\begin{itemize} |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
296 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
297 |
\item Transparent use of EoE slaves via virtual network interfaces. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
298 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
299 |
\item Natively supports either a switched or a routed EoE network |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
300 |
architecture. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
301 |
|
369 | 302 |
\end{itemize} |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
303 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
304 |
\item User space command-line-tool ``ethercat``. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
305 |
|
369 | 306 |
\begin{itemize} |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
307 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
308 |
\item Showing the current bus with slaves, Pdos and Sdos. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
309 |
\item Showing the bus configuration. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
310 |
\item Showing domains and process data. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
311 |
\item Setting the master's debug level. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
312 |
\item Writing alias addresses. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
313 |
\item Sdo uploading/downloading. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
314 |
\item Reading/writing a slave's SII. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
315 |
\item Setting slave states. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
316 |
\item Generate slave description XML. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
317 |
|
369 | 318 |
\end{itemize} |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
319 |
|
369 | 320 |
\item Seamless system integration though LSB\nomenclature{LSB}{Linux |
321 |
Standard Base} compliance. |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
322 |
|
369 | 323 |
\begin{itemize} |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
324 |
|
1095 | 325 |
\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
|
326 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
327 |
\item Init script for master control. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
328 |
|
369 | 329 |
\end{itemize} |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
330 |
|
369 | 331 |
\item Virtual read-only network interface for monitoring and debugging |
332 |
purposes. |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
333 |
|
369 | 334 |
\end{itemize} |
335 |
||
336 |
%------------------------------------------------------------------------------ |
|
337 |
||
338 |
\section{License} |
|
339 |
\label{sec:license} |
|
340 |
||
341 |
The master code is released under the terms and conditions of the GNU |
|
342 |
General Public License\index{GPL} \cite{gpl} (version 2). Other |
|
343 |
developers, that want to use EtherCAT with Linux systems, are invited |
|
344 |
to use the master code or even participate on development. |
|
345 |
||
346 |
%------------------------------------------------------------------------------ |
|
347 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
348 |
\chapter{Architecture} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
349 |
\label{sec:arch} |
369 | 350 |
\index{Master!Architecture} |
351 |
||
352 |
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
|
353 |
an early design decision, which has been made for several reasons: |
369 | 354 |
|
355 |
\begin{itemize} |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
356 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
357 |
\item Kernel code has significantly better realtime characteristics, i.~e. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
358 |
less latency than user space code. It was foreseeable, that a fieldbus master |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
359 |
has a lot of cyclic work to do. Cyclic work is usually triggered by timer |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
360 |
interrupts inside the kernel. The execution delay of a function that processes |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
361 |
timer interrupts is less, when it resides in kernel space, because there is no |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
362 |
need of time-consuming context switches to a user space process. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
363 |
|
369 | 364 |
\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
|
365 |
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
|
366 |
anyway (through network device drivers), which is one more reason for the |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
367 |
master code being in kernel space. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
368 |
|
369 | 369 |
\end{itemize} |
370 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
371 |
Figure~\ref{fig:arch} gives a general overview of the master architecture. |
369 | 372 |
|
373 |
\begin{figure}[htbp] |
|
374 |
\centering |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
375 |
\includegraphics[width=.9\textwidth]{images/architecture} |
369 | 376 |
\caption{Master architecture} |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
377 |
\label{fig:arch} |
369 | 378 |
\end{figure} |
379 |
||
380 |
\paragraph{Master Module} |
|
381 |
\index{Master module} |
|
382 |
||
1086
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
383 |
Kernel module containing one or more EtherCAT master instances (see |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
384 |
section~\ref{sec:mastermod}), the ``Device Interface'' (see |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
385 |
section~\ref{sec:ecdev}) and the ``Realtime Interface'' (see |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
386 |
section~\ref{sec:ecrt}). |
369 | 387 |
|
388 |
\paragraph{Device Modules} |
|
389 |
\index{Device modules} |
|
390 |
||
1086
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
391 |
EtherCAT-capable Ethernet device driver modules\index{Device modules}, that |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
392 |
offer their devices to the EtherCAT master via the device interface (see |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
393 |
section~\ref{sec:ecdev}). These modified network drivers can handle network |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
394 |
devices used for EtherCAT operation and ``normal'' Ethernet devices in |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
395 |
parallel. A master can accept a certain device and then is able to send and |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
396 |
receive EtherCAT frames. Ethernet devices declined by the master module are |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
397 |
connected to the kernel's network stack as usual. |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
398 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
399 |
\paragraph{Application Modules} |
1086
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
400 |
\index{Application module} |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
401 |
|
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
402 |
Kernel modules, that use the EtherCAT master (usually for cyclic exchange of |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
403 |
process data with EtherCAT slaves). These modules are not part of the EtherCAT |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
404 |
master code\footnote{Although there are some examples provided in the |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
405 |
\textit{examples} directory, see chapter~\ref{chapter:examples}}, but have to |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
406 |
be generated or written by the user. An application module can ``request'' a |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
407 |
master through the realtime interface (see section~\ref{sec:ecrt}). If this |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
408 |
succeeds, the module has the control over the master: It can provide a bus |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
409 |
configuration and exchange process data. |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
410 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
411 |
%------------------------------------------------------------------------------ |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
412 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
413 |
\section{Phases} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
414 |
\index{Master phases} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
415 |
|
1086
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
416 |
The EtherCAT master runs through several phases (see fig.~\ref{fig:phases}): |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
417 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
418 |
\begin{figure}[htbp] |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
419 |
\centering |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
420 |
\includegraphics[width=.9\textwidth]{images/phases} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
421 |
\caption{Master phases and transitions} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
422 |
\label{fig:phases} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
423 |
\end{figure} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
424 |
\begin{description} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
425 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
426 |
\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
|
427 |
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
|
428 |
possible until then. |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
429 |
|
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
430 |
\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
|
431 |
an Ethernet device, but is not requested by any application yet. The master |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
432 |
runs its state machine (see section~\ref{sec:fsm-master}), that automatically |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
433 |
scans the bus for slaves and executes pending operations from the user space |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
434 |
interface (for example Sdo access). The command-line tool can be used to access |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
435 |
the bus, but there is no process data exchange because of the missing bus |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
436 |
configuration. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
437 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
438 |
\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
|
439 |
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
|
440 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
441 |
\end{description} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
442 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
443 |
%------------------------------------------------------------------------------ |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
444 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
445 |
\section{General behavior} % FIXME |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
446 |
\index{Master behavior} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
447 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
448 |
\ldots |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
449 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
450 |
%------------------------------------------------------------------------------ |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
451 |
|
1086
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
452 |
\section{Master Module} |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
453 |
\label{sec:mastermodule} |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
454 |
\index{Master module} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
455 |
|
1086
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
456 |
The EtherCAT master kernel module \textit{ec\_master} can contain multiple |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
457 |
master instances. Each master waits for a certain Ethernet device identified |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
458 |
by its MAC address\index{MAC address}. These addresses have to be specified on |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
459 |
module loading via the \textit{main\_devices} module parameter. The number of |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
460 |
master instances to initialize is taken from the number of MAC addresses |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
461 |
given. |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
462 |
|
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
463 |
The below command loads the master module with a single master instance that |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
464 |
waits for the Ethernet device with the MAC address |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
465 |
\lstinline+00:0E:0C:DA:A2:20+. The master will be accessible via index $0$. |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
466 |
|
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
467 |
\begin{lstlisting} |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
468 |
# `\textbf{modprobe ec\_master main\_devices=00:0E:0C:DA:A2:20}` |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
469 |
\end{lstlisting} |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
470 |
|
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
471 |
MAC addresses for multiple masters have to be separated by commas: |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
472 |
|
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
473 |
\begin{lstlisting} |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
474 |
# `\textbf{modprobe ec\_master main\_devices=00:0E:0C:DA:A2:20,00:e0:81:71:d5:1c}` |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
475 |
\end{lstlisting} |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
476 |
|
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
477 |
The two masters can be addressed by their indices 0 and 1 respectively (see |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
478 |
figure~\ref{fig:masters}). The master index is needed for the |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
479 |
\lstinline+ecrt_master_request()+ function of the realtime interface (see |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
480 |
section~\ref{sec:ecrt}) and the \lstinline+--master+ option of the |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
481 |
\textit{ethercat} command-line tool (see section~\ref{sec:ethercat}), which |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
482 |
defaults to $0$. |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
483 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
484 |
\begin{figure}[htbp] |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
485 |
\centering |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
486 |
\includegraphics[width=.5\textwidth]{images/masters} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
487 |
\caption{Multiple masters in one module} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
488 |
\label{fig:masters} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
489 |
\end{figure} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
490 |
|
1086
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
491 |
\paragraph{Init script} |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
492 |
\index{Init script} |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
493 |
|
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
494 |
Most probably you won't want to load the master module and the Ethernet driver |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
495 |
modules manually, but start the master as a service. See |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
496 |
section~\ref{sec:system} on how to do this. |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
497 |
|
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
498 |
\paragraph{Syslog} |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
499 |
|
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
500 |
The master module outputs information about it's state and events to the |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
501 |
kernel ring buffer. These also end up in the system logs. The above module |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
502 |
loading command should result in the messages below: |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
503 |
|
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
504 |
\begin{lstlisting} |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
505 |
# `\textbf{dmesg | tail -2}` |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
506 |
EtherCAT: Master driver `\masterversion` |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
507 |
EtherCAT: 2 masters waiting for devices. |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
508 |
|
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
509 |
# `\textbf{tail -2 /var/log/messages}` |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
510 |
Jul 4 10:22:45 ethercat kernel: EtherCAT: Master driver `\masterversion` |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
511 |
Jul 4 10:22:45 ethercat kernel: EtherCAT: 2 masters waiting |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
512 |
for devices. |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
513 |
\end{lstlisting} |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
514 |
|
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
515 |
All EtherCAT master output is prefixed with \lstinline+EtherCAT+ which makes |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
516 |
searching the logs easier. |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
517 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
518 |
%------------------------------------------------------------------------------ |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
519 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
520 |
\section{Handling of Process Data} % FIXME |
369 | 521 |
\label{sec:processdata} |
522 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
523 |
\ldots |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
524 |
|
369 | 525 |
\paragraph{Process Data Image} |
526 |
\index{Process data} |
|
527 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
528 |
The slaves offer their inputs and outputs by presenting the master so-called |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
529 |
``Process Data Objects'' (Pdos\index{Pdo}). The available Pdos can be |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
530 |
determined by reading out the slave's TXPDO and RXPDO E$^2$PROM categories. The |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
531 |
application can register the Pdos for data exchange during cyclic operation. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
532 |
The sum of all registered Pdos defines the ``process data image'', which is |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
533 |
exchanged via the ``Logical ReadWrite'' datagrams introduced |
369 | 534 |
in~\cite[section~5.4.2.4]{dlspec}. |
535 |
||
536 |
\paragraph{Process Data Domains} |
|
537 |
\index{Domain} |
|
538 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
539 |
The process data image can be easily managed by creating so-called |
814 | 540 |
``domains'', which group Pdos and allocate the datagrams needed to |
369 | 541 |
exchange them. Domains are mandatory for process data exchange, so |
542 |
there has to be at least one. They were introduced for the following |
|
543 |
reasons: |
|
544 |
||
545 |
\begin{itemize} |
|
546 |
\item The maximum size of a ``Logical ReadWrite'' datagram is limited |
|
547 |
due to the limited size of an Ethernet frame: The maximum data size |
|
548 |
is the Ethernet data field size minus the EtherCAT frame header, |
|
549 |
EtherCAT datagram header and EtherCAT datagram footer: $1500 - 2 - |
|
550 |
12 - 2 = 1484$ octets. If the size of the process data image exceeds |
|
551 |
this limit, multiple frames have to be sent, and the image has to be |
|
552 |
partitioned for the use of multiple datagrams. A domain manages this |
|
553 |
automatically. |
|
814 | 554 |
\item Not every Pdo has to be exchanged with the same frequency: The |
555 |
values of Pdos can vary slowly over time (for example temperature |
|
369 | 556 |
values), so exchanging them with a high frequency would just waste |
557 |
bus bandwidth. For this reason, multiple domains can be created, to |
|
814 | 558 |
group different Pdos and so allow separate exchange. |
369 | 559 |
\end{itemize} |
560 |
||
561 |
There is no upper limit for the number of domains, but each domain |
|
562 |
occupies one FMMU in each slave involved, so the maximum number of |
|
563 |
domains is also limited by the slaves' capabilities. |
|
564 |
||
565 |
\paragraph{FMMU Configuration} |
|
566 |
\index{FMMU!Configuration} |
|
567 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
568 |
An application can register Pdos for process data exchange. Every |
814 | 569 |
Pdo is part of a memory area in the slave's physical memory, that is |
369 | 570 |
protected by a sync manager \cite[section~6.7]{dlspec} for |
571 |
synchronized access. In order to make a sync manager react on a |
|
572 |
datagram accessing its memory, it is necessary to access the last byte |
|
573 |
covered by the sync manager. Otherwise the sync manager will not react |
|
574 |
on the datagram and no data will be exchanged. That is why the whole |
|
575 |
synchronized memory area has to be included into the process data |
|
814 | 576 |
image: For example, if a certain Pdo of a slave is registered for |
369 | 577 |
exchange with a certain domain, one FMMU will be configured to map the |
814 | 578 |
complete sync-manager-protected memory, the Pdo resides in. If a |
579 |
second Pdo of the same slave is registered for process data exchange |
|
580 |
within the same domain, and this Pdo resides in the same |
|
581 |
sync-manager-protected memory as the first Pdo, the FMMU configuration |
|
369 | 582 |
is not touched, because the appropriate memory is already part of the |
814 | 583 |
domain's process data image. If the second Pdo belongs to another |
369 | 584 |
sync-manager-protected area, this complete area is also included into |
585 |
the domains process data image. See figure~\ref{fig:fmmus} for an |
|
586 |
overview, how FMMU's are configured to map physical memory to logical |
|
587 |
process data images. |
|
588 |
||
589 |
\begin{figure}[htbp] |
|
590 |
\centering |
|
591 |
\includegraphics[width=\textwidth]{images/fmmus} |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
592 |
\caption{FMMU configuration for several domains} |
369 | 593 |
\label{fig:fmmus} |
594 |
\end{figure} |
|
595 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
596 |
\paragraph{Process Data Pointers} % FIXME |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
597 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
598 |
The figure also demonstrates the way, the application can access the exchanged |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
599 |
process data: At Pdo registration, the application has to provide the address |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
600 |
of a process data pointer. Upon calculation of the domain image and allocation |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
601 |
of process data memory, this pointer is redirected to the appropriate location |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
602 |
inside the domain's process data memory and can later be easily dereferenced by |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
603 |
the module code. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
604 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
605 |
%------------------------------------------------------------------------------ |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
606 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
607 |
\chapter{Application Interface} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
608 |
\label{sec:ecrt} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
609 |
\index{Application interface} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
610 |
|
1094
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
611 |
The application interface provides functions and data structures for |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
612 |
applications to access and use an EtherCAT master. The complete documentation |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
613 |
of the interface is included as Doxygen~\cite{doxygen} comments in the header |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
614 |
file \textit{include/ecrt.h}. You can either directly view the file comments |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
615 |
or generate an HTML documentation as described in section~\ref{sec:gendoc}. |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
616 |
|
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
617 |
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
|
618 |
interface. |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
619 |
|
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
620 |
Every application should use the master in two steps: |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
621 |
|
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
622 |
\begin{description} |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
623 |
|
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
624 |
\item[Configuration] The master is requested and the configuration is applied. |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
625 |
Domains are created Slaves are configured and Pdo entries are registered (see |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
626 |
section~\ref{sec:masterconfig}). |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
627 |
|
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
628 |
\item[Operation] Cyclic code is run, process data is exchanged (see |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
629 |
section~\ref{sec:cyclic}). |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
630 |
|
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
631 |
\end{description} |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
632 |
|
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
633 |
%------------------------------------------------------------------------------ |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
634 |
|
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
635 |
\section{Master Configuration} |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
636 |
\label{sec:masterconfig} |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
637 |
|
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
638 |
\ldots |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
639 |
|
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
640 |
\begin{figure}[htbp] |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
641 |
\centering |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
642 |
\includegraphics[width=.8\textwidth]{images/app-config} |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
643 |
\caption{Master configuration structures} |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
644 |
\label{fig:app-config} |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
645 |
\end{figure} |
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 |
%------------------------------------------------------------------------------ |
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 |
\section{Cyclic Operation} |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
650 |
\label{sec:cyclic} |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
651 |
|
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
652 |
\ldots |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
653 |
% FIXME PDOS endianess |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
654 |
|
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
655 |
|
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
656 |
%------------------------------------------------------------------------------ |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
657 |
|
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
658 |
\section{Concurrent Master Access} % FIXME |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
659 |
\label{sec:concurr} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
660 |
\index{Concurrency} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
661 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
662 |
In some cases, one master is used by several instances, for example when an |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
663 |
application does cyclic process data exchange, and there are EoE-capable slaves |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
664 |
that require to exchange Ethernet data with the kernel (see |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
665 |
section~\ref{sec:eoeimp}). For this reason, the master is a shared resource, |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
666 |
and access to it has to be sequentialized. This is usually done by locking with |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
667 |
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
|
668 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
669 |
The master itself can not provide locking mechanisms, because it has no chance |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
670 |
to know the appropriate kind of lock. Imagine, the application uses RTAI |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
671 |
functionality, then ordinary kernel semaphores would not be sufficient. For |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
672 |
that, an important design decision was made: The application that reserved a |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
673 |
master must have the total control, therefore it has to take responsibility for |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
674 |
providing the appropriate locking mechanisms. If another instance wants to |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
675 |
access the master, it has to request the master lock by callbacks, that have to |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
676 |
be set by the application. Moreover the application can deny access to the |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
677 |
master if it considers it to be awkward at the moment. |
369 | 678 |
|
679 |
\begin{figure}[htbp] |
|
680 |
\centering |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
681 |
\includegraphics[width=.6\textwidth]{images/master-locks} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
682 |
\caption{Concurrent master access} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
683 |
\label{fig:locks} |
369 | 684 |
\end{figure} |
685 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
686 |
Figure~\ref{fig:locks} exemplary shows, how two processes share one master: The |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
687 |
application's cyclic task uses the master for process data exchange, while the |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
688 |
master-internal EoE process uses it to communicate with EoE-capable slaves. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
689 |
Both have to acquire the master lock before access: The application task can |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
690 |
access the lock natively, while the EoE process has to use the callbacks. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
691 |
Section~\ref{sec:concurrency} gives an example, of how to implement this. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
692 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
693 |
%------------------------------------------------------------------------------ |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
694 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
695 |
\chapter{Ethernet devices} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
696 |
\label{sec:devices} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
697 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
698 |
The EtherCAT protocol is based on the Ethernet standard. That's why the master |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
699 |
relies on standard Ethernet hardware to communicate with the bus. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
700 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
701 |
The term \textit{device} is used as a synonym for Ethernet network interface |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
702 |
hardware. There are device driver modules that handle Ethernet hardware, which |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
703 |
the master can use to connect to an EtherCAT bus. |
369 | 704 |
|
705 |
Section~\ref{sec:networkdrivers} offers an overview of general Linux |
|
706 |
network driver modules, while section~\ref{sec:requirements} will show |
|
707 |
the requirements to an EtherCAT-enabled network driver. Finally, |
|
708 |
sections~\ref{sec:seldev} to~\ref{sec:patching} show how to fulfill |
|
709 |
these requirements and implement such a driver module. |
|
710 |
||
711 |
%------------------------------------------------------------------------------ |
|
712 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
713 |
\section{Network Driver Basics} |
369 | 714 |
\label{sec:networkdrivers} |
715 |
\index{Network drivers} |
|
716 |
||
717 |
EtherCAT relies on Ethernet hardware and the master needs a physical |
|
718 |
Ethernet device to communicate with the bus. Therefore it is necessary |
|
719 |
to understand how Linux handles network devices and their drivers, |
|
720 |
respectively. |
|
721 |
||
722 |
\paragraph{Tasks of a Network Driver} |
|
723 |
||
1095 | 724 |
Network device drivers usually handle the lower two layers of the OSI model, |
725 |
that is the physical layer and the data-link layer. A network device itself |
|
726 |
natively handles the physical layer issues: It represents the hardware to |
|
727 |
connect to the medium and to send and receive data in the way, the physical |
|
728 |
layer protocol describes. The network device driver is responsible for getting |
|
729 |
data from the kernel's networking stack and forwarding it to the hardware, |
|
730 |
that does the physical transmission. If data is received by the hardware |
|
731 |
respectively, the driver is notified (usually by means of an interrupt) and |
|
732 |
has to read the data from the hardware memory and forward it to the network |
|
733 |
stack. There are a few more tasks, a network device driver has to handle, |
|
734 |
including queue control, statistics and device dependent features. |
|
369 | 735 |
|
736 |
\paragraph{Driver Startup} |
|
737 |
||
738 |
Usually, a driver searches for compatible devices on module loading. |
|
739 |
For PCI drivers, this is done by scanning the PCI bus and checking for |
|
740 |
known device IDs. If a device is found, data structures are allocated |
|
741 |
and the device is taken into operation. |
|
742 |
||
743 |
\paragraph{Interrupt Operation} |
|
744 |
\index{Interrupt} |
|
745 |
||
746 |
A network device usually provides a hardware interrupt that is used to |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
747 |
notify the driver of received frames and success of transmission, or |
369 | 748 |
errors, respectively. The driver has to register an interrupt service |
749 |
routine (ISR\index{ISR}\nomenclature{ISR}{Interrupt Service Routine}), |
|
750 |
that is executed each time, the hardware signals such an event. If the |
|
751 |
interrupt was thrown by the own device (multiple devices can share one |
|
752 |
hardware interrupt), the reason for the interrupt has to be determined |
|
753 |
by reading the device's interrupt register. For example, if the flag |
|
754 |
for received frames is set, frame data has to be copied from hardware |
|
755 |
to kernel memory and passed to the network stack. |
|
756 |
||
757 |
\paragraph{The net\_device structure} |
|
758 |
\index{net\_device} |
|
759 |
||
760 |
The driver registers a \textit{net\_device} structure for each device |
|
761 |
to communicate with the network stack and to create a ``network |
|
762 |
interface''. In case of an Ethernet driver, this interface appears as |
|
763 |
\textit{ethX}, where X is a number assigned by the kernel on |
|
764 |
registration. The \textit{net\_device} structure receives events |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
765 |
(either from user space or from the network stack) via several |
369 | 766 |
callbacks, which have to be set before registration. Not every |
767 |
callback is mandatory, but for reasonable operation the ones below are |
|
768 |
needed in any case: |
|
769 |
||
770 |
\begin{description} |
|
1095 | 771 |
|
772 |
\item[open()] This function is called when network communication has to be |
|
773 |
started, for example after a command \textit{ifconfig ethX up} from user |
|
774 |
space. Frame reception has to be enabled by the driver. |
|
775 |
||
776 |
\item[stop()] The purpose of this callback is to ``close'' the device, i.~e. |
|
777 |
make the hardware stop receiving frames. |
|
778 |
||
779 |
\item[hard\_start\_xmit()] This function is cal\-led for each frame that has |
|
780 |
to be transmitted. The network stack passes the frame as a pointer to an |
|
781 |
\textit{sk\_buff} structure (``socket buffer''\index{Socket buffer}, see |
|
782 |
below), which has to be freed after sending. |
|
783 |
||
784 |
\item[get\_stats()] This call has to return a pointer to the device's |
|
785 |
\textit{net\_device\_stats} structure, which permanently has to be filled with |
|
786 |
frame statistics. This means, that every time a frame is received, sent, or an |
|
787 |
error happened, the appropriate counter in this structure has to be increased. |
|
788 |
||
789 |
\end{description} |
|
790 |
||
791 |
The actual registration is done with the \lstinline+register_netdev()+ call, |
|
792 |
unregistering is done with \lstinline+unregister_netdev()+. |
|
369 | 793 |
|
794 |
\paragraph{The netif Interface} |
|
795 |
\index{netif} |
|
796 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
797 |
All other communication in the direction interface $\to$ network stack is done |
1095 | 798 |
via the \lstinline+netif_*()+ calls. For example, on successful device |
799 |
opening, the network stack has to be notified, that it can now pass frames to |
|
800 |
the interface. This is done by calling \lstinline+netif_start_queue()+. After |
|
801 |
this call, the \lstinline+hard_start_xmit()+ callback can be called by the |
|
802 |
network stack. Furthermore a network driver usually manages a frame |
|
803 |
transmission queue. If this gets filled up, the network stack has to be told |
|
804 |
to stop passing further frames for a while. This happens with a call to |
|
805 |
\lstinline+netif_stop_queue()+. If some frames have been sent, and there is |
|
806 |
enough space again to queue new frames, this can be notified with |
|
807 |
\lstinline+netif_wake_queue()+. Another important call is |
|
808 |
\lstinline+netif_receive_skb()+\footnote{This function is part of the NAPI |
|
809 |
(``New API''), that replaces the kernel 2.4 technique for interfacing to the |
|
810 |
network stack (with \lstinline+netif_rx()+). NAPI is a technique to improve |
|
811 |
network performance on Linux. Read more in |
|
812 |
\url{http://www.cyberus.ca/~hadi/usenix-paper.tgz}.}: It passes a frame to the |
|
813 |
network stack, that was just received by the device. Frame data has to be |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
814 |
packed into a so-called ``socket buffer'' for that (see below). |
369 | 815 |
|
816 |
\paragraph{Socket Buffers} |
|
817 |
\index{Socket buffer} |
|
818 |
||
1095 | 819 |
Socket buffers are the basic data type for the whole network stack. They |
820 |
serve as containers for network data and are able to quickly add data headers |
|
821 |
and footers, or strip them off again. Therefore a socket buffer consists of an |
|
822 |
allocated buffer and several pointers that mark beginning of the buffer |
|
823 |
(\textit{head}), beginning of data (\textit{data}), end of data |
|
824 |
(\textit{tail}) and end of buffer (\textit{end}). In addition, a socket buffer |
|
825 |
holds network header information and (in case of received data) a pointer to |
|
826 |
the \textit{net\_device}, it was received on. There exist functions that |
|
827 |
create a socket buffer (\lstinline+dev_alloc_skb()+), add data either from |
|
828 |
front (\lstinline+skb_push()+) or back (\lstinline+skb_put()+), remove data |
|
829 |
from front (\lstinline+skb_pull()+) or back (\lstinline+skb_trim()+), or |
|
830 |
delete the buffer (\lstinline+kfree_skb()+). A socket buffer is passed from |
|
831 |
layer to layer, and is freed by the layer that uses it the last time. In case |
|
832 |
of sending, freeing has to be done by the network driver. |
|
369 | 833 |
|
834 |
%------------------------------------------------------------------------------ |
|
835 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
836 |
\section{EtherCAT Device Drivers} |
369 | 837 |
\label{sec:requirements} |
838 |
||
1095 | 839 |
There are a few requirements for Ethernet network devices to function as |
840 |
EtherCAT devices, when connected to an EtherCAT bus. |
|
369 | 841 |
|
842 |
\paragraph{Dedicated Interfaces} |
|
843 |
||
1095 | 844 |
For performance and realtime purposes, the EtherCAT master needs direct and |
845 |
exclusive access to the Ethernet hardware. This implies that the network |
|
846 |
device must not be connected to the kernel's network stack as usual, because |
|
847 |
the kernel would try to use it as an ordinary Ethernet device. |
|
369 | 848 |
|
849 |
\paragraph{Interrupt-less Operation} |
|
850 |
\index{Interrupt} |
|
851 |
||
1095 | 852 |
EtherCAT frames travel through the logical EtherCAT ring and are then sent |
853 |
back to the master. Communication is highly deterministic: A frame is sent and |
|
854 |
will be received again after a constant time. Therefore, there is no need to |
|
855 |
notify the driver about frame reception: The master can instead query the |
|
856 |
hardware for received frames. |
|
857 |
||
858 |
Figure~\ref{fig:interrupt} shows two workflows for cyclic frame transmission |
|
859 |
and reception with and without interrupts. |
|
369 | 860 |
|
861 |
\begin{figure}[htbp] |
|
862 |
\centering |
|
863 |
\includegraphics[width=.8\textwidth]{images/interrupt} |
|
864 |
\caption{Interrupt Operation versus Interrupt-less Operation} |
|
865 |
\label{fig:interrupt} |
|
866 |
\end{figure} |
|
867 |
||
1095 | 868 |
In the left workflow ``Interrupt Operation'', the data from the last cycle is |
869 |
first processed and a new frame is assembled with new datagrams, which is then |
|
870 |
sent. The cyclic work is done for now. Later, when the frame is received |
|
871 |
again by the hardware, an interrupt is triggered and the ISR is executed. The |
|
872 |
ISR will fetch the frame data from the hardware and initiate the frame |
|
873 |
dissection: The datagrams will be processed, so that the data is ready for |
|
874 |
processing in the next cycle. |
|
875 |
||
876 |
In the right workflow ``Interrupt-less Operation'', there is no hardware |
|
877 |
interrupt enabled. Instead, the hardware will be polled by the master by |
|
878 |
executing the ISR. If the frame has been received in the meantime, it will be |
|
879 |
dissected. The situation is now the same as at the beginning of the left |
|
880 |
workflow: The received data is processed and a new frame is assembled and |
|
881 |
sent. There is nothing to do for the rest of the cycle. |
|
882 |
||
883 |
The interrupt-less operation is desirable, because there is simply no need for |
|
884 |
an interrupt. Moreover hardware interrupts are not conducive in improving the |
|
885 |
driver's realtime behaviour: Their indeterministic incidences contribute to |
|
886 |
increasing the jitter. Besides, if a realtime extension (like RTAI) is used, |
|
887 |
some additional effort would have to be made to prioritize interrupts. |
|
369 | 888 |
|
889 |
\paragraph{Ethernet and EtherCAT Devices} |
|
890 |
||
1095 | 891 |
Another issue lies in the way Linux handles devices of the same type. For |
892 |
example, a PCI\nomenclature{PCI}{Peripheral Component Interconnect, Computer |
|
893 |
Bus} driver scans the PCI bus for devices it can handle. Then it registers |
|
894 |
itself as the responsible driver for all of the devices found. The problem is, |
|
895 |
that an unmodified driver can not be told to ignore a device because it will |
|
896 |
be used for EtherCAT later. There must be a way to handle multiple devices of |
|
897 |
the same type, where one is reserved for EtherCAT, while the other is treated |
|
369 | 898 |
as an ordinary Ethernet device. |
899 |
||
1095 | 900 |
For all this reasons, the author decided that the only acceptable solution is |
901 |
to modify standard Ethernet drivers in a way that they keep their normal |
|
902 |
functionality, but gain the ability to treat one or more of the devices as |
|
903 |
EtherCAT-capable. |
|
369 | 904 |
|
905 |
Below are the advantages of this solution: |
|
906 |
||
907 |
\begin{itemize} |
|
908 |
\item No need to tell the standard drivers to ignore certain devices. |
|
909 |
\item One networking driver for EtherCAT and non-EtherCAT devices. |
|
910 |
\item No need to implement a network driver from scratch and running |
|
911 |
into issues, the former developers already solved. |
|
912 |
\end{itemize} |
|
913 |
||
914 |
The chosen approach has the following disadvantages: |
|
915 |
||
916 |
\begin{itemize} |
|
917 |
\item The modified driver gets more complicated, as it must handle |
|
918 |
EtherCAT and non-EtherCAT devices. |
|
919 |
\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
|
920 |
\item Changes and bug fixes on the standard drivers have to be ported |
369 | 921 |
to the Ether\-CAT-capable versions from time to time. |
922 |
\end{itemize} |
|
923 |
||
924 |
%------------------------------------------------------------------------------ |
|
925 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
926 |
\section{Device Selection} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
927 |
\label{sec:deviceselection} |
369 | 928 |
|
929 |
After loading the master module, at least one EtherCAT-capable network |
|
930 |
driver module has to be loaded, that connects one of its devices to |
|
931 |
the master. To specify an EtherCAT device and the master to connect |
|
932 |
to, all EtherCAT-capable network driver modules should provide two |
|
933 |
module parameters: |
|
934 |
||
935 |
\begin{description} |
|
936 |
\item[ec\_device\_index] PCI device index of the device that is |
|
937 |
connected to the EtherCAT bus. If this parameter is left away, all |
|
938 |
devices found are treated as ordinary Ethernet devices. Default: |
|
939 |
$-1$ |
|
940 |
\item[ec\_master\_index] Index of the master to connect to. Default: |
|
941 |
$0$ |
|
942 |
\end{description} |
|
943 |
||
944 |
The following command loads the EtherCAT-capable RTL8139 device |
|
945 |
driver, telling it to handle the second device as an EtherCAT device |
|
946 |
and connecting it to the first master: |
|
947 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
948 |
\begin{lstlisting}[gobble=2] |
379 | 949 |
# `\textbf{modprobe ec\_8139too ec\_device\_index=1}` |
369 | 950 |
\end{lstlisting} |
951 |
||
952 |
Usually, this command does not have to be entered manually, but is |
|
953 |
called by the EtherCAT init script. See section~\ref{sec:init} for |
|
954 |
more information. |
|
955 |
||
956 |
%------------------------------------------------------------------------------ |
|
957 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
958 |
\section{The Device Interface} |
369 | 959 |
\label{sec:ecdev} |
960 |
\index{Device interface} |
|
961 |
||
962 |
An anticipation to the section about the master module |
|
963 |
(section~\ref{sec:mastermod}) has to be made in order to understand |
|
964 |
the way, a network device driver module can connect a device to a |
|
965 |
specific EtherCAT master. |
|
966 |
||
967 |
The master module provides a ``device interface'' for network device |
|
968 |
drivers. To use this interface, a network device driver module must |
|
969 |
include the header |
|
970 |
\textit{devices/ecdev.h}\nomenclature{ecdev}{EtherCAT Device}, coming |
|
971 |
with the EtherCAT master code. This header offers a function interface |
|
972 |
for EtherCAT devices which is explained below. All functions of the |
|
973 |
device interface are named with the prefix \textit{ecdev}. |
|
974 |
||
975 |
\paragraph{Device Registration} |
|
976 |
||
977 |
A network device driver can connect a physical device to an EtherCAT |
|
978 |
master with the \textit{ecdev\_register()} function. |
|
979 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
980 |
\begin{lstlisting}[gobble=2,language=C] |
369 | 981 |
ec_device_t *ecdev_register(unsigned int master_index, |
982 |
struct net_device *net_dev, |
|
983 |
ec_isr_t isr, |
|
984 |
struct module *module); |
|
985 |
\end{lstlisting} |
|
986 |
||
987 |
The first parameter \textit{master\_index} must be the index of the |
|
988 |
EtherCAT master to connect to (see section~\ref{sec:mastermod}), |
|
989 |
followed by \textit{net\_dev}, the pointer to the corresponding |
|
990 |
net\_device structure, which represents the network device to connect. |
|
991 |
The third parameter \textit{isr} must be a pointer to the interrupt |
|
992 |
service routine (ISR\index{ISR}) handling the device. The master will |
|
993 |
later execute the ISR in order to receive frames and to update the |
|
994 |
device status. The last parameter \textit{module} must be the pointer |
|
995 |
to the device driver module, which is usually accessible via the macro |
|
996 |
\textit{THIS\_MODULE} (see next paragraph). On success, the function |
|
997 |
returns a pointer to an \textit{ec\_device\_t} object, which has to be |
|
998 |
specified when calling further functions of the device interface. |
|
999 |
Therefore the device module has to store this pointer for future use. |
|
1000 |
In error case, the \textit{ecdev\_register()} returns \textit{NULL}, |
|
1001 |
which means that the device could not be registered. The reason for |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1002 |
this is printed to \textit{Syslog}\index{Syslog}. In this case, the |
369 | 1003 |
device module is supposed to abort the module initialisation and let |
1004 |
the \textit{insmod} command fail. |
|
1005 |
||
1006 |
\paragraph{Implicit Dependencies} |
|
1007 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1008 |
The reason for the module pointer has to be specified at device registration is |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1009 |
a non-trivial one: The master has to know about the module, because there will |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1010 |
be an implicit dependency between the device module and a later connected |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1011 |
application module: When an application module connects to the master, the use |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1012 |
count of the master module will be increased, so that the master module can not |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1013 |
be unloaded for the time of the connection. This is reasonable, and so |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1014 |
automatically done by the kernel. The kernel knows about this dependency, |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1015 |
because the application module uses kernel symbols provided by the master |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1016 |
module. Moreover it is mandatory, that the device module can be unloaded |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1017 |
neither, because it is implicitly used by the application module, too. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1018 |
Unloading it would lead to a fatal situation, because the master would have no |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1019 |
device to send and receive frames for the application. This dependency can not |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1020 |
be detected automatically, because the application module does not use any |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1021 |
symbols of the device module. Therefore the master explicitly increments the |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1022 |
use counter of the connected device module upon connection of an application |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1023 |
and decrements it, if it disconnects again. In this manner, it is impossible to |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1024 |
unload a device module while the master is in use. This is done with the kernel |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1025 |
function pair \textit{try\_module\_get()} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1026 |
\index{try\_module\_get@\textit{try\_module\_get()}} and \textit{module\_put()} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1027 |
\index{module\_put@\textit{module\_put()}}. The first one increases the use |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1028 |
count of a module and only fails, if the module is currently being unloaded. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1029 |
The last one decreases the use count again and never fails. Both functions take |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1030 |
a pointer to the module as their argument, which the device module therefore |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1031 |
has to specify upon device registration. |
369 | 1032 |
|
1033 |
\paragraph{Device Unregistering} |
|
1034 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1035 |
The deregistration of a device is usually done in the device module's cleanup |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1036 |
function, by calling the \textit{ecdev\_unregister()} function and specifying |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1037 |
the master index and a pointer to the device object again. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1038 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1039 |
\begin{lstlisting}[gobble=2,language=C] |
369 | 1040 |
void ecdev_unregister(unsigned int master_index, |
1041 |
ec_device_t *device); |
|
1042 |
\end{lstlisting} |
|
1043 |
||
1044 |
This function can fail too (if the master index is invalid, or the |
|
1045 |
given device was not registered), but due to the fact, that this |
|
1046 |
failure can not be dealt with appropriately, because the device module |
|
1047 |
is unloading anyway, the failure code would not be of any interest. So |
|
1048 |
the function has a void return value. |
|
1049 |
||
1050 |
\paragraph{Starting the Master} |
|
1051 |
||
1052 |
When a device has been initialized completely and is ready to send and |
|
1053 |
receive frames, the master has to be notified about this by calling |
|
1054 |
the \textit{ecdev\_start()} function. |
|
1055 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1056 |
\begin{lstlisting}[gobble=2,language=C] |
369 | 1057 |
int ecdev_start(unsigned int master_index); |
1058 |
\end{lstlisting} |
|
1059 |
||
1060 |
The master will then enter ``Idle Mode'' and start scanning the bus |
|
1061 |
(and possibly handling EoE slaves). Moreover it will make the bus |
|
1062 |
accessible via Sysfs interface and react to user interactions. The |
|
1063 |
function takes one parameter \textit{master\_index}, which has to be |
|
1064 |
the same as at the call to \textit{ecdev\_register()}. The return |
|
1065 |
value will be non-zero if the starting process failed. In this case |
|
1066 |
the device module is supposed to abort the init sequence and make the |
|
1067 |
init function return an error code. |
|
1068 |
||
1069 |
\paragraph{Stopping the Master} |
|
1070 |
||
1071 |
Before a device can be unregistered, the master has to be stopped by |
|
1072 |
calling the \textit{ecdev\_stop()} function. It will stop processing |
|
1073 |
messages of EoE slaves and leave ``Idle Mode''. The only parameter is |
|
1074 |
\textit{master\_index}. This function can not fail. |
|
1075 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1076 |
\begin{lstlisting}[gobble=2,language=C] |
369 | 1077 |
void ecdev_stop(unsigned int master_index); |
1078 |
\end{lstlisting} |
|
1079 |
||
1080 |
A subsequent call to \textit{ecdev\_unregister()} will now unregister |
|
1081 |
the device savely. |
|
1082 |
||
1083 |
\paragraph{Receiving Frames} |
|
1084 |
||
1085 |
The interrupt service routine handling device events usually has a |
|
1086 |
section where new frames are fetched from the hardware and forwarded |
|
1087 |
to the kernel network stack via \textit{netif\_receive\_skb()}. For an |
|
1088 |
EtherCAT-capable device, this has to be replaced by calling the |
|
1089 |
\textit{ecdev\_receive()} function to forward the received data to the |
|
1090 |
connected EtherCAT master instead. |
|
1091 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1092 |
\begin{lstlisting}[gobble=2,language=C] |
369 | 1093 |
void ecdev_receive(ec_device_t *device, |
1094 |
const void *data, |
|
1095 |
size_t size); |
|
1096 |
\end{lstlisting} |
|
1097 |
||
1098 |
This function takes 3 arguments, a pointer to the device object |
|
1099 |
(\textit{device}), a pointer to the received data, and the size of the |
|
1100 |
received data. The data range has to include the Ethernet headers |
|
1101 |
starting with the destination address and reach up to the last octet |
|
1102 |
of EtherCAT data, excluding the FCS. Most network devices handle the |
|
1103 |
FCS in hardware, so it is not seen by the driver code and therefore |
|
1104 |
doesn't have to be cut off manually. |
|
1105 |
||
1106 |
\paragraph{Handling the Link Status} |
|
1107 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1108 |
Information about the link status (i.~e. if there is a carrier signal detected |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1109 |
on the physical port) is also important to the master. This information is |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1110 |
usually gathered by the ISR and should be forwarded to the master by calling |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1111 |
the \textit{ecdev\_link\_state()} function. The master then can react on this |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1112 |
and warn the application of a lost link. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1113 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1114 |
\begin{lstlisting}[gobble=2,language=C] |
369 | 1115 |
void ecdev_link_state(ec_device_t *device, |
1116 |
uint8_t new_state); |
|
1117 |
\end{lstlisting} |
|
1118 |
||
1119 |
The parameter \textit{device} has to be a pointer to the device object |
|
1120 |
returned by \textit{ecdev\_\-register()}. With the second parameter |
|
1121 |
\textit{new\_state}, the new link state is passed: 1, if the link went |
|
1122 |
up, and 0, if it went down. |
|
1123 |
||
1124 |
%------------------------------------------------------------------------------ |
|
1125 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1126 |
\section{Patching Network Drivers} |
369 | 1127 |
\label{sec:patching} |
1128 |
\index{Network drivers} |
|
1129 |
||
1130 |
This section will demonstrate, how to make a standard Ethernet driver |
|
1131 |
EtherCAT-capable. The below code examples are taken out of the |
|
1132 |
modified RealTek RTL8139 driver coming with the EtherCAT master |
|
1133 |
(\textit{devices/8139too.c}). The driver was originally developed by |
|
1134 |
Donald Becker, and is currently maintained by Jeff Garzik. |
|
1135 |
||
1136 |
Unfortunately, there is no standard procedure to enable an Ethernet |
|
1137 |
driver for use with the EtherCAT master, but there are a few common |
|
1138 |
techniques, that are described in this section. |
|
1139 |
||
1140 |
\begin{enumerate} |
|
1141 |
\item A first simple rule is, that \textit{netif\_*()}-calls must be |
|
1142 |
strictly avoided for all EtherCAT devices. As mentioned before, |
|
1143 |
EtherCAT devices have no connection to the network stack, and |
|
1144 |
therefore must not call its interface functions. |
|
1145 |
\item Another important thing is, that EtherCAT devices should be |
|
1146 |
operated without interrupts. So any calls of registering interrupt |
|
1147 |
handlers and enabling interrupts at hardware level must be avoided, |
|
1148 |
too. |
|
1149 |
\item The master does not use a new socket buffer for each send |
|
1150 |
operation: Instead there is a fix one allocated on master |
|
1151 |
initialization. This socket buffer is filled with an EtherCAT frame |
|
1152 |
with every send operation and passed to the |
|
1153 |
\textit{hard\_start\_xmit()} callback. For that it is necessary, |
|
1154 |
that the socket buffer is not be freed by the network driver as |
|
1155 |
usual. |
|
1156 |
\end{enumerate} |
|
1157 |
||
1158 |
As mentioned before, the driver will handle both EtherCAT and ordinary |
|
1159 |
Ethernet devices. This implies, that for each device-dependent |
|
1160 |
operation, it has to be checked if an EtherCAT device is involved, or |
|
1161 |
just an Ethernet device. For means of simplicity, this example driver |
|
1162 |
will only handle one EtherCAT device. This makes the case |
|
1163 |
differentiations easier. |
|
1164 |
||
1165 |
\paragraph{Global Variables} |
|
1166 |
||
1167 |
First of all, there have to be additional global variables declared, |
|
1168 |
as shown in the listing: |
|
1169 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1170 |
\begin{lstlisting}[gobble=2,language=C,numbers=left] |
369 | 1171 |
static int ec_device_index = -1; |
1172 |
static int ec_device_master_index = 0; |
|
1173 |
static ec_device_t *rtl_ec_dev; |
|
1174 |
struct net_device *rtl_ec_net_dev = NULL; |
|
1175 |
\end{lstlisting} |
|
1176 |
||
1177 |
\begin{description} |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1178 |
\item[\linenum{1} -- \linenum{2}] To |
369 | 1179 |
comply to the requirements for parameters of EtherCAT device modules |
1180 |
described in section~\ref{sec:seldev}, there have to be additional |
|
1181 |
parameter variables: \textit{ec\_\-device\_\-index} holds the index |
|
1182 |
of the EtherCAT device and defaults to $-1$ (no EtherCAT device), |
|
1183 |
while \textit{ec\_device\_master\_index} stores index of the master, |
|
1184 |
the single device will be connected to. Default: $0$ |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1185 |
\item[\linenum{3}] \textit{rtl\_ec\_dev} will be |
369 | 1186 |
the pointer to the later registered RealTek EtherCAT device, which |
1187 |
can be used as a parameter for device methods. |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1188 |
\item[\linenum{4}] \textit{rtl\_ec\_net\_dev} is |
369 | 1189 |
a pointer to the \textit{net\_device} structure of the dedicated |
1190 |
device and is set while scanning the PCI bus and finding the device |
|
1191 |
with the specified index. This is done inside the |
|
1192 |
\textit{pci\_module\_init()} function executed as the first thing on |
|
1193 |
module loading. |
|
1194 |
\end{description} |
|
1195 |
||
1196 |
\paragraph{Module Initialization} |
|
1197 |
||
1198 |
Below is the (shortened) coding of the device driver's module init |
|
1199 |
function: |
|
1200 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1201 |
\begin{lstlisting}[gobble=2,language=C,numbers=left] |
369 | 1202 |
static int __init rtl8139_init_module(void) |
1203 |
{ |
|
1204 |
if (pci_module_init(&rtl8139_pci_driver) < 0) { |
|
1205 |
printk(KERN_ERR "Failed to init PCI mod.\n"); |
|
1206 |
goto out_return; |
|
1207 |
} |
|
1208 |
||
1209 |
if (rtl_ec_net_dev) { |
|
1210 |
printk(KERN_INFO "Registering" |
|
1211 |
" EtherCAT device...\n"); |
|
1212 |
if (!(rtl_ec_dev = |
|
1213 |
ecdev_register(ec_device_master_index, |
|
1214 |
rtl_ec_net_dev, |
|
1215 |
rtl8139_interrupt, |
|
1216 |
THIS_MODULE))) { |
|
1217 |
printk(KERN_ERR "Failed to reg." |
|
1218 |
" EtherCAT device!\n"); |
|
1219 |
goto out_unreg_pci; |
|
1220 |
} |
|
1221 |
||
1222 |
printk(KERN_INFO "Starting EtherCAT" |
|
1223 |
" device...\n"); |
|
1224 |
if (ecdev_start(ec_device_master_index)) { |
|
1225 |
printk(KERN_ERR "Failed to start" |
|
1226 |
" EtherCAT device!\n"); |
|
1227 |
goto out_unreg_ec; |
|
1228 |
} |
|
1229 |
} else { |
|
1230 |
printk(KERN_WARNING "No EtherCAT device" |
|
1231 |
" registered!\n"); |
|
1232 |
} |
|
1233 |
||
1234 |
return 0; |
|
1235 |
||
1236 |
out_unreg_ec: |
|
1237 |
ecdev_unregister(ec_device_master_index, rtl_ec_dev); |
|
1238 |
out_unreg_pci: |
|
1239 |
pci_unregister_driver(&rtl8139_pci_driver); |
|
1240 |
out_return: |
|
1241 |
return -1; |
|
1242 |
} |
|
1243 |
\end{lstlisting} |
|
1244 |
||
1245 |
\begin{description} |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1246 |
\item[\linenum{3}] This call initializes all |
369 | 1247 |
RTL8139-compatible devices found on the pci bus. If a device with |
1248 |
index \textit{ec\_device\_index} is found, a pointer to its |
|
1249 |
\textit{net\_device} structure is stored in |
|
1250 |
\textit{rtl\_ec\_net\_dev} for later use (see next listings). |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1251 |
\item[\linenum{8}] If the specified device was |
369 | 1252 |
found, \textit{rtl\_ec\_net\_dev} is non-zero. |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1253 |
\item[\linenum{11}] The device is connected to |
369 | 1254 |
the specified master with a call to \textit{ecdev\_register()}. If |
1255 |
this fails, module loading is aborted. |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1256 |
\item[\linenum{23}] The device registration was |
369 | 1257 |
successful and the master is started. This can fail, which aborts |
1258 |
module loading. |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1259 |
\item[\linenum{29}] If no EtherCAT device was |
369 | 1260 |
found, a warning is output. |
1261 |
\end{description} |
|
1262 |
||
1263 |
\paragraph{Device Searching} |
|
1264 |
||
1265 |
During the PCI initialization phase, a variable \textit{board\_idx} is |
|
1266 |
increased for each RTL8139-compatible device found. The code below is |
|
1267 |
executed for each device: |
|
1268 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1269 |
\begin{lstlisting}[gobble=2,language=C,numbers=left] |
369 | 1270 |
if (board_idx == ec_device_index) { |
1271 |
rtl_ec_net_dev = dev; |
|
1272 |
strcpy(dev->name, "ec0"); |
|
1273 |
} |
|
1274 |
\end{lstlisting} |
|
1275 |
||
1276 |
\begin{description} |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1277 |
\item[\linenum{1}] The device with the specified |
369 | 1278 |
index will be the EtherCAT device. |
1279 |
\end{description} |
|
1280 |
||
1281 |
\paragraph{Avoiding Device Registration} |
|
1282 |
||
1283 |
Later in the PCI initialization phase, the net\_devices get |
|
1284 |
registered. This has to be avoided for EtherCAT devices and so this is |
|
1285 |
a typical example for an EtherCAT case differentiation: |
|
1286 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1287 |
\begin{lstlisting}[gobble=2,language=C,numbers=left] |
369 | 1288 |
if (dev != rtl_ec_net_dev) { |
1289 |
i = register_netdev(dev); |
|
1290 |
if (i) goto err_out; |
|
1291 |
} |
|
1292 |
\end{lstlisting} |
|
1293 |
||
1294 |
\begin{description} |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1295 |
\item[\linenum{1}] If the current net\_device is |
369 | 1296 |
not the EtherCAT device, it is registered at the network stack. |
1297 |
\end{description} |
|
1298 |
||
1299 |
\paragraph{Avoiding Interrupt Registration} |
|
1300 |
||
1301 |
In the next two listings, there is an interrupt requested and the |
|
1302 |
device's interrupts are enabled. This also has to be encapsulated by |
|
1303 |
if-clauses, because interrupt operation is not wanted for EtherCAT |
|
1304 |
devices. |
|
1305 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1306 |
\begin{lstlisting}[gobble=2,language=C,numbers=left] |
369 | 1307 |
if (dev != rtl_ec_net_dev) { |
1308 |
retval = request_irq(dev->irq, rtl8139_interrupt, |
|
1309 |
SA_SHIRQ, dev->name, dev); |
|
1310 |
if (retval) return retval; |
|
1311 |
} |
|
1312 |
\end{lstlisting} |
|
1313 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1314 |
\begin{lstlisting}[gobble=2,language=C,numbers=left] |
369 | 1315 |
if (dev != rtl_ec_net_dev) { |
1316 |
/* Enable all known interrupts by setting |
|
1317 |
the interrupt mask. */ |
|
1318 |
RTL_W16(IntrMask, rtl8139_intr_mask); |
|
1319 |
} |
|
1320 |
\end{lstlisting} |
|
1321 |
||
1322 |
\paragraph{Frame Sending} |
|
1323 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1324 |
The listing below shows an excerpt of the function representing the |
369 | 1325 |
\textit{hard\_start\_xmit()} callback of the net\_device. |
1326 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1327 |
\begin{lstlisting}[gobble=2,language=C,numbers=left] |
369 | 1328 |
/* Note: the chip doesn't have auto-pad! */ |
1329 |
if (likely(len < TX_BUF_SIZE)) { |
|
1330 |
if (len < ETH_ZLEN) |
|
1331 |
memset(tp->tx_buf[entry], 0, ETH_ZLEN); |
|
1332 |
skb_copy_and_csum_dev(skb, tp->tx_buf[entry]); |
|
1333 |
if (dev != rtl_ec_net_dev) { |
|
1334 |
dev_kfree_skb(skb); |
|
1335 |
} |
|
1336 |
} else { |
|
1337 |
if (dev != rtl_ec_net_dev) { |
|
1338 |
dev_kfree_skb(skb); |
|
1339 |
} |
|
1340 |
tp->stats.tx_dropped++; |
|
1341 |
return 0; |
|
1342 |
} |
|
1343 |
\end{lstlisting} |
|
1344 |
||
1345 |
\begin{description} |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1346 |
\item[\linenum{6} + \linenum{10}] The |
369 | 1347 |
master uses a fixed socket buffer for transmission, which is reused |
1348 |
and may not be freed. |
|
1349 |
\end{description} |
|
1350 |
||
1351 |
\paragraph{Frame Receiving} |
|
1352 |
||
1353 |
During ordinary frame reception, a socket buffer is created and filled |
|
1354 |
with the received data. This is not necessary for an EtherCAT device: |
|
1355 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1356 |
\begin{lstlisting}[gobble=2,language=C,numbers=left] |
369 | 1357 |
if (dev != rtl_ec_net_dev) { |
1358 |
/* Malloc up new buffer, compatible with net-2e. */ |
|
1359 |
/* Omit the four octet CRC from the length. */ |
|
1360 |
||
1361 |
skb = dev_alloc_skb (pkt_size + 2); |
|
1362 |
if (likely(skb)) { |
|
1363 |
skb->dev = dev; |
|
1364 |
skb_reserve(skb, 2); /* 16 byte align |
|
1365 |
the IP fields. */ |
|
1366 |
eth_copy_and_sum(skb, &rx_ring[ring_off + 4], |
|
1367 |
pkt_size, 0); |
|
1368 |
skb_put(skb, pkt_size); |
|
1369 |
skb->protocol = eth_type_trans(skb, dev); |
|
1370 |
||
1371 |
dev->last_rx = jiffies; |
|
1372 |
tp->stats.rx_bytes += pkt_size; |
|
1373 |
tp->stats.rx_packets++; |
|
1374 |
||
1375 |
netif_receive_skb (skb); |
|
1376 |
} else { |
|
1377 |
if (net_ratelimit()) |
|
1378 |
printk(KERN_WARNING |
|
1379 |
"%s: Memory squeeze, dropping" |
|
1380 |
" packet.\n", dev->name); |
|
1381 |
tp->stats.rx_dropped++; |
|
1382 |
} |
|
1383 |
} else { |
|
1384 |
ecdev_receive(rtl_ec_dev, |
|
1385 |
&rx_ring[ring_offset + 4], pkt_size); |
|
1386 |
dev->last_rx = jiffies; |
|
1387 |
tp->stats.rx_bytes += pkt_size; |
|
1388 |
tp->stats.rx_packets++; |
|
1389 |
} |
|
1390 |
\end{lstlisting} |
|
1391 |
||
1392 |
\begin{description} |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1393 |
\item[\linenum{28}] If the device is an EtherCAT |
369 | 1394 |
device, no socket buffer is allocated. Instead a pointer to the data |
1395 |
(which is still in the device's receive ring) is passed to the |
|
1396 |
EtherCAT master. Unnecessary copy operations are avoided. |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1397 |
\item[\linenum{30} -- \linenum{32}] The |
369 | 1398 |
device's statistics are updated as usual. |
1399 |
\end{description} |
|
1400 |
||
1401 |
\paragraph{Link State} |
|
1402 |
||
1403 |
The link state (i.~e. if there is a carrier signal detected on the |
|
1404 |
receive port) is determined during execution of the ISR. The listing |
|
1405 |
below shows the different processing for Ethernet and EtherCAT |
|
1406 |
devices: |
|
1407 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1408 |
\begin{lstlisting}[gobble=2,language=C,numbers=left] |
369 | 1409 |
if (dev != rtl_ec_net_dev) { |
1410 |
if (tp->phys[0] >= 0) { |
|
1411 |
mii_check_media(&tp->mii, netif_msg_link(tp), |
|
1412 |
init_media); |
|
1413 |
} |
|
1414 |
} else { |
|
1415 |
void __iomem *ioaddr = tp->mmio_addr; |
|
1416 |
uint16_t link = RTL_R16(BasicModeStatus) |
|
1417 |
& BMSR_LSTATUS; |
|
1418 |
ecdev_link_state(rtl_ec_dev, link ? 1 : 0); |
|
1419 |
} |
|
1420 |
\end{lstlisting} |
|
1421 |
||
1422 |
\begin{description} |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1423 |
\item[\linenum{3}] The ``media check'' is done |
369 | 1424 |
via the media independent interface (MII\nomenclature{MII}{Media |
1425 |
Independent Interface}), a standard interface for Fast Ethernet |
|
1426 |
devices. |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1427 |
\item[\linenum{7} -- \linenum{10}] For |
369 | 1428 |
EtherCAT devices, the link state is fetched manually from the |
1429 |
appropriate device register, and passed to the EtherCAT master by |
|
1430 |
calling \textit{ecdev\_\-link\_\-state()}. |
|
1431 |
\end{description} |
|
1432 |
||
1433 |
\paragraph{Module Cleanup} |
|
1434 |
||
1435 |
Below is the module's cleanup function: |
|
1436 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1437 |
\begin{lstlisting}[gobble=2,language=C,numbers=left] |
369 | 1438 |
static void __exit rtl8139_cleanup_module (void) |
1439 |
{ |
|
1440 |
printk(KERN_INFO "Cleaning up RTL8139-EtherCAT" |
|
1441 |
" module...\n"); |
|
1442 |
||
1443 |
if (rtl_ec_net_dev) { |
|
1444 |
printk(KERN_INFO "Stopping device...\n"); |
|
1445 |
ecdev_stop(ec_device_master_index); |
|
1446 |
printk(KERN_INFO "Unregistering device...\n"); |
|
1447 |
ecdev_unregister(ec_device_master_index, |
|
1448 |
rtl_ec_dev); |
|
1449 |
rtl_ec_dev = NULL; |
|
1450 |
} |
|
1451 |
||
1452 |
pci_unregister_driver(&rtl8139_pci_driver); |
|
1453 |
||
1454 |
printk(KERN_INFO "RTL8139-EtherCAT module" |
|
1455 |
" cleaned up.\n"); |
|
1456 |
} |
|
1457 |
\end{lstlisting} |
|
1458 |
||
1459 |
\begin{description} |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1460 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1461 |
\item[\linenum{6}] Stopping and deregistration is only done, if a device was |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1462 |
registered before. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1463 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1464 |
\item[\linenum{8}] The master is first stopped, so it does not access the |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1465 |
device any more. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1466 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1467 |
\item[\linenum{10}] After this, the device is unregistered. The master is now |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1468 |
``orphaned''. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1469 |
|
369 | 1470 |
\end{description} |
1471 |
||
1472 |
%------------------------------------------------------------------------------ |
|
1473 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1474 |
\chapter{State Machines} |
369 | 1475 |
\label{sec:fsm} |
1476 |
\index{FSM} |
|
1477 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1478 |
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
|
1479 |
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
|
1480 |
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
|
1481 |
possibilities. |
369 | 1482 |
|
1483 |
The below short code example exemplary shows how to read all slave |
|
1484 |
states and moreover illustrates the restrictions of ``sequential'' |
|
1485 |
coding: |
|
1486 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1487 |
\begin{lstlisting}[gobble=2,language=C,numbers=left] |
369 | 1488 |
ec_datagram_brd(datagram, 0x0130, 2); // prepare datagram |
1489 |
if (ec_master_simple_io(master, datagram)) return -1; |
|
1490 |
slave_states = EC_READ_U8(datagram->data); // process datagram |
|
1491 |
\end{lstlisting} |
|
1492 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1493 |
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
|
1494 |
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
|
1495 |
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
|
1496 |
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
|
1497 |
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
|
1498 |
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
|
1499 |
a frame with the queued datagram and then waits actively for its reception. |
369 | 1500 |
|
1501 |
This sequential approach is very simple, reflecting in only three |
|
1502 |
lines of code. The disadvantage is, that the master is blocked for the |
|
1503 |
time it waits for datagram reception. There is no difficulty when only |
|
1504 |
one instance is using the master, but if more instances want to |
|
1505 |
(synchronously\footnote{At this time, synchronous master access will |
|
1506 |
be adequate to show the advantages of an FSM. The asynchronous |
|
1507 |
approach will be discussed in section~\ref{sec:eoeimp}}) use the |
|
1508 |
master, it is inevitable to think about an alternative to the |
|
1509 |
sequential model. |
|
1510 |
||
1511 |
Master access has to be sequentialized for more than one instance |
|
1512 |
wanting to send and receive datagrams synchronously. With the present |
|
1513 |
approach, this would result in having one phase of active waiting for |
|
1514 |
each instance, which would be non-acceptable especially in realtime |
|
1515 |
circumstances, because of the huge time overhead. |
|
1516 |
||
1517 |
A possible solution is, that all instances would be executed |
|
1518 |
sequentially to queue their datagrams, then give the control to the |
|
1519 |
next instance instead of waiting for the datagram reception. Finally, |
|
1520 |
bus IO is done by a higher instance, which means that all queued |
|
1521 |
datagrams are sent and received. The next step is to execute all |
|
1522 |
instances again, which then process their received datagrams and issue |
|
1523 |
new ones. |
|
1524 |
||
1525 |
This approach results in all instances having to retain their state, |
|
1526 |
when giving the control back to the higher instance. It is quite |
|
1527 |
obvious to use a \textit{finite state machine} model in this case. |
|
1528 |
Section~\ref{sec:fsmtheory} will introduce some of the theory used, |
|
1529 |
while the listings below show the basic approach by coding the example |
|
1530 |
from above as a state machine: |
|
1531 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1532 |
\begin{lstlisting}[gobble=2,language=C,numbers=left] |
369 | 1533 |
// state 1 |
1534 |
ec_datagram_brd(datagram, 0x0130, 2); // prepare datagram |
|
1535 |
ec_master_queue(master, datagram); // queue datagram |
|
1536 |
next_state = state_2; |
|
1537 |
// state processing finished |
|
1538 |
\end{lstlisting} |
|
1539 |
||
1540 |
After all instances executed their current state and queued their |
|
1541 |
datagrams, these are sent and received. Then the respective next |
|
1542 |
states are executed: |
|
1543 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1544 |
\begin{lstlisting}[gobble=2,language=C,numbers=left] |
369 | 1545 |
// state 2 |
1546 |
if (datagram->state != EC_DGRAM_STATE_RECEIVED) { |
|
1547 |
next_state = state_error; |
|
1548 |
return; // state processing finished |
|
1549 |
} |
|
1550 |
slave_states = EC_READ_U8(datagram->data); // process datagram |
|
1551 |
// state processing finished. |
|
1552 |
\end{lstlisting} |
|
1553 |
||
1554 |
See section~\ref{sec:statemodel} for an introduction to the |
|
1555 |
state machine programming concept used in the master code. |
|
1556 |
||
1557 |
%------------------------------------------------------------------------------ |
|
1558 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1559 |
\section{State Machine Theory} |
369 | 1560 |
\label{sec:fsmtheory} |
1561 |
\index{FSM!Theory} |
|
1562 |
||
1563 |
A finite state machine \cite{automata} is a model of behavior with |
|
1564 |
inputs and outputs, where the outputs not only depend on the inputs, |
|
1565 |
but the history of inputs. The mathematical definition of a finite |
|
1566 |
state machine (or finite automaton) is a six-tuple $(\Sigma, \Gamma, |
|
1567 |
S, s_0, \delta, \omega)$, with |
|
1568 |
||
1569 |
\begin{itemize} |
|
1570 |
\item the input alphabet $\Sigma$, with $\Sigma \neq |
|
1571 |
\emptyset$, containing all input symbols, |
|
1572 |
\item the output alphabet $\Gamma$, with $\Gamma \neq |
|
1573 |
\emptyset$, containing all output symbols, |
|
1574 |
\item the set of states $S$, with $S \neq \emptyset$, |
|
1575 |
\item the set of initial states $s_0$ with $s_0 \subseteq S, s_0 \neq |
|
1576 |
\emptyset$ |
|
1577 |
\item the transition function $\delta: S \times \Sigma \rightarrow S |
|
1578 |
\times \Gamma$ |
|
1579 |
\item the output function $\omega$. |
|
1580 |
\end{itemize} |
|
1581 |
||
1582 |
The state transition function $\delta$ is often specified by a |
|
1583 |
\textit{state transition table}, or by a \textit{state transition |
|
1584 |
diagram}. The transition table offers a matrix view of the state |
|
1585 |
machine behavior (see table~\ref{tab:statetrans}). The matrix rows |
|
1586 |
correspond to the states ($S = \{s_0, s_1, s_2\}$) and the columns |
|
1587 |
correspond to the input symbols ($\Gamma = \{a, b, \varepsilon\}$). |
|
1588 |
The table contents in a certain row $i$ and column $j$ then represent |
|
1589 |
the next state (and possibly the output) for the case, that a certain |
|
1590 |
input symbol $\sigma_j$ is read in the state $s_i$. |
|
1591 |
||
1592 |
\begin{table}[htbp] |
|
1593 |
\caption{A typical state transition table} |
|
1594 |
\label{tab:statetrans} |
|
1595 |
\vspace{2mm} |
|
1596 |
\centering |
|
1597 |
\begin{tabular}{l|ccc} |
|
1598 |
& $a$ & $b$ & $\varepsilon$\\ \hline |
|
1599 |
$s_0$ & $s_1$ & $s_1$ & $s_2$\\ |
|
1600 |
$s_1$ & $s_2$ & $s_1$ & $s_0$\\ |
|
1601 |
$s_2$ & $s_0$ & $s_0$ & $s_0$\\ \hline |
|
1602 |
\end{tabular} |
|
1603 |
\end{table} |
|
1604 |
||
1605 |
The state diagram for the same example looks like the one in |
|
1606 |
figure~\ref{fig:statetrans}. The states are represented as circles or |
|
1607 |
ellipses and the transitions are drawn as arrows between them. Close |
|
1608 |
to a transition arrow can be the condition that must be fulfilled to |
|
1609 |
allow the transition. The initial state is marked by a filled black |
|
1610 |
circle with an arrow pointing to the respective state. |
|
1611 |
||
1612 |
\begin{figure}[htbp] |
|
1613 |
\centering |
|
1614 |
\includegraphics[width=.5\textwidth]{images/statetrans} |
|
1615 |
\caption{A typical state transition diagram} |
|
1616 |
\label{fig:statetrans} |
|
1617 |
\end{figure} |
|
1618 |
||
1619 |
\paragraph{Deterministic and non-deterministic state machines} |
|
1620 |
||
1621 |
A state machine can be deterministic, meaning that for one state and |
|
1622 |
input, there is one (and only one) following state. In this case, the |
|
1623 |
state machine has exactly one starting state. Non-deterministic state |
|
1624 |
machines can have more than one transitions for a single state-input |
|
1625 |
combination. There is a set of starting states in the latter case. |
|
1626 |
||
1627 |
\paragraph{Moore and Mealy machines} |
|
1628 |
||
1629 |
There is a distinction between so-called \textit{Moore machines}, and |
|
1630 |
\textit{Mealy machines}. Mathematically spoken, the distinction lies |
|
1631 |
in the output function $\omega$: If it only depends on the current |
|
1632 |
state ($\omega: S \rightarrow \Gamma$), the machine corresponds to the |
|
1633 |
``Moore Model''. Otherwise, if $\omega$ is a function of a state and |
|
1634 |
the input alphabet ($\omega: S \times \Sigma \rightarrow \Gamma$) the |
|
1635 |
state machine corresponds to the ``Mealy model''. Mealy machines are |
|
1636 |
the more practical solution in most cases, because their design allows |
|
1637 |
machines with a minimum number of states. In practice, a mixture of |
|
1638 |
both models is often used. |
|
1639 |
||
1640 |
\paragraph{Misunderstandings about state machines} |
|
1641 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1642 |
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
|
1643 |
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
|
1644 |
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
|
1645 |
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
|
1646 |
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
|
1647 |
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
|
1648 |
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
|
1649 |
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
|
1650 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1651 |
%------------------------------------------------------------------------------ |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1652 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1653 |
\section{The Master's State Model} |
369 | 1654 |
\label{sec:statemodel} |
1655 |
||
1656 |
This section will introduce the techniques used in the master to |
|
1657 |
implement state machines. |
|
1658 |
||
1659 |
\paragraph{State Machine Programming} |
|
1660 |
||
1661 |
There are certain ways to implement a state machine in \textit{C} |
|
1662 |
code. An obvious way is to implement the different states and actions |
|
1663 |
by one big case differentiation: |
|
1664 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1665 |
\begin{lstlisting}[gobble=2,language=C,numbers=left] |
369 | 1666 |
enum {STATE_1, STATE_2, STATE_3}; |
1667 |
int state = STATE_1; |
|
1668 |
||
1669 |
void state_machine_run(void *priv_data) { |
|
1670 |
switch (state) { |
|
1671 |
case STATE_1: |
|
1672 |
action_1(); |
|
1673 |
state = STATE_2; |
|
1674 |
break; |
|
1675 |
case STATE_2: |
|
1676 |
action_2() |
|
1677 |
if (some_condition) state = STATE_1; |
|
1678 |
else state = STATE_3; |
|
1679 |
break; |
|
1680 |
case STATE_3: |
|
1681 |
action_3(); |
|
1682 |
state = STATE_1; |
|
1683 |
break; |
|
1684 |
} |
|
1685 |
} |
|
1686 |
\end{lstlisting} |
|
1687 |
||
1688 |
For small state machines, this is an option. The disadvantage is, that |
|
1689 |
with an increasing number of states the code soon gets complex and an |
|
1690 |
additional case differentiation is executed each run. Besides, lots of |
|
1691 |
indentation is wasted. |
|
1692 |
||
1693 |
The method used in the master is to implement every state in an own |
|
1694 |
function and to store the current state function with a function |
|
1695 |
pointer: |
|
1696 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1697 |
\begin{lstlisting}[gobble=2,language=C,numbers=left] |
369 | 1698 |
void (*state)(void *) = state1; |
1699 |
||
1700 |
void state_machine_run(void *priv_data) { |
|
1701 |
state(priv_data); |
|
1702 |
} |
|
1703 |
||
1704 |
void state1(void *priv_data) { |
|
1705 |
action_1(); |
|
1706 |
state = state2; |
|
1707 |
} |
|
1708 |
||
1709 |
void state2(void *priv_data) { |
|
1710 |
action_2(); |
|
1711 |
if (some_condition) state = state1; |
|
1712 |
else state = state2; |
|
1713 |
} |
|
1714 |
||
1715 |
void state3(void *priv_data) { |
|
1716 |
action_3(); |
|
1717 |
state = state1; |
|
1718 |
} |
|
1719 |
\end{lstlisting} |
|
1720 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1721 |
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
|
1722 |
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
|
1723 |
parallel. For this reason each EoE handler object has its own state pointer.} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1724 |
are gathered in a single object of the \textit{ec\_fsm\_t} class. This is |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1725 |
advantageous, because there is always one instance of every state machine |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1726 |
available and can be started on demand. |
369 | 1727 |
|
1728 |
\paragraph{Mealy and Moore} |
|
1729 |
||
1730 |
If a closer look is taken to the above listing, it can be seen that |
|
1731 |
the actions executed (the ``outputs'' of the state machine) only |
|
1732 |
depend on the current state. This accords to the ``Moore'' model |
|
1733 |
introduced in section~\ref{sec:fsmtheory}. As mentioned, the ``Mealy'' |
|
1734 |
model offers a higher flexibility, which can be seen in the listing |
|
1735 |
below: |
|
1736 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1737 |
\begin{lstlisting}[gobble=2,language=C,numbers=left] |
369 | 1738 |
void state7(void *priv_data) { |
1739 |
if (some_condition) { |
|
1740 |
action_7a(); |
|
1741 |
state = state1; |
|
1742 |
} |
|
1743 |
else { |
|
1744 |
action_7b(); |
|
1745 |
state = state8; |
|
1746 |
} |
|
1747 |
} |
|
1748 |
\end{lstlisting} |
|
1749 |
||
1750 |
\begin{description} |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1751 |
\item[\linenum{3} + \linenum{7}] The |
369 | 1752 |
state function executes the actions depending on the state |
1753 |
transition, that is about to be done. |
|
1754 |
\end{description} |
|
1755 |
||
1756 |
The most flexible alternative is to execute certain actions depending |
|
1757 |
on the state, followed by some actions dependent on the state |
|
1758 |
transition: |
|
1759 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1760 |
\begin{lstlisting}[gobble=2,language=C,numbers=left] |
369 | 1761 |
void state9(void *priv_data) { |
1762 |
action_9(); |
|
1763 |
if (some_condition) { |
|
1764 |
action_9a(); |
|
1765 |
state = state7; |
|
1766 |
} |
|
1767 |
else { |
|
1768 |
action_9b(); |
|
1769 |
state = state10; |
|
1770 |
} |
|
1771 |
} |
|
1772 |
\end{lstlisting} |
|
1773 |
||
1774 |
This model is oftenly used in the master. It combines the best aspects |
|
1775 |
of both approaches. |
|
1776 |
||
1777 |
\paragraph{Using Sub State Machines} |
|
1778 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1779 |
To avoid having too much states, certain functions of the EtherCAT master state |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1780 |
machine have been sourced out into sub state machines. This helps to |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1781 |
encapsulate the related workflows and moreover avoids the ``state explosion'' |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1782 |
phenomenon described in section~\ref{sec:fsmtheory}. If the master would |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1783 |
instead use one big state machine, the number of states would be a multiple of |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1784 |
the actual number. This would increase the level of complexity to a |
369 | 1785 |
non-manageable grade. |
1786 |
||
1787 |
\paragraph{Executing Sub State Machines} |
|
1788 |
||
1789 |
If a state machine starts to execute a sub state machine, it usually |
|
1790 |
remains in one state until the sub state machine terminates. This is |
|
1791 |
usually done like in the listing below, which is taken out of the |
|
1792 |
slave configuration state machine code: |
|
1793 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1794 |
\begin{lstlisting}[gobble=2,language=C,numbers=left] |
813
bfc3f1ab52de
Fixed typo SAVEOP -> SAFEOP.
Florian Pose <fp@igh-essen.com>
parents:
487
diff
changeset
|
1795 |
void ec_fsm_slaveconf_safeop(ec_fsm_t *fsm) |
369 | 1796 |
{ |
1797 |
fsm->change_state(fsm); // execute state change |
|
1798 |
// sub state machine |
|
1799 |
||
1800 |
if (fsm->change_state == ec_fsm_error) { |
|
1801 |
fsm->slave_state = ec_fsm_end; |
|
1802 |
return; |
|
1803 |
} |
|
1804 |
||
1805 |
if (fsm->change_state != ec_fsm_end) return; |
|
1806 |
||
1807 |
// continue state processing |
|
1808 |
... |
|
1809 |
\end{lstlisting} |
|
1810 |
||
1811 |
\begin{description} |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1812 |
\item[\linenum{3}] \textit{change\_state} is the |
369 | 1813 |
state pointer of the state change state machine. The state function, |
1814 |
the pointer points on, is executed\ldots |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1815 |
\item[\linenum{6}] \ldots either until the state |
369 | 1816 |
machine terminates with the error state \ldots |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1817 |
\item[\linenum{11}] \ldots or until the state |
369 | 1818 |
machine terminates in the end state. Until then, the ``higher'' |
1819 |
state machine remains in the current state and executes the sub |
|
1820 |
state machine again in the next cycle. |
|
1821 |
\end{description} |
|
1822 |
||
1823 |
\paragraph{State Machine Descriptions} |
|
1824 |
||
1825 |
The below sections describe every state machine used in the EtherCAT |
|
1826 |
master. The textual descriptions of the state machines contain |
|
1827 |
references to the transitions in the corresponding state transition |
|
1828 |
diagrams, that are marked with an arrow followed by the name of the |
|
1829 |
successive state. Transitions caused by trivial error cases (i.~e. no |
|
1830 |
response from slave) are not described explicitly. These transitions |
|
1831 |
are drawn as dashed arrows in the diagrams. |
|
1832 |
||
1833 |
%------------------------------------------------------------------------------ |
|
1834 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1835 |
\section{The Operation State Machine} |
369 | 1836 |
\label{sec:fsm-op} |
1837 |
\index{FSM!Operation} |
|
1838 |
||
1839 |
The Operation state machine is executed by calling the |
|
1840 |
\textit{ecrt\_master\_run()} method in cyclic realtime code. Its |
|
1841 |
purpose is to monitor the bus and to reconfigure slaves after a bus |
|
1842 |
failure or power failure. Figure~\ref{fig:fsm-op} shows its transition |
|
1843 |
diagram. |
|
1844 |
||
1845 |
\begin{figure}[htbp] |
|
1846 |
\centering |
|
1847 |
\includegraphics[width=.8\textwidth]{images/fsm-op} |
|
1848 |
\caption{Transition diagram of the operation state machine} |
|
1849 |
\label{fig:fsm-op} |
|
1850 |
\end{figure} |
|
1851 |
||
1852 |
\begin{description} |
|
1853 |
\item[START] This is the beginning state of the operation state |
|
1854 |
machine. There is a datagram issued, that queries the ``AL Control |
|
1855 |
Response'' attribute \cite[section~5.3.2]{alspec} of all slaves via |
|
1856 |
broadcast. In this way, all slave states and the number of slaves |
|
379 | 1857 |
responding can be determined. $\rightarrow$~BROADCAST |
369 | 1858 |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1859 |
\item[BROADCAST] The broadcast datagram is evaluated. A change in the number of |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1860 |
responding slaves is treated as a topology change. If the number of slaves is |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1861 |
not as expected, the bus is marked as ``tainted''. In this state, no slave |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1862 |
reconfiguration is possible, because the assignment of known slaves and those |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1863 |
present on the bus is ambiguous. If the number of slaves is considered as |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1864 |
right, the bus is marked for validation, because it turned from tainted to |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1865 |
normal state and it has to be checked, if all slaves are valid. Now, the state |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1866 |
of every single slave has to be determined. For that, a (unicast) datagram is |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1867 |
issued, that queries the first slave's ``AL Control Response'' attribute. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1868 |
$\rightarrow$~READ STATES |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1869 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1870 |
\item[READ STATES] If the current slave did not respond to its configured |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1871 |
station address, it is marked as offline, and the next slave is queried. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1872 |
$\rightarrow$~READ STATES |
369 | 1873 |
|
1874 |
If the slave responded, it is marked as online and its current state |
|
379 | 1875 |
is stored. The next slave is queried. $\rightarrow$~READ STATES |
369 | 1876 |
|
1877 |
If all slaves have been queried, and the bus is marked for |
|
1878 |
validation, the validation is started by checking the first slaves |
|
379 | 1879 |
vendor ID. $\rightarrow$~VALIDATE VENDOR |
369 | 1880 |
|
1881 |
If no validation has to be done, it is checked, if all slaves are in |
|
1882 |
the state they are supposed to be. If not, the first of slave with |
|
1883 |
the wrong state is reconfigured and brought in the required state. |
|
379 | 1884 |
$\rightarrow$~CONFIGURE SLAVES |
369 | 1885 |
|
1886 |
If all slaves are in the correct state, the state machine is |
|
379 | 1887 |
restarted. $\rightarrow$~START |
369 | 1888 |
|
1889 |
\item[CONFIGURE SLAVES] The slave configuration state machine is |
|
379 | 1890 |
executed until termination. $\rightarrow$~CONFIGURE SLAVES |
369 | 1891 |
|
1892 |
If there are still slaves in the wrong state after another check, |
|
1893 |
the first of these slaves is configured and brought into the correct |
|
379 | 1894 |
state again. $\rightarrow$~CONFIGURE SLAVES |
369 | 1895 |
|
1896 |
If all slaves are in the correct state, the state machine is |
|
379 | 1897 |
restarted. $\rightarrow$~START |
369 | 1898 |
|
1899 |
\item[VALIDATE VENDOR] The SII state machine is executed until |
|
1900 |
termination. If the slave has the wrong vendor ID, the state machine |
|
379 | 1901 |
is restarted. $\rightarrow$~START |
369 | 1902 |
|
1903 |
If the slave has the correct vendor ID, its product ID is queried. |
|
379 | 1904 |
$\rightarrow$~VALIDATE PRODUCT |
369 | 1905 |
|
1906 |
\item[VALIDATE PRODUCT] The SII state machine is executed until |
|
1907 |
termination. If the slave has the wrong product ID, the state |
|
379 | 1908 |
machine is restarted. $\rightarrow$~START |
369 | 1909 |
|
1910 |
If the slave has the correct product ID, the next slave's vendor ID |
|
379 | 1911 |
is queried. $\rightarrow$~VALIDATE VENDOR |
369 | 1912 |
|
1913 |
If all slaves have the correct vendor IDs and product codes, the |
|
1914 |
configured station addresses can be safely rewritten. This is done |
|
1915 |
for the first slave marked as offline. |
|
379 | 1916 |
$\rightarrow$~REWRITE ADDRESSES |
369 | 1917 |
|
1095 | 1918 |
\item[REWRITE ADDRESSES] If the station address was successfully written, it is |
1919 |
searched for the next slave marked as offline. If there is one, its address is |
|
1920 |
reconfigured, too. $\rightarrow$~REWRITE ADDRESSES |
|
369 | 1921 |
|
1922 |
If there are no more slaves marked as offline, the state machine is |
|
379 | 1923 |
restarted. $\rightarrow$~START |
369 | 1924 |
\end{description} |
1925 |
||
1926 |
%------------------------------------------------------------------------------ |
|
1927 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1928 |
\section{The Idle State Machine} |
369 | 1929 |
\label{sec:fsm-idle} |
1930 |
\index{FSM!Idle} |
|
1931 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1932 |
The Idle state machine is executed by a kernel thread, if no application is |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1933 |
connected. Its purpose is to make slave information available to user space, |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1934 |
operate EoE-capable slaves, read and write SII contents and test slave |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
1935 |
functionality. Figure~\ref{fig:fsm-idle} shows its transition diagram. |
369 | 1936 |
|
1937 |
\begin{figure}[htbp] |
|
1938 |
\centering |
|
1939 |
\includegraphics[width=.8\textwidth]{images/fsm-idle} |
|
1940 |
\caption{Transition diagram of the idle state machine} |
|
1941 |
\label{fig:fsm-idle} |
|
1942 |
\end{figure} |
|
1943 |
||
1944 |
\begin{description} |
|
1945 |
\item[START] The beginning state of the idle state machine. Similar to |
|
1946 |
the operation state machine, a broadcast datagram is issued, to |
|
1947 |
query all slave states and the number of slaves. |
|
379 | 1948 |
$\rightarrow$~BROADCAST |
369 | 1949 |
|
1950 |
\item[BROADCAST] The number of responding slaves is evaluated. If it |
|
1951 |
has changed since the last time, this is treated as a topology |
|
1952 |
change and the internal list of slaves is cleared and rebuild |
|
1953 |
completely. The slave scan state machine is started for the first |
|
379 | 1954 |
slave. $\rightarrow$~SCAN FOR SLAVES |
369 | 1955 |
|
1956 |
If no topology change happened, every single slave state is fetched. |
|
379 | 1957 |
$\rightarrow$~READ STATES |
369 | 1958 |
|
1959 |
\item[SCAN FOR SLAVES] The slave scan state machine is executed until |
|
379 | 1960 |
termination. $\rightarrow$~SCAN FOR SLAVES |
369 | 1961 |
|
1962 |
If there is another slave to scan, the slave scan state machine is |
|
379 | 1963 |
started again. $\rightarrow$~SCAN FOR SLAVES |
369 | 1964 |
|
1965 |
If all slave information has been fetched, slave addresses are |
|
1966 |
calculated and EoE processing is started. Then, the state machine is |
|
379 | 1967 |
restarted. $\rightarrow$~START |
369 | 1968 |
|
1969 |
\item[READ STATES] If the slave did not respond to the query, it is |
|
1970 |
marked as offline. The next slave is queried. |
|
379 | 1971 |
$\rightarrow$~READ STATES |
369 | 1972 |
|
1973 |
If the slave responded, it is marked as online. And the next slave |
|
379 | 1974 |
is queried. $\rightarrow$~READ STATES |
369 | 1975 |
|
1976 |
If all slave states have been determined, it is checked, if any |
|
1977 |
slaves are not in the state they supposed to be. If this is true, |
|
1978 |
the slave configuration state machine is started for the first of |
|
379 | 1979 |
them. $\rightarrow$~CONFIGURE SLAVES |
369 | 1980 |
|
1981 |
If all slaves are in the correct state, it is checked, if any |
|
1982 |
E$^2$PROM write operations are pending. If this is true, the first |
|
1983 |
pending operation is executed by starting the SII state machine for |
|
379 | 1984 |
writing access. $\rightarrow$~WRITE EEPROM |
369 | 1985 |
|
1986 |
If all these conditions are false, there is nothing to do and the |
|
379 | 1987 |
state machine is restarted. $\rightarrow$~START |
369 | 1988 |
|
1989 |
\item[CONFIGURE SLAVES] The slave configuration state machine is |
|
379 | 1990 |
executed until termination. $\rightarrow$~CONFIGURE SLAVES |
369 | 1991 |
|
1992 |
After this, it is checked, if another slave needs a state change. If |
|
1993 |
this is true, the slave state change state machine is started for |
|
379 | 1994 |
this slave. $\rightarrow$~CONFIGURE SLAVES |
369 | 1995 |
|
1996 |
If all slaves are in the correct state, it is determined, if any |
|
1997 |
E$^2$PROM write operations are pending. If this is true, the first |
|
1998 |
pending operation is executed by starting the SII state machine for |
|
379 | 1999 |
writing access. $\rightarrow$~WRITE EEPROM |
369 | 2000 |
|
2001 |
If all prior conditions are false, the state machine is restarted. |
|
379 | 2002 |
$\rightarrow$~START |
369 | 2003 |
|
2004 |
\item[WRITE EEPROM] The SII state machine is executed until |
|
379 | 2005 |
termination. $\rightarrow$~WRITE EEPROM |
369 | 2006 |
|
2007 |
If the current word has been written successfully, and there are |
|
2008 |
still word to write, the SII state machine is started for the next |
|
379 | 2009 |
word. $\rightarrow$~WRITE EEPROM |
369 | 2010 |
|
2011 |
If all words have been written successfully, the new E$^2$PROM |
|
2012 |
contents are evaluated and the state machine is restarted. |
|
379 | 2013 |
$\rightarrow$~START |
369 | 2014 |
|
2015 |
\end{description} |
|
2016 |
||
2017 |
%------------------------------------------------------------------------------ |
|
2018 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2019 |
\section{The Slave Scan State Machine} |
369 | 2020 |
\label{sec:fsm-scan} |
2021 |
\index{FSM!Slave Scan} |
|
2022 |
||
2023 |
The slave scan state machine, which can be seen in |
|
2024 |
figure~\ref{fig:fsm-slavescan}, leads through the process of fetching |
|
2025 |
all slave information. |
|
2026 |
||
2027 |
\begin{figure}[htbp] |
|
2028 |
\centering |
|
2029 |
\includegraphics[width=.6\textwidth]{images/fsm-slavescan} |
|
2030 |
\caption{Transition diagram of the slave scan state machine} |
|
2031 |
\label{fig:fsm-slavescan} |
|
2032 |
\end{figure} |
|
2033 |
||
2034 |
\begin{description} |
|
2035 |
\item[START] In the beginning state of the slave scan state machine, |
|
2036 |
the station address is written to the slave, which is always the |
|
2037 |
ring position~+~$1$. In this way, the address 0x0000 (default |
|
2038 |
address) is not used, which makes it easy to detect unconfigured |
|
379 | 2039 |
slaves. $\rightarrow$~ADDRESS |
369 | 2040 |
|
2041 |
\item[ADDRESS] The writing of the station address is verified. After |
|
2042 |
that, the slave's ``AL Control Response'' attribute is queried. |
|
379 | 2043 |
$\rightarrow$~STATE |
369 | 2044 |
|
2045 |
\item[STATE] The AL state is evaluated. A warning is output, if the |
|
2046 |
slave has still the \textit{Change} bit set. After that, the slave's |
|
2047 |
``DL Information'' attribute is queried. |
|
379 | 2048 |
$\rightarrow$~BASE |
369 | 2049 |
|
2050 |
\item[BASE] The queried base data are evaluated: Slave type, revision |
|
2051 |
and build number, and even more important, the number of supported |
|
2052 |
sync managers and FMMUs are stored. After that, the slave's data |
|
2053 |
link layer information is read from the ``DL Status'' attribute at |
|
379 | 2054 |
address 0x0110. $\rightarrow$~DATALINK |
369 | 2055 |
|
2056 |
\item[DATALINK] In this state, the DL information is evaluated: This |
|
2057 |
information about the communication ports contains, if the link is |
|
2058 |
up, if the loop has been closed and if there is a carrier detected |
|
2059 |
on the RX side of each port. |
|
2060 |
||
2061 |
Then, the state machine starts measuring the size of the slave's |
|
2062 |
E$^2$PROM contents. This is done by subsequently reading out each |
|
2063 |
category header, until the last category is reached (type 0xFFFF). |
|
2064 |
This procedure is started by querying the first category header at |
|
2065 |
word address 0x0040 via the SII state machine. |
|
379 | 2066 |
$\rightarrow$~EEPROM SIZE |
369 | 2067 |
|
2068 |
\item[EEPROM SIZE] The SII state machine is executed until |
|
379 | 2069 |
termination. $\rightarrow$~EEPROM SIZE |
369 | 2070 |
|
2071 |
If the category type does not mark the end of the categories, the |
|
2072 |
position of the next category header is determined via the length of |
|
2073 |
the current category, and the SII state machine is started again. |
|
379 | 2074 |
$\rightarrow$~EEPROM SIZE |
369 | 2075 |
|
2076 |
If the size of the E$^2$PROM contents has been determined, memory is |
|
2077 |
allocated, to read all the contents. The SII state machine is |
|
379 | 2078 |
started to read the first word. $\rightarrow$~EEPROM DATA |
369 | 2079 |
|
2080 |
\item[EEPROM DATA] The SII state machine is executed until |
|
379 | 2081 |
termination. $\rightarrow$~EEPROM DATA |
369 | 2082 |
|
2083 |
Two words have been read. If more than one word is needed, the two |
|
2084 |
words are written in the allocated memory. Otherwise only one word |
|
2085 |
(the last word) is copied. If more words are to read, the SII state |
|
2086 |
machine is started again to read the next two words. |
|
379 | 2087 |
$\rightarrow$~EEPROM DATA |
369 | 2088 |
|
2089 |
The complete E$^2$PROM contents have been read. The slave's identity |
|
2090 |
object and mailbox information are evaluated. Moreover the category |
|
2091 |
types STRINGS, GENERAL, SYNC and PDO are evaluated. The slave |
|
379 | 2092 |
scanning has been completed. $\rightarrow$~END |
369 | 2093 |
|
2094 |
\item[END] Slave scanning has been finished. |
|
2095 |
||
2096 |
\end{description} |
|
2097 |
||
2098 |
%------------------------------------------------------------------------------ |
|
2099 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2100 |
\section{The Slave Configuration State Machine} |
369 | 2101 |
\label{sec:fsm-conf} |
2102 |
\index{FSM!Slave Configuration} |
|
2103 |
||
2104 |
The slave configuration state machine, which can be seen in |
|
2105 |
figure~\ref{fig:fsm-slaveconf}, leads through the process of |
|
2106 |
configuring a slave and bringing it to a certain state. |
|
2107 |
||
2108 |
\begin{figure}[htbp] |
|
2109 |
\centering |
|
2110 |
\includegraphics[width=.6\textwidth]{images/fsm-slaveconf} |
|
2111 |
\caption{Transition diagram of the slave configuration state |
|
2112 |
machine} |
|
2113 |
\label{fig:fsm-slaveconf} |
|
2114 |
\end{figure} |
|
2115 |
||
2116 |
\begin{description} |
|
2117 |
\item[INIT] The state change state machine has been initialized to |
|
379 | 2118 |
bring the slave into the INIT state. Now, the slave state change |
2119 |
state machine is executed until termination. $\rightarrow$~INIT |
|
369 | 2120 |
|
2121 |
If the slave state change failed, the configuration has to be |
|
379 | 2122 |
aborted. $\rightarrow$~END |
2123 |
||
2124 |
The slave state change succeeded and the slave is now in INIT state. |
|
2125 |
If this is the target state, the configuration is finished. |
|
2126 |
$\rightarrow$~END |
|
369 | 2127 |
|
2128 |
If the slave does not support any sync managers, the sync manager |
|
2129 |
configuration can be skipped. The state change state machine is |
|
379 | 2130 |
started to bring the slave into PREOP state. |
2131 |
$\rightarrow$~PREOP |
|
369 | 2132 |
|
2133 |
Sync managers are configured conforming to the sync manager category |
|
2134 |
information provided in the slave's E$^2$PROM. The corresponding |
|
379 | 2135 |
datagram is issued. $\rightarrow$~SYNC |
369 | 2136 |
|
2137 |
\item[SYNC] If the sync manager configuration datagram is accepted, |
|
2138 |
the sync manager configuration was successful. The slave may now |
|
379 | 2139 |
enter the PREOP state, and the state change state machine is |
2140 |
started. $\rightarrow$~PREOP |
|
369 | 2141 |
|
2142 |
\item[PREOP] The state change state machine is executed until |
|
379 | 2143 |
termination. $\rightarrow$~PREOP |
369 | 2144 |
|
2145 |
If the state change failed, the configuration has to be aborted. |
|
379 | 2146 |
$\rightarrow$~END |
2147 |
||
2148 |
If the PREOP state was the target state, the configuration is |
|
2149 |
finished. $\rightarrow$~END |
|
369 | 2150 |
|
2151 |
If the slave supports no FMMUs, the FMMU configuration can be |
|
814 | 2152 |
skipped. If the slave has Sdos to configure, it is begun with |
2153 |
sending the first Sdo. $\rightarrow$~SDO\_CONF |
|
2154 |
||
2155 |
If no Sdo configurations are provided, the slave can now directly be |
|
813
bfc3f1ab52de
Fixed typo SAVEOP -> SAFEOP.
Florian Pose <fp@igh-essen.com>
parents:
487
diff
changeset
|
2156 |
brought into the SAFEOP state and the state change state machine is |
bfc3f1ab52de
Fixed typo SAVEOP -> SAFEOP.
Florian Pose <fp@igh-essen.com>
parents:
487
diff
changeset
|
2157 |
started again. $\rightarrow$~SAFEOP |
369 | 2158 |
|
814 | 2159 |
Otherwise, all supported FMMUs are configured according to the Pdos |
369 | 2160 |
requested via the master's realtime interface. The appropriate |
379 | 2161 |
datagram is issued. $\rightarrow$~FMMU |
369 | 2162 |
|
2163 |
\item[FMMU] The FMMU configuration datagram was accepted. If the slave |
|
814 | 2164 |
has Sdos to configure, it is begun with sending the first Sdo. |
379 | 2165 |
$\rightarrow$~SDO\_CONF |
2166 |
||
813
bfc3f1ab52de
Fixed typo SAVEOP -> SAFEOP.
Florian Pose <fp@igh-essen.com>
parents:
487
diff
changeset
|
2167 |
Otherwise, the slave can now be brought into the SAFEOP state. The |
379 | 2168 |
state change state machine is started. |
813
bfc3f1ab52de
Fixed typo SAVEOP -> SAFEOP.
Florian Pose <fp@igh-essen.com>
parents:
487
diff
changeset
|
2169 |
$\rightarrow$~SAFEOP |
369 | 2170 |
|
2171 |
\item[SDO\_CONF] The CoE state machine is executed until termination. |
|
379 | 2172 |
$\rightarrow$~SDO\_CONF |
369 | 2173 |
|
814 | 2174 |
If another Sdo has to be configured, a new Sdo download sequence is |
379 | 2175 |
begun. $\rightarrow$~SDO\_CONF |
2176 |
||
813
bfc3f1ab52de
Fixed typo SAVEOP -> SAFEOP.
Florian Pose <fp@igh-essen.com>
parents:
487
diff
changeset
|
2177 |
Otherwise, the slave can now be brought into the SAFEOP state. The |
379 | 2178 |
state change state machine is started. |
813
bfc3f1ab52de
Fixed typo SAVEOP -> SAFEOP.
Florian Pose <fp@igh-essen.com>
parents:
487
diff
changeset
|
2179 |
$\rightarrow$~SAFEOP |
bfc3f1ab52de
Fixed typo SAVEOP -> SAFEOP.
Florian Pose <fp@igh-essen.com>
parents:
487
diff
changeset
|
2180 |
|
bfc3f1ab52de
Fixed typo SAVEOP -> SAFEOP.
Florian Pose <fp@igh-essen.com>
parents:
487
diff
changeset
|
2181 |
\item[SAFEOP] The state change state machine is executed until |
bfc3f1ab52de
Fixed typo SAVEOP -> SAFEOP.
Florian Pose <fp@igh-essen.com>
parents:
487
diff
changeset
|
2182 |
termination. $\rightarrow$~SAFEOP |
369 | 2183 |
|
2184 |
If the state change failed, the configuration has to be aborted. |
|
379 | 2185 |
$\rightarrow$~END |
2186 |
||
813
bfc3f1ab52de
Fixed typo SAVEOP -> SAFEOP.
Florian Pose <fp@igh-essen.com>
parents:
487
diff
changeset
|
2187 |
If the SAFEOP state was the target state, the configuration is |
379 | 2188 |
finished. $\rightarrow$~END |
2189 |
||
2190 |
The slave can now directly be brought into the OP state and the |
|
2191 |
state change state machine is started a last time. |
|
2192 |
$\rightarrow$~OP |
|
369 | 2193 |
|
2194 |
\item[OP] The state change state machine is executed until |
|
379 | 2195 |
termination. $\rightarrow$~OP |
369 | 2196 |
|
2197 |
If the state change state machine terminates, the slave |
|
2198 |
configuration is finished, regardless of its success. |
|
379 | 2199 |
$\rightarrow$~END |
369 | 2200 |
|
2201 |
\item[END] The termination state. |
|
2202 |
||
2203 |
\end{description} |
|
2204 |
||
2205 |
%------------------------------------------------------------------------------ |
|
2206 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2207 |
\section{The State Change State Machine} |
369 | 2208 |
\label{sec:fsm-change} |
2209 |
\index{FSM!State Change} |
|
2210 |
||
2211 |
The state change state machine, which can be seen in |
|
2212 |
figure~\ref{fig:fsm-change}, leads through the process of changing a |
|
2213 |
slave's state. This implements the states and transitions described in |
|
2214 |
\cite[section~6.4.1]{alspec}. |
|
2215 |
||
2216 |
\begin{figure}[htbp] |
|
2217 |
\centering |
|
2218 |
\includegraphics[width=.9\textwidth]{images/fsm-change} |
|
2219 |
\caption{Transition diagram of the state change state machine} |
|
2220 |
\label{fig:fsm-change} |
|
2221 |
\end{figure} |
|
2222 |
||
2223 |
\begin{description} |
|
2224 |
\item[START] The beginning state, where a datagram with the state |
|
2225 |
change command is written to the slave's ``AL Control Request'' |
|
379 | 2226 |
attribute. Nothing can fail. $\rightarrow$~CHECK |
369 | 2227 |
|
2228 |
\item[CHECK] After the state change datagram has been sent, the ``AL |
|
2229 |
Control Response'' attribute is queried with a second datagram. |
|
379 | 2230 |
$\rightarrow$~STATUS |
369 | 2231 |
|
2232 |
\item[STATUS] The read memory contents are evaluated: While the |
|
2233 |
parameter \textit{State} still contains the old slave state, the |
|
2234 |
slave is busy with reacting on the state change command. In this |
|
2235 |
case, the attribute has to be queried again. |
|
379 | 2236 |
$\rightarrow$~STATUS |
369 | 2237 |
|
2238 |
In case of success, the \textit{State} parameter contains the new |
|
2239 |
state and the \textit{Change} bit is cleared. The slave is in the |
|
379 | 2240 |
requested state. $\rightarrow$~END |
369 | 2241 |
|
2242 |
If the slave can not process the state change, the \textit{Change} |
|
2243 |
bit is set: Now the master tries to get the reason for this by |
|
2244 |
querying the \textit{AL Status Code} parameter. |
|
379 | 2245 |
$\rightarrow$~CODE |
369 | 2246 |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2247 |
\item[END] If the state machine ends in this state, the slave's state |
369 | 2248 |
change has been successful. |
2249 |
||
2250 |
\item[CODE] The status code query has been sent. Reading the |
|
2251 |
\textit{AL Status Code} might fail, because not all slaves support |
|
2252 |
this parameter. Anyway, the master has to acknowledge the state |
|
2253 |
change error by writing the current slave state to the ``AL Control |
|
2254 |
Request'' attribute with the \textit{Acknowledge} bit set. |
|
379 | 2255 |
$\rightarrow$~ACK |
369 | 2256 |
|
2257 |
\item[ACK] After that, the ``AL Control Response'' attribute is |
|
2258 |
queried for the state of the acknowledgement. |
|
379 | 2259 |
$\rightarrow$~CHECK ACK |
369 | 2260 |
|
2261 |
\item[CHECK ACK] If the acknowledgement has been accepted by the |
|
2262 |
slave, the old state is kept. Still, the state change was |
|
379 | 2263 |
unsuccessful. $\rightarrow$~ERROR |
369 | 2264 |
|
2265 |
If the acknowledgement is ignored by the slave, a timeout happens. |
|
2266 |
In any case, the overall state change was unsuccessful. |
|
379 | 2267 |
$\rightarrow$~ERROR |
369 | 2268 |
|
2269 |
If there is still now response from the slave, but the timer did not |
|
2270 |
run out yet, the slave's ``AL Control Response'' attribute is |
|
379 | 2271 |
queried again. $\rightarrow$~CHECK ACK |
369 | 2272 |
|
2273 |
\item[ERROR] If the state machine ends in this state, the slave's |
|
2274 |
state change was unsuccessful. |
|
2275 |
||
2276 |
\end{description} |
|
2277 |
||
2278 |
%------------------------------------------------------------------------------ |
|
2279 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2280 |
\section{The SII State Machine} |
369 | 2281 |
\label{sec:fsm-sii} |
2282 |
\index{FSM!SII} |
|
2283 |
||
2284 |
The SII\index{SII} state machine (shown in figure~\ref{fig:fsm-sii}) |
|
2285 |
implements the process of reading or writing E$^2$PROM data via the |
|
2286 |
Slave Information Interface described in \cite[section~5.4]{alspec}. |
|
2287 |
||
2288 |
\begin{figure}[htbp] |
|
2289 |
\centering |
|
2290 |
\includegraphics[width=.9\textwidth]{images/fsm-sii} |
|
2291 |
\caption{Transition diagram of the SII state machine} |
|
2292 |
\label{fig:fsm-sii} |
|
2293 |
\end{figure} |
|
2294 |
||
2295 |
\begin{description} |
|
2296 |
\item[READ\_START] The beginning state for reading access, where the |
|
2297 |
read request and the requested address are written to the SII |
|
2298 |
attribute. Nothing can fail up to now. |
|
379 | 2299 |
$\rightarrow$~READ\_CHECK |
369 | 2300 |
|
2301 |
\item[READ\_CHECK] When the SII read request has been sent |
|
2302 |
successfully, a timer is started. A check/fetch datagram is issued, |
|
2303 |
that reads out the SII attribute for state and data. |
|
379 | 2304 |
$\rightarrow$~READ\_FETCH |
369 | 2305 |
|
2306 |
\item[READ\_FETCH] Upon reception of the check/fetch datagram, the |
|
2307 |
\textit{Read Operation} and \textit{Busy} parameters are checked: |
|
2308 |
\begin{itemize} |
|
2309 |
\item If the slave is still busy with fetching E$^2$PROM data into |
|
2310 |
the interface, the timer is checked. If it timed out, the reading |
|
379 | 2311 |
is aborted ($\rightarrow$~ERROR), if not, the check/fetch datagram |
2312 |
is issued again. $\rightarrow$~READ\_FETCH |
|
369 | 2313 |
|
2314 |
\item If the slave is ready with reading data, these are copied from |
|
2315 |
the datagram and the read cycle is completed. |
|
379 | 2316 |
$\rightarrow$~END |
369 | 2317 |
\end{itemize} |
2318 |
\end{description} |
|
2319 |
||
2320 |
The write access states behave nearly the same: |
|
2321 |
||
2322 |
\begin{description} |
|
2323 |
\item[WRITE\_START] The beginning state for writing access, |
|
2324 |
respectively. A write request, the target address and the data word |
|
2325 |
are written to the SII attribute. Nothing can fail. |
|
379 | 2326 |
$\rightarrow$~WRITE\_CHECK |
369 | 2327 |
|
2328 |
\item[WRITE\_CHECK] When the SII write request has been sent |
|
2329 |
successfully, the timer is started. A check datagram is issued, that |
|
2330 |
reads out the SII attribute for the state of the write operation. |
|
379 | 2331 |
$\rightarrow$~WRITE\_CHECK2 |
369 | 2332 |
|
2333 |
\item[WRITE\_CHECK2] Upon reception of the check datagram, the |
|
2334 |
\textit{Write Operation} and \textit{Busy} parameters are checked: |
|
2335 |
\begin{itemize} |
|
2336 |
\item If the slave is still busy with writing E$^2$PROM data, the |
|
2337 |
timer is checked. If it timed out, the operation is aborted |
|
379 | 2338 |
($\rightarrow$~ERROR), if not, the check datagram is issued again. |
2339 |
$\rightarrow$~WRITE\_CHECK2 |
|
369 | 2340 |
\item If the slave is ready with writing data, the write cycle is |
379 | 2341 |
completed. $\rightarrow$~END |
369 | 2342 |
\end{itemize} |
2343 |
\end{description} |
|
2344 |
||
2345 |
%------------------------------------------------------------------------------ |
|
2346 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2347 |
\chapter{Mailbox Protocol Implementations} |
369 | 2348 |
\index{Mailbox} |
2349 |
||
2350 |
The EtherCAT master implements the EoE and the CoE mailbox |
|
2351 |
protocols. See the below section for details. |
|
2352 |
||
2353 |
%------------------------------------------------------------------------------ |
|
2354 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2355 |
\section{Ethernet-over-EtherCAT (EoE)} |
369 | 2356 |
\label{sec:eoeimp} |
2357 |
\index{EoE} |
|
2358 |
||
2359 |
The EtherCAT master implements the Ethernet-over-EtherCAT mailbox |
|
2360 |
protocol to enable the tunneling of Ethernet frames to special slaves, |
|
2361 |
that can either have physical Ethernet ports to forward the frames to, |
|
2362 |
or have an own IP stack to receive the frames. |
|
2363 |
||
2364 |
\paragraph{Virtual Network Interfaces} |
|
2365 |
||
2366 |
The master creates a virtual EoE network interface for every |
|
2367 |
EoE-capable slave. These interfaces are called \textit{eoeX}, where X |
|
2368 |
is a number provided by the kernel on interface registration. Frames |
|
2369 |
sent to these interfaces are forwarded to the associated slaves by the |
|
2370 |
master. Frames, that are received by the slaves, are fetched by the |
|
2371 |
master and forwarded to the virtual interfaces. |
|
2372 |
||
2373 |
This bears the following advantages: |
|
2374 |
||
2375 |
\begin{itemize} |
|
2376 |
\item Flexibility: The user can decide, how the EoE-capable slaves are |
|
2377 |
interconnected with the rest of the world. |
|
2378 |
\item Standard tools can be used to monitor the EoE activity and to |
|
2379 |
configure the EoE interfaces. |
|
2380 |
\item The Linux kernel's layer-2-bridging implementation (according to |
|
2381 |
the IEEE 802.1D MAC Bridging standard) can be used natively to |
|
2382 |
bridge Ethernet traffic between EoE-capable slaves. |
|
2383 |
\item The Linux kernel's network stack can be used to route packets |
|
2384 |
between EoE-capable slaves and to track security issues, just like |
|
2385 |
having physical network interfaces. |
|
2386 |
\end{itemize} |
|
2387 |
||
2388 |
\paragraph{EoE Handlers} |
|
2389 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2390 |
The virtual EoE interfaces and the related functionality is encapsulated in the |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2391 |
\textit{ec\_eoe\_t} class (see section~\ref{sec:class-eoe}). So the master |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2392 |
does not create the network interfaces directly: This is done inside the |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2393 |
constructor of the \textit{ec\_eoe\_t} class. An object of this class is called |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2394 |
``EoE handler'' below. An EoE handler additionally contains a frame queue. Each |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2395 |
time, the kernel passes a new socket buffer for sending via the interface's |
369 | 2396 |
\textit{hard\_start\_xmit()} callback, the socket buffer is queued for |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2397 |
transmission by the EoE state machine (see below). If the queue gets filled up, |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2398 |
the passing of new socket buffers is suspended with a call to |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2399 |
\textit{netif\_stop\_queue()}. |
369 | 2400 |
|
2401 |
\paragraph{Static Handler Creation} |
|
2402 |
||
2403 |
The master creates a pool of EoE handlers at startup, that are coupled |
|
2404 |
to EoE-capable slaves on demand. The lifetime of the corresponding |
|
2405 |
network interfaces is equal to the lifetime of the master module. |
|
2406 |
This approach is opposed to creating the virtual network interfaces on |
|
2407 |
demand (i.~e. on running across a new EoE-capable slave). The latter |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2408 |
approach was considered as difficult, because of several reasons: |
369 | 2409 |
|
2410 |
\begin{itemize} |
|
2411 |
\item The \textit{alloc\_netdev()} function can sleep and must be |
|
2412 |
called from a non-interrupt context. This reduces the flexibility of |
|
2413 |
choosing an appropriate method for cyclic EoE processing. |
|
2414 |
\item Unregistering network interfaces requires them to be ``down'', |
|
2415 |
which can not be guaranteed upon sudden disappearing of an |
|
2416 |
EoE-capable slave. |
|
2417 |
\item The connection to the EoE-capable slaves must be as continuous |
|
2418 |
as possible. Especially the transition from idle to operation mode |
|
2419 |
(and vice versa) causes the rebuilding of the internal data |
|
2420 |
structures. These transitions must be as transparent as possible for |
|
2421 |
the instances using the network interfaces. |
|
2422 |
\end{itemize} |
|
2423 |
||
1095 | 2424 |
\paragraph{Number of Handlers} % FIXME |
369 | 2425 |
|
2426 |
The master module has a parameter \textit{ec\_eoeif\_count} to specify |
|
2427 |
the number of EoE interfaces (and handlers) per master to create. This |
|
2428 |
parameter can either be specified when manually loading the master |
|
2429 |
module, or (when using the init script) by setting the |
|
379 | 2430 |
\$EOE\_INTERFACES variable in the sysconfig file (see |
369 | 2431 |
section~\ref{sec:sysconfig}). Upon loading of the master module, the |
2432 |
virtual interfaces become available: |
|
2433 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2434 |
\begin{lstlisting}[gobble=2] |
379 | 2435 |
# `\textbf{ifconfig -a}` |
369 | 2436 |
eoe0 Link encap:Ethernet HWaddr 00:11:22:33:44:06 |
2437 |
BROADCAST MULTICAST MTU:1500 Metric:1 |
|
2438 |
RX packets:0 errors:0 dropped:0 overruns:0 frame:0 |
|
2439 |
TX packets:0 errors:0 dropped:0 overruns:0 carrier:0 |
|
2440 |
collisions:0 txqueuelen:1000 |
|
2441 |
RX bytes:0 (0.0 b) TX bytes:0 (0.0 b) |
|
2442 |
||
2443 |
eoe1 Link encap:Ethernet HWaddr 00:11:22:33:44:07 |
|
2444 |
BROADCAST MULTICAST MTU:1500 Metric:1 |
|
2445 |
RX packets:0 errors:0 dropped:0 overruns:0 frame:0 |
|
2446 |
TX packets:0 errors:0 dropped:0 overruns:0 carrier:0 |
|
2447 |
collisions:0 txqueuelen:1000 |
|
2448 |
RX bytes:0 (0.0 b) TX bytes:0 (0.0 b) |
|
2449 |
... |
|
2450 |
\end{lstlisting} |
|
2451 |
||
2452 |
\paragraph{Coupling of EoE Slaves} |
|
2453 |
||
2454 |
During execution of the slave scan state machine (see |
|
2455 |
section~\ref{sec:fsm-scan}), the master determines the supported |
|
2456 |
mailbox protocols. This is done by examining the ``Supported Mailbox |
|
2457 |
Protocols'' mask field at word address 0x001C of the SII\index{SII}. |
|
2458 |
If bit 1 is set, the slave supports the EoE protocol. After slave |
|
2459 |
scanning, the master runs through all slaves again and couples each |
|
2460 |
EoE-capable slave to a free EoE handler. It can happen, that there are |
|
2461 |
not enough EoE handlers to cover all EoE-capable slaves. In this case, |
|
2462 |
the number of EoE handlers must be increased accordingly. |
|
2463 |
||
2464 |
\paragraph{EoE State Machine} |
|
2465 |
\index{FSM!EoE} |
|
2466 |
||
2467 |
Every EoE handler owns an EoE state machine, that is used to send |
|
2468 |
frames to the coupled slave and receive frames from the it via the EoE |
|
2469 |
communication primitives. This state machine is showed in |
|
2470 |
figure~\ref{fig:fsm-eoe}. |
|
2471 |
||
2472 |
\begin{figure}[htbp] |
|
2473 |
\centering |
|
2474 |
\includegraphics[width=.7\textwidth]{images/fsm-eoe} |
|
2475 |
\caption{Transition diagram of the EoE state machine} |
|
2476 |
\label{fig:fsm-eoe} |
|
2477 |
\end{figure} |
|
2478 |
||
2479 |
\begin{description} |
|
2480 |
\item[RX\_START] The beginning state of the EoE state machine. A |
|
2481 |
mailbox check datagram is sent, to query the slave's mailbox for new |
|
379 | 2482 |
frames. $\rightarrow$~RX\_CHECK |
369 | 2483 |
|
2484 |
\item[RX\_CHECK] The mailbox check datagram is received. If the |
|
2485 |
slave's mailbox did not contain data, a transmit cycle is started. |
|
379 | 2486 |
$\rightarrow$~TX\_START |
369 | 2487 |
|
2488 |
If there are new data in the mailbox, a datagram is sent to fetch |
|
379 | 2489 |
the new data. $\rightarrow$~RX\_FETCH |
369 | 2490 |
|
2491 |
\item[RX\_FETCH] The fetch datagram is received. If the mailbox data |
|
2492 |
do not contain a ``EoE Fragment request'' command, the data are |
|
2493 |
dropped and a transmit sequence is started. |
|
379 | 2494 |
$\rightarrow$~TX\_START |
369 | 2495 |
|
2496 |
If the received Ethernet frame fragment is the first fragment, a new |
|
2497 |
socket buffer is allocated. In either case, the data are copied into |
|
2498 |
the correct position of the socket buffer. |
|
2499 |
||
2500 |
If the fragment is the last fragment, the socket buffer is forwarded |
|
2501 |
to the network stack and a transmit sequence is started. |
|
379 | 2502 |
$\rightarrow$~TX\_START |
369 | 2503 |
|
2504 |
Otherwise, a new receive sequence is started to fetch the next |
|
379 | 2505 |
fragment. $\rightarrow$~RX\_\-START |
369 | 2506 |
|
2507 |
\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
|
2508 |
checked, if the transmission queue contains a frame to send. If not, |
379 | 2509 |
a receive sequence is started. $\rightarrow$~RX\_START |
369 | 2510 |
|
2511 |
If there is a frame to send, it is dequeued. If the queue was |
|
2512 |
inactive before (because it was full), the queue is woken up with a |
|
2513 |
call to \textit{netif\_wake\_queue()}. The first fragment of the |
|
379 | 2514 |
frame is sent. $\rightarrow$~TX\_SENT |
369 | 2515 |
|
2516 |
\item[TX\_SENT] It is checked, if the first fragment was sent |
|
2517 |
successfully. If the current frame consists of further fragments, |
|
379 | 2518 |
the next one is sent. $\rightarrow$~TX\_SENT |
369 | 2519 |
|
2520 |
If the last fragment was sent, a new receive sequence is started. |
|
379 | 2521 |
$\rightarrow$~RX\_START |
369 | 2522 |
\end{description} |
2523 |
||
2524 |
\paragraph{EoE Processing} |
|
2525 |
||
2526 |
To execute the EoE state machine of every active EoE handler, there |
|
2527 |
must be a cyclic process. The easiest thing would be to execute the |
|
2528 |
EoE state machines synchronously to the operation state machine (see |
|
2529 |
section~\ref{sec:fsm-op}) with every realtime cycle. This approach has |
|
2530 |
the following disadvantages: |
|
2531 |
||
2532 |
\begin{itemize} |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2533 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2534 |
\item Only one EoE fragment can be sent or received every few cycles. This |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2535 |
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
|
2536 |
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
|
2537 |
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
|
2538 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2539 |
\item The receiving and forwarding of frames to the kernel requires the dynamic |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2540 |
allocation of frames. Some realtime extensions do not support calling memory |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2541 |
allocation functions in realtime context, so the EoE state machine may not be |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2542 |
executed with each application cycle. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2543 |
|
369 | 2544 |
\end{itemize} |
2545 |
||
2546 |
To overcome these problems, an own cyclic process is needed to |
|
2547 |
asynchronously execute the EoE state machines. For that, the master |
|
2548 |
owns a kernel timer, that is executed each timer interrupt. This |
|
2549 |
guarantees a constant bandwidth, but poses the new problem of |
|
2550 |
concurrent access to the master. The locking mechanisms needed for |
|
2551 |
this are introduced in section~\ref{sec:concurr}. |
|
2552 |
Section~\ref{sec:concurrency} gives practical implementation examples. |
|
2553 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2554 |
\paragraph{Idle phase} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2555 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2556 |
EoE data must also be exchanged in idle phase, to guarantee the continuous |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2557 |
availability of the connection to the EoE-capable slaves. Although there is no |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2558 |
application connected in this case, the master is still accessed by the master |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2559 |
state machine (see section~\ref{sec:fsm-master}). With the EoE timer running in |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2560 |
addition, there is still concurrency, that has to be protected by a lock. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2561 |
Therefore the master owns an internal spinlock that is used protect master |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2562 |
access during idle phase. |
369 | 2563 |
|
2564 |
\paragraph{Automatic Configuration} |
|
2565 |
||
379 | 2566 |
By default, slaves are left in INIT state during idle mode. If an EoE |
2567 |
interface is set to running state (i.~e. with the \textit{ifconfig up} |
|
2568 |
command), the requested slave state of the related slave is |
|
2569 |
automatically set to OP, whereupon the idle state machine will attempt |
|
2570 |
to configure the slave and put it into operation. |
|
369 | 2571 |
|
2572 |
%------------------------------------------------------------------------------ |
|
2573 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2574 |
\section{CANopen-over-EtherCAT (CoE)} |
369 | 2575 |
\label{sec:coeimp} |
2576 |
\index{CoE} |
|
2577 |
||
2578 |
The CANopen-over-EtherCAT protocol \cite[section~5.6]{alspec} is used |
|
2579 |
to configure slaves on application level. Each CoE-capable slave |
|
814 | 2580 |
provides a list of Sdos for this reason. |
2581 |
||
2582 |
\paragraph{Sdo Configuration} |
|
2583 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2584 |
The Sdo configurations have to be provided by the application. This is done |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2585 |
via the \textit{ecrt\_slave\_conf\_sdo*()} methods (see |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2586 |
section~\ref{sec:ecrt-slave}), that are part of the realtime interface. The |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2587 |
slave stores the Sdo configurations in a linked list, but does not apply them |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2588 |
at once. |
369 | 2589 |
|
814 | 2590 |
\paragraph{Sdo Download State Machine} |
2591 |
||
2592 |
The best time to apply Sdo configurations is during the slave's PREOP |
|
379 | 2593 |
state, because mailbox communication is already possible and slave's |
2594 |
application will start with updating input data in the succeeding |
|
814 | 2595 |
SAFEOP state. Therefore the Sdo configuration has to be part of the |
379 | 2596 |
slave configuration state machine (see section~\ref{sec:fsm-conf}): It |
814 | 2597 |
is implemented via an Sdo download state machine, that is executed |
813
bfc3f1ab52de
Fixed typo SAVEOP -> SAFEOP.
Florian Pose <fp@igh-essen.com>
parents:
487
diff
changeset
|
2598 |
just before entering the slave's SAFEOP state. In this way, it is |
814 | 2599 |
guaranteed that the Sdo configurations are applied each time, the |
379 | 2600 |
slave is reconfigured. |
369 | 2601 |
|
814 | 2602 |
The transition diagram of the Sdo Download state machine can be seen |
369 | 2603 |
in figure~\ref{fig:fsm-coedown}. |
2604 |
||
2605 |
\begin{figure}[htbp] |
|
2606 |
\centering |
|
2607 |
\includegraphics[width=.9\textwidth]{images/fsm-coedown} |
|
2608 |
\caption{Transition diagram of the CoE download state machine} |
|
2609 |
\label{fig:fsm-coedown} |
|
2610 |
\end{figure} |
|
2611 |
||
2612 |
\begin{description} |
|
2613 |
\item[START] The beginning state of the CoE download state |
|
814 | 2614 |
machine. The ``Sdo Download Normal Request'' mailbox command is |
379 | 2615 |
sent. $\rightarrow$~REQUEST |
369 | 2616 |
|
2617 |
\item[REQUEST] It is checked, if the CoE download request has been |
|
2618 |
received by the slave. After that, a mailbox check command is issued |
|
379 | 2619 |
and a timer is started. $\rightarrow$~CHECK |
369 | 2620 |
|
2621 |
\item[CHECK] If no mailbox data is available, the timer is checked. |
|
2622 |
\begin{itemize} |
|
814 | 2623 |
\item If it timed out, the Sdo download is aborted. |
379 | 2624 |
$\rightarrow$~ERROR |
369 | 2625 |
\item Otherwise, the mailbox is queried again. |
379 | 2626 |
$\rightarrow$~CHECK |
369 | 2627 |
\end{itemize} |
2628 |
||
2629 |
If the mailbox contains new data, the response is fetched. |
|
379 | 2630 |
$\rightarrow$~RESPONSE |
369 | 2631 |
|
2632 |
\item[RESPONSE] If the mailbox response could not be fetched, the data |
|
814 | 2633 |
is invalid, the wrong protocol was received, or a ``Abort Sdo |
2634 |
Transfer Request'' was received, the Sdo download is aborted. |
|
379 | 2635 |
$\rightarrow$~ERROR |
369 | 2636 |
|
814 | 2637 |
If a ``Sdo Download Normal Response'' acknowledgement was received, |
2638 |
the Sdo download was successful. $\rightarrow$~END |
|
2639 |
||
2640 |
\item[END] The Sdo download was successful. |
|
2641 |
||
2642 |
\item[ERROR] The Sdo download was aborted due to an error. |
|
369 | 2643 |
|
2644 |
\end{description} |
|
2645 |
||
2646 |
%------------------------------------------------------------------------------ |
|
2647 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2648 |
\chapter{User Space} |
369 | 2649 |
\label{sec:user} |
2650 |
\index{User space} |
|
2651 |
||
2652 |
For the master runs as a kernel module, accessing it is natively |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2653 |
limited to analyzing Syslog messages and controlling using modutils. |
369 | 2654 |
|
2655 |
It is necessary to implement further interfaces, that make it easier |
|
2656 |
to access the master from user space and allow a finer influence. It |
|
2657 |
should be possible to view and to change special parameters at runtime. |
|
2658 |
||
2659 |
Bus visualization is a second point: For development and debugging |
|
2660 |
purposes it would be nice, if one could show the connected slaves with |
|
2661 |
a single command. |
|
2662 |
||
2663 |
Another aspect is automatic startup and configuration. If the master |
|
2664 |
is to be integrated into a running system, it must be able to |
|
2665 |
automatically start with a persistent configuration. |
|
2666 |
||
2667 |
A last thing is monitoring EtherCAT communication. For debugging |
|
2668 |
purposes, there had to be a way to analyze EtherCAT datagrams. The |
|
2669 |
best way would be with a popular network analyzer, like Wireshark |
|
2670 |
\cite{wireshark} (the former Ethereal) or others. |
|
2671 |
||
2672 |
This section covers all those points and introduces the interfaces and |
|
2673 |
tools to make all that possible. |
|
2674 |
||
2675 |
%------------------------------------------------------------------------------ |
|
2676 |
||
1087
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2677 |
\section{Command-line Tool} |
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2678 |
\label{sec:ethercat} |
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2679 |
|
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2680 |
% --master |
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2681 |
|
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2682 |
\subsection{Character devices} |
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2683 |
\label{sec:cdev} |
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2684 |
|
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2685 |
Each master instance will get a character device as a user-space interface. |
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2686 |
The devices are named \textit{/dev/EtherCATX}, where $X$ is the index of the |
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2687 |
master. |
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2688 |
|
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2689 |
% FIXME |
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2690 |
% udev |
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2691 |
% rights |
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2692 |
|
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2693 |
%------------------------------------------------------------------------------ |
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2694 |
|
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2695 |
\subsection{Listing the bus} |
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2696 |
|
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2697 |
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
|
2698 |
|
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2699 |
\begin{lstlisting} |
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2700 |
$ `\textbf{ethercat slaves}` |
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2701 |
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
|
2702 |
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
|
2703 |
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
|
2704 |
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
|
2705 |
\end{lstlisting} |
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2706 |
|
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2707 |
Every slave found is displayed as one text row. The columns have the following |
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2708 |
meanings: |
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2709 |
|
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2710 |
\begin{enumerate} |
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2711 |
|
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2712 |
\item Ring position in the bus. |
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2713 |
|
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2714 |
\item Alias and position (see section~\ref{sec:addr}). |
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2715 |
|
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2716 |
\item Application-layer state. |
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2717 |
|
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2718 |
\item Error flag: \lstinline!+! means that the slave is ok, \lstinline+E+ |
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2719 |
means that an error has occurred during scanning or configuration. |
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2720 |
|
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2721 |
\item The slave's name, as it appears in the ``general'' SII category. If no |
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2722 |
name is found, the slave's vendor ID and product code are listed. |
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2723 |
|
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2724 |
\end{enumerate} |
369 | 2725 |
|
2726 |
%------------------------------------------------------------------------------ |
|
2727 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2728 |
\subsection{SII Access} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2729 |
\label{sec:siiaccess} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2730 |
\index{SII!Access} |
369 | 2731 |
|
1087
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2732 |
It is possible to directly read or write the complete SII contents of the |
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2733 |
slaves. This was introduced for the reasons below: |
369 | 2734 |
|
2735 |
\begin{itemize} |
|
1087
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2736 |
|
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2737 |
\item The format of the SII data is still in development and categories can be |
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2738 |
added in the future. With read and write access, the complete memory contents |
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2739 |
can be easily backed up and restored. |
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2740 |
|
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2741 |
\item Some SII data fields have to be altered (like the alias address). A quick |
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2742 |
writing must be possible for that. |
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2743 |
|
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2744 |
\item Through reading access, analyzing category data is possible from user |
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2745 |
space. |
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2746 |
|
369 | 2747 |
\end{itemize} |
2748 |
||
1087
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2749 |
Reading out SII data is as easy as other commands. Though the data are in |
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2750 |
binary format, analysis is easier with a tool like \textit{hexdump}: |
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2751 |
|
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2752 |
\begin{lstlisting} |
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2753 |
$ `\textbf{ethercat sii\_read --slave 3 | hexdump}` |
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2754 |
0000000 0103 0000 0000 0000 0000 0000 0000 008c |
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2755 |
0000010 0002 0000 3052 07f0 0000 0000 0000 0000 |
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2756 |
0000020 0000 0000 0000 0000 0000 0000 0000 0000 |
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2757 |
... |
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2758 |
\end{lstlisting} |
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2759 |
|
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2760 |
Backing up SII contents can easily done with a redirection: |
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2761 |
|
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2762 |
\begin{lstlisting} |
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2763 |
$ `\textbf{ethercat sii\_read --slave 3 > sii-of-slave3.bin}` |
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2764 |
\end{lstlisting} |
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2765 |
|
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2766 |
To download SII contents to a slave, writing access to the master's character |
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2767 |
device is necessary (see section~\ref{sec:cdev}). |
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2768 |
|
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2769 |
\begin{lstlisting} |
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2770 |
# `\textbf{ethercat sii\_write --slave 3 sii-of-slave3.bin}` |
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2771 |
\end{lstlisting} |
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2772 |
|
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2773 |
The SII contents will be checked for validity and then sent to the slave. The |
f1417824cee5
prepared command-line tool.
Florian Pose <fp@igh-essen.com>
parents:
1086
diff
changeset
|
2774 |
write operation may take a few seconds. |
369 | 2775 |
|
2776 |
%------------------------------------------------------------------------------ |
|
2777 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2778 |
\section{System Integration} |
369 | 2779 |
\label{sec:system} |
2780 |
||
1086
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
2781 |
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
|
2782 |
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
|
2783 |
|
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
2784 |
\subsection{Init Script} |
369 | 2785 |
\label{sec:init} |
2786 |
\index{Init script} |
|
2787 |
||
1086
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
2788 |
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
|
2789 |
Standard Base'' (LSB\index{LSB}, \cite{lsb}). The script is installed to |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
2790 |
\textit{etc/init.d/ethercat} below the installation prefix and has to be copied |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
2791 |
(or better: linked) to the appropriate location (see |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
2792 |
section~\ref{sec:install}), before the master can be inserted as a service. |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
2793 |
Please note, that the init script depends on the sysconfig file described |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
2794 |
below. |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
2795 |
|
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
2796 |
To provide service dependencies (i.~e. which services have to be started before |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
2797 |
others) inside the init script code, LSB defines a special comment block. |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
2798 |
System tools can extract this information to insert the EtherCAT init script at |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
2799 |
the correct place in the startup sequence: |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
2800 |
|
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
2801 |
\lstinputlisting[firstline=38,lastline=48] |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
2802 |
{../script/init.d/ethercat} |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
2803 |
|
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
2804 |
\subsection{Sysconfig} |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
2805 |
\label{sec:sysconfig} |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
2806 |
\index{Sysconfig file} |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
2807 |
|
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
2808 |
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
|
2809 |
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
|
2810 |
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
|
2811 |
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
|
2812 |
the file and included below: |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
2813 |
|
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
2814 |
\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
|
2815 |
{../script/sysconfig/ethercat} |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
2816 |
|
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
2817 |
\subsection{Service} |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
2818 |
\label{sec:service} |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
2819 |
\index{Service} |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
2820 |
|
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
2821 |
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
|
2822 |
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
|
2823 |
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
|
2824 |
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
|
2825 |
command: |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
2826 |
|
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
2827 |
\begin{lstlisting} |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
2828 |
# `\textbf{insserv ethercat}` |
369 | 2829 |
\end{lstlisting} |
2830 |
||
2831 |
The init script can also be used for manually starting and stopping |
|
2832 |
the EtherCAT master. It has to be executed with one of the parameters |
|
379 | 2833 |
\texttt{start}, \texttt{stop}, \texttt{restart} or \texttt{status}. |
369 | 2834 |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2835 |
\begin{lstlisting}[gobble=2] |
379 | 2836 |
# `\textbf{/etc/init.d/ethercat restart}` |
369 | 2837 |
Shutting down EtherCAT master done |
2838 |
Starting EtherCAT master done |
|
2839 |
\end{lstlisting} |
|
2840 |
||
2841 |
%------------------------------------------------------------------------------ |
|
2842 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2843 |
\section{Monitoring and Debugging} |
369 | 2844 |
\label{sec:debug} |
2845 |
\index{Monitoring} |
|
2846 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2847 |
For debugging purposes, every EtherCAT master registers a read-only network |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2848 |
interface \textit{ecX}, where X is a number, provided by the kernel on device |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2849 |
registration. While it is ``up'', the master forwards every frame sent and |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2850 |
received to this interface. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2851 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2852 |
This makes it possible to connect an network monitor (like Wireshark or |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2853 |
tcpdump) to the debug interface and monitor the EtherCAT frames. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2854 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2855 |
% FIXME schedule() |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2856 |
It has to be considered, that can be frame rate can be very high. The master |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2857 |
state machine usually runs every kernel timer interrupt (usually up to |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2858 |
\unit{1}{\kilo\hertz}) and with a connected application, the rate can be even |
369 | 2859 |
higher. |
2860 |
||
2861 |
\paragraph{Attention:} The socket buffers needed for the operation of |
|
2862 |
the debugging interface have to be allocated dynamically. Some Linux |
|
2863 |
realtime extensions do not allow this in realtime context! |
|
2864 |
||
2865 |
%------------------------------------------------------------------------------ |
|
2866 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2867 |
\chapter{Timing Aspects} |
369 | 2868 |
\label{sec:timing} |
2869 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2870 |
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
|
2871 |
are rare, there are a few aspects that can (and should be) dealt with. |
369 | 2872 |
|
2873 |
%------------------------------------------------------------------------------ |
|
2874 |
||
2875 |
\subsection{Realtime Interface Profiling} |
|
2876 |
\label{sec:timing-profile} |
|
2877 |
\index{Realtime!Profiling} |
|
2878 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2879 |
One of the most important timing aspects are the execution times of the |
369 | 2880 |
realtime interface functions, that are called in cyclic context. These |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2881 |
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
|
2882 |
To measure the timing of the functions, the following code was used: |
369 | 2883 |
|
2884 |
\begin{lstlisting}[gobble=2,language=C] |
|
2885 |
c0 = get_cycles(); |
|
2886 |
ecrt_master_receive(master); |
|
2887 |
c1 = get_cycles(); |
|
2888 |
ecrt_domain_process(domain1); |
|
2889 |
c2 = get_cycles(); |
|
2890 |
ecrt_master_run(master); |
|
2891 |
c3 = get_cycles(); |
|
2892 |
ecrt_master_send(master); |
|
2893 |
c4 = get_cycles(); |
|
2894 |
\end{lstlisting} |
|
2895 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2896 |
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
|
2897 |
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
|
2898 |
\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
|
2899 |
\milli\second. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2900 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2901 |
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
|
2902 |
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
|
2903 |
\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
|
2904 |
results were averaged. These can be seen in table~\ref{tab:profile}. |
369 | 2905 |
|
2906 |
\begin{table}[htpb] |
|
2907 |
\centering |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2908 |
\caption{Profiling of a Realtime Cycle on a \unit{2.0}{\giga\hertz} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2909 |
Processor} |
369 | 2910 |
\label{tab:profile} |
2911 |
\vspace{2mm} |
|
2912 |
\begin{tabular}{l|r|r} |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2913 |
Element & Mean Duration [\second] & Standard Deviancy [\micro\second] \\ |
369 | 2914 |
\hline |
2915 |
\textit{ecrt\_master\_receive()} & 8.04 & 0.48\\ |
|
2916 |
\textit{ecrt\_domain\_process()} & 0.14 & 0.03\\ |
|
2917 |
\textit{ecrt\_master\_run()} & 0.29 & 0.12\\ |
|
2918 |
\textit{ecrt\_master\_send()} & 2.18 & 0.17\\ \hline |
|
2919 |
Complete Cycle & 10.65 & 0.69\\ \hline |
|
2920 |
\end{tabular} |
|
2921 |
\end{table} |
|
2922 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2923 |
It is obvious, that the functions accessing hardware make up the |
369 | 2924 |
lion's share. The \textit{ec\_master\_receive()} executes the ISR of |
2925 |
the Ethernet device, analyzes datagrams and copies their contents into |
|
2926 |
the memory of the datagram objects. The \textit{ec\_master\_send()} |
|
2927 |
assembles a frame out of different datagrams and copies it to the |
|
2928 |
hardware buffers. Interestingly, this makes up only a quarter of the |
|
2929 |
receiving time. |
|
2930 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2931 |
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
|
2932 |
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
|
2933 |
\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
|
2934 |
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
|
2935 |
\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
|
2936 |
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
|
2937 |
functions are more or less complex. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2938 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2939 |
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
|
2940 |
frequency can be up to \unit{100}{\kilo\hertz}. For two reasons, this frequency |
369 | 2941 |
keeps being theoretical: |
2942 |
||
2943 |
\begin{enumerate} |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2944 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2945 |
\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
|
2946 |
realtime cycles. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2947 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2948 |
\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
|
2949 |
cycle begins. The determination of the bus cycle time is difficult and covered |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2950 |
in section~\ref{sec:timing-bus}. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2951 |
|
369 | 2952 |
\end{enumerate} |
2953 |
||
2954 |
%------------------------------------------------------------------------------ |
|
2955 |
||
2956 |
\subsection{Bus Cycle Measuring} |
|
2957 |
\label{sec:timing-bus} |
|
2958 |
\index{Bus cycle} |
|
2959 |
||
2960 |
For measuring the time, a frame is ``on the wire'', two timestamps |
|
2961 |
must be be taken: |
|
2962 |
||
2963 |
\begin{enumerate} |
|
2964 |
\item The time, the Ethernet hardware begins with physically sending |
|
2965 |
the frame. |
|
2966 |
\item The time, the frame is completely received by the Ethernet |
|
2967 |
hardware. |
|
2968 |
\end{enumerate} |
|
2969 |
||
2970 |
Both times are difficult to determine. The first reason is, that the |
|
2971 |
interrupts are disabled and the master is not notified, when a frame |
|
2972 |
is sent or received (polling would distort the results). The second |
|
2973 |
reason is, that even with interrupts enabled, the time from the event |
|
2974 |
to the notification is unknown. Therefore the only way to confidently |
|
2975 |
determine the bus cycle time is an electrical measuring. |
|
2976 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2977 |
Anyway, the bus cycle time is an important factor when designing realtime code, |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2978 |
because it limits the maximum frequency for the cyclic task of the application. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2979 |
In practice, these timing parameters are highly dependent on the hardware and |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2980 |
often a trial and error method must be used to determine the limits of the |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2981 |
system. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2982 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2983 |
The central question is: What happens, if the cycle frequency is too high? The |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2984 |
answer is, that the EtherCAT frames that have been sent at the end of the cycle |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2985 |
are not yet received, when the next cycle starts. First this is noticed by |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2986 |
\textit{ecrt\_domain\_process()}, because the working counter of the process |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2987 |
data datagrams were not increased. The function will notify the user via |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2988 |
Syslog\footnote{To limit Syslog output, a mechanism has been implemented, that |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2989 |
outputs a summarized notification at maximum once a second.}. In this case, the |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2990 |
process data keeps being the same as in the last cycle, because it is not |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2991 |
erased by the domain. When the domain datagrams are queued again, the master |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2992 |
notices, that they are already queued (and marked as sent). The master will |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2993 |
mark them as unsent again and output a warning, that datagrams were |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2994 |
``skipped''. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2995 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2996 |
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
|
2997 |
can be up to \unit{25}{\kilo\hertz} without skipped frames. This value can |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2998 |
surely be increased by choosing faster hardware. Especially the RealTek network |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
2999 |
hardware could be replaced by a faster one. Besides, implementing a dedicated |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3000 |
ISR for EtherCAT devices would also contribute to increasing the latency. These |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3001 |
are two points on the author's to-do list. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3002 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3003 |
%------------------------------------------------------------------------------ |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3004 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3005 |
\chapter{Installation} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3006 |
\label{sec:installation} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3007 |
\index{Master!Installation} |
369 | 3008 |
|
1094
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3009 |
\section{Building the software} |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3010 |
|
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3011 |
The current EtherCAT master code is available at~\cite{etherlab} or can be |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3012 |
obtained from the EtherLab CD. The \textit{tar.bz2} file has to be unpacked |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3013 |
with the commands below (or similar): |
369 | 3014 |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3015 |
\begin{lstlisting}[gobble=2] |
487 | 3016 |
`\$` `\textbf{tar xjf ethercat-\masterversion.tar.bz2}` |
3017 |
`\$` `\textbf{cd ethercat-\masterversion/}` |
|
374
e43a29f9079e
Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents:
371
diff
changeset
|
3018 |
\end{lstlisting} |
e43a29f9079e
Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents:
371
diff
changeset
|
3019 |
|
e43a29f9079e
Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents:
371
diff
changeset
|
3020 |
The tarball was created with GNU Autotools, so the build process |
487 | 3021 |
follows the below commands: |
369 | 3022 |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3023 |
\begin{lstlisting}[gobble=2] |
379 | 3024 |
`\$` `\textbf{./configure}` |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3025 |
`\$` `\textbf{make}` |
487 | 3026 |
`\$` `\textbf{make modules}` |
374
e43a29f9079e
Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents:
371
diff
changeset
|
3027 |
\end{lstlisting} |
e43a29f9079e
Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents:
371
diff
changeset
|
3028 |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3029 |
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
|
3030 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3031 |
\begin{table} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3032 |
\caption{Configuration options} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3033 |
\label{tab:config} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3034 |
\vspace{2mm} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3035 |
\begin{tabular}{l|p{.3\textwidth}|l} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3036 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3037 |
\bf Option/Switch & \bf Description & \bf Default\\\hline |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3038 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3039 |
\lstinline+--prefix+ & Installation prefix & \textit{/opt/etherlab}\\ |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3040 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3041 |
\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
|
3042 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3043 |
\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
|
3044 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3045 |
\hline |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3046 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3047 |
\lstinline+--enable-eoe+ & Enable EoE support & yes\\ |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3048 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3049 |
\lstinline+--enable-cycles+ & Use CPU timestamp counter. Enable this on Intel |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3050 |
architecture to get finer timing calculation. & no\\ |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3051 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3052 |
\lstinline+--enable-debug-if+ & Create a debug interface for each master & no\\ |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3053 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3054 |
\lstinline+--enable-debug-ring+ & Create a debug ring to record frames & no\\ |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3055 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3056 |
\hline |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3057 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3058 |
\lstinline+--enable-8139too+ & Build the 8139too driver & yes\\ |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3059 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3060 |
\lstinline+--with-8139too-kernel+ & 8139too kernel & $\dagger$\\ |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3061 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3062 |
\lstinline+--enable-e100+ & Build the e100 driver & no\\ |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3063 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3064 |
\lstinline+--with-e100-kernel+ & e100 kernel & $\dagger$\\ |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3065 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3066 |
\lstinline+--enable-forcedeth+ & Enable forcedeth driver & no\\ |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3067 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3068 |
\lstinline+--with-forcedeth-kernel+ & forcedeth kernel & $\dagger$\\ |
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 |
\lstinline+--enable-e1000+ & Enable e1000 driver & no\\ |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3071 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3072 |
\lstinline+--with-e1000-kernel+ & e1000 kernel & $\dagger$\\ |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3073 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3074 |
\lstinline+--enable-r8169+ & Enable r8169 driver & no\\ |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3075 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3076 |
\lstinline+--with-r8169-kernel+ & r8169 kernel & $\dagger$\\ |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3077 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3078 |
\end{tabular} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3079 |
\vspace{2mm} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3080 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3081 |
\begin{description} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3082 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3083 |
\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
|
3084 |
extracted from the Linux kernel sources. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3085 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3086 |
\end{description} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3087 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3088 |
\end{table} |
487 | 3089 |
|
1094
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3090 |
\section{Building the documentation} |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3091 |
\label{sec:gendoc} |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3092 |
|
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3093 |
The source code is documented using Doxygen~\cite{doxygen}. To build the HTML |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3094 |
documentation, you must have the Doxygen software installed. The below command |
1095 | 3095 |
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
|
3096 |
|
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3097 |
\begin{lstlisting} |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3098 |
$ `\textbf{make doc}` |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3099 |
\end{lstlisting} |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3100 |
|
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3101 |
To view them, point your browser to \textit{doxygen-output/html/index.html}. |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3102 |
|
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3103 |
\section{Installation} |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3104 |
|
1106
745a0cc03143
Added depmod call to docs.
Florian Pose <fp@igh-essen.com>
parents:
1095
diff
changeset
|
3105 |
The below commands have to be entered as \textit{root}: The first one will |
745a0cc03143
Added depmod call to docs.
Florian Pose <fp@igh-essen.com>
parents:
1095
diff
changeset
|
3106 |
install the EtherCAT header, init script, sysconfig file and the user space |
745a0cc03143
Added depmod call to docs.
Florian Pose <fp@igh-essen.com>
parents:
1095
diff
changeset
|
3107 |
tools to the prefix path. The second one will install the kernel modules to the |
745a0cc03143
Added depmod call to docs.
Florian Pose <fp@igh-essen.com>
parents:
1095
diff
changeset
|
3108 |
kernel's modules directory. The following \lstinline+depmod+ call is necessary |
745a0cc03143
Added depmod call to docs.
Florian Pose <fp@igh-essen.com>
parents:
1095
diff
changeset
|
3109 |
to include the kernel modules into the \textit{modules.dep} file to make it |
745a0cc03143
Added depmod call to docs.
Florian Pose <fp@igh-essen.com>
parents:
1095
diff
changeset
|
3110 |
available to the \lstinline+modprobe+ command, used in the init script. |
369 | 3111 |
|
1094
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3112 |
\begin{lstlisting} |
1106
745a0cc03143
Added depmod call to docs.
Florian Pose <fp@igh-essen.com>
parents:
1095
diff
changeset
|
3113 |
# `\textbf{make install}` |
1094
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3114 |
# `\textbf{make modules\_install}` |
1106
745a0cc03143
Added depmod call to docs.
Florian Pose <fp@igh-essen.com>
parents:
1095
diff
changeset
|
3115 |
# `\textbf{depmod}` |
369 | 3116 |
\end{lstlisting} |
3117 |
||
1095 | 3118 |
If the target kernel's modules directory is not under \textit{/lib/modules}, a |
3119 |
different destination directory can be specified with the \lstinline+DESTDIR+ |
|
3120 |
make variable. For example: |
|
487 | 3121 |
|
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{make DESTDIR=/vol/nfs/root modules\_install}` |
487 | 3124 |
\end{lstlisting} |
3125 |
||
3126 |
This command will install the compiled kernel modules to |
|
3127 |
\textit{/vol/nfs/root/lib/modules}, prepended by the kernel release. |
|
3128 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3129 |
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
|
3130 |
master shall not be loaded on system startup, the use of the init script is |
1086
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
3131 |
recommended for manual (un-)loading.} (see section~\ref{sec:system}), the init |
722ead4ecc22
Doc: Architecture, master module, system integration.
Florian Pose <fp@igh-essen.com>
parents:
1085
diff
changeset
|
3132 |
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
|
3133 |
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
|
3134 |
distributions. |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3135 |
|
1107 | 3136 |
% FIXME relative ln -s? |
1094
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3137 |
\begin{lstlisting} |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3138 |
# `\textbf{cd /opt/etherlab}` |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3139 |
# `\textbf{cp etc/sysconfig/ethercat /etc/sysconfig/}` |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3140 |
# `\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
|
3141 |
# `\textbf{insserv ethercat}` |
374
e43a29f9079e
Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents:
371
diff
changeset
|
3142 |
\end{lstlisting} |
e43a29f9079e
Updated documentation concerning autotools/installation.
Florian Pose <fp@igh-essen.com>
parents:
371
diff
changeset
|
3143 |
|
376
d1441d87f5c1
Documentation: EtherLab-CD; obtaining the DEVICE_INDEX.
Florian Pose <fp@igh-essen.com>
parents:
374
diff
changeset
|
3144 |
Now the sysconfig file \texttt{/etc/sysconfig/ethercat} (see |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3145 |
section~\ref{sec:sysconfig}) has to be customized. The minimal customization |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3146 |
is to set the \lstinline+MASTER0_DEVICE+ variable to the MAC address of the |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3147 |
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
|
3148 |
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
|
3149 |
\lstinline+DEVICE_MODULES+ variable. |
369 | 3150 |
|
3151 |
After the basic configuration is done, the master can be started with |
|
3152 |
the below command: |
|
3153 |
||
1094
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3154 |
\begin{lstlisting} |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3155 |
# `\textbf{/etc/init.d/ethercat start}` |
369 | 3156 |
\end{lstlisting} |
3157 |
||
3158 |
The operation of the master can be observed by looking at the |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3159 |
Syslog\index{Syslog} messages, which should look like the ones below. If |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3160 |
EtherCAT slaves are connected to the master's EtherCAT device, the activity |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3161 |
indicators should begin to flash. |
369 | 3162 |
|
3163 |
\begin{lstlisting}[numbers=left] |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3164 |
EtherCAT: Master driver `\masterversion` |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3165 |
EtherCAT: 1 master waiting for devices. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3166 |
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
|
3167 |
Copyright (c) 1999-2005 Intel Corporation. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3168 |
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
|
3169 |
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
|
3170 |
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
|
3171 |
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
|
3172 |
EtherCAT: Starting master thread. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3173 |
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
|
3174 |
Connection |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3175 |
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
|
3176 |
Full Duplex |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3177 |
EtherCAT: Link state changed to UP. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3178 |
EtherCAT: 7 slave(s) responding. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3179 |
EtherCAT: Slave states: PREOP. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3180 |
EtherCAT: Scanning bus. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3181 |
EtherCAT: Bus scanning completed in 431 ms. |
369 | 3182 |
\end{lstlisting} |
3183 |
||
3184 |
\begin{description} |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3185 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3186 |
\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
|
3187 |
is initialized. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3188 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3189 |
\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
|
3190 |
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
|
3191 |
\lstinline+00:0E:0C:DA:A2:20+. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3192 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3193 |
\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
|
3194 |
state machine and begins scanning the bus. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3195 |
|
369 | 3196 |
\end{description} |
3197 |
||
3198 |
%------------------------------------------------------------------------------ |
|
3199 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3200 |
\chapter{Application examples} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3201 |
\label{chapter:examples} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3202 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3203 |
This chapter will give practical examples of how to use the EtherCAT master via |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3204 |
the realtime interface by writing an application module. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3205 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3206 |
%------------------------------------------------------------------------------ |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3207 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3208 |
\section{Minimal Example} |
369 | 3209 |
\label{sec:mini} |
3210 |
\index{Examples!Minimal} |
|
3211 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3212 |
This section will explain the use of the EtherCAT master from a minimal kernel |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3213 |
module. The complete module code is obtainable as a part of the EtherCAT master |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3214 |
code release (see~\cite{etherlab}, file \textit{examples/mini/mini.c}). |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3215 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3216 |
The minimal example uses a kernel timer (software interrupt) to generate a |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3217 |
cyclic task. After the timer function is executed, it re-adds itself with a |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3218 |
delay of one \textit{jiffy}\index{jiffies}, which results in a timer frequency |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3219 |
of \textit{HZ}\nomenclature{HZ}{Kernel macro containing the timer interrupt |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3220 |
frequency} |
369 | 3221 |
|
3222 |
The module-global variables, needed to operate the master can be seen |
|
3223 |
in listing~\ref{lst:minivar}. |
|
3224 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3225 |
\begin{lstlisting}[gobble=2,language=C,numbers=left,caption={Minimal |
369 | 3226 |
variables},label=lst:minivar] |
3227 |
struct timer_list timer; |
|
3228 |
||
3229 |
ec_master_t *master = NULL; |
|
3230 |
ec_domain_t *domain1 = NULL; |
|
3231 |
||
3232 |
void *r_dig_in, *r_ana_out; |
|
3233 |
||
3234 |
ec_pdo_reg_t domain1_pdos[] = { |
|
3235 |
{"1", Beckhoff_EL1014_Inputs, &r_dig_in}, |
|
3236 |
{"2", Beckhoff_EL4132_Ouput1, &r_ana_out}, |
|
3237 |
{} |
|
3238 |
}; |
|
3239 |
\end{lstlisting} |
|
3240 |
||
3241 |
\begin{description} |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3242 |
\item[\linenum{1}] There is a timer object |
369 | 3243 |
declared, that is needed to tell the kernel to install a timer and |
3244 |
execute a certain function, if it runs out. This is done by a |
|
3245 |
variable of the \textit{timer\_list} structure. |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3246 |
\item[\linenum{3} -- \linenum{4}] There |
369 | 3247 |
is a pointer declared, that will later point to a requested EtherCAT |
3248 |
master. Additionally there is a pointer to a domain object needed, |
|
3249 |
that will manage process data IO. |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3250 |
\item[\linenum{6}] The pointers \textit{r\_*} |
369 | 3251 |
will later point to the \underline{r}aw process data values inside |
3252 |
the domain memory. The addresses they point to will be set during a |
|
3253 |
call to \textit{ec\_\-master\_\-activate()}, that will create the |
|
3254 |
domain memory and configure the mapped process data image. |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3255 |
\item[\linenum{8} -- \linenum{12}] The |
814 | 3256 |
configuration of the mapping of certain Pdos in a domain can easily |
369 | 3257 |
be done with the help of an initialization array of the |
3258 |
\textit{ec\_pdo\_reg\_t} type, defined as part of the realtime |
|
3259 |
interface. Each record must contain the ASCII bus-address of the |
|
3260 |
slave (see section~\ref{sec:addr}), the slave's vendor ID and |
|
814 | 3261 |
product code, and the index and subindex of the Pdo to map (these |
369 | 3262 |
four fields can be specified in junction, by using one of the |
3263 |
defines out of the \textit{include/ecdb.h} header). The last field |
|
3264 |
has to be the address of the process data pointer, so it can later |
|
3265 |
be redirected appropriately. Attention: The initialization array |
|
3266 |
must end with an empty record (\textit{\{\}})! |
|
3267 |
\end{description} |
|
3268 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3269 |
The initialization of the minimal application is done by the ``Minimal init |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3270 |
function'' in listing~\ref{lst:miniinit}. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3271 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3272 |
\begin{lstlisting}[gobble=2,language=C,numbers=left,caption={Minimal init |
369 | 3273 |
function},label={lst:miniinit}] |
3274 |
int __init init_mini_module(void) |
|
3275 |
{ |
|
3276 |
if (!(master = ecrt_request_master(0))) { |
|
3277 |
goto out_return; |
|
3278 |
} |
|
3279 |
||
3280 |
if (!(domain1 = ecrt_master_create_domain(master))) { |
|
3281 |
goto out_release_master; |
|
3282 |
} |
|
3283 |
||
3284 |
if (ecrt_domain_register_pdo_list(domain1, |
|
3285 |
domain1_pdos)) { |
|
3286 |
goto out_release_master; |
|
3287 |
} |
|
3288 |
||
3289 |
if (ecrt_master_activate(master)) { |
|
3290 |
goto out_release_master; |
|
3291 |
} |
|
3292 |
||
3293 |
ecrt_master_prepare(master); |
|
3294 |
||
3295 |
init_timer(&timer); |
|
3296 |
timer.function = run; |
|
3297 |
timer.expires = jiffies + 10; |
|
3298 |
add_timer(&timer); |
|
3299 |
||
3300 |
return 0; |
|
3301 |
||
3302 |
out_release_master: |
|
3303 |
ecrt_release_master(master); |
|
3304 |
out_return: |
|
3305 |
return -1; |
|
3306 |
} |
|
3307 |
\end{lstlisting} |
|
3308 |
||
3309 |
\begin{description} |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3310 |
\item[\linenum{3}] It is tried to request the |
369 | 3311 |
first EtherCAT master (index 0). On success, the |
3312 |
\textit{ecrt\_\-request\_\-master()} function returns a pointer to |
|
3313 |
the reserved master, that can be used as an object to following |
|
3314 |
functions calls. On failure, the function returns \textit{NULL}. |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3315 |
\item[\linenum{7}] In order to exchange process |
369 | 3316 |
data, a domain object has to be created. The |
3317 |
\textit{ecrt\_\-master\_\-create\_domain()} function also returns a |
|
3318 |
pointer to the created domain, or \textit{NULL} in error case. |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3319 |
\item[\linenum{11}] The registration of domain |
814 | 3320 |
Pdos with an initialization array results in a single function call. |
369 | 3321 |
Alternatively the data fields could be registered with individual |
3322 |
calls of \textit{ecrt\_domain\_register\_pdo()}. |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3323 |
\item[\linenum{16}] After the configuration of |
369 | 3324 |
process data mapping, the master can be activated for cyclic |
3325 |
operation. This will configure all slaves and bring them into |
|
379 | 3326 |
OP state. |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3327 |
\item[\linenum{20}] This call is needed to avoid |
369 | 3328 |
a case differentiation in cyclic operation: The first operation in |
3329 |
cyclic mode is a receive call. Due to the fact, that there is |
|
3330 |
nothing to receive during the first cycle, there had to be an |
|
3331 |
\textit{if}-statement to avoid a warning. A call to |
|
3332 |
\textit{ec\_master\_prepare()} sends a first datagram containing a |
|
3333 |
process data exchange datagram, so that the first receive call will |
|
3334 |
not fail. |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3335 |
\item[\linenum{22} -- \linenum{25}] The |
369 | 3336 |
master is now ready for cyclic operation. The kernel timer that |
3337 |
cyclically executes the \textit{run()} function is initialized and |
|
3338 |
started. |
|
3339 |
\end{description} |
|
3340 |
||
3341 |
The coding of a cleanup function fo the minimal module can be seen in |
|
3342 |
listing~\ref{lst:miniclean}. |
|
3343 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3344 |
\begin{lstlisting}[gobble=2,language=C,numbers=left,caption={Minimal cleanup |
369 | 3345 |
function},label={lst:miniclean}] |
3346 |
void __exit cleanup_mini_module(void) |
|
3347 |
{ |
|
3348 |
del_timer_sync(&timer); |
|
3349 |
ecrt_master_deactivate(master); |
|
3350 |
ecrt_release_master(master); |
|
3351 |
} |
|
3352 |
\end{lstlisting} |
|
3353 |
||
3354 |
\begin{description} |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3355 |
\item[\linenum{3}] To cleanup the module, it it |
369 | 3356 |
necessary to stop the cyclic processing. This is done by a call to |
3357 |
\textit{del\_timer\_sync()} which safely removes a queued timer |
|
3358 |
object. It is assured, that no cyclic work will be done after this |
|
3359 |
call returns. |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3360 |
\item[\linenum{4}] This call deactivates the |
379 | 3361 |
master, which results in all slaves being brought to their INIT |
3362 |
state again. |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3363 |
\item[\linenum{5}] This call releases the master, |
369 | 3364 |
removes any existing configuration and silently starts the idle |
3365 |
mode. The value of the master pointer is invalid after this call and |
|
3366 |
the module can be safely unloaded. |
|
3367 |
\end{description} |
|
3368 |
||
3369 |
The final part of the minimal module is that for the cyclic work. Its |
|
3370 |
coding can be seen in listing~\ref{lst:minirun}. |
|
3371 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3372 |
\begin{lstlisting}[gobble=2,language=C,numbers=left,caption={Minimal cyclic |
369 | 3373 |
function},label={lst:minirun}] |
3374 |
void run(unsigned long data) |
|
3375 |
{ |
|
3376 |
static uint8_t dig_in_0; |
|
3377 |
||
3378 |
ecrt_master_receive(master); |
|
3379 |
ecrt_domain_process(domain1); |
|
3380 |
||
3381 |
dig_in_0 = EC_READ_BIT(r_dig_in, 0); |
|
3382 |
EC_WRITE_S16(r_ana_out, dig_in_0 * 0x3FFF); |
|
3383 |
||
3384 |
ecrt_master_run(master); |
|
3385 |
ecrt_master_send(master); |
|
3386 |
||
3387 |
timer.expires += 1; // frequency = HZ |
|
3388 |
add_timer(&timer); |
|
3389 |
} |
|
3390 |
\end{lstlisting} |
|
3391 |
||
3392 |
\begin{description} |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3393 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3394 |
\item[\linenum{5}] The cyclic processing starts with receiving datagrams, that |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3395 |
were sent in the last cycle. The frames containing these datagrams have to be |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3396 |
received by the network interface card prior to this call. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3397 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3398 |
\item[\linenum{6}] The process data of domain 1 has been automatically copied |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3399 |
into domain memory while datagram reception. This call checks the working |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3400 |
counter for changes and re-queues the domain's datagram for sending. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3401 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3402 |
\item[\linenum{8}] This is an example for reading out a bit-oriented process |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3403 |
data value (i.~e. bit 0) via the \textit{EC\_READ\_BIT()} macro. See |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3404 |
section~\ref{sec:macros} for more information about those macros. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3405 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3406 |
\item[\linenum{9}] This line shows how to write a signed, 16-bit process data |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3407 |
value. In this case, the slave is able to output voltages of |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3408 |
\unit{-10--+10}{\volt} with a resolution of \unit{16}{bit}. This write command |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3409 |
outputs either \unit{0}{\volt} or \unit{+5}{\volt}, depending of the value of |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3410 |
\textit{dig\_in\_0}. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3411 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3412 |
\item[\linenum{11}] This call runs the master's operation state machine (see |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3413 |
section~\ref{sec:fsm-op}). A single state is processed, and datagrams are |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3414 |
queued. Mainly bus observation is done: The bus state is determined and in case |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3415 |
of slaves that lost their configuration, reconfiguration is tried. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3416 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3417 |
\item[\linenum{12}] This method sends all queued datagrams, in this case the |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3418 |
domain's datagram and one of the master state machine. In best case, all |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3419 |
datagrams fit into one frame. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3420 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3421 |
\item[\linenum{14} -- \linenum{15}] Kernel timers are implemented as |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3422 |
``one-shot'' timers, so they have to be re-added after each execution. The time |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3423 |
of the next execution is specified in \textit{jiffies} and will happen at the |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3424 |
time of the next system timer interrupt. This results in the \textit{run()} |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3425 |
function being executed with a frequency of \textit{HZ}. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3426 |
|
369 | 3427 |
\end{description} |
3428 |
||
3429 |
%------------------------------------------------------------------------------ |
|
3430 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3431 |
\section{RTAI Example} |
369 | 3432 |
\label{sec:rtai} |
3433 |
\index{Examples!RTAI} |
|
3434 |
||
3435 |
The whole code can be seen in the EtherCAT master code release |
|
3436 |
(see~\cite{etherlab}, file \textit{examples/rtai/rtai\_sample.c}). |
|
3437 |
||
3438 |
Listing~\ref{lst:rtaivar} shows the defines and global variables |
|
3439 |
needed for a minimal RTAI module with EtherCAT processing. |
|
3440 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3441 |
\begin{lstlisting}[gobble=2,language=C,numbers=left,caption={RTAI task |
369 | 3442 |
declaration},label={lst:rtaivar}] |
3443 |
#define FREQUENCY 10000 |
|
3444 |
#define TIMERTICKS (1000000000 / FREQUENCY) |
|
3445 |
||
3446 |
RT_TASK task; |
|
3447 |
\end{lstlisting} |
|
3448 |
||
3449 |
\begin{description} |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3450 |
\item[\linenum{1} -- \linenum{2}] RTAI |
369 | 3451 |
takes the cycle period as nanoseconds, so the easiest way is to |
3452 |
define a frequency and convert it to a cycle time in nanoseconds. |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3453 |
\item[\linenum{4}] The \textit{task} variable |
369 | 3454 |
later contains information about the running RTAI task. |
3455 |
\end{description} |
|
3456 |
||
3457 |
Listing~\ref{lst:rtaiinit} shows the module init function for the RTAI |
|
3458 |
module. Most lines are the same as in listing~\ref{lst:miniinit}, |
|
3459 |
differences come up when starting the cyclic code. |
|
3460 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3461 |
\begin{lstlisting}[gobble=2,language=C,numbers=left,caption={RTAI module init |
369 | 3462 |
function},label={lst:rtaiinit}] |
3463 |
int __init init_mod(void) |
|
3464 |
{ |
|
3465 |
RTIME requested_ticks, tick_period, now; |
|
3466 |
||
3467 |
if (!(master = ecrt_request_master(0))) { |
|
3468 |
goto out_return; |
|
3469 |
} |
|
3470 |
||
3471 |
if (!(domain1 = ecrt_master_create_domain(master))) { |
|
3472 |
goto out_release_master; |
|
3473 |
} |
|
3474 |
||
3475 |
if (ecrt_domain_register_pdo_list(domain1, |
|
3476 |
domain1_pdos)) { |
|
3477 |
goto out_release_master; |
|
3478 |
} |
|
3479 |
||
3480 |
if (ecrt_master_activate(master)) { |
|
3481 |
goto out_release_master; |
|
3482 |
} |
|
3483 |
||
3484 |
ecrt_master_prepare(master); |
|
3485 |
||
3486 |
requested_ticks = nano2count(TIMERTICKS); |
|
3487 |
tick_period = start_rt_timer(requested_ticks); |
|
3488 |
||
3489 |
if (rt_task_init(&task, run, 0, 2000, 0, 1, NULL)) { |
|
3490 |
goto out_stop_timer; |
|
3491 |
} |
|
3492 |
||
3493 |
now = rt_get_time(); |
|
3494 |
if (rt_task_make_periodic(&task, now + tick_period, |
|
3495 |
tick_period)) { |
|
3496 |
goto out_stop_task; |
|
3497 |
} |
|
3498 |
||
3499 |
return 0; |
|
3500 |
||
3501 |
out_stop_task: |
|
3502 |
rt_task_delete(&task); |
|
3503 |
out_stop_timer: |
|
3504 |
stop_rt_timer(); |
|
3505 |
out_deactivate: |
|
3506 |
ecrt_master_deactivate(master); |
|
3507 |
out_release_master: |
|
3508 |
ecrt_release_master(master); |
|
3509 |
out_return: |
|
3510 |
return -1; |
|
3511 |
} |
|
3512 |
\end{lstlisting} |
|
3513 |
||
3514 |
\begin{description} |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3515 |
\item[\linenum{24} -- \linenum{25}] The |
369 | 3516 |
nanoseconds are converted to RTAI timer ticks and an RTAI timer is |
3517 |
started. \textit{tick\_period} will be the ``real'' number of ticks |
|
3518 |
used for the timer period (which can be different to the requested |
|
3519 |
one). |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3520 |
\item[\linenum{27}] The RTAI task is initialized |
369 | 3521 |
by specifying the cyclic function, the parameter to hand over, the |
3522 |
stack size, priority, a flag that tells, if the function will use |
|
3523 |
floating point operations and a signal handler. |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3524 |
\item[\linenum{32}] The task is made periodic by |
369 | 3525 |
specifying a start time and a period. |
3526 |
\end{description} |
|
3527 |
||
3528 |
The cleanup function of the RTAI module in listing~\ref{lst:rtaiclean} |
|
3529 |
is nearly as simple as that of the minimal module. |
|
3530 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3531 |
\begin{lstlisting}[gobble=2,language=C,numbers=left,caption={RTAI module |
369 | 3532 |
cleanup function},label={lst:rtaiclean}] |
3533 |
void __exit cleanup_mod(void) |
|
3534 |
{ |
|
3535 |
rt_task_delete(&task); |
|
3536 |
stop_rt_timer(); |
|
3537 |
ecrt_master_deactivate(master); |
|
3538 |
ecrt_release_master(master); |
|
3539 |
rt_sem_delete(&master_sem); |
|
3540 |
} |
|
3541 |
\end{lstlisting} |
|
3542 |
||
3543 |
\begin{description} |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3544 |
\item[\linenum{2}] The RTAI task will be stopped |
369 | 3545 |
and deleted. |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3546 |
\item[\linenum{3}] After that, the RTAI timer can |
369 | 3547 |
be stopped. |
3548 |
\end{description} |
|
3549 |
||
3550 |
The rest is the same as for the minimal module. |
|
3551 |
||
3552 |
Worth to mention is, that the cyclic function of the RTAI module |
|
3553 |
(listing~\ref{lst:rtairun}) has a slightly different architecture. The |
|
3554 |
function is not executed until returning for every cycle, but has an |
|
3555 |
infinite loop in it, that is placed in a waiting state for the rest of |
|
3556 |
each cycle. |
|
3557 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3558 |
\begin{lstlisting}[gobble=2,language=C,numbers=left,caption={RTAI module cyclic |
369 | 3559 |
function},label={lst:rtairun}] |
3560 |
void run(long data) |
|
3561 |
{ |
|
3562 |
while (1) { |
|
3563 |
ecrt_master_receive(master); |
|
3564 |
ecrt_domain_process(domain1); |
|
3565 |
||
3566 |
k_pos = EC_READ_U32(r_ssi_input); |
|
3567 |
||
3568 |
ecrt_master_run(master); |
|
3569 |
ecrt_master_send(master); |
|
3570 |
||
3571 |
rt_task_wait_period(); |
|
3572 |
} |
|
3573 |
} |
|
3574 |
\end{lstlisting} |
|
3575 |
||
3576 |
\begin{description} |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3577 |
\item[\linenum{3}] The \textit{while (1)} loop |
369 | 3578 |
executes for the lifetime of the RTAI task. |
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3579 |
\item[\linenum{12}] The |
369 | 3580 |
\textit{rt\_task\_wait\_period()} function sets the process into a |
3581 |
sleeping state until the beginning of the next cycle. It also |
|
3582 |
checks, if the cyclic function has to be terminated. |
|
3583 |
\end{description} |
|
3584 |
||
3585 |
%------------------------------------------------------------------------------ |
|
3586 |
||
3587 |
\section{Concurrency Example} |
|
3588 |
\label{sec:concurrency} |
|
3589 |
\index{Examples!Concurrency} |
|
3590 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3591 |
As mentioned before, there can be concurrent access to the EtherCAT master. The |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3592 |
application and a EoE\index{EoE} process can compete for master access, for |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3593 |
example. In this case, the module has to provide the locking mechanism, because |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3594 |
it depends on the module's architecture which lock has to be used. The module |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3595 |
makes this locking mechanism available to the master through the master's |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3596 |
locking callbacks. |
369 | 3597 |
|
3598 |
In case of RTAI, the lock can be an RTAI semaphore, as shown in |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3599 |
listing~\ref{lst:convar}. A normal Linux semaphore would not be appropriate, |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3600 |
because it could not block the RTAI task due to RTAI running in a higher domain |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3601 |
than the Linux kernel (see~\cite{rtai}). |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3602 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3603 |
\begin{lstlisting}[gobble=2,language=C,numbers=left,caption={RTAI semaphore for |
369 | 3604 |
concurrent access},label={lst:convar}] |
3605 |
SEM master_sem; |
|
3606 |
\end{lstlisting} |
|
3607 |
||
3608 |
The module has to implement the two callbacks for requesting and |
|
3609 |
releasing the master lock. An exemplary coding can be seen in |
|
3610 |
listing~\ref{lst:conlock}. |
|
3611 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3612 |
\begin{lstlisting}[gobble=2,language=C,numbers=left,caption={RTAI locking |
369 | 3613 |
callbacks for concurrent access},label={lst:conlock}] |
3614 |
int request_lock(void *data) |
|
3615 |
{ |
|
3616 |
rt_sem_wait(&master_sem); |
|
3617 |
return 0; |
|
3618 |
} |
|
3619 |
||
3620 |
void release_lock(void *data) |
|
3621 |
{ |
|
3622 |
rt_sem_signal(&master_sem); |
|
3623 |
} |
|
3624 |
\end{lstlisting} |
|
3625 |
||
3626 |
\begin{description} |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3627 |
\item[\linenum{1}] The \textit{request\_lock()} |
369 | 3628 |
function has a data parameter. The master always passes the value, |
3629 |
that was specified when registering the callback function. This can |
|
3630 |
be used for handing the master pointer. Notice, that it has an |
|
3631 |
integer return value (see line 4). |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3632 |
\item[\linenum{3}] The call to |
369 | 3633 |
\textit{rt\_sem\_wait()} either returns at once, when the semaphore |
3634 |
was free, or blocks until the semaphore is freed again. In any case, |
|
3635 |
the semaphore finally is reserved for the process calling the |
|
3636 |
request function. |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3637 |
\item[\linenum{4}] When the lock was requested |
369 | 3638 |
successfully, the function should return 0. The module can prohibit |
3639 |
requesting the lock by returning non-zero (see paragraph ``Tuning |
|
3640 |
the jitter'' below). |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3641 |
\item[\linenum{7}] The \textit{release\_lock()} |
369 | 3642 |
function gets the same argument passed, but has a void return value, |
3643 |
because is always succeeds. |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3644 |
\item[\linenum{9}] The \textit{rt\_sem\_signal()} |
369 | 3645 |
function frees the semaphore, that was prior reserved with |
3646 |
\textit{rt\_sem\_wait()}. |
|
3647 |
\end{description} |
|
3648 |
||
3649 |
In the module's init function, the semaphore must be initialized, and |
|
3650 |
the callbacks must be passed to the EtherCAT master: |
|
3651 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3652 |
\begin{lstlisting}[gobble=2,language=C,numbers=left,caption={Module init |
369 | 3653 |
function for concurrent access},label={lst:coninit}] |
3654 |
int __init init_mod(void) |
|
3655 |
{ |
|
3656 |
RTIME tick_period, requested_ticks, now; |
|
3657 |
||
3658 |
rt_sem_init(&master_sem, 1); |
|
3659 |
||
3660 |
if (!(master = ecrt_request_master(0))) { |
|
3661 |
goto out_return; |
|
3662 |
} |
|
3663 |
||
3664 |
ecrt_master_callbacks(master, request_lock, |
|
3665 |
release_lock, NULL); |
|
3666 |
// ... |
|
3667 |
\end{lstlisting} |
|
3668 |
||
3669 |
\begin{description} |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3670 |
\item[\linenum{5}] The call to |
369 | 3671 |
\textit{rt\_sem\_init()} initializes the semaphore and sets its |
3672 |
value to 1, meaning that only one process can reserve the semaphore |
|
3673 |
without blocking. |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3674 |
\item[\linenum{11}] The callbacks are passed to |
369 | 3675 |
the master with a call to \textit{ecrt\_master\_callbacks()}. The |
3676 |
last parameter is the argument, that the master should pass with |
|
3677 |
each call to a callback function. Here it is not used and set to |
|
3678 |
\textit{NULL}. |
|
3679 |
\end{description} |
|
3680 |
||
3681 |
For the cyclic function being only one competitor for master access, |
|
3682 |
it has to request the lock like any other process. There is no need to |
|
3683 |
use the callbacks (which are meant for processes of lower priority), |
|
3684 |
so it can access the semaphore directly: |
|
3685 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3686 |
\begin{lstlisting}[gobble=2,language=C,numbers=left,caption={RTAI cyclic |
369 | 3687 |
function for concurrent access},label={lst:conrun}] |
3688 |
void run(long data) |
|
3689 |
{ |
|
3690 |
while (1) { |
|
3691 |
rt_sem_wait(&master_sem); |
|
3692 |
||
3693 |
ecrt_master_receive(master); |
|
3694 |
ecrt_domain_process(domain1); |
|
3695 |
||
3696 |
k_pos = EC_READ_U32(r_ssi_input); |
|
3697 |
||
3698 |
ecrt_master_run(master); |
|
3699 |
ecrt_master_send(master); |
|
3700 |
||
3701 |
rt_sem_signal(&master_sem); |
|
3702 |
rt_task_wait_period(); |
|
3703 |
} |
|
3704 |
} |
|
3705 |
\end{lstlisting} |
|
3706 |
||
3707 |
\begin{description} |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3708 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3709 |
\item[\linenum{4}] Every access to the master has to be preceded by a call to |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3710 |
\textit{rt\_sem\_wait()}, because another instance might currently access the |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3711 |
master. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3712 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3713 |
\item[\linenum{14}] When cyclic processing finished, the semaphore has to be |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3714 |
freed again, so that other processes have the possibility to access the master. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3715 |
|
369 | 3716 |
\end{description} |
3717 |
||
3718 |
A little change has to be made to the cleanup function in case of |
|
3719 |
concurrent master access. |
|
3720 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3721 |
\begin{lstlisting}[gobble=2,language=C,numbers=left,caption={RTAI module |
369 | 3722 |
cleanup function for concurrent access},label={lst:conclean}] |
3723 |
void __exit cleanup_mod(void) |
|
3724 |
{ |
|
3725 |
rt_task_delete(&task); |
|
3726 |
stop_rt_timer(); |
|
3727 |
ecrt_master_deactivate(master); |
|
3728 |
ecrt_release_master(master); |
|
3729 |
rt_sem_delete(&master_sem); |
|
3730 |
} |
|
3731 |
\end{lstlisting} |
|
3732 |
||
3733 |
\begin{description} |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3734 |
\item[\linenum{7}] Upon module cleanup, the |
369 | 3735 |
semaphore has to be deleted, so that memory can be freed. |
3736 |
\end{description} |
|
3737 |
||
3738 |
\paragraph{Tuning the Jitter} |
|
3739 |
\index{Jitter} |
|
3740 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3741 |
Concurrent access leads to higher jitter for the application task, because |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3742 |
there are situations, in which the task has to wait for a process of lower |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3743 |
priority to finish accessing the master. In most cases this is acceptable, |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3744 |
because a master access cycle (receive/process/send) only takes |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3745 |
\unit{10-20}{\micro\second} on recent systems, what would be the maximum |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3746 |
additional jitter. However some applications demand a minimum jitter. For this |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3747 |
reason the master access can be prohibited by the application: If the time, |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3748 |
another process wants to access the master, is to close to the beginning of the |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3749 |
next application cycle, the module can disallow, that the lock is taken. In |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3750 |
this case, the request callback has to return $1$, meaning that the lock has |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3751 |
not been taken. The foreign process must abort its master access and try again |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3752 |
next time. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3753 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3754 |
This measure helps to significantly reducing the jitter produced by concurrent |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3755 |
master access. Below are excerpts of an example coding: |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3756 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3757 |
\begin{lstlisting}[gobble=2,language=C,numbers=left,caption={Variables for |
369 | 3758 |
jitter reduction},label={lst:redvar}] |
3759 |
#define FREQUENCY 10000 // RTAI task frequency in Hz |
|
3760 |
// ... |
|
3761 |
cycles_t t_last_cycle = 0; |
|
3762 |
const cycles_t t_critical = cpu_khz * 1000 / FREQUENCY |
|
3763 |
- cpu_khz * 30 / 1000; |
|
3764 |
\end{lstlisting} |
|
3765 |
||
3766 |
\begin{description} |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3767 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3768 |
\item[\linenum{3}] The variable \textit{t\_last\_cycle} holds the timer ticks |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3769 |
at the beginning of the last realtime cycle. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3770 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3771 |
\item[\linenum{4}] \textit{t\_critical} contains the number of ticks, that may |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3772 |
have passed since the beginning of the last cycle, until there is no more |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3773 |
foreign access possible. It is calculated by subtracting the ticks for |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3774 |
\unit{30}{\micro\second} from the ticks for a complete cycle. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3775 |
|
369 | 3776 |
\end{description} |
3777 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3778 |
\begin{lstlisting}[gobble=2,language=C,numbers=left,caption={Cyclic function |
369 | 3779 |
with reduced jitter},label={lst:redrun}] |
3780 |
void run(long data) |
|
3781 |
{ |
|
3782 |
while (1) { |
|
3783 |
t_last_cycle = get_cycles(); |
|
3784 |
rt_sem_wait(&master_sem); |
|
3785 |
// ... |
|
3786 |
\end{lstlisting} |
|
3787 |
||
3788 |
\begin{description} |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3789 |
\item[\linenum{4}] The ticks of the beginning of |
369 | 3790 |
the current realtime cycle are taken before reserving the semaphore. |
3791 |
\end{description} |
|
3792 |
||
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3793 |
\begin{lstlisting}[gobble=2,language=C,numbers=left,caption={Request callback |
369 | 3794 |
for reduced jitter},label={lst:redreq}] |
3795 |
int request_lock(void *data) |
|
3796 |
{ |
|
3797 |
// too close to the next RT cycle: deny access. |
|
3798 |
if (get_cycles() - t_last_cycle > t_critical) |
|
3799 |
return -1; |
|
3800 |
||
3801 |
// allow access |
|
3802 |
rt_sem_wait(&master_sem); |
|
3803 |
return 0; |
|
3804 |
} |
|
3805 |
\end{lstlisting} |
|
3806 |
||
3807 |
\begin{description} |
|
1085
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3808 |
|
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3809 |
\item[\linenum{4}] If the time of request is too close to the next realtime |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3810 |
cycle (here: \unit{<30}{\micro\second} before the estimated beginning), the |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3811 |
locking is denied. The requesting process must abort its cycle. |
c75cdcc5ce87
Started to re-write the documentation.
Florian Pose <fp@igh-essen.com>
parents:
917
diff
changeset
|
3812 |
|
369 | 3813 |
\end{description} |
3814 |
||
3815 |
%------------------------------------------------------------------------------ |
|
3816 |
||
3817 |
\begin{thebibliography}{99} |
|
1094
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3818 |
|
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3819 |
\bibitem{etherlab} Ingenieurgemeinschaft IgH: EtherLab -- Open Source Toolkit |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3820 |
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
|
3821 |
technology. \url{http://etherlab.org/en}, 2008. |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3822 |
|
369 | 3823 |
\bibitem{dlspec} IEC 61158-4-12: Data-link Protocol Specification. |
1095 | 3824 |
International Electrotechnical Commission (IEC), 2005. |
1094
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3825 |
|
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3826 |
\bibitem{alspec} IEC 61158-6-12: Application Layer Protocol Specification. |
1095 | 3827 |
International Electrotechnical Commission (IEC), 2005. |
1094
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3828 |
|
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3829 |
\bibitem{gpl} GNU General Public License, Version 2. |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3830 |
\url{http://www.gnu.org/licenses/gpl.txt}. August~9, 2006. |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3831 |
|
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3832 |
\bibitem{lsb} Linux Standard Base. |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3833 |
\url{http://www.linuxfoundation.org/en/LSB}. August~9, 2006. |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3834 |
|
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3835 |
\bibitem{wireshark} Wireshark. \url{http://www.wireshark.org}. 2008. |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3836 |
|
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3837 |
\bibitem{automata} {\it Hopcroft, J.~E. / Ullman, J.~D.}: Introduction to |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3838 |
Automata Theory, Languages and Computation. Adison-Wesley, Reading, |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3839 |
Mass.~1979. |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3840 |
|
369 | 3841 |
\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
|
3842 |
misunderstandings. In: IEE journal ``Computing and Control Engineering'', |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3843 |
2004. |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3844 |
|
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3845 |
\bibitem{rtai} RTAI. The RealTime Application Interface for Linux from DIAPM. |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3846 |
\url{http://www.rtai.org}, 2006. |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3847 |
|
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3848 |
\bibitem{doxygen} Doxygen. Source code documentation generator tool. |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3849 |
\url{http://www.stack.nl/~dimitri/doxygen}, 2008. |
eb0258e53236
App interface; doxygen; bib.
Florian Pose <fp@igh-essen.com>
parents:
1087
diff
changeset
|
3850 |
|
369 | 3851 |
\end{thebibliography} |
3852 |
||
917
07b0ad9722a1
Fixed bug concerning listings package.
Florian Pose <fp@igh-essen.com>
parents:
814
diff
changeset
|
3853 |
\printnomenclature |
369 | 3854 |
\addcontentsline{toc}{chapter}{\nomname} |
3855 |
\markleft{\nomname} |
|
3856 |
||
3857 |
\printindex |
|
3858 |
\markleft{Index} |
|
3859 |
||
3860 |
%------------------------------------------------------------------------------ |
|
3861 |
||
3862 |
\end{document} |
|
3863 |
||
3864 |
%------------------------------------------------------------------------------ |