X-Git-Url: http://rtime.felk.cvut.cz/gitweb/pes-rpp/rpp-lib.git/blobdiff_plain/d9115ab7fd6d434ec2b6f0edfd1c851d7bd10c90..5cdc272011e0d887d1297641a7f9bdcc6173b12d:/rpp/include/rpp/fr.h diff --git a/rpp/include/rpp/fr.h b/rpp/include/rpp/fr.h index 56b1dd3..9c6157a 100644 --- a/rpp/include/rpp/fr.h +++ b/rpp/include/rpp/fr.h @@ -3,9 +3,10 @@ * * @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 + * @author Michal Horn */ @@ -15,319 +16,129 @@ #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 @@ -337,16 +148,18 @@ int8_t rpp_fr_init_controller(uint8_t ctrl, uint32_t* error); * 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. * @@ -357,55 +170,74 @@ int8_t rpp_fr_start_communication(uint8_t ctrl, uint32_t* error); 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. @@ -413,21 +245,27 @@ int8_t rpp_fr_abort_communication(uint8_t ctrl); * @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); @@ -435,28 +273,33 @@ 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. @@ -467,16 +310,18 @@ int8_t rpp_fr_get_poc_status(uint8_t ctrl, Fr_POCStatusType* poc_status_ptr); * 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. @@ -488,13 +333,23 @@ int8_t rpp_fr_transmit_lpdu(uint8_t ctrl, uint16_t lpdu_idx, const uint8_t* lsdu 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. @@ -507,20 +362,23 @@ int8_t rpp_fr_cancel_transmit_lpdu(uint8_t ctrl, uint16_t lpdu_idx); * 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. @@ -530,18 +388,52 @@ int8_t rpp_fr_receive_lpdu(uint8_t ctrl, uint16_t lpdu_idx, uint8_t* lsdu, Fr_Rx * * @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. @@ -555,7 +447,9 @@ int8_t rpp_fr_disable_lpdu(uint8_t ctrl, uint16_t lpdu_idx); /** * 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. @@ -565,53 +459,58 @@ int8_t rpp_fr_disable_lpdu(uint8_t ctrl, uint16_t lpdu_idx); * 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. @@ -621,12 +520,15 @@ int8_t rpp_fr_get_network_management_vector(uint8_t ctrl, uint8_t* nm_vector); * 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. @@ -636,29 +538,48 @@ int8_t rpp_fr_get_channel_status(uint8_t ctrl, uint16_t* channel_a_status, uint1 * 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 @@ -670,33 +591,39 @@ int8_t rpp_fr_get_sync_frame_list(uint8_t ctrl, uint8_t list_size, uint16_t* cha * 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. * @@ -705,9 +632,10 @@ int8_t rpp_fr_set_timer(uint8_t ctrl, uint8_t timer_idx, uint8_t cycle_threshold * 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). @@ -719,7 +647,9 @@ int8_t rpp_fr_set_timer(uint8_t ctrl, uint8_t timer_idx, uint8_t cycle_threshold 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. * @@ -727,9 +657,9 @@ int8_t rpp_fr_cancel_timer(uint8_t ctrl, uint8_t timer_idx); * 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). @@ -743,28 +673,33 @@ int8_t rpp_fr_clear_timer_irq(uint8_t ctrl, uint8_t timer_idx); /** * 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. @@ -772,11 +707,13 @@ int8_t rpp_fr_get_timer_irq_status(uint8_t ctrl, uint8_t timer_idx, boolean_t* i * @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. @@ -787,7 +724,6 @@ int8_t rpp_fr_get_driver_version(Std_VersionInfoType* version); * 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 */ -