
diff -r 91d190223daa -r acb649738601 documentation/ethercat_doc.tex
--- a/documentation/ethercat_doc.tex	Wed Aug 13 15:51:26 2008 +0000
+++ b/documentation/ethercat_doc.tex	Thu Aug 14 15:49:00 2008 +0000
@@ -603,7 +603,7 @@
 \begin{figure}[htbp]
   \centering
   \includegraphics[width=.8\textwidth]{images/app-config}
-  \caption{Master configuration structures}
+  \caption{Master Configuration}
   \label{fig:app-config}
 \end{figure}
 
@@ -658,26 +658,12 @@
 \chapter{Ethernet Devices}
 \label{sec:devices}
 
-%   Device Interface
-%   Device Modules
-%   Network Driver Basics
-%   EtherCAT Network Drivers
-%   Device Selection
-%   The Device Interface
-%   Patching Network Drivers
-
-The EtherCAT protocol is based on the Ethernet standard, so the master relies
-on standard Ethernet hardware to communicate with the bus.
+The EtherCAT protocol is based on the Ethernet standard, so a master relies on
+standard Ethernet hardware to communicate with the bus.
 
 The term \textit{device} is used as a synonym for Ethernet network interface
 hardware. There are device driver modules that handle Ethernet hardware, which
-the master can use to connect to an EtherCAT bus.
-
-Section~\ref{sec:networkdrivers} offers an overview of general Linux
-network driver modules, while section~\ref{sec:requirements} will show
-the requirements to an EtherCAT-enabled network driver. Finally,
-sections~\ref{sec:seldev} to~\ref{sec:patching} show how to fulfill
-these requirements and implement such a driver module.
+a master can use to connect to an EtherCAT bus.
 
 %------------------------------------------------------------------------------
 
@@ -725,7 +711,7 @@
 for received frames is set, frame data has to be copied from hardware
 to kernel memory and passed to the network stack.
 
-\paragraph{The \lstinline+net_device+ structure}
+\paragraph{The \lstinline+net_device+ Structure}
 \index{net\_device}
 
 The driver registers a \lstinline+net_device+ structure for each device to
@@ -770,7 +756,7 @@
 The actual registration is done with the \lstinline+register_netdev()+ call,
 unregistering is done with \lstinline+unregister_netdev()+.
 
-\paragraph{The netif Interface}
+\paragraph{The \lstinline+netif+ Interface}
 \index{netif}
 
 All other communication in the direction interface $\to$ network stack is done
@@ -814,7 +800,7 @@
 %------------------------------------------------------------------------------
 
 \section{EtherCAT Device Drivers}
-\label{sec:requirements}
+\label{sec:ethercatdrivers}
 
 There are a few requirements for Ethernet network devices to function as
 EtherCAT devices, when connected to an EtherCAT bus.
@@ -915,7 +901,7 @@
 
 %------------------------------------------------------------------------------
 
-\section{The Device Interface}
+\section{EtherCAT Device Interface}
 \label{sec:ecdev}
 \index{Device interface}
 
@@ -1370,8 +1356,8 @@
 (re-)configured.
 
 \item[Request handling] Requests (either originating from the application or
-from external sources) are handled. This can be SII accesses, Sdo accesses,
-etc.
+from external sources) are handled. A request is a job that the master shall
+process asynchronously, for example an SII access, Sdo access, or similar.
 
 \end{description}
 
@@ -1415,23 +1401,14 @@
 State change FSM (see section~\ref{sec:fsm-change}) to enable mailbox
 communication and read the Pdo configuration via CoE.
 
-\item[Pdos] The Pdos are read via CoE (if supported) using the Pdo FSM (see
-section~\ref{sec:fsm-pdo}). If this is successful, the Pdo information from
-the SII (if any) is overwritten.
+\item[Pdos] The Pdos are read via CoE (if supported) using the Pdo Reading FSM
+(see section~\ref{sec:fsm-pdo}). If this is successful, the Pdo information
+from the SII (if any) is overwritten.
 
 \end{description}
 
 %------------------------------------------------------------------------------
 
-%     SII
-%     Pdo assign/mapping
-%   Slave configuration
-%     State change
-%     Pdo assign/mapping
-%   CoE upload/download/information
-
-%------------------------------------------------------------------------------
-
 \section{The Slave Configuration State Machine}
 \label{sec:fsm-conf}
 \index{FSM!Slave Configuration}
@@ -1499,68 +1476,41 @@
 
 \begin{figure}[htbp]
   \centering
-  \includegraphics[width=.9\textwidth]{images/fsm-change} % FIXME
+  \includegraphics[width=.6\textwidth]{graphs/fsm_change}
   \caption{Transition Diagram of the State Change State Machine}
   \label{fig:fsm-change}
 \end{figure}
 
-% FIXME
-
 \begin{description}
-\item[START] The beginning state, where a datagram with the state
-  change command is written to the slave's ``AL Control Request''
-  attribute. Nothing can fail. $\rightarrow$~CHECK
-
-\item[CHECK] After the state change datagram has been sent, the ``AL
-  Control Response'' attribute is queried with a second datagram.
-  $\rightarrow$~STATUS
-
-\item[STATUS] The read memory contents are evaluated: While the
-  parameter \textit{State} still contains the old slave state, the
-  slave is busy with reacting on the state change command. In this
-  case, the attribute has to be queried again.
-  $\rightarrow$~STATUS
-
-  In case of success, the \textit{State} parameter contains the new
-  state and the \textit{Change} bit is cleared. The slave is in the
-  requested state.  $\rightarrow$~END
-
-  If the slave can not process the state change, the \textit{Change}
-  bit is set: Now the master tries to get the reason for this by
-  querying the \textit{AL Status Code} parameter.
-  $\rightarrow$~CODE
-
-\item[END] If the state machine ends in this state, the slave's state
-  change has been successful.
-
-\item[CODE] The status code query has been sent. Reading the
-  \textit{AL Status Code} might fail, because not all slaves support
-  this parameter. Anyway, the master has to acknowledge the state
-  change error by writing the current slave state to the ``AL Control
-  Request'' attribute with the \textit{Acknowledge} bit set.
-  $\rightarrow$~ACK
-
-\item[ACK] After that, the ``AL Control Response'' attribute is
-  queried for the state of the acknowledgement.
-  $\rightarrow$~CHECK ACK
-
-\item[CHECK ACK] If the acknowledgement has been accepted by the
-  slave, the old state is kept. Still, the state change was
-  unsuccessful. $\rightarrow$~ERROR
-
-  If the acknowledgement is ignored by the slave, a timeout happens.
-  In any case, the overall state change was unsuccessful.
-  $\rightarrow$~ERROR
-
-  If there is still now response from the slave, but the timer did not
-  run out yet, the slave's ``AL Control Response'' attribute is
-  queried again.  $\rightarrow$~CHECK ACK
-
-\item[ERROR] If the state machine ends in this state, the slave's
-  state change was unsuccessful.
+
+\item[Start] The new application-layer state is requested via the ``AL Control
+Request'' register (see ~\cite[section 5.3.1]{alspec}).
+
+\item[Check for Response] Some slave need some time to respond to an AL state
+change command, and do not respond for some time. For this case, the command
+is issued again, until it is acknowledged.
+
+\item[Check AL Status] If the AL State change datagram was acknowledged, the
+``AL Control Response'' register (see~\cite[section 5.3.2]{alspec}) must be
+read out until the slave changes the AL state.
+
+\item[AL Status Code] If the slave refused the state change command, the
+reason can be read from the ``AL Status Code'' field in the ``AL State
+Changed'' registers (see~\cite[section 5.3.3]{alspec}).
+
+\item[Acknowledge State] If the state change was not successful, the master
+has to acknowledge the old state by writing to the ``AL Control request''
+register again.
+
+\item[Check Acknowledge] After sending the acknowledge command, it has to read
+out the ``AL Control Response'' register again.
 
 \end{description}
 
+The ``start\_ack'' state is a shortcut in the state machine for the case, that
+the master wants to acknowledge a spontaneous AL state change, that was not
+requested.
+
 %------------------------------------------------------------------------------
 
 \section{The SII State Machine}
@@ -1573,65 +1523,106 @@
 
 \begin{figure}[htbp]
   \centering
-  \includegraphics[width=.9\textwidth]{images/fsm-sii} % FIXME
+  \includegraphics[width=.5\textwidth]{graphs/fsm_sii}
   \caption{Transition Diagram of the SII State Machine}
   \label{fig:fsm-sii}
 \end{figure}
 
-% FIXME
+This is how the reading part of the state machine works:
 
 \begin{description}
-\item[READ\_START] The beginning state for reading access, where the
-  read request and the requested address are written to the SII
-  attribute. Nothing can fail up to now.
-  $\rightarrow$~READ\_CHECK
-
-\item[READ\_CHECK] When the SII read request has been sent
-  successfully, a timer is started. A check/fetch datagram is issued,
-  that reads out the SII attribute for state and data.
-  $\rightarrow$~READ\_FETCH
-
-\item[READ\_FETCH] Upon reception of the check/fetch datagram, the
-  \textit{Read Operation} and \textit{Busy} parameters are checked:
-  \begin{itemize}
-  \item If the slave is still busy with fetching E$^2$PROM data into
-    the interface, the timer is checked. If it timed out, the reading
-    is aborted ($\rightarrow$~ERROR), if not, the check/fetch datagram
-    is issued again. $\rightarrow$~READ\_FETCH
-
-  \item If the slave is ready with reading data, these are copied from
-    the datagram and the read cycle is completed.
-    $\rightarrow$~END
-  \end{itemize}
+
+\item[Start Reading] The read request and the requested word address are
+written to the SII attribute.
+
+\item[Check Read Command] If the SII read request command has been
+acknowledged, a timer is started. A datagram is issued, that reads out the SII
+attribute for state and data.
+
+\item[Fetch Data] If the read operation is still busy (the SII is usually
+implemented as an E$^2$PROM), the state is read again. Otherwise the data are
+copied from the datagram.
+
 \end{description}
 
-The write access states behave nearly the same:
+The writing part works nearly similar:
 
 \begin{description}
-\item[WRITE\_START] The beginning state for writing access,
-  respectively. A write request, the target address and the data word
-  are written to the SII attribute. Nothing can fail.
-  $\rightarrow$~WRITE\_CHECK
-
-\item[WRITE\_CHECK] When the SII write request has been sent
-  successfully, the timer is started. A check datagram is issued, that
-  reads out the SII attribute for the state of the write operation.
-  $\rightarrow$~WRITE\_CHECK2
-
-\item[WRITE\_CHECK2] Upon reception of the check datagram, the
-  \textit{Write Operation} and \textit{Busy} parameters are checked:
-  \begin{itemize}
-  \item If the slave is still busy with writing E$^2$PROM data, the
-    timer is checked. If it timed out, the operation is aborted
-    ($\rightarrow$~ERROR), if not, the check datagram is issued again.
-    $\rightarrow$~WRITE\_CHECK2
-  \item If the slave is ready with writing data, the write cycle is
-    completed. $\rightarrow$~END
-  \end{itemize}
+
+\item[Start Writing] A write request, the target address and the data word are
+written to the SII attribute.
+
+\item[Check Write Command] If the SII write request command has been
+acknowledged, a timer is started. A datagram is issued, that reads out the SII
+attribute for the state of the write operation.
+
+\item[Wait while Busy] If the write operation is still busy (determined by a
+minimum wait time and the state of the busy flag), the state machine remains in
+this state to avoid that another write operation is issued too early.
+
 \end{description}
 
 %------------------------------------------------------------------------------
 
+\section{The Pdo State Machines}
+\label{sec:fsm-pdo}
+\index{FSM!Pdo}
+
+The Pdo state machines are a set of state machines that read or write the Pdo
+assignment and the Pdo mapping via the ``CoE Communication Area'' described in
+\cite[section 5.6.7.4]{alspec}. For the object access, the
+CANopen-over-EtherCAT access primitives are used (see
+section~\ref{sec:coeimp}), so the slave must support the CoE mailbox protocol.
+
+\paragraph{Pdo Reading FSM} This state machine (fig.~\ref{fig:fsm-pdo-read})
+has the purpose to read the complete Pdo configuration of a slave. It reads
+the Pdo assignment for each Sync Manager and uses the Pdo Entry Reading FSM
+(fig.~\ref{fig:fsm_pdo_entry_read}) to read the mapping for each assigned Pdo.
+
+\begin{figure}[htbp]
+  \centering
+  \includegraphics[width=.4\textwidth]{graphs/fsm_pdo_read}
+  \caption{Transition Diagram of the Pdo Reading State Machine}
+  \label{fig:fsm-pdo-read}
+\end{figure}
+
+Basically it reads the every Sync manager's Pdo assignment Sdo's
+(\lstinline+0x1C1x+) number of elements to determine the number of assigned
+Pdos for this sync manager and then reads out the subindices of the Sdo to get
+the assigned Pdo's indices. When a Pdo index is read, the Pdo Entry Reading
+FSM is executed to read the Pdo's mapped Pdo entries.
+
+\paragraph{Pdo Entry Reading FSM} This state machine
+(fig.~\ref{fig:fsm_pdo_entry_reading}) reads the Pdo mapping (the Pdo entries)
+of a Pdo. It reads the respective mapping Sdo (\lstinline+0x1600+ -
+\lstinline+0x17ff+, or \lstinline+0x1a00+ - \lstinline+0x1bff+) for the given
+Pdo by reading first the subindex zero (number of elements) to determine the
+number of mapped Pdo entries. After that, each subindex is read to get the
+mapped Pdo entry index, subindex and bit size.
+
+\begin{figure}[htbp]
+  \centering
+  \includegraphics[width=.4\textwidth]{graphs/fsm_pdo_entry_read}
+  \caption{Transition Diagram of the Pdo Entry Reading State Machine}
+  \label{fig:fsm-pdo-read}
+\end{figure}
+
+\begin{figure}[htbp]
+  \centering
+  \includegraphics[width=.9\textwidth]{graphs/fsm_pdo_conf}
+  \caption{Transition Diagram of the Pdo Configuration State Machine}
+  \label{fig:fsm-pdo-read}
+\end{figure}
+
+\begin{figure}[htbp]
+  \centering
+  \includegraphics[width=.4\textwidth]{graphs/fsm_pdo_entry_conf}
+  \caption{Transition Diagram of the Pdo Entry Configuration State Machine}
+  \label{fig:fsm-pdo-read}
+\end{figure}
+
+%------------------------------------------------------------------------------
+
 \chapter{Mailbox Protocol Implementations}
 \index{Mailbox}
 
@@ -1807,6 +1798,14 @@
 configure slaves and exchange data objects on application level.
 
 % FIXME
+%
+% Download / Upload
+% Expedited / Normal
+% Segmentung
+% Sdo Info Services
+%
+
+\ldots
 
 \paragraph{Sdo Download State Machine}
 
@@ -1874,28 +1873,27 @@
 
 % FIXME
 
-For the master runs as a kernel module, accessing it is natively
-limited to analyzing Syslog messages and controlling using modutils.
-
-It is necessary to implement further interfaces, that make it easier
-to access the master from user space and allow a finer influence. It
-should be possible to view and to change special parameters at runtime.
-
-Bus visualization is a second point: For development and debugging
-purposes it would be nice, if one could show the connected slaves with
-a single command.
-
-Another aspect is automatic startup and configuration. If the master
-is to be integrated into a running system, it must be able to
-automatically start with a persistent configuration.
-
-A last thing is monitoring EtherCAT communication. For debugging
-purposes, there had to be a way to analyze EtherCAT datagrams. The
-best way would be with a popular network analyzer, like Wireshark
-\cite{wireshark} (the former Ethereal) or others.
-
-This section covers all those points and introduces the interfaces and
-tools to make all that possible.
+For the master runs as a kernel module, accessing it is natively limited to
+analyzing Syslog messages and controlling using modutils.
+
+It is necessary to implement further interfaces, that make it easier to access
+the master from user space and allow a finer influence. It should be possible
+to view and to change special parameters at runtime.
+
+Bus visualization is a second point: For development and debugging purposes it
+would be nice, if one could show the connected slaves with a single command.
+
+Another aspect is automatic startup and configuration. If the master is to be
+integrated into a running system, it must be able to automatically start with
+a persistent configuration.
+
+A last thing is monitoring EtherCAT communication. For debugging purposes,
+there had to be a way to analyze EtherCAT datagrams. The best way would be
+with a popular network analyzer, like Wireshark \cite{wireshark} (the former
+Ethereal) or others.
+
+This section covers all those points and introduces the interfaces and tools
+to make all that possible.
 
 %------------------------------------------------------------------------------
 




