diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 11f2bc36..4e7f33bd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -13,12 +13,12 @@ forward to your contributions. 🎉 > And if you like the project, but just don't have time to contribute, that's > fine. There are other easy ways to support the project and show your > appreciation, which we would also be very happy about: +> > - Star the project > - Write something about it in the social media > - Refer this project in your project's readme > - Mention the project at local meetups and tell your friends/colleagues - ## Table of Contents @@ -26,12 +26,7 @@ forward to your contributions. 🎉 - [I Want To Contribute](#i-want-to-contribute) - [Reporting Bugs](#reporting-bugs) - [Suggesting Enhancements](#suggesting-enhancements) - - [Your First Code Contribution](#your-first-code-contribution) - - [Improving The Documentation](#improving-the-documentation) - [Styleguides](#styleguides) - - [Commit Messages](#commit-messages) -- [Join The Project Team](#join-the-project-team) - ## I Have a Question @@ -39,9 +34,9 @@ forward to your contributions. 🎉 > [Documentation](https://docs.etherlab.org). Before you ask a question, it is best to search for existing -[Issues](https://gitlab.com/etherlab.org/ethercat/issues) and in the [mailing -list archives](https://lists.etherlab.org/mailman/listinfo) for posts that -might help you. +[Issues](https://gitlab.com/etherlab.org/ethercat/-/work_items) and in the +[mailing list archives](https://lists.etherlab.org/mailman/listinfo) for posts +that might help you. In case you have found a suitable issue and still need clarification, you can write your question in this issue. It is also advisable to search the internet @@ -52,8 +47,8 @@ recommend the following: - If it is a question about getting a certain device to work, please ask you question on our [mailing lists](https://lists.etherlab.org/mailman/listinfo). -- If f you think the problem lies in the master itself, open an - [Issue](https://gitlab.com/etherlab.org/ethercat/issues/new). +- If you think the problem lies in the master itself, open an + [Issue](https://gitlab.com/etherlab.org/ethercat/-/work_items/new?type=Issue). - Provide as much context as you can about what you're running into. - Provide project and platform versions: EtherCAT master version, Linux Kernel version, the Linux distribution and the used Ethernet driver (generic, @@ -61,15 +56,14 @@ recommend the following: We will then take care of the issue as soon as possible. - ## I Want To Contribute > ### Legal Notice +> > When contributing to this project, you must agree that you have authored 100% > of the content, that you have the necessary rights to the content and that > the content you contribute may be provided under the project licence. - ### Reporting Bugs @@ -89,17 +83,16 @@ possible. - To see if other users have experienced (and potentially already solved) the same issue you are having, check if there is not already a bug report existing for your bug or error in the - [bug tracker](https://gitlab.com/etherlab.org/ethercat/issues?q=label%3Abug). + [bug tracker](https://gitlab.com/etherlab.org/ethercat/-/work_items). - Also make sure to search the internet to see if users outside of the GitLab community have discussed the issue. - Collect information about the bug: - Stack trace (Traceback) - - OS, Platform and Version (Linux Kernel, Distribution, x86, ARM, ...) + - OS, Platform and Version (Linux Kernel, Distribution, x86, ARM, ...) - The Ethernet driver use are using (generic, 8139too, ccat, ...) - Can you reliably reproduce the issue? And can you also reproduce it with older versions? - #### How Do I Submit a Good Bug Report? @@ -110,9 +103,10 @@ possible. We use GitLab issues to track bugs and errors. If you run into an issue with the project: -- Open an [Issue](https://gitlab.com/etherlab.org/ethercat/issues/new). (Since - we can't be sure at this point whether it is a bug or not, we ask you not to - talk about a bug yet and not to label the issue.) +- Open an + [Issue](https://gitlab.com/etherlab.org/ethercat/-/work_items/new?type=Issue). + (Since we can't be sure at this point whether it is a bug or not, we ask you + not to talk about a bug yet and not to label the issue.) - Explain the behavior you would expect and the actual behavior. - Please provide as much context as possible and describe the *reproduction steps* that someone else can follow to recreate the issue on their own. This @@ -124,7 +118,6 @@ Once it's filed: - The project team will label the issue accordingly. - ### Suggesting Enhancements This section guides you through submitting an enhancement suggestion for IgH @@ -132,16 +125,15 @@ EtherCAT Master, **including completely new features and minor improvements to existing functionality**. Following these guidelines will help maintainers and the community to understand your suggestion and find related suggestions. - #### Before Submitting an Enhancement - Make sure that you are using the latest version. - Read the [documentation](https://docs.etherlab.org) carefully and find out if the functionality is already covered, maybe by an individual configuration. -- Perform a [search](https://gitlab.com/etherlab.org/ethercat/issues) to see if - the enhancement has already been suggested. If it has, add a comment to the - existing issue instead of opening a new one. +- Perform a [search](https://gitlab.com/etherlab.org/ethercat/-/work_items) to + see if the enhancement has already been suggested. If it has, add a comment + to the existing issue instead of opening a new one. - Find out whether your idea fits with the scope and aims of the project. It's up to you to make a strong case to convince the project's developers of the merits of this feature. Keep in mind that we want features that will be @@ -149,12 +141,11 @@ the community to understand your suggestion and find related suggestions. just targeting a minority of users, consider writing an add-on/plugin library. - #### How Do I Submit a Good Enhancement Suggestion? Enhancement suggestions are tracked as -[GitLab issues](https://gitlab.com/etherlab.org/ethercat/issues). +[GitLab issues](https://gitlab.com/etherlab.org/ethercat/-/work_items). - Use a **clear and descriptive title** for the issue to identify the suggestion. @@ -170,12 +161,11 @@ Enhancement suggestions are tracked as users. You may also want to point out the other projects that solved it better and which could serve as inspiration. - ## Styleguides There is a [coding style document](CodingStyle.md) next to this guide. - ## Attribution + This guide is based on the [contributing.md](https://contributing.md/generator)! diff --git a/CodingStyle.md b/CodingStyle.md index b51f84e8..9d64c260 100644 --- a/CodingStyle.md +++ b/CodingStyle.md @@ -1,15 +1,15 @@ -vim: spelllang=en tw=78 +# Coding Style This is a short introduction to the coding style that shall be used. The below 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). -# Line length +## Line length - Lines shall not exceed 78 characters. -# Whitespace +## Whitespace - Indentation shall be done using 4 space characters @@ -21,7 +21,7 @@ differences). - Binary operators (`=`, `==`, `~=`, `|`, `||`, etc.) shall be enclosed by 2 spaces (except `.` and `->`). -# Placing braces +## Placing braces - Braces shall be placed in the following way (K&R style): @@ -40,7 +40,7 @@ int function(...) } ``` -# 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. @@ -54,3 +54,5 @@ int function(...) statement(B); \ } while (0) ``` + +vim: spelllang=en tw=78 diff --git a/FEATURES.md b/FEATURES.md index e5f85c4e..8c8ee0ee 100644 --- a/FEATURES.md +++ b/FEATURES.md @@ -1,9 +1,7 @@ -This is the FEATURES file of the IgH EtherCAT Master. - -vim: spelllang=en spell - # General Features +This is the FEATURES.md file of the IgH EtherCAT Master. + - EtherCAT master implementation conforming to IEC/PAS 62407. - Runs as kernel module for Linux 2.6. - Multiple masters possible on one machine. @@ -85,3 +83,5 @@ vim: spelllang=en spell - Virtual read-only network interface for debugging and traffic monitoring purposes (using Wireshark, etc.). No additional hardware necessary. + +vim: spelllang=en spell diff --git a/INSTALL.md b/INSTALL.md index 38045c4e..0f4f135c 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -1,12 +1,10 @@ -This is the INSTALL file of the IgH EtherCAT Master. - -vim: set spelllang=en spell tw=78 - # Building and installing +This is the INSTALL.md file of the IgH EtherCAT Master. + 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). +[documentation](https://gitlab.com/etherlab.org/ethercat/-/jobs/artifacts/stable-1.6/raw/pdf/ethercat_doc.pdf?job=pdf). --- @@ -57,3 +55,5 @@ examples. Have fun! --- + +vim: set spelllang=en spell tw=78 diff --git a/README.md b/README.md index 2f0b2947..9f285be4 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,15 @@ -This is the README file of the IgH EtherCAT Master. - -Contents: +# The IgH EtherCAT Master [[_TOC_]] -# General Information +## General Information + +This is the README.md file of the IgH EtherCAT Master. This is an open-source EtherCAT master implementation for Linux 2.6 or newer. See the [features file](FEATURES.md) for a list of features. For more -information, see https://etherlab.org/ethercat. +information, see [etherlab.org/ethercat](https://etherlab.org/ethercat). or contact @@ -18,12 +18,12 @@ Dipl.-Ing. (FH) Florian Pose Ingenieurgemeinschaft IgH Nordsternstraße 66 D-45329 Essen -http://igh.de +[igh.de](http://igh.de) >>> -# Documentation +## Documentation -## Handbook +### Handbook The PDF documentation is generated via LaTeX and can be build with the following steps: @@ -36,7 +36,7 @@ make 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 +### Doxygen To generate the Doxygen documentation, the following commands can be used. Therefore, the configure script must have run (see the [install @@ -50,30 +50,30 @@ make doc An up-to-date Doxygen output can be found on [docs.etherlab.org](https://docs.etherlab.org/ethercat/1.6/doxygen/index.html). -# Requirements +## Requirements -## Software requirements +### Software requirements Configured sources for the Linux 2.6 (or newer) kernel are required to build the EtherCAT master. -## Hardware requirements +### Hardware requirements -A table of supported hardware can be found at: -https://docs.etherlab.org/ethercat/1.6/doxygen/devicedrivers.html +A table of supported hardware can be found at +[docs.etherlab.org](https://docs.etherlab.org/ethercat/1.6/doxygen/devicedrivers.html). -# Building and installing +## Building and installing See the [install file](INSTALL.md). -# Dry-run and Field Simulation +## Dry-run and Field Simulation A limited set of the userspace API is available in `libfakeethercat`, a library which can be used to run an userspace application without an EtherCAT master or with emulated EtherCAT slaves. -Please find some details [here](fake_lib/README.md). +Please find some details in the [Fakelib README](fake_lib/README.md). -# Realtime and 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 @@ -83,7 +83,7 @@ idle mode and EoE). To avoid frame timeouts, deactivating DMA access for hard drives is recommended (`hdparm -d0 `). -# License +## License Copyright (C) 2006-2023 Florian Pose, Ingenieurgemeinschaft IgH @@ -102,11 +102,11 @@ You should have received a copy of the GNU General Public License along with the IgH EtherCAT Master; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA -# I have a question / I want to contribute +## I have a question / I want to contribute Please see the [contributiong document](CONTRIBUTING.md). -# Coding Style +## Coding Style Developers shall use the coding style rules in the [coding style file](CodingStyle.md). diff --git a/devices/device_drivers_template.md b/devices/device_drivers_template.md index 63ee5b62..3f9912d4 100644 --- a/devices/device_drivers_template.md +++ b/devices/device_drivers_template.md @@ -1,18 +1,21 @@ Device Drivers {#devicedrivers} ============== -This table contains a list of all available native drivers, -depending on the kernel version. +This table contains a list of all available native drivers, depending on the +kernel version. The `generic` and the `ccat` driver are independent of the kernel version. To find out which native driver is required for your network card, you can use `lspci -vv` or look in `/sys`: + ```sh admin@ipc:~> ls -l /sys/class/net/eth5/device/driver lrwxrwxrwx 1 root root 0 6. Nov 15:35 /sys/class/net/eth5/device/driver -> ../../../../bus/pci/drivers/e1000 ``` + or + ```sh admin@ipc:~> basename $(readlink /sys/class/net/eth5/device/driver) e1000 diff --git a/fake_lib/README.md b/fake_lib/README.md index 220e833e..4b67ccf7 100644 --- a/fake_lib/README.md +++ b/fake_lib/README.md @@ -1,5 +1,4 @@ -FakeEtherCAT Library {#libfakeethercat} -==================== +# FakeEtherCAT Library {#libfakeethercat} Libfakeethercat is a userspace library which has the same API as the EtherCAT master interface library libethercat. Libfakeethercat can be used to spin up @@ -14,11 +13,11 @@ references), most function calls will just do nothing and return no error. However, some methods have a bit of logic implemented to simulate a working master. This is what is possible: - - Creating master and domain instances - - Activating master, `send()` and `receive()`. - - Processing and queuing domains - - Configuring PDOs - - Configuring SDOs using `ecrt_slave_config_sdo*()` +- Creating master and domain instances +- Activating master, `send()` and `receive()`. +- Processing and queuing domains +- Configuring PDOs +- Configuring SDOs using `ecrt_slave_config_sdo*()` The SDO config does not do anything, but when activating the master the SDO config will be dumped into a JSON file. @@ -29,8 +28,8 @@ bus works without errors. So currently, a bus error cannot be simulated. ## How to build [RtIPC](https://gitlab.com/etherlab.org/rtipc) is needed. Simply pass -`--enable-fakeuserlib` to your `./configure` call and the library will be -built for you. +`--enable-fakeuserlib` to your `./configure` call and the library will be built +for you. ## How to set up dry run mode @@ -67,6 +66,7 @@ export FAKE_EC_HOMEDIR=/tmp/FakeEtherCAT rm -rf $FAKE_EC_HOMEDIR mkdir -p $FAKE_EC_HOMEDIR ``` + For each master instance, one subdirectory named by the master id is created. ### Spin up your application @@ -123,7 +123,7 @@ simulator. ## Environment variables - - FAKE_EC_HOMEDIR: Directory for RtIPC bulletin board and SDO json files - - FAKE_EC_NAME: Will be used for naming RtIPC config and SDO json file - - FAKE_EC_PREFIX: Prefix for RtIPC variables, useful to run multiple - simulators side by side. +- `FAKE_EC_HOMEDIR`: Directory for RtIPC bulletin board and SDO json files +- `FAKE_EC_NAME`: Will be used for naming RtIPC config and SDO json file +- `FAKE_EC_PREFIX`: Prefix for RtIPC variables, useful to run multiple simulators + side by side. diff --git a/master/api_usage_notes.md b/master/api_usage_notes.md index 1880866d..64510b70 100644 --- a/master/api_usage_notes.md +++ b/master/api_usage_notes.md @@ -1,5 +1,4 @@ -Notes regaring API Usage {#apiusage} -======================== +# Notes regaring API Usage {#apiusage} There are some restrictions on the [Application Interface](@ref ApplicationInterface) with respect to the state of @@ -10,12 +9,12 @@ following. All configuration (`ecrt_slave_config_*()`) has to be done in Linux process context. They can be blocking, so take care when holding locks. After -ecrt_master_activate() ing the master, your application must not alter the -slave configuration. Instead, update process data using ecrt_domain_queue() -and ecrt_domain_process() or use the asynchronous interface like +`ecrt_master_activate()` ing the master, your application must not alter the +slave configuration. Instead, update process data using ecrt_domain_queue() and +ecrt_domain_process() or use the asynchronous interface like ecrt_sdo_request_read(). Don't forget to ecrt_master_receive() and -ecrt_master_send(). These functions can be called from non-process context -too, like Xenomai/RTAI applications or custom kernel modules. +ecrt_master_send(). These functions can be called from non-process context too, +like Xenomai/RTAI applications or custom kernel modules. ## Master Phase