Make the RPP layer thread safe

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

diff --git a/rpp/include/rpp/fr.h b/rpp/include/rpp/fr.h
index 973aea511daa31899ec2cd6e0cdd328840c690c1..afea18ef71a202fd901523c52fc6f2137cc19f56 100644 (file)
--- a/rpp/include/rpp/fr.h
+++ b/rpp/include/rpp/fr.h
@@ -3,7 +3,7 @@
  *
  * @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>
@@ -38,6 +38,8 @@ typedef enum {
 /**
  * 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.
  *
@@ -64,6 +66,9 @@ int8_t rpp_fr_init_driver(const Fr_ConfigType *config_ptr, uint32_t *error);
 /**
  * FlexRay controller initialization.
  *
+ * 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.
  *
@@ -101,6 +106,9 @@ int8_t rpp_fr_init_controller(uint8_t ctrl, uint32_t *error);
 /**
  * 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.
  *
@@ -145,6 +153,8 @@ int8_t rpp_fr_start_communication(uint8_t ctrl, uint32_t *error);
 /**
  * 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
  * function, communication on all configured slots is allowed.
@@ -162,6 +172,8 @@ int8_t rpp_fr_all_slots(uint8_t ctrl);
 /**
  * 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.
  *
@@ -193,6 +205,8 @@ int8_t rpp_fr_halt_communication(uint8_t ctrl);
 /**
  * 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.
  *
@@ -223,6 +237,8 @@ int8_t rpp_fr_abort_communication(uint8_t ctrl);
 /**
  * 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.
  *
@@ -237,6 +253,8 @@ int8_t rpp_fr_send_wup(uint8_t ctrl);
 /**
  * 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().
  *
@@ -255,6 +273,8 @@ int8_t rpp_fr_set_wu_channel(uint8_t ctrl, Fr_ChannelType channel);
 /**
  * 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.
  *
@@ -270,6 +290,8 @@ 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).
  *
@@ -293,6 +315,8 @@ int8_t rpp_fr_transmit_lpdu(uint8_t ctrl, uint16_t lpdu_idx, const uint8_t *lsdu
 /**
  * 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).
  *
@@ -311,6 +335,8 @@ int8_t rpp_fr_cancel_transmit_lpdu(uint8_t ctrl, uint16_t lpdu_idx);
 /**
  * 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).
  *
@@ -341,6 +367,8 @@ int8_t rpp_fr_receive_lpdu(uint8_t ctrl, uint16_t lpdu_idx, uint8_t *lsdu, Fr_Rx
 /**
  * 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).
  *
@@ -367,6 +395,8 @@ int8_t rpp_fr_check_tx_lpdu_status(uint8_t ctrl, uint16_t lpdu_idx, Fr_TxLPduSta
 /**
  * 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).
  *
@@ -397,6 +427,8 @@ int8_t rpp_fr_reconfigure_lpdu(uint8_t ctrl, uint16_t lpdu_idx, uint16_t frame_i
 /**
  * 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).
  *
@@ -415,6 +447,8 @@ int8_t rpp_fr_disable_lpdu(uint8_t ctrl, uint16_t lpdu_idx);
 /**
  * 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.
@@ -430,6 +464,8 @@ 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
@@ -453,6 +489,8 @@ int8_t rpp_fr_get_network_management_vector(uint8_t ctrl, uint8_t *nm_vector);
 /**
  * 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.
  *
@@ -487,6 +525,8 @@ int8_t rpp_fr_get_channel_status(uint8_t ctrl, uint16_t *channel_a_status, uint1
 /**
  * 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.
  *
@@ -503,6 +543,8 @@ int8_t rpp_fr_get_clock_correction(uint8_t ctrl, int16_t *rate_correction, int32
 /**
  * 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.
@@ -533,6 +575,8 @@ int8_t rpp_fr_get_sync_frame_list(uint8_t ctrl, uint8_t list_size, uint16_t *cha
 /**
  * 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.
@@ -552,6 +596,8 @@ int8_t rpp_fr_get_wakeup_rx_status(uint8_t ctrl, uint8_t *status);
 /**
  * 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
@@ -577,6 +623,8 @@ int8_t rpp_fr_set_timer(uint8_t ctrl, uint8_t timer_idx, uint8_t cycle_set, uint
 /**
  * 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.
  *
  * The FlexRay controller has two absolute timers. Each of them can be
@@ -601,6 +649,8 @@ int8_t rpp_fr_cancel_timer(uint8_t ctrl, uint8_t timer_idx);
 /**
  * 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
@@ -623,6 +673,8 @@ 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
@@ -646,6 +698,8 @@ int8_t rpp_fr_get_timer_irq_status(uint8_t ctrl, uint8_t timer_idx, boolean_t *i
 /**
  * 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.
@@ -658,6 +712,8 @@ 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.