mirror of
https://gitlab.com/etherlab.org/ethercat.git
synced 2026-02-06 03:41:52 +08:00
52 lines
2.9 KiB
Markdown
52 lines
2.9 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. |
|