From 7591838644a3fcb5145b9ccc7200166debe7ba87 Mon Sep 17 00:00:00 2001 From: Romain Forlot Date: Fri, 17 Mar 2017 12:48:46 +0100 Subject: Comments fixes, typo and formating. No more warning when generate the docs and all comments follow the same formating. Change-Id: I80d4c5c2d64401c2e53a550c60155680c4f968ce Signed-off-by: Romain Forlot --- src/can/can-bus-dev.cpp | 45 +++-- src/can/can-bus-dev.hpp | 12 +- src/can/can-bus.cpp | 204 +++++++++------------- src/can/can-bus.hpp | 24 +-- src/can/can-command.hpp | 50 +++--- src/can/can-decoder.cpp | 252 ++++++++++++++------------- src/can/can-decoder.hpp | 2 +- src/can/can-message.cpp | 134 +++++++------- src/can/can-signals.hpp | 86 ++++----- src/configuration.hpp | 22 +-- src/diagnostic/active-diagnostic-request.cpp | 1 - src/diagnostic/active-diagnostic-request.hpp | 2 +- src/diagnostic/diagnostic-manager.cpp | 8 +- src/diagnostic/diagnostic-manager.hpp | 18 +- src/diagnostic/diagnostic-message.cpp | 18 +- src/diagnostic/diagnostic-message.hpp | 10 +- src/low-can-binding.cpp | 42 +++-- src/utils/openxc-utils.cpp | 174 +++++++++--------- src/utils/signals.cpp | 44 ++--- src/utils/timer.cpp | 1 + src/utils/timer.hpp | 29 +-- 21 files changed, 575 insertions(+), 603 deletions(-) diff --git a/src/can/can-bus-dev.cpp b/src/can/can-bus-dev.cpp index 85bed4a..fb76498 100644 --- a/src/can/can-bus-dev.cpp +++ b/src/can/can-bus-dev.cpp @@ -31,7 +31,9 @@ #include "../low-can-binding.hpp" /// @brief Class constructor -/// @param dev_name String representing the device name into the linux /dev tree +/// +/// @param[in] dev_name - String representing the device name into the linux /dev tree +/// @param[in] address - integer identifier of the bus, set using init_can_dev from can_bus_t. can_bus_dev_t::can_bus_dev_t(const std::string& dev_name, int32_t address) : device_name_{dev_name}, address_{address} {} @@ -47,6 +49,10 @@ uint32_t can_bus_dev_t::get_address() const } /// @brief Open the can socket and returning it +/// +/// We try to open CAN socket and apply the following options +/// timestamp received messages and pass the socket to FD mode. +/// /// @return -1 if something wrong. int can_bus_dev_t::open() { @@ -55,41 +61,41 @@ int can_bus_dev_t::open() struct ifreq ifr; struct timeval timeout; - DEBUG(binder_interface, "CAN Handler socket : %d", can_socket_.socket()); + DEBUG(binder_interface, "open: CAN Handler socket : %d", can_socket_.socket()); if (can_socket_) return 0; can_socket_.open(PF_CAN, SOCK_RAW, CAN_RAW); if (can_socket_) { - DEBUG(binder_interface, "CAN Handler socket correctly initialized : %d", can_socket_.socket()); + DEBUG(binder_interface, "open: CAN Handler socket correctly initialized : %d", can_socket_.socket()); // Set timeout for read can_socket_.setopt(SOL_SOCKET, SO_RCVTIMEO, (char *)&timeout, sizeof(timeout)); // Set timestamp for receveid frame if (can_socket_.setopt(SOL_SOCKET, SO_TIMESTAMP, ×tamp_on, sizeof(timestamp_on)) < 0) - WARNING(binder_interface, "setsockopt SO_TIMESTAMP error: %s", ::strerror(errno)); - DEBUG(binder_interface, "Switch CAN Handler socket to use fd mode"); + WARNING(binder_interface, "open: setsockopt SO_TIMESTAMP error: %s", ::strerror(errno)); + DEBUG(binder_interface, "open: Switch CAN Handler socket to use fd mode"); // try to switch the socket into CAN_FD mode if (can_socket_.setopt(SOL_CAN_RAW, CAN_RAW_FD_FRAMES, &canfd_on, sizeof(canfd_on)) < 0) { - NOTICE(binder_interface, "Can not switch into CAN Extended frame format."); + NOTICE(binder_interface, "open: Can not switch into CAN Extended frame format."); is_fdmode_on_ = false; } else { - DEBUG(binder_interface, "Correctly set up CAN socket to use FD frames."); + DEBUG(binder_interface, "open: Correctly set up CAN socket to use FD frames."); is_fdmode_on_ = true; } // Attempts to open a socket to CAN bus ::strcpy(ifr.ifr_name, device_name_.c_str()); - DEBUG(binder_interface, "ifr_name is : %s", ifr.ifr_name); + DEBUG(binder_interface, "open: ifr_name is : %s", ifr.ifr_name); if(::ioctl(can_socket_.socket(), SIOCGIFINDEX, &ifr) < 0) { - ERROR(binder_interface, "ioctl failed. Error was : %s", strerror(errno)); + ERROR(binder_interface, "open: ioctl failed. Error was : %s", strerror(errno)); } else { @@ -109,12 +115,17 @@ int can_bus_dev_t::open() } /// @brief Close the bus. +/// +/// @return interger return value of socket.close() function int can_bus_dev_t::close() { return can_socket_.close(); } -/// @brief Read the can socket and retrieve canfd_frame +/// @brief Read the can socket and retrieve canfd_frame. +/// +/// Read operation are blocking and we try to read CANFD frame +/// rather than classic CAN frame. CANFD frame are retro compatible. can_message_t can_bus_dev_t::read() { ssize_t nbytes; @@ -161,7 +172,7 @@ void can_bus_dev_t::stop_reading() } /// @brief Thread function used to read the can socket. -/// @param[in] can_bus object to be used to read the can socket +/// @param[in] can_bus - object to be used to read the can socket void can_bus_dev_t::can_reader(can_bus_t& can_bus) { while(is_running_) @@ -176,7 +187,9 @@ void can_bus_dev_t::can_reader(can_bus_t& can_bus) } /// @brief Send a can message from a can_message_t object. -/// @param[in] can_msg the can message object to send +/// @param[in] can_msg - the can message object to send +/// +/// @return 0 if message snet, -1 if something wrong. int can_bus_dev_t::send(can_message_t& can_msg) { ssize_t nbytes; @@ -211,6 +224,8 @@ int can_bus_dev_t::send(can_message_t& can_msg) /// @param[in] arbitration_id - CAN arbitration id. /// @param[in] data - CAN message payload to send /// @param[in] size - size of the data to send +/// +/// @return True if message sent, false if not. bool can_bus_dev_t::shims_send(const uint32_t arbitration_id, const uint8_t* data, const uint8_t size) { ssize_t nbytes; @@ -227,14 +242,14 @@ bool can_bus_dev_t::shims_send(const uint32_t arbitration_id, const uint8_t* dat if (nbytes == -1) { ERROR(binder_interface, "send_can_message: Sending CAN frame failed."); - return -1; + return false; } - return (int)nbytes; + return true; } else { ERROR(binder_interface, "send_can_message: socket not initialized. Attempt to reopen can device socket."); open(); } - return 0; + return false; } diff --git a/src/can/can-bus-dev.hpp b/src/can/can-bus-dev.hpp index 63e6163..a612e7d 100644 --- a/src/can/can-bus-dev.hpp +++ b/src/can/can-bus-dev.hpp @@ -29,20 +29,20 @@ class can_bus_t; class can_message_t; /// @brief Object representing a can device. Handle opening, closing and reading on the -/// socket. This is the low level object to be use by can_bus_t. +/// socket. This is the low level object to be initialized and use by can_bus_t. class can_bus_dev_t { private: - std::string device_name_; + std::string device_name_; ///< a string identifier identitfying the linux CAN device. utils::socket_t can_socket_; - int32_t address_; /// < an identifier used through binding that refer to that device + int32_t address_; ///< an identifier used through binding that refer to that device - bool is_fdmode_on_; /// < boolean telling if whether or not the can socket use fdmode. + bool is_fdmode_on_; ///< boolean telling if whether or not the can socket use fdmode. struct sockaddr_can txAddress_; /// < internal member using to bind to the socket - std::thread th_reading_; /// < Thread handling read the socket can device filling can_message_q_ queue of can_bus_t - bool is_running_ = false; /// < boolean telling whether or not reading is running or not + std::thread th_reading_; ///< Thread handling read the socket can device filling can_message_q_ queue of can_bus_t + bool is_running_ = false; ///< boolean telling whether or not reading is running or not void can_reader(can_bus_t& can_bus); public: diff --git a/src/can/can-bus.cpp b/src/can/can-bus.cpp index 0c2337c..a81c142 100644 --- a/src/can/can-bus.cpp +++ b/src/can/can-bus.cpp @@ -40,12 +40,9 @@ extern "C" #include } -/** -* @brief Class constructor -* -* @param struct afb_binding_interface *interface between daemon and binding -* @param int file handle to the json configuration file. -*/ +/// @brief Class constructor +/// +/// @param[in] conf_file - handle to the json configuration file. can_bus_t::can_bus_t(int conf_file) : conf_file_{conf_file} { @@ -53,18 +50,16 @@ can_bus_t::can_bus_t(int conf_file) std::map> can_bus_t::can_devices_; -/** - * @brief Will make the decoding operation on a classic CAN message. It will not - * handle CAN commands nor diagnostic messages that have their own method to get - * this happens. - * - * It will add to the vehicle_message queue the decoded message and tell the event push - * thread to process it. - * - * @param[in] can_message - a single CAN message from the CAN socket read, to be decode. - * - * @return How many signals has been decoded. - */ +/// @brief Will make the decoding operation on a classic CAN message. It will not +/// handle CAN commands nor diagnostic messages that have their own method to get +/// this happens. +/// +/// It will add to the vehicle_message queue the decoded message and tell the event push +/// thread to process it. +/// +/// @param[in] can_message - a single CAN message from the CAN socket read, to be decode. +/// +/// @return How many signals has been decoded. int can_bus_t::process_can_signals(can_message_t& can_message) { int processed_signals = 0; @@ -72,21 +67,21 @@ int can_bus_t::process_can_signals(can_message_t& can_message) openxc_DynamicField search_key, decoded_message; openxc_VehicleMessage vehicle_message; - /* First we have to found which can_signal_t it is */ + // First we have to found which can_signal_t it is search_key = build_DynamicField((double)can_message.get_id()); configuration_t::instance().find_can_signals(search_key, signals); - /* Decoding the message ! Don't kill the messenger ! */ + // Decoding the message ! Don't kill the messenger ! for(auto& sig : signals) { std::lock_guard subscribed_signals_lock(get_subscribed_signals_mutex()); std::map& s = get_subscribed_signals(); - /* DEBUG message to make easier debugger STL containers... - DEBUG(binder_interface, "Operator[] key char: %s, event valid? %d", sig.generic_name, afb_event_is_valid(s[sig.generic_name])); - DEBUG(binder_interface, "Operator[] key string: %s, event valid? %d", sig.generic_name, afb_event_is_valid(s[std::string(sig.generic_name)])); - DEBUG(binder_interface, "Nb elt matched char: %d", (int)s.count(sig.generic_name)); - DEBUG(binder_interface, "Nb elt matched string: %d", (int)s.count(std::string(sig.generic_name)));*/ + // DEBUG message to make easier debugger STL containers... + //DEBUG(binder_interface, "Operator[] key char: %s, event valid? %d", sig.generic_name, afb_event_is_valid(s[sig.generic_name])); + //DEBUG(binder_interface, "Operator[] key string: %s, event valid? %d", sig.generic_name, afb_event_is_valid(s[std::string(sig.generic_name)])); + //DEBUG(binder_interface, "Nb elt matched char: %d", (int)s.count(sig.generic_name)); + //DEBUG(binder_interface, "Nb elt matched string: %d", (int)s.count(std::string(sig.generic_name)); if( s.find(sig->get_name()) != s.end() && afb_event_is_valid(s[sig->get_name()])) { decoded_message = decoder_t::translateSignal(*sig, can_message, configuration_t::instance().get_can_signals()); @@ -105,15 +100,14 @@ int can_bus_t::process_can_signals(can_message_t& can_message) return processed_signals; } -/** - * @brief Will make the decoding operation on a diagnostic CAN message.It will add to - * the vehicle_message queue the decoded message and tell the event push thread to process it. - * - * @param[in] manager - the diagnostic manager object that handle diagnostic communication - * @param[in] can_message - a single CAN message from the CAN socket read, to be decode. - * - * @return How many signals has been decoded. - */ +/// @brief Will make the decoding operation on a diagnostic CAN message.Then it find the subscribed signal +/// corresponding and will add the vehicle_message to the queue of event to pushed before notifying +/// the event push thread to process it. +/// +/// @param[in] manager - the diagnostic manager object that handle diagnostic communication +/// @param[in] can_message - a single CAN message from the CAN socket read, to be decode. +/// +/// @return How many signals has been decoded. int can_bus_t::process_diagnostic_signals(diagnostic_manager_t& manager, const can_message_t& can_message) { int processed_signals = 0; @@ -134,20 +128,18 @@ int can_bus_t::process_diagnostic_signals(diagnostic_manager_t& manager, const c return processed_signals; } -/** -* @brief thread to decoding raw CAN messages. -* -* @desc It will take from the can_message_q_ queue the next can message to process then it will search -* about signal subscribed if there is a valid afb_event for it. We only decode signal for which a -* subscription has been made. Can message will be decoded using translateSignal that will pass it to the -* corresponding decoding function if there is one assigned for that signal. If not, it will be the default -* noopDecoder function that will operate on it. -* -* Depending on the nature of message, if id match a diagnostic request corresponding id for a response -* then decoding a diagnostic message else use classic CAN signals decoding functions. -* -* TODO: make diagnostic messages parsing optionnal. -*/ +/// @brief thread to decoding raw CAN messages. +/// +/// Depending on the nature of message, if arbitration ID matches ID for a diagnostic response +/// then decoding a diagnostic message else use classic CAN signals decoding functions. +/// +/// It will take from the can_message_q_ queue the next can message to process then it search +/// about signal subscribed if there is a valid afb_event for it. We only decode signal for which a +/// subscription has been made. Can message will be decoded using translateSignal that will pass it to the +/// corresponding decoding function if there is one assigned for that signal. If not, it will be the default +/// noopDecoder function that will operate on it. +/// +/// TODO: make diagnostic messages parsing optionnal. void can_bus_t::can_decode_message() { can_message_t can_message; @@ -165,10 +157,8 @@ void can_bus_t::can_decode_message() } } -/** -* @brief thread to push events to suscribers. It will read subscribed_signals map to look -* which are events that has to be pushed. -*/ +/// @brief thread to push events to suscribers. It will read subscribed_signals map to look +/// which are events that has to be pushed. void can_bus_t::can_event_push() { openxc_VehicleMessage v_message; @@ -195,10 +185,8 @@ void can_bus_t::can_event_push() } } -/** -* @brief Will initialize threads that will decode -* and push subscribed events. -*/ +/// @brief Will initialize threads that will decode +/// and push subscribed events. void can_bus_t::start_threads() { is_decoding_ = true; @@ -212,25 +200,23 @@ void can_bus_t::start_threads() is_pushing_ = false; } -/** -* @brief Will stop all threads holded by can_bus_t object -* which are decoding and pushing then will wait that's -* they'll finish their job. -*/ +/// @brief Will stop all threads holded by can_bus_t object +/// which are decoding and pushing then will wait that's +/// they'll finish their job. void can_bus_t::stop_threads() { is_decoding_ = false; is_pushing_ = false; } -/** -* @brief Will initialize can_bus_dev_t objects after reading -* the configuration file passed in the constructor. All CAN buses -* Initialized here will be added to a vector holding them for -* inventory and later access. -* -* That will initialize CAN socket reading too using a new thread. -*/ +/// @brief Will initialize can_bus_dev_t objects after reading +/// the configuration file passed in the constructor. All CAN buses +/// Initialized here will be added to a vector holding them for +/// inventory and later access. +/// +/// That will initialize CAN socket reading too using a new thread. +/// +/// @return 0 if ok, other if not. int can_bus_t::init_can_dev() { std::vector devices_name; @@ -264,12 +250,10 @@ int can_bus_t::init_can_dev() return 1; } -/** -* @brief read the conf_file_ and will parse json objects -* in it searching for canbus objects devices name. -* -* @return Vector of can bus device name string. -*/ +/// @brief read the conf_file_ and will parse json objects +/// in it searching for canbus objects devices name. +/// +/// @return Vector of can bus device name string. std::vector can_bus_t::read_conf() { std::vector ret; @@ -314,31 +298,25 @@ std::vector can_bus_t::read_conf() return ret; } -/** -* @brief return new_can_message_cv_ member -* -* @return return new_can_message_cv_ member -*/ +/// @brief return new_can_message_cv_ member +/// +/// @return return new_can_message_cv_ member std::condition_variable& can_bus_t::get_new_can_message_cv() { return new_can_message_cv_; } -/** -* @brief return can_message_mutex_ member -* -* @return return can_message_mutex_ member -*/ +/// @brief return can_message_mutex_ member +/// +/// @return return can_message_mutex_ member std::mutex& can_bus_t::get_can_message_mutex() { return can_message_mutex_; } -/** -* @brief Return first can_message_t on the queue -* -* @return a can_message_t -*/ +/// @brief Return first can_message_t on the queue +/// +/// @return a can_message_t can_message_t can_bus_t::next_can_message() { can_message_t can_msg; @@ -355,21 +333,17 @@ can_message_t can_bus_t::next_can_message() return can_msg; } -/** -* @brief Push a can_message_t into the queue -* -* @param the const reference can_message_t object to push into the queue -*/ +/// @brief Push a can_message_t into the queue +/// +/// @param[in] can_msg - the const reference can_message_t object to push into the queue void can_bus_t::push_new_can_message(const can_message_t& can_msg) { can_message_q_.push(can_msg); } -/** -* @brief Return first openxc_VehicleMessage on the queue -* -* @return a openxc_VehicleMessage containing a decoded can message -*/ +/// @brief Return first openxc_VehicleMessage on the queue +/// +/// @return a openxc_VehicleMessage containing a decoded can message openxc_VehicleMessage can_bus_t::next_vehicle_message() { openxc_VehicleMessage v_msg; @@ -385,34 +359,28 @@ openxc_VehicleMessage can_bus_t::next_vehicle_message() return v_msg; } -/** -* @brief Push a openxc_VehicleMessage into the queue -* -* @param the const reference openxc_VehicleMessage object to push into the queue -*/ +/// @brief Push a openxc_VehicleMessage into the queue +/// +/// @param[in] v_msg - const reference openxc_VehicleMessage object to push into the queue void can_bus_t::push_new_vehicle_message(const openxc_VehicleMessage& v_msg) { vehicle_message_q_.push(v_msg); } -/** -* @brief Return a map with the can_bus_dev_t initialized -* -* @return map can_bus_dev_m_ map -*/ +/// @brief Return a map with the can_bus_dev_t initialized +/// +/// @return map can_bus_dev_m_ map const std::map>& can_bus_t::get_can_devices() const { return can_bus_t::can_devices_; } -/** -* @brief Return the shared pointer on the can_bus_dev_t initialized -* with device_name "bus" -* -* @param[in] bus - CAN bus device name to retrieve. -* -* @return A shared pointer on an object can_bus_dev_t -*/ +/// @brief Return the shared pointer on the can_bus_dev_t initialized +/// with device_name "bus" +/// +/// @param[in] bus - CAN bus device name to retrieve. +/// +/// @return A shared pointer on an object can_bus_dev_t std::shared_ptr can_bus_t::get_can_device(std::string bus) { return can_bus_t::can_devices_[bus]; diff --git a/src/can/can-bus.hpp b/src/can/can-bus.hpp index 9370d3b..eb47476 100644 --- a/src/can/can-bus.hpp +++ b/src/can/can-bus.hpp @@ -48,25 +48,25 @@ class can_bus_t { private: - int conf_file_; /// < configuration file handle used to initialize can_bus_dev_t objects. + int conf_file_; ///< configuration file handle used to initialize can_bus_dev_t objects. void can_decode_message(); - std::thread th_decoding_; /// < thread that'll handle decoding a can frame - bool is_decoding_ = false; /// < boolean member controling thread while loop + std::thread th_decoding_; ///< thread that'll handle decoding a can frame + bool is_decoding_ = false; ///< boolean member controling thread while loop void can_event_push(); - std::thread th_pushing_; /// < thread that'll handle pushing decoded can frame to subscribers - bool is_pushing_ = false; /// < boolean member controling thread while loop + std::thread th_pushing_; ///< thread that'll handle pushing decoded can frame to subscribers + bool is_pushing_ = false; ///< boolean member controling thread while loop - std::condition_variable new_can_message_cv_; /// < condition_variable use to wait until there is a new CAN message to read - std::mutex can_message_mutex_; /// < mutex protecting the can_message_q_ queue. - std::queue can_message_q_; /// < queue that'll store can_message_t to decoded + std::condition_variable new_can_message_cv_; ///< condition_variable use to wait until there is a new CAN message to read + std::mutex can_message_mutex_; ///< mutex protecting the can_message_q_ queue. + std::queue can_message_q_; ///< queue that'll store can_message_t to decoded - std::condition_variable new_decoded_can_message_; /// < condition_variable use to wait until there is a new vehicle message to read from the queue vehicle_message_q_ - std::mutex decoded_can_message_mutex_; /// < mutex protecting the vehicle_message_q_ queue. - std::queue vehicle_message_q_; /// < queue that'll store openxc_VehicleMessage to pushed + std::condition_variable new_decoded_can_message_; ///< condition_variable use to wait until there is a new vehicle message to read from the queue vehicle_message_q_ + std::mutex decoded_can_message_mutex_; ///< mutex protecting the vehicle_message_q_ queue. + std::queue vehicle_message_q_; ///< queue that'll store openxc_VehicleMessage to pushed - static std::map> can_devices_; /// < Can device map containing all can_bus_dev_t objects initialized during init_can_dev function + static std::map> can_devices_; ///< Can device map containing all can_bus_dev_t objects initialized during init_can_dev function public: can_bus_t(int conf_file); diff --git a/src/can/can-command.hpp b/src/can/can-command.hpp index 8324d32..4cf20cb 100644 --- a/src/can/can-command.hpp +++ b/src/can/can-command.hpp @@ -20,34 +20,34 @@ #include "openxc.pb.h" #include "can-signals.hpp" -/** - * @brief The type signature for a function to handle a custom OpenXC command. - * - * @param[in] name - the name of the received command. - * @param[in] value - the value of the received command, in a DynamicField. The actual type - * may be a number, string or bool. - * @param[in] event - an optional event from the received command, in a DynamicField. The - * actual type may be a number, string or bool. - * @param[in] signals - The list of all signals. - * @param[in] signalCount - The length of the signals array. - */ +/// +/// @brief The type signature for a function to handle a custom OpenXC command. +/// +/// @param[in] name - the name of the received command. +/// @param[in] value - the value of the received command, in a DynamicField. The actual type +/// may be a number, string or bool. +/// @param[in] event - an optional event from the received command, in a DynamicField. The +/// actual type may be a number, string or bool. +/// @param[in] signals - The list of all signals. +/// @param[in] signalCount - The length of the signals array. +/// typedef void (*CommandHandler)(const char* name, openxc_DynamicField* value, openxc_DynamicField* event, can_signal_t* signals, int signalCount); -/* @struct CanCommand - * @brief The structure to represent a supported custom OpenXC command. - * - * @desc For completely customized CAN commands without a 1-1 mapping between an - * OpenXC message from the host and a CAN signal, you can define the name of the - * command and a custom function to handle it in the VI. An example is - * the "turn_signal_status" command in OpenXC, which has a value of "left" or - * "right". The vehicle may have separate CAN signals for the left and right - * turn signals, so you will need to implement a custom command handler to send - * the correct signals. - * - * Command handlers are also useful if you want to trigger multiple CAN messages - * or signals from a signal OpenXC message. - */ +/// @struct CanCommand +/// @brief The structure to represent a supported custom OpenXC command. +/// +/// For completely customized CAN commands without a 1-1 mapping between an +/// OpenXC message from the host and a CAN signal, you can define the name of the +/// command and a custom function to handle it in the VI. An example is +/// the "turn_signal_status" command in OpenXC, which has a value of "left" or +/// "right". The vehicle may have separate CAN signals for the left and right +/// turn signals, so you will need to implement a custom command handler to send +/// the correct signals. +/// +/// Command handlers are also useful if you want to trigger multiple CAN messages +/// or signals from a signal OpenXC message. +/// typedef struct { const char* generic_name; /*!< generic_name - The name of the command.*/ CommandHandler handler; /*!< handler - An function to process the received command's data and perform some diff --git a/src/can/can-decoder.cpp b/src/can/can-decoder.cpp index 866434e..467261a 100644 --- a/src/can/can-decoder.cpp +++ b/src/can/can-decoder.cpp @@ -20,15 +20,15 @@ #include "canutil/read.h" #include "../utils/openxc-utils.hpp" -/* Public: Parse the signal's bitfield from the given data and return the raw -* value. -* -* @param[in] signal - The signal to parse from the data. -* @param[in] message - can_message_t to parse -* -* @return Returns the raw value of the signal parsed as a bitfield from the given byte -* array. -*/ +/// @brief Parse the signal's bitfield from the given data and return the raw +/// value. +/// +/// @param[in] signal - The signal to parse from the data. +/// @param[in] message - can_message_t to parse +/// +/// @return Returns the raw value of the signal parsed as a bitfield from the given byte +/// array. +/// float decoder_t::parseSignalBitfield(can_signal_t& signal, const can_message_t& message) { return bitfield_parse_float(message.get_data(), CAN_MESSAGE_SIZE, @@ -36,21 +36,21 @@ float decoder_t::parseSignalBitfield(can_signal_t& signal, const can_message_t& signal.get_offset()); } -/* Public: Wrap a raw CAN signal value in a DynamicField without modification. -* -* This is an implementation of the SignalDecoder type signature, and can be -* used directly in the can_signal_t.decoder field. -* -* @param[in] signal - The details of the signal that contains the state mapping. -* @param[in] signals - The list of all signals -* @param[in] value - The numerical value that will be wrapped in a DynamicField. -* @param[out]send - An output argument that will be set to false if the value should -* not be sent for any reason. -* -* @return Returns a DynamicField with the original, unmodified raw CAN signal value as -* its numeric value. The 'send' argument will not be modified as this decoder -* always succeeds. -*/ +/// @brief Wrap a raw CAN signal value in a DynamicField without modification. +/// +/// This is an implementation of the SignalDecoder type signature, and can be +/// used directly in the can_signal_t.decoder field. +/// +/// @param[in] signal - The details of the signal that contains the state mapping. +/// @param[in] signals - The list of all signals +/// @param[in] value - The numerical value that will be wrapped in a DynamicField. +/// @param[out] send - An output argument that will be set to false if the value should +/// not be sent for any reason. +/// +/// @return Returns a DynamicField with the original, unmodified raw CAN signal value as +/// its numeric value. The 'send' argument will not be modified as this decoder +/// always succeeds. +/// openxc_DynamicField decoder_t::noopDecoder(can_signal_t& signal, const std::vector& signals, float value, bool* send) { @@ -58,21 +58,21 @@ openxc_DynamicField decoder_t::noopDecoder(can_signal_t& signal, return decoded_value; } -/* Public: Coerces a numerical value to a boolean. -* -* This is an implementation of the SignalDecoder type signature, and can be -* used directly in the can_signal_t.decoder field. -* -* @param[in] signal - The details of the signal that contains the state mapping. -* @param[in] signals - The list of all signals -* @param[in] value - The numerical value that will be converted to a boolean. -* @param[out] send - An output argument that will be set to false if the value should -* not be sent for any reason. -* -* @return Returns a DynamicField with a boolean value of false if the raw signal value -* is 0.0, otherwise true. The 'send' argument will not be modified as this -* decoder always succeeds. -*/ +/// @brief Coerces a numerical value to a boolean. +/// +/// This is an implementation of the SignalDecoder type signature, and can be +/// used directly in the can_signal_t.decoder field. +/// +/// @param[in] signal - The details of the signal that contains the state mapping. +/// @param[in] signals - The list of all signals +/// @param[in] value - The numerical value that will be converted to a boolean. +/// @param[out] send - An output argument that will be set to false if the value should +/// not be sent for any reason. +/// +/// @return Returns a DynamicField with a boolean value of false if the raw signal value +/// is 0.0, otherwise true. The 'send' argument will not be modified as this +/// decoder always succeeds. +/// openxc_DynamicField decoder_t::booleanDecoder(can_signal_t& signal, const std::vector& signals, float value, bool* send) { @@ -80,21 +80,21 @@ openxc_DynamicField decoder_t::booleanDecoder(can_signal_t& signal, return decoded_value; } -/* Public: Update the metadata for a signal and the newly received value. -* -* This is an implementation of the SignalDecoder type signature, and can be -* used directly in the can_signal_t.decoder field. -* -* This function always flips 'send' to false. -* -* @param[in] signal - The details of the signal that contains the state mapping. -* @param[in] signals - The list of all signals. -* @param[in] value - The numerical value that will be converted to a boolean. -* @param[out] send - This output argument will always be set to false, so the caller will -* know not to publish this value to the pipeline. -* -* @return Return value is undefined. -*/ +/// @brief Update the metadata for a signal and the newly received value. +/// +/// This is an implementation of the SignalDecoder type signature, and can be +/// used directly in the can_signal_t.decoder field. +/// +/// This function always flips 'send' to false. +/// +/// @param[in] signal - The details of the signal that contains the state mapping. +/// @param[in] signals - The list of all signals. +/// @param[in] value - The numerical value that will be converted to a boolean. +/// @param[out] send - This output argument will always be set to false, so the caller will +/// know not to publish this value to the pipeline. +/// +/// @return Return value is undefined. +/// openxc_DynamicField decoder_t::ignoreDecoder(can_signal_t& signal, const std::vector& signals, float value, bool* send) { @@ -106,22 +106,22 @@ openxc_DynamicField decoder_t::ignoreDecoder(can_signal_t& signal, return decoded_value; } -/* Public: Find and return the corresponding string state for a CAN signal's -* raw integer value. -* -* This is an implementation of the SignalDecoder type signature, and can be -* used directly in the can_signal_t.decoder field. -* -* @param[in] signal - The details of the signal that contains the state mapping. -* @param[in] signals - The list of all signals. -* @param[in] value - The numerical value that should map to a state. -* @param[out] send - An output argument that will be set to false if the value should -* not be sent for any reason. -* -* @return Returns a DynamicField with a string value if a matching state is found in -* the signal. If an equivalent isn't found, send is sent to false and the -* return value is undefined. -*/ +/// @brief Find and return the corresponding string state for a CAN signal's +/// raw integer value. +/// +/// This is an implementation of the SignalDecoder type signature, and can be +/// used directly in the can_signal_t.decoder field. +/// +/// @param[in] signal - The details of the signal that contains the state mapping. +/// @param[in] signals - The list of all signals. +/// @param[in] value - The numerical value that should map to a state. +/// @param[out] send - An output argument that will be set to false if the value should +/// not be sent for any reason. +/// +/// @return Returns a DynamicField with a string value if a matching state is found in +/// the signal. If an equivalent isn't found, send is sent to false and the +/// return value is undefined. +/// openxc_DynamicField decoder_t::stateDecoder(can_signal_t& signal, const std::vector& signals, float value, bool* send) { @@ -136,19 +136,19 @@ openxc_DynamicField decoder_t::stateDecoder(can_signal_t& signal, } -/* Public: Parse a signal from a CAN message, apply any required transforations -* to get a human readable value and public the result to the pipeline. -* -* If the can_signal_t has a non-NULL 'decoder' field, the raw CAN signal value -* will be passed to the decoder before publishing. -* -* @param[in] signal - The details of the signal to decode and forward. -* @param[in] message - The received CAN message that should contain this signal. -* @param[in] signals - an array of all active signals. -* -* The decoder returns an openxc_DynamicField, which may contain a number, -* string or boolean. -*/ +/// @brief Parse a signal from a CAN message, apply any required transforations +/// to get a human readable value and public the result to the pipeline. +/// +/// If the can_signal_t has a non-NULL 'decoder' field, the raw CAN signal value +/// will be passed to the decoder before publishing. +/// +/// @param[in] signal - The details of the signal to decode and forward. +/// @param[in] message - The received CAN message that should contain this signal. +/// @param[in] signals - an array of all active signals. +/// +/// The decoder returns an openxc_DynamicField, which may contain a number, +/// string or boolean. +/// openxc_DynamicField decoder_t::translateSignal(can_signal_t& signal, can_message_t& message, const std::vector& signals) { @@ -172,21 +172,21 @@ openxc_DynamicField decoder_t::translateSignal(can_signal_t& signal, can_message return decoded_value; } -/* Public: Parse a signal from a CAN message and apply any required -* transforations to get a human readable value. -* -* If the can_signal_t has a non-NULL 'decoder' field, the raw CAN signal value -* will be passed to the decoder before returning. -* -* @param[in] signal - The details of the signal to decode and forward. -* @param[in] value - The numerical value that will be converted to a boolean. -* @param[in] signals - an array of all active signals. -* @param[out] send - An output parameter that will be flipped to false if the value could -* not be decoded. -* -* @return The decoder returns an openxc_DynamicField, which may contain a number, -* string or boolean. If 'send' is false, the return value is undefined. -*/ +/// @brief Parse a signal from a CAN message and apply any required +/// transforations to get a human readable value. +/// +/// If the can_signal_t has a non-NULL 'decoder' field, the raw CAN signal value +/// will be passed to the decoder before returning. +/// +/// @param[in] signal - The details of the signal to decode and forward. +/// @param[in] value - The numerical value that will be converted to a boolean. +/// @param[in] signals - an array of all active signals. +/// @param[out] send - An output parameter that will be flipped to false if the value could +/// not be decoded. +/// +/// @return The decoder returns an openxc_DynamicField, which may contain a number, +/// string or boolean. If 'send' is false, the return value is undefined. +/// openxc_DynamicField decoder_t::decodeSignal( can_signal_t& signal, float value, const std::vector& signals, bool* send) { @@ -197,19 +197,19 @@ openxc_DynamicField decoder_t::decodeSignal( can_signal_t& signal, return decoded_value; } -/* Public: Decode a transformed, human readable value from an raw CAN signal -* already parsed from a CAN message. -* -* This is the same as decodeSignal but you must parse the bitfield value of the signal from the CAN -* message yourself. This is useful if you need that raw value for something -* else. -* -* @param[in] signal - The details of the signal to decode and forward. -* @param[in] value - The numerical value that will be converted to a boolean. -* @param[in] signals - an array of all active signals. -* @param[out] send - An output parameter that will be flipped to false if the value could -* not be decoded. -*/ +/// @brief Decode a transformed, human readable value from an raw CAN signal +/// already parsed from a CAN message. +/// +/// This is the same as decodeSignal but you must parse the bitfield value of the signal from the CAN +/// message yourself. This is useful if you need that raw value for something +/// else. +/// +/// @param[in] signal - The details of the signal to decode and forward. +/// @param[in] message - Raw CAN message to decode +/// @param[in] signals - an array of all active signals. +/// @param[out] send - An output parameter that will be flipped to false if the value could +/// not be decoded. +/// openxc_DynamicField decoder_t::decodeSignal( can_signal_t& signal, const can_message_t& message, const std::vector& signals, bool* send) { @@ -218,20 +218,22 @@ openxc_DynamicField decoder_t::decodeSignal( can_signal_t& signal, } -/** -* @brief Decode the payload of an OBD-II PID. -* -* This function matches the type signature for a DiagnosticResponseDecoder, so -* it can be used as the decoder for a DiagnosticRequest. It returns the decoded -* value of the PID, using the standard formulas (see -* http://en.wikipedia.org/wiki/OBD-II_PIDs#Mode_01). -* -* @param[in] response - the received DiagnosticResponse (the data is in response.payload, -* a byte array). This is most often used when the byte order is -* signiticant, i.e. with many OBD-II PID formulas. -* @param[in] parsed_payload - the entire payload of the response parsed as an int. -*/ -float decoder_t::decode_obd2_response(const DiagnosticResponse* response, float parsedPayload) +/// +/// @brief Decode the payload of an OBD-II PID. +/// +/// This function matches the type signature for a DiagnosticResponseDecoder, so +/// it can be used as the decoder for a DiagnosticRequest. It returns the decoded +/// value of the PID, using the standard formulas (see +/// http://en.wikipedia.org/wiki/OBD-II_PIDs#Mode_01). +/// +/// @param[in] response - the received DiagnosticResponse (the data is in response.payload, +/// a byte array). This is most often used when the byte order is +/// signiticant, i.e. with many OBD-II PID formulas. +/// @param[in] parsed_payload - the entire payload of the response parsed as an int. +/// +/// @return Float decoded value. +/// +float decoder_t::decode_obd2_response(const DiagnosticResponse* response, float parsed_payload) { return diagnostic_decode_obd2_pid(response); } \ No newline at end of file diff --git a/src/can/can-decoder.hpp b/src/can/can-decoder.hpp index 0507a6b..ebe1de2 100644 --- a/src/can/can-decoder.hpp +++ b/src/can/can-decoder.hpp @@ -44,6 +44,6 @@ public: static openxc_DynamicField decodeSignal(can_signal_t& signal, float value, const std::vector& signals, bool* send); - static float decode_obd2_response(const DiagnosticResponse* response, float parsedPayload); + static float decode_obd2_response(const DiagnosticResponse* response, float parsed_payload); }; \ No newline at end of file diff --git a/src/can/can-message.cpp b/src/can/can-message.cpp index 5d8c9cb..af0d3f3 100644 --- a/src/can/can-message.cpp +++ b/src/can/can-message.cpp @@ -21,11 +21,11 @@ #include "../low-can-binding.hpp" -/** -* @brief Class constructor -* -* Constructor about can_message_t class. -*/ +/// +/// @brief Class constructor +/// +/// Constructor about can_message_t class. +/// can_message_t::can_message_t() : maxdlen_{0}, id_{0}, length_{0}, format_{can_message_format_t::ERROR}, rtr_flag_{false}, flags_{0} {} @@ -46,31 +46,31 @@ can_message_t::can_message_t(uint8_t maxdlen, data_{data} {} -/** -* @brief Retrieve id_ member value. -* -* @return id_ class member -*/ +/// +/// @brief Retrieve id_ member value. +/// +/// @return id_ class member +/// uint32_t can_message_t::get_id() const { return id_; } -/** -* @brief Retrieve RTR flag member. -* -* @return rtr_flags_ class member -*/ +/// +/// @brief Retrieve RTR flag member. +/// +/// @return rtr_flags_ class member +/// bool can_message_t::get_rtr_flag_() const { return rtr_flag_; } -/** -* @brief Retrieve format_ member value. -* -* @return format_ class member -*/ +/// +/// @brief Retrieve format_ member value. +/// +/// @return format_ class member +/// can_message_format_t can_message_t::get_format() const { if (format_ != can_message_format_t::STANDARD || format_ != can_message_format_t::EXTENDED) @@ -78,43 +78,43 @@ can_message_format_t can_message_t::get_format() const return format_; } -/** -* @brief Retrieve flags_ member value. -* -* @return flags_ class member -*/ +/// +/// @brief Retrieve flags_ member value. +/// +/// @return flags_ class member +/// uint8_t can_message_t::get_flags() const { return flags_; } -/** -* @brief Retrieve data_ member value. -* -* @return pointer to the first element -* of class member data_ -*/ +/// +/// @brief Retrieve data_ member value. +/// +/// @return pointer to the first element +/// of class member data_ +/// const uint8_t* can_message_t::get_data() const { return data_.data(); } -/** -* @brief Retrieve length_ member value. -* -* @return length_ class member -*/ +/// +/// @brief Retrieve length_ member value. +/// +/// @return length_ class member +/// uint8_t can_message_t::get_length() const { return length_; } -/** -* @brief Control whether the object is correctly initialized -* to be sent over the CAN bus -* -* @return true if object correctly initialized and false if not. -*/ +/// +/// @brief Control whether the object is correctly initialized +/// to be sent over the CAN bus +/// +/// @return true if object correctly initialized and false if not. +/// bool can_message_t::is_correct_to_send() { if (id_ != 0 && length_ != 0 && format_ != can_message_format_t::ERROR) @@ -127,14 +127,14 @@ bool can_message_t::is_correct_to_send() return false; } -/** -* @brief Set format_ member value. -* -* Preferred way to initialize these members by using -* convert_from_canfd_frame method. -* -* @param[in] new_format - class member -*/ +/// +/// @brief Set format_ member value. +/// +/// Preferred way to initialize these members by using +/// convert_from_canfd_frame method. +/// +/// @param[in] new_format - class member +/// void can_message_t::set_format(const can_message_format_t new_format) { if(new_format == can_message_format_t::STANDARD || new_format == can_message_format_t::EXTENDED || new_format == can_message_format_t::ERROR) @@ -143,16 +143,16 @@ void can_message_t::set_format(const can_message_format_t new_format) ERROR(binder_interface, "ERROR: Can set format, wrong format chosen"); } -/** -* @brief Take a canfd_frame struct to initialize class members -* -* This is the preferred way to initialize class members. -* -* @param[in] frame - canfd_frame to convert coming from a read of CAN socket -* @param[in] nbyte - bytes read from socket read operation. -* -* @return A can_message_t object fully initialized with canfd_frame values. -*/ +/// +/// @brief Take a canfd_frame struct to initialize class members +/// +/// This is the preferred way to initialize class members. +/// +/// @param[in] frame - canfd_frame to convert coming from a read of CAN socket +/// @param[in] nbytes - bytes read from socket read operation. +/// +/// @return A can_message_t object fully initialized with canfd_frame values. +/// can_message_t can_message_t::convert_from_canfd_frame(const struct canfd_frame& frame, size_t nbytes) { uint8_t maxdlen, length, flags = (uint8_t)NULL; @@ -240,13 +240,13 @@ can_message_t can_message_t::convert_from_canfd_frame(const struct canfd_frame& return can_message_t(maxdlen, id, length, format, rtr_flag, flags, data); } -/** -* @brief Take all initialized class's members and build an -* canfd_frame struct that can be use to send a CAN message over -* the bus. -* -* @return canfd_frame struct built from class members. -*/ +/// +/// @brief Take all initialized class's members and build an +/// canfd_frame struct that can be use to send a CAN message over +/// the bus. +/// +/// @return canfd_frame struct built from class members. +/// canfd_frame can_message_t::convert_to_canfd_frame() { canfd_frame frame; diff --git a/src/can/can-signals.hpp b/src/can/can-signals.hpp index aacb888..34ebeeb 100644 --- a/src/can/can-signals.hpp +++ b/src/can/can-signals.hpp @@ -1,19 +1,19 @@ -/* - * Copyright (C) 2015, 2016 "IoT.bzh" - * Author "Romain Forlot" - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ +/// +/// Copyright (C) 2015, 2016 "IoT.bzh" +/// Author "Romain Forlot" +/// +/// Licensed under the Apache License, Version 2.0 (the "License"); +/// you may not use this file except in compliance with the License. +/// You may obtain a copy of the License at +/// +/// http://www.apache.org/licenses/LICENSE-2.0 +/// +/// Unless required by applicable law or agreed to in writing, software +/// distributed under the License is distributed on an "AS IS" BASIS, +/// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +/// See the License for the specific language governing permissions and +/// limitations under the License. +/// #pragma once @@ -40,36 +40,36 @@ extern "C" class can_signal_t; -/** - * @brief The type signature for a CAN signal decoder. - * - * @desc A SignalDecoder transforms a raw floating point CAN signal into a number, - * string or boolean. - * - * @param[in] signal - The CAN signal that we are decoding. - * @param[in] signals - The list of all signals. - * @param[in] signalCount - The length of the signals array. - * @param[in] value - The CAN signal parsed from the message as a raw floating point - * value. - * @param[out] send - An output parameter. If the decoding failed or the CAN signal should - * not send for some other reason, this should be flipped to false. - * - * @return a decoded value in an openxc_DynamicField struct. - */ +/// +/// @brief The type signature for a CAN signal decoder. +/// +/// A SignalDecoder transforms a raw floating point CAN signal into a number, +/// string or boolean. +/// +/// @param[in] signal - The CAN signal that we are decoding. +/// @param[in] signals - The list of all signals. +/// @param[in] signalCount - The length of the signals array. +/// @param[in] value - The CAN signal parsed from the message as a raw floating point +/// value. +/// @param[out] send - An output parameter. If the decoding failed or the CAN signal should +/// not send for some other reason, this should be flipped to false. +/// +/// @return a decoded value in an openxc_DynamicField struct. +/// typedef openxc_DynamicField (*SignalDecoder)(can_signal_t& signal, const std::vector& signals, float value, bool* send); -/** - * @brief: The type signature for a CAN signal encoder. - * - * @desc A SignalEncoder transforms a number, string or boolean into a raw floating - * point value that fits in the CAN signal. - * - * @params[in] signal - The CAN signal to encode. - * @params[in] value - The dynamic field to encode. - * @params send - An output parameter. If the encoding failed or the CAN signal should - * not be encoded for some other reason, this will be flipped to false. - */ +/// +/// @brief: The type signature for a CAN signal encoder. +/// +/// A SignalEncoder transforms a number, string or boolean into a raw floating +/// point value that fits in the CAN signal. +/// +/// @param[in] signal - The CAN signal to encode. +/// @param[in] value - The dynamic field to encode. +/// @param[out] send - An output parameter. If the encoding failed or the CAN signal should +/// not be encoded for some other reason, this will be flipped to false. +/// typedef uint64_t (*SignalEncoder)(can_signal_t* signal, openxc_DynamicField* value, bool* send); diff --git a/src/configuration.hpp b/src/configuration.hpp index be188b9..57eeef3 100644 --- a/src/configuration.hpp +++ b/src/configuration.hpp @@ -29,17 +29,17 @@ #include "low-can-binding.hpp" -/** - * @brief Class representing a configuration attached to the binding. - * - * @desc It regroups all needed objects instance from other class - * that will be used along the binding life. It gets a global vision - * on which signals are implemented for that binding. - * Here, it is only the definition of the class with predefined accessors - * methods used in the binding. - * - * It will be the reference point to needed objects. - */ +/// +/// @brief Class representing a configuration attached to the binding. +/// +/// It regroups all needed objects instance from other class +/// that will be used along the binding life. It gets a global vision +/// on which signals are implemented for that binding. +/// Here, it is only the definition of the class with predefined accessors +/// methods used in the binding. +/// +/// It will be the reference point to needed objects. +/// class configuration_t { private: diff --git a/src/diagnostic/active-diagnostic-request.cpp b/src/diagnostic/active-diagnostic-request.cpp index 9e64bd5..a9c21c6 100644 --- a/src/diagnostic/active-diagnostic-request.cpp +++ b/src/diagnostic/active-diagnostic-request.cpp @@ -24,7 +24,6 @@ #define ERROR_PID 0xFF -// @brief std::string active_diagnostic_request_t::prefix_ = "diagnostic_messages"; bool active_diagnostic_request_t::operator==(const active_diagnostic_request_t& b) diff --git a/src/diagnostic/active-diagnostic-request.hpp b/src/diagnostic/active-diagnostic-request.hpp index 452ff97..247eeb1 100644 --- a/src/diagnostic/active-diagnostic-request.hpp +++ b/src/diagnostic/active-diagnostic-request.hpp @@ -53,7 +53,7 @@ typedef void (*DiagnosticResponseCallback)(const active_diagnostic_request_t* re /// /// @brief An active diagnostic request, either recurring or one-time. /// -/// @desc Will host a diagnostic_message_t class members to describe an on going +/// Will host a diagnostic_message_t class members to describe an on going /// diagnostic request on the CAN bus. Diagnostic message will be converted to /// a DiagnosticRequest using ad-hoc method build_diagnostic_request from diagnostic message. /// Then missing member, that can not be hosted into a DiagnosticRequest struct, will be passed diff --git a/src/diagnostic/diagnostic-manager.cpp b/src/diagnostic/diagnostic-manager.cpp index 07b08ca..2d4669e 100644 --- a/src/diagnostic/diagnostic-manager.cpp +++ b/src/diagnostic/diagnostic-manager.cpp @@ -37,7 +37,7 @@ diagnostic_manager_t::diagnostic_manager_t() /// to have 1 diagnostic bus which are the first bus declared in the JSON /// description file. Configuration instance will return it. /// -/// @desc this will initialize DiagnosticShims and cancel all active requests +/// this will initialize DiagnosticShims and cancel all active requests /// if there are any. bool diagnostic_manager_t::initialize() { @@ -222,7 +222,7 @@ active_diagnostic_request_t* diagnostic_manager_t::find_recurring_request(const /// @brief Add and send a new one-time diagnostic request. /// -/// @desc A one-time (aka non-recurring) request can existing in parallel with a +/// A one-time (aka non-recurring) request can existing in parallel with a /// recurring request for the same PID or mode, that's not a problem. /// /// For an example, see the docs for addRecurringRequest. This function is very @@ -232,7 +232,7 @@ active_diagnostic_request_t* diagnostic_manager_t::find_recurring_request(const /// @param[in] name - Human readable name this response, to be used when /// publishing received responses. TODO: If the name is NULL, the published output /// will use the raw OBD-II response format. -/// @param[in] waitForMultipleResponses - If false, When any response is received +/// @param[in] wait_for_multiple_responses - If false, When any response is received /// for this request it will be removed from the active list. If true, the /// request will remain active until the timeout clock expires, to allow it /// to receive multiple response. Functional broadcast requests will always @@ -326,7 +326,7 @@ bool diagnostic_manager_t::validate_optional_request_attributes(float frequencyH /// @param[in] name - An optional human readable name this response, to be used when /// publishing received responses. If the name is NULL, the published output /// will use the raw OBD-II response format. -/// @param[in] waitForMultipleResponses - If false, When any response is received +/// @param[in] wait_for_multiple_responses - If false, When any response is received /// for this request it will be removed from the active list. If true, the /// request will remain active until the timeout clock expires, to allow it /// to receive multiple response. Functional broadcast requests will always diff --git a/src/diagnostic/diagnostic-manager.hpp b/src/diagnostic/diagnostic-manager.hpp index c66e21a..bd5cefb 100644 --- a/src/diagnostic/diagnostic-manager.hpp +++ b/src/diagnostic/diagnostic-manager.hpp @@ -26,20 +26,20 @@ #include "../can/can-bus.hpp" #include "active-diagnostic-request.hpp" -/* Each CAN bus needs its own set of shim functions, so this should - * match the maximum CAN controller count. - */ +/// Each CAN bus needs its own set of shim functions, so this should +/// match the maximum CAN controller count. +/// #define MAX_SHIM_COUNT can_bus_t.get_can_devices().size() #define DIAGNOSTIC_RESPONSE_ARBITRATION_ID_OFFSET 0x8 class active_diagnostic_request_t; -/** - * @brief The core structure for running the diagnostics module by the binding. - * - * @desc This stores details about the active requests and shims required to connect - * the diagnostics library to the CAN device. - */ +/// +/// @brief The core structure for running the diagnostics module by the binding. +/// +/// This stores details about the active requests and shims required to connect +/// the diagnostics library to the CAN device. +/// class diagnostic_manager_t { protected: static bool shims_send(const uint32_t arbitration_id, const uint8_t* data, const uint8_t size); diff --git a/src/diagnostic/diagnostic-message.cpp b/src/diagnostic/diagnostic-message.cpp index ca8bf84..6f61557 100644 --- a/src/diagnostic/diagnostic-message.cpp +++ b/src/diagnostic/diagnostic-message.cpp @@ -80,10 +80,10 @@ void diagnostic_message_t::set_supported(bool value) supported_ = value; } -/** - * @brief Build a DiagnosticRequest struct to be passed - * to diagnostic manager instance. - */ +/// +/// @brief Build a DiagnosticRequest struct to be passed +/// to diagnostic manager instance. +/// const DiagnosticRequest diagnostic_message_t::build_diagnostic_request() { return {/*arbitration_id: */OBD2_FUNCTIONAL_BROADCAST_ID, @@ -97,11 +97,11 @@ const DiagnosticRequest diagnostic_message_t::build_diagnostic_request() /*DiagnosticRequestType: */DiagnosticRequestType::DIAGNOSTIC_REQUEST_TYPE_PID }; } -/** -* @brief Check if a request is an OBD-II PID request. -* -* @return true if the request is a mode 1 request and it has a 1 byte PID. -*/ +/// +/// @brief Check if a request is an OBD-II PID request. +/// +/// @return true if the request is a mode 1 request and it has a 1 byte PID. +/// bool diagnostic_message_t::is_obd2_request(const DiagnosticRequest* request) { return request->mode == 0x1 && request->has_pid && request->pid < 0xff; diff --git a/src/diagnostic/diagnostic-message.hpp b/src/diagnostic/diagnostic-message.hpp index b25fea3..064904d 100644 --- a/src/diagnostic/diagnostic-message.hpp +++ b/src/diagnostic/diagnostic-message.hpp @@ -38,17 +38,17 @@ enum UNIT { INVALID }; -/** - * @brief - A representation of an OBD-II PID. - */ +/// +/// @brief - A representation of an OBD-II PID. +/// class diagnostic_message_t { private: - uint8_t pid_; /*!< pid - The 1 byte PID.*/ + uint8_t pid_; /*!< pid_ - The 1 byte PID.*/ std::string generic_name_; /*!< generic_name_ - A human readable name to use for this PID when published.*/ int min_; /*!< min_ - Minimum value that can take this pid */ int max_; /*!< max_ - Maximum value that can take this pid */ enum UNIT unit_; /*!< unit_ : Which unit system is used by that pid. See enum UNIT above.*/ - float frequency_; /*!< frequency - The frequency to request this PID if supported by the vehicle when automatic, recurring OBD-II requests are enabled.*/ + float frequency_; /*!< frequency_ - The frequency to request this PID if supported by the vehicle when automatic, recurring OBD-II requests are enabled.*/ DiagnosticResponseDecoder decoder_; /*!< decoder_ - An optional DiagnosticResponseDecoder to parse the payload of responses * to this request. If the decoder is NULL, the output will include the raw payload * instead of a parsed value.*/ diff --git a/src/low-can-binding.cpp b/src/low-can-binding.cpp index 2b04fa8..d88ac99 100644 --- a/src/low-can-binding.cpp +++ b/src/low-can-binding.cpp @@ -45,11 +45,11 @@ extern "C" // Interface between the daemon and the binding const struct afb_binding_interface *binder_interface; -/******************************************************************************** -* -* Subscription and unsubscription -* -*********************************************************************************/ +///****************************************************************************** +/// +/// Subscription and unsubscription +/// +///*******************************************************************************/ static int make_subscription_unsubscription(struct afb_req request, const std::string& sig_name, std::map& s, bool subscribe) { @@ -109,16 +109,16 @@ static int subscribe_unsubscribe_signal(struct afb_req request, bool subscribe, return make_subscription_unsubscription(request, sig, s, subscribe); } -/** - * @fn static int subscribe_unsubscribe_signals(struct afb_req request, bool subscribe, const std::vector& signals) - * @brief subscribe to all signals in the vector signals - * - * @param[in] afb_req request : contain original request use to subscribe or unsubscribe - * @param[in] subscribe boolean value used to chose between a subscription operation or an unsubscription - * @param[in] can_signal_t vector with can_signal_t to subscribe - * - * @return Number of correctly subscribed signal - */ +/// +/// @fn static int subscribe_unsubscribe_signals(struct afb_req request, bool subscribe, const std::vector& signals) +/// @brief subscribe to all signals in the vector signals +/// +/// @param[in] afb_req request : contain original request use to subscribe or unsubscribe +/// @param[in] subscribe boolean value used to chose between a subscription operation or an unsubscription +/// @param[in] can_signal_t vector with can_signal_t to subscribe +/// +/// @return Number of correctly subscribed signal +/// static int subscribe_unsubscribe_signals(struct afb_req request, bool subscribe, const std::vector& signals) { int rets = 0; @@ -243,13 +243,11 @@ extern "C" return &binding_desc; } - /** - * @brief Initialize the binding. - * - * @param[in] service Structure which represent the Application Framework Binder. - * - * @return Exit code, zero if success. - */ + /// @brief Initialize the binding. + /// + /// @param[in] service Structure which represent the Application Framework Binder. + /// + /// @return Exit code, zero if success. int afbBindingV1ServiceInit(struct afb_service service) { can_bus_t& can_bus_manager = configuration_t::instance().get_can_bus_manager(); diff --git a/src/utils/openxc-utils.cpp b/src/utils/openxc-utils.cpp index 111ac1d..52b49d2 100644 --- a/src/utils/openxc-utils.cpp +++ b/src/utils/openxc-utils.cpp @@ -20,17 +20,17 @@ #include "../configuration.hpp" -/** - * @brief Build a specific VehicleMessage containing a DiagnosticResponse. - * - * @param[in] request - Original request use to retrieve decoder and callback - * @param[in] response - Response to the request that will be decoded if decoder set - * and put into the DiagnosticResponse of the VehicleMessage. - * @param[in] parsed_value - raw parsed value of the payload from CAN message - * - * @return a vehicle message including simple message that will be convert into - * a JSON object before being pushed to the subscribers - */ +/// +/// @brief Build a specific VehicleMessage containing a DiagnosticResponse. +/// +/// @param[in] request - Original request use to retrieve decoder and callback +/// @param[in] response - Response to the request that will be decoded if decoder set +/// and put into the DiagnosticResponse of the VehicleMessage. +/// @param[in] parsed_value - raw parsed value of the payload from CAN message +/// +/// @return a vehicle message including simple message that will be convert into +/// a JSON object before being pushed to the subscribers +/// openxc_VehicleMessage build_VehicleMessage(active_diagnostic_request_t* request, const DiagnosticResponse& response, float parsed_value) { openxc_VehicleMessage message; @@ -85,14 +85,14 @@ openxc_VehicleMessage build_VehicleMessage(active_diagnostic_request_t* request, return message; } -/** - * @brief Build a specific VehicleMessage containing a SimpleMessage. - * - * @param[in] message - simple message to include into openxc_VehicleMessage - * - * @return a vehicle message including simple message that will be convert into - * a JSON object before being pushed to the subscribers - */ +/// +/// @brief Build a specific VehicleMessage containing a SimpleMessage. +/// +/// @param[in] message - simple message to include into openxc_VehicleMessage +/// +/// @return a vehicle message including simple message that will be convert into +/// a JSON object before being pushed to the subscribers +/// openxc_VehicleMessage build_VehicleMessage(const openxc_SimpleMessage& message) { openxc_VehicleMessage v; @@ -107,12 +107,12 @@ openxc_VehicleMessage build_VehicleMessage(const openxc_SimpleMessage& message) return v; } -/** - * @brief Build an empty VehicleMessage that isn't usable by at least the struct - * is initialized for the most part and can be use to check a false return value. - * - * @return A VehicleMessage with all boolean value to false. - */ +/// +/// @brief Build an empty VehicleMessage that isn't usable by at least the struct +/// is initialized for the most part and can be use to check a false return value. +/// +/// @return A VehicleMessage with all boolean value to false. +/// openxc_VehicleMessage build_VehicleMessage() { openxc_VehicleMessage v; @@ -134,17 +134,17 @@ bool is_valid(const openxc_VehicleMessage& v) return true; } -/** - * @brief Build an openxc_SimpleMessage associating a name to an openxc_DynamicField - * - * @param[in] name - const string reference name to assign to the created SimpleMessage - * this will set has_name member to true and assign name to the name member. Maximum size for name is - * set to 100 char. - * @param[in] value - const reference with DynamicField to assign to SimpleMessage - * value. - * - * @return an openxc_SimpleMessage struct initialized with name and value provided. - */ +/// +/// @brief Build an openxc_SimpleMessage associating a name to an openxc_DynamicField +/// +/// @param[in] name - const string reference name to assign to the created SimpleMessage +/// this will set has_name member to true and assign name to the name member. Maximum size for name is +/// set to 100 char. +/// @param[in] value - const reference with DynamicField to assign to SimpleMessage +/// value. +/// +/// @return an openxc_SimpleMessage struct initialized with name and value provided. +/// openxc_SimpleMessage build_SimpleMessage(const std::string& name, const openxc_DynamicField& value) { openxc_SimpleMessage s; @@ -157,14 +157,14 @@ openxc_SimpleMessage build_SimpleMessage(const std::string& name, const openxc_D return s; } -/** - * @brief Build an openxc_DynamicField with a string value - * - * @param[in] value - const string reference value to assign to builded - * openxc_DynamicField. - * - * @return openxc_DynamicField initialized with a string value. - */ +/// +/// @brief Build an openxc_DynamicField with a string value +/// +/// @param[in] value - const string reference value to assign to builded +/// openxc_DynamicField. +/// +/// @return openxc_DynamicField initialized with a string value. +/// openxc_DynamicField build_DynamicField(const std::string& value) { openxc_DynamicField d; @@ -179,15 +179,15 @@ openxc_DynamicField build_DynamicField(const std::string& value) return d; } -/** - * @fn openxc_DynamicField build_DynamicField(double value); - * - * @brief Build an openxc_DynamicField with a double value - * - * @param[in] value - double value to assign to builded openxc_DynamicField. - * - * @return openxc_DynamicField initialized with a double value. - */ +/// +/// @fn openxc_DynamicField build_DynamicField(double value); +/// +/// @brief Build an openxc_DynamicField with a double value +/// +/// @param[in] value - double value to assign to builded openxc_DynamicField. +/// +/// @return openxc_DynamicField initialized with a double value. +/// openxc_DynamicField build_DynamicField(double value) { openxc_DynamicField d; @@ -202,13 +202,13 @@ openxc_DynamicField build_DynamicField(double value) return d; } -/** - * @brief Build an openxc_DynamicField with a boolean value - * - * @param[in] value - boolean value to assign to builded openxc_DynamicField. - * - * @return openxc_DynamicField initialized with a boolean value. - */ +/// +/// @brief Build an openxc_DynamicField with a boolean value +/// +/// @param[in] value - boolean value to assign to builded openxc_DynamicField. +/// +/// @return openxc_DynamicField initialized with a boolean value. +/// openxc_DynamicField build_DynamicField(bool value) { openxc_DynamicField d; @@ -223,16 +223,16 @@ openxc_DynamicField build_DynamicField(bool value) return d; } -/** - * @brief Extract the simple message value from an openxc_VehicleMessage - * and return it. If there isn't SimpleMessage in the VehicleMessage then - * returned value will be a SimpleMessage with all field set at false. - * DynamicField from SimpleMessage will be boolean DynamicField set to false too. - * - * @param[in] v_msg - const reference to openxc_VehicleMessage - * - * @return A simpleMessage from the provided VehicleMessage. - */ +/// +/// @brief Extract the simple message value from an openxc_VehicleMessage +/// and return it. If there isn't SimpleMessage in the VehicleMessage then +/// returned value will be a SimpleMessage with all field set at false. +/// DynamicField from SimpleMessage will be boolean DynamicField set to false too. +/// +/// @param[in] v_msg - const reference to openxc_VehicleMessage +/// +/// @return A simpleMessage from the provided VehicleMessage. +/// openxc_SimpleMessage get_simple_message(const openxc_VehicleMessage& v_msg) { if (v_msg.has_simple_message) @@ -242,13 +242,13 @@ openxc_SimpleMessage get_simple_message(const openxc_VehicleMessage& v_msg) return s_msg; } -/** - * @brief Make a JSON object from a DynamicField - * - * @param[in] field - openxc_DynamicField struct to convert into - * a json object. - * @param[out] value - pointer to the object to set up. - */ +/// +/// @brief Make a JSON object from a DynamicField +/// +/// @param[in] field - openxc_DynamicField struct to convert into +/// a json object. +/// @param[out] value - pointer to the object to set up. +/// void jsonify_DynamicField(const openxc_DynamicField& field, json_object* value) { if(field.has_numeric_value) @@ -259,16 +259,16 @@ void jsonify_DynamicField(const openxc_DynamicField& field, json_object* value) json_object_object_add(value, "value", json_object_new_string(field.string_value)); } -/** - * @brief Make a JSON object from a SimpleMessage - * - * @param[in] s_msg - const reference to an openxc_SimpleMessage - * struct to convert into a json object. - * @param[out] json - pointer with the DynamicField converted into json object - * - * @return True if SimpleMessage has been transformed into json object - * and false if not. In such case, a json object is returned { "error": "error msg"} - */ +/// +/// @brief Make a JSON object from a SimpleMessage +/// +/// @param[in] s_msg - const reference to an openxc_SimpleMessage +/// struct to convert into a json object. +/// @param[out] json - pointer with the DynamicField converted into json object +/// +/// @return True if SimpleMessage has been transformed into json object +/// and false if not. In such case, a json object is returned { "error": "error msg"} +/// bool jsonify_simple(const openxc_SimpleMessage& s_msg, json_object* json) { if(s_msg.has_name) diff --git a/src/utils/signals.cpp b/src/utils/signals.cpp index 41e13c0..2e14a98 100644 --- a/src/utils/signals.cpp +++ b/src/utils/signals.cpp @@ -17,21 +17,21 @@ #include "signals.hpp" -/** - * @brief Can signal event map making access to afb_event - * externaly to an openxc existing structure. - * - * @desc Event map is making relation between can_signal_t generic name - * and the afb_event struct used by application framework to pushed - * to the subscriber. - */ +/// +/// @brief Can signal event map making access to afb_event +/// externaly to an openxc existing structure. +/// +/// Event map is making relation between can_signal_t generic name +/// and the afb_event struct used by application framework to pushed +/// to the subscriber. +/// std::map subscribed_signals; -/** -* @brief Mutex allowing safe manipulation on subscribed_signals map. -* @desc To ensure that the map object isn't modified when we read it, you -* have to set this mutex before use subscribed_signals map object. -*/ +/// +/// @brief Mutex allowing safe manipulation on subscribed_signals map. +/// To ensure that the map object isn't modified when we read it, you +/// have to set this mutex before use subscribed_signals map object. +/// std::mutex subscribed_signals_mutex; std::mutex& get_subscribed_signals_mutex() @@ -44,15 +44,15 @@ std::map& get_subscribed_signals() return subscribed_signals; } -/** - * @fn std::vector find_signals(const openxc_DynamicField &key) - * @brief return signals name found searching through CAN_signals and OBD2 pid - * - * @param[in] const openxc_DynamicField : can contain numeric or string value in order to search against - * can signals or obd2 signals name. - * - * @return std::vector Vector of signals name found. - */ +/// +/// @fn std::vector find_signals(const openxc_DynamicField &key) +/// @brief return signals name found searching through CAN_signals and OBD2 pid +/// +/// @param[in] key : can contain numeric or string value in order to search against +/// can signals or obd2 signals name. +/// +/// @return Vector of signals name found. +/// std::vector find_signals(const openxc_DynamicField &key) { std::vector found_signals_name; diff --git a/src/utils/timer.cpp b/src/utils/timer.cpp index 784bb46..7c2560e 100644 --- a/src/utils/timer.cpp +++ b/src/utils/timer.cpp @@ -60,6 +60,7 @@ frequency_clock_t::frequency_clock_t(float frequency) {} /// @brief Return the period in ms given the frequency in hertz. +/// @param[in] frequency - Frequency to convert, in Hertz float frequency_clock_t::frequency_to_period(float frequency) { return 1 / frequency; diff --git a/src/utils/timer.hpp b/src/utils/timer.hpp index b34fdf6..5be0e3c 100644 --- a/src/utils/timer.hpp +++ b/src/utils/timer.hpp @@ -17,35 +17,24 @@ #pragma once -/* - * @brief return epoch in milliseconds - * - * @return long long int epoch in milliseconds - */ +/// @brief return epoch in milliseconds +/// +/// @return long long int epoch in milliseconds typedef long long int (*time_function_t)(); long long int system_time_us(); long long int system_time_ms(); long long int system_time_s(); -/** - * @class frequency_clock_t - * @brief A frequency counting clock. - * - * @var frequency_clock_t::frequency - * the clock frequency in Hz. - * @var frequency_clock_t::last_time - * the last time (in milliseconds since startup) that the clock - * ticked. - * @var frequency_clock_t::time_function - * a function returning current time - */ + +/// @brief A frequency counting clock. +/// Utility class allowing some time function. class frequency_clock_t { private: - float frequency_; - unsigned long last_tick_; - time_function_t time_function_; + float frequency_; ///< the clock frequency in Hz. + unsigned long last_tick_; ///< the last time (in milliseconds since startup) that the clock ticked. + time_function_t time_function_; ///< a function returning current time public: frequency_clock_t(); -- cgit 1.2.3-korg