3051 \section{The Sysfs Interface}

  3051 \section{Command-line Tool}

  3052 \label{sec:sysfs}

  3052 \label{sec:ethercat}

  3053 

  3053 

  3054 The system filesystem (Sysfs\index{Sysfs}) was introduced with Linux

  3054 % --master

  3055 kernel 2.5 and is a well-defined interface for drivers to export

  3055 

  3056 information to user space. It serves also as an relief for the process

  3056 \subsection{Character devices}

  3057 filesystem (Procfs), where over the years much non-process information

  3057 \label{sec:cdev}

  3058 was concentrated.

  3058 

  3059 

  3059 Each master instance will get a character device as a user-space interface.

  3060 Sysfs exports information about devices, classes and buses via a

  3060 The devices are named \textit{/dev/EtherCATX}, where $X$ is the index of the

  3061 virtual filesystem, usually mounted to \textit{/sys}. The EtherCAT

  3061 master.

  3062 master slightly differs from this concept, because the only physical

  3062 

  3063 device is the network adapter it uses for bus communication, which is

  3063 % FIXME

  3064 already represented in Sysfs. For the EtherCAT bus is no system bus

  3064 % udev

  3065 like PCI (with device and driver structures), it would not make any

  3065 % rights

  3066 sense to represent it as bus structure in Sysfs.

  3066 

  3067 

  3067 %------------------------------------------------------------------------------

  3068 Therefore, the EtherCAT master is represented as a new directory

  3068 

  3069 directly unter the Sysfs root. Every master gets its own Sysfs entry

  3069 \subsection{Listing the bus}

  3070 named \textit{ethercatX}, where X is the index of the master. Two

  3070 

  3071 masters would result in the directories \textit{/sys/ethercat0} and

  3071 Slave information can be gathered with the subcommand \lstinline+slaves+:

  3072 \textit{/sys/ethercat1}, respectively.

  3072 

  3073 

  3073 \begin{lstlisting}

  3074 The Sysfs base class in the kernel code is the \textit{kobject}

  3074 $ `\textbf{ethercat slaves}`

  3075 structure. Each object structure, that is to be represented in Sysfs,

  3075 0     0:0  PREOP  +  EK1100 Ethernet Kopplerklemme (2A E-Bus)

  3076 has to contain such a structure, because due to the concurrent access

  3076 1  5555:0  PREOP  +  EL3162 2K. Ana. Eingang 0-10V

  3077 (through ``normal'' kernel code and Sysfs code) the object deletion

  3077 2  5555:1  PREOP  +  EL4102 2K. Ana. Ausgang 0-10V

  3078 gets a little more complicated: The object may not be freed until no

  3078 3  5555:2  PREOP  +  EL2004 4K. Dig. Ausgang 24V, 0,5A

  3079 instance uses it any more. Therefore, each kobject maintains a

  3079 \end{lstlisting}

  3080 reference counter. If the reference counter gets zero, the object is

  3080 

  3081 finally freed. A kobject can be registered to appear as a directory in

  3081 Every slave found is displayed as one text row. The columns have the following

  3082 Sysfs with a call to \textit{kobject\_add()}. Each kobject type can

  3082 meanings:

  3083 define attributes, that appear as files in the kobject's

  3083 

  3084 directory. Callback functions have to be provided for reading (and

  3084 \begin{enumerate}

  3085 perhaps writing) access.

  3085 

  3086 

  3086 \item Ring position in the bus.

  3087 \subsection{Master Attributes}

  3087 

  3088 \label{sec:sysfs-master}

  3088 \item Alias and position (see section~\ref{sec:addr}).

  3089 

  3089 

  3090 Below is a typical listing of the masters Sysfs directory (that is a

  3090 \item Application-layer state.

  3091 file system representation of the master's kobject):

  3091 

  3092 

  3092 \item Error flag: \lstinline!+! means that the slave is ok, \lstinline+E+

  3093 \begin{lstlisting}[gobble=2]

  3093 means that an error has occurred during scanning or configuration.

  3094   `\$` `\textbf{ls /sys/ethercat0}`

  3094 

  3095   debug_level          slave000  slave003  slave006

  3095 \item The slave's name, as it appears in the ``general'' SII category. If no

  3096   eeprom_write_enable  slave001  slave004  slave007

  3096 name is found, the slave's vendor ID and product code are listed.

  3097   info                 slave002  slave005  slave008

  3097 

  3098 \end{lstlisting}

  3098 \end{enumerate}

  3099 

  3100 The following attributes exist in the master directory:

  3101 

  3102 \begin{description}

  3103 \item[debug\_level] (read/write) This attribute contains the master's

  3104   debug level, which controls, how much information is printed into

  3105   Syslog. The values 0 (no additional debug messages), 1 (a few

  3106   additional debug messages) and 2 (all additional debug messages) are

  3107   defined. Writing is done with command like

  3108 

  3109   \begin{lstlisting}[gobble=4]

  3110     # `\textbf{echo 1 > /sys/ethercat0/debug\_level}`

  3111   \end{lstlisting}

  3112 

  3113   and is receipted with a syslog message by the master:

  3114 

  3115   \begin{lstlisting}[gobble=4]

  3116     EtherCAT: Master debug level set to 1.

  3117   \end{lstlisting}

  3118 

  3119 \item[enable\_eeprom\_writing] (read/write) See

  3120   section~\ref{sec:eepromaccess} for how to use this attribute.

  3121 

  3122 \item[info] (read only) This attribute contains information about the

  3123   master. Example contents are below:

  3124 

  3125   \begin{lstlisting}[gobble=4]

  3126     `\$` `\textbf{cat /sys/ethercat0/info}`

  3127 

  3128     Mode: IDLE

  3129     Slaves: 9

  3130 

  3131     Timing (min/avg/max) [us]:

  3132       Idle cycle: 4 / 4.38 / 34

  3133       EoE cycle: 9 / 11.91 / 23

  3134 

  3135     EoE statistics (RX/TX) [bps]:

  3136       eoe0: 0 / 3184

  3137   \end{lstlisting}

  3138 

  3139   The mode can be \textit{ORPHANED}, \textit{IDLE} or

  3140   \textit{OPERATION}. The other parameters are self-explanatory.

  3141 

  3142 \end{description}

  3143 

  3144 \subsubsection{Domain Attributes}

  3145 \label{sec:sysfs-domain}

  3146 

  3147 In operation mode, each created domain is represented as a directory

  3148 \textit{domainX}, where X is the domain index. Below is a listing of

  3149 the domain directory contents:

  3150 

  3151 \begin{lstlisting}[gobble=2]

  3152   `\$` `\textbf{ls /sys/ethercat0/domain0}`

  3153   image_size

  3154 \end{lstlisting}

  3155 

  3156 The domain directories currently only export the domain's image size.

  3157 It is planned to export the whole process data mapping for debugging

  3158 purposes.

  3159 

  3160 \subsubsection{Slave Attributes}

  3161 \label{sec:sysfs-slave}

  3162 

  3163 Each slave on the bus is represented in its own directory

  3164 \textit{slaveXXX}, where XXX is the slave's 3-digit ring position in

  3165 the EtherCAT bus. Below is a listing of a slave directory:

  3166 

  3167 \begin{lstlisting}[gobble=2]

  3168   `\$` `\textbf{ls /sys/ethercat0/slave003}`

  3169   eeprom  info  state

  3170 \end{lstlisting}

  3171 

  3172 \begin{description}

  3173 \item[eeprom] (read/write) See section~\ref{sec:eepromaccess} for how

  3174   to use this attribute.

  3175 

  3176 \item[info] (read only) This attribute contains a bunch of information

  3177   about the slave. Below is an example output:

  3178 

  3179   \begin{lstlisting}[gobble=4]

  3180     `\$` `\textbf{cat /sys/ethercat0/slave003/info}`

  3181 

  3182     Name: EL4132 2K. Ana. Ausgang +/-10V

  3183     Vendor ID: 0x00000002

  3184     Product code: 0x10243052

  3185 

  3186     State: INIT

  3187     Ring position: 3

  3188     Advanced position: 1:3

  3189 

  3190     Data link status:

  3191       Port 0 (EBUS) Link down, Loop open, Signal detected

  3192       Port 1 (EBUS) Link down, Loop open, Signal detected

  3193       Port 2 (EBUS) Link down, Loop closed, No signal

  3194       Port 3 (EBUS) Link down, Loop closed, No signal

  3195 

  3196     Mailboxes:

  3197       RX mailbox: 0x1800/246, TX mailbox: 0x18F6/246

  3198       Supported protocols: CoE, FoE

  3199 

  3200     SII data:

  3201       Group: AnaOut

  3202       Image: TERM_AO

  3203       Order#: EL4132

  3204 

  3205     Sync-Managers:

  3206       0: 0x1800, length 246, control 0x26, enable

  3207       1: 0x18F6, length 246, control 0x22, enable

  3208       2: 0x1000, length 0, control 0x24, enable

  3209       3: 0x1100, length 0, control 0x20, enable

  3210 

  3211     Pdos:

  3212       RXPDO "Channel 1" (0x1600), Sync-Manager 2

  3213         "Output" 0x6411:1, 16 bit

  3214       RXPDO "Channel 2" (0x1601), Sync-Manager 2

  3215         "Output" 0x6411:2, 16 bit

  3216   \end{lstlisting}

  3217 

  3218   This is nearly all of the SII category information needed to

  3219   configure the slave, supplemented with state and addressing

  3220   information.

  3221 

  3222 \item[state] (read/write) This attribute contains the slave's state.

  3223   It can be read or written:

  3224 

  3225   \begin{lstlisting}[gobble=4]

  3226     # `\textbf{cat /sys/ethercat0/slave003/state}`

  3227     OP

  3228     # `\textbf{echo SAFEOP > /sys/ethercat0/slave003/state}`

  3229   \end{lstlisting}

  3230 

  3231   This command should also be receipted with a syslog message:

  3232 

  3233   \begin{lstlisting}[gobble=4]

  3234     EtherCAT: Accepted new state SAFEOP for slave 3.

  3235     EtherCAT: Changing state of slave 3 from OP to SAFEOP.

  3236     EtherCAT: Slave states: INIT, SAFEOP, OP.

  3237   \end{lstlisting}

  3238 

  3239   After the new requested state was accepted from user space, the

  3240   operation state machine (see section~\ref{sec:fsm-op}) or the idle

  3241   state machine (section~\ref{sec:fsm-idle}) notices, that the

  3242   requested slave state differs from the current one, and therefore

  3243   executes the slave configuration state machine, until the slave has

  3244   reached the requested state.

  3245 \end{description}

  3253 It is possible to directly read or write the complete E$^2$PROM

  3106 It is possible to directly read or write the complete SII contents of the

  3254 contents of the slaves. This was introduced for the reasons below:

  3107 slaves. This was introduced for the reasons below:

  3257 \item The format of the E$^2$PROM data is still in development and

  3110 

  3258   categories can be added in the future. With read and write access,

  3111 \item The format of the SII data is still in development and categories can be

  3259   the complete memory contents can be easily backed up and restored.

  3112 added in the future. With read and write access, the complete memory contents

  3260 \item Some E$^2$PROM data fields have to be altered (like the alias

  3113 can be easily backed up and restored.

  3261   address). A quick writing must be possible for that.

  3114 

  3262 \item Through read access, analyzing category data is possible from

  3115 \item Some SII data fields have to be altered (like the alias address). A quick

  3263   user space.

  3116 writing must be possible for that.

  3117 

  3118 \item Through reading access, analyzing category data is possible from user

  3119 space.

  3120 

  3266 Reading out E$^2$PROM data is as easy as reading other attributes. Though the

  3123 Reading out SII data is as easy as other commands. Though the data are in

  3267 data are in binary format, analysis is easier with a tool like

  3124 binary format, analysis is easier with a tool like \textit{hexdump}:

  3268 \textit{hexdump}:

  3125 

  3269 

  3126 \begin{lstlisting}

  3270 \begin{lstlisting}[gobble=2]

  3127 $ `\textbf{ethercat sii\_read --slave 3 | hexdump}`

  3271   `\$` `\textbf{cat /sys/ethercat0/slave003/eeprom | hexdump}`

  3128 0000000 0103 0000 0000 0000 0000 0000 0000 008c

  3272   0000000 0103 0000 0000 0000 0000 0000 0000 008c

  3129 0000010 0002 0000 3052 07f0 0000 0000 0000 0000

  3273   0000010 0002 0000 3052 07f0 0000 0000 0000 0000

  3130 0000020 0000 0000 0000 0000 0000 0000 0000 0000

  3274   0000020 0000 0000 0000 0000 0000 0000 0000 0000

  3131 ...

  3275   ...

  3132 \end{lstlisting}

  3276 \end{lstlisting}

  3133 

  3277 

  3134 Backing up SII contents can easily done with a redirection:

  3278 Backing up E$^2$PROM contents gets as easy as copying a file:

  3135 

  3279 

  3136 \begin{lstlisting}

  3280 \begin{lstlisting}[gobble=2]

  3137 $ `\textbf{ethercat sii\_read --slave 3 > sii-of-slave3.bin}`

  3281   `\$` `\textbf{cp /sys/ethercat0/slave003/eeprom slave003.eep}`

  3138 \end{lstlisting}

  3282 \end{lstlisting}

  3139 

  3283 

  3140 To download SII contents to a slave, writing access to the master's character

  3284 Writing access is only possible as \textit{root}. Moreover writing has

  3141 device is necessary (see section~\ref{sec:cdev}).

  3285 to be explicitly enabled and is only allowed in idle mode. This is a

  3142 

  3286 safety measure, because without the correct memory contents, a slave

  3143 \begin{lstlisting}

  3287 is unusable. Writing E$^2$PROM contents in operation mode is not

  3144 # `\textbf{ethercat sii\_write --slave 3 sii-of-slave3.bin}`

  3288 provided yet.

  3145 \end{lstlisting}

  3289 

  3146 

  3290 E$^2$PROM writing is enabled with the command below:

  3147 The SII contents will be checked for validity and then sent to the slave. The

  3291 

  3148 write operation may take a few seconds.

  3292 \begin{lstlisting}[gobble=2]

  3293   # `\textbf{echo 1 > /sys/ethercat0/eeprom\_write\_enable}`

  3294 \end{lstlisting}

  3295 

  3296 The success can be seen in the Syslog messages again:

  3297 

  3298 \begin{lstlisting}[gobble=2]

  3299   EtherCAT: Slave EEPROM writing enabled.

  3300 \end{lstlisting}

  3301 

  3302 Now, it is possible to write E$^2$PROM contents to a slave. The master

  3303 will accept data through the \textit{eeprom} file and will perform a

  3304 short validation of the contents, before starting the write operation.

  3305 This validation checks the complete size and the category headers.

  3306 

  3307 \begin{lstlisting}[gobble=2]

  3308   # `\textbf{cat slave003.eep > /sys/ethercat0/slave003/eeprom}`

  3309 \end{lstlisting}

  3310 

  3311 The write operation can take a few seconds.

  3312 

  3313 \begin{lstlisting}[gobble=2]

  3314   EtherCAT: EEPROM writing scheduled for slave 3, 88 words.

  3315   EtherCAT: Writing EEPROM of slave 3...

  3316   EtherCAT: Finished writing EEPROM of slave 3.

  3317 \end{lstlisting}

  3318 

  3319 %------------------------------------------------------------------------------

  3320 

  3321 \section{User Space Tools}

  3322 \index{User space!Tools}

  3323 

  3324 There is a user space tool called \textit{lsec}\index{lsec} (``List

  3325 EtherCAT'') to visualize the EtherCAT bus. Running it usually results

  3326 in an output like this:

  3327 

  3328 \begin{lstlisting}[gobble=2]

  3329   `\$` `\textbf{lsec}`

  3330   EtherCAT bus listing for master 0:

  3331      0  1:0  OP      EK1100 Ethernet Kopplerklemme (2A E-Bus)

  3332      1  1:1  INIT    EL4132 2K. Ana. Ausgang +/-10V

  3333      2  1:2  INIT    EL4132 2K. Ana. Ausgang +/-10V

  3334      3  1:3  SAFEOP  EL4132 2K. Ana. Ausgang +/-10V

  3335      4  1:4  INIT    EL5101 Incremental Encoder Interface

  3336      5  1:5  INIT    EL1014 4K. Dig. Eingang 24V, 10s

  3337      6  1:6  OP      EL6601 1 Port Switch (Ethernet, CoE)

  3338      7  1:7  INIT    EL5101 Incremental Encoder Interface

  3339      8  1:8  INIT    EL5001 1K. SSI Encoder

  3340 \end{lstlisting}

  3341 

  3342 Every slave is displayed as one text row. The first column shows its

  3343 ring position, the second displays the ``advanced position address''

  3344 (see section~\ref{sec:addr}) and the third column displays the current

  3345 slave state. The last column is the slave's name, as it appears in the

  3346 ``general'' E$^2$PROM category.

  3347 

  3348 The lsec program is a Perl script, that evaluates the Sysfs

  3349 \textit{info} attributes of the slaves (see

  3350 section~\ref{sec:sysfs-slave}). This is done for master $0$ by

  3351 default, but the master index can be specified via command line:

  3352 

  3353 \begin{lstlisting}[gobble=2]

  3354   `\$` `\textbf{lsec -h}`

  3355   Usage: ec_list [OPTIONS]

  3356           -m <IDX>    Query master <IDX>.

  3357           -h          Show this help.

  3358 \end{lstlisting}

  3359 

  3360 This script has proved as useful for troubleshooting: If it displays

  3361 slaves, the master is up and running, and the bus connection is

  3362 present, too. It is also useful when building up a bus: It can verify

  3363 the list of slaves and help to create a process data image (see

  3364 chapter~\ref{chapter:usage}).