SOEM/doc/soem.dox

/**
 * \mainpage Simple Open EtherCAT Master or SOEM
 *
 * \section start Tutorial
 * For a tutorial on SOEM  See tutorial.txt
 *
 * \section overview Overview
 * SOEM is an EtherCAT master library written in c. Its purpose is to learn and
 * to use. All users are invited to study the source to get an understanding
 * how an EtherCAT master functions and how it interacts with EtherCAT slaves.
 *
 * As all applications are different SOEM tries to not impose any design architecture.
 * Under Linux it can be used in generic user mode, PREEMPT_RT or Xenomai. under Windows
 * it can be used as user mode program.
 *
 * Preconditions Linux:
 * - Linux 2.6 kernel or later.
 * - GCC compiler (others might work, just not tested).
 * - One (or two if in redundant mode) 100Mb/s NIC that can connect to a RAW socket.
 * - Application must run as root / kernel.
 *
 * Preconditions Windows:
 * - Windows2000 - Windows 7 (8 not tested, might work).
 * - VC compiler (others might work, just not tested).
 * - One (or two if in redundant mode) 100Mb/s NIC that can connect to a RAW socket.
 * - WinPcap installed.
 *
 * Features as of 1.1.2 :
 * - Connects to a standard RAW socket.
 * - Full redundancy support.
 * - Recovery of "out-of-order" frames.
 * - Low level functions, BRD, BWR, APRMW, FPRD, LRW....
 * - Blocking or non blocking transfers.
 * - Automatic configuration of slaves.
 * - Use of internal configuration table (quick).
 * - Use of slave internal data in EEprom and/or CoE.
 * - Setting and reading of slave state.
 * - Automatic generation of processdata mapping.
 * - Mailbox link layer support with resend toggle.
 * - CoE, SDO read / write.
 * - CoE, Complete Access support.
 * - CoE, Segmented transfer support.
 * - CoE, Object Description list
 * - CoE, Emergency and abort SDO support.
 * - Distributed Clock (DC) support.
 * - Automatic configuration of DC slaves.
 * - Automatic sync of clocks with process data exchange.
 * - Flexible settting of sync0 and sync1 firing per slave.
 * - Access to slave functions through one slave structure.
 * - EEPROM read / write.
 * - Local cache for EEPROM access with automatic 4/8 byte reading.
 * - SII parsing.
 * - Portable code, only standard c, usable for embedded applications.
 * - All buffers are static so can be memory locked.
 * - Support for Little and Big endian targets.
 *
 * Features as of 1.1.3 :
 * - CoE, TxPDO and RxPDO, master is client (beta).
 * - FoE, Read and Write file (beta).
 *
 * Features as of 1.1.4 :
 * - FMMU allocation is floating instead of fixed. If needed more than 2 FMMUs are used.
 * - SYNC1 generation supported.
 *
 * Features as of 1.2.0 :
 * - Changed license to GPLv2 only. Adresses leagal concerns about master licensing.
 * - Slave init and process data mapping is split in two functions. This allows
 * dynamic user reconfiguration of PDO mapping.
 * - Eeprom transfer to and from PDI
 * - Eeprom is released to PDI when going to SAFEOP.
 *
 * Features as of 1.2.2 :
 * - Redesign of topology and delay measurement. 4 port slaves are fully supported now.
 * - Delay measurement of slaves that are reverse connected work too.
 * - New ethercatprint unit to display errors in readable text.
 *
 * Features as of 1.2.4 :
 * - SoE, servo over EtherCAT support.
 * - SoE read request and write request.
 * - SoE segmented transfers.
 * - SoE error response.
 * - Added SoE errors to print module.
 * - Auto config of SoE process data.
 *
 * Features as of 1.2.5 :
 * - Added eepromtool, it can read and write the ESC eeprom of a designated slave.
 * - Rewrite of eeprom read/write functions.
 * - Added infrastructure change to allow slave groups.
 * - Added recovery and reconfiguration of slaves after connection loss.
 * - Improved CoE PDO assignment read from slaves, no longer assume assign indexes
 * as functionally fixed.
 *
 * Features as of 1.2.8 :
 * - Changed directory structure.
 * - Changed make file.
 * - Moved hardware / OS dependend part in separate directories.
 * - Added firm_update tool to upload firmware to slaves in Boot state, use with care.
 * - Added DC for LRD/LWR case.
 * - Separated expectedWKC to inputsWKC and outputsWKC.
 * - Added PreOP->SafeOP hooks in configuration functions.
 * - With CoE use expedited download if mailbox size is very small and object <= 4 bytes.
 * - Added mailbox error handling.
 * - Rewrite of ec_recover_slave() and ec_reconfigure_slave()
 * - Added -map option in slaveinfo, shows SOEM IO mapping of all slaves found.
 *
 * Features as of 1.3.0 :
 * - Added win32 target.
 * - Added rtk target.
 * - Compiles under gcc / visual-c / borland-c.
 * - Multiple port support. One master can run concurrent stacks on multiple network ports.
 * - All global vars are encapsulated in context struct.
 * - All timing abstracted in osal.c.
 * - Linux timing converted to get_clock(CLOCK_MONOTONIC).
 * - Error messages updated to latest ETG1020 document.
 * - FoE transfers now support busy response.
 *
 * \section build Build instructions
 *
 * See README.md in the root folder.
 *
 * \section start Getting started
 *
 * For examples see simple_test.c in ~/test/linux/simple_test.
 * First try (assume EtherCAT on eth0): sudo ./simple_test eth0
 * As SOEM uses RAW sockets it will need to run as root.
 *
 * \section bugs Squashed bugs
 * Version 1.1.3
 * - Added missing Big-Endian conversion in ethercatconfig.c
 * - Fixed bug in segmented SDO transfers in ethercatcoe.c
 *
 * Version 1.1.4
 * - Changed FMMU algorithm of allocation during configuration. EL4732 supported now.
 * - Changed the ec_slave structure around SM en FMMU storage.
 * - Fixed bug in FoE write in ethercatfoe.c
 *
 * Version 1.2.0
 * - Fixed bug in type definition of int32 and uint32 for 64bit OS.
 * - Fixed bug in maximum dataframe size calculation.
 *
 * Version 1.2.2
 * - Fixed bugs in ec_adddatagram.
 * - Fixed several bugs in CoE object dictionary read functions.
 * - Fixed bug in PDO mapping read function.
 * - Changed ec_slave structure around topology and delay variables.
 * - Added several constants in ethercattype.c
 *
 * Version 1.2.3
 * - Clear SM enable if size is 0, even if enable is set in SII.
 * - Fixed bug in DC propagation delay calculation. Branches with only non DC slaves
 * now correctly close root port.
 * - Fixed bug in ec_receive_processdata(), wkc now checks for EC_NOFRAME instead of 0.
 * - Fixed bug in makefile.
 *
 * Version 1.2.5
 * - Fixed bugs in ec_config_map().
 * - Added EC_STATE_BOOT constant.
 * - Fixed mailbox size bug, In and Out mailbox can now be of different size.
 * - Fixed SM type bug.
 * - Fixed FoE bugs.
 * - Fixed siigetbyte() unaligned copy.
 * - Fixed bug in nicdrv.c, socket handles are 0 included.
 * - Fixed bug in ethercatconfig.c causing memory corruption.
 *
 * Version 1.2.8
 * - Fixed NetX mailbox configuration behaviour.
 * - Fixed FoE write bug.
 * - Fixed SII string read bug.
 * - Fixed bug in table lookup for printing
 *
 * Version 1.3.0
 * - Fixed NetX100 configuration behaviour.
 * - Fixed linux gettimeofday() to get_clock().
 * - Fixed eeprom cache flush on reinit.
 * - Fixed make for new gcc linker version.
 *
 * Version 1.3.1
 * - Added intime target.
 * - Added rtk fec target.
 * - Compiles under gcc / visual-c / intime / borland-c .
 * - Added multi-threaded configuration for parallel configurations of slaves
 *
 * Version 1.3.2 : 2018-02-02
 * - Made a mistake. DON'T USE!
 *
 * Version 1.3.3 : 2018-02-02
 * - Added rtems target.
 * - Added support for overlapping IOmap.
 *
 * \section legal Legal notice
*
 * Licensed under the GNU General Public License version 2 with exceptions. See
 * LICENSE file in the project root for full license information
 *
 */