From 4a39a106e19ee5eec7e6339fa52a234fa7386971 Mon Sep 17 00:00:00 2001 From: Florian Pose Date: Thu, 6 Jun 2024 15:07:25 +0200 Subject: [PATCH] Reviewed API usage. --- include/ecrt.h | 11 +++-- master/api_usage_notes.md | 86 ++++++++++++++++++--------------------- 2 files changed, 47 insertions(+), 50 deletions(-) diff --git a/include/ecrt.h b/include/ecrt.h index 8832482b..3ab462fb 100644 --- a/include/ecrt.h +++ b/include/ecrt.h @@ -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' System Time Offset and * Cyclic Operation Start Time 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. */ diff --git a/master/api_usage_notes.md b/master/api_usage_notes.md index 11be7b72..e365cda3 100644 --- a/master/api_usage_notes.md +++ b/master/api_usage_notes.md @@ -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. |