IgH

Master 1.5.0 Documentation

Dipl.-Ing. (FH) Florian Pose, [email protected] Ingenieurgemeinschaft

Essen, April 30, 2010 Revision 6129a5f715fb

ii

6129a5f715fb, 2010/04/30

Contents
Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 The IgH EtherCAT Master 1.1 Feature Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.2 License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 Architecture 2.1 Master Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.2 Master Phases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.3 Process Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 Application Interface 3.1 Master Conguration . . . 3.1.1 Slave Conguration 3.2 Cyclic Operation . . . . . 3.3 VoE Handlers . . . . . . . 3.4 Concurrent Master Access 3.5 Distributed Clocks . . . . x 1 1 3 5 7 8 8 11 11 11 13 13 14 15 19 19 21 23 24 24 24 27 28 30 33 33 36 36 39 40

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

4 Ethernet Devices 4.1 Network Driver Basics . . . . . . 4.2 Native EtherCAT Device Drivers 4.3 Generic EtherCAT Device Driver 4.4 Providing Ethernet Devices . . . 4.5 EtherCAT Device Interface . . . . 4.6 Patching Native Network Drivers

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

5 State Machines 5.1 State Machine Theory . . . . . . . . . 5.2 The Masters State Model . . . . . . . 5.3 The Master State Machine . . . . . . . 5.4 The Slave Scan State Machine . . . . . 5.5 The Slave Conguration State Machine 5.6 The State Change State Machine . . . 5.7 The SII State Machine . . . . . . . . . 5.8 The PDO State Machines . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

6129a5f715fb, 2010/04/30

iii

6 Mailbox Protocol Implementations 6.1 Ethernet over EtherCAT (EoE) . . . 6.2 CANopen over EtherCAT (CoE) . . 6.3 Vendor specic over EtherCAT (VoE) 6.4 Servo Prole over EtherCAT (SoE) .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

45 45 47 49 49 51 51 51 52 52 53 53 54 54 55 56 56 57 58 58 59 60 61 62 64 65 65 66 66 66 67 67 68 68 69 69 70

7 Userspace Interfaces 7.1 Command-line Tool . . . . . . . . . . . . . . . . 7.1.1 Character Devices . . . . . . . . . . . . . 7.1.2 Setting Alias Addresses . . . . . . . . . . 7.1.3 Displaying the Bus Conguration . . . . 7.1.4 Output PDO information in C Language 7.1.5 Displaying Process Data . . . . . . . . . 7.1.6 Setting a Masters Debug Level . . . . . 7.1.7 Congured Domains . . . . . . . . . . . 7.1.8 SDO Access . . . . . . . . . . . . . . . . 7.1.9 EoE Statistics . . . . . . . . . . . . . . . 7.1.10 File-Access over EtherCAT . . . . . . . . 7.1.11 Creating Topology Graphs . . . . . . . . 7.1.12 Master and Ethernet Devices . . . . . . 7.1.13 Sync Managers, PDOs and PDO Entries 7.1.14 Register Access . . . . . . . . . . . . . . 7.1.15 SDO Dictionary . . . . . . . . . . . . . . 7.1.16 SII Access . . . . . . . . . . . . . . . . . 7.1.17 Slaves on the Bus . . . . . . . . . . . . . 7.1.18 SoE IDN Access . . . . . . . . . . . . . . 7.1.19 Requesting Application-Layer States . . 7.1.20 Displaying the Master Version . . . . . . 7.1.21 Generating Slave Description XML . . . 7.2 Userspace Library . . . . . . . . . . . . . . . . . 7.2.1 Using the Library . . . . . . . . . . . . . 7.2.2 Implementation . . . . . . . . . . . . . . 7.2.3 Timing . . . . . . . . . . . . . . . . . . . 7.3 System Integration . . . . . . . . . . . . . . . . 7.3.1 Init Script . . . . . . . . . . . . . . . . . 7.3.2 Syscong File . . . . . . . . . . . . . . . 7.3.3 Starting the Master as a Service . . . . . 7.4 Debug Interfaces . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

8 Timing Aspects 73 8.0.1 Application Interface Proling . . . . . . . . . . . . . . . . . . . 73 8.0.2 Bus Cycle Measuring . . . . . . . . . . . . . . . . . . . . . . . . 74 9 Installation 77

iv

6129a5f715fb, 2010/04/30

9.1 9.2 9.3 9.4 9.5

Getting the Software . . . . . . . . . Building the Software . . . . . . . . . Building the Interface Documentation Installing the Software . . . . . . . . Automatic Device Node Creation . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

77 77 78 78 81 83 83

Bibliography Glossary

6129a5f715fb, 2010/04/30

vi

6129a5f715fb, 2010/04/30

List of Tables
3.1 5.1 7.1 8.1 9.1 Specifying a Slave Position . . . . . . . . . . . . . . . . . . . . . . . . . 12 A typical state transition table . . . . . . . . . . . . . . . . . . . . . . . 29 Application Interface Timing Comparison . . . . . . . . . . . . . . . . 68

Proling of an Application Cycle on a 2.0 GHz Processor . . . . . . . . 73 Conguration options . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

6129a5f715fb, 2010/04/30

vii

viii

6129a5f715fb, 2010/04/30

List of Figures
2.1 2.2 2.3 2.4 3.1 3.2 3.3 3.4 4.1 5.1 5.2 5.3 5.4 5.5 5.6 5.7 5.8 5.9 5.10 6.1 6.2 Master Architecture . . . . . . . Multiple masters in one module Master phases and transitions . FMMU Conguration . . . . . . Master Conguration . . . . . . Slave Conguration Attachment Concurrent Master Access . . . Distributed Clocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 . 7 . 8 . 10 . . . . 12 13 14 15

Interrupt Operation versus Interrupt-less Operation . . . . . . . . . . . 22 A typical state transition diagram . . . . . . . . . . . . . . . . . . . Transition diagram of the master state machine . . . . . . . . . . . Transition diagram of the slave scan state machine . . . . . . . . . Transition diagram of the slave conguration state machine . . . . . Transition Diagram of the State Change State Machine . . . . . . . Transition Diagram of the SII State Machine . . . . . . . . . . . . . Transition Diagram of the PDO Reading State Machine . . . . . . . Transition Diagram of the PDO Entry Reading State Machine . . . Transition Diagram of the PDO Conguration State Machine . . . . Transition Diagram of the PDO Entry Conguration State Machine . . . . . . . . . . . . . . . . . . . . 29 34 35 37 38 39 41 41 42 43

Transition Diagram of the EoE State Machine . . . . . . . . . . . . . . 46 Transition diagram of the CoE download state machine . . . . . . . . . 48

6129a5f715fb, 2010/04/30

ix

Conventions

Conventions
The following typographic conventions are used: Italic face is used for newly introduced terms and le names. Typewriter face is used for code examples and command line output. Bold typewriter face is used for user input in command lines. Data values and addresses are usually specied as hexadecimal values. These are marked in the C programming language style with the prex 0x (example: 0x88A4). Unless otherwise noted, address values are specied as byte addresses. Function names are always printed with parentheses, but without parameters. So, if a function ecrt_request_master() has empty parentheses, this shall not imply that it has no parameters. If shell commands have to be entered, this is marked by a dollar prompt:
$

Further, if a shell command has to be entered as the superuser, the prompt is a mesh:
#

6129a5f715fb, 2010/04/30

1 The IgH EtherCAT Master

This chapter covers some general information about the EtherCAT master.

1.1 Feature Summary

The list below gives a short summary of the master features. Designed as a kernel module for Linux 2.6. Implemented according to IEC 61158-12 [2] [3]. Comes with EtherCAT-capable native drivers for several common Ethernet chips, as well as a generic driver for all chips supported by the Linux kernel. The native drivers operate the hardware without interrupts. Native drivers for additional Ethernet hardware can easily be implemented using the common device interface (see sec. 4.5) provided by the master module. For any other hardware, the generic driver can be used. It uses the lower layers of the Linux network stack. The master module supports multiple EtherCAT masters running in parallel. The master code supports any Linux realtime extension through its independent architecture. RTAI [10], ADEOS, RT-Preempt [11], etc. It runs well even without realtime extensions. Common Application Interface for applications, that want to use EtherCAT functionality (see chap. 3). Domains are introduced, to allow grouping of process data transfers with different slave groups and task periods. Handling of multiple domains with dierent task periods. Automatic calculation of process data mapping, FMMU and sync manager conguration within each domain. Communication through several nite state machines. Automatic bus scanning after topology changes.

6129a5f715fb, 2010/04/30

1 The IgH EtherCAT Master Bus monitoring during operation. Automatic reconguration of slaves (for example after power failure) during operation. Distributed Clocks support (see sec. 3.5). Conguration of the slaves DC parameters through the application interface. Synchronization (oset and drift compensation) of the distributed slave clocks to the reference clock. Optional synchronization of the reference clock to the master clock. CANopen over EtherCAT (CoE) SDO upload, download and information service. Slave conguration via SDOs. SDO access from userspace and from the application. Ethernet over EtherCAT (EoE) Transparent use of EoE slaves via virtual network interfaces. Natively supports either a switched or a routed EoE network architecture. Vendor-specic over EtherCAT (VoE) Communication with vendor-specic mailbox protocols via the API. File Access over EtherCAT (FoE) Loading and storing les via the command-line tool. Updating a slaves rmware can be done easily. Servo Prole over EtherCAT (SoE) Implemented according to IEC 61800-7 [15]. Storing IDN congurations, that are written to the slave during startup. Accessing IDNs via the command-line tool. Accessing IDNs at runtime via the the user-space library. Userspace command-line-tool ethercat (see sec. 7.1) Detailed information about master, slaves, domains and bus conguration. Setting the masters debug level. Reading/Writing alias addresses. Listing slave congurations. Viewing process data. SDO download/upload; listing SDO dictionaries.

6129a5f715fb, 2010/04/30

1.2 License Loading and storing les via FoE. SoE IDN access. Access to slave registers. Slave SII (EEPROM) access. Controlling application-layer states. Generation of slave description XML and C-code from existing slaves. Seamless system integration though LSB compliance. Master and network device conguration via syscong les. Init script for master control. Virtual read-only network interface for monitoring and debugging purposes.

1.2 License
The master code is released under the terms and conditions of the GNU General Public License (GPL [4]), 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 masters application interface (see chap. 3), the userspace library (see sec. 7.2) is licensed under the terms and conditions of the GNU Lesser General Public License (LGPL [5]), version 2.1.

6129a5f715fb, 2010/04/30

1 The IgH EtherCAT Master

6129a5f715fb, 2010/04/30

2 Architecture
The EtherCAT master is integrated into the Linux 2.6 kernel. This was an early design decision, which has been made for several reasons: Kernel code has signicantly better realtime characteristics, i. e. less latency than userspace code. It was foreseeable, that a eldbus master has a lot of cyclic work to do. Cyclic work is usually triggered by timer interrupts inside the kernel. The execution delay of a function that processes timer interrupts is less, when it resides in kernelspace, because there is no need of time-consuming context switches to a userspace process. It was also foreseeable, that the master code has to directly communicate with the Ethernet hardware. This has to be done in the kernel anyway (through network device drivers), which is one more reason for the master code being in kernelspace. Figure 2.1 gives a general overview of the master architecture. The components of the master environment are described below: Master Module Kernel module containing one or more EtherCAT master instances (see sec. 2.1), the Device Interface (see sec. 4.5) and the Application Interface (see chap. 3). Device Modules EtherCAT-capable Ethernet device driver modules, that oer their devices to the EtherCAT master via the device interface (see sec. 4.5). These modied 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 kernels network stack as usual. Application A program that uses the EtherCAT master (usually for cyclic exchange of process data with EtherCAT slaves). These programs are not part of the EtherCAT master code1 , but have to be generated or written by the user. An application can request a master through the application interface (see chap. 3). If this succeeds, it has the control over the master: It can provide a bus conguration and exchange process data. Applications can be kernel modules (that use the kernel application interface directly) or userspace programs, that use the application interface via the EtherCAT library (see sec. 7.2).
1

Although there are some examples provided in the examples/ directory.

6129a5f715fb, 2010/04/30

2 Architecture

ecrt_*()

libethercat

Application Interface

Userspace Application

'ethercat' Tool

Userspace Kernelspace
Character Device

Application Module

EtherCAT Master Module

Generic Ethernet Driver Module

Master 1
Packet Socket

Task

Master 0
Generic Ethernet Device

Device Interface ecdev_*()

netif_*()

Native EtherCAT-capable Ethernet Driver

Standard Ethernet Driver

net_device

net_device

net_device

Hardware

NIC

NIC

NIC

EtherCAT

Ethernet

EtherCAT

Figure 2.1: Master Architecture

6129a5f715fb, 2010/04/30

Network Stack

ecrt_*()

Application Interface

2.1 Master Module

2.1 Master Module

The EtherCAT master kernel module ec master can contain multiple master instances. Each master waits for a certain Ethernet device identied by its MAC address. These addresses have to be specied on module loading via the main devices module parameter. The number of master instances to initialize is taken from the number of MAC addresses given. The below command loads the master module with a single master instance that waits for the Ethernet device with the MAC address 00:0E:0C:DA:A2:20. The master will be accessible via index 0.
# modprobe ec master main devices=00:0E:0C:DA:A2:20

MAC addresses for multiple masters have to be separated by commas:

# modprobe ec master main devices=00:0E:0C:DA:A2:20,00:e0:81:71:d5:1c

The two masters can be addressed by their indices 0 and 1 respectively (see gure 2.2). The master index is needed for the ecrt_master_request() function of the application interface (see chap. 3) and the --master option of the ethercat command-line tool (see sec. 7.1), which defaults to 0.
Kernel space EtherCAT master module

master 0

master 1

Figure 2.2: Multiple masters in one module

Debug Level The master module also has a parameter debug level to set the initial debug level for all masters (see also 7.1.6). Init Script In most cases it is not necessary to load the master module and the Ethernet driver modules manually. There is an init script available, so the master can be started as a service (see sec. 7.3). Syslog The master module outputs information about its state and events to the kernel ring buer. These also end up in the system logs. The above module loading command should result in the messages below:

6129a5f715fb, 2010/04/30

2 Architecture
# dmesg | tail -2 EtherCAT : Master driver 1.5.0 EtherCAT : 2 masters waiting for devices . # tail -2 /var/log/messages Jul 4 10:22:45 ethercat kernel : EtherCAT : Master driver 1.5.0 Jul 4 10:22:45 ethercat kernel : EtherCAT : 2 masters waiting for devices .

All EtherCAT master output is prexed with EtherCAT which makes searching the logs easier.

2.2 Master Phases

Every EtherCAT master provided by the master module (see sec. 2.1) runs through several phases (see g. 2.3):
Device connection Master request

Orphaned Device disconnection

Idle Master release

Operation

Figure 2.3: Master phases and transitions Orphaned phase This mode takes eect, when the master still waits for its Ethernet device to connect. No bus communication is possible until then. Idle phase takes eect when the master has accepted an Ethernet device, but is not requested by any application yet. The master runs its state machine (see sec. 5.3), 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 conguration. Operation phase The master is requested by an application that can provide a bus conguration and exchange process data.

2.3 Process Data

This section shall introduce a few terms and ideas how the master handles process data.

6129a5f715fb, 2010/04/30

2.3 Process Data Process Data Image Slaves oer their inputs and outputs by presenting the master so-called Process Data Objects (PDOs). The available PDOs can be either determined by reading out the slaves TXPDO and RXPDO SII categories from the E2 PROM (in case of xed PDOs) or by reading out the appropriate CoE objects (see sec. 6.2), if available. The application can register the PDOs entries for exchange during cyclic operation. The sum of all registered PDO entries denes the process data image, which is exchanged via datagrams with logical memory access (like LWR, LRD or LRW) introduced in [2, sec. 5.4]. Process Data Domains The process data image can be easily managed by creating so-called domains, which allow grouped PDO exchange. They also take care of managing the datagram structures needed to exchange the PDOs. Domains are mandatory for process data exchange, so there has to be at least one. They were introduced for the following reasons: The maximum size of a datagram is limited due to the limited size of an Ethernet frame: The maximum data size is the Ethernet data eld size minus the EtherCAT frame header, EtherCAT datagram header and EtherCAT datagram footer: 1500 2 12 2 = 1484 octets. If the size of the process data image exceeds this limit, multiple frames have to be sent, and the image has to be partitioned for the use of multiple datagrams. A domain manages this automatically. Not every PDO has to be exchanged with the same frequency: The values of PDOs can vary slowly over time (for example temperature values), so exchanging them with a high frequency would just waste bus bandwidth. For this reason, multiple domains can be created, to group dierent PDOs and so allow separate exchange. There is no upper limit for the number of domains, but each domain occupies one FMMU in each slave involved, so the maximum number of domains is de facto limited by the slaves. FMMU Conguration An application can register PDO entries for exchange. Every PDO entry and its parent PDO is part of a memory area in the slaves physical memory, that is protected by a sync manager [2, sec. 6.7] 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 entry of a slave is registered for exchange with a certain domain, one FMMU will be congured to map the complete sync-managerprotected memory, the PDO entry resides in. If a second PDO entry of the same slave is registered for process data exchange within the same domain, and it resides in the same sync-manager-protected memory as the rst one, the FMMU conguration is

6129a5f715fb, 2010/04/30

2 Architecture not altered, because the desired memory is already part of the domains process data image. If the second PDO entry would belong to another sync-manager-protected area, this complete area would also be included into the domains process data image. Figure 2.4 gives an overview, how FMMUs are congured to map physical memory to logical process data images.
Slave0 RAM SM0 SM1 Slave1 RAM SM3

FMMU0

FMMU1

FMMU2

FMMU0

Domain0 Image

Domain1 Image

Registered PDO Entries

Figure 2.4: FMMU Conguration

10

6129a5f715fb, 2010/04/30

3 Application Interface
The application interface provides functions and data structures for applications to access an EtherCAT master. The complete documentation of the interface is included as Doxygen [12] comments in the header le include/ecrt.h. It can either be read directly from the le comments, or as a more comfortable HTML documentation. The HTML generation is described in sec. 9.3. The following sections cover a general description of the application interface. Every application should use the master in two steps: Conguration The master is requested and the conguration is applied. For example, domains are created, slaves are congured and PDO entries are registered (see sec. 3.1). Operation Cyclic code is run and process data are exchanged (see sec. 3.2). Example Applications There are a few example applications in the examples/ subdirectory of the master code. They are documented in the source code.

3.1 Master Conguration

The bus conguration is supplied via the application interface. Figure 3.1 gives an overview of the objects, that can be congured by the application.

3.1.1 Slave Conguration

The application has to tell the master about the expected bus topology. This can be done by creating slave congurations. A slave conguration can be seen as an expected slave. When a slave conguration is created, the application provides the bus position (see below), vendor id and product code. When the bus conguration is applied, the master checks, if there is a slave with the given vendor id and product code at the given position. If this is the case, the slave conguration is attached to the real slave on the bus and the slave is congured according to the settings provided by the application. The state of a slave conguration can either be queried via the application interface or via the commandline tool (see sec. 7.1.3).

6129a5f715fb, 2010/04/30

11

3 Application Interface
Master Index n Domain

n Slave Configuration Alias Position Vendor ID Product Code n n Sync Manager Index Direction n PDO Index n

n PDO Entry Index Subindex Bitlength

SDO Configuration Index Subindex Data

SDO Request Index Subindex

Figure 3.1: Master Conguration Slave Position The slave position has to be specied as a tuple of alias and position. This allows addressing slaves either via an absolute bus position, or a stored identier called alias, or a mixture of both. The alias is a 16-bit value stored in the slaves E2 PROM. It can be modied via the command-line tool (see sec. 7.1.2). Table 3.1 shows, how the values are interpreted. Table 3.1: Specifying a Slave Position Position Interpretation 0 0 65535 Position addressing. The position parameter is interpreted as the absolute ring position in the bus. 1 65535 0 65535 Alias addressing. The position parameter is interpreted as relative position after the rst slave with the given alias address. Alias Figure 3.2 shows an example of how slave congurations are attached. Some of the congurations were attached, while others remain detached. The below lists gives the reasons beginning with the top slave conguration. 1. A zero alias means to use simple position addressing. Slave 1 exists and vendor id and product code match the expected values. 2. Although the slave with position 0 is found, the product code does not match, so the conguration is not attached.

12

6129a5f715fb, 2010/04/30

3.2 Cyclic Operation

Slaves
0 Vendor: Product: Alias: 0x00000001 0x00000001 0x0000

Slave Configurations
Alias: Position: Vendor: Product: Alias: Position: Vendor: Product: Alias: Position: Vendor: Product: Alias: Position: Vendor: Product: Alias: Position: Vendor: Product: 0x0000 1 0x00000002 0x00000004 0x0000 0 0x00000001 0x00000002 0x2000 0 0x00000001 0x00000002 0x3000 0 0x00000001 0x00000002 0x2000 1 0x00000001 0x00000002

1 Vendor: Product: Alias:

0x00000002 0x00000004 0x1000

2 Vendor: Product: Alias:

0x00000001 0x00000002 0x2000

3 Vendor: Product: Alias:

0x00000001 0x00000002 0x0000

Figure 3.2: Slave Conguration Attachment 3. The alias is non-zero, so alias addressing is used. Slave 2 is the rst slave with alias 0x2000. Because the position value is zero, the same slave is used. 4. There is no slave with the given alias, so the conguration can not be attached. 5. Slave 2 is again the rst slave with the alias 0x2000, but position is now 1, so slave 3 is attached.

3.2 Cyclic Operation

To enter cyclic operation mode, the master has to be activated to calculate the process data image and apply the bus conguration for the rst time. After activation, the application is in charge to send and receive frames.

3.3 VoE Handlers

During the conguration phase, the application can create handlers for the VoE mailbox protocol described in sec. 6.3. One VoE handler always belongs to a certain slave conguration, so the creation function is a method of the slave conguration. A VoE handler manages the VoE data and the datagram used to transmit and receive VoE messages. Is contains the state machine necessary to transfer VoE messages.

6129a5f715fb, 2010/04/30

13

3 Application Interface The VoE state machine can only process one operation at a time. As a result, either a read or write operation may be issued at a time1 . After the operation is initiated, the handler must be executed cyclically until it is nished. 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 the use of VoE handlers see the documentation of the application interface functions and the example applications provided in the examples/ directory.

3.4 Concurrent Master Access

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 sec. 6.1). 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 to know the appropriate kind of lock. For example if the application is in kernelspace and uses RTAI functionality, ordinary kernel semaphores would not be sucient. For that, an important design decision was made: The application that reserved a master must have the total control, therefore it has to take responsibility for providing the appropriate locking mechanisms. If another instance wants to access the master, it has to request the bus access via callbacks, that have to be provided by the application. Moreover the application can deny access to the master if it considers it to be awkward at the moment.
Master Module Application Module
Application Interface

Task

Master0

EoE

Figure 3.3: Concurrent Master Access

1

If simultaneous sending and receiving is desired, two VoE handlers can be created for the slave conguration.

14

6129a5f715fb, 2010/04/30

3.5 Distributed Clocks Figure 3.3 exemplary shows, how two processes share one master: The applications 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 access the bus from time to time, but the EoE process does this by asking the application to do the bus access for it. In this way, the application can use the appropriate locking mechanism to avoid accessing the bus at the same time. See the application interface documentation (chap. 3) for how to use these callbacks.

3.5 Distributed Clocks

From version 1.5, the master supports EtherCATs Distributed Clocks feature. It is possible to synchronize the slave clocks on the bus to the reference clock (which is the local clock of the rst slave with DC support) and to synchronize the reference clock to the master clock (which is the local clock of the master). All other clocks on the bus (after the reference clock) are considered as slave clocks (see g. 3.4).
Master

Slave 0 Master Clock

(No DC)

Slave 1

Slave 2

Slave n

Reference Clock

Slave Clocks

Figure 3.4: Distributed Clocks

Local Clocks Any EtherCAT slave that supports DC has a local clock register with nanosecond resolution. If the slave is powered, the clock starts from zero, meaning that when slaves are powered on at dierent times, their clocks will have dierent values. These osets have to be compensated by the distributed clocks mechanism. On the other hand, the clocks do not run exactly with the same speed, since the used quarts units have a natural frequency deviation. This deviation is usually very small, but over longer periods, the error would accumulate and the dierence between local clocks would grow. This clock drift has also to be compensated by the DC mechanism. Application Time The common time base for the bus has to be provided by the application. This application time tapp is used 1. to congure the slaves clock osets (see below), 2. to program the slaves start times for sync pulse generation (see below). 3. to synchronize the reference clock to the master clock (optional).

6129a5f715fb, 2010/04/30

15

3 Application Interface Oset Compensation For the oset compensation, each slave provides a System Time Oset register to , that is added to the internal clock value tint to get the System Time tsys :

tsys = tint + to tint = tsys to

(3.1)

The master reads the values of both registers to calculate a new system time oset in a way, that the resulting system time shall match the masters application time tapp :
!

tsys = tapp tint + to to to to = = = =

!

(3.2)

tapp tapp tint tapp (tsys to ) tapp tsys + to

(3.3)

The small time oset error resulting from the dierent times of reading and writing the registers will be compensated by the drift compensation. Drift Compensation The drift compensation is possible due to a special mechanism in each DC-capable slave: A write operation to the System time register will cause the internal time control loop to compare the written time (minus the programmed transmission delay, see below) to the current system time. The calculated time error will be used as an input to the time controller, that will tune the local clock speed to be a little faster or slower2 , according to the sign of the error. Transmission Delays The Ethernet frame needs a small amount of time to get from slave to slave. The resulting transmission delay times accumulate on the bus and can reach microsecond magnitude and thus have to be considered during the drift compensation. EtherCAT slaves supporting DC provide a mechanism to measure the transmission delays: For each of the four slave ports there is a receive time register. A write operation to the receive time register of port 0 starts the measuring and the current system time is latched and stored in a receive time register once the frame is received on the corresponding port. The master can read out the relative receive times, then calculate time delays between the slaves (using its knowledge of the bus topology), and nally calculate the time delays from the reference clock to each slave. These values are programmed into the slaves transmission delay registers. In this way, the drift compensation can reach nanosecond synchrony.
2

The local slave clock will be incremented either with 9 ns, 10 ns or 11 ns every 10 ns.

16

6129a5f715fb, 2010/04/30

3.5 Distributed Clocks Checking Synchrony DC-capable slaves provide the 32-bit System time dierence register at address 0x092c, where the system time dierence of the last drift compensation is stored in nanosecond resolution and in sign-and-magnitude coding3 . To check for bus synchrony, the system time dierence registers can also be cyclically read via the command-line-tool (see sec. 7.1.14):
$ watch -n0 "ethercat reg read -p4 -tsm32 0x92c"

Sync Signals Synchronous clocks are only the prerequisite for synchronous events on the bus. Each slave with DC support provides two sync signals, that can be programmed to create events, that will for example cause the slave application to latch its inputs on a certain time. A sync event can either be generated once or cyclically, depending on what makes sense for the slave application. Programming the sync signals is a matter of setting the so-called AssignActivate word and the sync signals cycle- and shift times. The AssignActivate word is slave-specic and has to be taken from the XML slave description (Device Dc), where also typical sync signal congurations OpModes can be found.

This allows broadcast-reading all system time dierence registers on the bus to get an upper approximation

6129a5f715fb, 2010/04/30

17

3 Application Interface

18

6129a5f715fb, 2010/04/30

4 Ethernet Devices
The EtherCAT protocol is based on the Ethernet standard, so a master relies on standard Ethernet hardware to communicate with the bus. The term device is used as a synonym for Ethernet network interface hardware. Native Ethernet Device Drivers There are native device driver modules (see sec. 4.2) that handle Ethernet hardware, which a master can use to connect to an EtherCAT bus. They oer their Ethernet hardware to the master module via the device interface (see sec. 4.5) and must be capable to prepare Ethernet devices either for EtherCAT (realtime) operation or for normal operation using the kernels network stack. The advantage of this approach is that the master can operate nearly directly on the hardware, which allows a high performance. The disadvantage is, that there has to be an EtherCAT-capable version of the original Ethernet driver. Generic Ethernet Device Driver From master version 1.5, there is a generic Ethernet device driver module (see sec. 4.3), that uses the lower layers of the network stack to connect to the hardware. The advantage is, that arbitrary Ethernet hardware can be used for EtherCAT operation, independently of the actual hardware driver (so all Linux Ethernet drivers are supported without modications). The disadvantage is, that this approach does not support realtime extensions like RTAI, because the Linux network stack is addressed. Moreover the performance is a little worse than the native approach, because the Ethernet frame data have to traverse the network stack.

4.1 Network Driver Basics

EtherCAT relies on Ethernet hardware and the master needs a physical Ethernet device to communicate with the bus. Therefore it is necessary to understand how Linux handles network devices and their drivers, respectively. Tasks of a Network Driver Network device drivers usually handle the lower two layers of the OSI model, that is the physical layer and the data-link layer. A network device itself natively handles the physical layer issues: It represents the hardware to connect to the medium and to send and receive data in the way, the physical layer protocol describes. The network device driver is responsible for getting data from the

6129a5f715fb, 2010/04/30

19

4 Ethernet Devices kernels networking stack and forwarding it to the hardware, that does the physical transmission. If data is received by the hardware respectively, the driver is notied (usually by means of an interrupt) and has to read the data from the hardware memory and forward it to the network stack. There are a few more tasks, a network device driver has to handle, including queue control, statistics and device dependent features. Driver Startup Usually, a driver searches for compatible devices on module loading. For PCI drivers, this is done by scanning the PCI bus and checking for known device IDs. If a device is found, data structures are allocated and the device is taken into operation. Interrupt Operation A network device usually provides a hardware interrupt that is used to notify the driver of received frames and success of transmission, or errors, respectively. The driver has to register an interrupt service routine (ISR), that is executed each time, the hardware signals such an event. If the interrupt was thrown by the own device (multiple devices can share one hardware interrupt), the reason for the interrupt has to be determined by reading the devices interrupt register. For example, if the ag for received frames is set, frame data has to be copied from hardware to kernel memory and passed to the network stack. The net_device Structure The driver registers a net_device structure for each device to communicate with the network stack and to create a network interface. In case of an Ethernet driver, this interface appears as ethX, where X is a number assigned by the kernel on registration. The net_device structure receives events (either from userspace or from the network stack) via several callbacks, which have to be set before registration. Not every callback is mandatory, but for reasonable operation the ones below are needed in any case:
open() This function is called when network communication has to be started, for example after a command ip link set ethX up from userspace. Frame reception

has to be enabled by the driver.

stop() The purpose of this callback is to close the device, i. e. make the hardware

stop receiving frames.

hard_start_xmit() This function is called for each frame that has to be transmitted. The network stack passes the frame as a pointer to an sk_buff structure (socket

buer, see below), which has to be freed after sending.

get_stats() This call has to return a pointer to the devices net_device_stats struc-

ture, which permanently has to be lled with frame statistics. This means, that every time a frame is received, sent, or an error happened, the appropriate counter in this structure has to be increased. The actual registration is done with the register_netdev() call, unregistering is done with unregister_netdev().

20

6129a5f715fb, 2010/04/30

4.2 Native EtherCAT Device Drivers The netif Interface All other communication in the direction interface network stack is done via the netif_*() calls. For example, on successful device opening, the network stack has to be notied, that it can now pass frames to the interface. This is done by calling netif_start_queue(). After this call, the hard_start_xmit() callback can be called by the network stack. Furthermore a network driver usually manages a frame transmission queue. If this gets lled up, the network stack has to be told to stop passing further frames for a while. This happens with a call to netif_stop_queue(). If some frames have been sent, and there is enough space again to queue new frames, this can be notied with netif_wake_queue(). Another important call is netif_receive_skb()1 : It passes a frame to the network stack, that was just received by the device. Frame data has to be included in a so-called socket buer for that (see below). Socket Buers Socket buers are the basic data type for the whole network stack. They serve as containers for network data and are able to quickly add data headers and footers, or strip them o again. Therefore a socket buer consists of an allocated buer and several pointers that mark beginning of the buer (head), beginning of data (data), end of data (tail) and end of buer (end). In addition, a socket buer holds network header information and (in case of received data) a pointer to the net_device, it was received on. There exist functions that create a socket buer (dev_alloc_skb()), add data either from front (skb_push()) or back (skb_put()), remove data from front (skb_pull()) or back (skb_trim()), or delete the buer (kfree_skb()). A socket buer is passed from layer to layer, and is freed by the layer that uses it the last time. In case of sending, freeing has to be done by the network driver.

4.2 Native EtherCAT Device Drivers

There are a few requirements, that applies to Ethernet hardware when used with a native Ethernet driver with EtherCAT functionality. Dedicated Hardware For performance and realtime purposes, the EtherCAT master needs direct and exclusive access to the Ethernet hardware. This implies that the network device must not be connected to the kernels network stack as usual, because the kernel would try to use it as an ordinary Ethernet device. Interrupt-less Operation EtherCAT frames travel through the logical EtherCAT ring and are then sent back to the master. Communication is highly deterministic: A frame is sent and will be received again after a constant time, so there is no need to
1

This function is part of the NAPI (New API), that replaces the kernel 2.4 technique for interfacing to the network stack (with netif_rx()). NAPI is a technique to improve network performance on Linux. Read more in http://www.cyberus.ca/~hadi/usenix-paper.tgz.

6129a5f715fb, 2010/04/30

21

4 Ethernet Devices notify the driver about frame reception: The master can instead query the hardware for received frames, if it expects them to be already received. Figure 4.1 shows two workows for cyclic frame transmission and reception with and without interrupts.
Interrupt Operation ... Data Processing Frame Assembly Realtime Cycle Realtime Cycle Frame Sending Interruptless Operation ... ISR Frame Dissection Data Processing Frame Assembly Frame Sending

Interrupt ISR Frame Dissection

Time

Data Processing ...

ISR ...

Figure 4.1: Interrupt Operation versus Interrupt-less Operation In the left workow Interrupt Operation, the data from the last cycle is rst processed and a new frame is assembled with new datagrams, which is then sent. The cyclic work is done for now. Later, when the frame is received again by the hardware, an interrupt is triggered and the ISR is executed. The ISR will fetch the frame data from the hardware and initiate the frame dissection: The datagrams will be processed, so that the data is ready for processing in the next cycle. In the right workow Interrupt-less Operation, there is no hardware interrupt enabled. Instead, the hardware will be polled by the master by executing the ISR. If the frame has been received in the meantime, it will be dissected. The situation is now the same as at the beginning of the left workow: The received data is processed and a new frame is assembled and sent. There is nothing to do for the rest of the cycle. The interrupt-less operation is desirable, because hardware interrupts are not conducive in improving the drivers realtime behaviour: Their indeterministic incidences contribute to increasing the jitter. Besides, if a realtime extension (like RTAI) is used, some additional eort would have to be made to prioritize interrupts. Ethernet and EtherCAT Devices Another issue lies in the way Linux handles devices of the same type. For example, a PCI driver scans the PCI bus for devices it can handle. Then it registers itself as the responsible driver for all of the devices found. The problem is, that an unmodied driver can not be told to ignore a device because it will be used for EtherCAT later. There must be a way to handle multiple devices

22

6129a5f715fb, 2010/04/30

4.3 Generic EtherCAT Device Driver of the same type, where one is reserved for EtherCAT, while the other is treated as an ordinary Ethernet device. For all this reasons, the author decided that the only acceptable solution is to modify standard Ethernet drivers in a way that they keep their normal functionality, but gain the ability to treat one or more of the devices as EtherCAT-capable. Below are the advantages of this solution: No need to tell the standard drivers to ignore certain devices. One networking driver for EtherCAT and non-EtherCAT devices. No need to implement a network driver from scratch and running into issues, the former developers already solved. The chosen approach has the following disadvantages: The modied driver gets more complicated, as it must handle EtherCAT and non-EtherCAT devices. Many additional case dierentiations in the driver code. Changes and bug xes on the standard drivers have to be ported to the EtherCAT-capable versions from time to time.

4.3 Generic EtherCAT Device Driver

Since there are approaches to enable the complete Linux kernel for realtime operation [11], it is possible to operate without native implementations of EtherCAT-capable Ethernet device drivers and use the Linux network stack instead. Fig. 2.1 shows the Generic Ethernet Driver Module, that connects to local Ethernet devices via the network stack. The kernel module is named ec_generic and can be loaded after the master module like a native EtherCAT-capable Ethernet driver. The generic device driver scans the network stack for interfaces, that have been registered by Ethernet device drivers. It oers all possible devices to the EtherCAT master. If the master accepts a device, the generic driver creates a packet socket (see man 7 packet) with socket_type set to SOCK_RAW, bound to that device. All functions of the device interface (see sec. 4.5) will then operate on that socket. Below are the advantages of this solution: Any Ethernet hardware, that is covered by a Linux Ethernet driver can be used for EtherCAT. No modications have to be made to the actual Ethernet drivers. The generic approach has the following disadvantages: The performance is a little worse than the native approach, because the frame data have to traverse the lower layers of the network stack. It is not possible to use in-kernel realtime extensions like RTAI with the generic driver, because the network stack code uses dynamic memory allocations and other things, that could cause the system to freeze in realtime context.

6129a5f715fb, 2010/04/30

23

4 Ethernet Devices

4.4 Providing Ethernet Devices

After loading the master module, additional module(s) have to be loaded to oer devices to the master(s) (see sec. 4.5). The master module knows the devices to choose from the module parameters (see sec. 2.1). If the init script is used to start the master, the drivers and devices to use can be specied in the syscong le (see sec. 7.3.2). Modules oering Ethernet devices can be native EtherCAT-capable network driver modules (see sec. 4.2) or the generic EtherCAT device driver module (see sec. 4.3).

4.5 EtherCAT Device Interface

An anticipation to the section about the master module (sec. 2.1) has to be made in order to understand the way, a network device driver module can connect a device to a specic 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 devices/ecdev.h, coming with the EtherCAT master code. This header oers a function interface for EtherCAT devices. All functions of the device interface are named with the prex ecdev. The documentation of the device interface can be found in the header le or in the appropriate module of the interface documentation (see sec. 9.3 for generation instructions).

4.6 Patching Native Network Drivers

This section will describe, how to make a standard Ethernet driver EtherCAT-capable, using the native approach (see sec. 4.2). Unfortunately, there is no standard procedure to enable an Ethernet driver for use with the EtherCAT master, but there are a few common techniques. 1. A rst simple rule is, that netif_*() calls must be avoided for all EtherCAT devices. As mentioned before, EtherCAT devices have no connection to the network stack, and therefore must not call its interface functions. 2. Another important thing is, that EtherCAT devices should be operated without interrupts. So any calls of registering interrupt handlers and enabling interrupts at hardware level must be avoided, too.

24

6129a5f715fb, 2010/04/30

4.6 Patching Native Network Drivers 3. The master does not use a new socket buer for each send operation: Instead there is a x one allocated on master initialization. This socket buer is lled with an EtherCAT frame with every send operation and passed to the hard_start_xmit() callback. For that it is necessary, that the socket buer is not be freed by the network driver as usual. An Ethernet driver usually handles several Ethernet devices, each described by a net_device structure with a priv_data eld 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 ec_device_t object returned by ecdev_offer() (see sec. 4.5) 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 be found by searching the string ecdev in the le devices/8139too-2.6.24-ethercat.c.

6129a5f715fb, 2010/04/30

25

4 Ethernet Devices

26

6129a5f715fb, 2010/04/30

5 State Machines
Many parts of the EtherCAT master are implemented as nite state machines (FSMs). Though this leads to a higher grade of complexity in some aspects, is opens many new possibilities. The below short code example exemplary shows how to read all slave states and moreover illustrates the restrictions of sequential coding:
1 2 3

ec_datagram_brd ( datagram , 0 x0130 , 2); // prepare datagram if ( ec_mas te r _ s im p l e_ i o ( master , datagram )) return -1; slave_states = EC_READ_U8 ( datagram - > data ); // process datagram

The ec master simple io() function provides a simple interface for synchronously sending a single datagram and receiving the result1 . Internally, it queues the specied datagram, invokes the 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, reecting 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 diculty when only one instance is using the master, but if more instances want to (synchronously2 ) 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 approach, this would result in having one phase of active waiting for each instance, which would be non-acceptable especially in realtime circumstances, because of the huge time overhead. A possible solution is, that all instances would be executed sequentially to queue their datagrams, then give the control to the next instance instead of waiting for the datagram reception. Finally, bus IO is done by a higher instance, which means that all queued datagrams are sent and received. The next step is to execute all instances again, which then process their received datagrams and issue new ones. This approach results in all instances having to retain their state, when giving the control back to the higher instance. It is quite obvious to use a nite state machine model in this case. Section 5.1 will introduce some of the theory used, while the
1

For all communication issues have been meanwhile sourced out into state machines, the function is deprecated and stopped existing. Nevertheless it is adequate for showing its own restrictions. 2 At this time, synchronous master access will be adequate to show the advantages of an FSM. The asynchronous approach will be discussed in sec. 6.1

6129a5f715fb, 2010/04/30

27

5 State Machines listings below show the basic approach by coding the example from above as a state machine:
1 2 3 4 5

// state 1 ec_datagram_brd ( datagram , 0 x0130 , 2); // prepare datagram ec_master_queue ( master , datagram ); // queue datagram next_state = state_2 ; // state processing finished

After all instances executed their current state and queued their datagrams, these are sent and received. Then the respective next states are executed:
1 2 3 4 5 6 7

if ( datagram - > state != E C _ D G R A M _ S T A T E _ R E C E I V E D ) {

next_state = state_error ; return ; // state processing finished } slave_states = EC_READ_U8 ( datagram - > data ); // process datagram // state processing finished .

// state 2

See sec. 5.2 for an introduction to the state machine programming concept used in the master code.

5.1 State Machine Theory

A nite state machine [8] is a model of behavior with inputs and outputs, where the outputs not only depend on the inputs, but the history of inputs. The mathematical denition of a nite state machine (or nite automaton) is a six-tuple (, , S, s0 , , ), with the input alphabet , with = , containing all input symbols, the output alphabet , with = , containing all output symbols, the set of states S, with S = , the set of initial states s0 with s0 S, s0 = the transition function : S S the output function . The state transition function is often specied by a state transition table, or by a state transition diagram. The transition table oers a matrix view of the state machine behavior (see table 5.1). The matrix rows correspond to the states (S = {s0 , s1 , s2 }) and the columns correspond to the input symbols ( = {a, b, }). The table contents in a certain row i and column j then represent the next state (and possibly the output) for the case, that a certain input symbol j is read in the state si .

28

6129a5f715fb, 2010/04/30

5.1 State Machine Theory

Table 5.1: A typical state transition table s0 s1 s2 a s1 s2 s0 b s1 s1 s0 s2 s0 s0

The state diagram for the same example looks like the one in gure 5.1. The states are represented as circles or ellipses and the transitions are drawn as arrows between them. Close to a transition arrow can be the condition that must be fullled to allow the transition. The initial state is marked by a lled black circle with an arrow pointing to the respective state.
b a, b s0 a, b, s2 a s1

Figure 5.1: A typical state transition diagram

Deterministic and non-deterministic state machines A state machine can be deterministic, meaning that for one state and input, there is one (and only one) following state. In this case, the state machine has exactly one starting state. Non-deterministic state machines can have more than one transitions for a single state-input combination. There is a set of starting states in the latter case. Moore and Mealy machines There is a distinction between so-called Moore machines, and Mealy machines. Mathematically spoken, the distinction lies in the output function : If it only depends on the current state ( : S ), the machine corresponds to the Moore Model. Otherwise, if is a function of a state and the input alphabet ( : S ) the state machine corresponds to the Mealy model. Mealy machines are the more practical solution in most cases, because their design allows machines with a minimum number of states. In practice, a mixture of both models is often used. Misunderstandings about state machines There is a phenomenon called state explosion, that is often taken as a counter-argument against general use of state

6129a5f715fb, 2010/04/30

29

5 State Machines machines in complex environments. It has to be mentioned, that this point is misleading [9]. State explosions happen usually as a result of a bad state machine design: Common mistakes are storing the present values of all inputs in a state, or not dividing a complex state machine into simpler sub state machines. The EtherCAT master uses several state machines, that are executed hierarchically and so serve as sub state machines. These are also described below.

5.2 The Masters State Model

This section will introduce the techniques used in the master to implement state machines. State Machine Programming There are certain ways to implement a state machine in C code. An obvious way is to implement the dierent states and actions by one big case dierentiation:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20

enum { STATE_1 , STATE_2 , STATE_3 }; int state = STATE_1 ; void sta te_mac hine_r un ( void * priv_data ) { switch ( state ) { case STATE_1 :
action_1 (); state = STATE_2 ; break ; case STATE_2 : action_2 () if ( some_condition ) state = STATE_1 ; else state = STATE_3 ; break ; case STATE_3 : action_3 (); state = STATE_1 ; break ; } }

For small state machines, this is an option. The disadvantage is, that with an increasing number of states the code soon gets complex and an additional case dierentiation is executed each run. Besides, lots of indentation is wasted. The method used in the master is to implement every state in an own function and to store the current state function with a function pointer:
1

void (* state )( void *) = state1 ;

30

6129a5f715fb, 2010/04/30

5.2 The Masters State Model

2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21

void state_mac hine_r un ( void * priv_data ) {

state ( priv_data ); }

void state1 ( void * priv_data ) {

action_1 (); state = state2 ; }

void state2 ( void * priv_data ) {

action_2 (); if ( some_condition ) state = state1 ; else state = state2 ; }

void state3 ( void * priv_data ) {

action_3 (); state = state1 ; }

In the master code, state pointers of all state machines3 are gathered in a single object of the ec_fsm_master_t class. This is advantageous, because there is always one instance of every state machine available and can be started on demand. 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 sec. 5.1. As mentioned, the Mealy model oers a higher exibility, which can be seen in the listing below:
1 2 3 4 5 6 7 8 9 10

void state7 ( void * priv_data ) { if ( some_condition ) {

action_7a (); state = state1 ; }

else {
action_7b (); state = state8 ;

} }
3

The state function executes the actions depending on the state transition, that is about to be done.
7

All except for the EoE state machine, because multiple EoE slaves have to be handled in parallel. For this reason each EoE handler object has its own state pointer.

6129a5f715fb, 2010/04/30

31

5 State Machines The most exible alternative is to execute certain actions depending on the state, followed by some actions dependent on the state transition:
1 2 3 4 5 6 7 8 9 10 11

void state9 ( void * priv_data ) {

action_9 (); if ( some_condition ) { action_9a (); state = state7 ; } else { action_9b (); state = state10 ; } }

This model is often used in the master. It combines the best aspects of both approaches. 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 workows and moreover avoids the state explosion phenomenon described in sec. 5.1. 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. 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 usually done like in the listing below, which is taken out of the slave conguration state machine code:
1 2 3 4 5 6 7 8 9 10 11 12 13 14

void e c _ f s m _ s l a v e c o n f _ s a f e o p ( ec_fsm_t * fsm )

{ fsm - > change_state ( fsm ); // execute state change // sub state machine

if ( fsm - > change_state == ec_fsm_error ) {

fsm - > slave_state = ec_fsm_end ; return ; }

if ( fsm - > change_state != ec_fsm_end ) return ;

// continue state processing ...

32

6129a5f715fb, 2010/04/30

5.3 The Master State Machine

change_state is the state pointer of the state change state machine. The state

function, the pointer points on, is executed. . .

6 11

. . . either until the state machine terminates with the error state . . . . . . or until the state machine terminates in the end state. Until then, the higher state machine remains in the current state and executes the sub state machine again in the next cycle.

State Machine Descriptions The below sections describe every state machine used in the EtherCAT master. The textual descriptions of the state machines contain references to the transitions in the corresponding state transition diagrams, that are marked with an arrow followed by the name of the successive state. Transitions caused by trivial error cases (i. e. no response from slave) are not described explicitly. These transitions are drawn as dashed arrows in the diagrams.

5.3 The Master State Machine

The master state machine is executed in the context of the master thread. Figure 5.2 shows its transition diagram. Its purposes are: Bus monitoring The bus topology is monitored. If it changes, the bus is (re-)scanned. Slave conguration The application-layer states of the slaves are monitored. If a slave is not in the state it supposed to be, the slave is (re-)congured. Request handling Requests (either originating from the application or from external sources) are handled. A request is a job that the master shall process asynchronously, for example an SII access, SDO access, or similar.

5.4 The Slave Scan State Machine

The slave scan state machine, which can be seen in gure 5.3, leads through the process of reading desired slave information. The scan process includes the following steps: Node Address The node address is set for the slave, so that it can be node-addressed for all following operations. AL State The initial application-layer state is read. Base Information Base information (like the number of supported FMMUs) is read from the lower physical memory. Data Link Information about the physical ports is read. SII Size The size of the SII contents is determined to allocate SII image memory. SII Data The SII contents are read into the masters image.

6129a5f715fb, 2010/04/30

33

5 State Machines

start

broadcast

clear_addresses

read_state

dc_measure_delays

acknowledge

scan_slave

configure_slave

sdo_dictionary

sdo_request

write_sii

reg_request

Figure 5.2: Transition diagram of the master state machine

34

6129a5f715fb, 2010/04/30

5.4 The Slave Scan State Machine

start

address

state

base

dc_cap

DC not supported

datalink

sii_size

sii_data

Not in PREOP preop No category data sync

pdos

end

Figure 5.3: Transition diagram of the slave scan state machine

6129a5f715fb, 2010/04/30

35

5 State Machines PREOP If the slave supports CoE, it is set to PREOP state using the State change FSM (see sec. 5.6) to enable mailbox communication and read the PDO conguration via CoE. PDOs The PDOs are read via CoE (if supported) using the PDO Reading FSM (see sec. 5.8). If this is successful, the PDO information from the SII (if any) is overwritten.

5.5 The Slave Conguration State Machine

The slave conguration state machine, which can be seen in gure 5.4, leads through the process of conguring a slave and bringing it to a certain application-layer state. INIT The state change FSM is used to bring the slave to the INIT state. FMMU Clearing To avoid that the slave reacts on any process data, the FMMU conguration are cleared. If the slave does not support FMMUs, this state is skipped. If INIT is the requested state, the state machine is nished. Mailbox Sync Manager Conguration If the slaves support mailbox communication, the mailbox sync managers are congured. Otherwise this state is skipped. PREOP The state change FSM is used to bring the slave to PREOP state. If this is the requested state, the state machine is nished. SDO Conguration If there is a slave conguration attached (see sec. 3.1), and there are any SDO congurations are provided by the application, these are sent to the slave. PDO Conguration The PDO conguration state machine is executed to apply all necessary PDO congurations. PDO Sync Manager Conguration If any PDO sync managers exist, they are congured. FMMU Conguration If there are FMMUs congurations supplied by the application (i. e. if the application registered PDO entries), they are applied. SAFEOP The state change FSM is used to bring the slave to SAFEOP state. If this is the requested state, the state machine is nished. OP The state change FSM is used to bring the slave to OP state. If this is the requested state, the state machine is nished.

5.6 The State Change State Machine

The state change state machine, which can be seen in gure 5.5, leads through the process of changing a slaves application-layer state. This implements the states and transitions described in [3, sec. 6.4.1].

36

6129a5f715fb, 2010/04/30

5.6 The State Change State Machine

start

init

clear_fmmus

No FMMUs

clear_sync

No SMs

dc_clear_assign

dc_read_offset

No DC support

dc_write_offset

mbox_sync

No mailboxes

Config detached

boot_preop

sdo_conf

No SDOs configured

No config attached

pdo_conf

pdo_sync

No PDO SMs

INIT requested

PREOP or BOOT requested

No FMMUs configured

fmmu

dc_cycle

No config attached

dc_start

DC not configured

dc_assign

safeop

op

SAFEOP requested

end

Figure 5.4: Transition diagram of the slave conguration state machine

6129a5f715fb, 2010/04/30

37

5 State Machines

start

check

status Refuse code Response timeout Change timeout ack start_ack

Ack only

Success

check_ack Ack only error end

Figure 5.5: Transition Diagram of the State Change State Machine

38

6129a5f715fb, 2010/04/30

5.7 The SII State Machine Start The new application-layer state is requested via the AL Control Request register (see [3, sec. 5.3.1]). 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. Check AL Status If the AL State change datagram was acknowledged, the AL Control Response register (see [3, sec. 5.3.2]) must be read out until the slave changes the AL state. AL Status Code If the slave refused the state change command, the reason can be read from the AL Status Code eld in the AL State Changed registers (see [3, sec. 5.3.3]). 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. Check Acknowledge After sending the acknowledge command, it has to read out the AL Control Response register again. The start ack state is a shortcut in the state machine for the case, that the master wants to acknowledge a spontaneous AL state change, that was not requested.

5.7 The SII State Machine

The SII state machine (shown in gure 5.6) implements the process of reading or writing SII data via the Slave Information Interface described in [2, sec. 6.4].
start_reading start_writing

read_check

write_check

read_fetch

write_check2

error

end

Figure 5.6: Transition Diagram of the SII State Machine This is how the reading part of the state machine works: Start Reading The read request and the requested word address are written to the SII attribute.

6129a5f715fb, 2010/04/30

39

5 State Machines Check Read Command If the SII read request command has been acknowledged, a timer is started. A datagram is issued, that reads out the SII attribute for state and data. Fetch Data If the read operation is still busy (the SII is usually implemented as an E2 PROM), the state is read again. Otherwise the data are copied from the datagram. The writing part works nearly similar: Start Writing A write request, the target address and the data word are written to the SII attribute. Check Write Command If the SII write request command has been acknowledged, a timer is started. A datagram is issued, that reads out the SII attribute for the state of the write operation. Wait while Busy If the write operation is still busy (determined by a minimum wait time and the state of the busy ag), the state machine remains in this state to avoid that another write operation is issued too early.

5.8 The PDO State Machines

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 [3, sec. 5.6.7.4]. For the object access, the CANopen over EtherCAT access primitives are used (see sec. 6.2), so the slave must support the CoE mailbox protocol. PDO Reading FSM This state machine (g. 5.7) has the purpose to read the complete PDO conguration of a slave. It reads the PDO assignment for each Sync Manager and uses the PDO Entry Reading FSM (g. 5.8) to read the mapping for each assigned PDO. Basically it reads the every Sync managers PDO assignment SDOs (0x1C1x) number of elements to determine the number of assigned PDOs for this sync manager and then reads out the subindices of the SDO to get the assigned PDOs indices. When a PDO index is read, the PDO Entry Reading FSM is executed to read the PDOs mapped PDO entries. PDO Entry Reading FSM This state machine (g. 5.8) reads the PDO mapping (the PDO entries) of a PDO. It reads the respective mapping SDO (0x1600 0x17ff, or 0x1a00 0x1bff) for the given PDO by reading rst the subindex zero (number of elements) to determine the number of mapped PDO entries. After that, each subindex is read to get the mapped PDO entry index, subindex and bit size.

40

6129a5f715fb, 2010/04/30

5.8 The PDO State Machines

start First SM

pdo_count

end

No more PDOs

Next PDO pdo

pdo_entries

Figure 5.7: Transition Diagram of the PDO Reading State Machine

start

count

Next entry pdo_entry

No more entries end

Figure 5.8: Transition Diagram of the PDO Entry Reading State Machine

6129a5f715fb, 2010/04/30

41

5 State Machines

start First SM No config First PDO No more SMs end Unknown read_mapping

Assign ok No PDOs

No PDOs

Next PDO

mapping

zero_pdo_count First PDO

Next PDO assign_pdo No more PDOs set_pdo_count

Figure 5.9: Transition Diagram of the PDO Conguration State Machine

42

6129a5f715fb, 2010/04/30

5.8 The PDO State Machines

start

zero_entry_count Add first entry

Next entry No Entries map_entry No more Entries set_entry_count

end

Figure 5.10: Transition Diagram of the PDO Entry Conguration State Machine

6129a5f715fb, 2010/04/30

43

5 State Machines

44

6129a5f715fb, 2010/04/30

6 Mailbox Protocol Implementations

The EtherCAT master implements the CANopen over EtherCAT (CoE), Ethernet over EtherCAT (EoE), File-access over EtherCAT (FoE), Vendor-specic over EtherCAT (VoE) and Servo Prole over EtherCAT (SoE) mailbox protocols. See the below sections for details.

6.1 Ethernet over EtherCAT (EoE)

The EtherCAT master implements the Ethernet over EtherCAT mailbox protocol [3, sec. 5.7] to enable the tunneling of Ethernet frames to special slaves, that can either have physical Ethernet ports to forward the frames to, or have an own IP stack to receive the frames. Virtual Network Interfaces The master creates a virtual EoE network interface for every EoE-capable slave. These interfaces are called either eoeXsY for a slave without an alias address (see sec. 7.1.2), where X is the master index and Y is the slaves ring position, or eoeXaY for a slave with a non-zero alias address, where X is the master index and Y is the decimal alias address. Frames sent to these interfaces are forwarded to the associated slaves by the master. Frames, that are received by the slaves, are fetched by the master and forwarded to the virtual interfaces. This bears the following advantages: Flexibility: The user can decide, how the EoE-capable slaves are interconnected with the rest of the world. Standard tools can be used to monitor the EoE activity and to congure the EoE interfaces. The Linux kernels layer-2-bridging implementation (according to the IEEE 802.1D MAC Bridging standard) can be used natively to bridge Ethernet trac between EoE-capable slaves. The Linux kernels network stack can be used to route packets between EoEcapable slaves and to track security issues, just like having physical network interfaces.

6129a5f715fb, 2010/04/30

45

6 Mailbox Protocol Implementations EoE Handlers The virtual EoE interfaces and the related functionality is encapsulated in the ec_eoe_t class. An object of this class is called EoE handler. For example the master does not create the network interfaces directly: This is done inside the constructor of an EoE handler. An EoE handler additionally contains a frame queue. Each time, the kernel passes a new socket buer for sending via the interfaces hard_start_xmit() callback, the socket buer is queued for transmission by the EoE state machine (see below). If the queue gets lled up, the passing of new socket buers is suspended with a call to netif_stop_queue(). Creation of EoE Handlers During bus scanning (see sec. 5.4), the master determines the supported mailbox protocols foe each slave. This is done by examining the Supported Mailbox Protocols mask eld at word address 0x001C of the SII. If bit 1 is set, the slave supports the EoE protocol. In this case, an EoE handler is created for that slave. EoE State Machine Every EoE handler owns an EoE state machine, that is used to send frames to the corresponding slave and receive frames from the it via the EoE communication primitives. This state machine is showed in gure 6.1.

RX_START

RX_CHECK

RX_FETCH

TX_START

TX_SENT

Figure 6.1: Transition Diagram of the EoE State Machine RX START The beginning state of the EoE state machine. A mailbox check datagram is sent, to query the slaves mailbox for new frames. RX CHECK RX CHECK The mailbox check datagram is received. If the slaves mailbox did not contain data, a transmit cycle is started. TX START If there are new data in the mailbox, a datagram is sent to fetch the new data. RX FETCH RX FETCH The fetch datagram is received. If the mailbox data do not contain a EoE Fragment request command, the data are dropped and a transmit sequence is started. TX START If the received Ethernet frame fragment is the rst fragment, a new socket buer is allocated. In either case, the data are copied into the correct position of the socket buer.

46

6129a5f715fb, 2010/04/30

6.2 CANopen over EtherCAT (CoE) If the fragment is the last fragment, the socket buer is forwarded to the network stack and a transmit sequence is started. TX START Otherwise, a new receive sequence is started to fetch the next fragment. RX START TX START The beginning state of a transmit sequence. It is checked, if the transmission queue contains a frame to send. If not, a receive sequence is started. RX START If there is a frame to send, it is dequeued. If the queue was inactive before (because it was full), the queue is woken up with a call to netif wake queue(). The rst fragment of the frame is sent. TX SENT TX SENT It is checked, if the rst fragment was sent successfully. If the current frame consists of further fragments, the next one is sent. TX SENT If the last fragment was sent, a new receive sequence is started. RX START

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 sec. 5.3). 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 sec. 3.4.

Automatic Conguration By default, slaves are left in PREOP state, if no conguration is applied. If an EoE interface link is set to up, the requested slaves application-layer state is automatically set to OP.

6.2 CANopen over EtherCAT (CoE)

The CANopen over EtherCAT protocol [3, sec. 5.6] is used to congure slaves and exchange data objects on application level.

6129a5f715fb, 2010/04/30

47

6 Mailbox Protocol Implementations SDO Download State Machine The best time to apply SDO congurations is during the slaves PREOP state, because mailbox communication is already possible and slaves application will start with updating input data in the succeeding SAFEOP state. Therefore the SDO conguration has to be part of the slave conguration state machine (see sec. 5.5): It is implemented via an SDO download state machine, that is executed just before entering the slaves SAFEOP state. In this way, it is guaranteed that the SDO congurations are applied each time, the slave is recongured. The transition diagram of the SDO Download state machine can be seen in gure 6.2.

START

REQUEST

CHECK

RESPONSE

ERROR

END

Figure 6.2: Transition diagram of the CoE download state machine

START The beginning state of the CoE download state machine. The SDO Download Normal Request mailbox command is sent. REQUEST REQUEST It is checked, if the CoE download request has been received by the slave. After that, a mailbox check command is issued and a timer is started. CHECK CHECK If no mailbox data is available, the timer is checked. If it timed out, the SDO download is aborted. ERROR Otherwise, the mailbox is queried again. CHECK If the mailbox contains new data, the response is fetched. RESPONSE RESPONSE If the mailbox response could not be fetched, the data is invalid, the wrong protocol was received, or a Abort SDO Transfer Request was received, the SDO download is aborted. ERROR If a SDO Download Normal Response acknowledgement was received, the SDO download was successful. END END The SDO download was successful. ERROR The SDO download was aborted due to an error.

48

6129a5f715fb, 2010/04/30

6.3 Vendor specic over EtherCAT (VoE)

6.3 Vendor specic over EtherCAT (VoE)

The VoE protocol opens the possibility to implement a vendor-specic mailbox 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 conguration via the application interface (see chap. 3). These handlers contain the state machine necessary for the communication via VoE. For more information about using VoE handlers, see sec. 3.3 or the example applications provided in the examples/ subdirectory.

6.4 Servo Prole over EtherCAT (SoE)

The SoE protocol implements the Service Channel layer, specied in IEC 61800-7 [15] via EtherCAT mailboxes. The SoE protocol is quite similar to the CoE protocol (see sec. 6.2). Instead of SDO indices and subindices, so-called identication numbers (IDNs) identify parameters. The implementation covers the SCC Read and SCC Write primitives, each with the ability to fragment data. There are several ways to use the SoE implementation: Reading and writing IDNs via the command-line tool (see sec. 7.1.18). Storing congurations for arbitrary IDNs via the application interface (see chap. 3, i. e. ecrt_slave_config_idn()). These congurations are written to the slave during conguration in PREOP state, before going to SAFEOP. The user-space library (see sec. 7.2), oers functions to read/write IDNs in blocking mode (ecrt_master_read_idn(), ecrt_master_write_idn()).

6129a5f715fb, 2010/04/30

49

6 Mailbox Protocol Implementations

50

6129a5f715fb, 2010/04/30

7 Userspace Interfaces
For the master runs as a kernel module, accessing it is natively limited to analyzing Syslog messages and controlling using modutils. It was necessary to implement further interfaces, that make it easier to access the master from userspace and allow a ner inuence. 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. 7.1). 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. 7.2). Another aspect is automatic startup and conguration. The master must be able to automatically start up with a persistent conguration (see sec. 7.3). A last thing is monitoring EtherCAT communication. For debugging purposes, there had to be a way to analyze EtherCAT datagrams. The best way would be with a popular network analyzer, like Wireshark [7] (the former Ethereal) or others (see sec. 7.4). This chapter covers all these points and introduces the interfaces and tools to make all that possible.

7.1 Command-line Tool

7.1.1 Character Devices
Each master instance will get a character device as a userspace interface. The devices are named /dev/EtherCATx, where x {0 . . . n} is the index of the master.

Device Node Creation The character device nodes are automatically created, if the udev Package is installed. See sec. 9.5 for how to install and congure it.

6129a5f715fb, 2010/04/30

51

7 Userspace Interfaces

7.1.2 Setting Alias Addresses

ethercat alias [ OPTIONS ] < ALIAS > Write alias addresses . Arguments : ALIAS must be an unsigned 16 bit number . Zero means removing an alias address . If multiple slaves are selected , the -- force option is required . Command - specific options : -- alias -a < alias > -- position -p <pos > Slave selection . See the help of the slaves command . -- force -f Acknowledge writing aliases of multiple slaves . Numerical values can be specified either with decimal ( no prefix ) , octal ( prefix 0 ) or hexadecimal ( prefix 0x ) base .

7.1.3 Displaying the Bus Conguration

ethercat config [ OPTIONS ] Show slave configurations . Without the -- verbose option , slave configurations are output one - per - line . Example : 1001:0 0 x0000003b /0 x02010000 3 OP | | | | | | | \ - Application - layer | | | state of the attached | | | slave , or -, if no | | | slave is attached . | | \ - Absolute decimal ring | | position of the attached | | slave , or - if none | | attached . | \ - Expected vendor ID and product code ( both | hexadecimal ). \ - Alias address and relative position ( both decimal ). With the -- verbose option given , the configured PDOs and SDOs are output in addition . Configuration selection : Slave configurations can be selected with

52

6129a5f715fb, 2010/04/30

7.1 Command-line Tool

the -- alias and -- position parameters as follows : 1) If neither the -- alias nor the -- position option is given , all slave configurations are displayed . 2) If only the -- position option is given , an alias of zero is assumed ( see 4)). 3) If only the -- alias option is given , all slave configurations with the given alias address are displayed . 4) If both the -- alias and the -- position option are given , the selection can match a single configuration , that is displayed , if it exists . Command - specific options : -- alias -a < alias > Configuration alias ( see above ). -- position -p <pos > Relative position ( see above ). -- verbose -v Show detailed configurations . Numerical values can be specified either with decimal ( no prefix ) , octal ( prefix 0 ) or hexadecimal ( prefix 0x ) base .

7.1.4 Output PDO information in C Language

ethercat cstruct [ OPTIONS ] Generate slave PDO information in C language . The output C code can be used directly with the e c r t _ s l a v e _ c o n f i g _ p d o s () function of the application interface . Command - specific options : -- alias -a < alias > -- position -p <pos > Slave selection . See the help of the slaves command . Numerical values can be specified either with decimal ( no prefix ) , octal ( prefix 0 ) or hexadecimal ( prefix 0x ) base .

7.1.5 Displaying Process Data

ethercat data [ OPTIONS ] Output binary domain process data . Data of multiple domains are concatenated . Command - specific options : -- domain -d < index > Positive numerical domain index . If omitted , data of all domains are output .

6129a5f715fb, 2010/04/30

53

7 Userspace Interfaces

Numerical values can be specified either with decimal ( no prefix ) , octal ( prefix 0 ) or hexadecimal ( prefix 0x ) base .

7.1.6 Setting a Masters Debug Level

ethercat debug < LEVEL > Set the master s debug level . Debug messages are printed to syslog . Arguments : LEVEL can have one of the following values : 0 for no debugging output , 1 for some debug messages , or 2 for printing all frame contents ( use with caution !). Numerical values can be specified either with decimal ( no prefix ) , octal ( prefix 0 ) or hexadecimal ( prefix 0x ) base .

7.1.7 Congured Domains

ethercat domains [ OPTIONS ] Show configured domains . Without the -- verbose option , the domains are displayed one - per - line . Example : Domain0 : LogBaseAddr 0 x00000000 , Size 6 , WorkingCounter 0/1

The domain s base address for the logical datagram ( LRD / LWR / LRW ) is displayed followed by the domain s process data size in byte . The last values are the current datagram working counter sum and the expected working counter sum . If the values are equal , all PDOs were exchanged during the last cycle . If the -- verbose option is given , the participating slave configurations / FMMUs and the current process data are additionally displayed : Domain1 : LogBaseAddr 0 x00000006 , Size 6 , WorkingCounter 0/1 SlaveConfig 1001:0 , SM3 ( Input ) , LogAddr 0 x00000006 , Size 6 0 x00 0 x00 0 x00 0 x00 0 x00 0 x00 The process data are displayed as hexadecimal bytes . Command - specific options : -- domain -d < index > Positive numerical domain index .

54

6129a5f715fb, 2010/04/30

7.1 Command-line Tool

If ommitted , all domains are displayed . -- verbose -v Show FMMUs and process data in addition .

Numerical values can be specified either with decimal ( no prefix ) , octal ( prefix 0 ) or hexadecimal ( prefix 0x ) base .

7.1.8 SDO Access

ethercat download [ OPTIONS ] < INDEX > < SUBINDEX > < VALUE > Write an SDO entry to a slave . This command requires a single slave to be selected . The data type of the SDO entry is taken from the SDO dictionary by default . It can be overridden with the -- type option . If the slave does not support the SDO information service or the SDO is not in the dictionary , the -- type option is mandatory . These are valid data types to use with the -- type option : bool , int8 , int16 , int32 , int64 , uint8 , uint16 , uint32 , uint64 , float , double string , octet_string , unicode_string . For sign - and - magnitude coding , use the following types : sm8 , sm16 , sm32 , sm64 Arguments : INDEX is the SDO index and must be an unsigned 16 bit number . SUBINDEX is the SDO entry subindex and must be an unsigned 8 bit number . VALUE is the value to download and must correspond to the SDO entry datatype ( see above ). Command - specific options : -- alias -a < alias > -- position -p <pos > Slave selection . See the help of the slaves command . -- type -t < type > SDO entry data type ( see above ). Numerical values can be specified either with decimal ( no prefix ) , octal ( prefix 0 ) or hexadecimal ( prefix 0x ) base . ethercat upload [ OPTIONS ] < INDEX > < SUBINDEX >

6129a5f715fb, 2010/04/30

55

7 Userspace Interfaces

Read an SDO entry from a slave . This command requires a single slave to be selected . The data type of the SDO entry is taken from the SDO dictionary by default . It can be overridden with the -- type option . If the slave does not support the SDO information service or the SDO is not in the dictionary , the -- type option is mandatory . These are valid data types to use with the -- type option : bool , int8 , int16 , int32 , int64 , uint8 , uint16 , uint32 , uint64 , float , double string , octet_string , unicode_string . For sign - and - magnitude coding , use the following types : sm8 , sm16 , sm32 , sm64 Arguments : INDEX is the SDO index and must be an unsigned 16 bit number . SUBINDEX is the SDO entry subindex and must be an unsigned 8 bit number . Command - specific options : -- alias -a < alias > -- position -p <pos > Slave selection . See the help of the slaves command . -- type -t < type > SDO entry data type ( see above ). Numerical values can be specified either with decimal ( no prefix ) , octal ( prefix 0 ) or hexadecimal ( prefix 0x ) base .

7.1.9 EoE Statistics

ethercat eoe Display Ethernet over EtherCAT statictics . The TxRate and RxRate are displayed in Byte / s .

7.1.10 File-Access over EtherCAT

ethercat foe_read [ OPTIONS ] < SOURCEFILE > Read a file from a slave via FoE . This command requires a single slave to be selected .

56

6129a5f715fb, 2010/04/30

7.1 Command-line Tool

Arguments : SOURCEFILE is the name of the source file on the slave . Command - specific options : -- output - file -o < file >

Local target filename . If - ( default ) , data are printed to stdout . Slave selection . See the help of the slaves command .

-- alias -- position

-a < alias > -p <pos >

Numerical values can be specified either with decimal ( no prefix ) , octal ( prefix 0 ) or hexadecimal ( prefix 0x ) base . ethercat foe_write [ OPTIONS ] < FILENAME > Store a file on a slave via FoE . This command requires a single slave to be selected . Arguments : FILENAME can either be a path to a file , or - . In the latter case , data are read from stdin and the -- output - file option has to be specified . Command - specific options : -- output - file -o < file >

Target filename on the slave . If the FILENAME argument is -, this is mandatory . Otherwise , the basename () of FILENAME is used by default . Slave selection . See the help of the slaves command .

-- alias -- position

-a < alias > -p <pos >

Numerical values can be specified either with decimal ( no prefix ) , octal ( prefix 0 ) or hexadecimal ( prefix 0x ) base .

7.1.11 Creating Topology Graphs

ethercat graph [ OPTIONS ] Output the bus topology as a graph . The bus is output in DOT language ( see http :// www . graphviz . org / doc / info / lang . html ) , which can be processed with the tools from the Graphviz package . Example : ethercat graph | dot - Tsvg > bus . svg

6129a5f715fb, 2010/04/30

57

7 Userspace Interfaces

See man dot for more information .

7.1.12 Master and Ethernet Devices

ethercat master [ OPTIONS ] Show master and Ethernet device information . Command - specific options : -- master -m < indices > Master indices . A comma - separated list with ranges is supported . Example : 1 ,4 ,5 ,7 -9. Default : - ( all ). Numerical values can be specified either with decimal ( no prefix ) , octal ( prefix 0 ) or hexadecimal ( prefix 0x ) base .

7.1.13 Sync Managers, PDOs and PDO Entries

ethercat pdos [ OPTIONS ] List Sync managers , PDO assignment and mapping . The information is displayed in three layers , which are indented accordingly : 1) Sync managers - Contains the sync manager information from the SII : Index , physical start address , default size , control register and enable word . Example : SM3 : PhysAddr 0 x1100 , DefaultSize 0 , ControlRegister 0 x20 , Enable 1 2) Assigned PDOs - PDO direction , hexadecimal index and the PDO name , if avaliable . Note that a Tx and Rx are seen from the slave s point of view . Example : TxPDO 0 x1a00 " Channel1 " 3) Mapped PDO entries - PDO entry index and subindex ( both hexadecimal ) , the length in bit and the description , if available . Example : PDO entry 0 x3101 :01 , 8 bit , " Status " Note , that the displayed PDO assignment and PDO mapping information can either originate from the SII or from the CoE communication area . Command - specific options : -- alias -a < alias > -- position -p <pos > Slave selection . See the help of

58

6129a5f715fb, 2010/04/30

7.1 Command-line Tool

the slaves command . Numerical values can be specified either with decimal ( no prefix ) , octal ( prefix 0 ) or hexadecimal ( prefix 0x ) base .

7.1.14 Register Access

ethercat reg_read [ OPTIONS ] < OFFSET > [ LENGTH ] Output a slave s register contents . This command requires a single slave to be selected . Arguments : OFFSET is the register address . Must be an unsigned 16 bit number . LENGTH is the number of bytes to read and must also be an unsigned 16 bit number . OFFSET plus LENGTH may not exceed 64 k . The length is ignored ( and can be omitted ) , if a selected data type implies a length . These are valid data types to use with the -- type option : bool , int8 , int16 , int32 , int64 , uint8 , uint16 , uint32 , uint64 , float , double string , octet_string , unicode_string . For sign - and - magnitude coding , use the following types : sm8 , sm16 , sm32 , sm64 Command - specific options : -- alias -a < alias > -- position -p <pos > Slave selection . See the help of the slaves command . -- type -t < type > Data type ( see above ). Numerical values can be specified either with decimal ( no prefix ) , octal ( prefix 0 ) or hexadecimal ( prefix 0x ) base . ethercat reg_write [ OPTIONS ] < OFFSET > < DATA > Write data to a slave s registers . This command requires a single slave to be selected . Arguments : OFFSET is the register address to write to . DATA depends on whether a datatype was specified with the -- type option : If not , DATA must be

6129a5f715fb, 2010/04/30

59

7 Userspace Interfaces
either a path to a file with data to write , or -, which means , that data are read from stdin . If a datatype was specified , VALUE is interpreted respective to the given type . These are valid data types to use with the -- type option : bool , int8 , int16 , int32 , int64 , uint8 , uint16 , uint32 , uint64 , float , double string , octet_string , unicode_string . For sign - and - magnitude coding , use the following types : sm8 , sm16 , sm32 , sm64 Command - specific options : -- alias -a < alias > -- position -p <pos > Slave selection . See the help of the slaves command . -- type -t < type > Data type ( see above ). Numerical values can be specified either with decimal ( no prefix ) , octal ( prefix 0 ) or hexadecimal ( prefix 0x ) base .

7.1.15 SDO Dictionary

ethercat sdos [ OPTIONS ] List SDO dictionaries . SDO dictionary information is displayed in two layers , which are indented accordingly : 1) SDOs - Hexadecimal SDO index and the name . Example : SDO 0 x1018 , " Identity object " 2) SDO entries - SDO index and SDO entry subindex ( both hexadecimal ) followed by the access rights ( see below ) , the data type , the length in bit , and the description . Example : 0 x1018 :01 , rwrwrw , uint32 , 32 bit , " Vendor id " The access rights are specified for the AL states PREOP , SAFEOP and OP . An r means , that the entry is readable in the corresponding state , an w means writable , respectively . If a right is not granted , a dash - is shown . If the -- quiet option is given , only the SDOs are output .

60

6129a5f715fb, 2010/04/30

7.1 Command-line Tool

Command - specific options : -- alias -a < alias > -- position -p <pos > Slave selection . See the help of the slaves command . -- quiet -q Only output SDOs ( without the SDO entries ). Numerical values can be specified either with decimal ( no prefix ) , octal ( prefix 0 ) or hexadecimal ( prefix 0x ) base .

7.1.16 SII Access

It is possible to directly read or write the complete SII contents of the slaves. This was introduced for the reasons below: 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. Some SII data elds have to be altered (like the alias address). A quick writing must be possible for that. Through reading access, analyzing category data is possible from userspace.
ethercat sii_read [ OPTIONS ] Output a slave s SII contents . This command requires a single slave to be selected . Without the -- verbose option , binary SII contents are output . With the -- verbose option given , a textual representation of the data is output , that is separated by SII category names . Command - specific options : -- alias -a < alias > -- position -p <pos > Slave selection . See the help of the slaves command . -- verbose -v Output textual data with category names . Numerical values can be specified either with decimal ( no prefix ) , octal ( prefix 0 ) or hexadecimal ( prefix 0x ) base .

Reading out SII data is as easy as other commands. Though the data are in binary format, analysis is easier with a tool like hexdump:
$ ethercat sii read --position 3 | hexdump 0000000 0103 0000 0000 0000 0000 0000 0000 008 c

6129a5f715fb, 2010/04/30

61

7 Userspace Interfaces
0000010 0002 0000 3052 07 f0 0000 0000 0000 0000 0000020 0000 0000 0000 0000 0000 0000 0000 0000 ...

Backing up SII contents can easily done with a redirection:

$ ethercat sii read --position 3 > sii-of-slave3.bin

To download SII contents to a slave, writing access to the masters character device is necessary (see sec. 7.1.1).
ethercat sii_write [ OPTIONS ] < FILENAME > Write SII contents to a slave . This command requires a single slave to be selected . The file contents are checked for validity and integrity . These checks can be overridden with the -- force option . Arguments : FILENAME must be a path to a file that contains a positive number of words . If it is -, data are read from stdin . Command - specific options : -- alias -a < alias > -- position -p <pos > Slave selection . See the help of the slaves command . -- force -f Override validity checks . Numerical values can be specified either with decimal ( no prefix ) , octal ( prefix 0 ) or hexadecimal ( prefix 0x ) base .

# ethercat sii write --position 3 sii-of-slave3.bin

The SII contents will be checked for validity and then sent to the slave. The write operation may take a few seconds.

7.1.17 Slaves on the Bus

Slave information can be gathered with the subcommand slaves:
ethercat slaves [ OPTIONS ] Display slaves on the bus . If the -- verbose option is not given , the slaves are displayed one - per - line . Example :

62

6129a5f715fb, 2010/04/30

7.1 Command-line Tool

1 | | | | | | | | | | | | | | \5555:0 PREOP + EL3162 2 C . Ana . Input 0 -10 V | | | | | | | | | \ - Name from the SII if avaliable , | | | | otherwise vendor ID and product | | | | code ( both hexadecimal ). | | | \ - Error flag . + means no error , | | | E means that scan or | | | configuration failed . | | \ - Current application - layer state . | \ - Decimal relative position to the last | slave with an alias address set . \ - Decimal alias address of this slave ( if set ) , otherwise of the last slave with an alias set , or zero , if no alias was encountered up to this position . Absolute ring position in the bus .

If the -- verbose option is given , a detailed ( multi - line ) description is output for each slave . Slave selection : Slaves for this and other commands can be selected with the -- alias and -- position parameters as follows : 1) If neither the -- alias nor the -- position option is given , all slaves are selected . 2) If only the -- position option is given , it is interpreted as an absolute ring position and a slave with this position is matched . 3) If only the -- alias option is given , all slaves with the given alias address and subsequent slaves before a slave with a different alias address match ( use - p0 if only the slaves with the given alias are desired , see 4)). 4) If both the -- alias and the -- position option are given , the latter is interpreted as relative position behind any slave with the given alias . Command - specific options : -- alias -a < alias > Slave alias ( see above ). -- position -p <pos > Slave position ( see above ). -- verbose -v Show detailed slave information . Numerical values can be specified either with decimal ( no prefix ) , octal ( prefix 0 ) or hexadecimal ( prefix 0x ) base .

Below is a typical output:

$ ethercat slaves 0 0:0 PREOP 1 5555:0 PREOP 2 5555:1 PREOP + + + EK1100 Ethernet Kopplerklemme (2 A E - Bus ) EL3162 2 K . Ana . Eingang 0 -10 V EL4102 2 K . Ana . Ausgang 0 -10 V

6129a5f715fb, 2010/04/30

63

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

7.1.18 SoE IDN Access

ethercat soe_read [ OPTIONS ] <IDN > Read an SoE IDN from a slave . This command requires a single slave to be selected . Arguments : IDN is the IDN and must be either an unsigned 16 bit number acc . to IEC 61800 -7 -204: Bit 15: (0) Standard data , (1) Product data Bit 14 - 12: Parameter set (0 - 7) Bit 11 - 0: Data block number or a string like P -0 -150 . Data of the given IDN are read and displayed according to the given datatype , or as raw hex bytes . These are valid data types to use with the -- type option : bool , int8 , int16 , int32 , int64 , uint8 , uint16 , uint32 , uint64 , float , double string , octet_string , unicode_string . For sign - and - magnitude coding , use the following types : sm8 , sm16 , sm32 , sm64 Command - specific options : -- alias -a < alias > -- position -p <pos > Slave selection . See the help of the slaves command . -- type -t < type > Data type ( see above ). Numerical values can be specified either with decimal ( no prefix ) , octal ( prefix 0 ) or hexadecimal ( prefix 0x ) base . ethercat soe_write [ OPTIONS ] <IDN > < VALUE > Write an SoE IDN to a slave . This command requires a single slave to be selected . Arguments : IDN is the IDN and must be either an unsigned 16 bit number acc . to IEC 61800 -7 -204: Bit 15: (0) Standard data , (1) Product data

64

6129a5f715fb, 2010/04/30

7.1 Command-line Tool

Bit 14 - 12: Parameter set (0 - 7) Bit 11 - 0: Data block number or a string like P -0 -150 . is the value to write ( see below ).

VALUE

The VALUE argument is interpreted as the given data type ( - - type is mandatory ) and written to the selected slave . These are valid data types to use with the -- type option : bool , int8 , int16 , int32 , int64 , uint8 , uint16 , uint32 , uint64 , float , double string , octet_string , unicode_string . For sign - and - magnitude coding , use the following types : sm8 , sm16 , sm32 , sm64 Command - specific options : -- alias -a < alias > -- position -p <pos > Slave selection . See the help of the slaves command . -- type -t < type > Data type ( see above ). Numerical values can be specified either with decimal ( no prefix ) , octal ( prefix 0 ) or hexadecimal ( prefix 0x ) base .

7.1.19 Requesting Application-Layer States

ethercat states [ OPTIONS ] < STATE > Request application - layer states . Arguments : STATE can be INIT , PREOP , BOOT , SAFEOP , or OP . Command - specific options : -- alias -a < alias > -- position -p <pos > Slave selection . See the help of the slaves command . Numerical values can be specified either with decimal ( no prefix ) , octal ( prefix 0 ) or hexadecimal ( prefix 0x ) base .

7.1.20 Displaying the Master Version

ethercat version [ OPTIONS ] Show version information .

6129a5f715fb, 2010/04/30

65

7 Userspace Interfaces

7.1.21 Generating Slave Description XML

ethercat xml [ OPTIONS ] Generate slave information XML . Note that the PDO information can either originate from the SII or from the CoE communication area . For slaves , that support configuring PDO assignment and mapping , the output depends on the last configuration . Command - specific options : -- alias -a < alias > -- position -p <pos > Slave selection . See the help of the slaves command . Numerical values can be specified either with decimal ( no prefix ) , octal ( prefix 0 ) or hexadecimal ( prefix 0x ) base .

7.2 Userspace Library

The native application interface (see chap. 3) 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 [5]. The library is named libethercat. Its sources reside in the lib/ subdirectory and are build by default when using make. It is installed in the lib/ path below the installation prex as libethercat.a (for static linking), libethercat.la (for the use with libtool ) and libethercat.so (for dynamic linking).

7.2.1 Using the Library

The application interface header ecrt.h can be used both in kernel and in user context. The following minimal example shows how to build a program with EtherCAT functionality. An entire example can be found in the examples/user/ path of the master sources.

#include < ecrt .h > int main ( void )

{ ec_master_t * master = ec r t _r e q ue s t _m a s te r (0);

if (! master ) return 1; // error

66

6129a5f715fb, 2010/04/30

7.2 Userspace Library

pause (); // wait for signal

return 0;
}

The program can be compiled and dynamically linked to the library with the below command:
gcc ethercat . c -o ectest -I / opt / etherlab / include \ -L / opt / etherlab / lib - lethercat \ -Wl , - - rpath -Wl ,/ opt / etherlab / lib

The library can also be linked statically to the program:

gcc - static ectest . c -o ectest -I / opt / etherlab / include \ / opt / etherlab / lib / libethercat . a

7.2.2 Implementation
Basically the kernel API was transferred into userspace via the master character device (see chap. 2, g. 2.1 and sec. 7.1.1). The function calls of the kernel API are mapped to the userspace via an ioctl() interface. The userspace API functions share a set of generic ioctl() calls. The kernel part of the interface calls the according API functions directly, what results in a minimum additional delay (see sec. 7.2.3). For performance reasons, the actual domain process data (see sec. 2.3) are not copied between kernel and user memory on every access: Instead, the data are memorymapped to the userspace application. Once the master is congured and activated, the master module creates one process data memory area spanning all domains and maps it to userspace, so that the application can directly access the process data. As a result, there is no additional delay when accessing process data from userspace. Kernel/User API Dierences Because of the memory-mapping of the process data, the memory is managed internally by the library functions. As a result, it is not possible to provide external memory for domains, like in the kernel API. The corresponding functions are only available in kernelspace. This is the only dierence when using the application interface in userspace.

7.2.3 Timing
An interesting aspect is the timing of the userspace library calls compared to those of the kernel API. Table 7.1 shows the call times and standard deviancies of typical (and time-critical) API functions measured on an Intel Pentium 4 M CPU with 2.2 GHz and a standard 2.6.26 kernel.

6129a5f715fb, 2010/04/30

67

7 Userspace Interfaces

Table 7.1: Application Interface Timing Comparison Kernelspace (t) (t) Function ecrt_master_receive() 1.1 s 0.3 s ecrt_domain_process() < 0.1 s < 0.1 s ecrt_domain_queue() < 0.1 s < 0.1 s 1.8 s 0.2 s ecrt_master_send() Userspace (t) (t) 2.2 s 0.5 s 1.0 s 0.2 s 1.0 s 0.1 s 2.5 s 0.5 s

The test results show, that for this conguration, the userspace API causes about 1 s additional delay for each function, compared to the kernel API.

7.3 System Integration

To integrate the EtherCAT master as a service into a running system, it comes with an init script and a syscong le, that are described below.

7.3.1 Init Script

The EtherCAT master init script conforms to the requirements of the Linux Standard Base (LSB, [6]). The script is installed to etc/init.d/ethercat below the installation prex and has to be copied (or better: linked) to the appropriate location (see sec. 9), before the master can be inserted as a service. Please note, that the init script depends on the syscong le described below. To provide service dependencies (i. e. which services have to be started before others) inside the init script code, LSB denes a special comment block. System tools can extract this information to insert the EtherCAT init script at the correct place in the startup sequence:
# Required - Start : # Should - Start : # Required - Stop : # Should - Stop : # Default - Start : # Default - Stop : # Short - Description : # Description : ### END INIT INFO $local_fs $syslog $network $time ntp $local_fs $syslog $network $time ntp 3 5 0 1 2 6 EtherCAT master EtherCAT master devel

#------------------------------------------------------------------------

68

6129a5f715fb, 2010/04/30

7.3 System Integration

7.3.2 Syscong File

For persistent conguration, the init script uses a syscong le installed to etc/syscong/ethercat (below the installation prex), that is mandatory for the init script. The syscong le contains all conguration variables needed to operate one or more masters. The documentation is inside the le and included below:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47

# # Master devices . # # The MASTER <X > _DEVICE variable specifies the Ethernet device for a master # with index X . # # Specify the MAC address ( hexadecimal with colons ) of the Ethernet device to # use . Example : "00:00:08:44: ab :66" # # The broadcast address " ff : ff : ff : ff : ff : ff " has a special meaning : It tells # the master to accept the first device offered by any Ethernet driver . # # The MASTER <X > _DEVICE variables also determine , how many masters will be # created : A non - empty variable M ASTER0_D EVICE will create one master , adding # a non - empty variable MAS TER1_DEV ICE will create a second master , and so on . # MAST ER0_DEVI CE ="" # MA STER1_DE VICE ="" # # Ethernet driver modules to use for EtherCAT operation . # # Specify a non - empty list of Ethernet drivers , that shall be used for EtherCAT # operation . # # Except for the generic Ethernet driver module , the init script will try to # unload the usual Ethernet driver modules in the list and replace them with # the EtherCAT - capable ones . If a certain ( EtherCAT - capable ) driver is not # found , a warning will appear . # # Possible values : 8139 too , e100 , e1000 , r8169 , generic . # Separate multiple drivers with spaces . # # Note : The e100 , e1000 , r8169 and generic drivers are not built by default . # Enable them with the -- enable - < driver > configure switches . # DEVI CE_MODUL ES ="" # # Flags for loading kernel modules . # # This can usually be left empty . Adjust this variable , if you have problems # with module loading . # # MO DPROBE_F LAGS =" - b " #------------------------------------------------------------------------------

7.3.3 Starting the Master as a Service

After the init script and the syscong le are placed into the right location, the EtherCAT master can be inserted as a service. The dierent Linux distributions oer

6129a5f715fb, 2010/04/30

69

7 Userspace Interfaces dierent ways to mark a service for starting and stopping in certain runlevels. For example, SUSE Linux provides the insserv command:
# insserv ethercat

The init script can also be used for manually starting and stopping the EtherCAT master. It has to be executed with one of the parameters start, stop, restart or status.
# /etc/init.d/ethercat restart Shutting down EtherCAT master Starting EtherCAT master done done

7.4 Debug Interfaces

EtherCAT buses can always be monitored by inserting a switch between master and slaves. This allows to connect another PC with a network monitor like Wireshark [7], for example. It is also possible to listen to local network interfaces on the machine running the EtherCAT master directly. If the generic Ethernet driver (see sec. 4.3) is used, the network monitor can directly listen on the network interface connected to the EtherCAT bus. When using native Ethernet drivers (see sec. 4.2), there are no local network interfaces to listen to, because the Ethernet devices used for EtherCAT are not registered at the network stack. For that case, so-called debug interfaces are supported, which are virtual network interfaces allowing to capture EtherCAT trac with a network monitor (like Wireshark or tcpdump) running on the master machine without using external hardware. To use this functionality, the master sources have to be congured with the --enable-debug-if switch (see sec. 9). Every EtherCAT master registers a read-only network interface per attached physical Ethernet device. The network interfaces are named ecdbgmX for the main device, and ecdbgbX for the backup device (for future use), where X is the master index. The below listing shows a debug interface among some standard network interfaces:
# ip link 1: lo : < LOOPBACK , UP > mtu 16436 qdisc noqueue link / loopback 00 :00:00 :00:00 :00 brd 00 :00:00 :00:00 :00 4: eth0 : < BROADCAST , MULTICAST > mtu 1500 qdisc noop qlen 1000 link / ether 00:13:46:3 b : ad : d7 brd ff : ff : ff : ff : ff : ff 8: ecdbgm0 : < BROADCAST , MULTICAST > mtu 1500 qdisc pfifo_fast qlen 1000 link / ether 00:04:61:03: d1 :01 brd ff : ff : ff : ff : ff : ff

While a debug interface is enabled, all frames sent or received to or from the physical device are additionally forwarded to the debug interface by the corresponding master. Network interfaces can be enabled with the below command:

70

6129a5f715fb, 2010/04/30

7.4 Debug Interfaces

# ip link set dev ecdbgm0 up

Please note, that the frame rate can be very high. With an application connected, the debug interface can produce thousands of frames per second. Attention The socket buers needed for the operation of debug interfaces have to be allocated dynamically. Some Linux realtime extensions (like RTAI) do not allow this in realtime context!

6129a5f715fb, 2010/04/30

71

7 Userspace Interfaces

72

6129a5f715fb, 2010/04/30

8 Timing Aspects
Although EtherCATs timing is highly deterministic and therefore timing issues are rare, there are a few aspects that can (and should be) dealt with.

8.0.1 Application Interface Proling

One of the most important timing aspects are the execution times of the application interface functions, that are called in cyclic context. These functions make up an important part of the overall timing of the application. To measure the timing of the functions, the following code was used:
c0 = get_cycles (); ecrt_maste r_ r e ce i v e ( master ); c1 = get_cycles (); ecrt_domai n_ p r oc e s s ( domain1 ); c2 = get_cycles (); ecrt_master_run ( master ); c3 = get_cycles (); ecrt_master_send ( master ); c4 = get_cycles ();

Between each call of an interface function, the CPU timestamp counter is read. The counter dierences are converted to s with help of the cpu_khz variable, that contains the number of increments per ms. For the actual measuring, a system with a 2.0 GHz CPU was used, that ran the above code in an RTAI thread with a period of 100 s. The measuring was repeated n = 100 times and the results were averaged. These can be seen in table 8.1. Table 8.1: Proling of an Application Cycle on a 2.0 GHz Processor Element ecrt master receive() ecrt domain process() ecrt master run() ecrt master send() Complete Cycle Mean Duration [s] Standard Deviancy [s] 8.04 0.48 0.14 0.03 0.29 0.12 2.18 0.17 10.65 0.69

6129a5f715fb, 2010/04/30

73

8 Timing Aspects It is obvious, that the functions accessing hardware make up the lions share. The ec master receive() executes the ISR of the Ethernet device, analyzes datagrams and copies their contents into the memory of the datagram objects. The ec master send() assembles a frame out of dierent datagrams and copies it to the hardware buers. Interestingly, this makes up only a quarter of the receiving time. The functions that only operate on the masters internal data structures are very fast (t < 1 s). Interestingly the runtime of ec domain process() has a small standard deviancy relative to the mean value, while this ratio is about twice as big for ec master run(): This probably results from the latter function having to execute code depending on the current state and the dierent state functions are more or less complex. For a realtime cycle makes up about 10 s, the theoretical frequency can be up to 100 kHz. For two reasons, this frequency keeps being theoretical: 1. The processor must still be able to run the operating system between the realtime cycles. 2. The EtherCAT frame must be sent and received, before the next realtime cycle begins. The determination of the bus cycle time is dicult and covered in sec. 8.0.2.

8.0.2 Bus Cycle Measuring

For measuring the time, a frame is on the wire, two timestamps must be taken: 1. The time, the Ethernet hardware begins with physically sending the frame. 2. The time, the frame is completely received by the Ethernet hardware. Both times are dicult to determine. The rst reason is, that the interrupts are disabled and the master is not notied, when a frame is sent or received (polling would distort the results). The second reason is, that even with interrupts enabled, the time from the event to the notication is unknown. Therefore the only way to condently determine the bus cycle time is an electrical measuring. Anyway, the bus cycle time is an important factor when designing realtime code, because it limits the maximum frequency for the cyclic task of the application. In practice, these timing parameters are highly dependent on the hardware and often a trial and error method must be used to determine the limits of the system. The central question is: What happens, if the cycle frequency is too high? The answer is, that the EtherCAT frames that have been sent at the end of the cycle are not yet received, when the next cycle starts. First this is noticed by ecrt domain process(), because the working counter of the process data datagrams were not increased. The function will notify the user via Syslog1 . In this case, the process data keeps being the
1

To limit Syslog output, a mechanism has been implemented, that outputs a summarized notication at maximum once a second.

74

6129a5f715fb, 2010/04/30

same as in the last cycle, because it is not erased by the domain. When the domain datagrams are queued again, the master notices, that they are already queued (and marked as sent). The master will mark them as unsent again and output a warning, that datagrams were skipped. On the mentioned 2.0 GHz system, the possible cycle frequency can be up to 25 kHz without skipped frames. This value can surely be increased by choosing faster hardware. Especially the RealTek network hardware could be replaced by a faster one. Besides, implementing a dedicated ISR for EtherCAT devices would also contribute to increasing the latency. These are two points on the authors to-do list.

6129a5f715fb, 2010/04/30

75

8 Timing Aspects

76

6129a5f715fb, 2010/04/30

9 Installation
9.1 Getting the Software
There are several ways to get the master software: 1. An ocial release (for example 1.5.0), can be downloaded from the masters website1 at the EtherLab project [1] as a tarball. 2. The most recent development revision (and moreover any other revision) can be obtained via the Mercurial [13] repository on the masters project page on SourceForge.net2 . The whole repository can be cloned with the command
hg clone http :// etherlabmaster . hg . sourceforge . net / hgweb / etherlabmaster / etherlabmaster local-dir

3. Without a local Mercurial installation, tarballs of arbitrary revisions can be downloaded via the bz2 links in the browsable repository pages3 .

9.2 Building the Software

After downloading a tarball or cloning the repository as described in sec. 9.1, the sources have to be prepared and congured for the build process. When a tarball was downloaded, it has to be extracted with the following commands:
$ tar xjf ethercat-1.5.0.tar.bz2 $ cd ethercat-1.5.0/

The software conguration is managed with Autoconf [14] so the released versions contain a configure shell script, that has to be executed for conguration (see below). Bootstrap When downloading or cloning directly from the repository, the configure script does not yet exist. It can be created via the bootstrap.sh script in the master sources. The autoconf and automake packages are required for this.
1 2

http://etherlab.org/en/ethercat/index.php http://sourceforge.net/projects/etherlabmaster 3 http://etherlabmaster.hg.sourceforge.net/hgweb/etherlabmaster/etherlabmaster

6129a5f715fb, 2010/04/30

77

9 Installation Conguration and Build The conguration and the build process follow the below commands:
$ ./configure $ make $ make modules

Table 9.1 lists important conguration switches and options.

9.3 Building the Interface Documentation

The source code is documented using Doxygen [12]. To build the HTML documentation, the Doxygen software has to be installed. The below command will generate the documents in the subdirectory doxygen-output:
$ make doc

The interface documentation can be viewed by pointing a browser to the le doxygenoutput/html/index.html. The functions and data structures of the application interface a covered by an own module Application Interface.

9.4 Installing the Software

The below commands have to be entered as root: The rst one will install the EtherCAT header, init script, syscong le and the userspace tool to the prex path. The second one will install the kernel modules to the kernels modules directory. The nal depmod call is necessary to include the kernel modules into the modules.dep le to make it available to the modprobe command, used in the init script.
# make install # make modules install # depmod

If the target kernels modules directory is not under /lib/modules, a dierent destination directory can be specied with the DESTDIR make variable. For example:
# make DESTDIR=/vol/nfs/root modules install

This command will install the compiled kernel modules to /vol/nfs/root/lib/modules, prepended by the kernel release. If the EtherCAT master shall be run as a service4 (see sec. 7.3), the init script and the syscong le have to be copied (or linked) to the appropriate locations. The below example is suitable for SUSE Linux. It may vary for other distributions.
4

Even if the EtherCAT master shall not be loaded on system startup, the use of the init script is recommended for manual (un-)loading.

78

6129a5f715fb, 2010/04/30

9.4 Installing the Software

Table 9.1: Conguration options Description --prefix Installation prex --with-linux-dir Linux kernel sources RTAI path (only for --with-rtai-dir RTAI example) --enable-tool Build the command-line tool ethercat (see sec. 7.1). --enable-userlib Build the userspace library. --enable-eoe Enable EoE support Use CPU timestamp --enable-cycles counter. Enable this on Intel architecture to get ner timing calculation. --enable-debug-if Create a debug interface for each master Create a debug ring to --enable-debug-ring record frames --enable-8139too Build the 8139too driver --with-8139too-kernel 8139too kernel --enable-e100 Build the e100 driver --with-e100-kernel e100 kernel --enable-e1000 Enable e1000 driver e1000 kernel --with-e1000-kernel --enable-r8169 Enable r8169 driver r8169 kernel --with-r8169-kernel --enable-generic Build the generic Ethernet driver (see sec. 4.3). Option/Switch Default /opt/etherlab Use running kernel

yes

yes yes no

no no yes no no no no

If this option is not specied, the kernel version to use is extracted from the Linux kernel sources.

6129a5f715fb, 2010/04/30

79

9 Installation
# # # #

cd /opt/etherlab cp etc/sysconfig/ethercat /etc/sysconfig/ ln -s etc/init.d/ethercat /etc/init.d/ insserv ethercat

Now the syscong le /etc/sysconfig/ethercat (see sec. 7.3.2) has to be customized. The minimal customization is to set the MASTER0_DEVICE variable to the MAC address of the Ethernet device to use (or ff:ff:ff:ff:ff:ff to use the rst device oered) and selecting the driver(s) to load via the DEVICE_MODULES variable. After the basic conguration is done, the master can be started with the below command:
# /etc/init.d/ethercat start

At this time, the operation of the master can be observed by viewing the Syslog messages, which should look like the ones below. If EtherCAT slaves are connected to the masters EtherCAT device, the activity indicators should begin to ash.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18

EtherCAT : Master driver 1.5.0 EtherCAT : 1 master waiting for devices . EtherCAT Intel ( R ) PRO /1000 Network Driver - version 6.0.60 - k2 Copyright ( c ) 1999 -2005 Intel Corporation . PCI : Found IRQ 12 for device 0000:01:01.0 PCI : Sharing IRQ 12 with 0000:00:1 d .2 PCI : Sharing IRQ 12 with 0000:00:1 f .1 EtherCAT : Accepting device 00:0 E :0 C : DA : A2 :20 for master 0. EtherCAT : Starting master thread . ec_e1000 : ec0 : e1000_probe : Intel ( R ) PRO /1000 Network Connection ec_e1000 : ec0 : e 1 0 00 _ w at c h do g _ ta s k : NIC Link is Up 100 Mbps Full Duplex EtherCAT : Link state changed to UP . EtherCAT : 7 slave ( s ) responding . EtherCAT : Slave states : PREOP . EtherCAT : Scanning bus . EtherCAT : Bus scanning completed in 431 ms .

The master module is loading, and one master is initialized.

The EtherCAT-capable e1000 driver is loading. The master accepts the device with the address 00:0E:0C:DA:A2:20.
8 16

The master goes to idle phase, starts its state machine and begins scanning the bus.

80

6129a5f715fb, 2010/04/30

9.5 Automatic Device Node Creation

9.5 Automatic Device Node Creation

The ethercat command-line tool (see sec. 7.1) 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 udev package is not installed by default. The device nodes will be created with mode 0660 and group root by default. If normal users shall have reading access, a udev rule le (for example /etc/udev/rules.d/99EtherCAT.rules) has to be created with the following contents:
KERNEL ==" EtherCAT [0 -9]*" , MODE ="0664"

After the udev rule le is created and the EtherCAT master is restarted with /etc /init.d/ethercat restart, the device node will be automatically created with the desired rights:
# ls -l /dev/EtherCAT0 crw - rw -r - - 1 root root 252 , 0 2008 -09 -03 16:19 / dev / EtherCAT0

Now, the ethercat tool can be used (see sec. 7.1) even as a non-root user. If non-root users shall have writing access, the following udev rule can be used instead:
KERNEL ==" EtherCAT [0 -9]*" , MODE ="0664" , GROUP =" users "

6129a5f715fb, 2010/04/30

81

9 Installation

82

6129a5f715fb, 2010/04/30

Bibliography
[1] Ingenieurgemeinschaft IgH: EtherLab Open Source Toolkit for rapid realtime code generation under Linux with Simulink/RTW and EtherCAT technology. http://etherlab.org/en, 2008. [2] IEC 61158-4-12: Data-link Protocol Specication. International Electrotechnical Commission (IEC), 2005. [3] IEC 61158-6-12: Application Layer Protocol Specication. International Electrotechnical Commission (IEC), 2005. [4] GNU General Public License, Version 2. http://www.gnu.org/licenses/ gpl-2.0.html. October 15, 2008. [5] GNU Lesser General Public License, Version 2.1. http://www.gnu.org/ licenses/old-licenses/lgpl-2.1.html. October 15, 2008. [6] Linux Standard Base. http://www.linuxfoundation.org/en/LSB. August 9, 2006. [7] Wireshark. http://www.wireshark.org. 2008. [8] Hopcroft, J. E. / Ullman, J. D.: Introduction to Automata Theory, Languages and Computation. Adison-Wesley, Reading, Mass. 1979. [9] Wagner, F. / Wolstenholme, P.: State machine misunderstandings. In: IEE journal Computing and Control Engineering, 2004. [10] RTAI. The RealTime Application Interface for Linux from DIAPM. https:// www.rtai.org, 2010. [11] RT PREEMPT HOWTO. PREEMPT_HOWTO, 2010. http://rt.wiki.kernel.org/index.php/RT_

[12] Doxygen. Source code documentation generator tool. http://www.stack.nl/ ~dimitri/doxygen, 2008. [13] Mercurial SCM. http://mercurial.selenic.com, 2010. [14] Autoconf GNU Project Free Software Foundation (FSF). http://www.gnu. org/software/autoconf, 2010. [15] IEC 61800-7-304: Adjustable speed electrical power drive systems - Part 7-300: Generic interface and use of proles for power drive systems - Mapping of proles to network technologies. International Electrotechnical Commission (IEC), 2007.

6129a5f715fb, 2010/04/30

83