# HG changeset patch
# User Florian Pose <fp@igh-essen.com>
# Date 1249377016 0
# Node ID b99f2f9cb73f7cc879c03737de87aff9542f24b6
# Parent  e3b09f847512a4f1dcf967ef0a8074c3e0ba66b7
DC documentation; new callback mechanism; cstruct

diff -r e3b09f847512 -r b99f2f9cb73f documentation/ethercat_doc.tex
--- a/documentation/ethercat_doc.tex	Tue Aug 04 07:54:16 2009 +0000
+++ b/documentation/ethercat_doc.tex	Tue Aug 04 09:10:16 2009 +0000
@@ -18,6 +18,7 @@
 \usepackage{listings}
 \usepackage{svn}
 \usepackage{SIunits}
+\usepackage{amsmath} % for \text{}
 \usepackage{hyperref}
 
 \hypersetup{pdfpagelabels,plainpages=false}
@@ -227,6 +228,20 @@
 
   \end{itemize}
 
+\item Distributed Clocks support (see sec.~\ref{sec:dc}).
+
+  \begin{itemize}
+
+  \item Configuration of the slave's DC parameters through the application
+  interface.
+
+  \item Synchronization (offset and drift compensation) of the distributed
+  slave clocks to the reference clock.
+
+  \item Optional synchronization of the reference clock to the master clock.
+
+  \end{itemize}
+
 \item CANopen over EtherCAT (CoE)
 
   \begin{itemize}
@@ -268,7 +283,7 @@
 
   \end{itemize}
 
-\item Userspace command-line-tool ``ethercat`` (see sec.~\ref{sec:tool})
+\item Userspace command-line-tool ``ethercat'' (see sec.~\ref{sec:tool})
 
   \begin{itemize}
 
@@ -283,7 +298,7 @@
   \item Access to slave registers.
   \item Slave SII (EEPROM) access.
   \item Controlling application-layer states.
-  \item Generation of slave description XML from existing slaves.
+  \item Generation of slave description XML and C-code from existing slaves.
 
   \end{itemize}
 
@@ -773,10 +788,10 @@
 be sufficient. For that, an important design decision was made: The
 application that reserved a master must have the total control, therefore it
 has to take responsibility for providing the appropriate locking mechanisms.
-If another instance wants to access the master, it has to request the master
-lock by callbacks, that have to be set by the application. Moreover the
-application can deny access to the master if it considers it to be awkward at
-the moment.
+If another instance wants to access the master, it has to request the bus
+access via callbacks, that have to be provided by the application. Moreover
+the application can deny access to the master if it considers it to be awkward
+at the moment.
 
 \begin{figure}[htbp]
   \centering
@@ -788,10 +803,126 @@
 Figure~\ref{fig:locks} exemplary shows, how two processes share one master:
 The application's cyclic task uses the master for process data exchange, while
 the master-internal EoE process uses it to communicate with EoE-capable
-slaves.  Both have to acquire the master lock before access: The application
-task can access the lock natively, while the EoE process has to use the
-callbacks. See the application interface documentation (chap.~\ref{chap:api})
-for how to use the locking callbacks.
+slaves. Both have to access the bus from time to time, but the EoE process
+does this by ``asking'' the application to do the bus access for it. In this
+way, the application can use the appropriate locking mechanism to avoid
+accessing the bus at the same time. See the application interface
+documentation (chap.~\ref{chap:api}) for how to use these callbacks.
+
+%------------------------------------------------------------------------------
+
+\section{Distributed Clocks}
+\label{sec:dc}
+\index{Distributed Clocks}
+
+From version 1.5, the master supports EtherCAT's ``Distributed Clocks''
+feature. It is possible to synchronize the slave clocks on the bus to the
+``reference clock'' (which is the local clock of the first slave with DC
+support) and to synchronize the reference clock to the ``master clock'' (which
+is the local clock of the master). All other clocks on the bus (after the
+reference clock) are considered as ``slave clocks'' (see fig.~\ref{fig:dc}).
+
+\begin{figure}[htbp]
+  \centering
+  \includegraphics[width=.8\textwidth]{images/dc}
+  \caption{Distributed Clocks}
+  \label{fig:dc}
+\end{figure}
+
+\paragraph{Local Clocks} Any EtherCAT slave that supports DC has a local clock
+register with nanosecond resolution. If the slave is powered, the clock starts
+from zero, meaning that when slaves are powered on at different times, their
+clocks will have different values. These ``offsets'' have to be compensated by
+the distributed clocks mechanism. On the other hand, the clocks do not run
+exactly with the same speed, since the used quarts units have a natural
+frequency deviation. This deviation is usually very small, but over longer
+periods, the error would accumulate and the difference between local clocks
+would grow. This clock ``drift'' has also to be compensated by the DC
+mechanism.
+
+\paragraph{Application Time} The common time base for the bus has to be
+provided by the application. This application time $t_\text{app}$ is used
+
+\begin{enumerate}
+\item to configure the slaves' clock offsets (see below),
+\item to program the slave's start times for sync pulse generation (see
+below).
+\item to synchronize the reference clock to the master clock (optional).
+\end{enumerate}
+
+\paragraph{Offset Compensation} For the offset compensation, each slave
+provides a ``System Time Offset'' register $t_\text{off}$, that is added to
+the internal clock value $t_\text{int}$ to get the ``System Time''
+$t_\text{sys}$:
+
+\begin{eqnarray}
+t_\text{sys} & = & t_\text{int} + t_\text{off} \\
+\Rightarrow t_\text{int} & = & t_\text{sys} - t_\text{off} \nonumber
+\end{eqnarray}
+
+The master reads the values of both registers to calculate a new system time
+offset in a way, that the resulting system time shall match the master's
+application time $t_\text{app}$:
+
+\begin{eqnarray}
+t_\text{sys} & \stackrel{!}{=} & t_\text{app} \\
+\Rightarrow t_\text{int} + t_\text{off} & \stackrel{!}{=} & t_\text{app} \nonumber \\
+\Rightarrow t_\text{off} & = & t_\text{app} - t_\text{int} \nonumber \\
+\Rightarrow t_\text{off} & = & t_\text{app} - (t_\text{sys} - t_\text{off}) \nonumber \\
+\Rightarrow t_\text{off} & = & t_\text{app} - t_\text{sys} + t_\text{off}
+\end{eqnarray}
+
+The small time offset error resulting from the different times of reading and
+writing the registers will be compensated by the drift compensation.
+
+\paragraph{Drift Compensation} The drift compensation is possible due to a
+special mechanism in each DC-capable slave: A write operation to the ``System
+time'' register will cause the internal time control loop to compare the
+written time (minus the programmed transmission delay, see below) to the
+current system time. The calculated time error will be used as an input to the
+time controller, that will tune the local clock speed to be a little faster or
+slower\footnote{The local slave clock will be incremented either with
+\unit{9}{\nano\second}, \unit{10}{\nano\second} or \unit{11}{\nano\second}
+every \unit{10}{\nano\second}.}, according to the sign of the error.
+
+\paragraph{Transmission Delays} The Ethernet frame needs a small amount of
+time to get from slave to slave. The resulting transmission delay times
+accumulate on the bus and can reach microsecond magnitude and thus have to be
+considered during the drift compensation. EtherCAT slaves supporting DC
+provide a mechanism to measure the transmission delays: For each of the four
+slave ports there is a receive time register. A write operation to the receive
+time register of port 0 starts the measuring and the current system time is
+latched and stored in a receive time register once the frame is received on
+the corresponding port. The master can read out the relative receive times,
+then calculate time delays between the slaves (using its knowledge of the bus
+topology), and finally calculate the time delays from the reference clock to
+each slave. These values are programmed into the slaves' transmission delay
+registers. In this way, the drift compensation can reach nanosecond synchrony. 
+
+\paragraph{Checking Synchrony} DC-capable slaves provide the 32-bit ``System
+time difference'' register at address \lstinline+0x092c+, where the system
+time difference of the last drift compensation is stored in nanosecond
+resolution and in sign-and-magnitude coding\footnote{This allows
+broadcast-reading all system time difference registers on the bus to get an
+upper approximation}. To check for bus synchrony, the system time difference
+registers can also be cyclically read via the command-line-tool (see
+sec.~\ref{sec:regaccess}):
+
+\begin{lstlisting}
+$ `\textbf{watch -n0 "ethercat reg\_read -p4 -tint32 0x92c"}`
+\end{lstlisting}
+
+\paragraph{Sync Signals} Synchronous clocks are only the prerequisite for
+synchronous events on the bus. Each slave with DC support provides two ``sync
+signals'', that can be programmed to create events, that will for example
+cause the slave application to latch its inputs on a certain time. A sync
+event can either be generated once or cyclically, depending on what makes
+sense for the slave application. Programming the sync signals is a matter of
+setting the so-called ``AssignActivate'' word and the sync signals' cycle- and
+shift times. The AssignActivate word is slave-specific and has to be taken
+from the XML slave description (\lstinline+Device+ $\rightarrow$
+\lstinline+Dc+), where also typical sync signal configurations ``OpModes'' can
+be found.
 
 %------------------------------------------------------------------------------
 
@@ -2155,6 +2286,7 @@
 %------------------------------------------------------------------------------
 
 \subsection{Register Access}
+\label{sec:regaccess}
 
 \lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_reg_read}
 
@@ -2322,10 +2454,10 @@
 sec.~\ref{sec:cdev}).
 
 The function calls of the kernel API are mapped to the userspace via an
-\lstinline+ioctl()+ interface. Each function has its own \lstinline+ioctl()+
-call. The kernel part of the interface calls the according API functions
-directly, what results in a minimum additional delay (see
-sec.~\ref{sec:usertiming}).
+\lstinline+ioctl()+ interface. The userspace API functions share a set of
+generic \lstinline+ioctl()+ calls. The kernel part of the interface calls the
+according API functions directly, what results in a minimum additional delay
+(see sec.~\ref{sec:usertiming}).
 
 For performance reasons, the actual domain process data (see
 sec.~\ref{sec:processdata}) are not copied between kernel and user memory on
diff -r e3b09f847512 -r b99f2f9cb73f documentation/images/Makefile
--- a/documentation/images/Makefile	Tue Aug 04 07:54:16 2009 +0000
+++ b/documentation/images/Makefile	Tue Aug 04 09:10:16 2009 +0000
@@ -8,6 +8,7 @@
 	app-config.fig \
 	architecture.fig \
 	attach.fig \
+	dc.fig \
 	fmmus.fig \
 	fsm-coedown.fig \
 	fsm-eoe.fig \
diff -r e3b09f847512 -r b99f2f9cb73f documentation/images/dc.fig
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/documentation/images/dc.fig	Tue Aug 04 09:10:16 2009 +0000
@@ -0,0 +1,136 @@
+#FIG 3.2
+Portrait
+Center
+Metric
+A4      
+100.00
+Single
+-2
+1200 2
+6 1215 1035 1755 1575
+1 3 0 1 0 7 50 -1 20 0.000 1 0.0000 1485 1305 225 225 1485 1305 1710 1305
+1 3 0 1 7 7 48 -1 20 0.000 1 0.0000 1485 1305 162 162 1485 1305 1647 1305
+1 3 0 1 7 0 47 -1 20 0.000 1 0.0000 1485 1305 23 23 1485 1305 1508 1305
+2 1 0 1 0 7 49 -1 -1 0.000 0 0 -1 0 0 2
+	 1485 1080 1485 1530
+2 1 0 1 0 7 49 -1 -1 0.000 0 0 -1 0 0 2
+	 1598 1110 1372 1500
+2 1 0 1 0 7 49 -1 -1 0.000 0 0 -1 0 0 2
+	 1680 1193 1290 1417
+2 1 0 1 0 7 49 -1 -1 0.000 0 0 -1 0 0 2
+	 1710 1305 1260 1305
+2 1 0 1 0 7 49 -1 -1 0.000 0 0 -1 0 0 2
+	 1680 1418 1290 1193
+2 1 0 1 0 7 49 -1 -1 0.000 0 0 -1 0 0 2
+	 1598 1500 1373 1110
+2 1 0 1 0 7 47 -1 -1 0.000 0 0 -1 0 0 2
+	 1485 1305 1530 1125
+2 1 0 1 0 7 47 -1 -1 0.000 0 0 -1 0 0 2
+	 1485 1305 1575 1260
+-6
+6 4950 1890 5490 2430
+1 3 0 1 0 7 50 -1 20 0.000 1 0.0000 5220 2160 225 225 5220 2160 5445 2160
+1 3 0 1 7 7 48 -1 20 0.000 1 0.0000 5220 2160 162 162 5220 2160 5382 2160
+1 3 0 1 7 0 47 -1 20 0.000 1 0.0000 5220 2160 23 23 5220 2160 5243 2160
+2 1 0 1 0 7 49 -1 -1 0.000 0 0 -1 0 0 2
+	 5220 1935 5220 2385
+2 1 0 1 0 7 49 -1 -1 0.000 0 0 -1 0 0 2
+	 5333 1965 5107 2355
+2 1 0 1 0 7 49 -1 -1 0.000 0 0 -1 0 0 2
+	 5415 2048 5025 2272
+2 1 0 1 0 7 49 -1 -1 0.000 0 0 -1 0 0 2
+	 5445 2160 4995 2160
+2 1 0 1 0 7 49 -1 -1 0.000 0 0 -1 0 0 2
+	 5415 2273 5025 2048
+2 1 0 1 0 7 49 -1 -1 0.000 0 0 -1 0 0 2
+	 5333 2355 5108 1965
+2 1 0 1 0 7 47 -1 -1 0.000 0 0 -1 0 0 2
+	 5220 2160 5265 1980
+2 1 0 1 0 7 47 -1 -1 0.000 0 0 -1 0 0 2
+	 5220 2160 5310 2115
+-6
+6 6030 1305 7380 2475
+6 6795 1890 7335 2430
+1 3 0 1 0 7 50 -1 20 0.000 1 0.0000 7065 2160 225 225 7065 2160 7290 2160
+1 3 0 1 7 7 48 -1 20 0.000 1 0.0000 7065 2160 162 162 7065 2160 7227 2160
+1 3 0 1 7 0 47 -1 20 0.000 1 0.0000 7065 2160 23 23 7065 2160 7088 2160
+2 1 0 1 0 7 49 -1 -1 0.000 0 0 -1 0 0 2
+	 7065 1935 7065 2385
+2 1 0 1 0 7 49 -1 -1 0.000 0 0 -1 0 0 2
+	 7178 1965 6952 2355
+2 1 0 1 0 7 49 -1 -1 0.000 0 0 -1 0 0 2
+	 7260 2048 6870 2272
+2 1 0 1 0 7 49 -1 -1 0.000 0 0 -1 0 0 2
+	 7290 2160 6840 2160
+2 1 0 1 0 7 49 -1 -1 0.000 0 0 -1 0 0 2
+	 7260 2273 6870 2048
+2 1 0 1 0 7 49 -1 -1 0.000 0 0 -1 0 0 2
+	 7178 2355 6953 1965
+2 1 0 1 0 7 47 -1 -1 0.000 0 0 -1 0 0 2
+	 7065 2160 7110 1980
+2 1 0 1 0 7 47 -1 -1 0.000 0 0 -1 0 0 2
+	 7065 2160 7155 2115
+-6
+2 4 0 1 0 7 51 -1 20 0.000 0 0 8 0 0 5
+	 7380 2475 6030 2475 6030 1305 7380 1305 7380 2475
+4 1 0 49 -1 16 16 0.0000 4 180 810 6705 1665 Slave 2\001
+-6
+6 7875 1305 9225 2475
+6 8640 1890 9180 2430
+1 3 0 1 0 7 50 -1 20 0.000 1 0.0000 8910 2160 225 225 8910 2160 9135 2160
+1 3 0 1 7 7 48 -1 20 0.000 1 0.0000 8910 2160 162 162 8910 2160 9072 2160
+1 3 0 1 7 0 47 -1 20 0.000 1 0.0000 8910 2160 23 23 8910 2160 8933 2160
+2 1 0 1 0 7 49 -1 -1 0.000 0 0 -1 0 0 2
+	 8910 1935 8910 2385
+2 1 0 1 0 7 49 -1 -1 0.000 0 0 -1 0 0 2
+	 9023 1965 8797 2355
+2 1 0 1 0 7 49 -1 -1 0.000 0 0 -1 0 0 2
+	 9105 2048 8715 2272
+2 1 0 1 0 7 49 -1 -1 0.000 0 0 -1 0 0 2
+	 9135 2160 8685 2160
+2 1 0 1 0 7 49 -1 -1 0.000 0 0 -1 0 0 2
+	 9105 2273 8715 2048
+2 1 0 1 0 7 49 -1 -1 0.000 0 0 -1 0 0 2
+	 9023 2355 8798 1965
+2 1 0 1 0 7 47 -1 -1 0.000 0 0 -1 0 0 2
+	 8910 2160 8955 1980
+2 1 0 1 0 7 47 -1 -1 0.000 0 0 -1 0 0 2
+	 8910 2160 9000 2115
+-6
+2 4 0 1 0 7 51 -1 20 0.000 0 0 8 0 0 5
+	 9225 2475 7875 2475 7875 1305 9225 1305 9225 2475
+4 1 0 49 -1 16 16 0.0000 4 180 810 8550 1665 Slave n\001
+-6
+2 4 0 1 0 7 51 -1 20 0.000 0 0 8 0 0 5
+	 1800 1620 450 1620 450 450 1800 450 1800 1620
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 1800 1080 2340 1935
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 3690 1935 4185 1935
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
+	1 1 1.00 60.00 120.00
+	 1125 1935 1350 1530
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
+	1 1 1.00 60.00 120.00
+	 4860 2880 5094 2391
+2 4 0 1 0 7 51 -1 20 0.000 0 0 8 0 0 5
+	 5535 2475 4185 2475 4185 1305 5535 1305 5535 2475
+2 4 0 1 0 7 51 -1 20 0.000 0 0 8 0 0 5
+	 3690 2475 2340 2475 2340 1305 3690 1305 3690 2475
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2
+	 5535 1935 6030 1935
+2 1 1 1 0 7 50 -1 -1 4.000 0 0 -1 0 0 2
+	 7380 1935 7875 1935
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
+	1 1 1.00 60.00 120.00
+	 8370 2880 8730 2385
+2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
+	1 1 1.00 60.00 120.00
+	 7470 2880 7224 2391
+4 1 0 49 -1 16 16 0.0000 4 180 735 1125 810 Master\001
+4 1 0 50 -1 16 16 0.0000 4 180 1800 4860 3105 Reference Clock\001
+4 1 0 50 -1 16 16 0.0000 4 180 1410 1125 2250 Master Clock\001
+4 1 0 49 -1 16 16 0.0000 4 180 810 4860 1665 Slave 1\001
+4 1 0 49 -1 16 16 0.0000 4 180 810 3015 1665 Slave 0\001
+4 1 0 49 -1 16 10 0.0000 4 150 615 3015 2205 (No DC)\001
+4 1 0 50 -1 16 16 0.0000 4 180 1395 7920 3105 Slave Clocks\001