etherlabmaster: comparison documentation/ethercat

equal deleted inserted replaced

-:bf0d42ca5aec
+:5b82b6b39c2d
 \usepackage{graphicx}
 \usepackage{makeidx}
 \usepackage[refpage]{nomencl}
 \usepackage{listings}
 \usepackage{svn}
-\usepackage{textcomp}
-\usepackage{url}
 \usepackage{SIunits}
 \usepackage{hyperref}
 \hypersetup{pdfpagelabels,plainpages=false}
 \hypersetup{linkcolor=blue,colorlinks=true,urlcolor=blue}
 \begin{itemize}
 \item The Ethernet hardware is operated without interrupts.
 \item Drivers for additional Ethernet hardware can easily be implemented
-using the common device interface (see section~\ref{sec:ecdev}) provided by
+using the common device interface (see sec.~\ref{sec:ecdev}) provided by the
-the master module.
+master module.
 \end{itemize}
 \item The master module supports multiple EtherCAT masters running in
 parallel.
 \item It runs well even without realtime extensions.
 \end{itemize}
 \item Common ``Application Interface'' for applications, that want to use
-EtherCAT functionality (see chap.~\ref{sec:ecrt}).
+EtherCAT functionality (see chap.~\ref{chap:api}).
 \item \textit{Domains} are introduced, to allow grouping of process
 data transfers with different slave groups and task periods.
 \begin{itemize}
 \item Natively supports either a switched or a routed EoE network
 architecture.
 \end{itemize}
-\item Userspace command-line-tool ``ethercat`` (see
+\item Userspace command-line-tool ``ethercat`` (see sec.~\ref{sec:tool})
-section~\ref{sec:ethercat})
 \begin{itemize}
 \item Showing the current bus with slaves, Pdos and Sdos.
 \item Showing the bus configuration.
 Public License (GPL \cite{gpl})\index{GPL}, version 2. Other developers, that
 want to use EtherCAT with Linux systems, are invited to use the master code or
 even participate on development.
 To allow static linking of userspace application against the master's
-application interface (see chap.~\ref{sec:ecrt}), the userspace library (see
+application interface (see chap.~\ref{chap:api}), the userspace library (see
 sec.~\ref{sec:userlib}) is licensed under the terms and conditions of the GNU
 Lesser General Public License (LGPL \cite{lgpl})\index{LGPL}, version 2.1.
 %------------------------------------------------------------------------------
 \paragraph{Master Module}
 \index{Master module}
 Kernel module containing one or more EtherCAT master instances (see
-section~\ref{sec:mastermod}), the ``Device Interface'' (see
+sec.~\ref{sec:mastermod}), the ``Device Interface'' (see sec.~\ref{sec:ecdev})
-section~\ref{sec:ecdev}) and the ``Application Interface'' (see
+and the ``Application Interface'' (see chap.~\ref{chap:api}).
-chap.~\ref{sec:ecrt}).
 \paragraph{Device Modules}
 \index{Device modules}
 EtherCAT-capable Ethernet device driver modules\index{Device modules}, that
 offer their devices to the EtherCAT master via the device interface (see
-section~\ref{sec:ecdev}). These modified network drivers can handle network
+sec.~\ref{sec:ecdev}). These modified network drivers can handle network
 devices used for EtherCAT operation and ``normal'' Ethernet devices in
 parallel. A master can accept a certain device and then is able to send and
 receive EtherCAT frames. Ethernet devices declined by the master module are
 connected to the kernel's network stack as usual.
 Kernel modules, that use the EtherCAT master (usually for cyclic exchange of
 process data with EtherCAT slaves). These modules are not part of the EtherCAT
 master code\footnote{Although there are some examples provided in the
 \textit{examples/} directory.}, but have to be generated or written by the
 user. An application module can ``request'' a master through the application
-interface (see chap.~\ref{sec:ecrt}). If this succeeds, the module has the
+interface (see chap.~\ref{chap:api}). If this succeeds, the module has the
 control over the master: It can provide a bus configuration and exchange
 process data.
 %------------------------------------------------------------------------------
 master still waits for its Ethernet device to connect. No bus communication is
 possible until then.
 \item[Idle phase]\index{Idle phase} takes effect when the master has accepted
 an Ethernet device, but is not requested by any application yet. The master
-runs its state machine (see section~\ref{sec:fsm-master}), that automatically
+runs its state machine (see sec.~\ref{sec:fsm-master}), that automatically
 scans the bus for slaves and executes pending operations from the userspace
 interface (for example Sdo access). The command-line tool can be used to
 access the bus, but there is no process data exchange because of the missing
 bus configuration.
 \end{lstlisting}
 The two masters can be addressed by their indices 0 and 1 respectively (see
 figure~\ref{fig:masters}). The master index is needed for the
 \lstinline+ecrt_master_request()+ function of the application interface (see
-chap.~\ref{sec:ecrt}) and the \lstinline+--master+ option of the
+chap.~\ref{chap:api}) and the \lstinline+--master+ option of the
-\textit{ethercat} command-line tool (see section~\ref{sec:ethercat}), which
+\textit{ethercat} command-line tool (see sec.~\ref{sec:tool}), which defaults
-defaults to $0$.
+to $0$.
 \begin{figure}[htbp]
 \centering
 \includegraphics[width=.5\textwidth]{images/masters}
 \caption{Multiple masters in one module}
 \paragraph{Init script}
 \index{Init script}
 Most probably you won't want to load the master module and the Ethernet driver
-modules manually, but start the master as a service. See
+modules manually, but start the master as a service. See sec.~\ref{sec:system}
-section~\ref{sec:system} on how to do this.
+on how to do this.
 \paragraph{Syslog}
 The master module outputs information about it's state and events to the
 kernel ring buffer. These also end up in the system logs.  The above module
 \paragraph{Process Data Image}
 \index{Process data}
 The slaves offer their inputs and outputs by presenting the master so-called
 ``Process Data Objects'' (Pdos\index{Pdo}). The available Pdos can be
-determined by reading out the slave's TXPDO and RXPDO E$^2$PROM categories. The
+determined by reading out the slave's TXPDO and RXPDO E$^2$PROM categories.
-application can register the Pdos for data exchange during cyclic operation.
+The application can register the Pdos for data exchange during cyclic
-The sum of all registered Pdos defines the ``process data image'', which is
+operation.  The sum of all registered Pdos defines the ``process data image'',
-exchanged via the ``Logical ReadWrite'' datagrams introduced
+which is exchanged via the ``Logical ReadWrite'' datagrams introduced
-in~\cite[section~5.4.2.4]{dlspec}.
+in~\cite[sec.~5.4.2.4]{dlspec}.
 \paragraph{Process Data Domains}
 \index{Domain}
 The process data image can be easily managed by creating so-called
 domains is also limited by the slaves' capabilities.
 \paragraph{FMMU Configuration}
 \index{FMMU!Configuration}
-An application can register Pdos for process data exchange. Every
+An application can register Pdos for process data exchange. Every Pdo is part
-Pdo is part of a memory area in the slave's physical memory, that is
+of a memory area in the slave's physical memory, that is protected by a sync
-protected by a sync manager \cite[section~6.7]{dlspec} for
+manager \cite[sec.~6.7]{dlspec} for synchronized access. In order to make a
-synchronized access. In order to make a sync manager react on a
+sync manager react on a datagram accessing its memory, it is necessary to
-datagram accessing its memory, it is necessary to access the last byte
+access the last byte covered by the sync manager. Otherwise the sync manager
-covered by the sync manager. Otherwise the sync manager will not react
+will not react on the datagram and no data will be exchanged. That is why the
-on the datagram and no data will be exchanged. That is why the whole
+whole synchronized memory area has to be included into the process data image:
-synchronized memory area has to be included into the process data
+For example, if a certain Pdo of a slave is registered for exchange with a
-image: For example, if a certain Pdo of a slave is registered for
+certain domain, one FMMU will be configured to map the complete
-exchange with a certain domain, one FMMU will be configured to map the
+sync-manager-protected memory, the Pdo resides in. If a second Pdo of the same
-complete sync-manager-protected memory, the Pdo resides in. If a
+slave is registered for process data exchange within the same domain, and this
-second Pdo of the same slave is registered for process data exchange
+Pdo resides in the same sync-manager-protected memory as the first Pdo, the
-within the same domain, and this Pdo resides in the same
+FMMU configuration is not touched, because the appropriate memory is already
-sync-manager-protected memory as the first Pdo, the FMMU configuration
+part of the domain's process data image.  If the second Pdo belongs to another
-is not touched, because the appropriate memory is already part of the
+sync-manager-protected area, this complete area is also included into the
-domain's process data image.  If the second Pdo belongs to another
+domains process data image. See figure~\ref{fig:fmmus} for an overview, how
-sync-manager-protected area, this complete area is also included into
+FMMU's are configured to map physical memory to logical process data images.
-the domains process data image. See figure~\ref{fig:fmmus} for an
-overview, how FMMU's are configured to map physical memory to logical
-process data images.
 \begin{figure}[htbp]
 \centering
 \includegraphics[width=\textwidth]{images/fmmus}
 \caption{FMMU configuration for several domains}
 the module code.
 %------------------------------------------------------------------------------
 \chapter{Application Interface}
-\label{sec:ecrt}
+\label{chap:api}
 \index{Application interface}
 %   Interface version
 %   Master Requesting and Releasing
 %   Master Locking
 The application interface provides functions and data structures for
 applications to access and use an EtherCAT master. The complete documentation
 of the interface is included as Doxygen~\cite{doxygen} comments in the header
 file \textit{include/ecrt.h}. You can either directly view the file comments
-or generate an HTML documentation as described in section~\ref{sec:gendoc}.
+or generate an HTML documentation as described in sec.~\ref{sec:gendoc}.
 The following sections cover a general description of the application
 interface.
 Every application should use the master in two steps:
 \begin{description}
 \item[Configuration] The master is requested and the configuration is applied.
 Domains are created Slaves are configured and Pdo entries are registered (see
-section~\ref{sec:masterconfig}).
+sec.~\ref{sec:masterconfig}).
 \item[Operation] Cyclic code is run, process data is exchanged (see
-section~\ref{sec:cyclic}).
+sec.~\ref{sec:cyclic}).
 \end{description}
 \paragraph{Example Applications} \index{Example Applications} There are a few
 example applications in the \textit{examples/} subdirectory of the master
 \section{Concurrent Master Access} % FIXME
 \label{sec:concurr}
 \index{Concurrency}
 In some cases, one master is used by several instances, for example when an
-application does cyclic process data exchange, and there are EoE-capable slaves
+application does cyclic process data exchange, and there are EoE-capable
-that require to exchange Ethernet data with the kernel (see
+slaves that require to exchange Ethernet data with the kernel (see
-section~\ref{sec:eoe}). For this reason, the master is a shared resource,
+sec.~\ref{sec:eoe}). For this reason, the master is a shared resource, and
-and access to it has to be sequentialized. This is usually done by locking with
+access to it has to be sequentialized. This is usually done by locking with
 semaphores, or other methods to protect critical sections.
 The master itself can not provide locking mechanisms, because it has no chance
 to know the appropriate kind of lock. For example if the application uses RTAI
 functionality, ordinary kernel semaphores would not be sufficient. For that, an
 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{sec:ecrt}
+callbacks. See the application interface documentation (chap.~\ref{chap:api}
 of how to use the locking callbacks.
 %------------------------------------------------------------------------------
 \chapter{Ethernet Devices}
 network driver.
 %------------------------------------------------------------------------------
 \section{EtherCAT Device Drivers}
-\label{sec:ethercatdrivers}
+\label{sec:drivers}
 There are a few requirements for Ethernet network devices to function as
 EtherCAT devices, when connected to an EtherCAT bus.
 \paragraph{Dedicated Interfaces}
 \section{Device Selection}
 \label{sec:deviceselection}
 After loading the master module, at least one EtherCAT-capable network driver
 module has to be loaded, that offers its devices to the master (see
-section~\ref{sec:ecdev}. The master module knows the devices to choose from the
+sec.~\ref{sec:ecdev}. The master module knows the devices to choose from the
-module parameters (see section~\ref{sec:mastermod}). If the init script is used
+module parameters (see sec.~\ref{sec:mastermod}). If the init script is used
 to start the master, the drivers and devices to use can be specified in the
-sysconfig file (see section~\ref{sec:sysconfig}).
+sysconfig file (see sec.~\ref{sec:sysconfig}).
 %------------------------------------------------------------------------------
 \section{EtherCAT Device Interface}
 \label{sec:ecdev}
 \index{Device interface}
 An anticipation to the section about the master module
-(section~\ref{sec:mastermod}) has to be made in order to understand
+(sec.~\ref{sec:mastermod}) has to be made in order to understand the way, a
-the way, a network device driver module can connect a device to a
+network device driver module can connect a device to a specific EtherCAT
-specific EtherCAT master.
+master.
 The master module provides a ``device interface'' for network device drivers.
 To use this interface, a network device driver module must include the header
 \textit{devices/ecdev.h}\nomenclature{ecdev}{EtherCAT Device}, coming with the
 EtherCAT master code. This header offers a function interface for EtherCAT
 devices. All functions of the device interface are named with the prefix
 \lstinline+ecdev+.
-The documentation of the device interface can be found in the header file or in
+The documentation of the device interface can be found in the header file or
-the appropriate module of the interface documentation (see
+in the appropriate module of the interface documentation (see
-section~\ref{sec:gendoc} for generation instructions).
+sec.~\ref{sec:gendoc} for generation instructions).
 \ldots % FIXME general description of the device interface
 %------------------------------------------------------------------------------
 a \lstinline+net_device+ structure with a \lstinline+priv_data+ field to
 attach driver-dependent data to the structure. To distinguish between normal
 Ethernet devices and the ones used by EtherCAT masters, the private data
 structure used by the driver could be extended by a pointer, that points to an
 \lstinline+ec_device_t+ object returned by \lstinline+ecdev_offer()+ (see
-section~\ref{sec:ecdev}) if the device is used by a master and otherwise is
+sec.~\ref{sec:ecdev}) if the device is used by a master and otherwise is zero.
-zero.
 The RealTek RTL-8139 Fast Ethernet driver is a ``simple'' Ethernet driver and
 can be taken as an example to patch new drivers. The interesting sections can
 be found by searching the string ``ecdev" in the file
 \textit{devices/8139too-2.6.24-ethercat.c}.
 the function is deprecated and stopped existing. Nevertheless it is adequate
 for showing it's own restrictions.}. Internally, it queues the specified
 datagram, invokes the \textit{ec\_master\_send\_datagrams()} function to send
 a frame with the queued datagram and then waits actively for its reception.
-This sequential approach is very simple, reflecting in only three
+This sequential approach is very simple, reflecting in only three lines of
-lines of code. The disadvantage is, that the master is blocked for the
+code. The disadvantage is, that the master is blocked for the time it waits
-time it waits for datagram reception. There is no difficulty when only
+for datagram reception. There is no difficulty when only one instance is using
-one instance is using the master, but if more instances want to
+the master, but if more instances want to (synchronously\footnote{At this
-(synchronously\footnote{At this time, synchronous master access will
+time, synchronous master access will be adequate to show the advantages of an
-be adequate to show the advantages of an FSM. The asynchronous
+FSM. The asynchronous approach will be discussed in sec.~\ref{sec:eoe}}) use
-approach will be discussed in section~\ref{sec:eoe}}) use the
+the master, it is inevitable to think about an alternative to the sequential
-master, it is inevitable to think about an alternative to the
+model.
-sequential model.
 Master access has to be sequentialized for more than one instance
 wanting to send and receive datagrams synchronously. With the present
 approach, this would result in having one phase of active waiting for
 each instance, which would be non-acceptable especially in realtime
 }
 slave_states = EC_READ_U8(datagram->data); // process datagram
 // state processing finished.
 \end{lstlisting}
-See section~\ref{sec:statemodel} for an introduction to the
+See sec.~\ref{sec:statemodel} for an introduction to the state machine
-state machine programming concept used in the master code.
+programming concept used in the master code.
 %------------------------------------------------------------------------------
 \section{State Machine Theory}
 \label{sec:fsmtheory}
 \paragraph{Mealy and Moore}
 If a closer look is taken to the above listing, it can be seen that the
 actions executed (the ``outputs'' of the state machine) only depend on the
 current state. This accords to the ``Moore'' model introduced in
-section~\ref{sec:fsmtheory}. As mentioned, the ``Mealy'' model offers a higher
+sec.~\ref{sec:fsmtheory}. As mentioned, the ``Mealy'' model offers a higher
 flexibility, which can be seen in the listing below:
 \begin{lstlisting}[gobble=2,language=C,numbers=left]
 void state7(void *priv_data) {
 if (some_condition) {
 \paragraph{Using Sub State Machines}
 To avoid having too much states, certain functions of the EtherCAT master
 state machine have been sourced out into sub state machines.  This helps to
 encapsulate the related workflows and moreover avoids the ``state explosion''
-phenomenon described in section~\ref{sec:fsmtheory}. If the master would
+phenomenon described in sec.~\ref{sec:fsmtheory}. If the master would instead
-instead use one big state machine, the number of states would be a multiple of
+use one big state machine, the number of states would be a multiple of the
-the actual number. This would increase the level of complexity to a
+actual number. This would increase the level of complexity to a non-manageable
-non-manageable grade.
+grade.
 \paragraph{Executing Sub State Machines}
 If a state machine starts to execute a sub state machine, it usually
 remains in one state until the sub state machine terminates. This is
 image memory.
 \item[SII Data] The SII contents are read into the master's image.
 \item[PREOP] If the slave supports CoE, it is set to PREOP state using the
-State change FSM (see section~\ref{sec:fsm-change}) to enable mailbox
+State change FSM (see sec.~\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 Reading FSM
-(see section~\ref{sec:fsm-pdo}). If this is successful, the Pdo information
+(see sec.~\ref{sec:fsm-pdo}). If this is successful, the Pdo information from
-from the SII (if any) is overwritten.
+the SII (if any) is overwritten.
 \end{description}
 %------------------------------------------------------------------------------
 \item[PREOP] The state change FSM is used to bring the slave to PREOP state.
 If this is the requested state, the state machine is finished.
 \item[Sdo Configuration] If there is a slave configuration attached (see
-section~\ref{sec:masterconfig}), and there are any Sdo configurations are
+sec.~\ref{sec:masterconfig}), and there are any Sdo configurations are
 provided by the application, these are sent to the slave.
 \item[Pdo Configuration] The Pdo configuration state machine is executed to
 apply all necessary Pdo configurations.
 \index{FSM!State Change}
 The state change state machine, which can be seen in
 figure~\ref{fig:fsm-change}, leads through the process of changing a slave's
 application-layer state. This implements the states and transitions described
-in \cite[section~6.4.1]{alspec}.
+in \cite[sec.~6.4.1]{alspec}.
 \begin{figure}[htbp]
 \centering
 \includegraphics[width=.6\textwidth]{graphs/fsm_change}
 \caption{Transition Diagram of the State Change State Machine}
 \end{figure}
 \begin{description}
 \item[Start] The new application-layer state is requested via the ``AL Control
-Request'' register (see ~\cite[section 5.3.1]{alspec}).
+Request'' register (see ~\cite[sec. 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
+``AL Control Response'' register (see~\cite[sec. 5.3.2]{alspec}) must be read
-read out until the slave changes the AL state.
+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}).
+Changed'' registers (see~\cite[sec. 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.
 \section{The SII State Machine}
 \label{sec:fsm-sii}
 \index{FSM!SII}
 The SII\index{SII} state machine (shown in figure~\ref{fig:fsm-sii})
-implements the process of reading or writing SII data via the
+implements the process of reading or writing SII data via the Slave
-Slave Information Interface described in \cite[section~6.4]{dlspec}.
+Information Interface described in \cite[sec.~6.4]{dlspec}.
 \begin{figure}[htbp]
 \centering
 \includegraphics[width=.5\textwidth]{graphs/fsm_sii}
 \caption{Transition Diagram of the SII State Machine}
 \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
+\cite[sec. 5.6.7.4]{alspec}. For the object access, the CANopen-over-EtherCAT
-CANopen-over-EtherCAT access primitives are used (see
+access primitives are used (see sec.~\ref{sec:coe}), so the slave must support
-section~\ref{sec:coe}), so the slave must support the CoE mailbox protocol.
+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.
 The master creates a virtual EoE network interface for every EoE-capable
 slave. These interfaces are called either
 \begin{description}
-\item[eoeXsY] for a slave without an alias address (see
+\item[eoeXsY] for a slave without an alias address (see sec.~\ref{sec:alias}),
-section~\ref{sec:alias}), where X is the master index and Y is the slave's
+where X is the master index and Y is the slave's ring position, or
-ring position, or
 \item[eoeXaY] for a slave with a non-zero alias address, where X is the master
 index and Y is the decimal alias address.
 \end{description}
 up, the passing of new socket buffers is suspended with a call to
 \lstinline+netif_stop_queue()+.
 \paragraph{Creation of EoE Handlers}
-During bus scanning (see section~\ref{sec:fsm-scan}), the master determines
+During bus scanning (see sec.~\ref{sec:fsm-scan}), the master determines the
-the supported mailbox protocols foe each slave. This is done by examining the
+supported mailbox protocols foe each slave. This is done by examining the
 ``Supported Mailbox Protocols'' mask field at word address 0x001C of the
 SII\index{SII}. If bit 1 is set, the slave supports the EoE protocol. In this
 case, an EoE handler is created for that slave.
 \paragraph{EoE State Machine}
 \paragraph{EoE Processing}
 To execute the EoE state machine of every active EoE handler, there must be a
 cyclic process. The easiest solution would be to execute the EoE state
 machines synchronously with the master state machine (see
-section~\ref{sec:fsm-master}). This approach has the following disadvantage:
+sec.~\ref{sec:fsm-master}). This approach has the following disadvantage:
 Only one EoE fragment could be sent or received every few cycles. This
 causes the data rate to be very low, because the EoE state machines are not
 executed in the time between the application cycles. Moreover, the data rate
 would be dependent on the period of the application task.
 To overcome this problem, an own cyclic process is needed to asynchronously
 execute the EoE state machines. For that, the master owns a kernel timer, that
 is executed each timer interrupt. This guarantees a constant bandwidth, but
 poses the new problem of concurrent access to the master. The locking
-mechanisms needed for this are introduced in section~\ref{sec:concurr}.
+mechanisms needed for this are introduced in sec.~\ref{sec:concurr}.
 \paragraph{Automatic Configuration}
 By default, slaves are left in PREOP state, if no configuration is applied. If
 an EoE interface link is set to ``up'', the requested slave's
 \section{CANopen-over-EtherCAT (CoE)}
 \label{sec:coe}
 \index{CoE}
-The CANopen-over-EtherCAT protocol \cite[section~5.6]{alspec} is used to
+The CANopen-over-EtherCAT protocol \cite[sec.~5.6]{alspec} is used to
 configure slaves and exchange data objects on application level.
 % FIXME
 %
 % Download / Upload
 \ldots
 \paragraph{Sdo Download State Machine}
-The best time to apply Sdo configurations is during the slave's PREOP
+The best time to apply Sdo configurations is during the slave's PREOP state,
-state, because mailbox communication is already possible and slave's
+because mailbox communication is already possible and slave's application will
-application will start with updating input data in the succeeding
+start with updating input data in the succeeding SAFEOP state. Therefore the
-SAFEOP state. Therefore the Sdo configuration has to be part of the
+Sdo configuration has to be part of the slave configuration state machine (see
-slave configuration state machine (see section~\ref{sec:fsm-conf}): It
+sec.~\ref{sec:fsm-conf}): It is implemented via an Sdo download state machine,
-is implemented via an Sdo download state machine, that is executed
+that is executed just before entering the slave's SAFEOP state. In this way,
-just before entering the slave's SAFEOP state. In this way, it is
+it is guaranteed that the Sdo configurations are applied each time, the slave
-guaranteed that the Sdo configurations are applied each time, the
+is reconfigured.
-slave is reconfigured.
 The transition diagram of the Sdo Download state machine can be seen
 in figure~\ref{fig:fsm-coedown}.
 \begin{figure}[htbp]
 communication protocol. VoE mailbox messages are prepended by a VoE header
 containing a 32-bit vendor ID and a 16-bit vendor-type. There are no more
 constraints regarding this protocol.
 The EtherCAT master allows to create multiple VoE handlers per slave
-configuration via the application interface (see chap.~\ref{sec:ecrt}). These
+configuration via the application interface (see chap.~\ref{chap:api}). These
 handlers contain the state machine necessary for the communication via VoE.
 One read or write operation may be issued at a time. After the operation is
 initiated, the handler must be executed cyclically until it is finished. After
 that, the results of the operation can be retrieved.
 A VoE handler has an own datagram structure, that is marked for exchange after
 each execution step. So the application can decide, how many handlers to
 execute before sending the corresponding EtherCAT frame(s).
 For more information about using VoE handlers, see the application interface
-documentation (chap.~\ref{sec:ecrt}) or the example applications provided in
+documentation (chap.~\ref{chap:api}) or the example applications provided in
 the \textit{examples/} subdirectory.
 %------------------------------------------------------------------------------
 \chapter{Userspace Interfaces}
 the master from userspace and allow a finer influence. It should be possible
 to view and to change special parameters at runtime.
 Bus visualization is another point: For development and debugging purposes it
 is necessary to show the connected slaves with a single command, for instance
-(see sec.~\ref{sec:ethercat}).
+(see sec.~\ref{sec:tool}).
 The application interface has to be available in userspace, to allow userspace
 programs to use EtherCAT master functionality. This was implemented via a
 character device and a userspace library (see sec.~\ref{sec:userlib}).
 to make all that possible.
 %------------------------------------------------------------------------------
 \section{Command-line Tool}
-\label{sec:ethercat}
+\label{sec:tool}
 % --master
 \subsection{Character Devices}
 \label{sec:cdev}
 Each master instance will get a character device as a userspace interface.
 The devices are named \textit{/dev/EtherCATx}, where $x \in \{0 \ldots n\}$ is
 the index of the master.
 \paragraph{Device Node Creation} The character device nodes are automatically
-created, if the \lstinline+udev+ Package is installed. See section
+created, if the \lstinline+udev+ Package is installed. See
-\ref{sec:autonode} for how to install and configure it.
+sec.~\ref{sec:autonode} for how to install and configure it.
 %------------------------------------------------------------------------------
 \subsection{Setting Alias Addresses}
 \label{sec:alias} % FIXME
 \begin{lstlisting}
 $ `\textbf{ethercat sii\_read --position 3 > sii-of-slave3.bin}`
 \end{lstlisting}
 To download SII contents to a slave, writing access to the master's character
-device is necessary (see section~\ref{sec:cdev}).
+device is necessary (see sec.~\ref{sec:cdev}).
 \lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_sii_write}
 \begin{lstlisting}
 # `\textbf{ethercat sii\_write --position 3 sii-of-slave3.bin}`
 %------------------------------------------------------------------------------
 \section{Userspace Library}
 \label{sec:userlib}
-The native application interface (see chap.~\ref{sec:ecrt}) resides in
+The native application interface (see chap.~\ref{chap:api}) resides in
 kernelspace and hence is only accessible from inside the kernel. To make the
 application interface available from userspace programs, a userspace library
 has been created, that can be linked to programs under the terms and
 conditions of the LGPL, version 2 \cite{lgpl}.
 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}).
 Also for performance reasons, the actual domain process data (see
-chap.~\ref{sec:ecrt}) are not copied between kernel and user memory on every
+chap.~\ref{chap:api}) are not copied between kernel and user memory on every
 access: Instead, the data are memory-mapped to the userspace application. Once
 the master is configured and activated, the master module creates one big
 process data memory area for all domains and maps it to userspace, so that the
 application can directly access the process data. For that, there is no
 additional delay when accessing the process data from userspace.
 The EtherCAT master init script conforms to the requirements of the ``Linux
 Standard Base'' (LSB\index{LSB}, \cite{lsb}). The script is installed to
 \textit{etc/init.d/ethercat} below the installation prefix and has to be
 copied (or better: linked) to the appropriate location (see
-section~\ref{sec:installation}), before the master can be inserted as a
+sec.~\ref{sec:installation}), before the master can be inserted as a service.
-service.  Please note, that the init script depends on the sysconfig file
+Please note, that the init script depends on the sysconfig file described
-described below.
+below.
 To provide service dependencies (i.~e. which services have to be started before
 others) inside the init script code, LSB defines a special comment block.
 System tools can extract this information to insert the EtherCAT init script at
 the correct place in the startup sequence:
 \item The processor must still be able to run the operating system between the
 realtime cycles.
 \item The EtherCAT frame must be sent and received, before the next realtime
 cycle begins. The determination of the bus cycle time is difficult and covered
-in section~\ref{sec:timing-bus}.
+in sec.~\ref{sec:timing-bus}.
 \end{enumerate}
 %------------------------------------------------------------------------------
 This command will install the compiled kernel modules to
 \textit{/vol/nfs/root/lib/modules}, prepended by the kernel release.
 If the EtherCAT master shall be run as a service\footnote{Even if the EtherCAT
 master shall not be loaded on system startup, the use of the init script is
-recommended for manual (un-)loading.} (see section~\ref{sec:system}), the init
+recommended for manual (un-)loading.} (see sec.~\ref{sec:system}), the init
 script and the sysconfig file have to be copied (or linked) to the appropriate
 locations. The below example is suitable for SUSE Linux. It may vary for other
 distributions.
 % FIXME relative ln -s?
 # `\textbf{ln -s etc/init.d/ethercat /etc/init.d/}`
 # `\textbf{insserv ethercat}`
 \end{lstlisting}
 Now the sysconfig file \texttt{/etc/sysconfig/ethercat} (see
-section~\ref{sec:sysconfig}) has to be customized. The minimal customization
+sec.~\ref{sec:sysconfig}) has to be customized. The minimal customization is
-is to set the \lstinline+MASTER0_DEVICE+ variable to the MAC address of the
+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
 \end{description}
 \section{Automatic Device Node Creation}
 \label{sec:autonode}
-The \lstinline+ethercat+ command-line tool (see section~\ref{sec:ethercat})
+The \lstinline+ethercat+ command-line tool (see sec.~\ref{sec:tool})
 communicates with the master via a character device. The corresponding device
-nodes are created automatically, if the udev daemon is running.
+nodes are created automatically, if the udev daemon is running.  Note, that on
-Note, that on some distributions, the \lstinline+udev+ package is not
+some distributions, the \lstinline+udev+ package is not installed by default.
-installed by default.
 The device nodes will be created with mode \lstinline+0660+ and group
 \lstinline+root+ by default. If you want to give normal users reading access,
 create a udev rule file (for example
 \textit{/etc/udev/rules.d/99-EtherCAT.rules} with the following content:
 \begin{lstlisting}
 # `\textbf{ls -l /dev/EtherCAT0}`
 crw-rw-r--  1 root root 252, 0 2008-09-03 16:19 /dev/EtherCAT0
 \end{lstlisting}
-Now, the \lstinline+ethercat+ tool can be used (see
+Now, the \lstinline+ethercat+ tool can be used (see sec.~\ref{sec:tool}) even
-section~\ref{sec:ethercat}) even as a non-root user.
+as a non-root user.
 %------------------------------------------------------------------------------
 \begin{thebibliography}{99}

changeset 1289	5b82b6b39c2d
parent 1283	e539c765f6a6
child 1291	9ce46c40a023