EC Master

Data Structures
struct	ec_pd_group
	process data group structure More...
struct	ec
	ethercat master structure More...

Macros
#define	EC_SHORT_TIMEOUT_MBX   (10000000)
	Short timeout value in [ns].
#define	EC_DEFAULT_TIMEOUT_MBX   (1000000000)
	Default timeout value in [ns].
#define	EC_DEFAULT_DELAY   (2000000)
	Default delay in [ns].
#define	ec_log(lvl, pre, format, ...)    _ec_log(pec, (lvl), (pre), (format), ##__VA_ARGS__)
#define	ec_group_will_be_sent(pec, group)   (int)((((pec)->pd_groups[(group)].divisor_cnt+1) % (pec)->pd_groups[(group)].divisor) == 0)
	Group datagram will be send on next time step.
#define	ec_group_was_sent(pec, group)   (int)((pec)->pd_groups[(group)].divisor_cnt == 0)
	Group datagram was sent.
#define	ec_to_adr(ado, adp)    ((osal_uint32_t)(adp) << 16u) | ((ado) & 0xFFFFu)
	Macro for EtherCAT address generation.
#define	ec_brd(pec, ado, data, datalen, wkc)
	Perform a broadcast read (BRD).
#define	ec_bwr(pec, ado, data, datalen, wkc)
	Perform a broadcast write (BWR).
#define	ec_brw(pec, ado, data, datalen, wkc)
	Perform a broadcast read/write (BRW).
#define	ec_aprd(pec, adp, ado, data, datalen, wkc)
	Perform a positional physical read (APRD)
#define	ec_apwr(pec, adp, ado, data, datalen, wkc)
	Perform a positional physical write (APWR)
#define	ec_aprw(pec, adp, ado, data, datalen, wkc)
	Perform a positional physical read/write (APRW)
#define	ec_fprd(pec, adp, ado, data, datalen, wkc)
	Perform a configured-address physical read (FPRD)
#define	ec_fpwr(pec, adp, ado, data, datalen, wkc)
	Perform a configured-address physical write (FPWR)
#define	ec_fprw(pec, adp, ado, data, datalen, wkc)
	Perform a configured-address physical read/write (FPRW)
#define	ec_frmw(pec, adp, ado, data, datalen, wkc)
	Perform a configured-address physical read/multiple-write (FPMW)
#define	check_ret(fcn, ...)
	Macro that checks return value and prints message in error case.
#define	check_ec_bwr(...)   check_ret(ec_bwr, __VA_ARGS__)
	Macro that checks return value and prints message in error case.
#define	check_ec_brd(...)   check_ret(ec_brd, __VA_ARGS__)
	Macro that checks return value and prints message in error case.
#define	check_ec_brw(...)   check_ret(ec_brw, __VA_ARGS__)
	Macro that checks return value and prints message in error case.
#define	check_ec_apwr(...)   check_ret(ec_apwr, __VA_ARGS__)
	Macro that checks return value and prints message in error case.
#define	check_ec_aprd(...)   check_ret(ec_aprd, __VA_ARGS__)
	Macro that checks return value and prints message in error case.
#define	check_ec_aprw(...)   check_ret(ec_aprw, __VA_ARGS__)
	Macro that checks return value and prints message in error case.
#define	check_ec_fpwr(...)   check_ret(ec_fpwr, __VA_ARGS__)
	Macro that checks return value and prints message in error case.
#define	check_ec_fprd(...)   check_ret(ec_fprd, __VA_ARGS__)
	Macro that checks return value and prints message in error case.
#define	check_ec_fprw(...)   check_ret(ec_fprw, __VA_ARGS__)
	Macro that checks return value and prints message in error case.
#define	check_ec_frmw(...)   check_ret(ec_frmw, __VA_ARGS__)
	Macro that checks return value and prints message in error case.

Typedefs
typedef struct ec_slave	ec_slave_t
typedef struct ec_pd_group	ec_pd_group_t
	process data group structure
typedef struct ec	ec_t
	ethercat master structure

Functions
void	_ec_log (ec_t *pec, int lvl, const osal_char_t *pre, const osal_char_t *format,...)
	EtherCAT logging function.
int	ec_open (ec_t *pec, struct hw_common *phw, int eeprom_log)
	Open ethercat master.
int	ec_close (ec_t *pec)
	Closes ethercat master.
int	ec_configure_tun (ec_t *pec, osal_uint8_t ip_address[4])
	Configures tun device of EtherCAT master, used for EoE slaves.
void	ec_configure_dc (ec_t *pec, osal_uint64_t timer, ec_dc_mode_t mode, void(*user_cb)(void *arg, int num), void *user_cb_arg)
	Configures distributed clocks settings on EtherCAT master.
int	ec_create_pd_groups (ec_t *pec, osal_uint32_t pd_group_cnt)
	Create process data groups.
void	ec_configure_pd_group (ec_t *pec, osal_uint16_t group, int clock_divisor, void(*user_cb)(void *arg, int num), void *user_cb_arg)
	Configure process data group settings.
int	ec_destroy_pd_groups (ec_t *pec)
	Destroy process data groups.
int	ec_transceive (ec_t *pec, osal_uint8_t cmd, osal_uint32_t adr, osal_uint8_t *data, osal_size_t datalen, osal_uint16_t *wkc)
	Syncronous ethercat read/write.
int	ec_transmit_no_reply (ec_t *pec, osal_uint8_t cmd, osal_uint32_t adr, osal_uint8_t *data, osal_size_t datalen)
	Asyncronous ethercat read/write, answer don't care.
int	ec_set_state (ec_t *pec, ec_state_t state)
	Set state on ethercat bus.
int	ec_send_process_data (ec_t *pec)
	send process data with logical commands
int	ec_send_distributed_clocks_sync (ec_t *pec)
	Send distributed clocks sync datagram.
int	ec_send_distributed_clocks_sync_with_rtc (ec_t *pec, osal_uint64_t act_rtc_time)
	Send distributed clock sync datagram.
int	ec_send_brd_ec_state (ec_t *pec)
	Send broadcast read to ec state.
int	ec_get_slave_count (ec_t *pec)
	Return current slave count.

Detailed Description

This modules contains main EtherCAT master functions.

Macro Definition Documentation

check_ret

#define check_ret	(		fcn,
			...
	)

Value:

    { \
    if (fcn(__VA_ARGS__) != EC_OK) { \
        ec_log(1, __func__, "" #fcn "(" #__VA_ARGS__ ") failed!\n"); \
    } }

Macro that checks return value and prints message in error case.

ec_aprd

#define ec_aprd	(		pec,
			adp,
			ado,
			data,
			datalen,
			wkc
	)

Value:

    ec_transceive((pec), EC_CMD_APRD, ((osal_uint32_t)(ado) << 16u) | \
            (*(osal_uint16_t *)&(adp) & 0xFFFFu), (osal_uint8_t *)(data), (datalen), (wkc))

Perform a positional physical read (APRD)

ec_aprw

#define ec_aprw	(		pec,
			adp,
			ado,
			data,
			datalen,
			wkc
	)

Value:

    ec_transceive((pec), EC_CMD_APRW, ((osal_uint32_t)(ado) << 16u) | \
            (*(osal_uint16_t *)&(adp) & 0xFFFFu), (osal_uint8_t *)(data), (datalen), (wkc))

Perform a positional physical read/write (APRW)

ec_apwr

#define ec_apwr	(		pec,
			adp,
			ado,
			data,
			datalen,
			wkc
	)

Value:

    ec_transceive((pec), EC_CMD_APWR, ((osal_uint32_t)(ado) << 16u) | \
            (*(osal_uint16_t *)&(adp) & 0xFFFFu), (osal_uint8_t *)(data), (datalen), (wkc))

Perform a positional physical write (APWR)

ec_brd

#define ec_brd	(		pec,
			ado,
			data,
			datalen,
			wkc
	)

Value:

    ec_transceive((pec), EC_CMD_BRD, ((osal_uint32_t)(ado) << 16u), \
            (osal_uint8_t *)(data), (datalen), (wkc))

Perform a broadcast read (BRD).

ec_brw

#define ec_brw	(		pec,
			ado,
			data,
			datalen,
			wkc
	)

Value:

    ec_transceive((pec), EC_CMD_BRW, ((osal_uint32_t)(ado) << 16u), \
            (osal_uint8_t *)(data), (datalen), (wkc))

Perform a broadcast read/write (BRW).

ec_bwr

#define ec_bwr	(		pec,
			ado,
			data,
			datalen,
			wkc
	)

Value:

    ec_transceive((pec), EC_CMD_BWR, ((osal_uint32_t)(ado) << 16u), \
            (osal_uint8_t *)(data), (datalen), (wkc))

Perform a broadcast write (BWR).

ec_fprd

#define ec_fprd	(		pec,
			adp,
			ado,
			data,
			datalen,
			wkc
	)

Value:

    ec_transceive((pec), EC_CMD_FPRD, ((osal_uint32_t)(ado) << 16lu) | \
            (osal_uint32_t)((adp) & 0xFFFFu), (osal_uint8_t *)(data), (datalen), (wkc))

Perform a configured-address physical read (FPRD)

ec_fprw

#define ec_fprw	(		pec,
			adp,
			ado,
			data,
			datalen,
			wkc
	)

Value:

    ec_transceive((pec), EC_CMD_FPRW, ((osal_uint32_t)(ado) << 16u) | \
            ((adp) & 0xFFFFu), (osal_uint8_t *)(data), (datalen), (wkc))

Perform a configured-address physical read/write (FPRW)

ec_fpwr

#define ec_fpwr	(		pec,
			adp,
			ado,
			data,
			datalen,
			wkc
	)

Value:

    ec_transceive((pec), EC_CMD_FPWR, ((osal_uint32_t)(ado) << 16u) | \
            ((adp) & 0xFFFFu), (osal_uint8_t *)(data), (datalen), (wkc))

Perform a configured-address physical write (FPWR)

ec_frmw

#define ec_frmw	(		pec,
			adp,
			ado,
			data,
			datalen,
			wkc
	)

Value:

    ec_transceive((pec), EC_CMD_FRMW, ((osal_uint32_t)(ado) << 16u) | \
            ((adp) & 0xFFFFu), (osal_uint8_t *)(data), (datalen), (wkc))

Perform a configured-address physical read/multiple-write (FPMW)

Function Documentation

_ec_log()

void _ec_log	(	ec_t *	pec,
		int	lvl,
		const osal_char_t *	pre,
		const osal_char_t *	format,
			...
	)

EtherCAT logging function.

This function does all EtherCAT logging.

Parameters

[in]	lvl	Log level of message.
[in]	pre	String prepended to message.
[in]	format	String format.
[in]	...	String format arguments.

ec_close()

int ec_close

(

ec_t *

pec

)

Closes ethercat master.

Parameters

[in]

pec

Pointer to ethercat master structure, which you got from ec_open.

Returns

0 on success

ec_configure_dc()

void ec_configure_dc	(	ec_t *	pec,
		osal_uint64_t	timer,
		ec_dc_mode_t	mode,
		void(*)(void *arg, int num)	user_cb,
		void *	user_cb_arg
	)

Configures distributed clocks settings on EtherCAT master.

Parameters

[in]	pec	Pointer to EtherCAT master structure.
[in]	timer	Fixed expected cyclic timer value.
[in]	mode	Distributed clock operating mode.
[in]	user_cb	Callback when DC datagram returned, maybe NULL.
[in]	user_cb_arg	Argument passed to 'user_cb', maybe NULL.

ec_configure_pd_group()

void ec_configure_pd_group	(	ec_t *	pec,
		osal_uint16_t	group,
		int	clock_divisor,
		void(*)(void *arg, int num)	user_cb,
		void *	user_cb_arg
	)

Configure process data group settings.

Parameters

[in]	pec	Pointer to EtherCAT master structure.
[in]	group	Number of group to configure.
[in]	clock_divisor	Send group datagram every 'clock_divisor' ticks.
[in]	user_cb	Callback when group datagram returned, maybe NULL.
[in]	user_cb_arg	Argument passed to 'user_cb', maybe NULL.

ec_configure_tun()

int ec_configure_tun	(	ec_t *	pec,
		osal_uint8_t	ip_address[4]
	)

Configures tun device of EtherCAT master, used for EoE slaves.

Parameters

[in]	pec	Pointer to ethercat master structure, which you got from ec_open.
[in]	ip_address	IP address to be set for tun device.

Returns

0 on success

ec_create_pd_groups()

int ec_create_pd_groups	(	ec_t *	pec,
		osal_uint32_t	pd_group_cnt
	)

Create process data groups.

Parameters

[in]	pec	Pointer to ethercat master structure, which you got from ec_open.
[in]	pd_group_cnt	Number of groups to create.

Returns

0 on success

ec_destroy_pd_groups()

int ec_destroy_pd_groups

(

ec_t *

pec

)

Destroy process data groups.

Parameters

[in]

pec

Pointer to ethercat master structure, which you got from ec_open.

Returns

0 on success

ec_get_slave_count()

int ec_get_slave_count

(

ec_t *

pec

)

Return current slave count.

Parameters

[in]

pec

Pointer to ethercat master structure.

Returns

cnt current slave count.

ec_open()

int ec_open	(	ec_t *	pec,
		struct hw_common *	phw,
		int	eeprom_log
	)

Open ethercat master.

This function is used as initial call to create the EtherCAT master instance. It configures all needed options with default values. A packet receive thread is spawned with given priority (prio) and affinity (affinity). Ensure that they meet your realtime requirements.

After the successfull completion a switch to EC_STATE_INIT will perform a initial scan of the bus.

Parameters

[out]	pec	Ethercat master instance pointer.
[in]	phw	Ethercat master network device access.
[in]	eeprom_log	Log eeprom to stdout.

Returns

0 on succes, otherwise error code

ec_send_brd_ec_state()

int ec_send_brd_ec_state

(

ec_t *

pec

)

Send broadcast read to ec state.

Parameters

[in]

pec

Pointer to ethercat master structure, which you got from ec_open.

Returns

0 on success

ec_send_distributed_clocks_sync()

int ec_send_distributed_clocks_sync

(

ec_t *

pec

)

Send distributed clocks sync datagram.

Parameters

[in]

pec

Pointer to ethercat master structure, which you got from ec_open.

Returns

0 on success

ec_send_distributed_clocks_sync_with_rtc()

int ec_send_distributed_clocks_sync_with_rtc	(	ec_t *	pec,
		osal_uint64_t	act_rtc_time
	)

Send distributed clock sync datagram.

Parameters

pec	Pointer to ethercat master structure, which you got from ec_open.
act_rtc_time	Current real-time clock value. If 0, the time of osal_timer_gettime_nsec() will be used. Otherwise the supplied time is used.

Returns

0 on success

ec_send_process_data()

int ec_send_process_data

(

ec_t *

pec

)

send process data with logical commands

Parameters

[in]

pec

Pointer to EtherCAT master struct.

Returns

EC_OK on success

ec_set_state()

int ec_set_state	(	ec_t *	pec,
		ec_state_t	state
	)

Set state on ethercat bus.

Parameters

[in]	pec	Pointer to ethercat master structure, which you got from ec_open.
[in]	state	New ethercat state.

Returns

Reached master state.

ec_transceive()

int ec_transceive	(	ec_t *	pec,
		osal_uint8_t	cmd,
		osal_uint32_t	adr,
		osal_uint8_t *	data,
		osal_size_t	datalen,
		osal_uint16_t *	wkc
	)

Syncronous ethercat read/write.

Parameters

[in]	pec	Pointer to ethercat master structure, which you got from ec_open.
[in]	cmd	EtherCAT command.
[in]	adr	32-bit address of slave.
[in]	data	Data buffer to read/write .
[in]	datalen	Length of data.
[out]	wkc	Return value for working counter.

Returns

0 on succes, otherwise error code

ec_transmit_no_reply()

int ec_transmit_no_reply	(	ec_t *	pec,
		osal_uint8_t	cmd,
		osal_uint32_t	adr,
		osal_uint8_t *	data,
		osal_size_t	datalen
	)

Asyncronous ethercat read/write, answer don't care.

Parameters

[in]	pec	Pointer to ethercat master structure, which you got from ec_open.
[in]	cmd	Ethercat command.
[in]	adr	32-bit address of slave.
[in]	data	Data buffer to read/write.
[in]	datalen	Length of data.

Returns

0 on succes, otherwise error code