# HG changeset patch # User Florian Pose # Date 1224599644 0 # Node ID 5b82b6b39c2d0603120886c6f582f80a2cf7d68b # Parent bf0d42ca5aec65eee32a49e7f129af765790312b Removed unnecessary modules; renamed references. diff -r bf0d42ca5aec -r 5b82b6b39c2d documentation/Makefile --- a/documentation/Makefile Tue Oct 21 11:58:31 2008 +0000 +++ b/documentation/Makefile Tue Oct 21 14:34:04 2008 +0000 @@ -51,11 +51,23 @@ makeindex $(FILE).glo -s nomencl.ist -o $(FILE).gls clean: - @rm -f $(FILE).aux $(FILE).dvi $(FILE).idx \ - $(FILE).ilg $(FILE).ind $(FILE).log \ - $(FILE).out $(FILE).pdf $(FILE).ps \ - $(FILE).toc $(FILE).lot $(FILE).lof \ - $(FILE).lol $(FILE).glo $(FILE).gls \ - images/*.bak *~ + @rm -f \ + $(FILE).aux \ + $(FILE).dvi \ + $(FILE).glo \ + $(FILE).gls \ + $(FILE).idx \ + $(FILE).ilg \ + $(FILE).ind \ + $(FILE).lof \ + $(FILE).log \ + $(FILE).lol \ + $(FILE).lot \ + $(FILE).nlo \ + $(FILE).out \ + $(FILE).pdf \ + $(FILE).toc \ + *~ \ + images/*.bak #------------------------------------------------------------------------------ diff -r bf0d42ca5aec -r 5b82b6b39c2d documentation/ethercat_doc.tex --- a/documentation/ethercat_doc.tex Tue Oct 21 11:58:31 2008 +0000 +++ b/documentation/ethercat_doc.tex Tue Oct 21 14:34:04 2008 +0000 @@ -17,8 +17,6 @@ \usepackage[refpage]{nomencl} \usepackage{listings} \usepackage{svn} -\usepackage{textcomp} -\usepackage{url} \usepackage{SIunits} \usepackage{hyperref} @@ -180,8 +178,8 @@ \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 - the master module. + using the common device interface (see sec.~\ref{sec:ecdev}) provided by the + master module. \end{itemize} @@ -202,7 +200,7 @@ \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. @@ -252,8 +250,7 @@ \end{itemize} -\item Userspace command-line-tool ``ethercat`` (see -section~\ref{sec:ethercat}) +\item Userspace command-line-tool ``ethercat`` (see sec.~\ref{sec:tool}) \begin{itemize} @@ -296,7 +293,7 @@ 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. @@ -338,16 +335,15 @@ \index{Master module} Kernel module containing one or more EtherCAT master instances (see -section~\ref{sec:mastermod}), the ``Device Interface'' (see -section~\ref{sec:ecdev}) and the ``Application Interface'' (see -chap.~\ref{sec:ecrt}). +sec.~\ref{sec:mastermod}), the ``Device Interface'' (see sec.~\ref{sec:ecdev}) +and the ``Application Interface'' (see chap.~\ref{chap:api}). \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 @@ -361,7 +357,7 @@ 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. @@ -386,7 +382,7 @@ \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 @@ -436,9 +432,9 @@ 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 -\textit{ethercat} command-line tool (see section~\ref{sec:ethercat}), which -defaults to $0$. +chap.~\ref{chap:api}) and the \lstinline+--master+ option of the +\textit{ethercat} command-line tool (see sec.~\ref{sec:tool}), which defaults +to $0$. \begin{figure}[htbp] \centering @@ -451,8 +447,8 @@ \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 -section~\ref{sec:system} on how to do this. +modules manually, but start the master as a service. See sec.~\ref{sec:system} +on how to do this. \paragraph{Syslog} @@ -486,11 +482,11 @@ 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 -application can register the Pdos for data exchange during cyclic operation. -The sum of all registered Pdos defines the ``process data image'', which is -exchanged via the ``Logical ReadWrite'' datagrams introduced -in~\cite[section~5.4.2.4]{dlspec}. +determined by reading out the slave's TXPDO and RXPDO E$^2$PROM categories. +The application can register the Pdos for data exchange during cyclic +operation. The sum of all registered Pdos defines the ``process data image'', +which is exchanged via the ``Logical ReadWrite'' datagrams introduced +in~\cite[sec.~5.4.2.4]{dlspec}. \paragraph{Process Data Domains} \index{Domain} @@ -524,26 +520,23 @@ \paragraph{FMMU Configuration} \index{FMMU!Configuration} -An application can register Pdos for process data exchange. Every -Pdo is part of a memory area in the slave's physical memory, that is -protected by a sync manager \cite[section~6.7]{dlspec} for -synchronized access. In order to make a sync manager react on a -datagram accessing its memory, it is necessary to access the last byte -covered by the sync manager. Otherwise the sync manager will not react -on the datagram and no data will be exchanged. That is why the whole -synchronized memory area has to be included into the process data -image: For example, if a certain Pdo of a slave is registered for -exchange with a certain domain, one FMMU will be configured to map the -complete sync-manager-protected memory, the Pdo resides in. If a -second Pdo of the same slave is registered for process data exchange -within the same domain, and this Pdo resides in the same -sync-manager-protected memory as the first Pdo, the FMMU configuration -is not touched, because the appropriate memory is already part of the -domain's process data image. If the second Pdo belongs to another -sync-manager-protected area, this complete area is also included into -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. +An application can register Pdos for process data exchange. Every Pdo is part +of a memory area in the slave's physical memory, that is protected by a sync +manager \cite[sec.~6.7]{dlspec} for synchronized access. In order to make a +sync manager react on a datagram accessing its memory, it is necessary to +access the last byte covered by the sync manager. Otherwise the sync manager +will not react on the datagram and no data will be exchanged. That is why the +whole synchronized memory area has to be included into the process data image: +For example, if a certain Pdo of a slave is registered for exchange with a +certain domain, one FMMU will be configured to map the complete +sync-manager-protected memory, the Pdo resides in. If a second Pdo of the same +slave is registered for process data exchange within the same domain, and this +Pdo resides in the same sync-manager-protected memory as the first Pdo, the +FMMU configuration is not touched, because the appropriate memory is already +part of the domain's process data image. If the second Pdo belongs to another +sync-manager-protected area, this complete area is also included into 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 @@ -564,7 +557,7 @@ %------------------------------------------------------------------------------ \chapter{Application Interface} -\label{sec:ecrt} +\label{chap:api} \index{Application interface} % Interface version @@ -583,7 +576,7 @@ 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. @@ -594,10 +587,10 @@ \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} @@ -636,10 +629,10 @@ \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 -that require to exchange Ethernet data with the kernel (see -section~\ref{sec:eoe}). For this reason, the master is a shared resource, -and access to it has to be sequentialized. This is usually done by locking with +application does cyclic process data exchange, and there are EoE-capable +slaves that require to exchange Ethernet data with the kernel (see +sec.~\ref{sec:eoe}). For this reason, the master is a shared resource, and +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 @@ -664,7 +657,7 @@ 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. %------------------------------------------------------------------------------ @@ -814,7 +807,7 @@ %------------------------------------------------------------------------------ \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. @@ -908,10 +901,10 @@ 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 -module parameters (see section~\ref{sec:mastermod}). If the init script is used +sec.~\ref{sec:ecdev}. The master module knows the devices to choose from the +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}). %------------------------------------------------------------------------------ @@ -920,9 +913,9 @@ \index{Device interface} An anticipation to the section about the master module -(section~\ref{sec:mastermod}) has to be made in order to understand -the way, a network device driver module can connect a device to a -specific EtherCAT master. +(sec.~\ref{sec:mastermod}) has to be made in order to understand the way, a +network device driver module can connect a device to a specific EtherCAT +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 @@ -931,9 +924,9 @@ 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 appropriate module of the interface documentation (see -section~\ref{sec:gendoc} for generation instructions). +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 @@ -973,8 +966,7 @@ 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 -zero. +sec.~\ref{sec:ecdev}) if the device is used by a master and otherwise is 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 @@ -1010,15 +1002,14 @@ 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 -lines of code. The disadvantage is, that the master is blocked for the -time it waits for datagram reception. There is no difficulty when only -one instance is using the master, but if more instances want to -(synchronously\footnote{At this time, synchronous master access will - be adequate to show the advantages of an FSM. The asynchronous - approach will be discussed in section~\ref{sec:eoe}}) use the -master, it is inevitable to think about an alternative to the -sequential model. +This sequential approach is very simple, reflecting in only three lines of +code. The disadvantage is, that the master is blocked for the time it waits +for datagram reception. There is no difficulty when only one instance is using +the master, but if more instances want to (synchronously\footnote{At this +time, synchronous master access will be adequate to show the advantages of an +FSM. The asynchronous approach will be discussed in sec.~\ref{sec:eoe}}) use +the master, it is inevitable to think about an alternative to the sequential +model. Master access has to be sequentialized for more than one instance wanting to send and receive datagrams synchronously. With the present @@ -1063,8 +1054,8 @@ // state processing finished. \end{lstlisting} -See section~\ref{sec:statemodel} for an introduction to the -state machine programming concept used in the master code. +See sec.~\ref{sec:statemodel} for an introduction to the state machine +programming concept used in the master code. %------------------------------------------------------------------------------ @@ -1242,7 +1233,7 @@ 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] @@ -1291,10 +1282,10 @@ 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 -instead use one big state machine, the number of states would be a multiple of -the actual number. This would increase the level of complexity to a -non-manageable grade. +phenomenon described in sec.~\ref{sec:fsmtheory}. If the master would instead +use one big state machine, the number of states would be a multiple of the +actual number. This would increase the level of complexity to a non-manageable +grade. \paragraph{Executing Sub State Machines} @@ -1412,12 +1403,12 @@ \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 -from the SII (if any) is overwritten. +(see sec.~\ref{sec:fsm-pdo}). If this is successful, the Pdo information from +the SII (if any) is overwritten. \end{description} @@ -1456,7 +1447,7 @@ 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 @@ -1486,7 +1477,7 @@ 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 @@ -1498,19 +1489,19 @@ \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 -read out until the slave changes the AL state. +``AL Control Response'' register (see~\cite[sec. 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}). +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'' @@ -1532,8 +1523,8 @@ \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 -Slave Information Interface described in \cite[section~6.4]{dlspec}. +implements the process of reading or writing SII data via the Slave +Information Interface described in \cite[sec.~6.4]{dlspec}. \begin{figure}[htbp] \centering @@ -1584,9 +1575,9 @@ 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:coe}), so the slave must support the CoE mailbox protocol. +\cite[sec. 5.6.7.4]{alspec}. For the object access, the CANopen-over-EtherCAT +access primitives are used (see sec.~\ref{sec:coe}), 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 @@ -1661,9 +1652,8 @@ \begin{description} -\item[eoeXsY] for a slave without an alias address (see -section~\ref{sec:alias}), where X is the master index and Y is the slave's -ring position, or +\item[eoeXsY] for a slave without an alias address (see sec.~\ref{sec:alias}), +where X is the master index and Y is the slave's 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. @@ -1709,8 +1699,8 @@ \paragraph{Creation of EoE Handlers} -During bus scanning (see section~\ref{sec:fsm-scan}), the master determines -the supported mailbox protocols foe each slave. This is done by examining the +During bus scanning (see sec.~\ref{sec:fsm-scan}), the master determines 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. @@ -1782,7 +1772,7 @@ 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 @@ -1793,7 +1783,7 @@ 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} @@ -1807,7 +1797,7 @@ \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 @@ -1822,15 +1812,14 @@ \paragraph{Sdo Download State Machine} -The best time to apply Sdo configurations is during the slave's PREOP -state, because mailbox communication is already possible and slave's -application will start with updating input data in the succeeding -SAFEOP state. Therefore the Sdo configuration has to be part of the -slave configuration state machine (see section~\ref{sec:fsm-conf}): It -is implemented via an Sdo download state machine, that is executed -just before entering the slave's SAFEOP state. In this way, it is -guaranteed that the Sdo configurations are applied each time, the -slave is reconfigured. +The best time to apply Sdo configurations is during the slave's PREOP state, +because mailbox communication is already possible and slave's application will +start with updating input data in the succeeding SAFEOP state. Therefore the +Sdo configuration has to be part of the slave configuration state machine (see +sec.~\ref{sec:fsm-conf}): It is implemented via an Sdo download state machine, +that is executed just before entering the slave's SAFEOP state. In this way, +it is guaranteed that the Sdo configurations are applied each time, the slave +is reconfigured. The transition diagram of the Sdo Download state machine can be seen in figure~\ref{fig:fsm-coedown}. @@ -1890,7 +1879,7 @@ 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 @@ -1901,7 +1890,7 @@ 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. %------------------------------------------------------------------------------ @@ -1919,7 +1908,7 @@ 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 @@ -1940,7 +1929,7 @@ %------------------------------------------------------------------------------ \section{Command-line Tool} -\label{sec:ethercat} +\label{sec:tool} % --master @@ -1952,8 +1941,8 @@ 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 -\ref{sec:autonode} for how to install and configure it. +created, if the \lstinline+udev+ Package is installed. See +sec.~\ref{sec:autonode} for how to install and configure it. %------------------------------------------------------------------------------ @@ -2073,7 +2062,7 @@ \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} @@ -2101,7 +2090,7 @@ \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 @@ -2167,7 +2156,7 @@ 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 @@ -2254,9 +2243,9 @@ 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 -service. Please note, that the init script depends on the sysconfig file -described below. +sec.~\ref{sec:installation}), before the master can be inserted as a service. +Please note, that the init script depends on the sysconfig file described +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. @@ -2415,7 +2404,7 @@ \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} @@ -2589,7 +2578,7 @@ 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. @@ -2603,8 +2592,8 @@ \end{lstlisting} Now the sysconfig file \texttt{/etc/sysconfig/ethercat} (see -section~\ref{sec:sysconfig}) has to be customized. The minimal customization -is to set the \lstinline+MASTER0_DEVICE+ variable to the MAC address of the +sec.~\ref{sec:sysconfig}) has to be customized. The minimal customization is +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. @@ -2659,11 +2648,10 @@ \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. -Note, that on some distributions, the \lstinline+udev+ package is not -installed by default. +nodes are created automatically, if the udev daemon is running. Note, that on +some distributions, the \lstinline+udev+ package is not 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, @@ -2683,8 +2671,8 @@ 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 -section~\ref{sec:ethercat}) even as a non-root user. +Now, the \lstinline+ethercat+ tool can be used (see sec.~\ref{sec:tool}) even +as a non-root user. %------------------------------------------------------------------------------