+/* SPDX-License-Identifier: GPL-2.0+ */
/*
* Copyright (c) 2015 Google, Inc
* Written by Simon Glass <sjg@chromium.org>
- *
- * SPDX-License-Identifier: GPL-2.0+
*/
#ifndef __REGMAP_H
#define __REGMAP_H
+#include <linux/delay.h>
+
+/**
+ * DOC: Overview
+ *
+ * Regmaps are an abstraction mechanism that allows device drivers to access
+ * register maps irrespective of the underlying bus architecture. This entails
+ * that for devices that support multiple busses (e.g. I2C and SPI for a GPIO
+ * expander chip) only one driver has to be written. This driver will
+ * instantiate a regmap with a backend depending on the bus the device is
+ * attached to, and use the regmap API to access the register map through that
+ * bus transparently.
+ *
+ * Read and write functions are supplied, which can read/write data of
+ * arbitrary length from/to the regmap.
+ *
+ * The endianness of regmap accesses is selectable for each map through device
+ * tree settings via the boolean "little-endian", "big-endian", and
+ * "native-endian" properties.
+ *
+ * Furthermore, the register map described by a regmap can be split into
+ * multiple disjoint areas called ranges. In this way, register maps with
+ * "holes", i.e. areas of addressable memory that are not part of the register
+ * map, can be accessed in a concise manner.
+ *
+ * Currently, only a bare "mem" backend for regmaps is supported, which
+ * accesses the register map as regular IO-mapped memory.
+ */
+
+/**
+ * enum regmap_size_t - Access sizes for regmap reads and writes
+ *
+ * @REGMAP_SIZE_8: 8-bit read/write access size
+ * @REGMAP_SIZE_16: 16-bit read/write access size
+ * @REGMAP_SIZE_32: 32-bit read/write access size
+ * @REGMAP_SIZE_64: 64-bit read/write access size
+ */
+enum regmap_size_t {
+ REGMAP_SIZE_8 = 1,
+ REGMAP_SIZE_16 = 2,
+ REGMAP_SIZE_32 = 4,
+ REGMAP_SIZE_64 = 8,
+};
+
+/**
+ * enum regmap_endianness_t - Endianness for regmap reads and writes
+ *
+ * @REGMAP_NATIVE_ENDIAN: Native endian read/write accesses
+ * @REGMAP_LITTLE_ENDIAN: Little endian read/write accesses
+ * @REGMAP_BIG_ENDIAN: Big endian read/write accesses
+ */
+enum regmap_endianness_t {
+ REGMAP_NATIVE_ENDIAN,
+ REGMAP_LITTLE_ENDIAN,
+ REGMAP_BIG_ENDIAN,
+};
+
/**
* struct regmap_range - a register map range
*
/**
* struct regmap - a way of accessing hardware/bus registers
*
- * @base: Base address of register map
- * @range_count: Number of ranges available within the map
- * @range: Pointer to the list of ranges, allocated if @range_count > 1
- * @base_range: If @range_count is <= 1, @range points here
+ * @range_count: Number of ranges available within the map
+ * @ranges: Array of ranges
*/
struct regmap {
- phys_addr_t base;
+ enum regmap_endianness_t endianness;
int range_count;
- struct regmap_range *range, base_range;
+ struct regmap_range ranges[0];
};
/*
* Interface to provide access to registers either through a direct memory
* bus or through a peripheral bus like I2C, SPI.
*/
+
+/**
+ * regmap_write() - Write a 32-bit value to a regmap
+ *
+ * @map: Regmap to write to
+ * @offset: Offset in the regmap to write to
+ * @val: Data to write to the regmap at the specified offset
+ *
+ * Note that this function will only write values of 32 bit width to the
+ * regmap; if the size of data to be read is different, the regmap_raw_write
+ * function can be used.
+ *
+ * Return: 0 if OK, -ve on error
+ */
int regmap_write(struct regmap *map, uint offset, uint val);
+
+/**
+ * regmap_read() - Read a 32-bit value from a regmap
+ *
+ * @map: Regmap to read from
+ * @offset: Offset in the regmap to read from
+ * @valp: Pointer to the buffer to receive the data read from the regmap
+ * at the specified offset
+ *
+ * Note that this function will only read values of 32 bit width from the
+ * regmap; if the size of data to be read is different, the regmap_raw_read
+ * function can be used.
+ *
+ * Return: 0 if OK, -ve on error
+ */
int regmap_read(struct regmap *map, uint offset, uint *valp);
-#define regmap_write32(map, ptr, member, val) \
- regmap_write(map, (uint32_t *)(ptr)->member - (uint32_t *)(ptr), val)
+/**
+ * regmap_raw_write() - Write a value of specified length to a regmap
+ *
+ * @map: Regmap to write to
+ * @offset: Offset in the regmap to write to
+ * @val: Value to write to the regmap at the specified offset
+ * @val_len: Length of the data to be written to the regmap
+ *
+ * Note that this function will, as opposed to regmap_write, write data of
+ * arbitrary length to the regmap, and not just 32-bit values, and is thus a
+ * generalized version of regmap_write.
+ *
+ * Return: 0 if OK, -ve on error
+ */
+int regmap_raw_write(struct regmap *map, uint offset, const void *val,
+ size_t val_len);
-#define regmap_read32(map, ptr, member, valp) \
- regmap_read(map, (uint32_t *)(ptr)->member - (uint32_t *)(ptr), valp)
+/**
+ * regmap_raw_read() - Read a value of specified length from a regmap
+ *
+ * @map: Regmap to read from
+ * @offset: Offset in the regmap to read from
+ * @valp: Pointer to the buffer to receive the data read from the regmap
+ * at the specified offset
+ * @val_len: Length of the data to be read from the regmap
+ *
+ * Note that this function will, as opposed to regmap_read, read data of
+ * arbitrary length from the regmap, and not just 32-bit values, and is thus a
+ * generalized version of regmap_read.
+ *
+ * Return: 0 if OK, -ve on error
+ */
+int regmap_raw_read(struct regmap *map, uint offset, void *valp,
+ size_t val_len);
/**
- * regmap_init_mem() - Set up a new register map that uses memory access
+ * regmap_raw_write_range() - Write a value of specified length to a range of a
+ * regmap
*
- * Use regmap_uninit() to free it.
+ * @map: Regmap to write to
+ * @range_num: Number of the range in the regmap to write to
+ * @offset: Offset in the regmap to write to
+ * @val: Value to write to the regmap at the specified offset
+ * @val_len: Length of the data to be written to the regmap
*
- * @dev: Device that uses this map
- * @mapp: Returns allocated map
+ * Return: 0 if OK, -ve on error
*/
-int regmap_init_mem(struct udevice *dev, struct regmap **mapp);
+int regmap_raw_write_range(struct regmap *map, uint range_num, uint offset,
+ const void *val, size_t val_len);
/**
- * regmap_init_mem_platdata() - Set up a new memory register map for of-platdata
+ * regmap_raw_read_range() - Read a value of specified length from a range of a
+ * regmap
*
- * This creates a new regmap with a list of regions passed in, rather than
- * using the device tree. It only supports 32-bit machines.
+ * @map: Regmap to read from
+ * @range_num: Number of the range in the regmap to write to
+ * @offset: Offset in the regmap to read from
+ * @valp: Pointer to the buffer to receive the data read from the regmap
+ * at the specified offset
+ * @val_len: Length of the data to be read from the regmap
+ *
+ * Return: 0 if OK, -ve on error
+ */
+int regmap_raw_read_range(struct regmap *map, uint range_num, uint offset,
+ void *valp, size_t val_len);
+
+/**
+ * regmap_range_set() - Set a value in a regmap range described by a struct
+ * @map: Regmap in which a value should be set
+ * @range: Range of the regmap in which a value should be set
+ * @type: Structure type that describes the memory layout of the regmap range
+ * @member: Member of the describing structure that should be set in the regmap
+ * range
+ * @val: Value which should be written to the regmap range
+ */
+#define regmap_range_set(map, range, type, member, val) \
+ do { \
+ typeof(((type *)0)->member) __tmp = val; \
+ regmap_raw_write_range(map, range, offsetof(type, member), \
+ &__tmp, sizeof(((type *)0)->member)); \
+ } while (0)
+
+/**
+ * regmap_set() - Set a value in a regmap described by a struct
+ * @map: Regmap in which a value should be set
+ * @type: Structure type that describes the memory layout of the regmap
+ * @member: Member of the describing structure that should be set in the regmap
+ * @val: Value which should be written to the regmap
+ */
+#define regmap_set(map, type, member, val) \
+ regmap_range_set(map, 0, type, member, val)
+
+/**
+ * regmap_range_get() - Get a value from a regmap range described by a struct
+ * @map: Regmap from which a value should be read
+ * @range: Range of the regmap from which a value should be read
+ * @type: Structure type that describes the memory layout of the regmap
+ * range
+ * @member: Member of the describing structure that should be read in the
+ * regmap range
+ * @valp: Variable that receives the value read from the regmap range
+ */
+#define regmap_range_get(map, range, type, member, valp) \
+ regmap_raw_read_range(map, range, offsetof(type, member), \
+ (void *)valp, sizeof(((type *)0)->member))
+
+/**
+ * regmap_get() - Get a value from a regmap described by a struct
+ * @map: Regmap from which a value should be read
+ * @type: Structure type that describes the memory layout of the regmap
+ * range
+ * @member: Member of the describing structure that should be read in the
+ * regmap
+ * @valp: Variable that receives the value read from the regmap
+ */
+#define regmap_get(map, type, member, valp) \
+ regmap_range_get(map, 0, type, member, valp)
+
+/**
+ * regmap_read_poll_timeout - Poll until a condition is met or a timeout occurs
+ *
+ * @map: Regmap to read from
+ * @addr: Offset 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).
+ * @timeout_ms: Timeout in ms, 0 means never timeout
+ * @test_add_time: Used for sandbox testing - amount of time to add after
+ * starting the loop (0 if not testing)
+ *
+ * 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 regmap_read_poll_timeout macros in linux but
+ * with millisecond timeout.
+ *
+ * The _test version is for sandbox testing only. Do not use this in normal
+ * code as it advances the timer.
+ */
+#define regmap_read_poll_timeout_test(map, addr, val, cond, sleep_us, \
+ timeout_ms, test_add_time) \
+({ \
+ unsigned long __start = get_timer(0); \
+ int __ret; \
+ for (;;) { \
+ __ret = regmap_read((map), (addr), &(val)); \
+ if (__ret) \
+ break; \
+ if (cond) \
+ break; \
+ if (IS_ENABLED(CONFIG_SANDBOX) && test_add_time) \
+ timer_test_add_offset(test_add_time); \
+ if ((timeout_ms) && get_timer(__start) > (timeout_ms)) { \
+ __ret = regmap_read((map), (addr), &(val)); \
+ break; \
+ } \
+ if ((sleep_us)) \
+ udelay((sleep_us)); \
+ } \
+ __ret ?: ((cond) ? 0 : -ETIMEDOUT); \
+})
+
+#define regmap_read_poll_timeout(map, addr, val, cond, sleep_us, timeout_ms) \
+ regmap_read_poll_timeout_test(map, addr, val, cond, sleep_us, \
+ timeout_ms, 0) \
+
+/**
+ * regmap_update_bits() - Perform a read/modify/write using a mask
+ *
+ * @map: The map returned by regmap_init_mem*()
+ * @offset: Offset of the memory
+ * @mask: Mask to apply to the read value
+ * @val: Value to OR with the read value after masking. Note that any
+ * bits set in @val which are not set in @mask are ignored
+ * Return: 0 if OK, -ve on error
+ */
+int regmap_update_bits(struct regmap *map, uint offset, uint mask, uint val);
+
+/**
+ * regmap_init_mem() - Set up a new register map that uses memory access
+ *
+ * @node: Device node that uses this map
+ * @mapp: Returns allocated map
+ * Return: 0 if OK, -ve on error
*
* Use regmap_uninit() to free it.
+ */
+int regmap_init_mem(ofnode node, struct regmap **mapp);
+
+/**
+ * regmap_init_mem_platdata() - Set up a new memory register map for
+ * of-platdata
*
* @dev: Device that uses this map
* @reg: List of address, size pairs
* @count: Number of pairs (e.g. 1 if the regmap has a single entry)
* @mapp: Returns allocated map
+ * Return: 0 if OK, -ve on error
+ *
+ * This creates a new regmap with a list of regions passed in, rather than
+ * using the device tree. It only supports 32-bit machines.
+ *
+ * Use regmap_uninit() to free it.
+ *
*/
int regmap_init_mem_platdata(struct udevice *dev, fdt_val_t *reg, int count,
struct regmap **mapp);
+int regmap_init_mem_index(ofnode node, struct regmap **mapp, int index);
+
/**
* regmap_get_range() - Obtain the base memory address of a regmap range
*
* @map: Regmap to query
* @range_num: Range to look up
+ * Return: Pointer to the range in question if OK, NULL on error
*/
void *regmap_get_range(struct regmap *map, unsigned int range_num);
/**
* regmap_uninit() - free a previously inited regmap
+ *
+ * @map: Regmap to free
+ * Return: 0 if OK, -ve on error
*/
int regmap_uninit(struct regmap *map);
projects / oweals / u-boot.git / blobdiff