54 lines
2.8 KiB
Markdown
54 lines
2.8 KiB
Markdown
Notes regaring API Usage {#apiusage}
|
|
========================
|
|
|
|
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. |
|