From ecda31bb6a14fe5348888d75d7de5979b67393cb Mon Sep 17 00:00:00 2001 From: Florian Pose Date: Tue, 12 Feb 2013 16:37:11 +0100 Subject: [PATCH] Improved API documentation. --- examples/rtai_rtdm_dc/main.c | 5 ++ include/ecrt.h | 119 +++++++++++++++++++++++++++++++---- 2 files changed, 111 insertions(+), 13 deletions(-) diff --git a/examples/rtai_rtdm_dc/main.c b/examples/rtai_rtdm_dc/main.c index 4efc4861..de40b603 100644 --- a/examples/rtai_rtdm_dc/main.c +++ b/examples/rtai_rtdm_dc/main.c @@ -503,6 +503,11 @@ int main(int argc, char *argv[]) */ dc_start_time_ns = system_time_ns(); dc_time_ns = dc_start_time_ns; + + /* Attention: The initial application time is also used for phase + * calculation for the SYNC0/1 interrupts. Please be sure to call it at + * the correct phase to the realtime cycle. + */ ecrt_master_application_time(master, dc_start_time_ns); ret = ecrt_master_select_reference_clock(master, sc_ek1100); diff --git a/include/ecrt.h b/include/ecrt.h index 01902051..46137e72 100644 --- a/include/ecrt.h +++ b/include/ecrt.h @@ -64,7 +64,7 @@ * ecrt_master_reference_clock_time() and the feature flag * EC_HAVE_REF_CLOCK_TIME to have the possibility to synchronize the master * clock to the reference clock. - * - Changed the datatypes of the shift times in ecrt_slave_config_dc() to + * - Changed the data types of the shift times in ecrt_slave_config_dc() to * int32_t to correctly display negative shift times. * - Added ecrt_slave_config_reg_pdo_entry_pos() and the feature flag * EC_HAVE_REG_BY_POS for registering PDO entries with non-unique indices @@ -588,6 +588,11 @@ ec_master_t *ecrt_open_master( * * After use, a master it has to be released to make it available for other * applications. + * + * This method frees all created data structures. It should not be called in + * realtime context. + * + * If the master was activated, ecrt_master_deactivate() is called internally. */ void ecrt_release_master( ec_master_t *master /**< EtherCAT master */ @@ -605,7 +610,6 @@ void ecrt_release_master( * request functions on the master, it has to reserve one for exclusive use. * * \return 0 in case of success, else < 0 - * */ int ecrt_master_reserve( ec_master_t *master /**< EtherCAT master */ @@ -629,6 +633,8 @@ int ecrt_master_reserve( * * The task of the receive callback (\a receive_cb) is to decide, if a call to * ecrt_master_receive() is allowed and to execute it respectively. + * + * \attention This method has to be called before ecrt_master_activate(). */ void ecrt_master_callbacks( ec_master_t *master, /**< EtherCAT master */ @@ -647,6 +653,9 @@ void ecrt_master_callbacks( * new domain object. This object can be used for registering PDOs and * exchanging them in cyclic operation. * + * This method allocates memory and should be called in non-realtime context + * before ecrt_master_activate(). + * * \return Pointer to the new domain on success, else NULL. */ ec_domain_t *ecrt_master_create_domain( @@ -677,6 +686,9 @@ ec_domain_t *ecrt_master_create_domain( * configuration, a warning is raised and only the first configuration is * applied. * + * This method allocates memory and should be called in non-realtime context + * before ecrt_master_activate(). + * * \retval >0 Pointer to the slave configuration structure. * \retval NULL in the error case. */ @@ -899,7 +911,8 @@ int ecrt_master_read_idn( * in charge of cyclically calling ecrt_master_send() and * ecrt_master_receive() to ensure bus communication. Before calling this * function, the master thread is responsible for that, so these functions may - * not be called! + * not be called! The method itself allocates memory and should not be called + * in realtime context. * * \return 0 in case of success, else < 0 */ @@ -914,16 +927,22 @@ int ecrt_master_activate( * ecrt_slave_config_create_sdo_request() and * ecrt_slave_config_create_voe_handler() are freed, so pointers to them * become invalid. + * + * This method should not be called in realtime context. */ void ecrt_master_deactivate( ec_master_t *master /**< EtherCAT master. */ ); /** Set interval between calls to ecrt_master_send(). + * + * This information helps the master to decide, how much data can be appended + * to a frame by the master state machine. When the master is configured with + * --enable-hrtimers, this is used to calculate the scheduling of the master + * thread. * * \retval 0 on success. * \retval <0 Error code. - * */ int ecrt_master_set_send_interval( ec_master_t *master, /**< EtherCAT master. */ @@ -997,6 +1016,12 @@ int ecrt_master_link_state( * distributed clocks. The time is not incremented by the master itself, so * this method has to be called cyclically. * + * \attention The first call of this method is used to calculate the phase + * delay for the slaves' SYNC0/1 interrupts. Either the method has to be + * called during the realtime cycle *only*, or the first time submitted must + * be in-phase with the realtime cycle. Otherwise synchronisation problems can + * occur. + * * The time is used when setting the slaves' System Time Offset and * Cyclic Operation Start Time registers and when synchronizing the * DC reference clock to the application time via @@ -1090,6 +1115,9 @@ void ecrt_master_reset( * Sets the direction of a sync manager. This overrides the direction bits * from the default control register from SII. * + * This method has to be called in non-realtime context before + * ecrt_master_activate(). + * * \return zero on success, else non-zero */ int ecrt_slave_config_sync_manager( @@ -1101,6 +1129,9 @@ int ecrt_slave_config_sync_manager( ); /** Configure a slave's watchdog times. + * + * This method has to be called in non-realtime context before + * ecrt_master_activate(). */ void ecrt_slave_config_watchdog( ec_slave_config_t *sc, /**< Slave configuration. */ @@ -1115,6 +1146,9 @@ void ecrt_slave_config_watchdog( ); /** Add a PDO to a sync manager's PDO assignment. + * + * This method has to be called in non-realtime context before + * ecrt_master_activate(). * * \see ecrt_slave_config_pdos() * \return zero on success, else non-zero @@ -1132,6 +1166,9 @@ int ecrt_slave_config_pdo_assign_add( * ecrt_slave_config_pdo_assign_add(), to clear the default assignment of a * sync manager. * + * This method has to be called in non-realtime context before + * ecrt_master_activate(). + * * \see ecrt_slave_config_pdos() */ void ecrt_slave_config_pdo_assign_clear( @@ -1141,6 +1178,9 @@ void ecrt_slave_config_pdo_assign_clear( ); /** Add a PDO entry to the given PDO's mapping. + * + * This method has to be called in non-realtime context before + * ecrt_master_activate(). * * \see ecrt_slave_config_pdos() * \return zero on success, else non-zero @@ -1160,6 +1200,9 @@ int ecrt_slave_config_pdo_mapping_add( * This can be called before mapping PDO entries via * ecrt_slave_config_pdo_mapping_add(), to clear the default mapping. * + * This method has to be called in non-realtime context before + * ecrt_master_activate(). + * * \see ecrt_slave_config_pdos() */ void ecrt_slave_config_pdo_mapping_clear( @@ -1233,6 +1276,9 @@ void ecrt_slave_config_pdo_mapping_clear( * \a n_syncs should set to a number greater than the number of list items; * using EC_END is recommended. * + * This method has to be called in non-realtime context before + * ecrt_master_activate(). + * * \return zero on success, else non-zero */ int ecrt_slave_config_pdos( @@ -1255,6 +1301,9 @@ int ecrt_slave_config_pdos( * This pointer may be \a NULL, in this case an error is raised if the PDO * entry does not byte-align. * + * This method has to be called in non-realtime context before + * ecrt_master_activate(). + * * \retval >=0 Success: Offset of the PDO entry's process data. * \retval <0 Error code. */ @@ -1274,6 +1323,9 @@ int ecrt_slave_config_reg_pdo_entry( * inside a slave's PDO mapping. An error is raised, if * one of the given positions is out of range. * + * This method has to be called in non-realtime context before + * ecrt_master_activate(). + * * \retval >=0 Success: Offset of the PDO entry's process data. * \retval <0 Error code. */ @@ -1296,6 +1348,9 @@ int ecrt_slave_config_reg_pdo_entry_pos( * device description file (Device -> Dc -> AssignActivate). Set this to zero, * if the slave shall be operated without distributed clocks (default). * + * This method has to be called in non-realtime context before + * ecrt_master_activate(). + * * \attention The \a sync1_shift time is ignored. */ void ecrt_slave_config_dc( @@ -1321,11 +1376,14 @@ void ecrt_slave_config_dc( * friends instead. * * This is the generic function for adding an SDO configuration. Please note - * that the this function does not do any endianess correction. If + * that the this function does not do any endianness correction. If * datatype-specific functions are needed (that automatically correct the - * endianess), have a look at ecrt_slave_config_sdo8(), + * endianness), have a look at ecrt_slave_config_sdo8(), * ecrt_slave_config_sdo16() and ecrt_slave_config_sdo32(). * + * This method has to be called in non-realtime context before + * ecrt_master_activate(). + * * \retval 0 Success. * \retval <0 Error code. */ @@ -1338,6 +1396,9 @@ int ecrt_slave_config_sdo( ); /** Add a configuration value for an 8-bit SDO. + * + * This method has to be called in non-realtime context before + * ecrt_master_activate(). * * \see ecrt_slave_config_sdo(). * @@ -1352,6 +1413,9 @@ int ecrt_slave_config_sdo8( ); /** Add a configuration value for a 16-bit SDO. + * + * This method has to be called in non-realtime context before + * ecrt_master_activate(). * * \see ecrt_slave_config_sdo(). * @@ -1366,6 +1430,9 @@ int ecrt_slave_config_sdo16( ); /** Add a configuration value for a 32-bit SDO. + * + * This method has to be called in non-realtime context before + * ecrt_master_activate(). * * \see ecrt_slave_config_sdo(). * @@ -1384,6 +1451,9 @@ int ecrt_slave_config_sdo32( * The SDO data are transferred via CompleteAccess. Data for the first * subindex (0) have to be included. * + * This method has to be called in non-realtime context before + * ecrt_master_activate(). + * * \see ecrt_slave_config_sdo(). * * \retval 0 Success. @@ -1401,6 +1471,9 @@ int ecrt_slave_config_complete_sdo( * The initial size is zero, so all messages will be dropped. This method can * be called even after master activation, but it will clear the ring buffer! * + * This method has to be called in non-realtime context before + * ecrt_master_activate(). + * * \return 0 on success, or negative error code. */ int ecrt_slave_config_emerg_size( @@ -1450,6 +1523,9 @@ int ecrt_slave_config_emerg_overruns( * The created SDO request object is freed automatically when the master is * released. * + * This method has to be called in non-realtime context before + * ecrt_master_activate(). + * * \return New SDO request, or NULL on error. */ ec_sdo_request_t *ecrt_slave_config_create_sdo_request( @@ -1469,6 +1545,9 @@ ec_sdo_request_t *ecrt_slave_config_create_sdo_request( * The created VoE handler object is freed automatically when the master is * released. * + * This method has to be called in non-realtime context before + * ecrt_master_activate(). + * * \return New VoE handler, or NULL on error. */ ec_voe_handler_t *ecrt_slave_config_create_voe_handler( @@ -1485,6 +1564,9 @@ ec_voe_handler_t *ecrt_slave_config_create_voe_handler( * The created register request object is freed automatically when the master * is released. * + * This method has to be called in non-realtime context before + * ecrt_master_activate(). + * * \return New register request, or NULL on error. */ ec_reg_request_t *ecrt_slave_config_create_reg_request( @@ -1519,8 +1601,11 @@ void ecrt_slave_config_state( * - Bit 14 - 12: Parameter set (0 - 7) * - Bit 11 - 0: Data block number (0 - 4095) * - * Please note that the this function does not do any endianess correction. - * Multi-byte data have to be passed in EtherCAT endianess (little-endian). + * Please note that the this function does not do any endianness correction. + * Multi-byte data have to be passed in EtherCAT endianness (little-endian). + * + * This method has to be called in non-realtime context before + * ecrt_master_activate(). * * \retval 0 Success. * \retval <0 Error code. @@ -1541,7 +1626,11 @@ int ecrt_slave_config_idn( /** Registers a bunch of PDO entries for a domain. * - * \todo doc + * This method has to be called in non-realtime context before + * ecrt_master_activate(). + * + * \see ecrt_slave_config_reg_pdo_entry() + * * \attention The registration array has to be terminated with an empty * structure, or one with the \a index field set to zero! * \return 0 on success, else non-zero. @@ -1569,6 +1658,10 @@ size_t ecrt_domain_size( * * The size of the allocated memory must be at least ecrt_domain_size(), after * all PDO entries have been registered. + * + * This method has to be called in non-realtime context before + * ecrt_master_activate(). + * */ void ecrt_domain_external_memory( ec_domain_t *domain, /**< Domain. */ @@ -1853,8 +1946,8 @@ void ecrt_voe_handler_read_nosync( /** Execute the handler. * - * This method executes the VoE handler. It has to be called in every bus cycle - * as long as it returns EC_REQUEST_BUSY. + * This method executes the VoE handler. It has to be called in every bus + * cycle as long as it returns EC_REQUEST_BUSY. * * \return Handler state. */ @@ -1870,8 +1963,8 @@ ec_request_state_t ecrt_voe_handler_execute( * * This function returns a pointer to the request's internal memory. * - * - After a read operation was successful, integer data can be evaluated using - * the EC_READ_*() macros as usual. Example: + * - After a read operation was successful, integer data can be evaluated + * using the EC_READ_*() macros as usual. Example: * \code * uint16_t value = EC_READ_U16(ecrt_reg_request_data(reg_request))); * \endcode