path: root/include/linux/regmap.h

/* SPDX-License-Identifier: GPL-2.0-only */
#ifndef __LINUX_REGMAP_H
#define __LINUX_REGMAP_H

/*
 * Register map access API
 *
 * Copyright 2011 Wolfson Microelectronics plc
 *
 * Author: Mark Brown <broonie@opensource.wolfsonmicro.com>
 */

#include <linux/list.h>
#include <linux/rbtree.h>
#include <linux/ktime.h>
#include <linux/delay.h>
#include <linux/err.h>
#include <linux/bug.h>
#include <linux/lockdep.h>

struct module;
struct clk;
struct device;
struct i2c_client;
struct i3c_device;
struct irq_domain;
struct slim_device;
struct spi_device;
struct spmi_device;
struct regmap;
struct regmap_range_cfg;
struct regmap_field;
struct snd_ac97;
struct sdw_slave;

/* An enum of all the supported cache types */
enum regcache_type {
	REGCACHE_NONE,
	REGCACHE_RBTREE,
	REGCACHE_COMPRESSED,
	REGCACHE_FLAT,
};

/**
 * struct reg_default - Default value for a register.
 *
 * @reg: Register address.
 * @def: Register default value.
 *
 * We use an array of structs rather than a simple array as many modern devices
 * have very sparse register maps.
 */
struct reg_default {
	unsigned int reg;
	unsigned int def;
};

/**
 * struct reg_sequence - An individual write from a sequence of writes.
 *
 * @reg: Register address.
 * @def: Register value.
 * @delay_us: Delay to be applied after the register write in microseconds
 *
 * Register/value pairs for sequences of writes with an optional delay in
 * microseconds to be applied after each write.
 */
struct reg_sequence {
	unsigned int reg;
	unsigned int def;
	unsigned int delay_us;
};

#define	regmap_update_bits(map, reg, mask, val) \
	regmap_update_bits_base(map, reg, mask, val, NULL, false, false)
#define	regmap_update_bits_async(map, reg, mask, val)\
	regmap_update_bits_base(map, reg, mask, val, NULL, true, false)
#define	regmap_update_bits_check(map, reg, mask, val, change)\
	regmap_update_bits_base(map, reg, mask, val, change, false, false)
#define	regmap_update_bits_check_async(map, reg, mask, val, change)\
	regmap_update_bits_base(map, reg, mask, val, change, true, false)

#define	regmap_write_bits(map, reg, mask, val) \
	regmap_update_bits_base(map, reg, mask, val, NULL, false, true)

#define	regmap_field_write(field, val) \
	regmap_field_update_bits_base(field, ~0, val, NULL, false, false)
#define	regmap_field_force_write(field, val) \
	regmap_field_update_bits_base(field, ~0, val, NULL, false, true)
#define	regmap_field_update_bits(field, mask, val)\
	regmap_field_update_bits_base(field, mask, val, NULL, false, false)
#define	regmap_field_force_update_bits(field, mask, val) \
	regmap_field_update_bits_base(field, mask, val, NULL, false, true)

#define	regmap_fields_write(field, id, val) \
	regmap_fields_update_bits_base(field, id, ~0, val, NULL, false, false)
#define	regmap_fields_force_write(field, id, val) \
	regmap_fields_update_bits_base(field, id, ~0, val, NULL, false, true)
#define	regmap_fields_update_bits(field, id, mask, val)\
	regmap_fields_update_bits_base(field, id, mask, val, NULL, false, false)
#define	regmap_fields_force_update_bits(field, id, mask, val) \
	regmap_fields_update_bits_base(field, id, mask, val, NULL, false, true)

/**
 * regmap_read_poll_timeout - Poll until a condition is met or a timeout occurs
 *
 * @map: Regmap to read from
 * @addr: Address to poll
 * @val: Unsigned integer variable to read the value into
 * @cond: Break condition (usually involving @val)
 * @sleep_us: Maximum time to sleep between reads in us (0
 *            tight-loops).  Should be less than ~20ms since usleep_range
 *            is used (see Documentation/timers/timers-howto.rst).
 * @timeout_us: Timeout in us, 0 means never timeout
 *
 * Returns 0 on success and -ETIMEDOUT upon a timeout or the regmap_read
 * error return value in case of a error read. In the two former cases,
 * the last read value at @addr is stored in @val. Must not be called
 * from atomic context if sleep_us or timeout_us are used.
 *
 * This is modelled after the readx_poll_timeout macros in linux/iopoll.h.
 */
#define regmap_read_poll_timeout(map, addr, val, cond, sleep_us, timeout_us) \
({ \
	u64 __timeout_us = (timeout_us); \
	unsigned long __sleep_us = (sleep_us); \
	ktime_t __timeout = ktime_add_us(ktime_get(), __timeout_us); \
	int __ret; \
	might_sleep_if(__sleep_us); \
	for (;;) { \
		__ret = regmap_read((map), (addr), &(val)); \
		if (__ret) \
			break; \
		if (cond) \
			break; \
		if ((__timeout_us) && \
		    ktime_compare(ktime_get(), __timeout) > 0) { \
			__ret = regmap_read((map), (addr), &(val)); \
			break; \
		} \
		if (__sleep_us) \
			usleep_range((__sleep_us >> 2) + 1, __sleep_us); \
	} \
	__ret ?: ((cond) ? 0 : -ETIMEDOUT); \
})

/**
 * regmap_field_read_poll_timeout - Poll until a condition is met or timeout
 *
 * @field: Regmap field to read from
 * @val: Unsigned integer variable to read the value into
 * @cond: Break condition (usually involving @val)
 * @sleep_us: Maximum time to sleep between reads in us (0
 *            tight-loops).  Should be less than ~20ms since usleep_range
 *            is used (see Documentation/timers/timers-howto.rst).
 * @tim