ec.h

Go to the documentation of this file.

 
/*
 * This file is part of libethercat.
 *
 * libethercat 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; either
 * version 3 of the License, or (at your option) any later version.
 * 
 * libethercat 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 libethercat (LICENSE.LGPL-V3); if not, write 
 * to the Free Software Foundation, Inc., 51 Franklin Street, Fifth 
 * Floor, Boston, MA  02110-1301, USA.
 * 
 * Please note that the use of the EtherCAT technology, the EtherCAT 
 * brand name and the EtherCAT logo is only permitted if the property 
 * rights of Beckhoff Automation GmbH are observed. For further 
 * information please contact Beckhoff Automation GmbH & Co. KG, 
 * Hülshorstweg 20, D-33415 Verl, Germany (www.beckhoff.com) or the 
 * EtherCAT Technology Group, Ostendstraße 196, D-90482 Nuremberg, 
 * Germany (ETG, www.ethercat.org).
 *
 */
 
#ifndef LIBETHERCAT_EC_H
#define LIBETHERCAT_EC_H
 
#include <libosal/types.h>
 
#include "libethercat/settings.h"
#include "libethercat/common.h"
#include "libethercat/dc.h"
#include "libethercat/slave.h"
#include "libethercat/hw.h"
#include "libethercat/regs.h"
#include "libethercat/idx.h"
#include "libethercat/datagram.h"
#include "libethercat/pool.h"
#include "libethercat/async_loop.h"
#include "libethercat/eeprom.h"
 
#if LIBETHERCAT_BUILD_POSIX == 1
#include "libethercat/veth.h"
#endif
 
#define EC_SHORT_TIMEOUT_MBX        (10000000)          
#define EC_DEFAULT_TIMEOUT_MBX      (1000000000)        
#define EC_DEFAULT_DELAY            (2000000)           
 
struct ec;
struct ec_slave;
typedef struct ec_slave ec_slave_t;
    
typedef struct ec_pd_group {
    osal_uint32_t group;            
    osal_uint32_t log;              
    osal_uint32_t log_len;          
    osal_uint8_t pd[LEC_MAX_PDLEN]; 
    osal_size_t   pdout_len;        
    osal_size_t   pdin_len;         
    osal_size_t   pd_lrw_len;       
 
    int use_lrw;                    
    int overlapping;                
 
    int skip_pd_on_wkc_mismatch;   
 
    osal_uint16_t wkc_expected_lrw; 
    osal_uint16_t wkc_expected_lrd; 
    osal_uint16_t wkc_expected_lwr; 
    int wkc_mismatch_cnt_lrw;       
    int wkc_mismatch_cnt_lrd;       
    int wkc_mismatch_cnt_lwr;       
 
    int recv_missed_lrw;            
    int recv_missed_lrd;            
    int recv_missed_lwr;            
 
 
    osal_uint32_t log_mbx_state;    
    osal_uint32_t log_mbx_state_len;
 
    osal_uint16_t wkc_expected_mbx_state;
 
    int wkc_mismatch_cnt_mbx_state; 
                                    //   flooding of log output.
 
    ec_cyclic_datagram_t cdg;       
    ec_cyclic_datagram_t cdg_lrd;   
    ec_cyclic_datagram_t cdg_lwr;   
    ec_cyclic_datagram_t cdg_lrd_mbx_state;
 
    int divisor;                    
    int divisor_cnt;                
} ec_pd_group_t;
 
typedef struct ec_statistics {
    osal_uint64_t lost_datagrams;
} ec_statistics_t;
 
typedef struct ec {
    struct hw_common *phw;          
 
    pool_entry_t dg_entries[LEC_MAX_DATAGRAMS]; 
    pool_t pool;                    
    idx_queue_t idx_q;              
    osal_int64_t main_cycle_interval;
    
    pool_entry_t mbx_mp_recv_free_entries[LEC_MAX_MBX_ENTRIES]; 
    pool_entry_t mbx_mp_send_free_entries[LEC_MAX_MBX_ENTRIES]; 
    pool_t mbx_message_pool_recv_free;  
    pool_t mbx_message_pool_send_free;  
 
    osal_uint16_t slave_cnt;        
    ec_slave_t slaves[LEC_MAX_SLAVES];             
 
    osal_uint16_t pd_group_cnt;     
    ec_pd_group_t pd_groups[LEC_MAX_GROUPS];       
 
    ec_dc_info_t dc;                
    ec_async_loop_t async_loop;
 
#if LIBETHERCAT_BUILD_POSIX == 1
    ec_veth_t veth;
#endif
    
    pool_t mbx_gw_recv_pool;        
 
    int eeprom_log;                 
    ec_state_t master_state;        
    int state_transition_pending;   
 
 
    void (*user_cb_state_transition)(void *arg, ec_t *pec, ec_state_t target_state, osal_bool_t up);
    void *user_cb_state_transition_arg;                                              
 
    int threaded_startup;           
    
    int consecutive_max_miss;       
 
    ec_cyclic_datagram_t cdg_state; 
                                    
    ec_statistics_t stats;
 
    void *ec_time_func_user;
    osal_uint64_t (*ec_time_func)(ec_t *pec);
 
    void *ec_log_func_user;
    void (*ec_log_func)(ec_t *pec, int lvl, const osal_char_t *format, ...) __attribute__ ((format (printf, 3, 4)));
} ec_t;
 
#ifdef __cplusplus
extern "C" {
#endif
 
#define ec_log(lvl, pre, format, ...) \
    _ec_log(pec, (lvl), (pre), (format), ##__VA_ARGS__)
 
 
void _ec_log(ec_t *pec, int lvl, const osal_char_t *pre, const osal_char_t *format, ...) __attribute__ ((format (printf, 4, 5)));
 
 
int ec_open(ec_t *pec, struct hw_common *phw, int eeprom_log);
 
 
int ec_close(ec_t *pec);
 
 
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);
 
 
int ec_create_pd_groups(ec_t *pec, osal_uint32_t pd_group_cnt);
 
 
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);
 
 
int ec_destroy_pd_groups(ec_t *pec);
 
 
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);
 
 
int ec_set_state(ec_t *pec, ec_state_t state);
 
#define ec_group_will_be_sent(pec, group) (int)((((pec)->pd_groups[(group)].divisor_cnt+1) % (pec)->pd_groups[(group)].divisor) == 0)   
#define ec_group_was_sent(pec, group)     (int)((pec)->pd_groups[(group)].divisor_cnt == 0)                                             
 
 
int ec_send_process_data(ec_t *pec);
 
 
int ec_send_distributed_clocks_sync(ec_t *pec);
 
 
int ec_send_distributed_clocks_sync_with_rtc(ec_t *pec, osal_uint64_t act_rtc_time);
 
 
int ec_send_brd_ec_state(ec_t *pec);
 
 
int ec_get_slave_count(ec_t *pec);
 
#ifdef __cplusplus
};
#endif
 
#define ec_to_adr(ado, adp) \
    ((osal_uint32_t)(adp) << 16u) | ((ado) & 0xFFFFu)
 
#define ec_brd(pec, ado, data, datalen, wkc) \
    ec_transceive((pec), EC_CMD_BRD, ((osal_uint32_t)(ado) << 16u), \
            (osal_uint8_t *)(data), (datalen), (wkc))
 
#define ec_bwr(pec, ado, data, datalen, wkc) \
    ec_transceive((pec), EC_CMD_BWR, ((osal_uint32_t)(ado) << 16u), \
            (osal_uint8_t *)(data), (datalen), (wkc))
 
#define ec_brw(pec, ado, data, datalen, wkc) \
    ec_transceive((pec), EC_CMD_BRW, ((osal_uint32_t)(ado) << 16u), \
            (osal_uint8_t *)(data), (datalen), (wkc))
 
#define ec_aprd(pec, adp, ado, data, datalen, wkc) \
    ec_transceive((pec), EC_CMD_APRD, ((osal_uint32_t)(ado) << 16u) | \
            (*(osal_uint16_t *)&(adp) & 0xFFFFu), (osal_uint8_t *)(data), (datalen), (wkc))
 
#define ec_apwr(pec, adp, ado, data, datalen, wkc) \
    ec_transceive((pec), EC_CMD_APWR, ((osal_uint32_t)(ado) << 16u) | \
            (*(osal_uint16_t *)&(adp) & 0xFFFFu), (osal_uint8_t *)(data), (datalen), (wkc))
 
#define ec_aprw(pec, adp, ado, data, datalen, wkc) \
    ec_transceive((pec), EC_CMD_APRW, ((osal_uint32_t)(ado) << 16u) | \
            (*(osal_uint16_t *)&(adp) & 0xFFFFu), (osal_uint8_t *)(data), (datalen), (wkc))
 
#define ec_fprd(pec, adp, ado, data, datalen, wkc) \
    ec_transceive((pec), EC_CMD_FPRD, ((osal_uint32_t)(ado) << 16lu) | \
            (osal_uint32_t)((adp) & 0xFFFFu), (osal_uint8_t *)(data), (datalen), (wkc))
 
#define ec_fpwr(pec, adp, ado, data, datalen, wkc) \
    ec_transceive((pec), EC_CMD_FPWR, ((osal_uint32_t)(ado) << 16u) | \
            ((adp) & 0xFFFFu), (osal_uint8_t *)(data), (datalen), (wkc))
 
#define ec_fprw(pec, adp, ado, data, datalen, wkc) \
    ec_transceive((pec), EC_CMD_FPRW, ((osal_uint32_t)(ado) << 16u) | \
            ((adp) & 0xFFFFu), (osal_uint8_t *)(data), (datalen), (wkc))
 
#define ec_frmw(pec, adp, ado, data, datalen, wkc) \
    ec_transceive((pec), EC_CMD_FRMW, ((osal_uint32_t)(ado) << 16u) | \
            ((adp) & 0xFFFFu), (osal_uint8_t *)(data), (datalen), (wkc))
 
#define check_ret(fcn, ...) { \
    if (fcn(__VA_ARGS__) != EC_OK) { \
        ec_log(1, __func__, "" #fcn "(" #__VA_ARGS__ ") failed!\n"); \
    } }
 
#define check_ec_bwr(...)  check_ret(ec_bwr, __VA_ARGS__)   
#define check_ec_brd(...)  check_ret(ec_brd, __VA_ARGS__)   
#define check_ec_brw(...)  check_ret(ec_brw, __VA_ARGS__)   
 
#define check_ec_apwr(...)  check_ret(ec_apwr, __VA_ARGS__) 
#define check_ec_aprd(...)  check_ret(ec_aprd, __VA_ARGS__) 
#define check_ec_aprw(...)  check_ret(ec_aprw, __VA_ARGS__) 
 
#define check_ec_fpwr(...)  check_ret(ec_fpwr, __VA_ARGS__) 
#define check_ec_fprd(...)  check_ret(ec_fprd, __VA_ARGS__) 
#define check_ec_fprw(...)  check_ret(ec_fprw, __VA_ARGS__) 
#define check_ec_frmw(...)  check_ret(ec_frmw, __VA_ARGS__) 
 
#endif // LIBETHERCAT_EC_H