ecrt.h

Go to the documentation of this file.

/******************************************************************************
 *
 *  $Id$
 *
 *  Copyright (C) 2006-2012  Florian Pose, Ingenieurgemeinschaft IgH
 *
 *  This file is part of the IgH EtherCAT master userspace library.
 *
 *  The IgH EtherCAT master userspace library is free software; you can
 *  redistribute it and/or modify it under the terms of the GNU Lesser General
 *  Public License as published by the Free Software Foundation; version 2.1
 *  of the License.
 *
 *  The IgH EtherCAT master userspace library 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 Lesser General Public License for more details.
 *
 *  You should have received a copy of the GNU Lesser General Public License
 *  along with the IgH EtherCAT master userspace library. If not, see
 *  <http://www.gnu.org/licenses/>.
 *
 *  ---
 *
 *  The license mentioned above concerns the source code only. Using the
 *  EtherCAT technology and brand is only permitted in compliance with the
 *  industrial property and similar rights of Beckhoff Automation GmbH.
 *
 *****************************************************************************/

/*****************************************************************************/

#ifndef __ECRT_H__
#define __ECRT_H__

#ifdef __KERNEL__
#include <asm/byteorder.h>
#include <linux/types.h>
#include <linux/time.h>
#else
#include <stdlib.h> // for size_t
#include <stdint.h>
#include <sys/time.h> // for struct timeval
#endif

/******************************************************************************
 * Global definitions
 *****************************************************************************/

#define ECRT_VER_MAJOR 1

#define ECRT_VER_MINOR 5

#define ECRT_VERSION(a, b) (((a) << 8) + (b))

#define ECRT_VERSION_MAGIC ECRT_VERSION(ECRT_VER_MAJOR, ECRT_VER_MINOR)

/******************************************************************************
 * Feature flags
 *****************************************************************************/

#define EC_HAVE_REDUNDANCY

#define EC_HAVE_EMERGENCY

#define EC_HAVE_REG_ACCESS

#define EC_HAVE_SELECT_REF_CLOCK

#define EC_HAVE_REF_CLOCK_TIME

#define EC_HAVE_REG_BY_POS

/*****************************************************************************/

#define EC_END ~0U

#define EC_MAX_SYNC_MANAGERS 16

#define EC_MAX_STRING_LENGTH 64

#define EC_MAX_PORTS 4

#define EC_TIMEVAL2NANO(TV) \
    (((TV).tv_sec - 946684800ULL) * 1000000000ULL + (TV).tv_usec * 1000ULL)

#define EC_COE_EMERGENCY_MSG_SIZE 8

/******************************************************************************
 * Data types
 *****************************************************************************/

struct ec_master;
typedef struct ec_master ec_master_t; 
struct ec_slave_config;
typedef struct ec_slave_config ec_slave_config_t; 
struct ec_domain;
typedef struct ec_domain ec_domain_t; 
struct ec_sdo_request;
typedef struct ec_sdo_request ec_sdo_request_t; 
struct ec_voe_handler;
typedef struct ec_voe_handler ec_voe_handler_t; 
struct ec_reg_request;
typedef struct ec_reg_request ec_reg_request_t; 
/*****************************************************************************/

typedef struct {
    unsigned int slaves_responding; 
    unsigned int al_states : 4; 
    unsigned int link_up : 1; 
} ec_master_state_t;

/*****************************************************************************/

typedef struct {
    unsigned int slaves_responding; 
    unsigned int al_states : 4; 
    unsigned int link_up : 1; 
} ec_master_link_state_t;

/*****************************************************************************/

typedef struct  {
    unsigned int online : 1; 
    unsigned int operational : 1; 
    unsigned int al_state : 4; 
} ec_slave_config_state_t;

/*****************************************************************************/

typedef struct {
   unsigned int slave_count; 
   unsigned int link_up : 1; 
   uint8_t scan_busy; 
   uint64_t app_time; 
} ec_master_info_t;

/*****************************************************************************/

typedef enum {
    EC_PORT_NOT_IMPLEMENTED, 
    EC_PORT_NOT_CONFIGURED, 
    EC_PORT_EBUS, 
    EC_PORT_MII 
} ec_slave_port_desc_t;

/*****************************************************************************/

typedef struct {
    uint8_t link_up; 
    uint8_t loop_closed; 
    uint8_t signal_detected; 
} ec_slave_port_link_t;

/*****************************************************************************/

typedef struct {
    uint16_t position; 
    uint32_t vendor_id; 
    uint32_t product_code; 
    uint32_t revision_number; 
    uint32_t serial_number; 
    uint16_t alias; 
    int16_t current_on_ebus; 
    struct {
        ec_slave_port_desc_t desc; 
        ec_slave_port_link_t link; 
        uint32_t receive_time; 
        uint16_t next_slave; 
        uint32_t delay_to_next_dc; 
    } ports[EC_MAX_PORTS]; 
    uint8_t al_state; 
    uint8_t error_flag; 
    uint8_t sync_count; 
    uint16_t sdo_count; 
    char name[EC_MAX_STRING_LENGTH]; 
} ec_slave_info_t;

/*****************************************************************************/

typedef enum {
    EC_WC_ZERO = 0,   
    EC_WC_INCOMPLETE, 
    EC_WC_COMPLETE    
} ec_wc_state_t;

/*****************************************************************************/

typedef struct {
    unsigned int working_counter; 
    ec_wc_state_t wc_state; 
    unsigned int redundancy_active; 
} ec_domain_state_t;

/*****************************************************************************/

typedef enum {
    EC_DIR_INVALID, 
    EC_DIR_OUTPUT, 
    EC_DIR_INPUT, 
    EC_DIR_COUNT 
} ec_direction_t;

/*****************************************************************************/

typedef enum {
    EC_WD_DEFAULT, 
    EC_WD_ENABLE, 
    EC_WD_DISABLE, 
} ec_watchdog_mode_t;

/*****************************************************************************/

typedef struct {
    uint16_t index; 
    uint8_t subindex; 
    uint8_t bit_length; 
} ec_pdo_entry_info_t;

/*****************************************************************************/

typedef struct {
    uint16_t index; 
    unsigned int n_entries; 
    ec_pdo_entry_info_t *entries; 
} ec_pdo_info_t;

/*****************************************************************************/

typedef struct {
    uint8_t index; 
    ec_direction_t dir; 
    unsigned int n_pdos; 
    ec_pdo_info_t *pdos; 
    ec_watchdog_mode_t watchdog_mode; 
} ec_sync_info_t;

/*****************************************************************************/

typedef struct {
    uint16_t alias; 
    uint16_t position; 
    uint32_t vendor_id; 
    uint32_t product_code; 
    uint16_t index; 
    uint8_t subindex; 
    unsigned int *offset; 
    unsigned int *bit_position; 
} ec_pdo_entry_reg_t;

/*****************************************************************************/

typedef enum {
    EC_REQUEST_UNUSED, 
    EC_REQUEST_BUSY, 
    EC_REQUEST_SUCCESS, 
    EC_REQUEST_ERROR, 
} ec_request_state_t;

/*****************************************************************************/

typedef enum {
    EC_AL_STATE_INIT = 1, 
    EC_AL_STATE_PREOP = 2, 
    EC_AL_STATE_SAFEOP = 4, 
    EC_AL_STATE_OP = 8, 
} ec_al_state_t;

/******************************************************************************
 * Global functions
 *****************************************************************************/

#ifdef __cplusplus
extern "C" {
#endif

unsigned int ecrt_version_magic(void);

ec_master_t *ecrt_request_master(
        unsigned int master_index 
        );

#ifndef __KERNEL__

ec_master_t *ecrt_open_master(
        unsigned int master_index 
        );

#endif // #ifndef __KERNEL__

void ecrt_release_master(
        ec_master_t *master 
        );

/******************************************************************************
 * Master methods
 *****************************************************************************/

#ifndef __KERNEL__

int ecrt_master_reserve(
        ec_master_t *master 
        );

#endif // #ifndef __KERNEL__

#ifdef __KERNEL__

void ecrt_master_callbacks(
        ec_master_t *master, 
        void (*send_cb)(void *), 
        void (*receive_cb)(void *), 
        void *cb_data 
        );

#endif /* __KERNEL__ */

ec_domain_t *ecrt_master_create_domain(
        ec_master_t *master 
        );

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 
        );

int ecrt_master_select_reference_clock(
        ec_master_t *master, 
        ec_slave_config_t *sc 
        );

int ecrt_master(
        ec_master_t *master, 
        ec_master_info_t *master_info 
        );

int ecrt_master_get_slave(
        ec_master_t *master, 
        uint16_t slave_position, 
        ec_slave_info_t *slave_info 
        );

#ifndef __KERNEL__

int ecrt_master_get_sync_manager(
        ec_master_t *master, 
        uint16_t slave_position, 
        uint8_t sync_index, 
        ec_sync_info_t *sync 
        );

int ecrt_master_get_pdo(
        ec_master_t *master, 
        uint16_t slave_position, 
        uint8_t sync_index, 
        uint16_t pos, 
        ec_pdo_info_t *pdo 
        );

int ecrt_master_get_pdo_entry(
        ec_master_t *master, 
        uint16_t slave_position, 
        uint8_t sync_index, 
        uint16_t pdo_pos, 
        uint16_t entry_pos, 
        ec_pdo_entry_info_t *entry 
        );

#endif /* #ifndef __KERNEL__ */

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 
        );

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 
        );

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 
        );

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 
        );

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 
        );

int ecrt_master_activate(
        ec_master_t *master 
        );

void ecrt_master_deactivate(
        ec_master_t *master 
        );

int ecrt_master_set_send_interval(
        ec_master_t *master, 
        size_t send_interval 
        );

void ecrt_master_send(
        ec_master_t *master 
        );

void ecrt_master_receive(
        ec_master_t *master 
        );

void ecrt_master_send_ext(
        ec_master_t *master 
        );

void ecrt_master_state(
        const ec_master_t *master, 
        ec_master_state_t *state 
        );

int ecrt_master_link_state(
        const ec_master_t *master, 
        unsigned int dev_idx, 
        ec_master_link_state_t *state 
        );

void ecrt_master_application_time(
        ec_master_t *master, 
        uint64_t app_time 
        );

void ecrt_master_sync_reference_clock(
        ec_master_t *master 
        );

void ecrt_master_sync_slave_clocks(
        ec_master_t *master 
        );

int ecrt_master_reference_clock_time(
        ec_master_t *master, 
        uint32_t *time 
        );

void ecrt_master_sync_monitor_queue(
        ec_master_t *master 
        );

uint32_t ecrt_master_sync_monitor_process(
        ec_master_t *master 
        );

void ecrt_master_reset(
        ec_master_t *master 
        );

/******************************************************************************
 * Slave configuration methods
 *****************************************************************************/

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 
        );

void ecrt_slave_config_watchdog(
        ec_slave_config_t *sc, 
        uint16_t watchdog_divider, 
        uint16_t watchdog_intervals 
        );

int ecrt_slave_config_pdo_assign_add(
        ec_slave_config_t *sc, 
        uint8_t sync_index, 
        uint16_t index 
        );

void ecrt_slave_config_pdo_assign_clear(
        ec_slave_config_t *sc, 
        uint8_t sync_index 
        );

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 
        );

void ecrt_slave_config_pdo_mapping_clear(
        ec_slave_config_t *sc, 
        uint16_t pdo_index 
        );

int ecrt_slave_config_pdos(
        ec_slave_config_t *sc, 
        unsigned int n_syncs, 
        const ec_sync_info_t syncs[] 
        );

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 
        );

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 
        );

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 
        );

int ecrt_slave_config_sdo(
        ec_slave_config_t *sc, 
        uint16_t index, 
        uint8_t subindex, 
        const uint8_t *data, 
        size_t size 
        );

int ecrt_slave_config_sdo8(
        ec_slave_config_t *sc, 
        uint16_t sdo_index, 
        uint8_t sdo_subindex, 
        uint8_t value 
        );

int ecrt_slave_config_sdo16(
        ec_slave_config_t *sc, 
        uint16_t sdo_index, 
        uint8_t sdo_subindex, 
        uint16_t value 
        );

int ecrt_slave_config_sdo32(
        ec_slave_config_t *sc, 
        uint16_t sdo_index, 
        uint8_t sdo_subindex, 
        uint32_t value 
        );

int ecrt_slave_config_complete_sdo(
        ec_slave_config_t *sc, 
        uint16_t index, 
        const uint8_t *data, 
        size_t size 
        );

int ecrt_slave_config_emerg_size(
        ec_slave_config_t *sc, 
        size_t elements 
        );

int ecrt_slave_config_emerg_pop(
        ec_slave_config_t *sc, 
        uint8_t *target 
        );

int ecrt_slave_config_emerg_clear(
        ec_slave_config_t *sc 
        );

int ecrt_slave_config_emerg_overruns(
        ec_slave_config_t *sc 
        );

ec_sdo_request_t *ecrt_slave_config_create_sdo_request(
        ec_slave_config_t *sc, 
        uint16_t index, 
        uint8_t subindex, 
        size_t size 
        );

ec_voe_handler_t *ecrt_slave_config_create_voe_handler(
        ec_slave_config_t *sc, 
        size_t size 
        );

ec_reg_request_t *ecrt_slave_config_create_reg_request(
        ec_slave_config_t *sc, 
        size_t size 
        );

void ecrt_slave_config_state(
        const ec_slave_config_t *sc, 
        ec_slave_config_state_t *state 
        );

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 
        );

/******************************************************************************
 * Domain methods
 *****************************************************************************/

int ecrt_domain_reg_pdo_entry_list(
        ec_domain_t *domain, 
        const ec_pdo_entry_reg_t *pdo_entry_regs 
        );

size_t ecrt_domain_size(
        const ec_domain_t *domain 
        );

#ifdef __KERNEL__

void ecrt_domain_external_memory(
        ec_domain_t *domain, 
        uint8_t *memory 
        );

#endif /* __KERNEL__ */

uint8_t *ecrt_domain_data(
        ec_domain_t *domain 
        );

void ecrt_domain_process(
        ec_domain_t *domain 
        );

void ecrt_domain_queue(
        ec_domain_t *domain 
        );

void ecrt_domain_state(
        const ec_domain_t *domain, 
        ec_domain_state_t *state 
        );

/*****************************************************************************
 * SDO request methods.
 ****************************************************************************/

void ecrt_sdo_request_index(
        ec_sdo_request_t *req, 
        uint16_t index, 
        uint8_t subindex 
        );

void ecrt_sdo_request_timeout(
        ec_sdo_request_t *req, 
        uint32_t timeout 
        );

uint8_t *ecrt_sdo_request_data(
        ec_sdo_request_t *req 
        );

size_t ecrt_sdo_request_data_size(
        const ec_sdo_request_t *req 
        );

#ifdef __KERNEL__
ec_request_state_t ecrt_sdo_request_state(
        const ec_sdo_request_t *req 
    );
#else
ec_request_state_t ecrt_sdo_request_state(
        ec_sdo_request_t *req 
    );
#endif

void ecrt_sdo_request_write(
        ec_sdo_request_t *req 
        );

void ecrt_sdo_request_read(
        ec_sdo_request_t *req 
        );

/*****************************************************************************
 * VoE handler methods.
 ****************************************************************************/

void ecrt_voe_handler_send_header(
        ec_voe_handler_t *voe, 
        uint32_t vendor_id, 
        uint16_t vendor_type 
        );

void ecrt_voe_handler_received_header(
        const ec_voe_handler_t *voe, 
        uint32_t *vendor_id, 
        uint16_t *vendor_type 
        );

uint8_t *ecrt_voe_handler_data(
        ec_voe_handler_t *voe 
        );

size_t ecrt_voe_handler_data_size(
        const ec_voe_handler_t *voe 
        );

void ecrt_voe_handler_write(
        ec_voe_handler_t *voe, 
        size_t size 
        );

void ecrt_voe_handler_read(
        ec_voe_handler_t *voe 
        );

void ecrt_voe_handler_read_nosync(
        ec_voe_handler_t *voe 
        );

ec_request_state_t ecrt_voe_handler_execute(
    ec_voe_handler_t *voe 
    );

/*****************************************************************************
 * Register request methods.
 ****************************************************************************/

uint8_t *ecrt_reg_request_data(
        ec_reg_request_t *req 
        );

#ifdef __KERNEL__
ec_request_state_t ecrt_reg_request_state(
        const ec_reg_request_t *req 
    );
#else
ec_request_state_t ecrt_reg_request_state(
        ec_reg_request_t *req 
    );
#endif

void ecrt_reg_request_write(
        ec_reg_request_t *req, 
        uint16_t address, 
        size_t size 
        );

void ecrt_reg_request_read(
        ec_reg_request_t *req, 
        uint16_t address, 
        size_t size 
        );

/*****************************************************************************/

#ifdef __cplusplus
}
#endif

/******************************************************************************
 * Bitwise read/write macros
 *****************************************************************************/

#define EC_READ_BIT(DATA, POS) ((*((uint8_t *) (DATA)) >> (POS)) & 0x01)

#define EC_WRITE_BIT(DATA, POS, VAL) \
    do { \
        if (VAL) *((uint8_t *) (DATA)) |=  (1 << (POS)); \
        else     *((uint8_t *) (DATA)) &= ~(1 << (POS)); \
    } while (0)

/******************************************************************************
 * Byte-swapping functions for user space
 *****************************************************************************/

#ifndef __KERNEL__

#if __BYTE_ORDER == __LITTLE_ENDIAN

#define le16_to_cpu(x) x
#define le32_to_cpu(x) x
#define le64_to_cpu(x) x

#define cpu_to_le16(x) x
#define cpu_to_le32(x) x
#define cpu_to_le64(x) x

#elif __BYTE_ORDER == __BIG_ENDIAN

#define swap16(x) \
        ((uint16_t)( \
        (((uint16_t)(x) & 0x00ffU) << 8) | \
        (((uint16_t)(x) & 0xff00U) >> 8) ))
#define swap32(x) \
        ((uint32_t)( \
        (((uint32_t)(x) & 0x000000ffUL) << 24) | \
        (((uint32_t)(x) & 0x0000ff00UL) <<  8) | \
        (((uint32_t)(x) & 0x00ff0000UL) >>  8) | \
        (((uint32_t)(x) & 0xff000000UL) >> 24) ))
#define swap64(x) \
        ((uint64_t)( \
        (((uint64_t)(x) & 0x00000000000000ffULL) << 56) | \
        (((uint64_t)(x) & 0x000000000000ff00ULL) << 40) | \
        (((uint64_t)(x) & 0x0000000000ff0000ULL) << 24) | \
        (((uint64_t)(x) & 0x00000000ff000000ULL) <<  8) | \
        (((uint64_t)(x) & 0x000000ff00000000ULL) >>  8) | \
        (((uint64_t)(x) & 0x0000ff0000000000ULL) >> 24) | \
        (((uint64_t)(x) & 0x00ff000000000000ULL) >> 40) | \
        (((uint64_t)(x) & 0xff00000000000000ULL) >> 56) ))

#define le16_to_cpu(x) swap16(x)
#define le32_to_cpu(x) swap32(x)
#define le64_to_cpu(x) swap64(x)

#define cpu_to_le16(x) swap16(x)
#define cpu_to_le32(x) swap32(x)
#define cpu_to_le64(x) swap64(x)

#endif

#define le16_to_cpup(x) le16_to_cpu(*((uint16_t *)(x)))
#define le32_to_cpup(x) le32_to_cpu(*((uint32_t *)(x)))
#define le64_to_cpup(x) le64_to_cpu(*((uint64_t *)(x)))

#endif /* ifndef __KERNEL__ */

/******************************************************************************
 * Read macros
 *****************************************************************************/

#define EC_READ_U8(DATA) \
    ((uint8_t) *((uint8_t *) (DATA)))

#define EC_READ_S8(DATA) \
     ((int8_t) *((uint8_t *) (DATA)))

#define EC_READ_U16(DATA) \
     ((uint16_t) le16_to_cpup((void *) (DATA)))

#define EC_READ_S16(DATA) \
     ((int16_t) le16_to_cpup((void *) (DATA)))

#define EC_READ_U32(DATA) \
     ((uint32_t) le32_to_cpup((void *) (DATA)))

#define EC_READ_S32(DATA) \
     ((int32_t) le32_to_cpup((void *) (DATA)))

#define EC_READ_U64(DATA) \
     ((uint64_t) le64_to_cpup((void *) (DATA)))

#define EC_READ_S64(DATA) \
     ((int64_t) le64_to_cpup((void *) (DATA)))

/******************************************************************************
 * Write macros
 *****************************************************************************/

#define EC_WRITE_U8(DATA, VAL) \
    do { \
        *((uint8_t *)(DATA)) = ((uint8_t) (VAL)); \
    } while (0)

#define EC_WRITE_S8(DATA, VAL) EC_WRITE_U8(DATA, VAL)

#define EC_WRITE_U16(DATA, VAL) \
    do { \
        *((uint16_t *) (DATA)) = cpu_to_le16((uint16_t) (VAL)); \
    } while (0)

#define EC_WRITE_S16(DATA, VAL) EC_WRITE_U16(DATA, VAL)

#define EC_WRITE_U32(DATA, VAL) \
    do { \
        *((uint32_t *) (DATA)) = cpu_to_le32((uint32_t) (VAL)); \
    } while (0)

#define EC_WRITE_S32(DATA, VAL) EC_WRITE_U32(DATA, VAL)

#define EC_WRITE_U64(DATA, VAL) \
    do { \
        *((uint64_t *) (DATA)) = cpu_to_le64((uint64_t) (VAL)); \
    } while (0)

#define EC_WRITE_S64(DATA, VAL) EC_WRITE_U64(DATA, VAL)

/*****************************************************************************/

#endif

---