Make the RPP layer thread safe

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

diff --git a/rpp/include/rpp/mout.h b/rpp/include/rpp/mout.h
index 29133928a98dc2486f7f9ace465f824346820f4d..1250dd82fd7c9605c6ed5c565fbc6cee3c8173bf 100644 (file)
--- a/rpp/include/rpp/mout.h
+++ b/rpp/include/rpp/mout.h
@@ -14,13 +14,69 @@
 
 /**
  * MOUT module initialization.
+ *
  * Call this method before using this module.
  *
- * @return SUCCESS if initialization successful.
- *          FAILURE is module already initialized.
+ * This function is not thread safe. Do not call it from multiple threads.
+ *
+ * @return SUCCESS if initialization successful.\n
+ *         FAILURE if module already initialized.
  */
 int8_t rpp_mout_init();
 
 
-#endif /* __RPP_MOUT_H */
+/**
+ * Set the output of given pin to given value.
+ *
+ * The function is thread safe, unless compiled with -DRPP_THREADSAFE=0.
+ *
+ * This function will also verify if a faulty condition is detected. See return
+ * documentation below for details.
+ *
+ * @param[in] pin       The pin number to set [1-6].
+ * @param[in] val       The value to be set [HIGH|LOW].
+ *
+ * @return SUCCESS if pin could be set and verified.\n
+ *         -1 if pin number is out of range.\n
+ *         -2 if val is not HIGH or LOW.\n
+ *         -3 if pin could not be set. With current implementation this should
+ *            never happen.\n
+ *         -4 if pin is confirmed to be in trouble.
+ *            This normally indicates a hardware failure and that the driver
+ *            chip pulled the diagnostic pin.
+ */
+int8_t rpp_mout_set(uint8_t pin, uint8_t val);
 
+
+/**
+ * Get the cached value of the given pin set by rpp_mout_set().
+ *
+ * The function is thread safe, unless compiled with -DRPP_THREADSAFE=0.
+ *
+ * This will not read the value on the pin. To confirm if the output is
+ * correctly set call rpp_mout_diag() and confirm SUCCESS.
+ *
+ * @param[in] pin       The pin number to get cached value [1-6].
+ *
+ * @return HIGH or LOW cached from last rpp_mout_set() call for given pin.
+ *         -1 if pin number is out of range.
+ */
+int8_t rpp_mout_get(uint8_t pin);
+
+
+/**
+ * Reads the value on the given diagnostic pin.
+ *
+ * The function is thread safe, unless compiled with -DRPP_THREADSAFE=0.
+ *
+ * Note that rpp_mout_set() calls this routine already before returning.
+ *
+ * @param[in] pin       The pin number to read [1-6].
+ *
+ * @return SUCCESS is output is operating normally.
+ *         FAILURE if a faulty condition was detected.
+ */
+int8_t rpp_mout_diag(uint8_t pin);
+
+
+#endif /* __RPP_MOUT_H */