Make the RPP layer thread safe

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

diff --git a/rpp/include/rpp/din.h b/rpp/include/rpp/din.h
index b2b9fde4fbfb7179485812364c5ad794efdf0139..7c6a81bcb5c51992a10c8f09d9e9b8ad39bfec19 100644 (file)
--- a/rpp/include/rpp/din.h
+++ b/rpp/include/rpp/din.h
@@ -17,6 +17,8 @@
  *
  * Call this method before using this module.
  *
+ * This function is not thread safe. Do not call it from multiple threads.
+ *
  * @return SUCCESS if initialization successful.\n
  *         FAILURE if module already initialized.
  */
@@ -27,12 +29,12 @@ int8_t rpp_din_init();
  * Configure voltage reference levels for digital inputs using variable
  * reference threshold.
  *
- * @todo Implement rpp_din_ref().
+ * The function is thread safe, unless compiled with -DRPP_THREADSAFE=0
  *
  * @param[in] refA      [0-4095] value to set (DAC is 12bits) the reference
- *                      voltage A (pins 13-16).
+ *                      voltage A (pins 12-15).
  * @param[in] refB      [0-4095] value to set (DAC is 12bits) the reference
- *                      voltage B (pins 9-12).
+ *                      voltage B (pins 8-11).
  *
  * @return SUCCESS if successful.\n
  *         -1 if pin millivolts is out of range.
@@ -45,11 +47,13 @@ int8_t rpp_din_ref(uint16_t refA, uint16_t refB);
  *
  * Call rpp_din_update() to commit configuration changes to the hardware.
  *
- * @param[in] pin       The pin number to setup [1-16].
- * @param[in] pull_type TRUE to setup pin as pull-up (a switch-to-ground device
+ * The function is thread safe, unless compiled with -DRPP_THREADSAFE=0
+ *
+ * @param[in] pin       The pin number to setup [0-15].
+ * @param[in] pull_up   TRUE to setup pin as pull-up (a switch-to-ground device
  *                      is connected) or FALSE to setup as pull-down
  *                      (switch-to-battery).
- *                      Note that pins [9-16] are pull-down only.
+ *                      Note that pins [8-15] are pull-down only.
  * @param[in] active    TRUE to setup pin as active or FALSE to set it as
  *                      tri-stated.
  * @param[in] can_wake  TRUE is given pin can wake module from sleep state and
@@ -58,30 +62,46 @@ int8_t rpp_din_ref(uint16_t refA, uint16_t refB);
  * @return SUCCESS if successful.\n
  *         -1 if pin number is out of range.\n
  *         -2 if pull_type is requested for pins without this feature.
+ *         -RPP_EBUSY if pin cannot be used as DIN (e.g. because it is used for IRC)
  */
-int8_t rpp_din_setup(uint8_t pin, boolean_t pull_type,
-                      boolean_t active, boolean_t can_wake);
+int8_t rpp_din_setup(uint8_t pin, boolean_t pull_up,
+                                        boolean_t active, boolean_t can_wake);
 
 
 /**
- * Get the current cached value of the given pin.
+ * Get the current cached value of the switch state on the given pin.
  *
  * Call rpp_din_update() to update cached values.
  *
- * @param[in] pin       The pin number to read [1-16].
- * @param[in] var_thr   TRUE to read from variable threshold uncached high speed
- *                      channel. See rpp_din_ref().\n
- *                      Note that only inputs [9-16] can use this option.\n
- *                      Inputs [9-12] use variable threshold B and [13-16] use
- *                      variable threshold A.\n
- *                      FALSE to read from SPI cached value. All pins can use
- *                      this option.
+ * The function is thread safe, unless compiled with -DRPP_THREADSAFE=0
  *
- * @return HIGH or LOW if successful.\n
+ * @param[in] pin       The pin number to read [0-15].
+ *
+ * @return RPP_CLOSED or RPP_OPEN if successful.\n
  *         -1 if pin number is out of range.\n
  *         -2 if var_thr is requested for inputs without this feature.
+ *         -RPP_EBUSY if pin cannot be used as DIN (e.g. because it is used for IRC)
  */
-int8_t rpp_din_get(uint8_t pin, boolean_t var_thr);
+int8_t rpp_din_get(uint8_t pin);
+
+
+/**
+ * Get uncached logical value of the given pin read via comparator with programmable threshold.
+ *
+ * Inputs [8-11] use programmable threshold B and [12-15] use
+ * programmable threshold A.\n
+ *
+ * The function is thread safe, unless compiled with -DRPP_THREADSAFE=0
+ *
+ * @see rpp_din_ref().
+ *
+ * @param[in] pin       The pin number to read [8-15].
+ *
+ * @return HIGH or LOW if successful.\n
+ *         -1 if pin number is out of range.\n
+ *         -RPP_EBUSY if pin cannot be used as DIN (e.g. because it is used for IRC)
+ */
+int8_t rpp_din_get_tr(uint8_t pin);
 
 
 /**
@@ -89,10 +109,13 @@ int8_t rpp_din_get(uint8_t pin, boolean_t var_thr);
  *
  * Call rpp_din_update() to update cached values.
  *
- * @param[in] pin       The pin number to read [1-16].
+ * The function is thread safe, unless compiled with -DRPP_THREADSAFE=0
+ *
+ * @param[in] pin       The pin number to read [0-15].
  *
  * @return HIGH or LOW if successful.\n
  *         -1 if pin number is out of range.
+ *         -RPP_EBUSY if pin cannot be used as DIN (e.g. because it is used for IRC)
  */
 int8_t rpp_din_diag(uint8_t pin);
 
@@ -101,6 +124,8 @@ int8_t rpp_din_diag(uint8_t pin);
  * Read and update cached values and diagnostic values of all pins. Also commit
  * configuration changes.
  *
+ * The function is thread safe, unless compiled with -DRPP_THREADSAFE=0
+ *
  * @return SUCCESS when transaction was successful.\n
  *         FAILURE if transaction could not be confirmed.
  */