# HG changeset patch # User Florian Pose # Date 1360683431 -3600 # Node ID c5c81a52fc30c6708f5c2a9c4d27e564693bd033 # Parent ec403cf308eb5efe44c9417a379f414bdbfbb7a5 Improved API documentation. diff -r ec403cf308eb -r c5c81a52fc30 examples/rtai_rtdm_dc/main.c --- a/examples/rtai_rtdm_dc/main.c Tue Feb 12 15:46:43 2013 +0100 +++ b/examples/rtai_rtdm_dc/main.c Tue Feb 12 16:37:11 2013 +0100 @@ -503,6 +503,11 @@ */ 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 -r ec403cf308eb -r c5c81a52fc30 include/ecrt.h --- a/include/ecrt.h Tue Feb 12 15:46:43 2013 +0100 +++ b/include/ecrt.h Tue Feb 12 16:37:11 2013 +0100 @@ -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 @@ * * 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 @@ * 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 @@ * * 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 @@ * 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 @@ * 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 @@ * 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,6 +927,8 @@ * 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. */ @@ -921,9 +936,13 @@ /** 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 @@ * 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 @@ * 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 @@ ); /** 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. */ @@ -1116,6 +1147,9 @@ /** 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 @@ * 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( @@ -1142,6 +1179,9 @@ /** 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 @@ * 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 @@ * \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 @@ * 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 @@ * 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 @@ * 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 @@ * 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. */ @@ -1339,6 +1397,9 @@ /** 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(). * * \retval 0 Success. @@ -1353,6 +1414,9 @@ /** 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(). * * \retval 0 Success. @@ -1367,6 +1431,9 @@ /** 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(). * * \retval 0 Success. @@ -1384,6 +1451,9 @@ * 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 @@ * 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 @@ * 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 @@ * 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 @@ * 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 @@ * - 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 @@ /** 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 @@ * * 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 @@ /** 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 @@ * * 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