Cppcheck report - ethercatcpp-core: /builds/ethercatcpp/ethercatcpp-core/include/ethercat_master/ethercatcpp/slave_device.h

/*      File: slave_device.h
 *       This file is part of the program ethercatcpp-core
 *       Program description : EtherCAT driver libraries for UNIX
 *       Copyright (C) 2017-2024 -  Robin Passama (LIRMM / CNRS) Arnaud Meline
 * (LIRMM / CNRS) Benjamin Navarro (LIRMM / CNRS). All Right reserved.
 *
 *       This software is free software: you can redistribute it and/or modify
 *       it under the terms of the CeCILL-C license as published by
 *       the CEA CNRS INRIA, either version 1
 *       of the License, or (at your option) any later version.
 *       This software 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
 *       CeCILL-C License for more details.
 *
 *       You should have received a copy of the CeCILL-C License
 *       along with this software. If not, it can be found on the official
 * website of the CeCILL licenses family (http://www.cecill.info/index.en.html).
 */
/**
 * @file slave_device.h
 * @author Robin Passama (design and maintenance)
 * @author Arnaud Meline (original)
 * @author Benjamin Navarro (refactoring)
 * @brief Header file for SlaveDevice class
 * @date October 2018 12.
 * @ingroup ethercatcpp-core
 */

#pragma once

#include <ethercatcpp/device.h>
#include <ethercatcpp/coe_utilities.h>

#include <string>
#include <vector>
#include <functional>
#include <memory>

/*! \namespace ethercatcpp
 *
 * Root namespace for common and general purpose ethercatcpp packages
 */
namespace ethercatcpp {

/** @brief This class define an EtherCAT unit device
 *
 * A unit device is an EtherCAT device who contain slave informations (it is
 * composed by a dedicated slave object). It define all steps function (run,
 * init and end), define EtherCAT I/O buffers and all EtherCAT slave
 * configurations.
 */
class SlaveDevice : public Device {
public:
    //! This enum define all type of buffers (SyncManager type)
    enum syncmanager_buffer_t {
        ASYNCHROS_OUT =
            1, //!< define an asynchro mailbox out (from master to slave)
        ASYNCHROS_IN =
            2, //!< define an asynchro mailbox in (from slave to master)
        SYNCHROS_OUT =
            3,          //!< define a synchro buffer out (from master to slave)
        SYNCHROS_IN = 4 //!< define a synchro buffer in (from slave to master)
    };

    /**
     * @brief Constructor of SlaveDevice class
     */
    SlaveDevice();
    virtual ~SlaveDevice();

    /**
     * @brief Set the serial number of the device.
     *
     * This make it posible to force the serial number of the device. So at
     * Master::init() step the serial number will be check, and an error throw
     * if the device serial number dos not match.
     *
     * @param [in] serial_number the serial number.
     */
    void set_serial_number(uint32_t serial_number);

    /**
     * @brief Get EtherCAT device manufacturer id.
     *
     * @return EtherCAT device manufacturer id.
     */
    uint32_t eep_manufacturer() const;

    /**
     * @brief Get EtherCAT device id.
     *
     * @return the device id.
     */
    uint32_t eep_device() const;

    /**
     * @brief Get device serial number.
     *
     * @return device serial number.
     */
    uint32_t serial_number() const;

protected:
    friend class coe::PDOMapping;
    friend class coe::PDOBuffer;

    /**
     * @brief Define a physical buffer (EtherCAT syncManager buffer).
     *
     * This function define a physical buffer and updates size of total I/O
     * buffer
     *
     * @tparam T is the first or unique data type defining buffer content.
     * @tparam U are the other data types defining buffer content
     * sequentially happend to T.
     * @param [in] type is the type of buffer selected in
     * syncmanager_buffer_t.
     * @param [in] start_addr is the buffer physical start address.
     * @param [in] flags is the specific flag for this buffer.
     */
    template <typename T, typename... U>
    void define_physical_buffer(syncmanager_buffer_t type, uint16_t start_addr,
                                uint32_t flags) {
        if constexpr (sizeof...(U) == 0) {
            define_physical_buffer(type, start_addr, flags,
                                   static_cast<uint16_t>(sizeof(T)));
        } else {
            define_physical_buffer(
                type, start_addr, flags,
                static_cast<uint16_t>(sizeof(T) + (sizeof(U) + ...)));
        }
    }

    /**
     * @brief Define a physical buffer (EtherCAT syncManager buffer).
     *
     * This function defines a physical buffer and update size of total I/O
     * buffer
     *
     * @param [in] type is the type of buffer selected in syncmanager_buffer_t.
     * @param [in] start_addr is the buffer physical start address.
     * @param [in] flags is the specific flag for this buffer.
     * @param [in] length is the size of the buffer in bytes.
     */
    void define_physical_buffer(syncmanager_buffer_t type, uint16_t start_addr,
                                uint32_t flags, uint16_t length);

    /**
     * @brief Get data of input physical buffer.
     *
     * This function get the raw datas of the input physical buffer and cast
     * them in the data structure type indicate with "template param" to more
     * easyest used.
     *
     * @tparam T is the data structure type of the buffer.
     * @param [in] start_addr is the input buffer physical start address.
     * @return pointer to buffer data with "template param" structure type.
     */
    template <typename T>
    T* input_buffer(uint16_t start_addr) {
        return reinterpret_cast<T*>(input_buffer(start_addr));
    }

    template <typename T, typename U, typename... Other>
    std::tuple<T*, U*, Other*...> input_buffer(uint16_t start_addr) {
        return input_buffer_tuple<T, U, Other...>(start_addr, 0);
    }

    /**
     * @brief Get data of input physical buffer.
     *
     * @param [in] start_addr is the input buffer physical start address.
     * @return pointer to buffer data.
     */
    uint8_t* input_buffer(uint16_t start_addr);

    /**
     * @brief Get data of output physical buffer.
     *
     * This function get the raw datas of the output physical buffer and cast
     * them in the data structure type indicate with "template param" to more
     * easyest used.
     *
     * @tparam T is the data structure type of the buffer.
     * @param [in] start_addr is the output buffer physical start address.
     * @return pointer to buffer data with "template param" structure type.
     */
    template <typename T>
    T* output_buffer(uint16_t start_addr) {
        return reinterpret_cast<T*>(output_buffer(start_addr));
    }

    template <typename T, typename U, typename... Other>
    std::tuple<T*, U*, Other*...> output_buffer(uint16_t start_addr) {
        return output_buffer_tuple<T, U, Other...>(start_addr, 0);
    }

    /**
     * @brief Get data of output physical buffer.
     *
     * @param [in] start_addr is the output buffer physical start address.
     * @return pointer to buffer data.
     */
    uint8_t* output_buffer(uint16_t start_addr);

    /**
     * @brief Add a run step and define pre_function and
     * post_function run step.
     *
     * @param [in] pre is the function witch is execute before a run step
     * (generally set commands).
     * @param [in] post is the function witch is execute after a run step
     * (generally get status and datas).
     */
    void add_run_step(std::function<void()>&& pre,
                      std::function<void()>&& post);

    /**
     * @brief Add a init step and define pre_function and post_function for this
     * init step.
     *
     * @param [in] pre is the function witch is execute before a init step
     * (generally set commands).
     * @param [in] post is the function witch is execute after a init step
     * (generally get status and datas).
     */
    void add_init_step(std::function<void()>&& pre,
                       std::function<void()>&& post);

    /**
     * @brief Add a end step and define pre_function and post_function for this
     * end step.
     *
     * @param [in] pre is the function witch is execute before a end step
     * (generally set commands).
     * @param [in] post is the function witch is execute after a end step
     * (generally get status and datas).
     */
    void add_end_step(std::function<void()>&& pre,
                      std::function<void()>&& post);

    /**
     * @brief Set a specific ID to the slave.
     *
     * @param [in] name is slave name.
     * @param [in] manufacturer is the slave manufacturer ID.
     * @param [in] model is the slave model ID.
     */
    void set_id(const std::string& name, uint32_t manufacturer, uint32_t model);

    /**
     * @brief Define if the slave have a distributed clock.
     *
     * @param [in] have_dc state for distributed clock (TRUE if have DC).
     */
    void define_distributed_clock(bool have_dc);

    /**
     * @brief Define the period between two non cyclic steps.
     *
     * @param [in] period time desired to wait in us.
     */
    void define_period_for_non_cyclic_steps(int period);

    /**
     * @brief Define the function that configures the slave in PREOP
     * state at initialization of the ethercat bus (Master::init()) .
     * @details This is typically used to configure CanOpen over EtherCAT
     * devices, by calling write_sdo/read_sdo, and functions to
     * define PDO mappings and PDO buffers configuration. It can also be used
     * for any operations using FoE.
     *
     * @param [in] func is the function witch is executed witch is executed at
     * bus initialization time.
     * @see Master::init()
     */
    void configure_at_init(std::function<void()>&& func);

    /**
     * @brief Define the function that performs configuration actions in PREOP
     * state at termination of the ethercat bus. (Master::end()).
     * @details This is typically used to configure CanOpen over EtherCAT
     * devices, by calling write_sdo/read_sdo.
     * @param [in] func is the function witch is executed at bus termination
     * time.
     * @see Master::end()
     */
    void configure_at_end(std::function<void()>&& func);

    //////////////////////////////////////////////////////////////
    ////////////////////// CoE configuration /////////////////////
    //////////////////////////////////////////////////////////////

    /**
     * @brief write a SDO capable object field
     *
     * @param index index of the object
     * @param sub_index sub-index of the field
     * @param buffer_size size of field data
     * @param buffer pointer to the memory zone holding the data to xrite
     * @return int the workcounter. 0 on failure.
     */
    int write_sdo(uint16_t index, uint8_t sub_index, int buffer_size,
                  void* buffer) const;

    /**
     * @brief read a SDO capable object field
     *
     * @param index index of the object
     * @param sub_index sub-index of the field
     * @param buffer_size size of field data
     * @param buffer pointer to the memory zone holding the data read
     * @return int the workcounter. 0 on failure.
     */
    int read_sdo(uint16_t index, uint8_t sub_index, int buffer_size,
                 void* buffer) const;

    /**
     * @brief Send a CoE write SDO packet to the slave
     *
     * @param [in] index is the SDO index to write data.
     * @param [in] sub_index is the SDO sub index to write data.
     * @param [in] value is the data to write.
     *
     * @tparam T represent the data type of input parameter value.
     * @return 0 if communication failed. Worcounter value if success.
     */
    template <typename T>
    int write_sdo(uint16_t index, uint8_t sub_index, T& value) const {
        return write_sdo(index, sub_index, static_cast<int>(sizeof(T)),
                         reinterpret_cast<void*>(&value));
    }

    /**
     * @brief Send a CoE read SDO packet to the slave
     *
     * @param [in] index is the SDO index to read data.
     * @param [in] sub_index is the SDO sub index to read data.
     * @param [in] value is the data readed.
     *
     * @tparam T represent the data type of input parameter value.
     * @return 0 if communication failed. Worcounter value if success.
     */
    template <typename T>
    int read_sdo(uint16_t index, uint8_t sub_index, T& value) const {
        return read_sdo(index, sub_index, static_cast<int>(sizeof(T)),
                        reinterpret_cast<void*>(&value));
    }

    /**
     * @brief Start the definition of the command PDO mapping.
     *
     * @tparam T represent the type of data register (generally uint8 or
     * uint16).
     * @return false if communication failed, true if success.
     */
    template <typename T>
    bool start_command_pdo_mapping() {
        // Have to desactivate buffer to change it
        T val = 0;
        set_command_mappings(0);
        return write_sdo(coe::coe_rx_pdo_assign, 0x00, val) != 0;
    }

    /**
     * @brief Add a new command PDO map link.
     *
     * @param [in] pdo_address is the map address who want to add to the PDO.
     * @tparam T represent the type of data register (generally uint8 or
     * uint16).
     * @return false if communication failed, true if success.
     */
    template <typename T>
    bool add_command_pdo_mapping(uint16_t pdo_address) {
        T val = 0;
        // Check if buffer is desactivate
        int wkc = read_sdo(coe::coe_rx_pdo_assign, 0x00, val);
        if (val != 0) { // not in config PDO mode
            return false;
        }
        // Send new PDO address mapping
        set_command_mappings(get_command_mappings() + 1);
        wkc += write_sdo(coe::coe_rx_pdo_assign, get_command_mappings(),
                         pdo_address);
        return (wkc == 2);
    }

    /**
     * @brief Finish the definition of the command PDO mapping.
     *
     * @tparam T represent the type of date register (generally uint8 or
     * uint16).
     * @return false if communication failed, true if success.
     */
    template <typename T>
    bool end_command_pdo_mapping() {
<--- Technically the member function 'ethercatcpp::SlaveDevice::end_command_pdo_mapping' can be const. [+]
The member function 'ethercatcpp::SlaveDevice::end_command_pdo_mapping' can be made a const function. Making this function 'const' should not cause compiler errors. Even though the function can be made const function technically it may not make sense conceptually. Think about your design and the task of the function first - is it a function that must not change object internal state?
        T val = static_cast<T>(get_command_mappings());
        // Have to reactivate buffer with map number to valid it
        return write_sdo(coe::coe_rx_pdo_assign, 0x00, val) != 0;
    }

    /**
     * @brief Start definition of the status PDO mapping.
     *
     * @tparam T represent the type of date register (generally uint8 or
     * uint16).
     * @return false if communication failed, true if success.
     */
    template <typename T>
    bool start_status_pdo_mapping() {
        // Have to desactivate buffer to change it
        T val = 0;
        set_status_mappings(0);
        return write_sdo(coe::coe_tx_pdo_assign, 0x00, val) != 0;
    }

    /**
     * @brief Add a new STATUS PDO map link.
     *
     * @param [in] pdo_address is the map address who want to add to the PDO.
     * @tparam T represent the type of "date register" (generally uint8 or
     * uint16).
     * @return false if communication failed, true if success.
     */
    template <typename T>
    bool add_status_pdo_mapping(uint16_t pdo_address) {
        T val = 0;
        // Check if buffer is desactivate
        int wkc = read_sdo(coe::coe_tx_pdo_assign, 0x00, val);
        if (val != 0) { // no in config PDO mode
            return false;
        }
        // Send new PDO address mapping
        set_status_mappings(get_status_mappings() + 1);
        // increment number of Status pdo mapping to
        // write in good index
        wkc += write_sdo(coe::coe_tx_pdo_assign, get_status_mappings(),
                         pdo_address);
        return (wkc == 2);
    }

    /**
     * @brief Finish definition of the status PDO mapping.
     *
     * @tparam T represent the type of date register (generally uint8 or
     * uint16).
     * @return false if communication failed, true if success.
     */
    template <typename T>
    bool end_status_pdo_mapping() {
<--- Technically the member function 'ethercatcpp::SlaveDevice::end_status_pdo_mapping' can be const. [+]
The member function 'ethercatcpp::SlaveDevice::end_status_pdo_mapping' can be made a const function. Making this function 'const' should not cause compiler errors. Even though the function can be made const function technically it may not make sense conceptually. Think about your design and the task of the function first - is it a function that must not change object internal state?
        int wkc = 0;
        T val = get_status_mappings();
        // Have to reactivate buffer with map number to valid it
        wkc += write_sdo(coe::coe_tx_pdo_assign, 0x00, val);
        return wkc > 0;
    }

    //////////////////////////////////////////////////////////////
    ////////////////////// DC configuration///////////////////////
    //////////////////////////////////////////////////////////////

    /**
     * @brief Define DC synchro signal 0.
     *
     * This function active DC sync 0 mode and set timers for a slave.
     *
     * @param [in] cycle_time_0 is Cycltime SYNC0 in ns.
     * @param [in] cycle_shift is CyclShift in ns.
     */
    void configure_dc_sync0(uint32_t cycle_time_0, int32_t cycle_shift) const;

    /**
     * @brief Define DC synchro signals 0 and 1.
     *
     * This function active DC sync 0 and 1 mode and set timers for a slave.
     *
     * @param [in] cycle_time_0 is Cycltime SYNC0 in ns.
     * @param [in] cycle_time_1 is Cycltime SYNC1 in ns. This time is a delta
     * time in relation to the SYNC0 fire. If CylcTime1 = 0 then SYNC1 fires a
     * the same time as SYNC0.
     * @param [in] cycle_shift is CyclShift in ns.
     */
    void configure_dc_sync0_1(uint32_t cycle_time_0, uint32_t cycle_time_1,
                              int32_t cycle_shift) const; // time in ns

    //////////////////////////////////////////////////////////////
    ////////////////////// FoE configuration /////////////////////
    //////////////////////////////////////////////////////////////

    int32_t read_file(std::string_view filename, uint32_t password,
                      int32_t size, uint8_t* buffer) const;
    bool write_file(std::string_view filename, uint32_t password, int32_t size,
                    uint8_t* buffer) const;

    //////////////////////////////////////////////////////////////
    ////////////////////// SoE configuration /////////////////////
    //////////////////////////////////////////////////////////////

    bool read_sercos(uint8_t drive, uint8_t flags, uint16_t idn, int32_t size,
                     uint8_t* buffer) const;
    bool write_sercos(uint8_t drive, uint8_t flags, uint16_t idn, int32_t size,
                      uint8_t* buffer) const;

#ifdef EOE_AVAILABLE
    //////////////////////////////////////////////////////////////
    ////////////////////// EoE configuration /////////////////////
    //////////////////////////////////////////////////////////////
    struct EthernetConfiguration {
        std::string ip;
        std::string mask;
        std::string mac;
        std::string gateway;
        std::string dns;
    };

    bool detect_ethernet_configuration(uint8_t port,
                                       EthernetConfiguration& config);
    bool configure_ethernet(uint8_t port, const EthernetConfiguration& config);

    int32_t read_ethernet(uint8_t port, int32_t size, uint8_t* buffer);
    bool write_ethernet(uint8_t port, int32_t size, uint8_t* buffer);
#endif
private:
    friend class Master;
    friend class SlaveInfo;

    /**
     * @brief Print all slave informations
     *
     */
    void print_slave_info() const;
    /**
     * @brief Get the number of run steps for the device
     *
     * @return number of run steps
     */
    uint8_t run_steps() const;

    /**
     * @brief Launch the pre_function for one specific run step
     *
     * @param [in] step is the specific step number who want to launch.
     */
    void pre_run_step(uint8_t step);
    /**
     * @brief Launch the post_function for one specific run step
     *
     * @param [in] step is the specific step number who want to launch.
     */
    void post_run_step(uint8_t step);

    /**
     * @brief Get the number of init steps for the device
     *
     * @return number of init steps
     */
    uint8_t init_steps() const;

    /**
     * @brief Launch the pre_function for one specific init
     * step
     *
     * @param [in] step is the specific step number who want to launch.
     */
    void pre_init_step(uint8_t step);

    /**
     * @brief Launch the post_function for one specific init step
     *
     * @param [in] step is the specific step number who want to launch.
     */
    void post_init_step(uint8_t step);

    /***
     * @brief Get the number of end steps for the device
     *
     * @return number of end steps
     */
    uint8_t end_steps() const;

    /**
     * @brief Launch the pre_function for one specific end step
     *
     * @param [in] step is the specific step number who want to launch.
     */
    void pre_end_step(uint8_t step);

    /**
     * @brief Launch the post_function for one specific end
     * step
     *
     * @param [in] step is the specific step number who want to launch.
     */
    void post_end_step(uint8_t step);

    /**
     * @brief Update In/Out buffers address
     */
    void update_buffers();

    /**
     * @brief Call the init configuration function
     */
    void launch_init_configuration();

    /**
     * @brief Call the end configuration function
     */
    void launch_end_configuration();

    void set_command_mappings(uint8_t mappings);
    uint8_t get_command_mappings() const;
    void set_status_mappings(uint8_t mappings);
    uint8_t get_status_mappings() const;

    std::vector<Device*> device_vector() final;

    SlaveInfo* slave_address() final;

    class Impl;
    std::unique_ptr<Impl> impl_;

    // Auxiliary template functions
    template <typename T>
    std::tuple<T*> input_buffer_tuple(uint16_t start_addr,
                                      size_t ptr_increment) {
        return std::make_tuple(
            reinterpret_cast<T*>(input_buffer(start_addr) + ptr_increment));
    }

    template <typename T, typename U, typename... Other>
    std::tuple<T*, U*, Other*...> input_buffer_tuple(uint16_t start_addr,
                                                     size_t ptr_increment) {
        return std::tuple_cat(input_buffer_tuple<T>(start_addr, ptr_increment),
                              input_buffer_tuple<U, Other...>(
                                  start_addr, ptr_increment + sizeof(T)));
    }

    template <typename T>
    std::tuple<T*> output_buffer_tuple(uint16_t start_addr,
                                       size_t ptr_increment) {
        return std::make_tuple(
            reinterpret_cast<T*>(output_buffer(start_addr) + ptr_increment));
    }

    template <typename T, typename U, typename... Other>
    std::tuple<T*, U*, Other*...> output_buffer_tuple(uint16_t start_addr,
                                                      size_t ptr_increment) {
        return std::tuple_cat(output_buffer_tuple<T>(start_addr, ptr_increment),
                              output_buffer_tuple<U, Other...>(
                                  start_addr, ptr_increment + sizeof(T)));
    }
};
} // namespace ethercatcpp