etherlabmaster: comparison include/ecrt.h

equal deleted inserted replaced

-:d8d9a1056afa
+:939f3e9bba1e
 *   ecrt_slave_config_state().
 * - Process data memory for a domain can now be allocated externally. This
 *   offers the possibility to use a shared-memory region. Therefore,
 *   added the domain methods ecrt_domain_size() and
 *   ecrt_domain_external_memory().
-* - PDO registration functions do not return a process data pointer any
+* - Pdo entry registration functions do not return a process data pointer,
-*   more. Instead an offset is returned by the funtion. In addition, an
+*   but an offset in the domain's process data. In addition, an optional bit
-*   optional bit position can be requested.
+*   position can be requested. This was necessary for the external domain
-*   This was necessary for the external domain memory. An additional
+*   memory. An additional advantage is, that the returned offset is
-*   advantage is, that the returned offset is immediately valid.
+*   immediately valid. If the domain's process data is allocated internally,
-*   If the domain's process data is allocated internally, the start
+*   the start address can be retrieved with ecrt_domain_data().
-*   address can be retrieved with ecrt_domain_data().
 * - Replaced ecrt_slave_pdo_mapping/add/clear() with
 *   ecrt_slave_config_pdo_assign_add() to add a Pdo to a sync manager's Pdo
 *   assignment and ecrt_slave_config_pdo_mapping_add() to add a Pdo entry to a
 *   Pdo's mapping. ecrt_slave_config_pdos() is a convenience function
 *   for both, that uses the new data types ec_pdo_info_t and
 *   information, if the process data was exchanged completely.
 * - Former "Pdo registration" meant Pdo entry registration in fact, therefore
 *   renamed ec_pdo_reg_t to ec_pdo_entry_reg_t and ecrt_domain_register_pdo()
 *   to ecrt_slave_config_reg_pdo_entry().
 * - Removed ecrt_domain_register_pdo_range(), because it's functionality can
-*   be reached by specifying an explicit Pdo mapping and registering those
+*   be reached by specifying an explicit Pdo assignment/mapping and
-*   Pdo entries.
+*   registering the mapped Pdo entries.
 * - Added an Sdo access interface, working with Sdo requests. These can be
 *   scheduled for reading and writing during realtime operation.
 * - Exported ecrt_slave_config_sdo(), the generic Sdo configuration function.
 * - Removed the bus_state and bus_tainted flags from ec_master_state_t.
 *
 */
 #define ECRT_VERSION_MAGIC ECRT_VERSION(ECRT_VER_MAJOR, ECRT_VER_MINOR)
 /*****************************************************************************/
-/** End of the Pdo list.
+/** End of the Pdo entry list.
 *
 * This is used in ecrt_slave_config_pdos().
 */
 #define EC_END ~0U
 /** Domain working counter interpretation.
 *
 * This is used in ec_domain_state_t.
 */
 typedef enum {
-EC_WC_ZERO = 0,   /**< No Pdos were exchanged. */
+EC_WC_ZERO = 0,   /**< No registered process data were exchanged. */
-EC_WC_INCOMPLETE, /**< Some of the registered Pdos were exchanged. */
+EC_WC_INCOMPLETE, /**< Some of the registered process data were
-EC_WC_COMPLETE    /**< All registered Pdos were exchanged. */
+exchanged. */
+EC_WC_COMPLETE    /**< All registered process data were exchanged. */
 } ec_wc_state_t;
 /*****************************************************************************/
 /** Domain state.
 ec_wc_state_t wc_state; /**< Working counter interpretation. */
 } ec_domain_state_t;
 /*****************************************************************************/
-/** Direction type for Pdo mapping functions.
+/** Direction type for Pdo assignment functions.
 */
 typedef enum {
 EC_DIR_OUTPUT, /**< Values written by the master. */
 EC_DIR_INPUT   /**< Values read by the master. */
 } ec_direction_t;
 * This can be used to map multiple Pdo entries into a given Pdo using
 * ecrt_slave_config_pdos().
 */
 typedef struct {
 uint16_t index; /**< Index of the Pdo entry to add to the Pdo
-configuration. */
+mapping. */
-uint8_t subindex; /**< Subindex of the Pdo entry to add to the
+uint8_t subindex; /**< Subindex of the Pdo entry. */
-Pdo configuration. */
 uint8_t bit_length; /**< Size of the Pdo entry in bit. */
 } ec_pdo_entry_info_t;
 /*****************************************************************************/
 * This can be use to assign multiple Pdos to a sync manager using
 * ecrt_slave_config_pdos().
 */
 typedef struct {
 ec_direction_t dir; /**< Pdo direction (input/output). */
-uint16_t index; /**< Index of the Pdo to map. */
+uint16_t index; /**< Index of the Pdo to assign. */
 unsigned int n_entries; /**< Number of Pdo entries in \a entries to map.
 Zero means, that the default mapping shall be
-used. */
+used (this can only be done if the slave is
+present at bus configuration time). */
 ec_pdo_entry_info_t *entries; /**< Array of Pdo entries to map. This must
 contain at least \a n_entries values. */
 } ec_pdo_info_t;
 /*****************************************************************************/
 uint16_t position; /**< Slave position. */
 uint32_t vendor_id; /**< Slave vendor ID. */
 uint32_t product_code; /**< Slave product code. */
 uint16_t index; /**< Pdo entry index. */
 uint8_t subindex; /**< Pdo entry subindex. */
-unsigned int *offset; /**< Pointer to a variable to store the Pdo's
+unsigned int *offset; /**< Pointer to a variable to store the Pdo entry's
-offset in the process data. This can either be byte-
+(byte-)offset in the process data. */
-or bitwise, depending on whether
+unsigned int *bit_position; /** Pointer to a variable to store a bit
-ecrt_domain_reg_pdo_entry_list() */
+position (0-7) within the \a offset. Can be
-unsigned int *bitposition; /** Pointer to variable to store a bit
+NULL, in which case an error is raised if the
-position within the address. Can be NULL,
+Pdo entry does not byte-align. */
-in which case an error is raised if the
-PDO does not byte-align. */
 } ec_pdo_entry_reg_t;
 /*****************************************************************************/
 /** Sdo request state.
 uint32_t product_code /**< Expected product code. */
 );
 /** Finishes the configuration phase and prepares for realtime mode.
 *
-* This function has to be called after all Pdo entries are registered. It
+* This function tells the master that the configuration phase is finished and
-* tells the master that the configuration phase is finished and the realtime
+* the realtime operation will begin. The function allocates internal memory
-* operation will begin. The function allocates internal memory for the
+* for the domains and calculates the logical FMMU addresses for domain
-* domains and calculates the logical FMMU addresses for domain members. It
+* members. It tells the master state machine that the bus configuration is
-* tells the master state machine that the bus configuration is now to be
+* now to be applied.
-* applied.
 *
 * \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
 const ec_pdo_info_t pdo_infos[] /**< List with Pdos. */
 );
 /** Registers a Pdo entry for process data exchange in a domain.
 *
-* Searches the current Pdo assignment and Pdo mappings for the given Pdo
+* Searches the assigned Pdos for the given Pdo entry. An error is raised, if
-* entry. An error is raised, if the given entry is not mapped. Otherwise, the
+* the given entry is not mapped. Otherwise, the corresponding sync manager
-* corresponding sync manager and FMMU configurations are provided for slave
+* and FMMU configurations are provided for slave configuration and the
-* configuration and the respective sync manager's assigned Pdos are appended
+* respective sync manager's assigned Pdos are appended to the given domain,
-* to the given domain, if not already done. The offset of the requested Pdo
+* if not already done. The offset of the requested Pdo entry's data inside
-* entry's data inside the domain's process data is returned. Optionally, the
+* the domain's process data is returned. Optionally, the Pdo entry bit
-* Pdo entry bit position can be retrieved if a non-null pointer is passed
+* position (0-7) can be retrieved via the \a bit_position output parameter.
-* to the \a bitposition parameter. If this is null, an error is raised if
+* This pointer may be \a NULL, in this case an error is raised if the Pdo
-* the Pdo entry does not byte align.
+* entry does not byte-align.
 *
 * \retval >=0 Success: Offset of the Pdo entry's process data.
 * \retval -1  Error: Pdo entry not found.
 * \retval -2  Error: Failed to register Pdo entry.
 * \retval -3  Error: Pdo entry is not byte-aligned.
 int ecrt_slave_config_reg_pdo_entry(
 ec_slave_config_t *sc, /**< Slave configuration. */
 uint16_t entry_index, /**< Index of the Pdo entry to register. */
 uint8_t entry_subindex, /**< Subindex of the Pdo entry to register. */
 ec_domain_t *domain, /**< Domain. */
-unsigned int *bitposition /**< Optional address if bit addressing
+unsigned int *bit_position /**< Optional address if bit addressing
 is desired */
 );
 /** Add an Sdo configuration.
 *

changeset 925	939f3e9bba1e
parent 923	a6b51990e7e6
child 1007	b6c3527697c3