--- a/documentation/ethercat_doc.tex Fri Jul 04 09:24:19 2008 +0000
+++ b/documentation/ethercat_doc.tex Fri Jul 04 09:48:42 2008 +0000
@@ -3048,201 +3048,54 @@
%------------------------------------------------------------------------------
-\section{The Sysfs Interface}
-\label{sec:sysfs}
-
-The system filesystem (Sysfs\index{Sysfs}) was introduced with Linux
-kernel 2.5 and is a well-defined interface for drivers to export
-information to user space. It serves also as an relief for the process
-filesystem (Procfs), where over the years much non-process information
-was concentrated.
-
-Sysfs exports information about devices, classes and buses via a
-virtual filesystem, usually mounted to \textit{/sys}. The EtherCAT
-master slightly differs from this concept, because the only physical
-device is the network adapter it uses for bus communication, which is
-already represented in Sysfs. For the EtherCAT bus is no system bus
-like PCI (with device and driver structures), it would not make any
-sense to represent it as bus structure in Sysfs.
-
-Therefore, the EtherCAT master is represented as a new directory
-directly unter the Sysfs root. Every master gets its own Sysfs entry
-named \textit{ethercatX}, where X is the index of the master. Two
-masters would result in the directories \textit{/sys/ethercat0} and
-\textit{/sys/ethercat1}, respectively.
-
-The Sysfs base class in the kernel code is the \textit{kobject}
-structure. Each object structure, that is to be represented in Sysfs,
-has to contain such a structure, because due to the concurrent access
-(through ``normal'' kernel code and Sysfs code) the object deletion
-gets a little more complicated: The object may not be freed until no
-instance uses it any more. Therefore, each kobject maintains a
-reference counter. If the reference counter gets zero, the object is
-finally freed. A kobject can be registered to appear as a directory in
-Sysfs with a call to \textit{kobject\_add()}. Each kobject type can
-define attributes, that appear as files in the kobject's
-directory. Callback functions have to be provided for reading (and
-perhaps writing) access.
-
-\subsection{Master Attributes}
-\label{sec:sysfs-master}
-
-Below is a typical listing of the masters Sysfs directory (that is a
-file system representation of the master's kobject):
-
-\begin{lstlisting}[gobble=2]
- `\$` `\textbf{ls /sys/ethercat0}`
- debug_level slave000 slave003 slave006
- eeprom_write_enable slave001 slave004 slave007
- info slave002 slave005 slave008
-\end{lstlisting}
-
-The following attributes exist in the master directory:
-
-\begin{description}
-\item[debug\_level] (read/write) This attribute contains the master's
- debug level, which controls, how much information is printed into
- Syslog. The values 0 (no additional debug messages), 1 (a few
- additional debug messages) and 2 (all additional debug messages) are
- defined. Writing is done with command like
-
- \begin{lstlisting}[gobble=4]
- # `\textbf{echo 1 > /sys/ethercat0/debug\_level}`
- \end{lstlisting}
-
- and is receipted with a syslog message by the master:
-
- \begin{lstlisting}[gobble=4]
- EtherCAT: Master debug level set to 1.
- \end{lstlisting}
-
-\item[enable\_eeprom\_writing] (read/write) See
- section~\ref{sec:eepromaccess} for how to use this attribute.
-
-\item[info] (read only) This attribute contains information about the
- master. Example contents are below:
-
- \begin{lstlisting}[gobble=4]
- `\$` `\textbf{cat /sys/ethercat0/info}`
-
- Mode: IDLE
- Slaves: 9
-
- Timing (min/avg/max) [us]:
- Idle cycle: 4 / 4.38 / 34
- EoE cycle: 9 / 11.91 / 23
-
- EoE statistics (RX/TX) [bps]:
- eoe0: 0 / 3184
- \end{lstlisting}
-
- The mode can be \textit{ORPHANED}, \textit{IDLE} or
- \textit{OPERATION}. The other parameters are self-explanatory.
-
-\end{description}
-
-\subsubsection{Domain Attributes}
-\label{sec:sysfs-domain}
-
-In operation mode, each created domain is represented as a directory
-\textit{domainX}, where X is the domain index. Below is a listing of
-the domain directory contents:
-
-\begin{lstlisting}[gobble=2]
- `\$` `\textbf{ls /sys/ethercat0/domain0}`
- image_size
-\end{lstlisting}
-
-The domain directories currently only export the domain's image size.
-It is planned to export the whole process data mapping for debugging
-purposes.
-
-\subsubsection{Slave Attributes}
-\label{sec:sysfs-slave}
-
-Each slave on the bus is represented in its own directory
-\textit{slaveXXX}, where XXX is the slave's 3-digit ring position in
-the EtherCAT bus. Below is a listing of a slave directory:
-
-\begin{lstlisting}[gobble=2]
- `\$` `\textbf{ls /sys/ethercat0/slave003}`
- eeprom info state
-\end{lstlisting}
-
-\begin{description}
-\item[eeprom] (read/write) See section~\ref{sec:eepromaccess} for how
- to use this attribute.
-
-\item[info] (read only) This attribute contains a bunch of information
- about the slave. Below is an example output:
-
- \begin{lstlisting}[gobble=4]
- `\$` `\textbf{cat /sys/ethercat0/slave003/info}`
-
- Name: EL4132 2K. Ana. Ausgang +/-10V
- Vendor ID: 0x00000002
- Product code: 0x10243052
-
- State: INIT
- Ring position: 3
- Advanced position: 1:3
-
- Data link status:
- Port 0 (EBUS) Link down, Loop open, Signal detected
- Port 1 (EBUS) Link down, Loop open, Signal detected
- Port 2 (EBUS) Link down, Loop closed, No signal
- Port 3 (EBUS) Link down, Loop closed, No signal
-
- Mailboxes:
- RX mailbox: 0x1800/246, TX mailbox: 0x18F6/246
- Supported protocols: CoE, FoE
-
- SII data:
- Group: AnaOut
- Image: TERM_AO
- Order#: EL4132
-
- Sync-Managers:
- 0: 0x1800, length 246, control 0x26, enable
- 1: 0x18F6, length 246, control 0x22, enable
- 2: 0x1000, length 0, control 0x24, enable
- 3: 0x1100, length 0, control 0x20, enable
-
- Pdos:
- RXPDO "Channel 1" (0x1600), Sync-Manager 2
- "Output" 0x6411:1, 16 bit
- RXPDO "Channel 2" (0x1601), Sync-Manager 2
- "Output" 0x6411:2, 16 bit
- \end{lstlisting}
-
- This is nearly all of the SII category information needed to
- configure the slave, supplemented with state and addressing
- information.
-
-\item[state] (read/write) This attribute contains the slave's state.
- It can be read or written:
-
- \begin{lstlisting}[gobble=4]
- # `\textbf{cat /sys/ethercat0/slave003/state}`
- OP
- # `\textbf{echo SAFEOP > /sys/ethercat0/slave003/state}`
- \end{lstlisting}
-
- This command should also be receipted with a syslog message:
-
- \begin{lstlisting}[gobble=4]
- EtherCAT: Accepted new state SAFEOP for slave 3.
- EtherCAT: Changing state of slave 3 from OP to SAFEOP.
- EtherCAT: Slave states: INIT, SAFEOP, OP.
- \end{lstlisting}
-
- After the new requested state was accepted from user space, the
- operation state machine (see section~\ref{sec:fsm-op}) or the idle
- state machine (section~\ref{sec:fsm-idle}) notices, that the
- requested slave state differs from the current one, and therefore
- executes the slave configuration state machine, until the slave has
- reached the requested state.
-\end{description}
+\section{Command-line Tool}
+\label{sec:ethercat}
+
+% --master
+
+\subsection{Character devices}
+\label{sec:cdev}
+
+Each master instance will get a character device as a user-space interface.
+The devices are named \textit{/dev/EtherCATX}, where $X$ is the index of the
+master.
+
+% FIXME
+% udev
+% rights
+
+%------------------------------------------------------------------------------
+
+\subsection{Listing the bus}
+
+Slave information can be gathered with the subcommand \lstinline+slaves+:
+
+\begin{lstlisting}
+$ `\textbf{ethercat slaves}`
+0 0:0 PREOP + EK1100 Ethernet Kopplerklemme (2A E-Bus)
+1 5555:0 PREOP + EL3162 2K. Ana. Eingang 0-10V
+2 5555:1 PREOP + EL4102 2K. Ana. Ausgang 0-10V
+3 5555:2 PREOP + EL2004 4K. Dig. Ausgang 24V, 0,5A
+\end{lstlisting}
+
+Every slave found is displayed as one text row. The columns have the following
+meanings:
+
+\begin{enumerate}
+
+\item Ring position in the bus.
+
+\item Alias and position (see section~\ref{sec:addr}).
+
+\item Application-layer state.
+
+\item Error flag: \lstinline!+! means that the slave is ok, \lstinline+E+
+means that an error has occurred during scanning or configuration.
+
+\item The slave's name, as it appears in the ``general'' SII category. If no
+name is found, the slave's vendor ID and product code are listed.
+
+\end{enumerate}
%------------------------------------------------------------------------------
@@ -3250,118 +3103,49 @@
\label{sec:siiaccess}
\index{SII!Access}
-It is possible to directly read or write the complete E$^2$PROM
-contents of the slaves. This was introduced for the reasons below:
+It is possible to directly read or write the complete SII contents of the
+slaves. This was introduced for the reasons below:
\begin{itemize}
-\item The format of the E$^2$PROM data is still in development and
- categories can be added in the future. With read and write access,
- the complete memory contents can be easily backed up and restored.
-\item Some E$^2$PROM data fields have to be altered (like the alias
- address). A quick writing must be possible for that.
-\item Through read access, analyzing category data is possible from
- user space.
+
+\item The format of the SII data is still in development and categories can be
+added in the future. With read and write access, the complete memory contents
+can be easily backed up and restored.
+
+\item Some SII data fields have to be altered (like the alias address). A quick
+writing must be possible for that.
+
+\item Through reading access, analyzing category data is possible from user
+space.
+
\end{itemize}
-Reading out E$^2$PROM data is as easy as reading other attributes. Though the
-data are in binary format, analysis is easier with a tool like
-\textit{hexdump}:
-
-\begin{lstlisting}[gobble=2]
- `\$` `\textbf{cat /sys/ethercat0/slave003/eeprom | hexdump}`
- 0000000 0103 0000 0000 0000 0000 0000 0000 008c
- 0000010 0002 0000 3052 07f0 0000 0000 0000 0000
- 0000020 0000 0000 0000 0000 0000 0000 0000 0000
- ...
-\end{lstlisting}
-
-Backing up E$^2$PROM contents gets as easy as copying a file:
-
-\begin{lstlisting}[gobble=2]
- `\$` `\textbf{cp /sys/ethercat0/slave003/eeprom slave003.eep}`
-\end{lstlisting}
-
-Writing access is only possible as \textit{root}. Moreover writing has
-to be explicitly enabled and is only allowed in idle mode. This is a
-safety measure, because without the correct memory contents, a slave
-is unusable. Writing E$^2$PROM contents in operation mode is not
-provided yet.
-
-E$^2$PROM writing is enabled with the command below:
-
-\begin{lstlisting}[gobble=2]
- # `\textbf{echo 1 > /sys/ethercat0/eeprom\_write\_enable}`
-\end{lstlisting}
-
-The success can be seen in the Syslog messages again:
-
-\begin{lstlisting}[gobble=2]
- EtherCAT: Slave EEPROM writing enabled.
-\end{lstlisting}
-
-Now, it is possible to write E$^2$PROM contents to a slave. The master
-will accept data through the \textit{eeprom} file and will perform a
-short validation of the contents, before starting the write operation.
-This validation checks the complete size and the category headers.
-
-\begin{lstlisting}[gobble=2]
- # `\textbf{cat slave003.eep > /sys/ethercat0/slave003/eeprom}`
-\end{lstlisting}
-
-The write operation can take a few seconds.
-
-\begin{lstlisting}[gobble=2]
- EtherCAT: EEPROM writing scheduled for slave 3, 88 words.
- EtherCAT: Writing EEPROM of slave 3...
- EtherCAT: Finished writing EEPROM of slave 3.
-\end{lstlisting}
-
-%------------------------------------------------------------------------------
-
-\section{User Space Tools}
-\index{User space!Tools}
-
-There is a user space tool called \textit{lsec}\index{lsec} (``List
-EtherCAT'') to visualize the EtherCAT bus. Running it usually results
-in an output like this:
-
-\begin{lstlisting}[gobble=2]
- `\$` `\textbf{lsec}`
- EtherCAT bus listing for master 0:
- 0 1:0 OP EK1100 Ethernet Kopplerklemme (2A E-Bus)
- 1 1:1 INIT EL4132 2K. Ana. Ausgang +/-10V
- 2 1:2 INIT EL4132 2K. Ana. Ausgang +/-10V
- 3 1:3 SAFEOP EL4132 2K. Ana. Ausgang +/-10V
- 4 1:4 INIT EL5101 Incremental Encoder Interface
- 5 1:5 INIT EL1014 4K. Dig. Eingang 24V, 10s
- 6 1:6 OP EL6601 1 Port Switch (Ethernet, CoE)
- 7 1:7 INIT EL5101 Incremental Encoder Interface
- 8 1:8 INIT EL5001 1K. SSI Encoder
-\end{lstlisting}
-
-Every slave is displayed as one text row. The first column shows its
-ring position, the second displays the ``advanced position address''
-(see section~\ref{sec:addr}) and the third column displays the current
-slave state. The last column is the slave's name, as it appears in the
-``general'' E$^2$PROM category.
-
-The lsec program is a Perl script, that evaluates the Sysfs
-\textit{info} attributes of the slaves (see
-section~\ref{sec:sysfs-slave}). This is done for master $0$ by
-default, but the master index can be specified via command line:
-
-\begin{lstlisting}[gobble=2]
- `\$` `\textbf{lsec -h}`
- Usage: ec_list [OPTIONS]
- -m <IDX> Query master <IDX>.
- -h Show this help.
-\end{lstlisting}
-
-This script has proved as useful for troubleshooting: If it displays
-slaves, the master is up and running, and the bus connection is
-present, too. It is also useful when building up a bus: It can verify
-the list of slaves and help to create a process data image (see
-chapter~\ref{chapter:usage}).
+Reading out SII data is as easy as other commands. Though the data are in
+binary format, analysis is easier with a tool like \textit{hexdump}:
+
+\begin{lstlisting}
+$ `\textbf{ethercat sii\_read --slave 3 | hexdump}`
+0000000 0103 0000 0000 0000 0000 0000 0000 008c
+0000010 0002 0000 3052 07f0 0000 0000 0000 0000
+0000020 0000 0000 0000 0000 0000 0000 0000 0000
+...
+\end{lstlisting}
+
+Backing up SII contents can easily done with a redirection:
+
+\begin{lstlisting}
+$ `\textbf{ethercat sii\_read --slave 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}).
+
+\begin{lstlisting}
+# `\textbf{ethercat sii\_write --slave 3 sii-of-slave3.bin}`
+\end{lstlisting}
+
+The SII contents will be checked for validity and then sent to the slave. The
+write operation may take a few seconds.
%------------------------------------------------------------------------------