path: root/drivers/iio/adc/ti-ads131m02.c

// SPDX-License-Identifier: GPL-2.0-only
/*
 * Driver for Texas Instruments ADS131M02 family ADC chips.
 *
 * Copyright (C) 2024 Protonic Holland
 * Copyright (C) 2025 Oleksij Rempel <kernel@pengutronix.de>, Pengutronix
 *
 * Primary Datasheet Reference (used for citations):
 * ADS131M08 8-Channel, Simultaneously-Sampling, 24-Bit, Delta-Sigma ADC
 * Document SBAS950B, Revised February 2021
 * https://www.ti.com/lit/ds/symlink/ads131m08.pdf
 */

#include <linux/array_size.h>
#include <linux/bitfield.h>
#include <linux/bitops.h>
#include <linux/cleanup.h>
#include <linux/clk.h>
#include <linux/crc-itu-t.h>
#include <linux/delay.h>
#include <linux/dev_printk.h>
#include <linux/device/devres.h>
#include <linux/err.h>
#include <linux/iio/iio.h>
#include <linux/lockdep.h>
#include <linux/mod_devicetable.h>
#include <linux/module.h>
#include <linux/mutex.h>
#include <linux/regulator/consumer.h>
#include <linux/reset.h>
#include <linux/spi/spi.h>
#include <linux/string.h>
#include <linux/types.h>
#include <linux/unaligned.h>

/* Max channels supported by the largest variant in the family (ADS131M08) */
#define ADS131M_MAX_CHANNELS		8

/* Section 6.7, t_REGACQ (min time after reset) is 5us */
#define ADS131M_RESET_DELAY_US		5

#define ADS131M_WORD_SIZE_BYTES		3
#define ADS131M_RESPONSE_WORDS		1
#define ADS131M_CRC_WORDS		1

/*
 * SPI Frame word count calculation.
 * Frame = N channel words + 1 response word + 1 CRC word.
 * Word size depends on WLENGTH bits in MODE register (Default 24-bit).
 */
#define ADS131M_FRAME_WORDS(nch) \
	((nch) + ADS131M_RESPONSE_WORDS + ADS131M_CRC_WORDS)

/*
 * SPI Frame byte size calculation.
 * Assumes default word size of 24 bits (3 bytes).
 */
#define ADS131M_FRAME_BYTES(nch) \
	(ADS131M_FRAME_WORDS(nch) * ADS131M_WORD_SIZE_BYTES)

/*
 * Index calculation for the start byte of channel 'x' data within the RX buffer.
 * Assumes 24-bit words (3 bytes per word).
 * The received frame starts with the response word (e.g., STATUS register
 * content when NULL command was sent), followed by data for channels 0 to N-1,
 * and finally the output CRC word.
 * Response = index 0..2, Chan0 = index 3..5, Chan1 = index 6..8, ...
 * Index for ChanX = 3 (response) + x * 3 (channel data size).
 */
#define ADS131M_CHANNEL_INDEX(x) \
	((x) * ADS131M_WORD_SIZE_BYTES + ADS131M_WORD_SIZE_BYTES)

#define ADS131M_CMD_NULL		0x0000
#define ADS131M_CMD_RESET		0x0011

#define ADS131M_CMD_ADDR_MASK		GENMASK(11, 7)
#define ADS131M_CMD_NUM_MASK		GENMASK(6, 0)

#define ADS131M_CMD_RREG_OP		0xa000
#define ADS131M_CMD_WREG_OP		0x6000

#define ADS131M_CMD_RREG(a, n) \
	(ADS131M_CMD_RREG_OP | \
	 FIELD_PREP(ADS131M_CMD_ADDR_MASK, a) | \
	 FIELD_PREP(ADS131M_CMD_NUM_MASK, n))
#define ADS131M_CMD_WREG(a, n) \
	(ADS131M_CMD_WREG_OP | \
	 FIELD_PREP(ADS131M_CMD_ADDR_MASK, a) | \
	 FIELD_PREP(ADS131M_CMD_NUM_MASK, n))

/*  STATUS Register (0x01h) bit definitions */
#define ADS131M_STATUS_CRC_ERR		BIT(12) /* Input CRC error */

#define ADS131M_REG_MODE		0x02
#define ADS131M_MODE_RX_CRC_EN		BIT(12) /* Enable Input CRC */
#define ADS131M_MODE_CRC_TYPE_ANSI	BIT(11) /* 0 = CCITT, 1 = ANSI */
#define ADS131M_MODE_RESET_FLAG		BIT(10)

#define ADS131M_REG_CLOCK		0x03
#define ADS131M_CLOCK_XTAL_DIS		BIT(7)
#define ADS131M_CLOCK_EXTREF_EN		BIT(6)

/* 1.2V internal reference, in millivolts, for IIO_VAL_FRACTIONAL_LOG2 */
#define ADS131M_VREF_INTERNAL_mV	1200
/* 24-bit resolution */
#define ADS131M_RESOLUTION_BITS		24
/* Signed data uses (RESOLUTION_BITS - 1) magnitude bits */
#define ADS131M_CODE_BITS              (ADS131M_RESOLUTION_BITS - 1)

/* External ref FSR = Vref * 0.96 */
#define ADS131M_EXTREF_SCALE_NUM	96
#define ADS131M_EXTREF_SCALE_DEN	100

struct ads131m_configuration {
	const struct iio_chan_spec *channels;
	const char *name;
	u16 reset_ack;
	u8 num_channels;
	u8 supports_extref:1;
	u8 supports_xtal:1;
};

struct ads131m_priv {
	struct iio_dev *indio_dev;
	struct spi_device *spi;
	const struct ads131m_configuration *config;

	bool use_external_ref;
	int scale_val;
	int scale_val2;

	struct spi_transfer xfer;
	struct spi_message msg;

	/*
	 * Protects the shared tx_buffer and rx_buffer. More importantly,
	 * this serializes all SPI communication to ensure the atomicity
	 * of multi-cycle command sequences (like WREG, RREG, or RESET).
	 */
	struct mutex lock;

	/* DMA-safe buffers should be placed at the end of the struct. */
	u8 tx_buffer[ADS131M_FRAME_BYTES(ADS131M_MAX_CHANNELS)]
		__aligned(IIO_DMA_MINALIGN);
	u8 rx_buffer[ADS131M_FRAME_BYTES(ADS131M_MAX_CHANNELS)];
};

/**
 * ads131m_tx_frame_unlocked - Sends a command frame with Input CRC
 * @priv: Device private data structure.
 * @command: The 16-bit command to send (e.g., NULL, RREG, RESET).
 *
 * This function sends a command in Word 0, and its calculated 16-bit
 * CRC in Word 1, as required when Input CRC is enabled.
 *
 * Return: 0 on success, or a negative error code.
 */
static int ads131m_tx_frame_unlocked(struct ads131m_priv *priv, u32 command)
{
	struct iio_dev *indio_dev = priv->indio_dev;
	u16 crc;

	lockdep_assert_held(&priv->lock);

	memset(priv->tx_buffer, 0, ADS131M_FRAME_BYTES(indio_dev->num_channels));

	/* Word 0: 16-bit command, MSB-aligned in 24-bit word */
	put_unaligned_be16(command, &priv->tx_buffer[0]);

	/* Word 1: Input CRC. Calculated over the 3 bytes of Word 0. */
	crc = crc_itu_t(0xffff, priv->tx_buffer, 3);
	put_unaligned_be16(crc, &priv->tx_buffer[3]);

	return spi_sync(priv->spi, &priv->msg);
}

/**
 * ads131m_rx_frame_unlocked - Receives a full SPI data frame.
 * @priv: Device private data structure.
 *
 * This function sends a NULL command (with its CRC) to clock out a
 * full SPI frame from the device (e.g., response + channel data + CRC).
 *
 * Return: 0 on success, or a negative error code.
 */
static int ads131m_rx_frame_unlocked(struct ads131m_priv *priv)
{
	return ads131m_tx_frame_unlocked(priv, ADS131M_CMD_NULL);
}

/**
 * ads131m_check_status_crc_err - Checks for an Input CRC error.
 * @priv: Device private data structure.
 *
 * Sends a NULL command to fetch the STATUS register and checks the
 * CRC_ERR bit. This is used to verify the integrity of the previous
 * command (like RREG or WREG).
 *
 * Return: 0 on success, -EIO if CRC_ERR bit is set.
 */
static int ads131m_check_status_crc_err(struct ads131m_priv *priv)
{
	struct device *dev = &priv->spi->dev;
	u16 status;
	int ret;

	lockdep_assert_held(&priv->lock);

	ret = ads131m_rx_frame_unlocked(priv);
	if (ret < 0) {
		dev_err_ratelimited(dev,
				    "SPI error on STATUS read for CRC check\n");
		return ret;
	}

	status = get_unaligned_be16(&priv->rx_buffer[0]);
	if (status & ADS131M_STATUS_CRC_ERR) {
		dev_err_ratelimited(dev,
				    "Input CRC error reported in STATUS = 0x%04x\n",
				    status);
		return -EIO;
	}

	return 0;
}

/**
 * ads131m_write_reg_unlocked - Writes a single register and verifies the ACK.
 * @priv: Device private data structure.
 * @reg: The 8-bit register address.
 * @val: The 16-bit value to write.
 *
 * This function performs the full 3-cycle WREG operation with Input CRC:
 * 1. (Cycle 1) Sends WREG command, data, and its calculated CRC.
 * 2. (Cycle 2) Sends NULL+CRC to retrieve the response from Cycle 1.
 * 3. Verifies the response is the correct ACK for the WREG.
 * 4. (Cycle 3) Sends NULL+CRC to retrieve STATUS and check for CRC_ERR.
 *
 * Return: 0 on success, or a negative error code.
 */
static int ads131m_write_reg_unlocked(struct ads131m_priv *priv, u8 reg, u16 val)
{
	struct iio_dev *indio_dev = priv->indio_dev;
	u16 command, expected_ac