Merge pull request #50 from adnan-ashraf/non-blocking-functions

Non-blocking functions

.github/workflows/stylechecker.yml

@@ -16,7 +16,7 @@ jobs:
     - name: Install recent uncrustify
       run: |
         # we need this because of a bug introduced in https://github.com/uncrustify/uncrustify/pull/3655
-        git clone https://github.com/uncrustify/uncrustify.git --branch uncrustify-0.75.1
+        git clone https://github.com/uncrustify/uncrustify.git --branch uncrustify-0.79.0
         cd uncrustify && mkdir build && cd build
         cmake .. && sudo make install && cd ../..
     - name: Run uncrustify

inc/mlx90632.h

@@ -61,15 +61,15 @@
 
 /* BIT, GENMASK and ARRAY_SIZE macros are imported from kernel */
 #ifndef BIT
-#define BIT(x)(1UL << (x))
+#define BIT(x)(1U << (x))
 #endif
 #ifndef GENMASK
 #ifndef BITS_PER_LONG
 #warning "Using default BITS_PER_LONG value"
 #define BITS_PER_LONG 64 /**< Define how many bits per long your CPU has */
 #endif
 #define GENMASK(h, l) \
-    (((~0UL) << (l)) & (~0UL >> (BITS_PER_LONG - 1 - (h))))
+        ((((1U << h) - 1) | (1U << h)) & ~((1U << l) - 1))
 #endif
 #ifndef ARRAY_SIZE
 #define ARRAY_SIZE(arr) (sizeof(arr) / sizeof(arr[0])) /**< Return number of elements in array */
@@ -163,6 +163,8 @@ typedef enum mlx90632_meas_e {
 /* Start of burst measurement options */
 #define MLX90632_START_BURST_MEAS MLX90632_CFG_SOB(1)
 #define MLX90632_BURST_MEAS_NOT_PENDING MLX90632_CFG_SOB(0)
+/* Start of single measurement option */
+#define MLX90632_START_SINGLE_MEAS (1 << MLX90632_CFG_SOC_SHIFT)
 
 /* Device status register - volatile */
 #define MLX90632_REG_STATUS 0x3fff /**< Device status register */
@@ -208,7 +210,48 @@ typedef enum mlx90632_meas_e {
  * Masks the old register and shifts the new value in
  */
 #define MLX90632_NEW_REG_VALUE(old_reg, new_value, h, l) \
-    ((old_reg & (0xFFFF ^ GENMASK(h, l))) | (new_value << MLX90632_EE_REFRESH_RATE_SHIFT))
+        ((old_reg & (0xFFFF ^ GENMASK(h, l))) | (new_value << MLX90632_EE_REFRESH_RATE_SHIFT))
+
+/** Read raw ambient and object temperature only when measurement data is ready
+ *
+ * Read raw ambient and object temperatures without waiting. This values still need
+ * to be pre-processed via @link mlx90632_preprocess_temp_ambient @endlink and @link
+ * mlx90632_preprocess_temp_object @endlink functions and then processed via @link
+ * mlx90632_calc_temp_ambient @endlink and @link mlx90632_calc_temp_object @endlink
+ * to retrieve values in milliCelsius. This function assumes that measurement cycle
+ * has been triggered and completed via @link mlx90632_start_measurement @endlink or
+ * @link mlx90632_trigger_measurement @endlink or @link mlx90632_wait_for_measurement @endlink,
+ * and channel position has been checked via @link mlx90632_get_channel_position @endlink
+ * in case of continuous mode. This function assumes that measurement cycle has been
+ * triggered and completed via @link mlx90632_start_measurement_burst @endlink, or @link
+ * mlx90632_trigger_measurement_burst @endlink and @link mlx90632_wait_for_measurement_burst
+ * @endlink with sufficient time in between needed to refresh the whole measurement table
+ * in case of burst mode. This function assumes that measurement cycle has been
+ * triggered and completed via @link mlx90632_trigger_measurement_single @endlink and
+ * @link mlx90632_wait_for_measurement @endlink with sufficient time in between needed to
+ * refresh a single measurement in case of single mode (must be triggered and completed
+ * two times after power-up before calling this function).
+ *
+ * @param[in] channel_position Channel position where new (recently updated) measurement can be found,
+ *                             usually return value of @link mlx90632_start_measurement @endlink or
+ *                             @link mlx90632_wait_for_measurement @endlink or @link
+ *                             mlx90632_get_channel_position @endlink in case of continuous mode,
+ *                             2 in case of burst mode, and return value of @link
+ *                             mlx90632_wait_for_measurement @endlink or @link
+ *                             mlx90632_get_channel_position @endlink in case of single mode
+ * @param[out] ambient_new_raw Pointer to where new raw ambient temperature is written
+ * @param[out] object_new_raw Pointer to where new raw object temperature is written
+ * @param[out] ambient_old_raw Pointer to where old raw ambient temperature is written
+ * @param[out] object_old_raw Pointer to where old raw object temperature is written
+ *
+ * @retval 0 Successfully read both temperatures
+ * @retval <0 Something went wrong. Check errno.h for more details
+ *
+ * @note This function is not blocking!
+ */
+int32_t mlx90632_read_temp_raw_wo_wait(int32_t channel_position,
+                                       int16_t *ambient_new_raw, int16_t *ambient_old_raw,
+                                       int16_t *object_new_raw, int16_t *object_old_raw);
 
 /** Read raw ambient and object temperature
  *
@@ -368,6 +411,30 @@ double mlx90632_calc_temp_object_reflected(int32_t object, int32_t ambient, doub
  */
 int32_t mlx90632_init(void);
 
+/** Trigger measurement for mlx90632
+ *
+ * Trigger measurement cycle. It does not read anything, just triggers measurement.
+ *
+ * @retval <0 Something failed. Check errno.h for more information
+ * @retval 0 Successfully triggered and started measuremeent
+ *
+ * @note This function is not blocking!
+ */
+int32_t mlx90632_trigger_measurement(void);
+
+/** Wait for measurement to complete for mlx90632
+ *
+ * Wait for measurement data to be ready. It does not read anything, just completes measurement.
+ * This function assumes that measurement cycle has been triggered via @link
+ * mlx90632_trigger_measurement @endlink or @link mlx90632_trigger_measurement_single @endlink.
+ *
+ * @retval <0 Something failed. Check errno.h for more information
+ * @retval >=0 Channel position where new (recently updated) measurement can be found
+ *
+ * @note This function is using usleep so it is blocking!
+ */
+int32_t mlx90632_wait_for_measurement(void);
+
 /** Trigger start measurement for mlx90632
  *
  * Trigger measurement cycle and wait for data to be ready. It does not read anything, just triggers and completes.
@@ -377,7 +444,7 @@ int32_t mlx90632_init(void);
  *
  * @note This function is using usleep so it is blocking!
  */
-int mlx90632_start_measurement(void);
+int32_t mlx90632_start_measurement(void);
 
 /** Set emissivity which is retained in single variable.
  *
@@ -391,6 +458,33 @@ void mlx90632_set_emissivity(double value);
  */
 double mlx90632_get_emissivity(void);
 
+/** Trigger burst measurement for mlx90632
+ *
+ * Trigger a full measurement cycle. It does not read anything, just triggers measurement.
+ * The SOB bit is set so that the complete measurement table is re-freshed.
+ *
+ * @note The SOB bit is cleared internally by the mlx90632 immediately after the measurement has started.
+ *
+ * @retval <0 Something failed. Check errno.h for more information
+ * @retval 0 Successfully triggered and started measuremeent
+ *
+ * @note This function is not blocking!
+ */
+int32_t mlx90632_trigger_measurement_burst(void);
+
+/** Wait for burst measurement to complete for mlx90632
+ *
+ * Wait for measurement data to be ready. It does not read anything, just completes measurement.
+ * This function assumes that burst measurement cycle has been triggered via @link
+ * mlx90632_trigger_measurement_burst @endlink.
+ *
+ * @retval <0 Something failed. Check errno.h for more information
+ * @retval 0 New data is available and waiting to be processed
+ *
+ * @note This function is using usleep so it is blocking!
+ */
+int32_t mlx90632_wait_for_measurement_burst(void);
+
 /** Trigger start of burst measurement for mlx90632
  *
  * Trigger a single measurement cycle and wait for data to be ready. It does not read anything, just triggers and completes.
@@ -407,6 +501,20 @@ double mlx90632_get_emissivity(void);
  */
 int32_t mlx90632_start_measurement_burst(void);
 
+/** Trigger single measurement for mlx90632
+ *
+ * Trigger a single measurement cycle. It does not read anything, just triggers measurement.
+ * The SOC bit is set so that the single measurement is triggered.
+ *
+ * @note The SOC bit is cleared internally by the mlx90632 immediately after the measurement has started.
+ *
+ * @retval <0 Something failed. Check errno.h for more information
+ * @retval 0 Successfully triggered and started measuremeent
+ *
+ * @note This function is not blocking!
+ */
+int32_t mlx90632_trigger_measurement_single(void);
+
 /** Reads the refresh rate and calculates the time needed for a single measurment from the EEPROM settings.
  *
  * @param[in] meas Measurement to read the frefresh rate for
@@ -453,11 +561,18 @@ int32_t mlx90632_set_refresh_rate(mlx90632_meas_t measRate);
  */
 mlx90632_meas_t mlx90632_get_refresh_rate(void);
 
+/** Gets the channel position where new (recently updated) measurement can be found
+ *
+ * @retval <0 Something failed. Check errno.h for more information
+ * @retval >=0 Channel position where new (recently updated) measurement can be found
+ */
+int32_t mlx90632_get_channel_position(void);
+
 ///@}
 
 #ifdef TEST
 int32_t mlx90632_read_temp_ambient_raw(int16_t *ambient_new_raw, int16_t *ambient_old_raw);
-int32_t mlx90632_read_temp_object_raw(int32_t start_measurement_ret,
+int32_t mlx90632_read_temp_object_raw(int32_t channel_position,
                                       int16_t *object_new_raw, int16_t *object_old_raw);
 
 #endif

inc/mlx90632_extended_meas.h

@@ -24,6 +24,37 @@
 #ifndef _MLX90632_EXTENDED_MEAS_LIB_
 #define _MLX90632_EXTENDED_MEAS_LIB_
 
+/** Read raw ambient and object temperature for extended range only when measurement data is ready
+ *
+ * Read raw ambient and object temperatures without waiting. This values still need
+ * to be pre-processed via @link mlx90632_preprocess_temp_ambient_extended @endlink and @link
+ * mlx90632_preprocess_temp_object_extended @endlink functions and then processed via @link
+ * mlx90632_calc_temp_ambient_extended @endlink and @link mlx90632_calc_temp_object_extended @endlink
+ * to retrieve values in milliCelsius. This function assumes that measurement cycle
+ * has been triggered and completed via @link mlx90632_start_measurement @endlink or
+ * @link mlx90632_trigger_measurement @endlink or @link mlx90632_wait_for_measurement @endlink,
+ * and channel position has been checked via @link mlx90632_get_channel_position @endlink
+ * in case of continuous mode. This function assumes that measurement cycle has been
+ * triggered and completed via @link mlx90632_start_measurement_burst @endlink, or @link
+ * mlx90632_trigger_measurement_burst @endlink and @link mlx90632_wait_for_measurement_burst
+ * @endlink with sufficient time in between needed to refresh the whole measurement table
+ * in case of burst mode. This function assumes that measurement cycle has been
+ * triggered and completed via @link mlx90632_trigger_measurement_single @endlink and
+ * @link mlx90632_wait_for_measurement @endlink with sufficient time in between needed to
+ * refresh a single measurement in case of single mode (must be triggered and completed
+ * three times after power-up before calling this function).
+ *
+ * @param[out] ambient_new_raw Pointer to where new raw ambient temperature is written
+ * @param[out] object_new_raw Pointer to where new raw object temperature is written
+ * @param[out] ambient_old_raw Pointer to where old raw ambient temperature is written
+ *
+ * @retval 0 Successfully read both temperatures
+ * @retval <0 Something went wrong. Check errno.h for more details
+ *
+ * @note This function is not blocking!
+ */
+int32_t mlx90632_read_temp_raw_extended_wo_wait(int16_t *ambient_new_raw, int16_t *ambient_old_raw, int16_t *object_new_raw);
+
 /** Read raw ambient and object temperature for extended range
  *
  * Trigger and read raw ambient and object temperatures. This values still need