ethercat/master/api_usage_notes.md

Notes regaring API Usage

There are some restrictions on the [Application Interface](@ref ApplicationInterface) with respect to the state of the master instance and the calling context, which are explained in the following.

Rules of Thumb

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_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.

Master phase

The first distinction of cases is whether ecrt_master_activate() has been called or not. Before ecrt_master_activate() (or after ecrt_master_deactivate()), the master is in idle phase. Sending and receiving EtherCAT frames will be done by the master itself, the application (e. g. you) can store slave configurations for later use. After ecrt_master_activate(), the master switches into operation mode. The application is now in charge of steering the communication. Process data can be exchanged under real time constraints. Altering the slave configuration is not possible anymore.

Tag	Description
master_op	Master must be in operation phase, so after
	ecrt_master_activate() has been called.
master_idle	Master must be in idle phase, so before
	ecrt_master_activate() has been called.
master_any	Master can be in idle or operation phase.

Allowed Context

The second distinction of cases is the calling context, which means how the application is run. Most of the functions of the [Application Interface](@ref ApplicationInterface) have to acquire locks or allocate memory, so they are potentially sleeping. They are tagged as blocking. Sleeping is not allowed in all contexts, for instance when using Xenomai/RTAI or a kernel timer. Only a very limited set of functions can be called from any context, marked as rt_safe. They do not allocate memory and will not block.

Tag	Description
rt_safe	Realtime context (RT userspace, atomic/softirq
	context in kernel, Xenomai/RTAI RT task) safe.
blocking	Linux process context only (userspace or
	kernel), might block.