Reviewed API usage.
This commit is contained in:
Florian Pose
parent
2c3a92ff23
commit
4a39a106e1
|
|
@ -821,8 +821,7 @@ EC_PUBLIC_API int ecrt_master_select_reference_clock(
|
|||
|
||||
/** Obtains master information.
|
||||
*
|
||||
* No memory is allocated on the heap in
|
||||
* this function.
|
||||
* No memory is allocated on the heap in this function.
|
||||
*
|
||||
* \apiusage{master_any,rt_safe}
|
||||
*
|
||||
|
|
@ -844,7 +843,6 @@ EC_PUBLIC_API int ecrt_master(
|
|||
*
|
||||
* \attention The pointer to this structure must point to a valid variable.
|
||||
*
|
||||
*
|
||||
* \return 0 in case of success, else < 0
|
||||
*/
|
||||
EC_PUBLIC_API int ecrt_master_scan_progress(
|
||||
|
|
@ -1192,6 +1190,7 @@ EC_PUBLIC_API int ecrt_master_link_state(
|
|||
* the slaves' SYNC0/1 interrupts. It should be called constantly at the same
|
||||
* point of the realtime cycle. So it is recommended to call it at the start
|
||||
* of the calculations to avoid deviancies due to changing execution times.
|
||||
* Avoid calling this method before the realtime cycle is established.
|
||||
*
|
||||
* The time is used when setting the slaves' <tt>System Time Offset</tt> and
|
||||
* <tt>Cyclic Operation Start Time</tt> registers and when synchronizing the
|
||||
|
|
@ -1202,7 +1201,7 @@ EC_PUBLIC_API int ecrt_master_link_state(
|
|||
* epoch time can be done with the EC_TIMEVAL2NANO() macro, but is not
|
||||
* necessary, since the absolute value is not of any interest.
|
||||
*
|
||||
* \apiusage{master_any,rt_safe}
|
||||
* \apiusage{master_op,rt_safe}
|
||||
*
|
||||
* \return Zero on success, otherwise negative error code.
|
||||
*/
|
||||
|
|
@ -2168,6 +2167,10 @@ EC_PUBLIC_API int ecrt_domain_reg_pdo_entry_list(
|
|||
);
|
||||
|
||||
/** Returns the current size of the domain's process data.
|
||||
*
|
||||
* The domain size is calculated after master activation.
|
||||
*
|
||||
* \apiusage{master_op,rt_safe}
|
||||
*
|
||||
* \return Size of the process data image, or a negative error code.
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -1,59 +1,53 @@
|
|||
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.
|
||||
|
||||
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.
|
||||
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 state
|
||||
## 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 mode.
|
||||
Sending and receiving EtherCAT frames will be done by the master itself,
|
||||
the Application (e.g. you) can configure the Slaves.
|
||||
After ecrt_master_activate(), the Master switches into Operational (OP) 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 Operational State, so after `ecrt_master_activate()` has been called. |
|
||||
| `master_idle` | Master must be in Idle State, so before `ecrt_master_activate()` has been called. |
|
||||
| `master_any` | Master can be in Idle or Operational State. |
|
||||
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 of the caller,
|
||||
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.
|
||||
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. |
|
||||
| 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. |
|
||||
|
|
|
|||
Loading…
Reference in New Issue