/******************************************************************************
*
* $Id$
*
* Copyright (C) 2006 Florian Pose, Ingenieurgemeinschaft IgH
*
* This file is part of the IgH EtherCAT Master.
*
* The IgH EtherCAT Master is free software; you can redistribute it
* and/or modify it under the terms of the GNU General Public License
* as published by the Free Software Foundation; either version 2 of the
* License, or (at your option) any later version.
*
* The IgH EtherCAT Master is distributed in the hope that it will be
* useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with the IgH EtherCAT Master; if not, write to the Free Software
* Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
*
* The right to use EtherCAT Technology is granted and comes free of
* charge under condition of compatibility of product made by
* Licensee. People intending to distribute/sell products based on the
* code, have to sign an agreement to guarantee that products using
* software based on IgH EtherCAT master stay compatible with the actual
* EtherCAT specification (which are released themselves as an open
* standard) as the (only) precondition to have the right to use EtherCAT
* Technology, IP and trade marks.
*
*****************************************************************************/
/** \file
*
* EtherCAT Real-Time Interface.
*
* \defgroup RealtimeInterface EtherCAT Real-Time 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.
*
* Changes in Version 1.4:
*
* - Replaced ec_slave_t with ec_slave_config_t, separating the slave objects
* from the requested bus configuration. Therefore, renamed
* ecrt_master_get_slave() to ecrt_master_slave_config().
* - Replaced slave address string with alias and position values. See
* ecrt_master_slave_config().
* - Removed ecrt_master_get_slave_by_pos(), because it is no longer
* necessary due to alias/position addressing.
* - Added ec_slave_config_state_t for the new method
* 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().
* - Replaced the process data pointers in the Pdo entry registration
* functions with a process data offset, that is now returned by
* ecrt_slave_config_reg_pdo_entry(). This was necessary for the external
* domain memory. An additional advantage is, that the returned offset value
* 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.
* - 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.
* - Added ec_domain_state_t and ec_wc_state_t for a new output parameter
* of ecrt_domain_state(). The domain state object does now contain
* 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
* Pdo entries.
*
* @{
*/
/*****************************************************************************/
#ifndef __ECRT_H__
#define __ECRT_H__
#include <asm/byteorder.h>
#ifdef __KERNEL__
#include <linux/types.h>
#else
#include <stdint.h>
#endif
/******************************************************************************
* Global definitions
*****************************************************************************/
/** EtherCAT real-time interface major version number.
*/
#define ECRT_VER_MAJOR 1
/** EtherCAT real-time interface minor version number.
*/
#define ECRT_VER_MINOR 4
/** EtherCAT real-time interface version word generator.
*/
#define ECRT_VERSION(a, b) (((a) << 8) + (b))
/** EtherCAT real-time interface version word.
*/
#define ECRT_VERSION_MAGIC ECRT_VERSION(ECRT_VER_MAJOR, ECRT_VER_MINOR)
/******************************************************************************
* Data types
*****************************************************************************/
struct ec_master;
typedef struct ec_master ec_master_t; /**< \see ec_master */
struct ec_slave_config;
typedef struct ec_slave_config ec_slave_config_t; /**< \see ec_slave_config */
struct ec_domain;
typedef struct ec_domain ec_domain_t; /**< \see ec_domain */
/*****************************************************************************/
/** Bus state.
*
* This is used in ec_master_state_t.
*/
typedef enum {
EC_BUS_FAILURE = -1, /**< At least one configured slave is offline. */
EC_BUS_OK /**< All configured slaves are online. */
} ec_bus_state_t;
/*****************************************************************************/
/** Master state.
*
* This is used for the output parameter of ecrt_master_state().
*/
typedef struct {
ec_bus_state_t bus_state; /**< \see ec_bus_state_t */
unsigned int bus_tainted; /**< Non-zero, if the bus topology differs from
the requested configuration. */
unsigned int slaves_responding; /**< Number of slaves in the bus. */
} ec_master_state_t;
/*****************************************************************************/
/** Slave configuration state.
*
* \see ecrt_slave_config_state().
*/
typedef struct {
unsigned int online : 1; /**< The slave is online. */
unsigned int configured : 1; /**< The slave was configured according to
the specified configuration. */
} ec_slave_config_state_t;
/*****************************************************************************/
/** Domain working counter interpretation.
*
* This is used in ec_domain_state_t.
*/
typedef enum {
EC_WC_ZERO = 0, /**< No Pdos were exchanged. */
EC_WC_INCOMPLETE, /**< Some of the registered Pdos were exchanged. */
EC_WC_COMPLETE /**< All registered Pdos were exchanged. */
} ec_wc_state_t;
/*****************************************************************************/
/** Domain state.
*
* This is used for the output parameter of ecrt_domain_state().
*/
typedef struct {
unsigned int working_counter; /**< Value of the last working counter. */
ec_wc_state_t wc_state; /**< Working counter interpretation. */
} ec_domain_state_t;
/*****************************************************************************/
/** Direction type for Pdo mapping functions.
*/
typedef enum {
EC_DIR_OUTPUT, /**< Values written by the master. */
EC_DIR_INPUT /**< Values read by the master. */
} ec_direction_t;
/*****************************************************************************/
/** Pdo entry mapping.
*
* \see ecrt_slave_config_mapping().
*/
typedef struct {
uint16_t index; /**< Index of the Pdo entry to add to the Pdo
configuration. */
uint8_t subindex; /**< Subindex of the Pdo entry to add to the
Pdo configuration. */
uint8_t bit_length; /**< Size of the Pdo entry in bit. */
} ec_pdo_entry_info_t;
/*****************************************************************************/
/** Pdo information.
*
* \see ecrt_slave_config_mapping().
*/
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. */
const ec_pdo_entry_info_t *entries; /**< Pdo configuration array. This
array must contain at least \a
n_entries values. */
} ec_pdo_info_t;
/*****************************************************************************/
/** List record type for Pdo entry mass-registration.
*
* This type is used for the array parameter of the
* ecrt_domain_reg_pdo_entry_list() convenience function.
*/
typedef struct {
uint16_t alias; /**< Slave alias address. */
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
offset in the process data. */
} ec_pdo_entry_reg_t;
/******************************************************************************
* Global functions
*****************************************************************************/
/** Returns the version magic of the realtime interface.
*
* \return Value of ECRT_VERSION_MAGIC() at EtherCAT master compile time.
*/
unsigned int ecrt_version_magic(void);
/** Requests an EtherCAT master for realtime operation.
*
* \return pointer to reserved master, or NULL on error
*/
ec_master_t *ecrt_request_master(
unsigned int master_index /**< Index of the master to request. */
);
/** Releases a requested EtherCAT master.
*/
void ecrt_release_master(
ec_master_t *master /**< EtherCAT master */
);
/******************************************************************************
* Master methods
*****************************************************************************/
/** Sets the locking callbacks.
*
* The request_cb function must return zero, to allow another instance
* (the EoE process for example) to access the master. Non-zero means,
* that access is forbidden at this time.
*/
void ecrt_master_callbacks(
ec_master_t *master, /**< EtherCAT master */
int (*request_cb)(void *), /**< Lock request function. */
void (*release_cb)(void *), /**< Lock release function. */
void *cb_data /**< Arbitrary user data. */
);
/** Creates a new domain.
*
* \return Pointer to the new domain on success, else NULL.
*/
ec_domain_t *ecrt_master_create_domain(
ec_master_t *master /**< EtherCAT master. */
);
/** Obtains a slave configuration.
*
* Creates a slave configuration object for the given \a alias and \a position
* tuple and returns it. If a configuration with the same \a alias and \a
* position already exists, it will be re-used. In the latter case, the given
* vendor ID and product code are compared to the stored ones. On mismatch, an
* error message is raised and the function returns \a NULL.
*
* Slaves are addressed with the \a alias and \a position parameters.
* - If \a alias is zero, \a position is interpreted as the desired slave's
* ring position.
* - If \a alias is non-zero, it matches a slave with the given alias. In this
* case, \a position is interpreted as ring offset, starting from the
* aliased slave, so a position of zero means the aliased slave itself and a
* positive value matches the n-th slave behind the aliased one.
*
* If the slave with the given address is found during the bus configuration,
* its vendor ID and product code are matched against the given value. On
* 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.
*
* \retval >0 Pointer to the slave configuration structure.
* \retval NULL in the error case.
*/
ec_slave_config_t *ecrt_master_slave_config(
ec_master_t *master, /**< EtherCAT master */
uint16_t alias, /**< Slave alias. */
uint16_t position, /**< Slave position. */
uint32_t vendor_id, /**< Expected vendor ID. */
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.
*
* \return 0 in case of success, else < 0
*/
int ecrt_master_activate(
ec_master_t *master /**< EtherCAT master. */
);
/** Sends all datagrams in the queue.
*
* \todo doc
*/
void ecrt_master_send(
ec_master_t *master /**< EtherCAT master. */
);
/** Fetches received frames from the hardware and processes the datagrams.
*/
void ecrt_master_receive(
ec_master_t *master /**< EtherCAT master. */
);
/** Reads the current master state.
*
* Stores the master state information in the given \a state structure.
*/
void ecrt_master_state(
const ec_master_t *master, /**< EtherCAT master. */
ec_master_state_t *state /**< Structure to store the information. */
);
/******************************************************************************
* 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()
* \return zero on success, else non-zero
*/
int ecrt_slave_config_pdo(
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()
* \return zero on success, else non-zero
*/
int ecrt_slave_config_pdo_entry(
ec_slave_config_t *sc, /**< Slave configuration. */
uint16_t pdo_index, /**< Index of the Pdo to configure. */
uint16_t entry_index, /**< Index of the Pdo entry to add to the Pdo's
configuration. */
uint8_t entry_subindex, /**< Subindex of the Pdo entry to add to the
Pdo's configuration. */
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:
*
* \code
* const ec_pdo_entry_info_t el3162_channel1[] = {
* {0x3101, 1, 8}, // status
* {0x3101, 2, 16} // value
* };
*
* const ec_pdo_entry_info_t el3162_channel2[] = {
* {0x3102, 1, 8}, // status
* {0x3102, 2, 16} // value
* };
*
* const ec_pdo_info_t el3162_mapping[] = {
* {EC_DIR_INPUT, 0x1A00, 2, el3162_channel1},
* {EC_DIR_INPUT, 0x1A01, 2, el3162_channel2},
* };
*
* if (ecrt_slave_config_mapping(sc, 2, el3162_mapping))
* 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.
*
* \code
* const ec_pdo_info_t pdo_mapping[] = {
* {EC_DIR_INPUT, 0x1600}, // Channel 1
* {EC_DIR_INPUT, 0x1601} // Channel 2
* };
*
* if (ecrt_slave_config_mapping(slave_config_ana_in, 2, pdo_mapping))
* return -1; // error
* \endcode
*
* \return zero on success, else non-zero
*/
int ecrt_slave_config_mapping(
ec_slave_config_t *sc, /**< Slave configuration. */
unsigned int n_entries, /**< Number of Pdos in \a pdos to map. */
const ec_pdo_info_t pdos[] /**< List with Pdo mapping. */
);
/** Registers a Pdo entry for process data exchange in a domain.
*
* Searches the current mapping and Pdo configurations 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.
*
* \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.
*/
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. */
);
/** Add a configuration value for an 8-bit SDO.
*
* \todo doc
* \return 0 in case of success, else < 0
*/
int ecrt_slave_config_sdo8(
ec_slave_config_t *sc, /**< Slave configuration */
uint16_t sdo_index, /**< Index of the SDO to configure. */
uint8_t sdo_subindex, /**< Subindex of the SDO to configure. */
uint8_t value /**< Value to set. */
);
/** Add a configuration value for a 16-bit SDO.
*
* \todo doc
* \return 0 in case of success, else < 0
*/
int ecrt_slave_config_sdo16(
ec_slave_config_t *sc, /**< Slave configuration */
uint16_t sdo_index, /**< Index of the SDO to configure. */
uint8_t sdo_subindex, /**< Subindex of the SDO to configure. */
uint16_t value /**< Value to set. */
);
/** Add a configuration value for a 32-bit SDO.
*
* \todo doc
* \return 0 in case of success, else < 0
*/
int ecrt_slave_config_sdo32(
ec_slave_config_t *sc, /**< Slave configuration */
uint16_t sdo_index, /**< Index of the SDO to configure. */
uint8_t sdo_subindex, /**< Subindex of the SDO to configure. */
uint32_t value /**< Value to set. */
);
/** Outputs the state of the slave configuration.
*
* Stores the state information in the given \a state structure.
*/
void ecrt_slave_config_state(
const ec_slave_config_t *sc, /**< Slave configuration */
ec_slave_config_state_t *state /**< State object to write to. */
);
/******************************************************************************
* Domain methods
*****************************************************************************/
/** Registers a bunch of Pdo entries for a domain.
*
* \todo doc
* \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(
ec_domain_t *domain, /**< Domain. */
const ec_pdo_entry_reg_t *pdo_entry_regs /**< Array of Pdo
registrations. */
);
/** Returns the current size of the domain's process data.
*
* \return Size of the process data image.
*/
size_t ecrt_domain_size(
ec_domain_t *domain /**< Domain. */
);
/** Provide external memory to store the domain's process data.
*
* 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.
*/
void ecrt_domain_external_memory(
ec_domain_t *domain, /**< Domain. */
uint8_t *memory /**< Address of the memory to store the process
data in. */
);
/** Returns the domain's process data.
*
* If external memory was provided with ecrt_domain_external_memory(), the
* returned pointer will contain the address of that memory. Otherwise it will
* point to the internally allocated memory.
*
* \return Pointer to the process data memory.
*/
uint8_t *ecrt_domain_data(
ec_domain_t *domain /**< Domain. */
);
/** Processes received datagrams.
*
* \todo doc
*/
void ecrt_domain_process(
ec_domain_t *domain /**< Domain. */
);
/** (Re-)queues all domain datagrams in the master's datagram queue.
*
* \todo doc
*/
void ecrt_domain_queue(
ec_domain_t *domain /**< Domain. */
);
/** Reads the state of a domain.
*
* Stores the domain state in the giveb \a state structure.
*/
void ecrt_domain_state(
const ec_domain_t *domain, /**< Domain. */
ec_domain_state_t *state /**< Pointer to a state object to store the
information. */
);
/******************************************************************************
* Bitwise read/write macros
*****************************************************************************/
/** Read a certain bit of an EtherCAT data byte.
* \param DATA EtherCAT data pointer
* \param POS bit position
*/
#define EC_READ_BIT(DATA, POS) ((*((uint8_t *) (DATA)) >> (POS)) & 0x01)
/** Write a certain bit of an EtherCAT data byte.
* \param DATA EtherCAT data pointer
* \param POS bit position
* \param VAL new bit value
*/
#define EC_WRITE_BIT(DATA, POS, VAL) \
do { \
if (VAL) *((uint8_t *) (DATA)) |= (1 << (POS)); \
else *((uint8_t *) (DATA)) &= ~(1 << (POS)); \
} while (0)
/******************************************************************************
* Read macros
*****************************************************************************/
/** Read an 8-bit unsigned value from EtherCAT data.
* \return EtherCAT data value
*/
#define EC_READ_U8(DATA) \
((uint8_t) *((uint8_t *) (DATA)))
/** Read an 8-bit signed value from EtherCAT data.
* \param DATA EtherCAT data pointer
* \return EtherCAT data value
*/
#define EC_READ_S8(DATA) \
((int8_t) *((uint8_t *) (DATA)))
/** Read a 16-bit unsigned value from EtherCAT data.
* \param DATA EtherCAT data pointer
* \return EtherCAT data value
*/
#define EC_READ_U16(DATA) \
((uint16_t) le16_to_cpup((void *) (DATA)))
/** Read a 16-bit signed value from EtherCAT data.
* \param DATA EtherCAT data pointer
* \return EtherCAT data value
*/
#define EC_READ_S16(DATA) \
((int16_t) le16_to_cpup((void *) (DATA)))
/** Read a 32-bit unsigned value from EtherCAT data.
* \param DATA EtherCAT data pointer
* \return EtherCAT data value
*/
#define EC_READ_U32(DATA) \
((uint32_t) le32_to_cpup((void *) (DATA)))
/** Read a 32-bit signed value from EtherCAT data.
* \param DATA EtherCAT data pointer
* \return EtherCAT data value
*/
#define EC_READ_S32(DATA) \
((int32_t) le32_to_cpup((void *) (DATA)))
/******************************************************************************
* Write macros
*****************************************************************************/
/** Write an 8-bit unsigned value to EtherCAT data.
* \param DATA EtherCAT data pointer
* \param VAL new value
*/
#define EC_WRITE_U8(DATA, VAL) \
do { \
*((uint8_t *)(DATA)) = ((uint8_t) (VAL)); \
} while (0)
/** Write an 8-bit signed value to EtherCAT data.
* \param DATA EtherCAT data pointer
* \param VAL new value
*/
#define EC_WRITE_S8(DATA, VAL) EC_WRITE_U8(DATA, VAL)
/** Write a 16-bit unsigned value to EtherCAT data.
* \param DATA EtherCAT data pointer
* \param VAL new value
*/
#define EC_WRITE_U16(DATA, VAL) \
do { \
*((uint16_t *) (DATA)) = (uint16_t) (VAL); \
cpu_to_le16s((uint16_t *) (DATA)); \
} while (0)
/** Write a 16-bit signed value to EtherCAT data.
* \param DATA EtherCAT data pointer
* \param VAL new value
*/
#define EC_WRITE_S16(DATA, VAL) EC_WRITE_U16(DATA, VAL)
/** Write a 32-bit unsigned value to EtherCAT data.
* \param DATA EtherCAT data pointer
* \param VAL new value
*/
#define EC_WRITE_U32(DATA, VAL) \
do { \
*((uint32_t *) (DATA)) = (uint32_t) (VAL); \
cpu_to_le32s((uint32_t *) (DATA)); \
} while (0)
/** Write a 32-bit signed value to EtherCAT data.
* \param DATA EtherCAT data pointer
* \param VAL new value
*/
#define EC_WRITE_S32(DATA, VAL) EC_WRITE_U32(DATA, VAL)
/*****************************************************************************/
/** @} */
#endif