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. %------------------------------------------------------------------------------