[nrf fromtree] drivers: adc: nrfx: enable negative values for single-ended ADC readings

The ADC driver API already supports ADC readings which can return signed
values, these are differential readings. In Nordic's datasheet, we have
a mode called "single ended", but its just a name. "Single ended" is a
differential reading, with the negative channel tied to GND. This is not
compatible with zephyrs definition of a single ended reading.

To support Nordic's "single ended" mode, the user must configure
a differential reading, with the negative input tied to ground, which
the saadc driver can then use to configure the reading as Nordic SAADC
"single ended", and return negative values as expected.

(cherry picked from commit 138f977)

Signed-off-by: Jakub Zymelka <[email protected]>

Author: jaz1-nordic

drivers/adc/adc_nrfx_saadc.c

@@ -100,6 +100,7 @@ BUILD_ASSERT((NRF_SAADC_AIN0 == NRF_SAADC_INPUT_AIN0) &&
 struct driver_data {
 	struct adc_context ctx;
 	uint8_t single_ended_channels;
+	uint8_t divide_single_ended_value;
 	uint8_t active_channel_cnt;
 	void *mem_reg;
 	void *user_buffer;
@@ -191,22 +192,24 @@ static int input_assign(nrf_saadc_input_t *pin_p,
 
 	if (channel_cfg->differential) {
 		if (channel_cfg->input_negative > ARRAY_SIZE(saadc_psels) ||
-		    channel_cfg->input_negative < NRF_SAADC_AIN0 ||
 		    (IS_ENABLED(CONFIG_NRF_PLATFORM_HALTIUM) &&
 		     (channel_cfg->input_positive > NRF_SAADC_AIN7) !=
 		     (channel_cfg->input_negative > NRF_SAADC_AIN7))) {
 			LOG_ERR("Invalid analog negative input number: %d",
 				channel_cfg->input_negative);
 			return -EINVAL;
 		}
-		*pin_n = saadc_psels[channel_cfg->input_negative];
+		*pin_n = channel_cfg->input_negative == NRF_SAADC_GND ?
+			 NRF_SAADC_INPUT_DISABLED :
+			 saadc_psels[channel_cfg->input_negative];
 	} else {
 		*pin_n = NRF_SAADC_INPUT_DISABLED;
 	}
 #else
 	*pin_p = channel_cfg->input_positive;
-	*pin_n = channel_cfg->differential ? channel_cfg->input_negative
-					   : NRF_SAADC_INPUT_DISABLED;
+	*pin_n = (channel_cfg->differential && (channel_cfg->input_negative != NRF_SAADC_GND))
+			 ? channel_cfg->input_negative
+			 : NRF_SAADC_INPUT_DISABLED;
 #endif
 	LOG_DBG("ADC positive input: %d", *pin_p);
 	LOG_DBG("ADC negative input: %d", *pin_n);
@@ -356,11 +359,18 @@ static int adc_nrfx_channel_setup(const struct device *dev,
 	 * after ADC sequence ends.
 	 */
 	if (channel_cfg->differential) {
-		ch_cfg->mode = NRF_SAADC_MODE_DIFFERENTIAL;
-		m_data.single_ended_channels &= ~BIT(channel_cfg->channel_id);
+		if (channel_cfg->input_negative == NRF_SAADC_GND) {
+			ch_cfg->mode = NRF_SAADC_MODE_SINGLE_ENDED;
+			m_data.single_ended_channels |= BIT(channel_cfg->channel_id);
+			m_data.divide_single_ended_value |= BIT(channel_cfg->channel_id);
+		} else {
+			ch_cfg->mode = NRF_SAADC_MODE_DIFFERENTIAL;
+			m_data.single_ended_channels &= ~BIT(channel_cfg->channel_id);
+		}
 	} else {
 		ch_cfg->mode = NRF_SAADC_MODE_SINGLE_ENDED;
 		m_data.single_ended_channels |= BIT(channel_cfg->channel_id);
+		m_data.divide_single_ended_value &= ~BIT(channel_cfg->channel_id);
 	}
 
 	nrfx_err_t ret = nrfx_saadc_channel_config(&cfg);
@@ -539,22 +549,32 @@ static void correct_single_ended(const struct adc_sequence *sequence, nrf_saadc_
 				 uint16_t num_samples)
 {
 	int16_t *sample = (int16_t *)buffer;
+	uint8_t selected_channels = sequence->channels;
+	uint8_t divide_single_ended_value = m_data.divide_single_ended_value;
 
 	if (m_data.internal_timer_enabled) {
-		for (int i = 0; i < num_samples; i++) {
-			if (sample[i] < 0) {
-				sample[i] = 0;
+		if (selected_channels & divide_single_ended_value) {
+			for (int i = 0; i < num_samples; i++) {
+				sample[i] /= 2;
+			}
+		} else {
+			for (int i = 0; i < num_samples; i++) {
+				if (sample[i] < 0) {
+					sample[i] = 0;
+				}
 			}
 		}
 	} else {
-		uint8_t selected_channels = sequence->channels;
 		uint8_t single_ended_channels = m_data.single_ended_channels;
 
 		for (uint16_t channel_bit = BIT(0); channel_bit <= single_ended_channels;
 		     channel_bit <<= 1) {
-			if ((channel_bit & selected_channels & single_ended_channels) &&
-			    (*sample < 0)) {
-				*sample = 0;
+			if (channel_bit & selected_channels & single_ended_channels) {
+				if (channel_bit & divide_single_ended_value) {
+					*sample /= 2;
+				} else if (*sample < 0) {
+					*sample = 0;
+				}
 			}
 			sample++;
 		}

include/zephyr/dt-bindings/adc/nrf-saadc.h

@@ -7,6 +7,30 @@
 #ifndef ZEPHYR_INCLUDE_DT_BINDINGS_ADC_NRF_SAADC_H_
 #define ZEPHYR_INCLUDE_DT_BINDINGS_ADC_NRF_SAADC_H_
 
+/**
+ * @brief Short ADC negative input to ground
+ *
+ * @details The nRF SAADC hardware only supports differential readings.
+ * The nRF SAADC SE (single ended) mode is differential with the negative
+ * input shorted to GND (ground). To use the nRF SAADC SE mode, set the
+ * negative input to NRF_SAADC_GND:
+ *
+ * @code{.dts}
+ *   zephyr,input-positive = <NRF_SAADC_AIN3>;
+ *   zephyr,input-negative = <NRF_SAADC_GND>;
+ * @endcode
+ *
+ * The nRF SAADC driver also supports using the nRF SAADC SE mode in
+ * emulated "single-ended" mode, as defined by zephyr. In this mode,
+ * negative readings will be clamped to 0 by software to emulate the
+ * behavior of an ADC in "single-ended" mode, as defined by zephyr. To
+ * do this, only define the positive input:
+ *
+ * @code{.dts}
+ *   zephyr,input-positive = <NRF_SAADC_AIN3>;
+ * @endcode
+ */
+#define NRF_SAADC_GND  0
 #define NRF_SAADC_AIN0 1
 #define NRF_SAADC_AIN1 2
 #define NRF_SAADC_AIN2 3