--- a/include/ecrt.h Mon Mar 31 09:42:37 2008 +0000
+++ b/include/ecrt.h Thu Apr 03 13:34:13 2008 +0000
@@ -37,10 +37,10 @@
*
* \defgroup RealtimeInterface EtherCAT Realtime Interface
*
- * EtherCAT interface for realtime modules. This interface is designed for
- * realtime modules that want to use EtherCAT. There are functions to request
- * a master, to map process data, to communicate with slaves via CoE and to
- * configure and activate the bus.
+ * EtherCAT interface for realtime applications. This interface is designed
+ * for realtime modules that want to use EtherCAT. There are functions to
+ * request a master, to map process data, to communicate with slaves via CoE
+ * and to configure and activate the bus.
*
* Changes in Version 1.4:
*
@@ -64,11 +64,12 @@
* is directly usable. If the domain's process data is allocated internally,
* the start address can be retrieved with ecrt_domain_data().
* - Replaced ecrt_slave_pdo_mapping/add/clear() with
- * ecrt_slave_config_pdo() to add a Pdo to the mapping and
- * ecrt_slave_config_pdo_entry() to add a Pdo entry to a Pdo configuration.
- * ecrt_slave_config_mapping() is a convenience function for
- * both, that uses the new data types ec_pdo_info_t and ec_pdo_entry_info_t.
- * Mapped Pdo entries can now immediately be registered.
+ * 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
+ * ec_pdo_entry_info_t. Pdo entries, that are mapped with these functions
+ * can now immediately be registered, even if the bus is offline.
* - Renamed ec_bus_status_t, ec_master_status_t to ec_bus_state_t and
* ec_master_state_t, respectively. Renamed ecrt_master_get_status() to
* ecrt_master_state(), for consistency reasons.
@@ -122,11 +123,11 @@
/*****************************************************************************/
-/** End of mapping.
- *
- * This is used in ecrt_slave_config_mapping().
- */
-#define EC_MAP_END ~0U
+/** End of the Pdo list.
+ *
+ * This is used in ecrt_slave_config_pdos().
+ */
+#define EC_END ~0U
/******************************************************************************
* Data types
@@ -149,6 +150,9 @@
/** Bus state.
*
* This is used in ec_master_state_t.
+ *
+ * \deprecated
+ * \todo remove
*/
typedef enum {
EC_BUS_FAILURE = -1, /**< At least one configured slave is offline. */
@@ -214,9 +218,10 @@
/*****************************************************************************/
-/** Pdo entry mapping.
- *
- * \see ecrt_slave_config_mapping().
+/** Pdo entry information.
+ *
+ * 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
@@ -230,17 +235,17 @@
/** Pdo information.
*
- * \see ecrt_slave_config_mapping().
+ * 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. */
- unsigned int n_entries; /**< Number of Pdo entries for the Pdo
- configuration. Zero means, that the default Pdo
- configuration shall be used. */
- ec_pdo_entry_info_t *entries; /**< Pdo configuration array. This
- array must contain at least \a
- n_entries values. */
+ unsigned int n_entries; /**< Number of Pdo entries in \a entries to map.
+ Zero means, that the default mapping shall be
+ used. */
+ 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;
/*****************************************************************************/
@@ -358,27 +363,38 @@
uint32_t product_code /**< Expected product code. */
);
-/** Applies the bus configuration and switches to realtime mode.
- *
- * Does the complete configuration and activation for all slaves. Sets sync
- * managers and FMMUs, and does the appropriate transitions, until the slave
- * is operational.
+/** Finishes the configuration phase and prepares for realtime mode.
+ *
+ * This function has to be called after all Pdo entries are registered. It
+ * tells the master that the configuration phase is finished and the realtime
+ * operation will begin. The function allocates internal memory for the
+ * domains and calculates the logical FMMU addresses for domain members. It
+ * tells the master state machine that the bus configuration is now to be
+ * 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
+ * not be called!
*
* \return 0 in case of success, else < 0
*/
-int ecrt_master_activate(
- ec_master_t *master /**< EtherCAT master. */
- );
+int ecrt_master_activate( ec_master_t *master /**< EtherCAT master. */);
/** Sends all datagrams in the queue.
*
- * \todo doc
+ * This has to be called cyclically by the realtime application after
+ * ecrt_master_activate() has returned.
*/
void ecrt_master_send(
ec_master_t *master /**< EtherCAT master. */
);
/** Fetches received frames from the hardware and processes the datagrams.
+ *
+ * This has to be called cyclically by the realtime application after
+ * ecrt_master_activate() has returned.
*/
void ecrt_master_receive(
ec_master_t *master /**< EtherCAT master. */
@@ -397,48 +413,64 @@
* Slave configuration methods
*****************************************************************************/
-/** Add a Pdo to the slave's Pdo mapping for the given direction.
- *
- * The first call of this function for a given \a dir will clear the default
- * mapping.
- *
- * \see ecrt_slave_config_mapping()
+/** Add a Pdo to a sync manager's Pdo assignment.
+ *
+ * \see ecrt_slave_config_pdos()
* \return zero on success, else non-zero
*/
-int ecrt_slave_config_pdo(
+int ecrt_slave_config_pdo_assign_add(
ec_slave_config_t *sc, /**< Slave configuration. */
- ec_direction_t dir, /**< Pdo direction (input/output). */
- uint16_t index /**< Index of the Pdo to map. */
- );
-
-/** Add a Pdo entry to the given Pdo's configuration.
- *
- * The first call of this function for a given \a pdo_index will clear the
- * default Pdo configuration.
- *
- * \see ecrt_slave_config_mapping()
+ ec_direction_t dir, /**< Sync manager direction (input/output). */
+ uint16_t index /**< Index of the Pdo to assign. */
+ );
+
+/** Clear a sync manager's Pdo assignment.
+ *
+ * This can be called before assigning Pdos via
+ * ecrt_slave_config_pdo_assign_add(), to clear the default assignment.
+ */
+void ecrt_slave_config_pdo_assign_clear(
+ ec_slave_config_t *sc, /**< Slave configuration. */
+ ec_direction_t dir /**< Sync manager direction (input/output). */
+ );
+
+/** Add a Pdo entry to the given Pdo's mapping.
+ *
+ * \see ecrt_slave_config_pdos()
* \return zero on success, else non-zero
*/
-int ecrt_slave_config_pdo_entry(
+int ecrt_slave_config_pdo_mapping_add(
ec_slave_config_t *sc, /**< Slave configuration. */
- uint16_t pdo_index, /**< Index of the Pdo to configure. */
+ uint16_t pdo_index, /**< Index of the Pdo. */
uint16_t entry_index, /**< Index of the Pdo entry to add to the Pdo's
- configuration. */
+ mapping. */
uint8_t entry_subindex, /**< Subindex of the Pdo entry to add to the
- Pdo's configuration. */
+ Pdo's mapping. */
uint8_t entry_bit_length /**< Size of the Pdo entry in bit. */
);
-/** Specify the Pdo mapping and (optionally) the Pdo configuration.
- *
- * This function is a convenience function for the ecrt_slave_config_pdo()
- * and ecrt_slave_config_pdo_entry() functions, that are better suitable
- * for automatic code generation.
- *
- * The following example shows, how to specify a complete Pdo mapping
- * including the Pdo configuration. With this information, the master is able
- * to reserve the complete process data, even if the slave is not present
- * at configuration time:
+/** 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.
+ */
+void ecrt_slave_config_pdo_mapping_clear(
+ ec_slave_config_t *sc, /**< Slave configuration. */
+ uint16_t pdo_index /**< Index of the Pdo. */
+ );
+
+/** Specify the Pdo assignment and (optionally) the Pdo mappings.
+ *
+ * This function is a convenience wrapper for the functions
+ * ecrt_slave_config_pdo_assign_clear(), ecrt_slave_config_pdo_assign_add(),
+ * ecrt_slave_config_pdo_mapping_clear() and
+ * ecrt_slave_config_pdo_mapping_add(), that are better suitable for automatic
+ * code generation.
+ *
+ * The following example shows, how to specify a complete Pdo assignment
+ * including the Pdo mappings. With this information, the master is able to
+ * reserve the complete process data, even if the slave is not present at
+ * configuration time:
*
* \code
* const ec_pdo_entry_info_t el3162_channel1[] = {
@@ -451,52 +483,52 @@
* {0x3102, 2, 16} // value
* };
*
- * const ec_pdo_info_t el3162_mapping[] = {
+ * const ec_pdo_info_t el3162_pdos[] = {
* {EC_DIR_INPUT, 0x1A00, 2, el3162_channel1},
* {EC_DIR_INPUT, 0x1A01, 2, el3162_channel2},
* };
*
- * if (ecrt_slave_config_mapping(sc, 2, el3162_mapping))
+ * if (ecrt_slave_config_pdos(sc, 2, el3162_pdos))
* return -1; // error
* \endcode
- *
- * The next example shows, how to configure only the Pdo mapping. The entries
- * for each mapped Pdo are taken from the default Pdo configuration. Please
- * note, that Pdo entry registration will fail, if the Pdo configuration is
- * left empty and the slave is offline.
+ *
+ * The next example shows, how to configure only the Pdo assignment. The
+ * entries for each assigned Pdo are taken from the Pdo's default mapping.
+ * Please note, that Pdo entry registration will fail, if the Pdo
+ * configuration is left empty and the slave is offline.
*
* \code
- * const ec_pdo_info_t pdo_mapping[] = {
+ * const ec_pdo_info_t pdos[] = {
* {EC_DIR_INPUT, 0x1600}, // Channel 1
* {EC_DIR_INPUT, 0x1601} // Channel 2
* };
*
- * if (ecrt_slave_config_mapping(slave_config_ana_in, 2, pdo_mapping))
+ * if (ecrt_slave_config_pdos(slave_config_ana_in, 2, pdos))
* return -1; // error
* \endcode
*
* Processing of \a pdo_infos will stop, if
* - the number of processed items reaches \a n_infos, or
- * - the \a dir member of an ec_pdo_info_t item is EC_MAP_END. In this case,
+ * - the \a dir member of an ec_pdo_info_t item is EC_END. In this case,
* \a n_infos should set to a number greater than the number of list items;
- * using EC_MAP_END is recommended.
+ * using EC_END is recommended.
*
* \return zero on success, else non-zero
*/
-int ecrt_slave_config_mapping(
+int ecrt_slave_config_pdos(
ec_slave_config_t *sc, /**< Slave configuration. */
unsigned int n_infos, /**< Number of Pdo infos in \a pdo_infos. */
- const ec_pdo_info_t pdo_infos[] /**< List with Pdo mapping. */
+ const ec_pdo_info_t pdo_infos[] /**< List with Pdos. */
);
/** Registers a Pdo entry for process data exchange in a domain.
*
- * Searches the current mapping and Pdo configurations for the given Pdo
+ * Searches the current Pdo assignment and Pdo mappings for the given Pdo
* entry. An error is raised, if the given entry is not mapped. Otherwise, the
* corresponding sync manager and FMMU configurations are provided for slave
- * configuration and the respective sync manager's Pdos are appended to the
- * given domain, if not already done. The offset of the requested Pdo entry's
- * data inside the domain's process data is returned.
+ * configuration and the respective sync manager's assigned Pdos are appended
+ * to the given domain, if not already done. The offset of the requested Pdo
+ * entry's data inside the domain's process data is returned.
*
* \retval >=0 Success: Offset of the Pdo entry's process data.
* \retval -1 Error: Pdo entry not found.