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@786: /** \file fp@786: * fp@864: * EtherCAT Realtime Interface. fp@864: * fp@864: * \defgroup RealtimeInterface EtherCAT Realtime Interface fp@786: * fp@879: * EtherCAT interface for realtime applications. This interface is designed fp@879: * for realtime modules that want to use EtherCAT. There are functions to fp@879: * request a master, to map process data, to communicate with slaves via CoE fp@879: * and to configure and activate the bus. fp@792: * fp@792: * Changes in Version 1.4: fp@792: * fp@792: * - Replaced ec_slave_t with ec_slave_config_t, separating the slave objects fp@792: * from the requested bus configuration. Therefore, renamed fp@792: * ecrt_master_get_slave() to ecrt_master_slave_config(). fp@792: * - Replaced slave address string with alias and position values. See fp@792: * ecrt_master_slave_config(). fp@792: * - Removed ecrt_master_get_slave_by_pos(), because it is no longer fp@807: * necessary due to alias/position addressing. fp@792: * - Added ec_slave_config_state_t for the new method fp@792: * ecrt_slave_config_state(). fp@792: * - Process data memory for a domain can now be allocated externally. This fp@842: * offers the possibility to use a shared-memory region. Therefore, fp@809: * added the domain methods ecrt_domain_size() and fp@809: * ecrt_domain_external_memory(). fp@792: * - Replaced the process data pointers in the Pdo entry registration fp@792: * functions with a process data offset, that is now returned by fp@807: * ecrt_slave_config_reg_pdo_entry(). This was necessary for the external fp@792: * domain memory. An additional advantage is, that the returned offset value fp@809: * is directly usable. If the domain's process data is allocated internally, fp@809: * the start address can be retrieved with ecrt_domain_data(). fp@792: * - Replaced ecrt_slave_pdo_mapping/add/clear() with fp@879: * ecrt_slave_config_pdo_assign_add() to add a Pdo to a sync manager's Pdo fp@879: * assignment and ecrt_slave_config_pdo_mapping_add() to add a Pdo entry to a fp@879: * Pdo's mapping. ecrt_slave_config_pdos() is a convenience function fp@879: * for both, that uses the new data types ec_pdo_info_t and fp@879: * ec_pdo_entry_info_t. Pdo entries, that are mapped with these functions fp@879: * can now immediately be registered, even if the bus is offline. fp@792: * - Renamed ec_bus_status_t, ec_master_status_t to ec_bus_state_t and fp@792: * ec_master_state_t, respectively. Renamed ecrt_master_get_status() to fp@792: * ecrt_master_state(), for consistency reasons. fp@792: * - Added ec_domain_state_t and ec_wc_state_t for a new output parameter fp@832: * of ecrt_domain_state(). The domain state object does now contain fp@832: * information, if the process data was exchanged completely. fp@792: * - Former "Pdo registration" meant Pdo entry registration in fact, therefore fp@792: * renamed ec_pdo_reg_t to ec_pdo_entry_reg_t and ecrt_domain_register_pdo() fp@807: * to ecrt_slave_config_reg_pdo_entry(). fp@792: * - Removed ecrt_domain_register_pdo_range(), because it's functionality can fp@792: * be reached by specifying an explicit Pdo mapping and registering those fp@792: * Pdo entries. fp@864: * - Added an Sdo access interface, working with Sdo requests. These can be fp@864: * scheduled for reading and writing during realtime operation. fp@792: * fp@792: * @{ fp@786: */ fp@199: fp@199: /*****************************************************************************/ fp@199: fp@125: #ifndef __ECRT_H__ fp@125: #define __ECRT_H__ fp@104: fp@104: #include fp@104: fp@110: #ifdef __KERNEL__ fp@110: #include fp@110: #else fp@110: #include fp@110: #endif fp@110: fp@779: /****************************************************************************** fp@779: * Global definitions fp@779: *****************************************************************************/ fp@779: fp@864: /** EtherCAT realtime interface major version number. fp@758: */ fp@637: #define ECRT_VER_MAJOR 1 fp@758: fp@864: /** EtherCAT realtime interface minor version number. fp@779: */ fp@779: #define ECRT_VER_MINOR 4 fp@779: fp@864: /** EtherCAT realtime interface version word generator. fp@779: */ fp@779: #define ECRT_VERSION(a, b) (((a) << 8) + (b)) fp@779: fp@864: /** EtherCAT realtime interface version word. fp@758: */ fp@541: #define ECRT_VERSION_MAGIC ECRT_VERSION(ECRT_VER_MAJOR, ECRT_VER_MINOR) fp@541: fp@878: /*****************************************************************************/ fp@878: fp@879: /** End of the Pdo list. fp@879: * fp@879: * This is used in ecrt_slave_config_pdos(). fp@879: */ fp@879: #define EC_END ~0U fp@878: fp@779: /****************************************************************************** fp@779: * Data types fp@779: *****************************************************************************/ fp@541: fp@104: struct ec_master; fp@286: typedef struct ec_master ec_master_t; /**< \see ec_master */ fp@104: fp@792: struct ec_slave_config; fp@792: typedef struct ec_slave_config ec_slave_config_t; /**< \see ec_slave_config */ fp@792: fp@104: struct ec_domain; fp@286: typedef struct ec_domain ec_domain_t; /**< \see ec_domain */ fp@104: fp@858: struct ec_sdo_request; fp@858: typedef struct ec_sdo_request ec_sdo_request_t; /**< \see ec_sdo_request. */ fp@858: fp@792: /*****************************************************************************/ fp@792: fp@792: /** Bus state. fp@792: * fp@792: * This is used in ec_master_state_t. fp@879: * fp@879: * \deprecated fp@879: * \todo remove fp@779: */ fp@612: typedef enum { fp@792: EC_BUS_FAILURE = -1, /**< At least one configured slave is offline. */ fp@792: EC_BUS_OK /**< All configured slaves are online. */ fp@792: } ec_bus_state_t; fp@792: fp@792: /*****************************************************************************/ fp@792: fp@792: /** Master state. fp@792: * fp@792: * This is used for the output parameter of ecrt_master_state(). fp@612: */ fp@612: typedef struct { fp@792: ec_bus_state_t bus_state; /**< \see ec_bus_state_t */ fp@792: unsigned int bus_tainted; /**< Non-zero, if the bus topology differs from fp@792: the requested configuration. */ fp@792: unsigned int slaves_responding; /**< Number of slaves in the bus. */ fp@792: } ec_master_state_t; fp@792: fp@792: /*****************************************************************************/ fp@792: fp@792: /** Slave configuration state. fp@792: * fp@792: * \see ecrt_slave_config_state(). fp@792: */ fp@792: typedef struct { fp@792: unsigned int online : 1; /**< The slave is online. */ fp@792: unsigned int configured : 1; /**< The slave was configured according to fp@792: the specified configuration. */ fp@792: } ec_slave_config_state_t; fp@792: fp@792: /*****************************************************************************/ fp@792: fp@792: /** Domain working counter interpretation. fp@792: * fp@792: * This is used in ec_domain_state_t. fp@792: */ fp@792: typedef enum { fp@792: EC_WC_ZERO = 0, /**< No Pdos were exchanged. */ fp@792: EC_WC_INCOMPLETE, /**< Some of the registered Pdos were exchanged. */ fp@792: EC_WC_COMPLETE /**< All registered Pdos were exchanged. */ fp@792: } ec_wc_state_t; fp@792: fp@792: /*****************************************************************************/ fp@792: fp@792: /** Domain state. fp@792: * fp@792: * This is used for the output parameter of ecrt_domain_state(). fp@640: */ fp@640: typedef struct { fp@792: unsigned int working_counter; /**< Value of the last working counter. */ fp@792: ec_wc_state_t wc_state; /**< Working counter interpretation. */ fp@792: } ec_domain_state_t; fp@792: fp@792: /*****************************************************************************/ fp@792: fp@792: /** Direction type for Pdo mapping functions. fp@779: */ fp@635: typedef enum { fp@792: EC_DIR_OUTPUT, /**< Values written by the master. */ fp@792: EC_DIR_INPUT /**< Values read by the master. */ fp@792: } ec_direction_t; fp@792: fp@792: /*****************************************************************************/ fp@792: fp@879: /** Pdo entry information. fp@879: * fp@879: * This can be used to map multiple Pdo entries into a given Pdo using fp@879: * ecrt_slave_config_pdos(). fp@792: */ fp@792: typedef struct { fp@792: uint16_t index; /**< Index of the Pdo entry to add to the Pdo fp@792: configuration. */ fp@792: uint8_t subindex; /**< Subindex of the Pdo entry to add to the fp@792: Pdo configuration. */ fp@792: uint8_t bit_length; /**< Size of the Pdo entry in bit. */ fp@792: } ec_pdo_entry_info_t; fp@792: fp@792: /*****************************************************************************/ fp@792: fp@792: /** Pdo information. fp@792: * fp@879: * This can be use to assign multiple Pdos to a sync manager using fp@879: * ecrt_slave_config_pdos(). fp@792: */ fp@792: typedef struct { fp@792: ec_direction_t dir; /**< Pdo direction (input/output). */ fp@792: uint16_t index; /**< Index of the Pdo to map. */ fp@879: unsigned int n_entries; /**< Number of Pdo entries in \a entries to map. fp@879: Zero means, that the default mapping shall be fp@879: used. */ fp@879: ec_pdo_entry_info_t *entries; /**< Array of Pdo entries to map. This must fp@879: contain at least \a n_entries values. */ fp@792: } ec_pdo_info_t; fp@792: fp@792: /*****************************************************************************/ fp@792: fp@792: /** List record type for Pdo entry mass-registration. fp@792: * fp@792: * This type is used for the array parameter of the fp@792: * ecrt_domain_reg_pdo_entry_list() convenience function. fp@792: */ fp@792: typedef struct { fp@792: uint16_t alias; /**< Slave alias address. */ fp@792: uint16_t position; /**< Slave position. */ fp@792: uint32_t vendor_id; /**< Slave vendor ID. */ fp@792: uint32_t product_code; /**< Slave product code. */ fp@792: uint16_t index; /**< Pdo entry index. */ fp@792: uint8_t subindex; /**< Pdo entry subindex. */ fp@809: unsigned int *offset; /**< Pointer to a variable to store the Pdo's fp@792: offset in the process data. */ fp@792: } ec_pdo_entry_reg_t; fp@416: fp@858: /*****************************************************************************/ fp@858: fp@861: /** Sdo request state. fp@861: * fp@861: * This is used as return type of ecrt_sdo_request_state(). fp@858: */ fp@858: typedef enum { fp@861: EC_SDO_REQUEST_UNUSED, /**< Not requested. */ fp@861: EC_SDO_REQUEST_BUSY, /**< Request is being processed. */ fp@861: EC_SDO_REQUEST_SUCCESS, /**< Request was processed successfully. */ fp@861: EC_SDO_REQUEST_ERROR, /**< Request processing failed. */ fp@861: } ec_sdo_request_state_t; fp@858: fp@199: /****************************************************************************** fp@779: * Global functions fp@199: *****************************************************************************/ fp@104: fp@792: /** Returns the version magic of the realtime interface. fp@792: * fp@792: * \return Value of ECRT_VERSION_MAGIC() at EtherCAT master compile time. fp@792: */ fp@541: unsigned int ecrt_version_magic(void); fp@541: fp@792: /** Requests an EtherCAT master for realtime operation. fp@792: * fp@792: * \return pointer to reserved master, or NULL on error fp@792: */ fp@792: ec_master_t *ecrt_request_master( fp@792: unsigned int master_index /**< Index of the master to request. */ fp@792: ); fp@792: fp@792: /** Releases a requested EtherCAT master. fp@792: */ fp@792: void ecrt_release_master( fp@792: ec_master_t *master /**< EtherCAT master */ fp@792: ); fp@792: fp@199: /****************************************************************************** fp@779: * Master methods fp@199: *****************************************************************************/ fp@104: fp@792: /** Sets the locking callbacks. fp@792: * fp@792: * The request_cb function must return zero, to allow another instance fp@792: * (the EoE process for example) to access the master. Non-zero means, fp@792: * that access is forbidden at this time. fp@792: */ fp@792: void ecrt_master_callbacks( fp@792: ec_master_t *master, /**< EtherCAT master */ fp@792: int (*request_cb)(void *), /**< Lock request function. */ fp@792: void (*release_cb)(void *), /**< Lock release function. */ fp@792: void *cb_data /**< Arbitrary user data. */ fp@792: ); fp@792: fp@792: /** Creates a new domain. fp@792: * fp@792: * \return Pointer to the new domain on success, else NULL. fp@792: */ fp@792: ec_domain_t *ecrt_master_create_domain( fp@792: ec_master_t *master /**< EtherCAT master. */ fp@792: ); fp@792: fp@792: /** Obtains a slave configuration. fp@792: * fp@792: * Creates a slave configuration object for the given \a alias and \a position fp@792: * tuple and returns it. If a configuration with the same \a alias and \a fp@792: * position already exists, it will be re-used. In the latter case, the given fp@792: * vendor ID and product code are compared to the stored ones. On mismatch, an fp@792: * error message is raised and the function returns \a NULL. fp@792: * fp@792: * Slaves are addressed with the \a alias and \a position parameters. fp@792: * - If \a alias is zero, \a position is interpreted as the desired slave's fp@792: * ring position. fp@792: * - If \a alias is non-zero, it matches a slave with the given alias. In this fp@792: * case, \a position is interpreted as ring offset, starting from the fp@792: * aliased slave, so a position of zero means the aliased slave itself and a fp@792: * positive value matches the n-th slave behind the aliased one. fp@792: * fp@792: * If the slave with the given address is found during the bus configuration, fp@792: * its vendor ID and product code are matched against the given value. On fp@792: * mismatch, the slave is not configured and an error message is raised. fp@792: * fp@792: * If different slave configurations are pointing to the same slave during bus fp@792: * configuration, a warning is raised and only the first configuration is fp@792: * applied. fp@792: * fp@792: * \retval >0 Pointer to the slave configuration structure. fp@792: * \retval NULL in the error case. fp@792: */ fp@792: ec_slave_config_t *ecrt_master_slave_config( fp@792: ec_master_t *master, /**< EtherCAT master */ fp@792: uint16_t alias, /**< Slave alias. */ fp@792: uint16_t position, /**< Slave position. */ fp@792: uint32_t vendor_id, /**< Expected vendor ID. */ fp@792: uint32_t product_code /**< Expected product code. */ fp@792: ); fp@792: fp@879: /** Finishes the configuration phase and prepares for realtime mode. fp@879: * fp@879: * This function has to be called after all Pdo entries are registered. It fp@879: * tells the master that the configuration phase is finished and the realtime fp@879: * operation will begin. The function allocates internal memory for the fp@879: * domains and calculates the logical FMMU addresses for domain members. It fp@879: * tells the master state machine that the bus configuration is now to be fp@879: * applied. fp@879: * fp@879: * \attention After this function has been called, the realtime application is fp@879: * in charge of cyclically calling ecrt_master_send() and fp@879: * ecrt_master_receive() to ensure bus communication. Before calling this fp@879: * function, the master thread is responsible for that, so these functions may fp@879: * not be called! fp@792: * fp@792: * \return 0 in case of success, else < 0 fp@792: */ fp@879: int ecrt_master_activate( ec_master_t *master /**< EtherCAT master. */); fp@792: fp@792: /** Sends all datagrams in the queue. fp@792: * fp@879: * This has to be called cyclically by the realtime application after fp@879: * ecrt_master_activate() has returned. fp@792: */ fp@792: void ecrt_master_send( fp@792: ec_master_t *master /**< EtherCAT master. */ fp@792: ); fp@792: fp@792: /** Fetches received frames from the hardware and processes the datagrams. fp@879: * fp@879: * This has to be called cyclically by the realtime application after fp@879: * ecrt_master_activate() has returned. fp@792: */ fp@792: void ecrt_master_receive( fp@792: ec_master_t *master /**< EtherCAT master. */ fp@792: ); fp@792: fp@792: /** Reads the current master state. fp@792: * fp@792: * Stores the master state information in the given \a state structure. fp@792: */ fp@792: void ecrt_master_state( fp@792: const ec_master_t *master, /**< EtherCAT master. */ fp@792: ec_master_state_t *state /**< Structure to store the information. */ fp@792: ); fp@792: fp@792: /****************************************************************************** fp@792: * Slave configuration methods fp@792: *****************************************************************************/ fp@792: fp@879: /** Add a Pdo to a sync manager's Pdo assignment. fp@879: * fp@879: * \see ecrt_slave_config_pdos() fp@842: * \return zero on success, else non-zero fp@842: */ fp@879: int ecrt_slave_config_pdo_assign_add( fp@842: ec_slave_config_t *sc, /**< Slave configuration. */ fp@879: ec_direction_t dir, /**< Sync manager direction (input/output). */ fp@879: uint16_t index /**< Index of the Pdo to assign. */ fp@879: ); fp@879: fp@879: /** Clear a sync manager's Pdo assignment. fp@879: * fp@879: * This can be called before assigning Pdos via fp@879: * ecrt_slave_config_pdo_assign_add(), to clear the default assignment. fp@879: */ fp@879: void ecrt_slave_config_pdo_assign_clear( fp@879: ec_slave_config_t *sc, /**< Slave configuration. */ fp@879: ec_direction_t dir /**< Sync manager direction (input/output). */ fp@879: ); fp@879: fp@879: /** Add a Pdo entry to the given Pdo's mapping. fp@879: * fp@879: * \see ecrt_slave_config_pdos() fp@842: * \return zero on success, else non-zero fp@842: */ fp@879: int ecrt_slave_config_pdo_mapping_add( fp@842: ec_slave_config_t *sc, /**< Slave configuration. */ fp@879: uint16_t pdo_index, /**< Index of the Pdo. */ fp@842: uint16_t entry_index, /**< Index of the Pdo entry to add to the Pdo's fp@879: mapping. */ fp@842: uint8_t entry_subindex, /**< Subindex of the Pdo entry to add to the fp@879: Pdo's mapping. */ fp@842: uint8_t entry_bit_length /**< Size of the Pdo entry in bit. */ fp@842: ); fp@842: fp@879: /** Clear the mapping of a given Pdo. fp@879: * fp@879: * This can be called before mapping Pdo entries via fp@879: * ecrt_slave_config_pdo_mapping_add(), to clear the default mapping. fp@879: */ fp@879: void ecrt_slave_config_pdo_mapping_clear( fp@879: ec_slave_config_t *sc, /**< Slave configuration. */ fp@879: uint16_t pdo_index /**< Index of the Pdo. */ fp@879: ); fp@879: fp@879: /** Specify the Pdo assignment and (optionally) the Pdo mappings. fp@879: * fp@879: * This function is a convenience wrapper for the functions fp@879: * ecrt_slave_config_pdo_assign_clear(), ecrt_slave_config_pdo_assign_add(), fp@879: * ecrt_slave_config_pdo_mapping_clear() and fp@879: * ecrt_slave_config_pdo_mapping_add(), that are better suitable for automatic fp@879: * code generation. fp@879: * fp@879: * The following example shows, how to specify a complete Pdo assignment fp@879: * including the Pdo mappings. With this information, the master is able to fp@879: * reserve the complete process data, even if the slave is not present at fp@879: * configuration time: fp@792: * fp@792: * \code fp@842: * const ec_pdo_entry_info_t el3162_channel1[] = { fp@842: * {0x3101, 1, 8}, // status fp@842: * {0x3101, 2, 16} // value fp@792: * }; fp@792: * fp@842: * const ec_pdo_entry_info_t el3162_channel2[] = { fp@842: * {0x3102, 1, 8}, // status fp@842: * {0x3102, 2, 16} // value fp@842: * }; fp@842: * fp@879: * const ec_pdo_info_t el3162_pdos[] = { fp@842: * {EC_DIR_INPUT, 0x1A00, 2, el3162_channel1}, fp@842: * {EC_DIR_INPUT, 0x1A01, 2, el3162_channel2}, fp@842: * }; fp@842: * fp@879: * if (ecrt_slave_config_pdos(sc, 2, el3162_pdos)) fp@842: * return -1; // error fp@792: * \endcode fp@879: * fp@879: * The next example shows, how to configure only the Pdo assignment. The fp@879: * entries for each assigned Pdo are taken from the Pdo's default mapping. fp@879: * Please note, that Pdo entry registration will fail, if the Pdo fp@879: * configuration is left empty and the slave is offline. fp@792: * fp@792: * \code fp@879: * const ec_pdo_info_t pdos[] = { fp@792: * {EC_DIR_INPUT, 0x1600}, // Channel 1 fp@792: * {EC_DIR_INPUT, 0x1601} // Channel 2 fp@792: * }; fp@792: * fp@879: * if (ecrt_slave_config_pdos(slave_config_ana_in, 2, pdos)) fp@842: * return -1; // error fp@792: * \endcode fp@792: * fp@878: * Processing of \a pdo_infos will stop, if fp@878: * - the number of processed items reaches \a n_infos, or fp@879: * - the \a dir member of an ec_pdo_info_t item is EC_END. In this case, fp@878: * \a n_infos should set to a number greater than the number of list items; fp@879: * using EC_END is recommended. fp@878: * fp@792: * \return zero on success, else non-zero fp@792: */ fp@879: int ecrt_slave_config_pdos( fp@792: ec_slave_config_t *sc, /**< Slave configuration. */ fp@844: unsigned int n_infos, /**< Number of Pdo infos in \a pdo_infos. */ fp@879: const ec_pdo_info_t pdo_infos[] /**< List with Pdos. */ fp@792: ); fp@792: fp@842: /** Registers a Pdo entry for process data exchange in a domain. fp@842: * fp@879: * Searches the current Pdo assignment and Pdo mappings for the given Pdo fp@842: * entry. An error is raised, if the given entry is not mapped. Otherwise, the fp@842: * corresponding sync manager and FMMU configurations are provided for slave fp@879: * configuration and the respective sync manager's assigned Pdos are appended fp@879: * to the given domain, if not already done. The offset of the requested Pdo fp@879: * entry's data inside the domain's process data is returned. fp@842: * fp@842: * \retval >=0 Success: Offset of the Pdo entry's process data. fp@842: * \retval -1 Error: Pdo entry not found. fp@842: * \retval -2 Error: Failed to register Pdo entry. fp@807: */ fp@807: int ecrt_slave_config_reg_pdo_entry( fp@807: ec_slave_config_t *sc, /**< Slave configuration. */ fp@807: uint16_t entry_index, /**< Index of the Pdo entry to register. */ fp@807: uint8_t entry_subindex, /**< Subindex of the Pdo entry to register. */ fp@807: ec_domain_t *domain /**< Domain. */ fp@807: ); fp@807: fp@792: /** Add a configuration value for an 8-bit SDO. fp@792: * fp@792: * \todo doc fp@792: * \return 0 in case of success, else < 0 fp@792: */ fp@792: int ecrt_slave_config_sdo8( fp@792: ec_slave_config_t *sc, /**< Slave configuration */ fp@792: uint16_t sdo_index, /**< Index of the SDO to configure. */ fp@792: uint8_t sdo_subindex, /**< Subindex of the SDO to configure. */ fp@792: uint8_t value /**< Value to set. */ fp@792: ); fp@792: fp@792: /** Add a configuration value for a 16-bit SDO. fp@792: * fp@792: * \todo doc fp@792: * \return 0 in case of success, else < 0 fp@792: */ fp@792: int ecrt_slave_config_sdo16( fp@792: ec_slave_config_t *sc, /**< Slave configuration */ fp@792: uint16_t sdo_index, /**< Index of the SDO to configure. */ fp@792: uint8_t sdo_subindex, /**< Subindex of the SDO to configure. */ fp@792: uint16_t value /**< Value to set. */ fp@792: ); fp@792: fp@792: /** Add a configuration value for a 32-bit SDO. fp@792: * fp@792: * \todo doc fp@792: * \return 0 in case of success, else < 0 fp@792: */ fp@792: int ecrt_slave_config_sdo32( fp@792: ec_slave_config_t *sc, /**< Slave configuration */ fp@792: uint16_t sdo_index, /**< Index of the SDO to configure. */ fp@792: uint8_t sdo_subindex, /**< Subindex of the SDO to configure. */ fp@792: uint32_t value /**< Value to set. */ fp@792: ); fp@792: fp@858: /** Create an Sdo request to exchange Sdos during realtime operation. fp@858: * fp@858: * The created Sdo request object is freed automatically when the master is fp@858: * released. fp@858: */ fp@858: ec_sdo_request_t *ecrt_slave_config_create_sdo_request( fp@858: ec_slave_config_t *sc, /**< Slave configuration. */ fp@858: uint16_t index, /**< Sdo index. */ fp@858: uint8_t subindex, /**< Sdo subindex. */ fp@858: size_t size /**< Data size to reserve. */ fp@858: ); fp@858: fp@792: /** Outputs the state of the slave configuration. fp@792: * fp@792: * Stores the state information in the given \a state structure. fp@792: */ fp@792: void ecrt_slave_config_state( fp@792: const ec_slave_config_t *sc, /**< Slave configuration */ fp@792: ec_slave_config_state_t *state /**< State object to write to. */ fp@792: ); fp@325: fp@199: /****************************************************************************** fp@779: * Domain methods fp@199: *****************************************************************************/ fp@104: fp@792: /** Registers a bunch of Pdo entries for a domain. fp@792: * fp@792: * \todo doc fp@792: * \attention The registration array has to be terminated with an empty fp@792: * structure, or one with the \a index field set to zero! fp@792: * \return 0 on success, else non-zero. fp@792: */ fp@792: int ecrt_domain_reg_pdo_entry_list( fp@792: ec_domain_t *domain, /**< Domain. */ fp@792: const ec_pdo_entry_reg_t *pdo_entry_regs /**< Array of Pdo fp@792: registrations. */ fp@792: ); fp@792: fp@792: /** Returns the current size of the domain's process data. fp@792: * fp@792: * \return Size of the process data image. fp@792: */ fp@792: size_t ecrt_domain_size( fp@792: ec_domain_t *domain /**< Domain. */ fp@792: ); fp@792: fp@809: /** Provide external memory to store the domain's process data. fp@809: * fp@809: * Call this after all Pdo entries have been registered and before activating fp@809: * the master. fp@809: * fp@809: * The size of the allocated memory must be at least ecrt_domain_size(), after fp@809: * all Pdo entries have been registered. fp@809: */ fp@809: void ecrt_domain_external_memory( fp@792: ec_domain_t *domain, /**< Domain. */ fp@792: uint8_t *memory /**< Address of the memory to store the process fp@792: data in. */ fp@792: ); fp@792: fp@809: /** Returns the domain's process data. fp@809: * fp@809: * If external memory was provided with ecrt_domain_external_memory(), the fp@809: * returned pointer will contain the address of that memory. Otherwise it will fp@809: * point to the internally allocated memory. fp@809: * fp@809: * \return Pointer to the process data memory. fp@809: */ fp@809: uint8_t *ecrt_domain_data( fp@809: ec_domain_t *domain /**< Domain. */ fp@809: ); fp@809: fp@792: /** Processes received datagrams. fp@792: * fp@792: * \todo doc fp@792: */ fp@792: void ecrt_domain_process( fp@792: ec_domain_t *domain /**< Domain. */ fp@792: ); fp@792: fp@792: /** (Re-)queues all domain datagrams in the master's datagram queue. fp@792: * fp@792: * \todo doc fp@792: */ fp@792: void ecrt_domain_queue( fp@792: ec_domain_t *domain /**< Domain. */ fp@792: ); fp@792: fp@792: /** Reads the state of a domain. fp@792: * fp@792: * Stores the domain state in the giveb \a state structure. fp@792: */ fp@792: void ecrt_domain_state( fp@792: const ec_domain_t *domain, /**< Domain. */ fp@792: ec_domain_state_t *state /**< Pointer to a state object to store the fp@792: information. */ fp@792: ); fp@635: fp@858: /***************************************************************************** fp@858: * Sdo request methods. fp@858: ****************************************************************************/ fp@858: fp@858: /** Set the timeout for an Sdo request. fp@858: * fp@858: * If the request cannot be processed in the specified time, if will be marked fp@858: * as failed. fp@864: * fp@864: * \todo The timeout functionality is not yet implemented. fp@858: */ fp@858: void ecrt_sdo_request_timeout( fp@858: ec_sdo_request_t *req, /**< Sdo request. */ fp@858: uint32_t timeout /**< Timeout in milliseconds. */ fp@858: ); fp@858: fp@858: /** Access to the Sdo request's data. fp@858: * fp@868: * This function returns a pointer to the request's internal Sdo data memory. fp@868: * fp@868: * - After a read operation was successful, integer data can be evaluated using fp@868: * the EC_READ_*() macros as usual. Example: fp@868: * \code fp@868: * uint16_t value = EC_READ_U16(ecrt_sdo_request_data(sdo))); fp@868: * \endcode fp@868: * - If a write operation shall be triggered, the data have to be written to fp@868: * the internal memory. Use the EC_WRITE_*() macros, if you are writing fp@868: * integer data. Be sure, that the data fit into the memory. The memory size fp@868: * is a parameter of ecrt_slave_config_create_sdo_request(). fp@868: * \code fp@868: * EC_WRITE_U16(ecrt_sdo_request_data(sdo), 0xFFFF); fp@868: * \endcode fp@868: * fp@864: * \attention The return value can be invalid during a read operation, because fp@864: * the internal Sdo data memory could be re-allocated if the read Sdo data do fp@864: * not fit inside. fp@858: * fp@858: * \return Pointer to the internal Sdo data memory. fp@858: */ fp@858: uint8_t *ecrt_sdo_request_data( fp@858: ec_sdo_request_t *req /**< Sdo request. */ fp@858: ); fp@858: fp@869: /** Returns the current Sdo data size. fp@869: * fp@869: * When the Sdo request is created, the data size is set to the size of the fp@869: * reserved memory. After a read operation the size is set to the size of the fp@869: * read data. The size is not modified in any other situation. fp@869: * fp@869: * \return Sdo data size in bytes. fp@869: */ fp@869: size_t ecrt_sdo_request_data_size( fp@869: const ec_sdo_request_t *req /**< Sdo request. */ fp@869: ); fp@869: fp@858: /** Get the current state of the Sdo request. fp@858: * fp@858: * \return Request state. fp@858: */ fp@861: ec_sdo_request_state_t ecrt_sdo_request_state( fp@858: const ec_sdo_request_t *req /**< Sdo request. */ fp@858: ); fp@858: fp@858: /** Schedule an Sdo write operation. fp@864: * fp@864: * \attention This method may not be called while ecrt_sdo_request_state() fp@864: * returns EC_SDO_REQUEST_BUSY. fp@858: */ fp@858: void ecrt_sdo_request_write( fp@858: ec_sdo_request_t *req /**< Sdo request. */ fp@858: ); fp@858: fp@864: /** Schedule an Sdo read operation. fp@864: * fp@864: * \attention This method may not be called while ecrt_sdo_request_state() fp@864: * returns EC_SDO_REQUEST_BUSY. fp@858: * fp@858: * \attention After calling this function, the return value of fp@864: * ecrt_sdo_request_data() must be considered as invalid while fp@864: * ecrt_sdo_request_state() returns EC_SDO_REQUEST_BUSY. fp@858: */ fp@858: void ecrt_sdo_request_read( fp@858: ec_sdo_request_t *req /**< Sdo request. */ fp@858: ); fp@858: fp@199: /****************************************************************************** fp@779: * Bitwise read/write macros fp@779: *****************************************************************************/ fp@779: fp@779: /** Read a certain bit of an EtherCAT data byte. fp@640: * \param DATA EtherCAT data pointer fp@640: * \param POS bit position fp@640: */ fp@199: #define EC_READ_BIT(DATA, POS) ((*((uint8_t *) (DATA)) >> (POS)) & 0x01) fp@199: fp@779: /** Write a certain bit of an EtherCAT data byte. fp@640: * \param DATA EtherCAT data pointer fp@640: * \param POS bit position fp@640: * \param VAL new bit value fp@640: */ 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@779: * Read macros fp@779: *****************************************************************************/ fp@779: fp@779: /** Read an 8-bit unsigned value from EtherCAT data. fp@779: * \return EtherCAT data value fp@779: */ fp@199: #define EC_READ_U8(DATA) \ fp@199: ((uint8_t) *((uint8_t *) (DATA))) fp@199: fp@779: /** Read an 8-bit signed value from EtherCAT data. fp@779: * \param DATA EtherCAT data pointer fp@779: * \return EtherCAT data value fp@779: */ fp@199: #define EC_READ_S8(DATA) \ fp@288: ((int8_t) *((uint8_t *) (DATA))) fp@199: fp@779: /** Read a 16-bit unsigned value from EtherCAT data. fp@779: * \param DATA EtherCAT data pointer fp@779: * \return EtherCAT data value fp@779: */ fp@199: #define EC_READ_U16(DATA) \ fp@199: ((uint16_t) le16_to_cpup((void *) (DATA))) fp@199: fp@779: /** Read a 16-bit signed value from EtherCAT data. fp@779: * \param DATA EtherCAT data pointer fp@779: * \return EtherCAT data value fp@779: */ fp@199: #define EC_READ_S16(DATA) \ fp@288: ((int16_t) le16_to_cpup((void *) (DATA))) fp@199: fp@779: /** Read a 32-bit unsigned value from EtherCAT data. fp@779: * \param DATA EtherCAT data pointer fp@779: * \return EtherCAT data value fp@779: */ fp@199: #define EC_READ_U32(DATA) \ fp@199: ((uint32_t) le32_to_cpup((void *) (DATA))) fp@199: fp@779: /** Read a 32-bit signed value from EtherCAT data. fp@779: * \param DATA EtherCAT data pointer fp@779: * \return EtherCAT data value fp@779: */ fp@199: #define EC_READ_S32(DATA) \ fp@288: ((int32_t) le32_to_cpup((void *) (DATA))) fp@199: fp@199: /****************************************************************************** fp@779: * Write macros fp@779: *****************************************************************************/ fp@779: fp@779: /** Write an 8-bit unsigned value to EtherCAT data. fp@779: * \param DATA EtherCAT data pointer fp@779: * \param VAL new value fp@779: */ 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@779: /** Write an 8-bit signed value to EtherCAT data. fp@779: * \param DATA EtherCAT data pointer fp@779: * \param VAL new value fp@779: */ fp@199: #define EC_WRITE_S8(DATA, VAL) EC_WRITE_U8(DATA, VAL) fp@199: fp@779: /** Write a 16-bit unsigned value to EtherCAT data. fp@779: * \param DATA EtherCAT data pointer fp@779: * \param VAL new value fp@779: */ fp@199: #define EC_WRITE_U16(DATA, VAL) \ fp@199: do { \ fp@199: *((uint16_t *) (DATA)) = (uint16_t) (VAL); \ fp@810: cpu_to_le16s((uint16_t *) (DATA)); \ fp@199: } while (0) fp@199: fp@779: /** Write a 16-bit signed value to EtherCAT data. fp@779: * \param DATA EtherCAT data pointer fp@779: * \param VAL new value fp@779: */ fp@199: #define EC_WRITE_S16(DATA, VAL) EC_WRITE_U16(DATA, VAL) fp@199: fp@779: /** Write a 32-bit unsigned value to EtherCAT data. fp@779: * \param DATA EtherCAT data pointer fp@779: * \param VAL new value fp@779: */ fp@199: #define EC_WRITE_U32(DATA, VAL) \ fp@199: do { \ fp@199: *((uint32_t *) (DATA)) = (uint32_t) (VAL); \ fp@810: cpu_to_le32s((uint32_t *) (DATA)); \ fp@199: } while (0) fp@199: fp@779: /** Write a 32-bit signed value to EtherCAT data. fp@779: * \param DATA EtherCAT data pointer fp@779: * \param VAL new value fp@779: */ fp@199: #define EC_WRITE_S32(DATA, VAL) EC_WRITE_U32(DATA, VAL) fp@199: fp@104: /*****************************************************************************/ fp@104: fp@792: /** @} */ fp@792: fp@104: #endif