etherlabmaster: comparison include/ecrt.h

equal deleted inserted replaced

-:ec403cf308eb
+:c5c81a52fc30
 *   EC_HAVE_SELECT_REF_CLOCK to check, if the method is available.
 * - Added method to get the reference clock time,
 *   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
 *   via their positions in the mapping.
 *
 /** Releases a requested EtherCAT 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 */
 );
 *
 * Before an application can use PDO/domain registration functions or SDO
 * 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 */
 );
 * currently accessible and whether or not to call the ecrt_master_send_ext()
 * method.
 *
 * 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 */
 void (*send_cb)(void *), /**< Datagram sending callback. */
 void (*receive_cb)(void *), /**< Receive callback. */
 *
 * For process data exchange, at least one process data domain is needed.
 * This method creates a new process data domain and returns a pointer to the
 * 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(
 ec_master_t *master /**< EtherCAT master. */
 * mismatch, the slave is not configured and an error message is raised.
 *
 * If different slave configurations are pointing to the same slave during bus
 * 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.
 */
 ec_slave_config_t *ecrt_master_slave_config(
 *
 * \attention After this function has been called, the realtime application is
 * 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
 */
 int ecrt_master_activate(
 ec_master_t *master /**< EtherCAT master. */
 * Removes the bus configuration. All objects created by
 * ecrt_master_create_domain(), ecrt_master_slave_config(), ecrt_domain_data()
 * 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. */
 size_t send_interval /**< Send interval in us */
 );
 *
 * The master has to know the application's time when operating slaves with
 * 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' <tt>System Time Offset</tt> and
 * <tt>Cyclic Operation Start Time</tt> registers and when synchronizing the
 * DC reference clock to the application time via
 * ecrt_master_sync_reference_clock().
 *
 /** Configure a sync manager.
 *
 * 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(
 ec_slave_config_t *sc, /**< Slave configuration. */
 ec_direction_t direction, /**< Input/Output. */
 ec_watchdog_mode_t watchdog_mode /** Watchdog mode. */
 );
 /** 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. */
 uint16_t watchdog_divider, /**< Number of 40 ns intervals. Used as a
 base unit for all slave watchdogs. If set
 */
 );
 /** 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
 */
 int ecrt_slave_config_pdo_assign_add(
 ec_slave_config_t *sc, /**< Slave configuration. */
 *
 * This can be called before assigning PDOs via
 * 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(
 ec_slave_config_t *sc, /**< Slave configuration. */
 uint8_t sync_index /**< Sync manager index. Must be less
 than #EC_MAX_SYNC_MANAGERS. */
 );
 /** 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
 */
 int ecrt_slave_config_pdo_mapping_add(
 /** Clear the mapping of a given PDO.
 *
 * 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(
 ec_slave_config_t *sc, /**< Slave configuration. */
 uint16_t pdo_index /**< Index of the PDO. */
 * Processing of \a syncs will stop, if
 * - the number of processed items reaches \a n_syncs, or
 * - the \a index member of an ec_sync_info_t item is 0xff. In this case,
 *   \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(
 ec_slave_config_t *sc, /**< Slave configuration. */
 * the domain's process data is returned. Optionally, the PDO entry bit
 * position (0-7) can be retrieved via the \a bit_position output parameter.
 * 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.
 */
 int ecrt_slave_config_reg_pdo_entry(
 ec_slave_config_t *sc, /**< Slave configuration. */
 *
 * Similar to ecrt_slave_config_reg_pdo_entry(), but not using PDO indices but
 * offsets in the PDO mapping, because PDO entry indices may not be unique
 * 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.
 */
 int ecrt_slave_config_reg_pdo_entry_pos(
 *
 * The AssignActivate word is vendor-specific and can be taken from the XML
 * 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(
 ec_slave_config_t *sc, /**< Slave configuration. */
 uint16_t assign_activate, /**< AssignActivate word. */
 * configured with this function, because they are part of the slave
 * configuration done by the master. Please use ecrt_slave_config_pdos() and
 * 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.
 */
 int ecrt_slave_config_sdo(
 size_t size /**< Size of the \a data. */
 );
 /** 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.
 * \retval <0 Error code.
 */
 uint8_t value /**< Value to set. */
 );
 /** 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.
 * \retval <0 Error code.
 */
 uint16_t value /**< Value to set. */
 );
 /** 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.
 * \retval <0 Error code.
 */
 /** Add configuration data for a complete SDO.
 *
 * 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.
 * \retval <0 Error code.
 */
 /** Set the size of the CoE emergency ring buffer.
 *
 * 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(
 ec_slave_config_t *sc, /**< Slave configuration. */
 size_t elements /**< Number of records of the CoE emergency ring. */
 /** Create an SDO request to exchange SDOs during realtime operation.
 *
 * 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(
 ec_slave_config_t *sc, /**< Slave configuration. */
 * both can be done simultaneously.
 *
 * 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(
 ec_slave_config_t *sc, /**< Slave configuration. */
 size_t size /**< Data size to reserve. */
 * This interface should not be used to take over master functionality,
 * instead it is intended for debugging and monitoring reasons.
 *
 * 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(
 ec_slave_config_t *sc, /**< Slave configuration. */
 * The \a idn parameter can be separated into several sections:
 *  - Bit 15: Standard data (0) or Product data (1)
 *  - 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.
+* Please note that the this function does not do any endianness correction.
-* Multi-byte data have to be passed in EtherCAT endianess (little-endian).
+* 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.
 */
 int ecrt_slave_config_idn(
 * Domain methods
 *****************************************************************************/
 /** 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.
 */
 int ecrt_domain_reg_pdo_entry_list(
 * Call this after all PDO entries have been registered and before activating
 * the master.
 *
 * 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. */
 uint8_t *memory /**< Address of the memory to store the process
 data in. */
 ec_voe_handler_t *voe /**< VoE handler. */
 );
 /** Execute the handler.
 *
-* This method executes the VoE handler. It has to be called in every bus cycle
+* This method executes the VoE handler. It has to be called in every bus
-* as long as it returns EC_REQUEST_BUSY.
+* cycle as long as it returns EC_REQUEST_BUSY.
 *
 * \return Handler state.
 */
 ec_request_state_t ecrt_voe_handler_execute(
 ec_voe_handler_t *voe /**< VoE handler. */
 /** Access to the register request's data.
 *
 * This function returns a pointer to the request's internal memory.
 *
-* - After a read operation was successful, integer data can be evaluated using
+* - After a read operation was successful, integer data can be evaluated
-*   the EC_READ_*() macros as usual. Example:
+*   using the EC_READ_*() macros as usual. Example:
 *   \code
 *   uint16_t value = EC_READ_U16(ecrt_reg_request_data(reg_request)));
 *   \endcode
 * - If a write operation shall be triggered, the data have to be written to
 *   the internal memory. Use the EC_WRITE_*() macros, if you are writing

branch	stable-1.5
changeset 2523	c5c81a52fc30
parent 2522	ec403cf308eb
child 2524	6d9865c37b6f