fp@104: /******************************************************************************
fp@104:  *
fp@125:  *  $Id$
fp@104:  *
fp@197:  *  Copyright (C) 2006  Florian Pose, Ingenieurgemeinschaft IgH
fp@197:  *
fp@197:  *  This file is part of the IgH EtherCAT Master.
fp@197:  *
fp@197:  *  The IgH EtherCAT Master is free software; you can redistribute it
fp@197:  *  and/or modify it under the terms of the GNU General Public License
fp@246:  *  as published by the Free Software Foundation; either version 2 of the
fp@246:  *  License, or (at your option) any later version.
fp@197:  *
fp@197:  *  The IgH EtherCAT Master is distributed in the hope that it will be
fp@197:  *  useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
fp@197:  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
fp@197:  *  GNU General Public License for more details.
fp@197:  *
fp@197:  *  You should have received a copy of the GNU General Public License
fp@197:  *  along with the IgH EtherCAT Master; if not, write to the Free Software
fp@197:  *  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
fp@197:  *
fp@246:  *  The right to use EtherCAT Technology is granted and comes free of
fp@246:  *  charge under condition of compatibility of product made by
fp@246:  *  Licensee. People intending to distribute/sell products based on the
fp@246:  *  code, have to sign an agreement to guarantee that products using
fp@246:  *  software based on IgH EtherCAT master stay compatible with the actual
fp@246:  *  EtherCAT specification (which are released themselves as an open
fp@246:  *  standard) as the (only) precondition to have the right to use EtherCAT
fp@246:  *  Technology, IP and trade marks.
fp@246:  *
fp@104:  *****************************************************************************/
fp@104: 
fp@199: /**
fp@199:    \file
fp@199:    EtherCAT realtime interface.
fp@199: */
fp@199: 
fp@199: /**
fp@199:    \defgroup RealtimeInterface EtherCAT realtime interface
fp@199:    EtherCAT interface for realtime modules.
fp@199:    This interface is designed for realtime modules that want to use EtherCAT.
fp@199:    There are functions to request a master, to map process data, to communicate
fp@199:    with slaves via CoE and to configure and activate the bus.
fp@199: */
fp@199: 
fp@199: /*****************************************************************************/
fp@199: 
fp@125: #ifndef __ECRT_H__
fp@125: #define __ECRT_H__
fp@104: 
fp@104: #include <asm/byteorder.h>
fp@104: 
fp@110: #ifdef __KERNEL__
fp@110: #include <linux/types.h>
fp@110: #else
fp@110: #include <stdint.h>
fp@110: #endif
fp@110: 
fp@104: /*****************************************************************************/
fp@104: 
fp@1746: /**
fp@1746:  * EtherCAT real-time interface major version number.
fp@1746:  */
fp@1744: #define ECRT_VER_MAJOR 1
fp@1746: 
fp@1746: /**
fp@1746:  * EtherCAT real-time interface minor version number.
fp@1746:  */
fp@1744: #define ECRT_VER_MINOR 3
fp@1739: 
fp@1746: /**
fp@1746:  * EtherCAT real-time interface version word generator.
fp@1746:  */
fp@1739: #define ECRT_VERSION(a,b) (((a) << 8) + (b))
fp@1746: 
fp@1746: /**
fp@1746:  * EtherCAT real-time interface version word.
fp@1746:  */
fp@1739: #define ECRT_VERSION_MAGIC ECRT_VERSION(ECRT_VER_MAJOR, ECRT_VER_MINOR)
fp@1739: 
fp@1739: /*****************************************************************************/
fp@1739: 
fp@104: struct ec_master;
fp@286: typedef struct ec_master ec_master_t; /**< \see ec_master */
fp@104: 
fp@104: struct ec_domain;
fp@286: typedef struct ec_domain ec_domain_t; /**< \see ec_domain */
fp@104: 
fp@104: struct ec_slave;
fp@286: typedef struct ec_slave ec_slave_t; /**< \see ec_slave */
fp@104: 
fp@200: /**
fp@1744:  * Bus status.
fp@1744:  */
fp@1744: 
fp@1744: typedef enum {
fp@1744:     EC_BUS_FAILURE = -1, /**< At least one slave with process data exchange
fp@1744:                            is offline. */
fp@1744:     EC_BUS_OK            /**< All slaves with process data exchange are
fp@1744:                            online. */
fp@1744: }
fp@1744: ec_bus_status_t;
fp@1744: 
fp@1744: /**
fp@1744:  * Master status.
fp@1744:  * This is used for the output parameter of ecrt_master_get_status().
fp@1744:  */
fp@1744: 
fp@1744: typedef struct {
fp@1744:     ec_bus_status_t bus_status; /**< \see ec_bus_status_t */
fp@1744:     unsigned int bus_tainted; /**< non-zero, if the bus topology is invalid */
fp@1744:     unsigned int slaves_responding; /**< number of responging slaves */
fp@1744: }
fp@1744: ec_master_status_t;
fp@1744: 
fp@1744: /**
fp@1744:  * List entry for domain PDO registrations.
fp@1744:  * This type is used as a parameter for the ecrt_domain_register_pdo_list()
fp@1744:  * convenience function.
fp@1744:  */
fp@1744: 
fp@1744: typedef struct {
fp@1744:     const char *slave_address; /**< slave address string
fp@1744:                                  \see ec_master_parse_slave_address() */
fp@1715:     uint32_t vendor_id; /**< vendor ID */
fp@1715:     uint32_t product_code; /**< product code */
fp@1744:     uint16_t pdo_entry_index; /**< PDO entry index */
fp@1744:     uint8_t pdo_entry_subindex; /**< PDO entry subindex */
fp@1715:     void **data_ptr; /**< address of the process data pointer */
fp@104: }
fp@1715: ec_pdo_reg_t;
fp@104: 
fp@1732: /**
fp@1744:  * Direction type for PDO mapping and range registration functions.
fp@1744:  */
fp@1744: 
fp@1744: typedef enum {
fp@1744:     EC_DIR_OUTPUT, /**< values written by master */
fp@1744:     EC_DIR_INPUT   /**< values read by master */
fp@1744: }
fp@1744: ec_direction_t;
fp@1744: 
fp@1744: /******************************************************************************
fp@1744:  *  Global functions
fp@199:  *****************************************************************************/
fp@104: 
fp@104: ec_master_t *ecrt_request_master(unsigned int master_index);
fp@104: void ecrt_release_master(ec_master_t *master);
fp@104: 
fp@1739: unsigned int ecrt_version_magic(void);
fp@1739: 
fp@199: /******************************************************************************
fp@199:  *  Master methods
fp@199:  *****************************************************************************/
fp@104: 
fp@204: void ecrt_master_callbacks(ec_master_t *master, int (*request_cb)(void *),
fp@204:                            void (*release_cb)(void *), void *cb_data);
fp@204: 
fp@104: ec_domain_t *ecrt_master_create_domain(ec_master_t *master);
fp@138: 
fp@1744: ec_slave_t *ecrt_master_get_slave(const ec_master_t *, const char *,
fp@1744:         uint32_t vendor_id, uint32_t product_code);
fp@1744: ec_slave_t *ecrt_master_get_slave_by_pos(const ec_master_t *, uint16_t,
fp@1744:         uint32_t vendor_id, uint32_t product_code);
fp@1744: 
fp@104: int ecrt_master_activate(ec_master_t *master);
fp@1715: 
fp@1715: void ecrt_master_send(ec_master_t *master);
fp@1715: void ecrt_master_receive(ec_master_t *master);
fp@138: 
fp@1744: void ecrt_master_get_status(const ec_master_t *master, ec_master_status_t *);
fp@1715: 
fp@199: /******************************************************************************
fp@199:  *  Domain Methods
fp@199:  *****************************************************************************/
fp@104: 
fp@1744: int ecrt_domain_register_pdo(ec_domain_t *domain, ec_slave_t *slave,
fp@1744:         uint16_t pdo_index, uint8_t pdo_subindex, void **data_ptr);
fp@1744: 
fp@1744: int ecrt_domain_register_pdo_range(ec_domain_t *domain, ec_slave_t *slave,
fp@1744:         ec_direction_t direction, uint16_t offset, uint16_t length,
fp@1744:         void **data_ptr);
fp@1732: 
fp@1715: int ecrt_domain_register_pdo_list(ec_domain_t *domain,
fp@1744:         const ec_pdo_reg_t *pdos);
fp@1732: 
fp@104: void ecrt_domain_process(ec_domain_t *domain);
fp@1739: void ecrt_domain_queue(ec_domain_t *domain);
fp@1744: 
fp@1715: int ecrt_domain_state(const ec_domain_t *domain);
fp@104: 
fp@199: /******************************************************************************
fp@199:  *  Slave Methods
fp@199:  *****************************************************************************/
fp@104: 
fp@1715: int ecrt_slave_conf_sdo8(ec_slave_t *slave, uint16_t sdo_index,
fp@1715:                          uint8_t sdo_subindex, uint8_t value);
fp@1715: int ecrt_slave_conf_sdo16(ec_slave_t *slave, uint16_t sdo_index,
fp@1715:                           uint8_t sdo_subindex, uint16_t value);
fp@1715: int ecrt_slave_conf_sdo32(ec_slave_t *slave, uint16_t sdo_index,
fp@1715:                           uint8_t sdo_subindex, uint32_t value);
fp@1715: 
fp@1744: void ecrt_slave_pdo_mapping_clear(ec_slave_t *, ec_direction_t);
fp@1744: int ecrt_slave_pdo_mapping_add(ec_slave_t *, ec_direction_t, uint16_t);
fp@1744: int ecrt_slave_pdo_mapping(ec_slave_t *, ec_direction_t, unsigned int, ...);
fp@1744: 
fp@199: /******************************************************************************
fp@199:  *  Bitwise read/write macros
fp@199:  *****************************************************************************/
fp@199: 
fp@199: /**
fp@1744:  * Read a certain bit of an EtherCAT data byte.
fp@1744:  * \param DATA EtherCAT data pointer
fp@1744:  * \param POS bit position
fp@1744:  */
fp@199: 
fp@199: #define EC_READ_BIT(DATA, POS) ((*((uint8_t *) (DATA)) >> (POS)) & 0x01)
fp@199: 
fp@199: /**
fp@1744:  * Write a certain bit of an EtherCAT data byte.
fp@1744:  * \param DATA EtherCAT data pointer
fp@1744:  * \param POS bit position
fp@1744:  * \param VAL new bit value
fp@1744:  */
fp@199: 
fp@199: #define EC_WRITE_BIT(DATA, POS, VAL) \
fp@199:     do { \
fp@199:         if (VAL) *((uint8_t *) (DATA)) |=  (1 << (POS)); \
fp@199:         else     *((uint8_t *) (DATA)) &= ~(1 << (POS)); \
fp@199:     } while (0)
fp@199: 
fp@199: /******************************************************************************
fp@199:  *  Read macros
fp@199:  *****************************************************************************/
fp@199: 
fp@199: /**
fp@1744:  * Read an 8-bit unsigned value from EtherCAT data.
fp@1744:  * \return EtherCAT data value
fp@1744:  */
fp@199: 
fp@199: #define EC_READ_U8(DATA) \
fp@199:     ((uint8_t) *((uint8_t *) (DATA)))
fp@199: 
fp@199: /**
fp@1744:  * Read an 8-bit signed value from EtherCAT data.
fp@1744:  * \param DATA EtherCAT data pointer
fp@1744:  * \return EtherCAT data value
fp@1744:  */
fp@199: 
fp@199: #define EC_READ_S8(DATA) \
fp@288:      ((int8_t) *((uint8_t *) (DATA)))
fp@199: 
fp@199: /**
fp@1744:  * Read a 16-bit unsigned value from EtherCAT data.
fp@1744:  * \param DATA EtherCAT data pointer
fp@1744:  * \return EtherCAT data value
fp@1744:  */
fp@199: 
fp@199: #define EC_READ_U16(DATA) \
fp@199:      ((uint16_t) le16_to_cpup((void *) (DATA)))
fp@199: 
fp@199: /**
fp@1744:  * Read a 16-bit signed value from EtherCAT data.
fp@1744:  * \param DATA EtherCAT data pointer
fp@1744:  * \return EtherCAT data value
fp@1744:  */
fp@199: 
fp@199: #define EC_READ_S16(DATA) \
fp@288:      ((int16_t) le16_to_cpup((void *) (DATA)))
fp@199: 
fp@199: /**
fp@1744:  * Read a 32-bit unsigned value from EtherCAT data.
fp@1744:  * \param DATA EtherCAT data pointer
fp@1744:  * \return EtherCAT data value
fp@1744:  */
fp@199: 
fp@199: #define EC_READ_U32(DATA) \
fp@199:      ((uint32_t) le32_to_cpup((void *) (DATA)))
fp@199: 
fp@199: /**
fp@1744:  * Read a 32-bit signed value from EtherCAT data.
fp@1744:  * \param DATA EtherCAT data pointer
fp@1744:  * \return EtherCAT data value
fp@1744:  */
fp@199: 
fp@199: #define EC_READ_S32(DATA) \
fp@288:      ((int32_t) le32_to_cpup((void *) (DATA)))
fp@199: 
fp@199: /******************************************************************************
fp@199:  *  Write macros
fp@199:  *****************************************************************************/
fp@199: 
fp@199: /**
fp@1744:  * Write an 8-bit unsigned value to EtherCAT data.
fp@1744:  * \param DATA EtherCAT data pointer
fp@1744:  * \param VAL new value
fp@1744:  */
fp@199: 
fp@199: #define EC_WRITE_U8(DATA, VAL) \
fp@199:     do { \
fp@199:         *((uint8_t *)(DATA)) = ((uint8_t) (VAL)); \
fp@199:     } while (0)
fp@199: 
fp@199: /**
fp@1744:  * Write an 8-bit signed value to EtherCAT data.
fp@1744:  * \param DATA EtherCAT data pointer
fp@1744:  * \param VAL new value
fp@1744:  */
fp@199: 
fp@199: #define EC_WRITE_S8(DATA, VAL) EC_WRITE_U8(DATA, VAL)
fp@199: 
fp@199: /**
fp@1744:  * Write a 16-bit unsigned value to EtherCAT data.
fp@1744:  * \param DATA EtherCAT data pointer
fp@1744:  * \param VAL new value
fp@1744:  */
fp@199: 
fp@199: #define EC_WRITE_U16(DATA, VAL) \
fp@199:     do { \
fp@199:         *((uint16_t *) (DATA)) = (uint16_t) (VAL); \
fp@199:         cpu_to_le16s(DATA); \
fp@199:     } while (0)
fp@199: 
fp@199: /**
fp@1744:  * Write a 16-bit signed value to EtherCAT data.
fp@1744:  * \param DATA EtherCAT data pointer
fp@1744:  * \param VAL new value
fp@1744:  */
fp@199: 
fp@199: #define EC_WRITE_S16(DATA, VAL) EC_WRITE_U16(DATA, VAL)
fp@199: 
fp@199: /**
fp@1744:  * Write a 32-bit unsigned value to EtherCAT data.
fp@1744:  * \param DATA EtherCAT data pointer
fp@1744:  * \param VAL new value
fp@1744:  */
fp@199: 
fp@199: #define EC_WRITE_U32(DATA, VAL) \
fp@199:     do { \
fp@199:         *((uint32_t *) (DATA)) = (uint32_t) (VAL); \
fp@1745:         cpu_to_le32s(DATA); \
fp@199:     } while (0)
fp@199: 
fp@199: /**
fp@1744:  * Write a 32-bit signed value to EtherCAT data.
fp@1744:  * \param DATA EtherCAT data pointer
fp@1744:  * \param VAL new value
fp@1744:  */
fp@199: 
fp@199: #define EC_WRITE_S32(DATA, VAL) EC_WRITE_U32(DATA, VAL)
fp@199: 
fp@104: /*****************************************************************************/
fp@104: 
fp@104: #endif