Mirrors_Framework/ethercat
1
0
Fork 0
mirror of https://gitlab.com/etherlab.org/ethercat.git synced 2026-02-05 19:39:50 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

Reviewed API usage.

Browse Source
This commit is contained in:
Florian Pose
2024-06-06 15:07:25 +02:00
parent 2c3a92ff23
commit 4a39a106e1
2 changed files with 47 additions and 50 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
include/ecrt.h
View File

@@ -821,8 +821,7 @@ EC_PUBLIC_API int ecrt_master_select_reference_clock(
/** Obtains master information. /** Obtains master information.
* *
* No memory is allocated on the heap in * No memory is allocated on the heap in this function.
* this function.
* *
* \apiusage{master_any,rt_safe} * \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. * \attention The pointer to this structure must point to a valid variable.
* *
*
* \return 0 in case of success, else < 0 * \return 0 in case of success, else < 0
*/ */
EC_PUBLIC_API int ecrt_master_scan_progress( 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 * 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 * 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. * 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 * 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 * <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 * epoch time can be done with the EC_TIMEVAL2NANO() macro, but is not
* necessary, since the absolute value is not of any interest. * 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. * \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. /** 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. * \return Size of the process data image, or a negative error code.
*/ */

86
master/api_usage_notes.md
View File

@@ -1,59 +1,53 @@
Notes regaring API Usage {#apiusage} Notes regaring API Usage {#apiusage}
======================== ========================
There are some restrictions on the [Application Interface](@ref ApplicationInterface) There are some restrictions on the [Application Interface](@ref
with respect to the state of the Master instance and the calling context, ApplicationInterface) with respect to the state of the master instance and the
which are explained in the following. calling context, which are explained in the following.
## Rules of Thumb ## Rules of Thumb
All configuration (`ecrt_slave_config_*()`) has to be done in Linux Process context. All configuration (`ecrt_slave_config_*()`) has to be done in Linux process
They can be blocking, so take care when holding locks. context. They can be blocking, so take care when holding locks. After
After ecrt_master_activate() ing the master, ecrt_master_activate() ing the master, your application must not alter the
your application must not alter the Slave configuration. slave configuration. Instead, update process data using ecrt_domain_queue()
Instead, update Process Data using and ecrt_domain_process() or use the asynchronous interface like
ecrt_domain_queue() and ecrt_domain_process() ecrt_sdo_request_read(). Don't forget to ecrt_master_receive() and
or use the asynchronous interface like ecrt_sdo_request_read(). ecrt_master_send(). These functions can be called from non-process context
Don't forget to ecrt_master_receive() and ecrt_master_send(). too, like Xenomai/RTAI applications or custom kernel modules.
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. The first distinction of cases is whether ecrt_master_activate() has been
Before ecrt_master_activate() (or after ecrt_master_deactivate()), called or not. Before ecrt_master_activate() (or after
the master is in Idle mode. ecrt_master_deactivate()), the master is in idle phase. Sending and receiving
Sending and receiving EtherCAT frames will be done by the master itself, EtherCAT frames will be done by the master itself, the application (e. g. you)
the Application (e.g. you) can configure the Slaves. can store slave configurations for later use. After ecrt_master_activate(),
After ecrt_master_activate(), the Master switches into Operational (OP) mode. the master switches into operation mode. The application is now in charge of
The Application is now in charge of steering the communication. steering the communication. Process data can be exchanged under real time
Process data can be exchanged under real time constraints. constraints. Altering the slave configuration is not possible anymore.
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. |
| 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 ## Allowed Context
The second distinction of cases is the calling context of the caller, The second distinction of cases is the calling context, which means how the
which means how the Application is run. application is run. Most of the functions of the [Application Interface](@ref
Most of the functions of the [Application Interface](@ref ApplicationInterface) ApplicationInterface) have to acquire locks or allocate memory, so they are
have to acquire locks or allocate memory, potentially sleeping. They are tagged as `blocking`. Sleeping is not allowed
so they are potentially sleeping. in all contexts, for instance when using Xenomai/RTAI or a kernel timer. Only
They are tagged as `blocking`. a very limited set of functions can be called from any context, marked as
Sleeping is not allowed in all contexts, `rt_safe`. They do not allocate memory and will not block.
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.
| Tag | Description |
| Tag | Description | |------------|------------------------------------------------|
|------------|-------------| | `rt_safe` | Realtime context (RT userspace, atomic/softirq |
| `rt_safe` | Realtime Context (RT Userspace, atomic/softirq context in Kernel, Xenomai/RTAI RT Task) safe. | | | context in kernel, Xenomai/RTAI RT task) safe. |
| `blocking` | Linux Process context only (Userspace or Kernel), might block. | | `blocking` | Linux process context only (userspace or |
| | kernel), might block. |