1 // SPDX-License-Identifier: GPL-2.0-only
2 /*
3 * Driver for Texas Instruments ADS131M02 family ADC chips.
4 *
5 * Copyright (C) 2024 Protonic Holland
6 * Copyright (C) 2025 Oleksij Rempel <kernel@pengutronix.de>, Pengutronix
7 *
8 * Primary Datasheet Reference (used for citations):
9 * ADS131M08 8-Channel, Simultaneously-Sampling, 24-Bit, Delta-Sigma ADC
10 * Document SBAS950B, Revised February 2021
11 * https://www.ti.com/lit/ds/symlink/ads131m08.pdf
12 */
13
14 #include <linux/array_size.h>
15 #include <linux/bitfield.h>
16 #include <linux/bitops.h>
17 #include <linux/cleanup.h>
18 #include <linux/clk.h>
19 #include <linux/crc-itu-t.h>
20 #include <linux/delay.h>
21 #include <linux/dev_printk.h>
22 #include <linux/device/devres.h>
23 #include <linux/err.h>
24 #include <linux/iio/iio.h>
25 #include <linux/lockdep.h>
26 #include <linux/module.h>
27 #include <linux/mutex.h>
28 #include <linux/regulator/consumer.h>
29 #include <linux/reset.h>
30 #include <linux/spi/spi.h>
31 #include <linux/string.h>
32 #include <linux/types.h>
33 #include <linux/unaligned.h>
34
35 /* Max channels supported by the largest variant in the family (ADS131M08) */
36 #define ADS131M_MAX_CHANNELS 8
37
38 /* Section 6.7, t_REGACQ (min time after reset) is 5us */
39 #define ADS131M_RESET_DELAY_US 5
40
41 #define ADS131M_WORD_SIZE_BYTES 3
42 #define ADS131M_RESPONSE_WORDS 1
43 #define ADS131M_CRC_WORDS 1
44
45 /*
46 * SPI Frame word count calculation.
47 * Frame = N channel words + 1 response word + 1 CRC word.
48 * Word size depends on WLENGTH bits in MODE register (Default 24-bit).
49 */
50 #define ADS131M_FRAME_WORDS(nch) \
51 ((nch) + ADS131M_RESPONSE_WORDS + ADS131M_CRC_WORDS)
52
53 /*
54 * SPI Frame byte size calculation.
55 * Assumes default word size of 24 bits (3 bytes).
56 */
57 #define ADS131M_FRAME_BYTES(nch) \
58 (ADS131M_FRAME_WORDS(nch) * ADS131M_WORD_SIZE_BYTES)
59
60 /*
61 * Index calculation for the start byte of channel 'x' data within the RX buffer.
62 * Assumes 24-bit words (3 bytes per word).
63 * The received frame starts with the response word (e.g., STATUS register
64 * content when NULL command was sent), followed by data for channels 0 to N-1,
65 * and finally the output CRC word.
66 * Response = index 0..2, Chan0 = index 3..5, Chan1 = index 6..8, ...
67 * Index for ChanX = 3 (response) + x * 3 (channel data size).
68 */
69 #define ADS131M_CHANNEL_INDEX(x) \
70 ((x) * ADS131M_WORD_SIZE_BYTES + ADS131M_WORD_SIZE_BYTES)
71
72 #define ADS131M_CMD_NULL 0x0000
73 #define ADS131M_CMD_RESET 0x0011
74
75 #define ADS131M_CMD_ADDR_MASK GENMASK(11, 7)
76 #define ADS131M_CMD_NUM_MASK GENMASK(6, 0)
77
78 #define ADS131M_CMD_RREG_OP 0xa000
79 #define ADS131M_CMD_WREG_OP 0x6000
80
81 #define ADS131M_CMD_RREG(a, n) \
82 (ADS131M_CMD_RREG_OP | \
83 FIELD_PREP(ADS131M_CMD_ADDR_MASK, a) | \
84 FIELD_PREP(ADS131M_CMD_NUM_MASK, n))
85 #define ADS131M_CMD_WREG(a, n) \
86 (ADS131M_CMD_WREG_OP | \
87 FIELD_PREP(ADS131M_CMD_ADDR_MASK, a) | \
88 FIELD_PREP(ADS131M_CMD_NUM_MASK, n))
89
90 /* STATUS Register (0x01h) bit definitions */
91 #define ADS131M_STATUS_CRC_ERR BIT(12) /* Input CRC error */
92
93 #define ADS131M_REG_MODE 0x02
94 #define ADS131M_MODE_RX_CRC_EN BIT(12) /* Enable Input CRC */
95 #define ADS131M_MODE_CRC_TYPE_ANSI BIT(11) /* 0 = CCITT, 1 = ANSI */
96 #define ADS131M_MODE_RESET_FLAG BIT(10)
97
98 #define ADS131M_REG_CLOCK 0x03
99 #define ADS131M_CLOCK_XTAL_DIS BIT(7)
100 #define ADS131M_CLOCK_EXTREF_EN BIT(6)
101
102 /* 1.2V internal reference, in millivolts, for IIO_VAL_FRACTIONAL_LOG2 */
103 #define ADS131M_VREF_INTERNAL_mV 1200
104 /* 24-bit resolution */
105 #define ADS131M_RESOLUTION_BITS 24
106 /* Signed data uses (RESOLUTION_BITS - 1) magnitude bits */
107 #define ADS131M_CODE_BITS (ADS131M_RESOLUTION_BITS - 1)
108
109 /* External ref FSR = Vref * 0.96 */
110 #define ADS131M_EXTREF_SCALE_NUM 96
111 #define ADS131M_EXTREF_SCALE_DEN 100
112
113 struct ads131m_configuration {
114 const struct iio_chan_spec *channels;
115 const char *name;
116 u16 reset_ack;
117 u8 num_channels;
118 u8 supports_extref:1;
119 u8 supports_xtal:1;
120 };
121
122 struct ads131m_priv {
123 struct iio_dev *indio_dev;
124 struct spi_device *spi;
125 const struct ads131m_configuration *config;
126
127 bool use_external_ref;
128 int scale_val;
129 int scale_val2;
130
131 struct spi_transfer xfer;
132 struct spi_message msg;
133
134 /*
135 * Protects the shared tx_buffer and rx_buffer. More importantly,
136 * this serializes all SPI communication to ensure the atomicity
137 * of multi-cycle command sequences (like WREG, RREG, or RESET).
138 */
139 struct mutex lock;
140
141 /* DMA-safe buffers should be placed at the end of the struct. */
142 u8 tx_buffer[ADS131M_FRAME_BYTES(ADS131M_MAX_CHANNELS)]
143 __aligned(IIO_DMA_MINALIGN);
144 u8 rx_buffer[ADS131M_FRAME_BYTES(ADS131M_MAX_CHANNELS)];
145 };
146
147 /**
148 * ads131m_tx_frame_unlocked - Sends a command frame with Input CRC
149 * @priv: Device private data structure.
150 * @command: The 16-bit command to send (e.g., NULL, RREG, RESET).
151 *
152 * This function sends a command in Word 0, and its calculated 16-bit
153 * CRC in Word 1, as required when Input CRC is enabled.
154 *
155 * Return: 0 on success, or a negative error code.
156 */
ads131m_tx_frame_unlocked(struct ads131m_priv * priv,u32 command)157 static int ads131m_tx_frame_unlocked(struct ads131m_priv *priv, u32 command)
158 {
159 struct iio_dev *indio_dev = priv->indio_dev;
160 u16 crc;
161
162 lockdep_assert_held(&priv->lock);
163
164 memset(priv->tx_buffer, 0, ADS131M_FRAME_BYTES(indio_dev->num_channels));
165
166 /* Word 0: 16-bit command, MSB-aligned in 24-bit word */
167 put_unaligned_be16(command, &priv->tx_buffer[0]);
168
169 /* Word 1: Input CRC. Calculated over the 3 bytes of Word 0. */
170 crc = crc_itu_t(0xffff, priv->tx_buffer, 3);
171 put_unaligned_be16(crc, &priv->tx_buffer[3]);
172
173 return spi_sync(priv->spi, &priv->msg);
174 }
175
176 /**
177 * ads131m_rx_frame_unlocked - Receives a full SPI data frame.
178 * @priv: Device private data structure.
179 *
180 * This function sends a NULL command (with its CRC) to clock out a
181 * full SPI frame from the device (e.g., response + channel data + CRC).
182 *
183 * Return: 0 on success, or a negative error code.
184 */
ads131m_rx_frame_unlocked(struct ads131m_priv * priv)185 static int ads131m_rx_frame_unlocked(struct ads131m_priv *priv)
186 {
187 return ads131m_tx_frame_unlocked(priv, ADS131M_CMD_NULL);
188 }
189
190 /**
191 * ads131m_check_status_crc_err - Checks for an Input CRC error.
192 * @priv: Device private data structure.
193 *
194 * Sends a NULL command to fetch the STATUS register and checks the
195 * CRC_ERR bit. This is used to verify the integrity of the previous
196 * command (like RREG or WREG).
197 *
198 * Return: 0 on success, -EIO if CRC_ERR bit is set.
199 */
ads131m_check_status_crc_err(struct ads131m_priv * priv)200 static int ads131m_check_status_crc_err(struct ads131m_priv *priv)
201 {
202 struct device *dev = &priv->spi->dev;
203 u16 status;
204 int ret;
205
206 lockdep_assert_held(&priv->lock);
207
208 ret = ads131m_rx_frame_unlocked(priv);
209 if (ret < 0) {
210 dev_err_ratelimited(dev,
211 "SPI error on STATUS read for CRC check\n");
212 return ret;
213 }
214
215 status = get_unaligned_be16(&priv->rx_buffer[0]);
216 if (status & ADS131M_STATUS_CRC_ERR) {
217 dev_err_ratelimited(dev,
218 "Input CRC error reported in STATUS = 0x%04x\n",
219 status);
220 return -EIO;
221 }
222
223 return 0;
224 }
225
226 /**
227 * ads131m_write_reg_unlocked - Writes a single register and verifies the ACK.
228 * @priv: Device private data structure.
229 * @reg: The 8-bit register address.
230 * @val: The 16-bit value to write.
231 *
232 * This function performs the full 3-cycle WREG operation with Input CRC:
233 * 1. (Cycle 1) Sends WREG command, data, and its calculated CRC.
234 * 2. (Cycle 2) Sends NULL+CRC to retrieve the response from Cycle 1.
235 * 3. Verifies the response is the correct ACK for the WREG.
236 * 4. (Cycle 3) Sends NULL+CRC to retrieve STATUS and check for CRC_ERR.
237 *
238 * Return: 0 on success, or a negative error code.
239 */
ads131m_write_reg_unlocked(struct ads131m_priv * priv,u8 reg,u16 val)240 static int ads131m_write_reg_unlocked(struct ads131m_priv *priv, u8 reg, u16 val)
241 {
242 struct iio_dev *indio_dev = priv->indio_dev;
243 u16 command, expected_ack, response, crc;
244 struct device *dev = &priv->spi->dev;
245 int ret_crc_err = 0;
246 int ret;
247
248 lockdep_assert_held(&priv->lock);
249
250 command = ADS131M_CMD_WREG(reg, 0); /* n = 0 for 1 register */
251 /*
252 * Per Table 8-11, WREG response is: 010a aaaa ammm mmmm
253 * For 1 reg (n = 0 -> m = 0): 010a aaaa a000 0000 = 0x4000 | (reg << 7)
254 */
255 expected_ack = 0x4000 | (reg << 7);
256
257 /* Cycle 1: Send WREG Command + Data + Input CRC */
258
259 memset(priv->tx_buffer, 0, ADS131M_FRAME_BYTES(indio_dev->num_channels));
260
261 /* Word 0: WREG command, 1 reg (n = 0), MSB-aligned */
262 put_unaligned_be16(command, &priv->tx_buffer[0]);
263
264 /* Word 1: Data, MSB-aligned */
265 put_unaligned_be16(val, &priv->tx_buffer[3]);
266
267 /* Word 2: Input CRC. Calculated over Word 0 (Cmd) and Word 1 (Data). */
268 crc = crc_itu_t(0xffff, priv->tx_buffer, 6);
269 put_unaligned_be16(crc, &priv->tx_buffer[6]);
270
271 /* Ignore the RX buffer (it's from the previous command) */
272 ret = spi_sync(priv->spi, &priv->msg);
273 if (ret < 0) {
274 dev_err_ratelimited(dev, "SPI error on WREG (cycle 1)\n");
275 return ret;
276 }
277
278 /* Cycle 2: Send NULL Command to get the WREG response */
279 ret = ads131m_rx_frame_unlocked(priv);
280 if (ret < 0) {
281 dev_err_ratelimited(dev, "SPI error on WREG ACK (cycle 2)\n");
282 return ret;
283 }
284
285 /*
286 * Response is in the first 2 bytes of the RX buffer
287 * (MSB-aligned 16-bit response)
288 */
289 response = get_unaligned_be16(&priv->rx_buffer[0]);
290 if (response != expected_ack) {
291 dev_err_ratelimited(dev, "WREG(0x%02x) failed, expected ACK 0x%04x, got 0x%04x\n",
292 reg, expected_ack, response);
293 ret_crc_err = -EIO;
294 /*
295 * Don't return yet, still need to do Cycle 3 to clear
296 * any potential CRC_ERR flag from this failed command.
297 */
298 }
299
300 /*
301 * Cycle 3: Check STATUS for Input CRC error.
302 * This is necessary even if ACK was wrong, to clear the CRC_ERR flag.
303 */
304 ret = ads131m_check_status_crc_err(priv);
305 if (ret < 0)
306 return ret;
307
308 return ret_crc_err;
309 }
310
311 /**
312 * ads131m_read_reg_unlocked - Reads a single register from the device.
313 * @priv: Device private data structure.
314 * @reg: The 8-bit register address.
315 * @val: Pointer to store the 16-bit register value.
316 *
317 * This function performs the full 3-cycle RREG operation with Input CRC:
318 * 1. (Cycle 1) Sends the RREG command + Input CRC.
319 * 2. (Cycle 2) Sends NULL+CRC to retrieve the register data.
320 * 3. (Cycle 3) Sends NULL+CRC to retrieve STATUS and check for CRC_ERR.
321 *
322 * Return: 0 on success, or a negative error code.
323 */
ads131m_read_reg_unlocked(struct ads131m_priv * priv,u8 reg,u16 * val)324 static int ads131m_read_reg_unlocked(struct ads131m_priv *priv, u8 reg, u16 *val)
325 {
326 struct device *dev = &priv->spi->dev;
327 u16 command;
328 int ret;
329
330 lockdep_assert_held(&priv->lock);
331
332 command = ADS131M_CMD_RREG(reg, 0); /* n=0 for 1 register */
333
334 /*
335 * Cycle 1: Send RREG Command + Input CRC
336 * Ignore the RX buffer (it's from the previous command)
337 */
338 ret = ads131m_tx_frame_unlocked(priv, command);
339 if (ret < 0) {
340 dev_err_ratelimited(dev, "SPI error on RREG (cycle 1)\n");
341 return ret;
342 }
343
344 /* Cycle 2: Send NULL Command to get the register data */
345 ret = ads131m_rx_frame_unlocked(priv);
346 if (ret < 0) {
347 dev_err_ratelimited(dev, "SPI error on RREG data (cycle 2)\n");
348 return ret;
349 }
350
351 /*
352 * Per datasheet, for a single reg read, the response is the data.
353 * It's in the first 2 bytes of the RX buffer (MSB-aligned 16-bit).
354 */
355 *val = get_unaligned_be16(&priv->rx_buffer[0]);
356
357 /*
358 * Cycle 3: Check STATUS for Input CRC error.
359 * The RREG command does not execute if CRC is bad, but we read
360 * STATUS anyway to clear the flag in case it was set.
361 */
362 return ads131m_check_status_crc_err(priv);
363 }
364
365 /**
366 * ads131m_rmw_reg - Reads, modifies, and writes a single register.
367 * @priv: Device private data structure.
368 * @reg: The 8-bit register address.
369 * @clear: Bitmask of bits to clear.
370 * @set: Bitmask of bits to set.
371 *
372 * This function performs an atomic read-modify-write operation on a register.
373 * It reads the register, applies the clear and set masks, and writes
374 * the new value back if it has changed.
375 *
376 * Return: 0 on success, or a negative error code.
377 */
ads131m_rmw_reg(struct ads131m_priv * priv,u8 reg,u16 clear,u16 set)378 static int ads131m_rmw_reg(struct ads131m_priv *priv, u8 reg, u16 clear, u16 set)
379 {
380 u16 old_val, new_val;
381 int ret;
382
383 guard(mutex)(&priv->lock);
384
385 ret = ads131m_read_reg_unlocked(priv, reg, &old_val);
386 if (ret < 0)
387 return ret;
388
389 new_val = (old_val & ~clear) | set;
390 if (new_val == old_val)
391 return 0;
392
393 return ads131m_write_reg_unlocked(priv, reg, new_val);
394 }
395
396 /**
397 * ads131m_verify_output_crc - Verifies the CRC of the received SPI frame.
398 * @priv: Device private data structure.
399 *
400 * This function calculates the CRC-16-CCITT (Poly 0x1021, Seed 0xFFFF) over
401 * the received response and channel data, and compares it to the CRC word
402 * received at the end of the SPI frame.
403 *
404 * Return: 0 on success, -EIO on CRC mismatch.
405 */
ads131m_verify_output_crc(struct ads131m_priv * priv)406 static int ads131m_verify_output_crc(struct ads131m_priv *priv)
407 {
408 struct iio_dev *indio_dev = priv->indio_dev;
409 struct device *dev = &priv->spi->dev;
410 u16 calculated_crc, received_crc;
411 size_t data_len;
412
413 lockdep_assert_held(&priv->lock);
414
415 /*
416 * Frame: [Response][Chan 0]...[Chan N-1][CRC Word]
417 * Data for CRC: [Response][Chan 0]...[Chan N-1]
418 * Data length = (N_channels + 1) * 3 bytes (at 24-bit word size)
419 */
420 data_len = ADS131M_FRAME_BYTES(indio_dev->num_channels) - 3;
421 calculated_crc = crc_itu_t(0xffff, priv->rx_buffer, data_len);
422
423 /*
424 * The received 16-bit CRC is MSB-aligned in the last 24-bit word.
425 * We extract it from the first 2 bytes (BE) of that word.
426 */
427 received_crc = get_unaligned_be16(&priv->rx_buffer[data_len]);
428 if (calculated_crc != received_crc) {
429 dev_err_ratelimited(dev, "Output CRC error. Got %04x, expected %04x\n",
430 received_crc, calculated_crc);
431 return -EIO;
432 }
433
434 return 0;
435 }
436
437 /**
438 * ads131m_adc_read - Reads channel data, checks input and output CRCs.
439 * @priv: Device private data structure.
440 * @channel: The channel number to read.
441 * @val: Pointer to store the raw 24-bit value.
442 *
443 * This function sends a NULL command (with Input CRC) to retrieve data.
444 * It checks the received STATUS word for any Input CRC errors from the
445 * previous command, and then verifies the Output CRC of the current
446 * data frame.
447 *
448 * Return: 0 on success, or a negative error code.
449 */
ads131m_adc_read(struct ads131m_priv * priv,u8 channel,s32 * val)450 static int ads131m_adc_read(struct ads131m_priv *priv, u8 channel, s32 *val)
451 {
452 struct device *dev = &priv->spi->dev;
453 u16 status;
454 int ret;
455 u8 *buf;
456
457 guard(mutex)(&priv->lock);
458
459 /* Send NULL command + Input CRC, and receive data frame */
460 ret = ads131m_rx_frame_unlocked(priv);
461 if (ret < 0)
462 return ret;
463
464 /*
465 * Check STATUS for Input CRC error from the previous command frame.
466 * Note: the STATUS word belongs to the frame before this NULL command.
467 */
468 status = get_unaligned_be16(&priv->rx_buffer[0]);
469 if (status & ADS131M_STATUS_CRC_ERR) {
470 dev_err_ratelimited(dev,
471 "Previous input CRC error reported in STATUS (0x%04x)\n",
472 status);
473 }
474
475 ret = ads131m_verify_output_crc(priv);
476 if (ret < 0)
477 return ret;
478
479 buf = &priv->rx_buffer[ADS131M_CHANNEL_INDEX(channel)];
480 *val = sign_extend32(get_unaligned_be24(buf), ADS131M_CODE_BITS);
481
482 return 0;
483 }
484
ads131m_read_raw(struct iio_dev * indio_dev,struct iio_chan_spec const * channel,int * val,int * val2,long mask)485 static int ads131m_read_raw(struct iio_dev *indio_dev, struct iio_chan_spec const *channel,
486 int *val, int *val2, long mask)
487 {
488 struct ads131m_priv *priv = iio_priv(indio_dev);
489 int ret;
490
491 switch (mask) {
492 case IIO_CHAN_INFO_RAW:
493 ret = ads131m_adc_read(priv, channel->channel, val);
494 if (ret)
495 return ret;
496 return IIO_VAL_INT;
497 case IIO_CHAN_INFO_SCALE:
498 *val = priv->scale_val;
499 *val2 = priv->scale_val2;
500
501 return IIO_VAL_FRACTIONAL;
502 default:
503 return -EINVAL;
504 }
505 }
506
507 #define ADS131M_VOLTAGE_CHANNEL(num) \
508 { \
509 .type = IIO_VOLTAGE, \
510 .differential = 1, \
511 .indexed = 1, \
512 .channel = (num), \
513 .info_mask_separate = BIT(IIO_CHAN_INFO_RAW), \
514 .info_mask_shared_by_type = BIT(IIO_CHAN_INFO_SCALE), \
515 }
516
517 static const struct iio_chan_spec ads131m02_channels[] = {
518 ADS131M_VOLTAGE_CHANNEL(0),
519 ADS131M_VOLTAGE_CHANNEL(1),
520 };
521
522 static const struct iio_chan_spec ads131m03_channels[] = {
523 ADS131M_VOLTAGE_CHANNEL(0),
524 ADS131M_VOLTAGE_CHANNEL(1),
525 ADS131M_VOLTAGE_CHANNEL(2),
526 };
527
528 static const struct iio_chan_spec ads131m04_channels[] = {
529 ADS131M_VOLTAGE_CHANNEL(0),
530 ADS131M_VOLTAGE_CHANNEL(1),
531 ADS131M_VOLTAGE_CHANNEL(2),
532 ADS131M_VOLTAGE_CHANNEL(3),
533 };
534
535 static const struct iio_chan_spec ads131m06_channels[] = {
536 ADS131M_VOLTAGE_CHANNEL(0),
537 ADS131M_VOLTAGE_CHANNEL(1),
538 ADS131M_VOLTAGE_CHANNEL(2),
539 ADS131M_VOLTAGE_CHANNEL(3),
540 ADS131M_VOLTAGE_CHANNEL(4),
541 ADS131M_VOLTAGE_CHANNEL(5),
542 };
543
544 static const struct iio_chan_spec ads131m08_channels[] = {
545 ADS131M_VOLTAGE_CHANNEL(0),
546 ADS131M_VOLTAGE_CHANNEL(1),
547 ADS131M_VOLTAGE_CHANNEL(2),
548 ADS131M_VOLTAGE_CHANNEL(3),
549 ADS131M_VOLTAGE_CHANNEL(4),
550 ADS131M_VOLTAGE_CHANNEL(5),
551 ADS131M_VOLTAGE_CHANNEL(6),
552 ADS131M_VOLTAGE_CHANNEL(7),
553 };
554
555 static const struct ads131m_configuration ads131m02_config = {
556 .channels = ads131m02_channels,
557 .num_channels = ARRAY_SIZE(ads131m02_channels),
558 .reset_ack = 0xff22,
559 .name = "ads131m02",
560 };
561
562 static const struct ads131m_configuration ads131m03_config = {
563 .channels = ads131m03_channels,
564 .num_channels = ARRAY_SIZE(ads131m03_channels),
565 .reset_ack = 0xff23,
566 .name = "ads131m03",
567 };
568
569 static const struct ads131m_configuration ads131m04_config = {
570 .channels = ads131m04_channels,
571 .num_channels = ARRAY_SIZE(ads131m04_channels),
572 .reset_ack = 0xff24,
573 .name = "ads131m04",
574 };
575
576 static const struct ads131m_configuration ads131m06_config = {
577 .channels = ads131m06_channels,
578 .num_channels = ARRAY_SIZE(ads131m06_channels),
579 .reset_ack = 0xff26,
580 .supports_extref = true,
581 .supports_xtal = true,
582 .name = "ads131m06",
583 };
584
585 static const struct ads131m_configuration ads131m08_config = {
586 .channels = ads131m08_channels,
587 .num_channels = ARRAY_SIZE(ads131m08_channels),
588 .reset_ack = 0xff28,
589 .supports_extref = true,
590 .supports_xtal = true,
591 .name = "ads131m08",
592 };
593
594 static const struct iio_info ads131m_info = {
595 .read_raw = ads131m_read_raw,
596 };
597
598 /*
599 * Prepares the reusable SPI message structure for a full-duplex transfer.
600 * The ADS131M requires sending a command frame while simultaneously
601 * receiving the response/data frame from the previous command cycle.
602 *
603 * This message is optimized for the primary data acquisition workflow:
604 * sending a single-word command (like NULL) and receiving a full data
605 * frame (Response + N*Channels + CRC).
606 *
607 * This message is sized for a full data frame and is reused for all
608 * command/data cycles. The driver does not implement variable-length SPI
609 * messages.
610 *
611 * Return: 0 on success, or a negative error code.
612 */
ads131m_prepare_message(struct ads131m_priv * priv)613 static int ads131m_prepare_message(struct ads131m_priv *priv)
614 {
615 struct iio_dev *indio_dev = priv->indio_dev;
616 struct device *dev = &priv->spi->dev;
617 int ret;
618
619 priv->xfer.tx_buf = priv->tx_buffer;
620 priv->xfer.rx_buf = priv->rx_buffer;
621 priv->xfer.len = ADS131M_FRAME_BYTES(indio_dev->num_channels);
622 spi_message_init_with_transfers(&priv->msg, &priv->xfer, 1);
623
624 ret = devm_spi_optimize_message(dev, priv->spi, &priv->msg);
625 if (ret)
626 return dev_err_probe(dev, ret, "failed to optimize SPI message\n");
627
628 return 0;
629 }
630
631 /**
632 * ads131m_hw_reset - Pulses the optional hardware reset.
633 * @priv: Device private data structure.
634 * @rstc: Reset control for the /RESET line.
635 *
636 * Pulses the /RESET line to perform a hardware reset and waits the
637 * required t_REGACQ time for the device to be ready.
638 *
639 * Return: 0 on success, or a negative error code.
640 */
ads131m_hw_reset(struct ads131m_priv * priv,struct reset_control * rstc)641 static int ads131m_hw_reset(struct ads131m_priv *priv,
642 struct reset_control *rstc)
643 {
644 struct device *dev = &priv->spi->dev;
645 int ret;
646
647 /*
648 * Manually pulse the reset line using the framework.
649 * The reset-gpio provider does not implement the .reset op,
650 * so we must use .assert and .deassert.
651 */
652 ret = reset_control_assert(rstc);
653 if (ret)
654 return dev_err_probe(dev, ret, "Failed to assert reset\n");
655
656 /* Datasheet: Hold /RESET low for > 2 f_CLKIN cycles. 1us is ample. */
657 fsleep(1);
658
659 ret = reset_control_deassert(rstc);
660 if (ret < 0)
661 return dev_err_probe(dev, ret, "Failed to deassert reset\n");
662
663 /* Wait t_REGACQ (5us) for registers to be accessible */
664 fsleep(ADS131M_RESET_DELAY_US);
665
666 return 0;
667 }
668
669 /**
670 * ads131m_sw_reset - Issues a software RESET and verifies ACK.
671 * @priv: Device private data structure.
672 *
673 * This function sends a RESET command (with Input CRC), waits t_REGACQ,
674 * reads back the RESET ACK, and then sends a final NULL to check for
675 * any input CRC errors.
676 *
677 * Return: 0 on success, or a negative error code.
678 */
ads131m_sw_reset(struct ads131m_priv * priv)679 static int ads131m_sw_reset(struct ads131m_priv *priv)
680 {
681 u16 expected_ack = priv->config->reset_ack;
682 struct device *dev = &priv->spi->dev;
683 u16 response;
684 int ret;
685
686 guard(mutex)(&priv->lock);
687
688 ret = ads131m_tx_frame_unlocked(priv, ADS131M_CMD_RESET);
689 if (ret < 0)
690 return dev_err_probe(dev, ret, "Failed to send RESET command\n");
691
692 /* Wait t_REGACQ (5us) for device to be ready after reset */
693 fsleep(ADS131M_RESET_DELAY_US);
694
695 /* Cycle 2: Send NULL + CRC to retrieve the response to the RESET */
696 ret = ads131m_rx_frame_unlocked(priv);
697 if (ret < 0)
698 return dev_err_probe(dev, ret, "Failed to read RESET ACK\n");
699
700 response = get_unaligned_be16(&priv->rx_buffer[0]);
701
702 /* Check against the device-specific ACK value */
703 if (response != expected_ack)
704 return dev_err_probe(dev, -EIO,
705 "RESET ACK mismatch, got 0x%04x, expected 0x%04x\n",
706 response, expected_ack);
707
708 /* Cycle 3: Check STATUS for Input CRC error on the RESET command. */
709 return ads131m_check_status_crc_err(priv);
710 }
711
712 /**
713 * ads131m_reset - Resets the device using hardware or software.
714 * @priv: Device private data structure.
715 * @rstc: Optional reset control, or NULL for software reset.
716 *
717 * This function performs a hardware reset if supported (rstc provided),
718 * otherwise it issues a software RESET command via SPI.
719 *
720 * Note: The software reset path also validates the device's reset
721 * acknowledgment against the expected ID for the compatible string.
722 * The hardware reset path bypasses this ID check.
723 *
724 * Return: 0 on success, or a negative error code.
725 */
ads131m_reset(struct ads131m_priv * priv,struct reset_control * rstc)726 static int ads131m_reset(struct ads131m_priv *priv, struct reset_control *rstc)
727 {
728 if (rstc)
729 return ads131m_hw_reset(priv, rstc);
730
731 return ads131m_sw_reset(priv);
732 }
733
ads131m_power_init(struct ads131m_priv * priv)734 static int ads131m_power_init(struct ads131m_priv *priv)
735 {
736 static const char * const supply_ids[] = { "avdd", "dvdd" };
737 struct device *dev = &priv->spi->dev;
738 int vref_uV;
739 int ret;
740
741 ret = devm_regulator_bulk_get_enable(dev, ARRAY_SIZE(supply_ids), supply_ids);
742 if (ret < 0)
743 return dev_err_probe(dev, ret, "failed to enable regulators\n");
744
745 /* Default to Internal 1.2V reference: 1200mV / 2^23 */
746 priv->scale_val = ADS131M_VREF_INTERNAL_mV;
747 priv->scale_val2 = BIT(ADS131M_CODE_BITS);
748
749 if (!priv->config->supports_extref)
750 return 0;
751
752 ret = devm_regulator_get_enable_read_voltage(dev, "refin");
753 if (ret < 0 && ret != -ENODEV)
754 return dev_err_probe(dev, ret, "failed to get refin supply\n");
755
756 if (ret == 0)
757 return dev_err_probe(dev, -EINVAL, "refin supply reports 0V\n");
758
759 if (ret == -ENODEV)
760 return 0;
761
762 vref_uV = ret;
763
764 /*
765 * External reference found: Scale(mV) = (vref_uV * 0.96) / 1000
766 * The denominator is 100 * 2^23 because of the 0.96 factor (96/100).
767 */
768 priv->scale_val = div_s64((s64)vref_uV * ADS131M_EXTREF_SCALE_NUM, 1000);
769 priv->scale_val2 = ADS131M_EXTREF_SCALE_DEN * BIT(ADS131M_CODE_BITS);
770 priv->use_external_ref = true;
771
772 return 0;
773 }
774
775 /**
776 * ads131m_hw_init - Initialize the ADC hardware.
777 * @priv: Device private data structure.
778 * @rstc: Optional reset control, or NULL for software reset.
779 * @is_xtal: True if 'clock-names' is "xtal", false if "clkin".
780 *
781 * Return: 0 on success, or a negative error code.
782 */
ads131m_hw_init(struct ads131m_priv * priv,struct reset_control * rstc,bool is_xtal)783 static int ads131m_hw_init(struct ads131m_priv *priv,
784 struct reset_control *rstc, bool is_xtal)
785 {
786 struct device *dev = &priv->spi->dev;
787 u16 mode_clear, mode_set;
788 int ret;
789
790 ret = ads131m_reset(priv, rstc);
791 if (ret < 0)
792 return ret;
793
794 /*
795 * Configure CLOCK register (0x03) based on DT properties.
796 * This register only needs configuration for 32-pin (M06/M08)
797 * variants, as the configurable bits (XTAL_DIS, EXTREF_EN)
798 * are reserved on 20-pin (M02/M03/M04) variants.
799 */
800 if (priv->config->supports_xtal || priv->config->supports_extref) {
801 u16 clk_set = 0;
802
803 if (priv->config->supports_xtal && !is_xtal)
804 clk_set |= ADS131M_CLOCK_XTAL_DIS;
805
806 if (priv->config->supports_extref && priv->use_external_ref)
807 clk_set |= ADS131M_CLOCK_EXTREF_EN;
808
809 ret = ads131m_rmw_reg(priv, ADS131M_REG_CLOCK,
810 ADS131M_CLOCK_EXTREF_EN | ADS131M_CLOCK_XTAL_DIS,
811 clk_set);
812 if (ret < 0)
813 return dev_err_probe(dev, ret, "Failed to configure CLOCK register\n");
814 }
815
816 /*
817 * The RESET command sets all registers to default, which means:
818 * 1. The RESET bit (Bit 10) in MODE is set to '1'.
819 * 2. The CRC_TYPE bit (Bit 11) in MODE is '0' (CCITT).
820 * 3. The RX_CRC_EN bit (Bit 12) in MODE is '0' (Disabled).
821 *
822 * We must:
823 * 1. Clear the RESET bit.
824 * 2. Enable Input CRC (RX_CRC_EN).
825 * 3. Explicitly clear the ANSI CRC bit (for certainty).
826 */
827 mode_clear = ADS131M_MODE_CRC_TYPE_ANSI | ADS131M_MODE_RESET_FLAG;
828 mode_set = ADS131M_MODE_RX_CRC_EN;
829
830 ret = ads131m_rmw_reg(priv, ADS131M_REG_MODE, mode_clear, mode_set);
831 if (ret < 0)
832 return dev_err_probe(dev, ret, "Failed to configure MODE register\n");
833
834 return 0;
835 }
836
837 /**
838 * ads131m_parse_clock - enable clock and detect "xtal" selection
839 * @priv: Device private data structure.
840 * @is_xtal: result flag (true if "xtal", false if default "clkin")
841 *
842 * Return: 0 on success, or a negative error code.
843 */
ads131m_parse_clock(struct ads131m_priv * priv,bool * is_xtal)844 static int ads131m_parse_clock(struct ads131m_priv *priv, bool *is_xtal)
845 {
846 struct device *dev = &priv->spi->dev;
847 struct clk *clk;
848 int ret;
849
850 clk = devm_clk_get_enabled(dev, NULL);
851 if (IS_ERR_OR_NULL(clk)) {
852 if (IS_ERR(clk))
853 ret = PTR_ERR(clk);
854 else
855 ret = -ENODEV;
856
857 return dev_err_probe(dev, ret, "clk get enabled failed\n");
858 }
859
860 ret = device_property_match_string(dev, "clock-names", "xtal");
861 if (ret > 0)
862 return dev_err_probe(dev, -EINVAL,
863 "'xtal' must be the only or first clock name");
864
865 if (ret < 0 && ret != -ENODATA)
866 return dev_err_probe(dev, ret,
867 "failed to read 'clock-names' property");
868
869 if (ret == 0 && !priv->config->supports_xtal)
870 return dev_err_probe(dev, -EINVAL,
871 "'xtal' clock not supported on this device");
872
873 *is_xtal = !ret;
874
875 return 0;
876 }
877
ads131m_probe(struct spi_device * spi)878 static int ads131m_probe(struct spi_device *spi)
879 {
880 const struct ads131m_configuration *config;
881 struct device *dev = &spi->dev;
882 struct reset_control *rstc;
883 struct iio_dev *indio_dev;
884 struct ads131m_priv *priv;
885 bool is_xtal;
886 int ret;
887
888 indio_dev = devm_iio_device_alloc(dev, sizeof(*priv));
889 if (!indio_dev)
890 return -ENOMEM;
891
892 priv = iio_priv(indio_dev);
893 priv->indio_dev = indio_dev;
894 priv->spi = spi;
895
896 indio_dev->modes = INDIO_DIRECT_MODE;
897 indio_dev->info = &ads131m_info;
898
899 config = spi_get_device_match_data(spi);
900
901 priv->config = config;
902 indio_dev->name = config->name;
903 indio_dev->channels = config->channels;
904 indio_dev->num_channels = config->num_channels;
905
906 rstc = devm_reset_control_get_optional_exclusive(dev, NULL);
907 if (IS_ERR(rstc))
908 return dev_err_probe(dev, PTR_ERR(rstc),
909 "Failed to get reset controller\n");
910
911 ret = devm_mutex_init(dev, &priv->lock);
912 if (ret < 0)
913 return ret;
914
915 ret = ads131m_prepare_message(priv);
916 if (ret < 0)
917 return ret;
918
919 ret = ads131m_power_init(priv);
920 if (ret < 0)
921 return ret;
922
923 /* Power must be applied and stable before the clock is enabled. */
924 ret = ads131m_parse_clock(priv, &is_xtal);
925 if (ret < 0)
926 return ret;
927
928 ret = ads131m_hw_init(priv, rstc, is_xtal);
929 if (ret < 0)
930 return ret;
931
932 return devm_iio_device_register(dev, indio_dev);
933 }
934
935 static const struct of_device_id ads131m_of_match[] = {
936 { .compatible = "ti,ads131m02", .data = &ads131m02_config },
937 { .compatible = "ti,ads131m03", .data = &ads131m03_config },
938 { .compatible = "ti,ads131m04", .data = &ads131m04_config },
939 { .compatible = "ti,ads131m06", .data = &ads131m06_config },
940 { .compatible = "ti,ads131m08", .data = &ads131m08_config },
941 { }
942 };
943 MODULE_DEVICE_TABLE(of, ads131m_of_match);
944
945 static const struct spi_device_id ads131m_id[] = {
946 { .name = "ads131m02", .driver_data = (kernel_ulong_t)&ads131m02_config },
947 { .name = "ads131m03", .driver_data = (kernel_ulong_t)&ads131m03_config },
948 { .name = "ads131m04", .driver_data = (kernel_ulong_t)&ads131m04_config },
949 { .name = "ads131m06", .driver_data = (kernel_ulong_t)&ads131m06_config },
950 { .name = "ads131m08", .driver_data = (kernel_ulong_t)&ads131m08_config },
951 { }
952 };
953 MODULE_DEVICE_TABLE(spi, ads131m_id);
954
955 static struct spi_driver ads131m_driver = {
956 .driver = {
957 .name = "ads131m02",
958 .of_match_table = ads131m_of_match,
959 },
960 .probe = ads131m_probe,
961 .id_table = ads131m_id,
962 };
963 module_spi_driver(ads131m_driver);
964
965 MODULE_AUTHOR("David Jander <david@protonic.nl>");
966 MODULE_DESCRIPTION("Texas Instruments ADS131M02 ADC driver");
967 MODULE_LICENSE("GPL");
968