Fixed some warnings in documentation compilation

[pes-rpp/rpp-lib.git] / rpp / include / rpp / can.h

diff --git a/rpp/include/rpp/can.h b/rpp/include/rpp/can.h
index 89723aa0e97dc5ae6de6f31c0803c0e77c0178b6..840117c979aee96617da255872ac3dff83302dc0 100644 (file)
--- a/rpp/include/rpp/can.h
+++ b/rpp/include/rpp/can.h
@@ -23,11 +23,19 @@ typedef uint16_t rpp_can_hw_obj;
  * CAN frame
  */
 struct rpp_can_pdu {
-       uint32_t id;
-       uint8_t dlc;
-       uint8_t data[8];
+       uint32_t id;    /**< The message ID. */
+       uint8_t dlc;    /**< The length of the data in bytes. */
+       uint8_t data[8];        /**< The data payload. */
 };
 
+/**
+ * CAN frame type selector
+ *
+ * RPP_CAN_STANDARD - 11b message ID and mask
+ * RPP_CAN_EXTENDED - 29b message ID and mask
+ * RPP_CAN_MIXED - allows the receive message object to receive both
+ * type of CAN frames. This value is invalid for transmit message objects.
+ */
 enum rpp_can_frame_type {
        RPP_CAN_STANDARD,
        RPP_CAN_EXTENDED,
@@ -45,22 +53,49 @@ enum rpp_can_timing_calculation {
        RPP_CAN_TIMING_CALC_AUTO
 };
 
+/**
+ * CAN transmit message object configuration.
+ *
+ * Stores all necessary parameters for configuring one transmit message object.
+ *
+ * The TMS570LS3137 has 3 CAN controllers.
+ *
+ * The mailbox number range for TMS570LS3137 is 0-63 and it must be unique for
+ * all RX and TX message objects.
+ *
+ */
 struct rpp_can_tx_config {
-       enum rpp_can_frame_type type;
-       uint8_t controller;
-       uint8_t msg_obj;
+       enum rpp_can_frame_type type;   /**< The type of the CAN frame. */
+       uint8_t controller;     /**< The CAN controller selector. CAN1 - CAN3. */
+       uint8_t msg_obj;        /**< The number of message object (mailbox) to use */
 };
 
+/**
+ * CAN receive message object configuration.
+ *
+ * Stores all necessary parameters for configuring one receive message object.
+ *
+ * The TMS570LS3137 has 3 CAN controllers.
+ *
+ * The mailbox number range for TMS570LS3137 is 0-63 and it must be unique for
+ * all RX and TX message objects.
+ *
+ * The ID and the mask define acceptance filter and its range depends on the
+ * frame type.
+ *
+ */
 struct rpp_can_rx_config {
-       enum rpp_can_frame_type type;
-       uint8_t controller;
-       uint8_t msg_obj;
-       uint32_t id;
-       uint32_t mask;
+       enum rpp_can_frame_type type;   /**< The type of the CAN frame. */
+       uint8_t controller;     /**< The CAN controller selector. CAN1 - CAN3. */
+       uint8_t msg_obj;        /**< The number of message object (mailbox) to use */
+       uint32_t id;    /**< The message ID. */
+       uint32_t mask;  /**< The mask for the message ID. */
 };
 
 /**
- * CAN controller configuration. Data stored in this structure varies on the timing_calc_method value.
+ * CAN controller configuration.
+ *
+ * Data stored in this structure varies on the timing_calc_method value.
  * If timing_calc_method is RPP_CAN_TIMING_CALC_MANUAL, the baudrate and clk is not used and
  * timing_config must point to a structure with the timing parameters.
  *
@@ -95,15 +130,21 @@ struct rpp_can_timing_cfg {
        int sampl_pt;           /**< The Sample point delay from the start of the frame in ns. */
 };
 
+/**
+ * Root of the CAN configuration.
+ *
+ * Contains an array of RX message objects, array of TX message objects and an array of
+ * the configurations of all the CAN controllers.
+ */
 struct rpp_can_config {
-       uint16_t num_tx_obj;
-       uint16_t num_rx_obj;
-       struct rpp_can_tx_config *tx_config;
-       struct rpp_can_rx_config *rx_config;
-       struct rpp_can_ctrl_config *ctrl;
+       uint16_t num_tx_obj;    /**< Number of transmit message objects. */
+       uint16_t num_rx_obj;    /**< Number of receive message objects. */
+       struct rpp_can_tx_config *tx_config;    /**< Array of configurations of transmit message objects. */
+       struct rpp_can_rx_config *rx_config;    /**< Array of configurations of receive message objects. */
+       struct rpp_can_ctrl_config *ctrl;       /**< Array of CAN controllers configuration. */
 };
 
-#define CAN_EFF_FLAG 0x80000000U
+#define CAN_EFF_FLAG 0x80000000U       /**< Flag for notifying about CAN ERROR FLAG reception. */
 
 /**
  * CAN module initialization.