bkinnightskytw
/
ethercat
mirror of https://gitlab.com/bkinnightskytw/ethercat.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Cherry-picked markdown conversions from stable-1.5.

This commit is contained in:
Florian Pose 2023-01-30 11:19:08 +01:00
parent b403327659
commit fb59955145
5 changed files with 165 additions and 109 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

49
CodingStyle.txt → CodingStyle.md
View File

@ -1,5 +1,3 @@
$Id$
vim: spelllang=en tw=78
This is a short introduction to the coding style that shall be used. The below
@ -7,11 +5,11 @@ rules are applicable for all C source files, except the Ethernet drivers, for
which the Linux Kernel coding style shall be used to minimize the
differences).
1) Line length
# Line length
- Lines shall not exceed 78 characters.
2) Whitespace
# Whitespace
- Indentation shall be done using 4 space characters
@ -20,36 +18,39 @@ differences).
- After commas, colons and semicolons, a single space shall be
placed (if not followed by a line break).
- Binary operators (=, ==, ~=, |, ||, etc.) shall be enclosed by 2 spaces
(except . and ->).
- Binary operators (`=`, `==`, `~=`, `|`, `||`, etc.) shall be enclosed by 2 spaces
(except `.` and `->`).
3) Placing braces
# Placing braces
- Braces shall be placed in the following way (K&R style):
if (...) {
...
} else if (...) {
...
} else {
...
}
```c
if (...) {
...
} else if (...) {
...
} else {
...
}
int function(...)
{
...
}
int function(...)
{
...
}
```
4) Defines and Macros
# Defines and Macros
- Defines and macros shall be named in CAPITAL letters. If a macro contains
multiple statements, they should be enclosed by a 'do {} while (0)' loop.
Macro parameters shall also be capital letters and shall be enclosed py
parantheses if necessary.
#define MACRO(A, B) \
do { \
if ((A) == 1) { \
statement(B); \
```c
#define MACRO(A, B) \
do { \
if ((A) == 1) { \
statement(B); \
} while (0)
```

38
FEATURES → FEATURES.md
View File

@ -1,20 +1,14 @@
-------------------------------------------------------------------------------
This is the FEATURES file of the IgH EtherCAT Master.
$Id$
vim: spelllang=en spell
-------------------------------------------------------------------------------
# General Features
General Features:
* EtherCAT master implementation conforming to IEC/PAS 62407.
- EtherCAT master implementation conforming to IEC/PAS 62407.
- Runs as kernel module for Linux 2.6.
- Multiple masters possible on one machine.
* Native EtherCAT-capable versions of standard Linux drivers for wide-spread
- Native EtherCAT-capable versions of standard Linux drivers for wide-spread
Ethernet devices, as well as a generic driver for all chips supported by the
Linux kernel.
- Interrupt-less operation of Ethernet devices when using native drivers.
@ -25,12 +19,12 @@ General Features:
- For any other hardware, the generic driver can be used. It uses the lower
layers of the Linux network stack.
* Supports any realtime environment through independent architecture.
- Supports any realtime environment through independent architecture.
- RTAI, Xenomai, RT-Preempt, etc.
- RTDM Interface for userspace realtime enviroments
- RTDM Interface for userspace realtime environments
- Operation possible without any realtime extension at all.
* Common API for Realtime-Applications in kernel- and userspace.
- Common API for Realtime-Applications in kernel- and userspace.
- Requesting and releasing masters.
- Dynamic slave configuration, even for slaves that are offline.
- Detailed configuration of the slaves' PDOs and SDOs.
@ -42,37 +36,37 @@ General Features:
- Similar userspace implementation of the kernel API via a C-library.
- Avoidance of unnecessary copy operations for process data.
* Separating slave groups through domains.
- Separating slave groups through domains.
- Handling of multiple slave groups with different sampling rates.
- Automatic calculation of process data mapping, FMMU- and sync manager
configuration within the domains.
- Process data exchange can be monitored via a per-domain mechanism.
* Master finite state machine (FSM).
- Master finite state machine (FSM).
- The same state machine runs both in idle mode and in realtime operation.
- Bus monitoring: Slave states are read cyclically. Automatic scanning of the
bus after a topology change.
- Automatic configuration of slaves, if a application-layer state change is
requested.
* Implementation of the "CANopen over EtherCAT" (CoE) mailbox protocol.
- Implementation of the "CANopen over EtherCAT" (CoE) mailbox protocol.
- Configuration of CoE-capable slaves.
- SDO information service (dictionary listing).
- SDO transfers both via the application interface and the command-line tool.
* Implementation of the "Ethernet over EtherCAT" (EoE) mailbox protocol.
- Implementation of the "Ethernet over EtherCAT" (EoE) mailbox protocol.
- Virtual network interface for any EoE-capable slave.
- Both a switched and a routed EoE network architecture is natively supported
and configurable with standard tools.
* Implementation of the "Vendor-specific over EtherCAT" (VoE) mailbox protocol.
- Implementation of the "Vendor-specific over EtherCAT" (VoE) mailbox protocol.
- Communication with vendor-specific mailbox protocols via the API.
* Implementation of the "File Access over EtherCAT" (FoE) mailbox protocol.
- Implementation of the "File Access over EtherCAT" (FoE) mailbox protocol.
- Loading and storing files via the command-line tool.
- Updating a slave's firmware can be done easily.
* Userspace command-line tool 'ethercat'.
- Userspace command-line tool `ethercat`.
- Detailed information about master, slaves, domains and bus configuration.
- Setting the master's debug level.
- Reading/Writing alias addresses.
@ -85,11 +79,9 @@ General Features:
- Controlling application-layer states.
- Generation of slave description XML from existing slaves.
* Seamless integration in any GNU/Linux distribution.
- Seamless integration in any GNU/Linux distribution.
- "Linux Standard Base"-compatible init script for master control.
- Master and Ethernet device configuration via sysconfig file.
* Virtual read-only network interface for debugging and traffic monitoring
- Virtual read-only network interface for debugging and traffic monitoring
purposes (using Wireshark, etc.). No additional hardware necessary.
-------------------------------------------------------------------------------

22
INSTALL
View File

@ -1,27 +1,23 @@
-------------------------------------------------------------------------------
This is the INSTALL file of the IgH EtherCAT Master.
$Id$
vim: set spelllang=en spell tw=78
-------------------------------------------------------------------------------
Building and installing
=======================
# Building and installing
The complete build and installation procedure is described in the respective
section of the documentation available from http://etherlab.org/en/ethercat.
section of the
[https://gitlab.com/etherlab.org/ethercat/-/jobs/artifacts/stable-1.5/raw/pdf/ethercat_doc.pdf?job=pdf](documentation).
-------------------------------------------------------------------------------
---
For the impatient, the procedure mainly consists of calling:
$ ./bootstrap # to create the configure script, if downloaded from the repo
```bash
./bootstrap # to create the configure script, if downloaded from the repo
$ ./configure --sysconfdir=/etc
$ make all modules
./configure --sysconfdir=/etc
make all modules
```
... and as root:

59
INSTALL.md Normal file
View File

@ -0,0 +1,59 @@
This is the INSTALL file of the IgH EtherCAT Master.
vim: set spelllang=en spell tw=78
# Building and installing
The complete build and installation procedure is described in the respective
section of the
[documentation](https://gitlab.com/etherlab.org/ethercat/-/jobs/artifacts/stable-1.5/raw/pdf/ethercat_doc.pdf?job=pdf).
---
For the impatient: The procedure mainly consists of calling
```bash
./bootstrap # to create the configure script, if downloaded from the repo
./configure --sysconfdir=/etc
make all modules
```
... and as root:
```bash
make modules_install install
depmod
```
... and then customizing the appropriate configuration file:
```bash
vi /etc/ethercat.conf # For systemd based distro
vi /etc/sysconfig/ethercat # For init.d based distro
```
Make sure, that the 'udev' package is installed, to automatically create the
EtherCAT character devices. The character devices will be created with mode
0660 and group root by default. If you want to give normal users reading
access, create a udev rule like this:
```bash
echo KERNEL==\"EtherCAT[0-9]*\", MODE=\"0664\" > /etc/udev/rules.d/99-EtherCAT.rules
```
Now you can start the EtherCAT master:
```bash
systemctl start ethercat # For systemd based distro
/etc/init.d/ethercat start # For init.d based distro
```
Have a look at the [examples subdirectory](examples/) for some application
examples.
---
Have fun!
---

106
README → README.md
View File

@ -1,63 +1,78 @@
------------------------------------------------------------------------------
This is the README file of the IgH EtherCAT Master.
vim: spelllang=en spell tw=78
------------------------------------------------------------------------------
Contents:
1) General Information
2) Requirements
3) Building and installing
4) Realtime & Tuning
5) License
6) Coding Style
- [General Information](#general-information)
- [Requirements](#requirements)
- [Building and Installing](#building-and-installing)
- [Realtime and Tuning](#realtime-and-tuning)
- [License](#license)
- [Coding Style](#coding-style)
------------------------------------------------------------------------------
# General Information
1) General Information
======================
This is an open-source EtherCAT master implementation for Linux 2.6 or newer.
This is an open-source EtherCAT master implementation for Linux 2.6.
See the FEATURES file for a list of features. For more information, see
http://etherlab.org/en/ethercat.
See the [features file](FEATURES.md) for a list of features. For more
information, see http://etherlab.org/en/ethercat.
or contact
Dipl.-Ing. (FH) Florian Pose <fp@igh.de>
Ingenieurgemeinschaft IgH
Nordsternstraße 66
D-45329 Essen
>>>
Dipl.-Ing. (FH) Florian Pose <fp@igh.de>
Ingenieurgemeinschaft IgH
Nordsternstraße 66
D-45329 Essen
http://igh.de
>>>
------------------------------------------------------------------------------
# Documentation
2) Requirements
===============
## Handbook
1) Software requirements
The PDF documentation is generated via LaTeX and can be build with the
following steps:
Configured sources for the Linux 2.6 kernel are required to build the EtherCAT
master.
```bash
cd documentation
make
```
2) Hardware requirements
The PDF is automatically held up-to-date and can be [downloaded from
GitLab](https://gitlab.com/etherlab.org/ethercat/-/jobs/artifacts/stable-1.5/raw/pdf/ethercat_doc.pdf?job=pdf).
## Doxygen
To generate the Doxygen documentation, the following commands can be used.
Therefore, the configure script must have run (see the [install
file](INSTALL.md)).
```bash
git submodule update --init
make doc
```
An up-to-date Doxygen output can be found on
[docs.etherlab.org](https://docs.etherlab.org/ethercat/1.5/doxygen/index.html).
# Requirements
## Software requirements
Configured sources for the Linux 2.6 (or newer) kernel are required to build
the EtherCAT master.
## Hardware requirements
A table of supported hardware can be found at
http://etherlab.org/en/ethercat/hardware.php.
------------------------------------------------------------------------------
# Building and installing
3) Building and installing
==========================
See the [install file](INSTALL.md).
See the INSTALL file.
------------------------------------------------------------------------------
4) Realtime & Tuning
====================
# Realtime and Tuning
Realtime patches for the Linux kernel are supported, but not required. The
realtime processing has to be done by the calling module (see API
@ -65,12 +80,9 @@ documentation). The EtherCAT master code itself is passive (except for the
idle mode and EoE).
To avoid frame timeouts, deactivating DMA access for hard drives is
recommended (hdparm -d0 <DEV>).
recommended (`hdparm -d0 <DEV>`).
------------------------------------------------------------------------------
5) License
==========
# License
Copyright (C) 2006-2023 Florian Pose, Ingenieurgemeinschaft IgH
@ -95,11 +107,7 @@ The license mentioned above concerns the source code only. Using the EtherCAT
technology and brand is only permitted in compliance with the industrial
property and similar rights of Beckhoff Automation GmbH.
------------------------------------------------------------------------------
# Coding Style
6) Coding Style
===============
Developers shall use the coding style rules in the CodingStyle.txt file.
------------------------------------------------------------------------------
Developers shall use the coding style rules in the [coding style
file](CodingStyle.md).