*
* @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"
-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_state_t;
-
-/**
- * Store cluster configuration parameters.
- *
- * This functions provides a mechanism to do the user FlexRay configuration.
- * The function parses the string with parameters and stores them into an
- * internal structure.
- * For complete user configuration also rpp_fr_config_node_params and
- * rpp_fr_config_static_buffer have to be called to configure local
- * FlexRay parameters and at least one static buffer.
- *
- * The string with configuration contains hexadecimal numbers separated by spaces.
- * Each number stands for one parameter in this order:
- * gColdStartAttempts
- * gdActionPointOffset
- * gdCASRxLowMax
- * gdDynamicSlotIdlePhase
- * gdMinislot
- * gdMinislotActionPointOffset
- * gdStaticSlot
- * gdTSSTransmitter
- * gdWakeupSymbolRxIdle
- * gdWakeupSymbolRxLow
- * gdWakeupSymbolRxWindow
- * gdWakeupSymbolTxIdle
- * gdWakeupSymbolTxLow
- * gListenNoise
- * gMacroPerCycle
- * gMaxWithoutClockCorrectionFatal
- * gMaxWithoutClockCorrectionPassive
- * gNumberOfMinislots
- * gNumberOfStaticSlots
- * gOffsetCorrectionStart
- * gPayloadLengthStatic
- * gSyncNodeMax
- * gdNIT
- * gdSampleClockPeriod
- * gNetworkManagementVectorLength
- *
- * For example:
- * "0x2 0xF 0x15E0 0xF 0xF 0xC 0x15A 0x8 0xAE4 0x9 0xF 0x4 0x43 0x1 0x4 0x2 0xAE3 0x0 0x56 0xA 0x12 0x12 0x4C 0xB4 0x3C"
- *
- * @param [in] params Address of the string with configuration parameters
- *
- * @return SUCCESS if configuration successful.
- * FAILURE if parameter parsing fails.
- */
-int8_t rpp_fr_config_cluster_params(const char* params);
-
/**
- * Store node configuration parameters.
- *
- * This functions provides a mechanism to do the user FlexRay configuration.
- * The function parses the string with parameters and stores them into an
- * internal structure.
- * For complete user configuration also rpp_fr_config_cluster_params and
- * rpp_fr_config_static_buffer have to be called to configure global
- * FlexRay parameters and at least one static buffer.
- *
- * The string with configuration contains hexadecimal numbers separated by spaces.
- * Each number stands for one parameter in this order:
- * pAllowHaltDueToClock
- * pAllowPassiveToActive
- * pChannels (0 - A, 1 - B, 2 - AB)
- * pClusterDriftDamping
- * pDelayCompensationA
- * pDelayCompensationB
- * pExternOffsetCorrection
- * pExternRateCorrection
- * pKeySlotUsedForStartup
- * pKeySlotUsedForSync
- * pLatestTx
- * pMacroInitialOffsetA
- * pMacroInitialOffsetB
- * pMicroInitialOffsetA
- * pMicroInitialOffsetB
- * pMicroPerCycle
- * pRateCorrectionOut
- * pOffsetCorrectionOut
- * pSamplesPerMicrotick
- * pSingleSlotEnabled
- * pWakeupChannel (0 - A, 1 - B)
- * pWakeupPattern
- * pdAcceptedStartupRange
- * pdListenTimeout
- * pdMaxDrift
- * pDecodingCorrection
- * syncFramePayloadMultiplexEnabled
- * secureBuffers (0 - FR_SB_RECONFIG_ENABLED, 1 - FR_SB_STAT_REC_DISABLED_STAT_TR_DISABLED, 2 - FR_SB_ALL_REC_DISABLED, 3 - FR_SB_ALL_REC_DISABLED_STAT_TR_DISABLED)
- *
- * For example:
- * "0x0 0x0 0x2 0x1 0x3 0x3 0x0 0x0 0x1 0x1 0x10D 0x6 0x6 0x18 0x18 0x36B00 0xCD 0x151 0x0 0x1 0x0 0x2 0x81 0x36DA2 0x151 0x33 0x0 0x0"
- *
- * @param [in] params Address of the string with configuration parameters
- *
- * @return SUCCESS if configuration successful.
- * FAILURE if parameter parsing fails.
+ * Enumeration of states for the FlexRay
*/
-int8_t rpp_fr_config_node_params(const char* params);
-
-/**
- * Add new static buffer configuration into the list of buffers.
- *
- * This functions provides a mechanism to do the user FlexRay configuration.
- * The function parses the string with parameters and stores them into an
- * internal structure.
- * For complete user configuration also rpp_fr_config_cluster_params and
- * rpp_fr_config_node_params have to be called to configure global and local
- * FlexRay parameters.
- * At least one static buffer must be configured as TX. For sync and coldstart nodes
- * the first buffer should be configured as TX.
- *
- * The string with configuration contains hexadecimal numbers or strings separated by spaces.
- * Each number or string stands for one parameter in this order:
- * channel (0 - A, 1 - B, 2 - AB)
- * cycleCounterFiltering
- * isTx
- * maxPayload
- * msgBufferInterrupt
- * payloadPreambleIndicatorTr
- * singleTransmit
- * slotId
- *
- * For example:
- * "0x2 0x0 0x1 0x9 0x1 0x0 0x0 0x1"
- *
- * @param [in] params Address of the string with configuration parameters
- *
- * @return SUCCESS if configuration successful.
- * FAILURE if parameter parsing fails.
- */
-int8_t rpp_fr_config_static_buffer(const char* params);
-
-/**
- * Add new dynamic buffer configuration into the list of buffers.
- *
- * This functions provides a mechanism to do the user FlexRay configuration.
- * The function parses the string with parameters and stores them into an
- * internal structure.
- * For complete user configuration also rpp_fr_config_cluster_params,
- * rpp_fr_config_node_params and rpp_fr_config_static_buffer have to be called
- * to configure global, local FlexRay parameters and at least one static buffer.
- *
- * The string with configuration contains hexadecimal numbers or strings separated by spaces.
- * Each number or string stands for one parameter in this order:
- * channel (0 - A, 1 - B)
- * cycleCounterFiltering
- * isTx
- * maxPayload
- * msgBufferInterrupt
- * singleTransmit
- * slotId
- *
- * For example:
- * "0x0 0x0 0x1 0x9 0x1 0x0 0x1"
- *
- * @param [in] params Address of the string with configuration parameters
- *
- * @return SUCCESS if configuration successful.
- * FAILURE if parameter parsing fails.
- */
-int8_t rpp_fr_config_dynamic_buffer(const char* params);
+typedef enum {
+ 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;
-/**
- * Configures new RX FIFO buffer configuration into the list of buffers.
- *
- * This functions provides a mechanism to do the user FlexRay configuration.
- * The function parses the string with parameters and stores them into an
- * internal structure.
- * For complete user configuration also rpp_fr_config_cluster_params,
- * rpp_fr_config_node_params and rpp_fr_config_static_buffer have to be called
- * to configure global, local FlexRay parameters and at least one static buffer.
- * Only one RX FIFO buffer with specified depth can be configured.
- *
- * The string with configuration contains hexadecimal numbers or strings separated by spaces.
- * Each number or string stands for one parameter in this order:
- * depth
- * channel (0 - A, 1 - B, 2 - AB)
- * cycleCounterFiltering
- * maxPayload
- * rejectNullFrames
- * rejectStaticSegment
- * slotId (zero means no frame will be rejected)
- *
- * For example:
- * "0x5 0x2 0x0 0x40 0x1 0x0 0x0"
- *
- * @param [in] params Address of the string with configuration parameters
- *
- * @return SUCCESS if configuration successful.
- * FAILURE if parameter parsing fails.
- */
-int8_t rpp_fr_config_fifo_buffer(const char* params);
+#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 */
-/**
- * FR module initialization.
- *
- * Call this method before using this module.
- *
- * @return SUCCESS if initialization successful.\n
- * FAILURE if module already initialized.
- */
-int8_t rpp_fr_init();
+/* AUTOSAR-like API */
/**
* FlexRay driver initialization.
*
- * This method should be called after rpp_fr_init and before any
- * other function from this module, except rpp_fr_config functions.
+ * This function is not thread safe. Do not call it from multiple threads.
*
- * The functions copies configuration data into drivers internal
+ * This method should be called before any other function from this
+ * 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 user configuration. Then the argument
- * for this function has to be NULL and configuration functions have to be called before
- * this function.
- *
- * After successful driver initialization, the FlexRay is ready for:
- * 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 default structure,
- * filled by rpp_fr_config functions, is used.
+ * 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] 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.
*
- * After successful controller initialization, the FlexRay is ready for:
- * rpp_fr_init_controller
- * rpp_fr_get_poc_status
- * rpp_fr_get_wakeup_rx_status
- * rpp_fr_get_timer_irq_status
- * rpp_fr_start_communication
- * rpp_fr_send_wup
- * rpp_fr_set_wu_channel
- * rpp_fr_get_global_time
- * rpp_fr_get_network_management_vector
- * rpp_fr_get_channel_status
+ * After successful controller initialization, the FlexRay driver is ready for calling:
+ * - rpp_fr_get_poc_status()
+ * - rpp_fr_get_wakeup_rx_status()
+ * - rpp_fr_get_timer_irq_status()
+ * - rpp_fr_start_communication()
+ * - rpp_fr_send_wup()
+ * - rpp_fr_set_wu_channel()
+ * - 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 successful.
+ * @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 attempt
- * to sending or receiving messages
+ * This method should be called after rpp_fr_init_controller() and
+ * before any attempt to send or receive messages.
*
- * For coldstarter the function tries to listen and join an existing network.
- * If it fails, it tries to initiate the new one.
+ * 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.
*
* After successful communication start, the FlexRay is ready for:
- * rpp_fr_init_controller
- * rpp_fr_get_poc_status
- * rpp_fr_get_wakeup_rx_status
- * rpp_fr_get_timer_irq_status
- * rpp_fr_start_communication
- * rpp_fr_send_wup
- * rpp_fr_set_wu_channel
- * rpp_fr_get_global_time
- * rpp_fr_get_network_management_vector
- * rpp_fr_get_channel_status
- * rpp_fr_all_slots
- * rpp_fr_halt_communication
- * rpp_fr_abort_communication
- * rpp_fr_transmit_lpdu
- * rpp_fr_cancel_transmit_lpdu
- * rpp_fr_receive_lpdu
- * rpp_fr_check_tx_lpdu_status
- * rpp_fr_disable_lpdu
- * rpp_fr_get_clock_correction
- * rpp_fr_get_sync_frame_list
- * rpp_fr_set_timer
- * rpp_fr_cancel_timer
+ * - rpp_fr_get_poc_status()
+ * - rpp_fr_get_wakeup_rx_status()
+ * - rpp_fr_get_timer_irq_status()
+ * - rpp_fr_set_wu_channel()
+ * - rpp_fr_get_global_time()
+ * - rpp_fr_get_network_management_vector()
+ * - rpp_fr_get_channel_status()
+ * - rpp_fr_all_slots()
+ * - rpp_fr_halt_communication()
+ * - rpp_fr_abort_communication()
+ * - rpp_fr_transmit_lpdu()
+ * - rpp_fr_cancel_transmit_lpdu()
+ * - rpp_fr_receive_lpdu()
+ * - rpp_fr_check_tx_lpdu_status()
+ * - rpp_fr_disable_lpdu()
+ * - rpp_fr_get_clock_correction()
+ * - 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 FlexRay node can be configured to communicate only on key frames
- * after the startup. Using this function the communication on all
- * configured slots can be allowed.
+ * The function is thread safe, unless compiled with -DRPP_THREADSAFE=0.
*
- * The function should be called only when the communication is running.
+ * The FlexRay node can be configured to communicate only on key
+ * frames after the startup. If this is the case, after calling this
+ * function, communication on all configured slots is allowed.
+ *
+ * The function should be called only after rpp_fr_start_communication() has been called.
*
* @param [in] ctrl Not used, set always to zero.
*
int8_t rpp_fr_all_slots(uint8_t ctrl);
/**
- * FlexRay stop communication after the end of the cycle.
+ * Stop communication after the end of the communication cycle.
*
- * The function should be called only when the communication is running.
+ * 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.
+ *
+ * After the communication is stopped, only those functions are allowed to be called:
+ * - rpp_fr_set_wu_channel()
+ * - rpp_fr_get_global_time()
+ * - rpp_fr_get_network_management_vector()
+ * - rpp_fr_get_channel_status()
+ * - rpp_fr_get_clock_correction()
+ * - 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)
*
- * After the communication is stopped, only those functions are allowed:
- * rpp_fr_get_global_time
- * rpp_fr_get_network_management_vector
- * rpp_fr_get_channel_status
- * rpp_fr_get_clock_correction
- * rpp_fr_get_sync_frame_list
- * rpp_fr_get_wakeup_rx_status
- * rpp_fr_get_poc_status
*
- * To establish new communication, reset the device.
-
* @param [in] ctrl Not used, set always to zero.
*
* @return SUCCESS if command passed successfully.
- * FAILURE if command rejectred.
+ * FAILURE if command rejected.
*
*/
int8_t rpp_fr_halt_communication(uint8_t ctrl);
/**
- * FlexRay stop communication immediately.
+ * Stop communication immediately.
*
- * The function should be called only when the communication is running.
+ * The function is thread safe, unless compiled with -DRPP_THREADSAFE=0.
*
- * After the communication is stopped, only those functions are allowed:
- * rpp_fr_get_global_time
- * rpp_fr_get_network_management_vector
- * rpp_fr_get_channel_status
- * rpp_fr_get_clock_correction
- * rpp_fr_get_sync_frame_list
- * rpp_fr_get_wakeup_rx_status
- * rpp_fr_get_poc_status
+ * The function should be called only after
+ * rpp_fr_start_communication() has been called.
*
- * To establish new communication, reset the device.
+ * After the communication is stopped, only those functions are allowed to be called:
+ * - rpp_fr_set_wu_channel()
+ * - rpp_fr_get_global_time()
+ * - rpp_fr_get_network_management_vector()
+ * - rpp_fr_get_channel_status()
+ * - rpp_fr_get_clock_correction()
+ * - 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)
*
* @param [in] ctrl Not used, set always to zero.
*
* @return SUCCESS if command passed successfully.
- * FAILURE if command rejectred.
+ * FAILURE if command rejected.
*
*/
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.
* @param [in] ctrl Not used, set always to zero.
*
* @return SUCCESS if command passed successfully.
- * FAILURE if command rejectred.
+ * FAILURE if command rejected.
*
*/
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 rejectred.
+ * FAILURE if command rejected.
*
*/
int8_t rpp_fr_set_wu_channel(uint8_t ctrl, Fr_ChannelType channel);
/**
* Get FlexRay POC state
*
- * The function can be called any time after driver is initialized.
+ * 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
- * (Fr_StartCommunication was called).
+ * (rpp_fr_start_communication() was called).
*
- * If the buffer assigned to the frame is in continuous mode, this
- * functions starts periodical message sending. The transmission can
- * be stopped by rpp_fr_cancel_transmit_lpdu.
- * If the buffer assigned to the frame is in single-shot mode, the
- * message is sent only once.
+ * If the buffer assigned to the frame is configured for continuous
+ * mode, this functions starts sending the message periodically. The
+ * transmission can be stopped by rpp_fr_cancel_transmit_lpdu(). If
+ * the buffer assigned to the frame is configured for single-shot
+ * mode, the message is sent only once.
*
* @param [in] ctrl Not used, set always to zero.
* @param [in] lpdu_idx Index of the frame, where the message will be sent.
* 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
- * (Fr_StartCommunication was called).
+ * (rpp_fr_start_communication() was called).
*
- * This is one way to stop transmission for buffers configured
- * in continuous mode.
+ * This is one way to stop transmission for buffers configured for
+ * continuous mode. The other way is to use rpp_fr_disable_lpdu().
*
* @param [in] ctrl Not used, set always to zero.
* @param [in] lpdu_idx Index of the frame, where the message transmission will be stopped.
int8_t rpp_fr_cancel_transmit_lpdu(uint8_t ctrl, uint16_t lpdu_idx);
/**
- * Receive a message from the bus in the specified frame
+ * 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
- * (Fr_StartCommunication was called).
+ * (rpp_fr_start_communication() was called).
+ *
+ * If a new message was received in a buffer configured for the static
+ * and dynamic segment or FIFO, this function can retrieve it.
*
- * If new message was received in static or dynamic buffer into some RX buffer,
- * 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
- * (Fr_StartCommunication was called).
+ * (rpp_fr_start_communication() was called).
+ *
+ * The status says whether a transmission request (TXR) is pending or
+ * not.
*
- * If buffer configured in single-shot mode, the transmission request (TXR)
- * is pending until the message is send.
- * For buffers configured in continuous mode, the transmission request is
- * always pending.
+ * If the buffer is configured for single-shot mode, the (TXR) is
+ * pending until the message is sent. For buffers configured in
+ * continuous mode, the transmission request is always pending.
*
- * The TXR pending or not pending is the status of the buffer.
*
* @param [in] ctrl Not used, set always to zero.
* @param [in] lpdu_idx Index of the frame to which the buffer is assigned.
*
* @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);
+
+
+/**
+ * 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_check_tx_lpdu_status(uint8_t ctrl, uint16_t lpdu_idx, Fr_TxLPduStatusType* lpdu_status);
+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 FlexRay buffer
+ * 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
- * (Fr_StartCommunication was called).
+ * (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 can be called any time after controller is initialized.
+ * 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.
* @param [out] cycle Adress where the number of actual cycle will be stored.
* 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 can be called any time after controller is initialized.
+ * 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 vectors received from all nodes.
+ * The FlexRay controller updates the vector at the end of every cycle
+ * by doing bit-wise OR on every network management (NM) vectors
+ * received from all nodes.
*
- * The NM vector can be sent to a frame by a buffer with payloadPreambleIndicatorTr
- * set. Those frames are automatically processed by the controller. But sending the
- * vector has to be done manually by copying the NM vector data (obtainable by
- * this function) into the TX buffer (using rpp_fr_transmit_lpdu function).
+ * 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 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 can be called any time after controller is initialized.
+ * The function is thread safe, unless compiled with -DRPP_THREADSAFE=0.
*
- * The output of the function is bitcoded in this way:
- * Bit 0: Channel A/B aggregated channel status vSS!ValidFrame
- * Bit 1: Channel A/B aggregated channel status vSS!SyntaxError
- * Bit 2: Channel A/B aggregated channel status vSS!ContentError
- * Bit 3: Channel A/B aggregated channel status additional communication
- * Bit 4: Channel A/B aggregated channel status vSS!Bviolation
- * Bit 5: Channel A/B aggregated channel status vSS!TxConflict
- * Bit 6: Not used (0)
- * Bit 7: Not used (0)
- * Bit 8: Channel A/B symbol window status data vSS!ValidMTS
- * Bit 9: Channel A/B symbol window status data vSS!SyntaxError
- * Bit 10: Channel A/B symbol window status data vSS!Bviolation
- * Bit 11: Channel A/B symbol window status data vSS!TxConflict
- * Bit 12: Channel A/B NIT status data vSS!SyntaxError
- * Bit 13: Channel A/B NIT status data vSS!Bviolation
- * Bit 14: Not used (0)
- * Bit 15: Not used (0)
+ * The function can be called any time after the controller is
+ * initialized.
*
+ * The output of the function is bitcoded in this way:
+ * - Bit 0: Channel A/B aggregated channel status vSS!ValidFrame
+ * - Bit 1: Channel A/B aggregated channel status vSS!SyntaxError
+ * - Bit 2: Channel A/B aggregated channel status vSS!ContentError
+ * - Bit 3: Channel A/B aggregated channel status additional communication
+ * - Bit 4: Channel A/B aggregated channel status vSS!Bviolation
+ * - Bit 5: Channel A/B aggregated channel status vSS!TxConflict
+ * - Bit 6: Not used (0)
+ * - Bit 7: Not used (0)
+ * - Bit 8: Channel A/B symbol window status data vSS!ValidMTS
+ * - Bit 9: Channel A/B symbol window status data vSS!SyntaxError
+ * - Bit 10: Channel A/B symbol window status data vSS!Bviolation
+ * - Bit 11: Channel A/B symbol window status data vSS!TxConflict
+ * - Bit 12: Channel A/B NIT status data vSS!SyntaxError
+ * - Bit 13: Channel A/B NIT status data vSS!Bviolation
+ * - Bit 14: Not used (0)
+ * - Bit 15: Not used (0)
*
* @param [in] ctrl Not used, set always to zero.
* @param [out] channel_a_status Address where the bitcoded status of the channel A will be stored.
* 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 can be called while communication is running or was stopped.
+ * The function is thread safe, unless compiled with -DRPP_THREADSAFE=0.
+ *
+ * The function can be called while the communication is running or
+ * was stopped.
*
* @param [in] ctrl Not used, set always to zero.
* @param [out] rate_correction Address where the rate will be stored.
* 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);
/**
- * Get clock 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.
- * @param [out] rate_correction Address where the rate will be stored.
- * @param [out] offset_correction Address where the offset will be stored.
+ * @param [in] list_size Size of the arrays passed via parameters:
+ * @param [out] channel_a_even_list Address the list of syncframes on channel A within the
+ * even communication cycle is written to. The exact
+ * number of elements written to the list is limited by
+ * parameter Fr_ListSize.
+ * Unused list elements are filled with the value '0' to indicate that no more syncframe has been seen.
+ * @param [out] channel_b_even_list Address the list of syncframes on channel B within the
+ * even communication cycle is written to. The exact
+ * number of elements written to the list is limited by
+ * parameter Fr_ListSize.
+ * @param [out] channel_a_odd_list Address the list of syncframes on channel A within the
+ * odd communication cycle is written to. The exact number
+ * of elements written to the list is limited by parameter
+ * Fr_ListSize.
+ * Unused list elements are filled with the value '0' to indicate that no more syncframe has been seen.
+ * @param [out] channel_b_odd_list Address the list of syncframes on channel B within the
*
* @return SUCCESS if everything is OK.
* 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_bodd_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 Wake Up Pattern was received on some channel, the flag is set in status address.
+ * If the Wake Up Pattern was received on some channel, the flag is set in status address.
* Bit 0: Wakeup received on channel A indicator
* Bit 1: Wakeup received on channel B indicator
* Bit 2-7: Unused
* 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 and offset.
+ * configured cycle set and offset.
*
- * Timer interrupt request can be detected by rpp_fr_get_timer_irq_status.
- * Timer interrupt request can be cleared by rpp_fr_clear_timer_irq
- * Timer can be canceled by rpp_fr_cancel_timer.
+ * Timer interrupt request can be detected by
+ * rpp_fr_get_timer_irq_status(). The timer interrupt request can be
+ * cleared by rpp_fr_clear_timer_irq(). The timer can be canceled by
+ * rpp_fr_cancel_timer().
*
* @param [in] ctrl Not used, set always to zero.
* @param [in] timer_idx Index of the timer (0,1).
- * @param [in] cycle_threshold Number of the cycle.
+ * @param [in] cycle_set Determines the set of cycles that trigger the interrupt (see Table 23-6 in TMS570 datasheet (SPNU499))
* @param [in] offset_threshold Offset in the cycle in mactroticks.
*
* @return SUCCESS if everything is OK.
* FAILURE if something failed.
*
*/
-int8_t rpp_fr_set_timer(uint8_t ctrl, uint8_t timer_idx, uint8_t cycle_threshold, uint16_t offset_threshold);
+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.
*
* configured cycle and offset. This function stops the timer and clears
* the interrupt request.
*
- * Timer interrupt request can be detected by rpp_fr_get_timer_irq_status.
- * Timer interrupt request can be cleared by rpp_fr_clear_timer_irq
- * Timer can be started by rpp_fr_set_timer.
+ * Timer interrupt request can be detected by
+ * rpp_fr_get_timer_irq_status(). Timer interrupt request can be
+ * cleared by rpp_fr_clear_timer_irq() Timer can be started by
+ * rpp_fr_set_timer().
*
* @param [in] ctrl Not used, set always to zero.
* @param [in] timer_idx Index of the timer (0,1).
int8_t rpp_fr_cancel_timer(uint8_t ctrl, uint8_t timer_idx);
/**
- * Clear IRQ flag of the absolute timer
+ * 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.
*
* configured to request the interrupt, when the global time reaches
* configured cycle and offset. This function clears the IRQ flag.
*
- * Timer interrupt request can be detected by rpp_fr_get_timer_irq_status.
- * Timer can be started by rpp_fr_set_timer.
- * Timer can be canceled by rpp_fr_cancel_timer.
+ * Timer interrupt request can be detected by rpp_fr_get_timer_irq_status().
+ * The timer can be started by rpp_fr_set_timer().
+ * The timer can be canceled by rpp_fr_cancel_timer().
*
* @param [in] ctrl Not used, set always to zero.
* @param [in] timer_idx Index of the timer (0,1).
/**
* 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
* configured to request the interrupt, when the global time reaches
* configured cycle and offset. Using this function the IRQ can be detected.
*
- * Timer interrupt request can be cleared by rpp_fr_clear_timer_irq
- * Timer can be started by rpp_fr_set_timer.
- * Timer can be canceled by rpp_fr_cancel_timer.
+ * Timer interrupt request can be cleared by rpp_fr_clear_timer_irq().
+ * The timer can be started by rpp_fr_set_timer().
+ * The timer can be canceled by rpp_fr_cancel_timer().
*
* @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