*
* @file fr.h
*
- * @copyright Copyright (C) 2013 Czech Technical University in Prague
+ * @copyright Copyright (C) 2013, 2015 Czech Technical University in Prague
*
* @author Carlos Jenkins <carlos@jenkins.co.cr>
* @author Michal Horn <hornmich@fel.cvut.cz>
#include "drv/Fr_GeneralTypes.h"
#include "drv/fr_tms570.h"
+/**
+ * Enumeration of states for the FlexRay
+ */
typedef enum {
- RPP_FR_UNKNOWN,
- RPP_FR_CONFIGURED,
- RPP_FR_NOT_INITIALIZED,
- RPP_FR_DRV_INITIALIZED,
- RPP_FR_CTR_INITIALIZED,
- RPP_FR_RUNNING,
- RPP_FR_HALTED,
- RPP_FR_ABORTED
+ RPP_FR_UNKNOWN, /**< FlexRay is in unknown state, this should not happen */
+ RPP_FR_NOT_INITIALIZED, /**< FlexRay driver was not yet configured and initialized, communication is not running. This is the default state after reset */
+ RPP_FR_DRV_INITIALIZED, /**< FlexRay driver was initialized, communication is not running, Driver is ready for controller initialization */
+ RPP_FR_CTR_INITIALIZED, /**< FlexRay controller was initlized, communicatin is not running, but can be started */
+ RPP_FR_RUNNING, /**< Communication is running */
+ RPP_FR_HALTED, /**< Communication was halted, controller is ready for reconfiguration and restart of the communication */
+ RPP_FR_ABORTED /**< Communication was aborted, controller is ready for reconfiguration and restart of the communication */
} rpp_fr_state_t;
-#define RPP_FR_MAX_STATIC_BUF_CNT 32
-#define RPP_FR_MAX_DYNAMIC_BUF_CNT 32
-#define RPP_FR_MAX_FIFO_BUF_DEPTH 32
+#define RPP_FR_MAX_STATIC_BUF_CNT 128 /**< Maximum number of the buffers for static segment of the communication cycle */
+#define RPP_FR_MAX_DYNAMIC_BUF_CNT 128 /**< Maximum number of the buffers for dynamic segment of the communication cycle */
+#define RPP_FR_MAX_FIFO_BUF_DEPTH 128 /**< Maximal depth of the RX FIFO buffer */
/* AUTOSAR-like API */
/**
* FlexRay driver initialization.
*
+ * This function is not thread safe. Do not call it from multiple threads.
+ *
* This method should be called before any other function from this
- * module, except rpp_fr_config_* functions.
+ * module.
*
* The function copies configuration data into drivers internal
* structures and initializes the driver.
*
- * There are two ways how to configure FlexRay.
- * 1) Passing address of the config structure as an argument from the application.
- * 2) Using rpp_fr_config_* functions to create configuration at run-time. Then the argument
- * for this function has to be NULL and configuration functions have to be called before
- * this function.
- *
* After a successful driver initialization, the driver is ready for calling:
* - rpp_fr_init_controller()
* - rpp_fr_get_poc_status()
* - rpp_fr_get_wakeup_rx_status()
* - rpp_fr_get_timer_irq_status()
*
- * @param [in] Fr_ConfigPtr Address of the structure with all FlexRay
- * configuration parameters. If it is NULL, then the default structure,
- * filled by rpp_fr_config functions, is used.
+ * @param [in] config_ptr Address of the structure with all FlexRay
+ * configuration parameters.
* @param [out] error Address where error flags will be stored. The flags
- * definitions can be found in fr_tms570h, with ERR_PARAM prefix.
+ * definitions can be found in fr_tms570.h, with ERR_PARAM prefix.
*
* @return SUCCESS if initialization successful.
* FAILURE if module already initialized.
*
*/
-int8_t rpp_fr_init_driver(const Fr_ConfigType* config_ptr, uint32_t* error);
+int8_t rpp_fr_init_driver(const Fr_ConfigType *config_ptr, uint32_t *error);
/**
* FlexRay controller initialization.
*
- * This method should be called after rpp_fr_init_driver() and before any
- * other function from this module.
+ * The function is thread safe, unless compiled with
+ * -DRPP_THREADSAFE=0.
+ *
+ * This method should be called after rpp_fr_init_driver(), rpp_fr_halt_communication() or
+ * rpp_fr_abort_communication() and before any other function from this module.
+ *
+ * Use this sequence to restart communication after halt or abort functions were called:
+ * - rpp_fr_init_controller()
+ * - rpp_fr_start_communication()
+ * - rpp_fr_all_slots() (optionally)
*
* The functions checks configuration parameters and configures FlexRay
* controller registers.
* - rpp_fr_get_global_time()
* - rpp_fr_get_network_management_vector()
* - rpp_fr_get_channel_status()
+ * - rpp_fr_reconfigure_lpdu()
*
* @param [in] ctrl Not used, set always to zero.
* @param [out] error Address where error flags will be stored. The flags
- * definitions can be found in fr_tms570h, with ERR_PARAM and FR_INIT_ERR
+ * definitions can be found in fr_tms570.h, with ERR_PARAM and FR_INIT_ERR
* prefix.
*
* @return SUCCESS if initialization if successful.
* FAILURE if module already initialized.
- *
*/
-int8_t rpp_fr_init_controller(uint8_t ctrl, uint32_t* error);
+
+int8_t rpp_fr_init_controller(uint8_t ctrl, uint32_t *error);
/**
- * FlexRay start communication
+ * Start communication
+ *
+ * The function is thread safe, unless compiled with
+ * -DRPP_THREADSAFE=0.
*
* This method should be called after rpp_fr_init_controller() and
* before any attempt to send or receive messages.
*
- * For coldstarter node the function tries to listen and join an
+ * For coldstarter node the function listens and tries to join an
* existing network. If it fails, it tries to initiate the new one.
* For regular node it only listens on the bus and tries to join to
* some existing network.
* - rpp_fr_get_sync_frame_list()
* - rpp_fr_set_timer()
* - rpp_fr_cancel_timer()
+ * - rpp_fr_reconfigure_lpdu()
+ *
*
* @param [in] ctrl Not used, set always to zero.
* @param [out] error Address where error flags will be stored. The flags
* FAILURE if module already initialized.
*
*/
-int8_t rpp_fr_start_communication(uint8_t ctrl, uint32_t* error);
+int8_t rpp_fr_start_communication(uint8_t ctrl, uint32_t *error);
/**
- * FlexRay allow communication on all slots
+ * Allow communication on all slots
+ *
+ * The function is thread safe, unless compiled with -DRPP_THREADSAFE=0.
*
* The FlexRay node can be configured to communicate only on key
* frames after the startup. If this is the case, after calling this
int8_t rpp_fr_all_slots(uint8_t ctrl);
/**
- * FlexRay stop communication after the end of the communication cycle.
+ * Stop communication after the end of the communication cycle.
+ *
+ * The function is thread safe, unless compiled with -DRPP_THREADSAFE=0.
*
* The function should be called only after
* rpp_fr_start_communication() has been called.
* - rpp_fr_get_sync_frame_list()
* - rpp_fr_get_wakeup_rx_status()
* - rpp_fr_get_poc_status()
+ * - rpp_fr_init_controller()
+ *
+ * To restart the communication, the following sequence has to be called:
+ * - rpp_fr_init_controller()
+ * - rpp_fr_start_communication()
+ * - rpp_fr_all_slots() (optionally)
+ *
*
- * To establish new communication, it is necessary to reset the
- * device.
* @param [in] ctrl Not used, set always to zero.
*
* @return SUCCESS if command passed successfully.
int8_t rpp_fr_halt_communication(uint8_t ctrl);
/**
- * FlexRay stop communication immediately.
+ * Stop communication immediately.
+ *
+ * The function is thread safe, unless compiled with -DRPP_THREADSAFE=0.
*
* The function should be called only after
* rpp_fr_start_communication() has been called.
* - rpp_fr_get_sync_frame_list()
* - rpp_fr_get_wakeup_rx_status()
* - rpp_fr_get_poc_status()
+ * - rpp_fr_init_controller()
*
- * To establish new communication, it is necessary to reset the
- * device.
+ * To restart the communication, the following sequence has to be called:
+ * - rpp_fr_init_controller()
+ * - rpp_fr_start_communication()
+ * - rpp_fr_all_slots() (optionally)
*
* @param [in] ctrl Not used, set always to zero.
*
int8_t rpp_fr_abort_communication(uint8_t ctrl);
/**
- * FlexRay send wakeup pattern.
+ * Send wakeup pattern.
+ *
+ * The function is thread safe, unless compiled with -DRPP_THREADSAFE=0.
*
* The function should be called after FlexRay controller is initialized
* and before the communication start.
int8_t rpp_fr_send_wup(uint8_t ctrl);
/**
- * FlexRay set channel for wakeup pattern sending.
+ * Set channel for wakeup pattern sending.
+ *
+ * The function is thread safe, unless compiled with -DRPP_THREADSAFE=0.
*
* This allows to change the configuration passed to the
* rpp_fr_init_driver().
*
* The function should be called after FlexRay controller is initialized
- * and before the communication start.
+ * and before the communication started.
*
* @param [in] ctrl Not used, set always to zero.
+ * @param [in] channel Channel selector, where wakeup pattern will be sent
*
* @return SUCCESS if command passed successfully.
* FAILURE if command rejected.
/**
* Get FlexRay POC state
*
+ * The function is thread safe, unless compiled with -DRPP_THREADSAFE=0.
+ *
* The function can be called any time after the driver is
* initialized.
*
* @param [in] ctrl Not used, set always to zero.
- * @parap [out] poc_status_ptr Address where status will be stored.
+ * @param [out] poc_status_ptr Address where status will be stored.
*
* @return SUCCESS if status retrieved successfully.
* FAILURE if something failed.
*
*/
-int8_t rpp_fr_get_poc_status(uint8_t ctrl, Fr_POCStatusType* poc_status_ptr);
+int8_t rpp_fr_get_poc_status(uint8_t ctrl, Fr_POCStatusType *poc_status_ptr);
/**
* Send a message on the bus in the specified frame
*
+ * The function is thread safe, unless compiled with -DRPP_THREADSAFE=0.
+ *
* The function can be called any time when communication is running
* (rpp_fr_start_communication() was called).
*
* FAILURE if something failed.
*
*/
-int8_t rpp_fr_transmit_lpdu(uint8_t ctrl, uint16_t lpdu_idx, const uint8_t* lsdu, uint8_t lsdu_length);
+int8_t rpp_fr_transmit_lpdu(uint8_t ctrl, uint16_t lpdu_idx, const uint8_t *lsdu, uint8_t lsdu_length);
/**
* Cancel a transmission of the message.
*
+ * The function is thread safe, unless compiled with -DRPP_THREADSAFE=0.
+ *
* The function can be called any time when communication is running
* (rpp_fr_start_communication() was called).
*
/**
* Receive a message from the bus from the specified frame.
*
+ * The function is thread safe, unless compiled with -DRPP_THREADSAFE=0.
+ *
* The function can be called any time when communication is running
* (rpp_fr_start_communication() was called).
*
* If a new message was received in a buffer configured for the static
- * or dynamic segment, this function can retrieve it.
+ * and dynamic segment or FIFO, this function can retrieve it.
+ *
+ * The buffers with lower index (specified in configuration) have higher
+ * priority in retrieving process. This means for example if some buffer is
+ * configured to accept messages from slot 2 on channel A and another buffer
+ * accepts from slot 2 on channel B, the message from the first buffer
+ * will be retrieved first. If there is a FIFO buffer configured to accept
+ * messages from slot 2 in different cyclesets then other buffers, those
+ * messages accepted by the FIFO will be retrieved at the end of the process.
*
* @param [in] ctrl Not used, set always to zero.
* @param [in] lpdu_idx Index of the frame where message will be received from.
* FAILURE if something failed.
*
*/
-int8_t rpp_fr_receive_lpdu(uint8_t ctrl, uint16_t lpdu_idx, uint8_t* lsdu, Fr_RxLPduStatusType* lpdu_status, uint8_t* lsdu_length);
+int8_t rpp_fr_receive_lpdu(uint8_t ctrl, uint16_t lpdu_idx, uint8_t *lsdu, Fr_RxLPduStatusType *lpdu_status, uint8_t *lsdu_length);
/**
* Check TX buffer status
*
+ * The function is thread safe, unless compiled with -DRPP_THREADSAFE=0.
+ *
* The function can be called any time when communication is running
* (rpp_fr_start_communication() was called).
*
- * The status says whther a transmission request (TXR) is pending or
+ * The status says whether a transmission request (TXR) is pending or
* not.
*
* If the buffer is configured for single-shot mode, the (TXR) is
* @return SUCCESS if everything is OK.
* FAILURE if something failed.
*/
-int8_t rpp_fr_check_tx_lpdu_status(uint8_t ctrl, uint16_t lpdu_idx, Fr_TxLPduStatusType* lpdu_status);
+int8_t rpp_fr_check_tx_lpdu_status(uint8_t ctrl, uint16_t lpdu_idx, Fr_TxLPduStatusType *lpdu_status);
+
+
+/**
+ * Reconfigure buffer
+ *
+ * The function is thread safe, unless compiled with -DRPP_THREADSAFE=0.
+ *
+ * The function can be called any time when after controller was initialized
+ * (rpp_fr_init_controller() was called).
+ *
+ * If the node is configured to allow buffer reconfiguration, some of the buffers
+ * can be reconfigured in runtime. Buffers used for synchronization and buffers
+ * assigned to the RX FIFO can not be reconfigured.
+ *
+ * It is not possible to change the direction (TX/RX) of the buffer or to change
+ * the mode (single-shot/continuous).
+ *
+ * Messages that were planned to be sent or received might not be transmitted or received
+ * if reconfiguration occurs in bad time.
+ *
+ * @param [in] ctrl Not used, set always to zero.
+ * @param [in] lpdu_idx Index of the frame, where reconfigured buffer is communicating.
+ * @param [in] frame_id Frame ID, where the buffer will be communicating after the reconfiguration.
+ * @param [in] channel Channel, where the buffer will be communicating. For dynamic segment it should not be AB.
+ * @param [in] cycle_set Cycle set value for cycle filtering. Can be 1, 2, 4, 8, 16, 32, 64.
+ * @param [in] cycle_offset Cycle offset value for cycle filtering. Must be 0 - cycle_set-1
+ * @param [in] payload Maximum payload for the reconfigured buffer in bytes. Must not be higher than the original payload, defined in half-words.
+ * @param [in] header_crc Not used, set to zero. The CRC is calculated automaticaly inside the function.
+ *
+ * @return SUCCESS if everything is OK.
+ * FAILURE if something failed.
+ */
+int8_t rpp_fr_reconfigure_lpdu(uint8_t ctrl, uint16_t lpdu_idx, uint16_t frame_id, Fr_ChannelType channel, uint8_t cycle_set, uint8_t cycle_offset, uint8_t payload, uint16_t header_crc);
/**
* Disable a FlexRay buffer
*
+ * The function is thread safe, unless compiled with -DRPP_THREADSAFE=0.
+ *
* The function can be called any time when communication is running
* (rpp_fr_start_communication() was called).
*
* This functions resets the configuration of the selected buffer.
- * The disabled buffer is not usable any more.
+ * The disabled buffer is not accessible or reconfigurable any more.
*
* @param [in] ctrl Not used, set always to zero.
* @param [in] lpdu_idx Index of the frame to which the buffer is assigned.
/**
* Get FlexRay global time
*
+ * The function is thread safe, unless compiled with -DRPP_THREADSAFE=0.
+ *
* The function can be called any time after the controller is initialized.
*
* @param [in] ctrl Not used, set always to zero.
* FAILURE if something failed.
*
*/
-int8_t rpp_fr_get_global_time(uint8_t ctrl, uint8_t* cycle, uint16_t* macroticks);
+int8_t rpp_fr_get_global_time(uint8_t ctrl, uint8_t *cycle, uint16_t *macroticks);
/**
* Get Network management vector.
*
+ * The function is thread safe, unless compiled with -DRPP_THREADSAFE=0.
+ *
* The function can be called any time after the controller is initialized.
*
* The FlexRay controller updates the vector at the end of every cycle
- * by doing bit-wise OR on every network managemet (NM) vectors
+ * by doing bit-wise OR on every network management (NM) vectors
* received from all nodes.
*
* The NM vector can be sent in a frame by a buffer with the
* payloadPreambleIndicatorTr parameter set. Those frames are
* automatically processed by all the receiving controllers. But
* sending the vector has to be done manually by copying the NM vector
- * data (obtainable by this function) into the TX buffer (using the
- * rpp_fr_transmit_lpdu() function).
+ * data into the TX buffer (using the rpp_fr_transmit_lpdu() function).
*
* @param [in] ctrl Not used, set always to zero.
* @param [out] nm_vector Address where the vector will be stored. The size of the buffer has to be at least gNetworkManagementVectorLength.
* @return SUCCESS if everything is OK.
* FAILURE if something failed.
*/
-int8_t rpp_fr_get_network_management_vector(uint8_t ctrl, uint8_t* nm_vector);
+int8_t rpp_fr_get_network_management_vector(uint8_t ctrl, uint8_t *nm_vector);
/**
- * Get Channel status.
+ * Get channel status.
+ *
+ * The function is thread safe, unless compiled with -DRPP_THREADSAFE=0.
*
* The function can be called any time after the controller is
* initialized.
* FAILURE if something failed.
*
*/
-int8_t rpp_fr_get_channel_status(uint8_t ctrl, uint16_t* channel_a_status, uint16_t* channel_b_status);
+int8_t rpp_fr_get_channel_status(uint8_t ctrl, uint16_t *channel_a_status, uint16_t *channel_b_status);
/**
* Get clock correction.
*
+ * The function is thread safe, unless compiled with -DRPP_THREADSAFE=0.
+ *
* The function can be called while the communication is running or
* was stopped.
*
* FAILURE if something failed.
*
*/
-int8_t rpp_fr_get_clock_correction(uint8_t ctrl, int16_t* rate_correction, int32_t* offset_correction);
+int8_t rpp_fr_get_clock_correction(uint8_t ctrl, int16_t *rate_correction, int32_t *offset_correction);
/**
* Gets a list of syncframes received or transmitted on channel A and channel B via the even and odd communication cycle.
*
+ * The function is thread safe, unless compiled with -DRPP_THREADSAFE=0.
+ *
* The function can be called while communication is running or was stopped.
*
* @param [in] ctrl Not used, set always to zero.
* FAILURE if something failed.
*
*/
-int8_t rpp_fr_get_sync_frame_list(uint8_t ctrl, uint8_t list_size, uint16_t* channel_a_even_list,
- uint16_t* channel_b_even_list, uint16_t* channel_a_odd_list, uint16_t* channel_b_odd_list);
+int8_t rpp_fr_get_sync_frame_list(uint8_t ctrl, uint8_t list_size, uint16_t *channel_a_even_list,
+ uint16_t *channel_b_even_list, uint16_t *channel_a_odd_list, uint16_t *channel_b_odd_list);
/**
* Get the status of WUP receiving
*
+ * The function is thread safe, unless compiled with -DRPP_THREADSAFE=0.
+ *
* The function can be called any time after controller is initialized.
*
* If the Wake Up Pattern was received on some channel, the flag is set in status address.
* FAILURE if something failed.
*
*/
-int8_t rpp_fr_get_wakeup_rx_status(uint8_t ctrl, uint8_t* status);
+int8_t rpp_fr_get_wakeup_rx_status(uint8_t ctrl, uint8_t *status);
/**
- * Set an absolute timer and start it.
+ * Set the absolute timer and start it.
+ *
+ * The function is thread safe, unless compiled with -DRPP_THREADSAFE=0.
*
* The function can be called any time after communication is running.
+ *
* The FlexRay controller has two absolute timers. Each of them can be
* configured to request the interrupt, when the global time reaches
* configured cycle set and offset.
int8_t rpp_fr_set_timer(uint8_t ctrl, uint8_t timer_idx, uint8_t cycle_set, uint16_t offset_threshold);
/**
- * Stops an absolute timer, clear IRQ.
+ * Stop the absolute timer, clear IRQ.
+ *
+ * The function is thread safe, unless compiled with -DRPP_THREADSAFE=0.
*
* The function can be called any time after communication is running.
*
/**
* Clear the IRQ flag of the absolute timer
*
+ * The function is thread safe, unless compiled with -DRPP_THREADSAFE=0.
+ *
* The function can be called any time after communication is running.
*
* The FlexRay controller has two absolute timers. Each of them can be
/**
* Get IRQ flag of the absolute timer
*
+ * The function is thread safe, unless compiled with -DRPP_THREADSAFE=0.
+ *
* The function can be called any time after communication is running.
*
* The FlexRay controller has two absolute timers. Each of them can be
*
* @param [in] ctrl Not used, set always to zero.
* @param [in] timer_idx Index of the timer (0,1).
+ * @param [out] irq_pending Address, where status of the IRQ flag will be stored.
*
* @return SUCCESS if everything is OK.
* FAILURE if something failed.
*
*/
-int8_t rpp_fr_get_timer_irq_status(uint8_t ctrl, uint8_t timer_idx, boolean_t* irq_pending);
+int8_t rpp_fr_get_timer_irq_status(uint8_t ctrl, uint8_t timer_idx, boolean_t *irq_pending);
/**
* Get information about the driver vendor, module and version.
*
+ * The function is thread safe
+ *
* The function can be called any time.
*
* @param [out] version Address, where the information will be stored.
* @return always SUCCESS
*
*/
-int8_t rpp_fr_get_driver_version(Std_VersionInfoType* version);
+int8_t rpp_fr_get_driver_version(Std_VersionInfoType *version);
/**
* Get configuration parameter value from the internal driver structures.
*
+ * The function is thread safe, unless compiled with -DRPP_THREADSAFE=0.
+ *
* The function can be called any time.
*
* @param [in] ctrl Not used, set always to zero.
* FAILURE if something failed.
*
*/
-int8_t rpp_fr_read_com_ctrl_config(uint8_t ctrl, uint8_t param_idx, uint32_t* param_value);
+int8_t rpp_fr_read_com_ctrl_config(uint8_t ctrl, uint8_t param_idx, uint32_t *param_value);
#endif /* __RPP_FR_H */
projects / pes-rpp / rpp-lib.git / blobdiff