ecrt.h File Reference

EtherCAT master application interface. More...

Go to the source code of this file.

Data Structures
struct	ec_master_state_t
	Master state. More...
struct	ec_master_link_state_t
	Redundant link state. More...
struct	ec_slave_config_state_t
	Slave configuration state. More...
struct	ec_master_info_t
	Master information. More...
struct	ec_slave_port_link_t
	EtherCAT slave port information. More...
struct	ec_slave_info_t
	Slave information. More...
struct	ec_domain_state_t
	Domain state. More...
struct	ec_pdo_entry_info_t
	PDO entry configuration information. More...
struct	ec_pdo_info_t
	PDO configuration information. More...
struct	ec_sync_info_t
	Sync manager configuration information. More...
struct	ec_pdo_entry_reg_t
	List record type for PDO entry mass-registration. More...
Defines
#define	ECRT_VER_MAJOR   1
	EtherCAT realtime interface major version number.
#define	ECRT_VER_MINOR   5
	EtherCAT realtime interface minor version number.
#define	ECRT_VERSION(a, b)   (((a) << 8) + (b))
	EtherCAT realtime interface version word generator.
#define	ECRT_VERSION_MAGIC   ECRT_VERSION(ECRT_VER_MAJOR, ECRT_VER_MINOR)
	EtherCAT realtime interface version word.
#define	EC_HAVE_REDUNDANCY
	Defined, if the redundancy features are available.
#define	EC_HAVE_EMERGENCY
	Defined, if the CoE emergency ring feature is available.
#define	EC_HAVE_REG_ACCESS
	Defined, if the register access interface is available.
#define	EC_HAVE_SELECT_REF_CLOCK
	Defined if the method ecrt_master_select_reference_clock() is available.
#define	EC_HAVE_REF_CLOCK_TIME
	Defined if the method ecrt_master_reference_clock_time() is available.
#define	EC_HAVE_REG_BY_POS
	Defined if the method ecrt_slave_config_reg_pdo_entry_pos() is available.
#define	EC_END   ~0U
	End of list marker.
#define	EC_MAX_SYNC_MANAGERS   16
	Maximum number of sync managers per slave.
#define	EC_MAX_STRING_LENGTH   64
	Maximum string length.
#define	EC_MAX_PORTS   4
	Maximum number of slave ports.
#define	EC_TIMEVAL2NANO(TV)   (((TV).tv_sec - 946684800ULL) * 1000000000ULL + (TV).tv_usec * 1000ULL)
	Timeval to nanoseconds conversion.
#define	EC_COE_EMERGENCY_MSG_SIZE   8
	Size of a CoE emergency message in byte.
#define	EC_READ_BIT(DATA, POS)   ((*((uint8_t *) (DATA)) >> (POS)) & 0x01)
	Read a certain bit of an EtherCAT data byte.
#define	EC_WRITE_BIT(DATA, POS, VAL)
	Write a certain bit of an EtherCAT data byte.
#define	EC_READ_U8(DATA)   ((uint8_t) *((uint8_t *) (DATA)))
	Read an 8-bit unsigned value from EtherCAT data.
#define	EC_READ_S8(DATA)   ((int8_t) *((uint8_t *) (DATA)))
	Read an 8-bit signed value from EtherCAT data.
#define	EC_READ_U16(DATA)   ((uint16_t) le16_to_cpup((void *) (DATA)))
	Read a 16-bit unsigned value from EtherCAT data.
#define	EC_READ_S16(DATA)   ((int16_t) le16_to_cpup((void *) (DATA)))
	Read a 16-bit signed value from EtherCAT data.
#define	EC_READ_U32(DATA)   ((uint32_t) le32_to_cpup((void *) (DATA)))
	Read a 32-bit unsigned value from EtherCAT data.
#define	EC_READ_S32(DATA)   ((int32_t) le32_to_cpup((void *) (DATA)))
	Read a 32-bit signed value from EtherCAT data.
#define	EC_READ_U64(DATA)   ((uint64_t) le64_to_cpup((void *) (DATA)))
	Read a 64-bit unsigned value from EtherCAT data.
#define	EC_READ_S64(DATA)   ((int64_t) le64_to_cpup((void *) (DATA)))
	Read a 64-bit signed value from EtherCAT data.
#define	EC_WRITE_U8(DATA, VAL)
	Write an 8-bit unsigned value to EtherCAT data.
#define	EC_WRITE_S8(DATA, VAL)   EC_WRITE_U8(DATA, VAL)
	Write an 8-bit signed value to EtherCAT data.
#define	EC_WRITE_U16(DATA, VAL)
	Write a 16-bit unsigned value to EtherCAT data.
#define	EC_WRITE_S16(DATA, VAL)   EC_WRITE_U16(DATA, VAL)
	Write a 16-bit signed value to EtherCAT data.
#define	EC_WRITE_U32(DATA, VAL)
	Write a 32-bit unsigned value to EtherCAT data.
#define	EC_WRITE_S32(DATA, VAL)   EC_WRITE_U32(DATA, VAL)
	Write a 32-bit signed value to EtherCAT data.
#define	EC_WRITE_U64(DATA, VAL)
	Write a 64-bit unsigned value to EtherCAT data.
#define	EC_WRITE_S64(DATA, VAL)   EC_WRITE_U64(DATA, VAL)
	Write a 64-bit signed value to EtherCAT data.
Typedefs
typedef struct ec_master	ec_master_t
typedef struct ec_slave_config	ec_slave_config_t
typedef struct ec_domain	ec_domain_t
typedef struct ec_sdo_request	ec_sdo_request_t
typedef struct ec_voe_handler	ec_voe_handler_t
typedef struct ec_reg_request	ec_reg_request_t
Enumerations
enum	ec_slave_port_desc_t { EC_PORT_NOT_IMPLEMENTED, EC_PORT_NOT_CONFIGURED, EC_PORT_EBUS, EC_PORT_MII }
	EtherCAT slave port descriptor. More...
enum	ec_wc_state_t { EC_WC_ZERO = 0, EC_WC_INCOMPLETE, EC_WC_COMPLETE }
	Domain working counter interpretation. More...
enum	ec_direction_t { EC_DIR_INVALID, EC_DIR_OUTPUT, EC_DIR_INPUT, EC_DIR_COUNT }
	Direction type for PDO assignment functions. More...
enum	ec_watchdog_mode_t { EC_WD_DEFAULT, EC_WD_ENABLE, EC_WD_DISABLE }
	Watchdog mode for sync manager configuration. More...
enum	ec_request_state_t { EC_REQUEST_UNUSED, EC_REQUEST_BUSY, EC_REQUEST_SUCCESS, EC_REQUEST_ERROR }
	Request state. More...
enum	ec_al_state_t { EC_AL_STATE_INIT = 1, EC_AL_STATE_PREOP = 2, EC_AL_STATE_SAFEOP = 4, EC_AL_STATE_OP = 8 }
	Application-layer state. More...
Functions
unsigned int	ecrt_version_magic (void)
	Returns the version magic of the realtime interface.
ec_master_t *	ecrt_request_master (unsigned int master_index)
	Requests an EtherCAT master for realtime operation.
void	ecrt_release_master (ec_master_t *master)
	Releases a requested EtherCAT master.
void	ecrt_master_callbacks (ec_master_t *master, void(*send_cb)(void *), void(*receive_cb)(void *), void *cb_data)
	Sets the locking callbacks.
ec_domain_t *	ecrt_master_create_domain (ec_master_t *master)
	Creates a new process data domain.
ec_slave_config_t *	ecrt_master_slave_config (ec_master_t *master, uint16_t alias, uint16_t position, uint32_t vendor_id, uint32_t product_code)
	Obtains a slave configuration.
int	ecrt_master_select_reference_clock (ec_master_t *master, ec_slave_config_t *sc)
	Selects the reference clock for distributed clocks.
int	ecrt_master (ec_master_t *master, ec_master_info_t *master_info)
	Obtains master information.
int	ecrt_master_get_slave (ec_master_t *master, uint16_t slave_position, ec_slave_info_t *slave_info)
	Obtains slave information.
int	ecrt_master_sdo_download (ec_master_t *master, uint16_t slave_position, uint16_t index, uint8_t subindex, uint8_t *data, size_t data_size, uint32_t *abort_code)
	Executes an SDO download request to write data to a slave.
int	ecrt_master_sdo_download_complete (ec_master_t *master, uint16_t slave_position, uint16_t index, uint8_t *data, size_t data_size, uint32_t *abort_code)
	Executes an SDO download request to write data to a slave via complete access.
int	ecrt_master_sdo_upload (ec_master_t *master, uint16_t slave_position, uint16_t index, uint8_t subindex, uint8_t *target, size_t target_size, size_t *result_size, uint32_t *abort_code)
	Executes an SDO upload request to read data from a slave.
int	ecrt_master_write_idn (ec_master_t *master, uint16_t slave_position, uint8_t drive_no, uint16_t idn, uint8_t *data, size_t data_size, uint16_t *error_code)
	Executes an SoE write request.
int	ecrt_master_read_idn (ec_master_t *master, uint16_t slave_position, uint8_t drive_no, uint16_t idn, uint8_t *target, size_t target_size, size_t *result_size, uint16_t *error_code)
	Executes an SoE read request.
int	ecrt_master_activate (ec_master_t *master)
	Finishes the configuration phase and prepares for cyclic operation.
void	ecrt_master_deactivate (ec_master_t *master)
	Deactivates the master.
int	ecrt_master_set_send_interval (ec_master_t *master, size_t send_interval)
	Set interval between calls to ecrt_master_send().
void	ecrt_master_send (ec_master_t *master)
	Sends all datagrams in the queue.
void	ecrt_master_receive (ec_master_t *master)
	Fetches received frames from the hardware and processes the datagrams.
void	ecrt_master_send_ext (ec_master_t *master)
	Sends non-application datagrams.
void	ecrt_master_state (const ec_master_t *master, ec_master_state_t *state)
	Reads the current master state.
int	ecrt_master_link_state (const ec_master_t *master, unsigned int dev_idx, ec_master_link_state_t *state)
	Reads the current state of a redundant link.
void	ecrt_master_application_time (ec_master_t *master, uint64_t app_time)
	Sets the application time.
void	ecrt_master_sync_reference_clock (ec_master_t *master)
	Queues the DC reference clock drift compensation datagram for sending.
void	ecrt_master_sync_slave_clocks (ec_master_t *master)
	Queues the DC clock drift compensation datagram for sending.
int	ecrt_master_reference_clock_time (ec_master_t *master, uint32_t *time)
	Get the lower 32 bit of the reference clock system time.
void	ecrt_master_sync_monitor_queue (ec_master_t *master)
	Queues the DC synchrony monitoring datagram for sending.
uint32_t	ecrt_master_sync_monitor_process (ec_master_t *master)
	Processes the DC synchrony monitoring datagram.
void	ecrt_master_reset (ec_master_t *master)
	Retry configuring slaves.
int	ecrt_slave_config_sync_manager (ec_slave_config_t *sc, uint8_t sync_index, ec_direction_t direction, ec_watchdog_mode_t watchdog_mode)
	Configure a sync manager.
void	ecrt_slave_config_watchdog (ec_slave_config_t *sc, uint16_t watchdog_divider, uint16_t watchdog_intervals)
	Configure a slave's watchdog times.
int	ecrt_slave_config_pdo_assign_add (ec_slave_config_t *sc, uint8_t sync_index, uint16_t index)
	Add a PDO to a sync manager's PDO assignment.
void	ecrt_slave_config_pdo_assign_clear (ec_slave_config_t *sc, uint8_t sync_index)
	Clear a sync manager's PDO assignment.
int	ecrt_slave_config_pdo_mapping_add (ec_slave_config_t *sc, uint16_t pdo_index, uint16_t entry_index, uint8_t entry_subindex, uint8_t entry_bit_length)
	Add a PDO entry to the given PDO's mapping.
void	ecrt_slave_config_pdo_mapping_clear (ec_slave_config_t *sc, uint16_t pdo_index)
	Clear the mapping of a given PDO.
int	ecrt_slave_config_pdos (ec_slave_config_t *sc, unsigned int n_syncs, const ec_sync_info_t syncs[])
	Specify a complete PDO configuration.
int	ecrt_slave_config_reg_pdo_entry (ec_slave_config_t *sc, uint16_t entry_index, uint8_t entry_subindex, ec_domain_t *domain, unsigned int *bit_position)
	Registers a PDO entry for process data exchange in a domain.
int	ecrt_slave_config_reg_pdo_entry_pos (ec_slave_config_t *sc, uint8_t sync_index, unsigned int pdo_pos, unsigned int entry_pos, ec_domain_t *domain, unsigned int *bit_position)
	Registers a PDO entry using its position.
void	ecrt_slave_config_dc (ec_slave_config_t *sc, uint16_t assign_activate, uint32_t sync0_cycle, int32_t sync0_shift, uint32_t sync1_cycle, int32_t sync1_shift)
	Configure distributed clocks.
int	ecrt_slave_config_sdo (ec_slave_config_t *sc, uint16_t index, uint8_t subindex, const uint8_t *data, size_t size)
	Add an SDO configuration.
int	ecrt_slave_config_sdo8 (ec_slave_config_t *sc, uint16_t sdo_index, uint8_t sdo_subindex, uint8_t value)
	Add a configuration value for an 8-bit SDO.
int	ecrt_slave_config_sdo16 (ec_slave_config_t *sc, uint16_t sdo_index, uint8_t sdo_subindex, uint16_t value)
	Add a configuration value for a 16-bit SDO.
int	ecrt_slave_config_sdo32 (ec_slave_config_t *sc, uint16_t sdo_index, uint8_t sdo_subindex, uint32_t value)
	Add a configuration value for a 32-bit SDO.
int	ecrt_slave_config_complete_sdo (ec_slave_config_t *sc, uint16_t index, const uint8_t *data, size_t size)
	Add configuration data for a complete SDO.
int	ecrt_slave_config_emerg_size (ec_slave_config_t *sc, size_t elements)
	Set the size of the CoE emergency ring buffer.
int	ecrt_slave_config_emerg_pop (ec_slave_config_t *sc, uint8_t *target)
	Read and remove one record from the CoE emergency ring buffer.
int	ecrt_slave_config_emerg_clear (ec_slave_config_t *sc)
	Clears CoE emergency ring buffer and the overrun counter.
int	ecrt_slave_config_emerg_overruns (ec_slave_config_t *sc)
	Read the number of CoE emergency overruns.
ec_sdo_request_t *	ecrt_slave_config_create_sdo_request (ec_slave_config_t *sc, uint16_t index, uint8_t subindex, size_t size)
	Create an SDO request to exchange SDOs during realtime operation.
ec_voe_handler_t *	ecrt_slave_config_create_voe_handler (ec_slave_config_t *sc, size_t size)
	Create an VoE handler to exchange vendor-specific data during realtime operation.
ec_reg_request_t *	ecrt_slave_config_create_reg_request (ec_slave_config_t *sc, size_t size)
	Create a register request to exchange EtherCAT register contents during realtime operation.
void	ecrt_slave_config_state (const ec_slave_config_t *sc, ec_slave_config_state_t *state)
	Outputs the state of the slave configuration.
int	ecrt_slave_config_idn (ec_slave_config_t *sc, uint8_t drive_no, uint16_t idn, ec_al_state_t state, const uint8_t *data, size_t size)
	Add an SoE IDN configuration.
int	ecrt_domain_reg_pdo_entry_list (ec_domain_t *domain, const ec_pdo_entry_reg_t *pdo_entry_regs)
	Registers a bunch of PDO entries for a domain.
size_t	ecrt_domain_size (const ec_domain_t *domain)
	Returns the current size of the domain's process data.
void	ecrt_domain_external_memory (ec_domain_t *domain, uint8_t *memory)
	Provide external memory to store the domain's process data.
uint8_t *	ecrt_domain_data (ec_domain_t *domain)
	Returns the domain's process data.
void	ecrt_domain_process (ec_domain_t *domain)
	Determines the states of the domain's datagrams.
void	ecrt_domain_queue (ec_domain_t *domain)
	(Re-)queues all domain datagrams in the master's datagram queue.
void	ecrt_domain_state (const ec_domain_t *domain, ec_domain_state_t *state)
	Reads the state of a domain.
void	ecrt_sdo_request_index (ec_sdo_request_t *req, uint16_t index, uint8_t subindex)
	Set the SDO index and subindex.
void	ecrt_sdo_request_timeout (ec_sdo_request_t *req, uint32_t timeout)
	Set the timeout for an SDO request.
uint8_t *	ecrt_sdo_request_data (ec_sdo_request_t *req)
	Access to the SDO request's data.
size_t	ecrt_sdo_request_data_size (const ec_sdo_request_t *req)
	Returns the current SDO data size.
ec_request_state_t	ecrt_sdo_request_state (const ec_sdo_request_t *req)
	Get the current state of the SDO request.
void	ecrt_sdo_request_write (ec_sdo_request_t *req)
	Schedule an SDO write operation.
void	ecrt_sdo_request_read (ec_sdo_request_t *req)
	Schedule an SDO read operation.
void	ecrt_voe_handler_send_header (ec_voe_handler_t *voe, uint32_t vendor_id, uint16_t vendor_type)
	Sets the VoE header for future send operations.
void	ecrt_voe_handler_received_header (const ec_voe_handler_t *voe, uint32_t *vendor_id, uint16_t *vendor_type)
	Reads the header data of a received VoE message.
uint8_t *	ecrt_voe_handler_data (ec_voe_handler_t *voe)
	Access to the VoE handler's data.
size_t	ecrt_voe_handler_data_size (const ec_voe_handler_t *voe)
	Returns the current data size.
void	ecrt_voe_handler_write (ec_voe_handler_t *voe, size_t size)
	Start a VoE write operation.
void	ecrt_voe_handler_read (ec_voe_handler_t *voe)
	Start a VoE read operation.
void	ecrt_voe_handler_read_nosync (ec_voe_handler_t *voe)
	Start a VoE read operation without querying the sync manager status.
ec_request_state_t	ecrt_voe_handler_execute (ec_voe_handler_t *voe)
	Execute the handler.
uint8_t *	ecrt_reg_request_data (ec_reg_request_t *req)
	Access to the register request's data.
ec_request_state_t	ecrt_reg_request_state (const ec_reg_request_t *req)
	Get the current state of the register request.
void	ecrt_reg_request_write (ec_reg_request_t *req, uint16_t address, size_t size)
	Schedule an register write operation.
void	ecrt_reg_request_read (ec_reg_request_t *req, uint16_t address, size_t size)
	Schedule a register read operation.

---

Detailed Description

EtherCAT master application interface.

Definition in file ecrt.h.