etherlabmaster: comparison documentation/ethercat

equal deleted inserted replaced

-:d1adfbdfa2a2
+:0fd56b9fbd38
 \end{description}
 %------------------------------------------------------------------------------
-\section{General Behavior} % FIXME
+\section{General Behavior}
 \index{Master behavior}
 \ldots
-%   Behavior (Scanning) TODO
+% TODO Behavior (Scanning)
 %------------------------------------------------------------------------------
 \section{Master Module}
 \label{sec:mastermod}
 \chapter{Application Interface}
 \label{chap:api}
 \index{Application interface}
-%   Interface version
+% TODO
-%   Master Requesting and Releasing
+%
-%   Master Locking
+% Interface version
-%   Configuring Pdo assignment and mapping
+% Master Requesting and Releasing
-%   Domains (memory)
+% Master Locking
-%   Pdo entry registration
+% Configuring Pdo assignment and mapping
-%   Sdo configuration
+% Domains (memory)
-%   Sdo access
+% Pdo entry registration
+% Sdo configuration
+% Sdo access
 The application interface provides functions and data structures for
 applications to access an EtherCAT master. The complete documentation of the
 interface is included as Doxygen~\cite{doxygen} comments in the header file
 \textit{include/ecrt.h}. It can either be read directly from the file
 To enter cyclic operation mode, the master has to be ``activated'' to
 calculate the process data image and apply the bus configuration for the first
 time. After activation, the application is in charge to send and receive
 frames.
-% TODO PDOS endianess
+% TODO
-% TODO Datagram injection
+%
+% PDO endianess
+% Datagram injection
 %------------------------------------------------------------------------------
 \section{Concurrent Master Access}
 \label{sec:concurr}
 \item[\usebox\boxopen] This function is called when network communication has
 to be started, for example after a command \lstinline+ip link set ethX up+
 from userspace. Frame reception has to be enabled by the driver.
-\item[\usebox\boxstop] The purpose of this callback is to ``close'' the device,
+\item[\usebox\boxstop] The purpose of this callback is to ``close'' the
-i.~e.  make the hardware stop receiving frames.
+device, i.~e. make the hardware stop receiving frames.
 \item[\usebox\boxxmit] This function is called for each frame that has to be
 transmitted. The network stack passes the frame as a pointer to an
 \lstinline+sk_buff+ structure (``socket buffer''\index{Socket buffer}, see
 below), which has to be freed after sending.
 The documentation of the device interface can be found in the header file or
 in the appropriate module of the interface documentation (see
 sec.~\ref{sec:gendoc} for generation instructions).
-\ldots % FIXME general description of the device interface
+% TODO general description of the device interface
 %------------------------------------------------------------------------------
 \section{Patching Network Drivers}
 \label{sec:patching}
 \index{CoE}
 The CANopen-over-EtherCAT protocol \cite[sec.~5.6]{alspec} is used to
 configure slaves and exchange data objects on application level.
-% FIXME
+% TODO
 %
 % Download / Upload
 % Expedited / Normal
 % Segmenting
 % Sdo Info Services
 %------------------------------------------------------------------------------
 \section{Command-line Tool}
 \label{sec:tool}
-% --master
+% TODO --master
 \subsection{Character Devices}
 \label{sec:cdev}
 Each master instance will get a character device as a userspace interface.
 \subsection{Bus Cycle Measuring}
 \label{sec:timing-bus}
 \index{Bus cycle}
-For measuring the time, a frame is ``on the wire'', two timestamps
+For measuring the time, a frame is ``on the wire'', two timestamps must be
-must be be taken:
+taken:
 \begin{enumerate}
-\item The time, the Ethernet hardware begins with physically sending
-the frame.
+\item The time, the Ethernet hardware begins with physically sending the
-\item The time, the frame is completely received by the Ethernet
+frame.
-hardware.
+\item The time, the frame is completely received by the Ethernet hardware.
 \end{enumerate}
 Both times are difficult to determine. The first reason is, that the
-interrupts are disabled and the master is not notified, when a frame
+interrupts are disabled and the master is not notified, when a frame is sent
-is sent or received (polling would distort the results). The second
+or received (polling would distort the results). The second reason is, that
-reason is, that even with interrupts enabled, the time from the event
+even with interrupts enabled, the time from the event to the notification is
-to the notification is unknown. Therefore the only way to confidently
+unknown. Therefore the only way to confidently determine the bus cycle time is
-determine the bus cycle time is an electrical measuring.
+an electrical measuring.
 Anyway, the bus cycle time is an important factor when designing realtime
 code, because it limits the maximum frequency for the cyclic task of the
 application.  In practice, these timing parameters are highly dependent on the
 hardware and often a trial and error method must be used to determine the
 limits of the system.
 The central question is: What happens, if the cycle frequency is too high? The
-answer is, that the EtherCAT frames that have been sent at the end of the cycle
+answer is, that the EtherCAT frames that have been sent at the end of the
-are not yet received, when the next cycle starts.  First this is noticed by
+cycle are not yet received, when the next cycle starts.  First this is noticed
-\textit{ecrt\_domain\_process()}, because the working counter of the process
+by \textit{ecrt\_domain\_process()}, because the working counter of the
-data datagrams were not increased. The function will notify the user via
+process data datagrams were not increased. The function will notify the user
-Syslog\footnote{To limit Syslog output, a mechanism has been implemented, that
+via Syslog\footnote{To limit Syslog output, a mechanism has been implemented,
-outputs a summarized notification at maximum once a second.}. In this case, the
+that outputs a summarized notification at maximum once a second.}. In this
-process data keeps being the same as in the last cycle, because it is not
+case, the process data keeps being the same as in the last cycle, because it
-erased by the domain. When the domain datagrams are queued again, the master
+is not erased by the domain. When the domain datagrams are queued again, the
-notices, that they are already queued (and marked as sent). The master will
+master notices, that they are already queued (and marked as sent). The master
-mark them as unsent again and output a warning, that datagrams were
+will mark them as unsent again and output a warning, that datagrams were
 ``skipped''.
 On the mentioned \unit{2.0}{\giga\hertz} system, the possible cycle frequency
 can be up to \unit{25}{\kilo\hertz} without skipped frames. This value can
-surely be increased by choosing faster hardware. Especially the RealTek network
+surely be increased by choosing faster hardware. Especially the RealTek
-hardware could be replaced by a faster one. Besides, implementing a dedicated
+network hardware could be replaced by a faster one. Besides, implementing a
-ISR for EtherCAT devices would also contribute to increasing the latency. These
+dedicated ISR for EtherCAT devices would also contribute to increasing the
-are two points on the author's to-do list.
+latency. These are two points on the author's to-do list.
 %------------------------------------------------------------------------------
 \chapter{Installation}
 \label{sec:installation}
 to set the \lstinline+MASTER0_DEVICE+ variable to the MAC address of the
 Ethernet device to use (or \lstinline+ff:ff:ff:ff:ff:ff+ to use the first
 device offered) and selecting the driver(s) to load via the
 \lstinline+DEVICE_MODULES+ variable.
-After the basic configuration is done, the master can be started with
+After the basic configuration is done, the master can be started with the
-the below command:
+below command:
 \begin{lstlisting}
 # `\textbf{/etc/init.d/ethercat start}`
 \end{lstlisting}

branch	stable-1.4
changeset 1664	0fd56b9fbd38
parent 1663	d1adfbdfa2a2
child 1665	c2dae2d88d31