* CAN frame
*/
struct rpp_can_pdu {
- uint32_t id; /**< The message ID. */
- uint8_t dlc; /**< The length of the data in bytes. */
- uint8_t data[8]; /**< The data payload. */
+ uint32_t id; /**< Message ID */
+ uint8_t dlc; /**< Length of the data in bytes */
+ uint8_t data[8]; /**< Message 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,
- RPP_CAN_MIXED,
+ 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 types of CAN
+ * frames. This value is invalid for
+ * transmit message objects. */
};
/**
- * Timing calculation methods.
- *
- * RPP_CAN_TIMING_CALC_MANUAL for manually specified timing parameters,
- * RPP_CAN_TIMING_CALC_AUTO for automatic parameters calculation from desired baudrate.
+ * Timing parameters calculation method
*/
enum rpp_can_timing_calculation {
- RPP_CAN_TIMING_CALC_MANUAL,
- RPP_CAN_TIMING_CALC_AUTO
+ RPP_CAN_TIMING_CALC_MANUAL, /**< Timing parameters are specified manually. */
+ RPP_CAN_TIMING_CALC_AUTO /**< Timing parameters are calculated automatically from desired baudrate. */
};
/**
*
* 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.
+ * The @a msg_obj index must be unique among all RX and TX message
+ * objects for the same controller.
*
*/
struct rpp_can_tx_config {
- 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 */
+ enum rpp_can_frame_type type; /**< Type of the frame to be transmitted */
+ uint8_t controller; /**< CAN controller index (1-3) */
+ uint8_t msg_obj; /**< Index of message object
+ * (mailbox) to use (0-63) */
};
/**
*
* 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 @a msg_obj index must be unique among all RX and TX message
+ * objects for the same controller.
*
- * The ID and the mask define acceptance filter and its range depends on the
- * frame type.
+ * The @a id and the @a mask define acceptance filter and its range
+ * depends on the frame type.
*
*/
struct rpp_can_rx_config {
- 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. */
+ enum rpp_can_frame_type type; /**< Type of the received CAN frames */
+ uint8_t controller; /**< CAN controller index (1-3) */
+ uint8_t msg_obj; /**< Index of message object (mailbox) to use (0-63) */
+ uint32_t id; /**< Acceptance filter message ID */
+ uint32_t mask; /**< Acceptance filter mask */
};
/**
* 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.
+ * Holds information needed to configure a CAN controller. The
+ * information here depends on the value of @a timing_calc_method. If
+ * @a timing_calc_method is @a RPP_CAN_TIMING_CALC_MANUAL, @a
+ * timing_config must point to a structure with the timing parameters,
+ * otherwise the @a baudrate and @a clk has to be set.
*
- * If timing_calc_method is RPP_CAN_TIMING_CALC_AUTO, the timing_config may be NULL and the timing
- * parameters are calculated by an algorithm from baudrate and clk values.
+ * If timing_calc_method is RPP_CAN_TIMING_CALC_AUTO, the
+ * @a timing_config may be NULL and the timing parameters are calculated
+ * by an algorithm from @a baudrate and @a clk values.
*
*/
struct rpp_can_ctrl_config {
- uint32_t baudrate; /**< Desired baudrate in bits per second. */
- uint32_t clk; /**< CAN input frequency in Hz. */
- enum rpp_can_timing_calculation timing_calc_method; /**< Manual/automatic timing calculation selector. */
- struct rpp_can_timing_cfg *timing_config; /**< CAN frame timing parameters */
+ uint32_t baudrate; /**< Desired baudrate in bits per second */
+ uint32_t clk; /**< Clock frequency of the CAN module in Hz */
+ enum rpp_can_timing_calculation timing_calc_method; /**< Manual/automatic timing calculation selector */
+ struct rpp_can_timing_cfg *timing_config; /**< CAN timing parameters */
};
/**
- * CAN frame timing specification. Used for storing manually specified timing parameters, which derive
- * the baudrate or for storing automatically calculated parameters from specified baudrate.
+ * CAN bit timing specification.
*
- * All fields are filled by the timing calculation algorithm.
- *
- * Only brp, prop_seg, phase_seg1, phase_seg2 and sjw are necessary for manual timing parameters specification.
+ * Specifies parameters for manual configuration of CAN controller
+ * timing. These parameters determine (among others) the used
+ * baudrate.
*
+ * tQ below stands for time quantum and equals to CLK/@a brp.
*/
struct rpp_can_timing_cfg {
- uint16_t brp; /**< Baudrate prescaler (1-64) in tQ. */
- uint8_t prop_seg; /**< The length of the propagation segment (1-8) in tQ. */
- uint8_t phase_seg1; /**< The length of the phase buffer segment 1 (1-8) in tQ. */
- uint8_t phase_seg2; /**< The length of the phase buffer segment 2 (1-8) in tQ. */
- uint8_t sjw; /**< The synchronization jump width (1-4) in tQ. */
- uint32_t tq; /**< The length of the time quantum (tQ) in ns. */
- uint32_t error; /**< The error rate from desired baudrate. */
- int sampl_pt; /**< The Sample point delay from the start of the frame in ns. */
+ uint16_t brp; /**< Baudrate prescaler (1-64) in CLKs. */
+ uint8_t prop_seg; /**< Length of the propagation segment (1-8) in tQ */
+ uint8_t phase_seg1; /**< Length of the phase buffer segment 1 (1-8) in tQ */
+ uint8_t phase_seg2; /**< Length of the phase buffer segment 2 (1-8) in tQ */
+ uint8_t sjw; /**< Synchronization jump width (1-4) in tQ */
+
+ /* TODO: Move the members below out of this structure - this
+ * structure should be read only. */
+ uint32_t tq; /**< The length of the time quantum (tQ) in ns */
+ uint32_t error; /**< The error rate from desired baudrate */
+ 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.
+ * Contains pointers to arrays of RX message objects, TX message
+ * objects and configurations of all the CAN controllers.
*/
struct rpp_can_config {
- 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. */
+ uint16_t num_tx_obj; /**< Number of configured message objects in @a tx_config */
+ uint16_t num_rx_obj; /**< Number of configured message objects in @a rx_config */
+ 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 3 CAN controller configurations */
};
-#define CAN_EFF_FLAG 0x80000000U /**< Flag for notifying about CAN ERROR FLAG reception. */
+/** Flag signalizing reception of EFF frame. */
+#define CAN_EFF_FLAG 0x80000000U
/**
* CAN module initialization.
*
* Call this method before using this module.
*
- * @param[in] config Configuration of the controllers and message objects
+ * @param[in] config Configuration of CAN controllers and message objects
*
- * @return SUCCESS if initialization successful.\n
- * FAILURE if module already initialized.
+ * @return @c SUCCESS if initialization was successful,\n
+ * @c FAILURE otherwise.
*/
int8_t rpp_can_init(const struct rpp_can_config *config);
/**
- * Setup a CAN message for transmission.
+ * Submit a CAN message for transmission.
*
* Data pointed by @a pdu is copied to the given message box for
- * transmission. A successful call to this function also clears the TX
- * confirmation that can be retrieved with rpp_can_check_tx_con()
- * until the written message is transmitted to the bus.
+ * transmission. A successful call to this function also resets the TX
+ * confirmation that can be retrieved with rpp_can_check_tx_con().
+ *
+ * @param[in] hw_obj Index of hardware object to use for transmission.
+ * It is an index to rpp_can_config.tx_config.
*
- * @param[in] hw_obj Hardware object to use for transmission.
* @param[in] pdu Message to send.
*
- * @return SUCCESS if the message was succesfully prepared for transmission,\n
- * FAILURE if an error was detected.
+ * @return @c SUCCESS if the message was successfully submitted for transmission,\n
+ * @c -RPP_EINVAL if invalid hw_obj was specified,\n
+ * @c -RPP_BUSY if previous transmission request is pending on the hardware object.
*/
int8_t rpp_can_write(rpp_can_hw_obj hw_obj, const struct rpp_can_pdu *pdu);
/**
* Checks whether a message was transmitted.
*
- * Call this function to check whether a message previously set for
- * transmission with rpp_can_write() was already transmitted to the
- * bus.
- *
+ * Call this function to check whether a message previously submitted
+ * for transmission with rpp_can_write() still waits for transmission
+ * or has already been transmitted to the bus.
* @param[in] hw_obj Hardware object to be checked.
- * @param[out] tx_con Where to store the TX confirmation flag.
- *
- * @return SUCCESS if tx_con was updated with the requested value,\n
- * -RPP_EINVAL if invalid hw_obj was specified,\n
- * -RPP_BUSY if previous transmission request is pending on the hardware object.
+ * @param[out] tx_con Where to store the TX confirmation flag. Its
+ * value will be @c true if a message waits for transmission and @c
+ * false otherwise.
+ * @return @c SUCCESS if @a tx_con was updated with the requested value,\n
+ * @c FAILURE if an error was detected.
*/
int8_t rpp_can_check_tx_con(rpp_can_hw_obj hw_obj, bool *tx_con);
*
* Data in the given message object is copied to @a pdu. A successful
* call to this function also clears the indication that can be
- * retrieved with rpp_can_check_rx_ind() until the next message is
- * received by that message object.
+ * retrieved with rpp_can_check_rx_ind().
*
- * @param[in] hw_obj Hardware object to be read.
+ * @param[in] hw_obj Hardware object to be read. It is an index to
+ * rpp_can_config.rx_config.
* @param[out] pdu Where to store the read message.
*
- * @return @li @c SUCCESS if the message was succesfully copied out from the message object,
+ * @return @li @c SUCCESS if the message was succesfully copied out
+ * from the message object,
* @li @c -RPP_ENODATA if no data was received,\n
* @li @c -RPP_EINVAL if @a hw_obj is invalid.
*/
* Checks whether a message was received by the message object.
*
* @param[in] hw_obj Hardware object to be checked.
- * @param[out] rx_ind Where to store the RX indication flag.
+ * @param[out] rx_ind Where to store the RX indication flag. Its value
+ * will be @c true if a message was received, @c false otherwise.
*
- * @return SUCCESS if rx_ind was updated with the requested value,\n
- * FAILURE if an error was detected.
+ * @return @c SUCCESS if @a rx_ind was updated with the requested value,\n
+ * @c FAILURE if an error was detected.
*/
int8_t rpp_can_check_rx_ind(rpp_can_hw_obj hw_obj, bool *rx_ind);
projects / pes-rpp / rpp-lib.git / commitdiff