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...

Macros
#define	ECRT_VER_MAJOR   1
	EtherCAT realtime interface major version number.
#define	ECRT_VER_MINOR   5
	EtherCAT realtime interface minor version number.
#define	ECRT_VER_PATCH   10
	EtherCAT realtime interface patchlevel number.
#define	ECRT_VERSION(a, b, c)   (((a) << 16) + ((b) << 8) + (c))
	EtherCAT realtime interface version word generator.
#define	ECRT_VERSION_MAGIC   ECRT_VERSION(ECRT_VER_MAJOR, ECRT_VER_MINOR, ECRT_VER_PATCH)
	EtherCAT realtime interface version word.
#define	EC_HAVE_REDUNDANCY
	Defined, if the redundancy features are available. More...
#define	EC_HAVE_EMERGENCY
	Defined, if the CoE emergency ring feature is available. More...
#define	EC_HAVE_REG_ACCESS
	Defined, if the register access interface is available. More...
#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_HAVE_SYNC_TO
	Defined if the method ecrt_master_sync_reference_clock_to() is available.
#define	EC_END   ~0U
	End of list marker. More...
#define	EC_MAX_SYNC_MANAGERS   16
	Maximum number of sync managers per slave.
#define	EC_MAX_STRING_LENGTH   64
	Maximum string length. More...
#define	EC_MAX_PORTS   4
	Maximum number of slave ports. More...
#define	EC_TIMEVAL2NANO(TV)   (((TV).tv_sec - 946684800ULL) * 1000000000ULL + (TV).tv_usec * 1000ULL)
	Timeval to nanoseconds conversion. More...
#define	EC_COE_EMERGENCY_MSG_SIZE   8
	Size of a CoE emergency message in byte. More...
#define	EC_READ_BIT(DATA, POS)   ((*((uint8_t *) (DATA)) >> (POS)) & 0x01)
	Read a certain bit of an EtherCAT data byte. More...
#define	EC_WRITE_BIT(DATA, POS, VAL)
	Write a certain bit of an EtherCAT data byte. More...
#define	EC_READ_U8(DATA)   ((uint8_t) *((uint8_t *) (DATA)))
	Read an 8-bit unsigned value from EtherCAT data. More...
#define	EC_READ_S8(DATA)   ((int8_t) *((uint8_t *) (DATA)))
	Read an 8-bit signed value from EtherCAT data. More...
#define	EC_READ_U16(DATA)   ((uint16_t) le16_to_cpup((void *) (DATA)))
	Read a 16-bit unsigned value from EtherCAT data. More...
#define	EC_READ_S16(DATA)   ((int16_t) le16_to_cpup((void *) (DATA)))
	Read a 16-bit signed value from EtherCAT data. More...
#define	EC_READ_U32(DATA)   ((uint32_t) le32_to_cpup((void *) (DATA)))
	Read a 32-bit unsigned value from EtherCAT data. More...
#define	EC_READ_S32(DATA)   ((int32_t) le32_to_cpup((void *) (DATA)))
	Read a 32-bit signed value from EtherCAT data. More...
#define	EC_READ_U64(DATA)   ((uint64_t) le64_to_cpup((void *) (DATA)))
	Read a 64-bit unsigned value from EtherCAT data. More...
#define	EC_READ_S64(DATA)   ((int64_t) le64_to_cpup((void *) (DATA)))
	Read a 64-bit signed value from EtherCAT data. More...
#define	EC_WRITE_U8(DATA, VAL)
	Write an 8-bit unsigned value to EtherCAT data. More...
#define	EC_WRITE_S8(DATA, VAL)   EC_WRITE_U8(DATA, VAL)
	Write an 8-bit signed value to EtherCAT data. More...
#define	EC_WRITE_U16(DATA, VAL)
	Write a 16-bit unsigned value to EtherCAT data. More...
#define	EC_WRITE_S16(DATA, VAL)   EC_WRITE_U16(DATA, VAL)
	Write a 16-bit signed value to EtherCAT data. More...
#define	EC_WRITE_U32(DATA, VAL)
	Write a 32-bit unsigned value to EtherCAT data. More...
#define	EC_WRITE_S32(DATA, VAL)   EC_WRITE_U32(DATA, VAL)
	Write a 32-bit signed value to EtherCAT data. More...
#define	EC_WRITE_U64(DATA, VAL)
	Write a 64-bit unsigned value to EtherCAT data. More...
#define	EC_WRITE_S64(DATA, VAL)   EC_WRITE_U64(DATA, VAL)
	Write a 64-bit signed value to EtherCAT data. More...

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_foe_request	ec_foe_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_BOTH,   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_foe_error_t {   FOE_BUSY = 0, FOE_READY = 1, FOE_IDLE = 2, FOE_WC_ERROR = 3,   FOE_RECEIVE_ERROR = 4, FOE_PROT_ERROR = 5, FOE_NODATA_ERROR = 6, FOE_PACKETNO_ERROR = 7,   FOE_OPCODE_ERROR = 8, FOE_TIMEOUT_ERROR = 9, FOE_SEND_RX_DATA_ERROR = 10, FOE_RX_DATA_ACK_ERROR = 11,   FOE_ACK_ERROR = 12, FOE_MBOX_FETCH_ERROR = 13, FOE_READ_NODATA_ERROR = 14, FOE_MBOX_PROT_ERROR = 15,   FOE_READ_OVER_ERROR = 16 }
	FoE error enumeration type. 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. More...
ec_master_t *	ecrt_request_master (unsigned int master_index)
	Requests an EtherCAT master for realtime operation. More...
void	ecrt_release_master (ec_master_t *master)
	Releases a requested EtherCAT master. More...
void	ecrt_master_callbacks (ec_master_t *master, void(*send_cb)(void *), void(*receive_cb)(void *), void *cb_data)
	Sets the locking callbacks. More...
ec_domain_t *	ecrt_master_create_domain (ec_master_t *master)
	Creates a new process data domain. More...
int	ecrt_master_setup_domain_memory (ec_master_t *master)
	setup the domain's process data memory. More...
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. More...
int	ecrt_master_select_reference_clock (ec_master_t *master, ec_slave_config_t *sc)
	Selects the reference clock for distributed clocks. More...
int	ecrt_master (ec_master_t *master, ec_master_info_t *master_info)
	Obtains master information. More...
int	ecrt_master_get_slave (ec_master_t *master, uint16_t slave_position, ec_slave_info_t *slave_info)
	Obtains slave information. More...
int	ecrt_master_sdo_download (ec_master_t *master, uint16_t slave_position, uint16_t index, uint8_t subindex, const uint8_t *data, size_t data_size, uint32_t *abort_code)
	Executes an SDO download request to write data to a slave. More...
int	ecrt_master_sdo_download_complete (ec_master_t *master, uint16_t slave_position, uint16_t index, const 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. More...
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. More...
int	ecrt_master_sdo_upload_complete (ec_master_t *master, uint16_t slave_position, uint16_t index, 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 via complete access. More...
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. More...
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. More...
int	ecrt_master_activate (ec_master_t *master)
	Finishes the configuration phase and prepares for cyclic operation. More...
void	ecrt_master_deactivate_slaves (ec_master_t *master)
	Deactivates the slaves distributed clocks and sends the slaves into PREOP. More...
void	ecrt_master_deactivate (ec_master_t *master)
	Deactivates the master. More...
int	ecrt_master_set_send_interval (ec_master_t *master, size_t send_interval)
	Set interval between calls to ecrt_master_send(). More...
size_t	ecrt_master_send (ec_master_t *master)
	Sends all datagrams in the queue. More...
void	ecrt_master_receive (ec_master_t *master)
	Fetches received frames from the hardware and processes the datagrams. More...
size_t	ecrt_master_send_ext (ec_master_t *master)
	Sends non-application datagrams. More...
void	ecrt_master_state (const ec_master_t *master, ec_master_state_t *state)
	Reads the current master state. More...
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. More...
void	ecrt_master_application_time (ec_master_t *master, uint64_t app_time)
	Sets the application time. More...
void	ecrt_master_sync_reference_clock (ec_master_t *master)
	Queues the DC reference clock drift compensation datagram for sending. More...
void	ecrt_master_sync_reference_clock_to (ec_master_t *master, uint64_t sync_time)
	Queues the DC reference clock drift compensation datagram for sending. More...
void	ecrt_master_sync_slave_clocks (ec_master_t *master)
	Queues the DC clock drift compensation datagram for sending. More...
int	ecrt_master_reference_clock_time (ec_master_t *master, uint32_t *time)
	Get the lower 32 bit of the reference clock system time. More...
void	ecrt_master_64bit_reference_clock_time_queue (ec_master_t *master)
	Queues the 64bit dc reference slave clock time value datagram for sending. More...
int	ecrt_master_64bit_reference_clock_time (ec_master_t *master, uint64_t *time)
	Get the 64bit dc reference slave clock time. More...
void	ecrt_master_sync_monitor_queue (ec_master_t *master)
	Queues the DC synchrony monitoring datagram for sending. More...
uint32_t	ecrt_master_sync_monitor_process (ec_master_t *master)
	Processes the DC synchrony monitoring datagram. More...
int	ecrt_master_rt_slave_requests (ec_master_t *master, unsigned int rt_slave_requests)
	Selects whether to process slave requests by the application or the master. More...
void	ecrt_master_exec_slave_requests (ec_master_t *master)
	Explicit call to process slave requests. More...
void	ecrt_master_reset (ec_master_t *master)
	Retry configuring slaves. More...
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. More...
void	ecrt_slave_config_watchdog (ec_slave_config_t *sc, uint16_t watchdog_divider, uint16_t watchdog_intervals)
	Configure a slave's watchdog times. More...
void	ecrt_slave_config_overlapping_pdos (ec_slave_config_t *sc, uint8_t allow_overlapping_pdos)
	Configure whether a slave allows overlapping PDOs. More...
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. More...
void	ecrt_slave_config_pdo_assign_clear (ec_slave_config_t *sc, uint8_t sync_index)
	Clear a sync manager's PDO assignment. More...
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. More...
void	ecrt_slave_config_pdo_mapping_clear (ec_slave_config_t *sc, uint16_t pdo_index)
	Clear the mapping of a given PDO. More...
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. More...
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. More...
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. More...
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. More...
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. More...
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. More...
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. More...
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. More...
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. More...
int	ecrt_slave_config_emerg_size (ec_slave_config_t *sc, size_t elements)
	Set the size of the CoE emergency ring buffer. More...
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. More...
int	ecrt_slave_config_emerg_clear (ec_slave_config_t *sc)
	Clears CoE emergency ring buffer and the overrun counter. More...
int	ecrt_slave_config_emerg_overruns (ec_slave_config_t *sc)
	Read the number of CoE emergency overruns. More...
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. More...
ec_sdo_request_t *	ecrt_slave_config_create_sdo_request_complete (ec_slave_config_t *sc, uint16_t index, size_t size)
	Create an SDO request to exchange SDOs during realtime operation using complete access. More...
ec_foe_request_t *	ecrt_slave_config_create_foe_request (ec_slave_config_t *sc, size_t size)
	Create an FoE request to exchange files during realtime operation. More...
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. More...
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. More...
void	ecrt_slave_config_state (const ec_slave_config_t *sc, ec_slave_config_state_t *state)
	Outputs the state of the slave configuration. More...
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. More...
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. More...
size_t	ecrt_domain_size (const ec_domain_t *domain)
	Returns the current size of the domain's process data. More...
void	ecrt_domain_external_memory (ec_domain_t *domain, uint8_t *memory)
	Provide external memory to store the domain's process data. More...
uint8_t *	ecrt_domain_data (ec_domain_t *domain)
	Returns the domain's process data. More...
void	ecrt_domain_process (ec_domain_t *domain)
	Determines the states of the domain's datagrams. More...
void	ecrt_domain_queue (ec_domain_t *domain)
	(Re-)queues all domain datagrams in the master's datagram queue. More...
void	ecrt_domain_state (const ec_domain_t *domain, ec_domain_state_t *state)
	Reads the state of a domain. More...
void	ecrt_sdo_request_index (ec_sdo_request_t *req, uint16_t index, uint8_t subindex)
	Set the SDO index and subindex and prepare for non-complete-access. More...
void	ecrt_sdo_request_index_complete (ec_sdo_request_t *req, uint16_t index)
	Set the SDO index and prepare for complete-access. More...
void	ecrt_sdo_request_timeout (ec_sdo_request_t *req, uint32_t timeout)
	Set the timeout for an SDO request. More...
uint8_t *	ecrt_sdo_request_data (ec_sdo_request_t *req)
	Access to the SDO request's data. More...
size_t	ecrt_sdo_request_data_size (const ec_sdo_request_t *req)
	Returns the current SDO data size. More...
ec_request_state_t	ecrt_sdo_request_state (const ec_sdo_request_t *req)
	Get the current state of the SDO request. More...
void	ecrt_sdo_request_write (ec_sdo_request_t *req)
	Schedule an SDO write operation. More...
void	ecrt_sdo_request_write_with_size (ec_sdo_request_t *req, size_t size)
	Schedule an SDO write operation. More...
void	ecrt_sdo_request_read (ec_sdo_request_t *req)
	Schedule an SDO read operation. More...
void	ecrt_foe_request_file (ec_foe_request_t *req, const char *file_name, uint32_t password)
	Select the filename to use for the next FoE operation. More...
void	ecrt_foe_request_timeout (ec_foe_request_t *req, uint32_t timeout)
	Set the timeout for an FoE request. More...
uint8_t *	ecrt_foe_request_data (ec_foe_request_t *req)
	Access to the FoE request's data. More...
size_t	ecrt_foe_request_data_size (const ec_foe_request_t *req)
	Returns the current FoE data size. More...
ec_request_state_t	ecrt_foe_request_state (const ec_foe_request_t *req)
	Get the current state of the FoE request. More...
ec_foe_error_t	ecrt_foe_request_result (const ec_foe_request_t *req)
	Get the result of the FoE request. More...
uint32_t	ecrt_foe_request_error_code (const ec_foe_request_t *req)
	Get the FoE error code from the FoE request. More...
size_t	ecrt_foe_request_progress (const ec_foe_request_t *req)
	Returns the progress of the current transfer. More...
void	ecrt_foe_request_write (ec_foe_request_t *req, size_t size)
	Schedule an FoE write operation. More...
void	ecrt_foe_request_read (ec_foe_request_t *req)
	Schedule an FoE read operation. More...
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. More...
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. More...
uint8_t *	ecrt_voe_handler_data (ec_voe_handler_t *voe)
	Access to the VoE handler's data. More...
size_t	ecrt_voe_handler_data_size (const ec_voe_handler_t *voe)
	Returns the current data size. More...
void	ecrt_voe_handler_write (ec_voe_handler_t *voe, size_t size)
	Start a VoE write operation. More...
void	ecrt_voe_handler_read (ec_voe_handler_t *voe)
	Start a VoE read operation. More...
void	ecrt_voe_handler_read_nosync (ec_voe_handler_t *voe)
	Start a VoE read operation without querying the sync manager status. More...
ec_request_state_t	ecrt_voe_handler_execute (ec_voe_handler_t *voe)
	Execute the handler. More...
uint8_t *	ecrt_reg_request_data (ec_reg_request_t *req)
	Access to the register request's data. More...
ec_request_state_t	ecrt_reg_request_state (const ec_reg_request_t *req)
	Get the current state of the register request. More...
void	ecrt_reg_request_write (ec_reg_request_t *req, uint16_t address, size_t size)
	Schedule an register write operation. More...
void	ecrt_reg_request_read (ec_reg_request_t *req, uint16_t address, size_t size)
	Schedule a register read operation. More...
void	ecrt_reg_request_readwrite (ec_reg_request_t *req, uint16_t address, size_t size)
	Schedule a register read-write operation. More...

Detailed Description

EtherCAT master application interface.

Definition in file ecrt.h.