1 /* SPDX-License-Identifier: GPL-2.0+ */
3 * Copyright (c) 2015 Google, Inc
4 * Written by Simon Glass <sjg@chromium.org>
10 #include <linux/delay.h>
15 * Regmaps are an abstraction mechanism that allows device drivers to access
16 * register maps irrespective of the underlying bus architecture. This entails
17 * that for devices that support multiple busses (e.g. I2C and SPI for a GPIO
18 * expander chip) only one driver has to be written. This driver will
19 * instantiate a regmap with a backend depending on the bus the device is
20 * attached to, and use the regmap API to access the register map through that
23 * Read and write functions are supplied, which can read/write data of
24 * arbitrary length from/to the regmap.
26 * The endianness of regmap accesses is selectable for each map through device
27 * tree settings via the boolean "little-endian", "big-endian", and
28 * "native-endian" properties.
30 * Furthermore, the register map described by a regmap can be split into
31 * multiple disjoint areas called ranges. In this way, register maps with
32 * "holes", i.e. areas of addressable memory that are not part of the register
33 * map, can be accessed in a concise manner.
35 * Currently, only a bare "mem" backend for regmaps is supported, which
36 * accesses the register map as regular IO-mapped memory.
40 * enum regmap_size_t - Access sizes for regmap reads and writes
42 * @REGMAP_SIZE_8: 8-bit read/write access size
43 * @REGMAP_SIZE_16: 16-bit read/write access size
44 * @REGMAP_SIZE_32: 32-bit read/write access size
45 * @REGMAP_SIZE_64: 64-bit read/write access size
55 * enum regmap_endianness_t - Endianness for regmap reads and writes
57 * @REGMAP_NATIVE_ENDIAN: Native endian read/write accesses
58 * @REGMAP_LITTLE_ENDIAN: Little endian read/write accesses
59 * @REGMAP_BIG_ENDIAN: Big endian read/write accesses
61 enum regmap_endianness_t {
68 * struct regmap_range - a register map range
70 * @start: Start address
71 * @size: Size in bytes
82 * struct regmap - a way of accessing hardware/bus registers
84 * @range_count: Number of ranges available within the map
85 * @ranges: Array of ranges
88 enum regmap_endianness_t endianness;
90 struct regmap_range ranges[0];
94 * Interface to provide access to registers either through a direct memory
95 * bus or through a peripheral bus like I2C, SPI.
99 * regmap_write() - Write a 32-bit value to a regmap
101 * @map: Regmap to write to
102 * @offset: Offset in the regmap to write to
103 * @val: Data to write to the regmap at the specified offset
105 * Note that this function will only write values of 32 bit width to the
106 * regmap; if the size of data to be read is different, the regmap_raw_write
107 * function can be used.
109 * Return: 0 if OK, -ve on error
111 int regmap_write(struct regmap *map, uint offset, uint val);
114 * regmap_read() - Read a 32-bit value from a regmap
116 * @map: Regmap to read from
117 * @offset: Offset in the regmap to read from
118 * @valp: Pointer to the buffer to receive the data read from the regmap
119 * at the specified offset
121 * Note that this function will only read values of 32 bit width from the
122 * regmap; if the size of data to be read is different, the regmap_raw_read
123 * function can be used.
125 * Return: 0 if OK, -ve on error
127 int regmap_read(struct regmap *map, uint offset, uint *valp);
130 * regmap_raw_write() - Write a value of specified length to a regmap
132 * @map: Regmap to write to
133 * @offset: Offset in the regmap to write to
134 * @val: Value to write to the regmap at the specified offset
135 * @val_len: Length of the data to be written to the regmap
137 * Note that this function will, as opposed to regmap_write, write data of
138 * arbitrary length to the regmap, and not just 32-bit values, and is thus a
139 * generalized version of regmap_write.
141 * Return: 0 if OK, -ve on error
143 int regmap_raw_write(struct regmap *map, uint offset, const void *val,
147 * regmap_raw_read() - Read a value of specified length from a regmap
149 * @map: Regmap to read from
150 * @offset: Offset in the regmap to read from
151 * @valp: Pointer to the buffer to receive the data read from the regmap
152 * at the specified offset
153 * @val_len: Length of the data to be read from the regmap
155 * Note that this function will, as opposed to regmap_read, read data of
156 * arbitrary length from the regmap, and not just 32-bit values, and is thus a
157 * generalized version of regmap_read.
159 * Return: 0 if OK, -ve on error
161 int regmap_raw_read(struct regmap *map, uint offset, void *valp,
165 * regmap_raw_write_range() - Write a value of specified length to a range of a
168 * @map: Regmap to write to
169 * @range_num: Number of the range in the regmap to write to
170 * @offset: Offset in the regmap to write to
171 * @val: Value to write to the regmap at the specified offset
172 * @val_len: Length of the data to be written to the regmap
174 * Return: 0 if OK, -ve on error
176 int regmap_raw_write_range(struct regmap *map, uint range_num, uint offset,
177 const void *val, size_t val_len);
180 * regmap_raw_read_range() - Read a value of specified length from a range of a
183 * @map: Regmap to read from
184 * @range_num: Number of the range in the regmap to write to
185 * @offset: Offset in the regmap to read from
186 * @valp: Pointer to the buffer to receive the data read from the regmap
187 * at the specified offset
188 * @val_len: Length of the data to be read from the regmap
190 * Return: 0 if OK, -ve on error
192 int regmap_raw_read_range(struct regmap *map, uint range_num, uint offset,
193 void *valp, size_t val_len);
196 * regmap_range_set() - Set a value in a regmap range described by a struct
197 * @map: Regmap in which a value should be set
198 * @range: Range of the regmap in which a value should be set
199 * @type: Structure type that describes the memory layout of the regmap range
200 * @member: Member of the describing structure that should be set in the regmap
202 * @val: Value which should be written to the regmap range
204 #define regmap_range_set(map, range, type, member, val) \
206 typeof(((type *)0)->member) __tmp = val; \
207 regmap_raw_write_range(map, range, offsetof(type, member), \
208 &__tmp, sizeof(((type *)0)->member)); \
212 * regmap_set() - Set a value in a regmap described by a struct
213 * @map: Regmap in which a value should be set
214 * @type: Structure type that describes the memory layout of the regmap
215 * @member: Member of the describing structure that should be set in the regmap
216 * @val: Value which should be written to the regmap
218 #define regmap_set(map, type, member, val) \
219 regmap_range_set(map, 0, type, member, val)
222 * regmap_range_get() - Get a value from a regmap range described by a struct
223 * @map: Regmap from which a value should be read
224 * @range: Range of the regmap from which a value should be read
225 * @type: Structure type that describes the memory layout of the regmap
227 * @member: Member of the describing structure that should be read in the
229 * @valp: Variable that receives the value read from the regmap range
231 #define regmap_range_get(map, range, type, member, valp) \
232 regmap_raw_read_range(map, range, offsetof(type, member), \
233 (void *)valp, sizeof(((type *)0)->member))
236 * regmap_get() - Get a value from a regmap described by a struct
237 * @map: Regmap from which a value should be read
238 * @type: Structure type that describes the memory layout of the regmap
240 * @member: Member of the describing structure that should be read in the
242 * @valp: Variable that receives the value read from the regmap
244 #define regmap_get(map, type, member, valp) \
245 regmap_range_get(map, 0, type, member, valp)
248 * regmap_read_poll_timeout - Poll until a condition is met or a timeout occurs
250 * @map: Regmap to read from
251 * @addr: Offset to poll
252 * @val: Unsigned integer variable to read the value into
253 * @cond: Break condition (usually involving @val)
254 * @sleep_us: Maximum time to sleep between reads in us (0 tight-loops).
255 * @timeout_ms: Timeout in ms, 0 means never timeout
256 * @test_add_time: Used for sandbox testing - amount of time to add after
257 * starting the loop (0 if not testing)
259 * Returns 0 on success and -ETIMEDOUT upon a timeout or the regmap_read
260 * error return value in case of a error read. In the two former cases,
261 * the last read value at @addr is stored in @val. Must not be called
262 * from atomic context if sleep_us or timeout_us are used.
264 * This is modelled after the regmap_read_poll_timeout macros in linux but
265 * with millisecond timeout.
267 * The _test version is for sandbox testing only. Do not use this in normal
268 * code as it advances the timer.
270 #define regmap_read_poll_timeout_test(map, addr, val, cond, sleep_us, \
271 timeout_ms, test_add_time) \
273 unsigned long __start = get_timer(0); \
276 __ret = regmap_read((map), (addr), &(val)); \
281 if (IS_ENABLED(CONFIG_SANDBOX) && test_add_time) \
282 timer_test_add_offset(test_add_time); \
283 if ((timeout_ms) && get_timer(__start) > (timeout_ms)) { \
284 __ret = regmap_read((map), (addr), &(val)); \
288 udelay((sleep_us)); \
290 __ret ?: ((cond) ? 0 : -ETIMEDOUT); \
293 #define regmap_read_poll_timeout(map, addr, val, cond, sleep_us, timeout_ms) \
294 regmap_read_poll_timeout_test(map, addr, val, cond, sleep_us, \
298 * regmap_update_bits() - Perform a read/modify/write using a mask
300 * @map: The map returned by regmap_init_mem*()
301 * @offset: Offset of the memory
302 * @mask: Mask to apply to the read value
303 * @val: Value to OR with the read value after masking. Note that any
304 * bits set in @val which are not set in @mask are ignored
305 * Return: 0 if OK, -ve on error
307 int regmap_update_bits(struct regmap *map, uint offset, uint mask, uint val);
310 * regmap_init_mem() - Set up a new register map that uses memory access
312 * @node: Device node that uses this map
313 * @mapp: Returns allocated map
314 * Return: 0 if OK, -ve on error
316 * Use regmap_uninit() to free it.
318 int regmap_init_mem(ofnode node, struct regmap **mapp);
321 * regmap_init_mem_platdata() - Set up a new memory register map for
324 * @dev: Device that uses this map
325 * @reg: List of address, size pairs
326 * @count: Number of pairs (e.g. 1 if the regmap has a single entry)
327 * @mapp: Returns allocated map
328 * Return: 0 if OK, -ve on error
330 * This creates a new regmap with a list of regions passed in, rather than
331 * using the device tree. It only supports 32-bit machines.
333 * Use regmap_uninit() to free it.
336 int regmap_init_mem_platdata(struct udevice *dev, fdt_val_t *reg, int count,
337 struct regmap **mapp);
339 int regmap_init_mem_index(ofnode node, struct regmap **mapp, int index);
342 * devm_regmap_init() - Initialise register map (device managed)
344 * @dev: Device that will be interacted with
345 * @bus: Bus-specific callbacks to use with device (IGNORED)
346 * @bus_context: Data passed to bus-specific callbacks (IGNORED)
347 * @config: Configuration for register map (IGNORED)
349 * @Return a valid pointer to a struct regmap or a ERR_PTR() on error.
350 * The structure is automatically freed when the device is unbound
352 struct regmap *devm_regmap_init(struct udevice *dev,
353 const struct regmap_bus *bus,
355 const struct regmap_config *config);
357 * regmap_get_range() - Obtain the base memory address of a regmap range
359 * @map: Regmap to query
360 * @range_num: Range to look up
361 * Return: Pointer to the range in question if OK, NULL on error
363 void *regmap_get_range(struct regmap *map, unsigned int range_num);
366 * regmap_uninit() - free a previously inited regmap
368 * @map: Regmap to free
369 * Return: 0 if OK, -ve on error
371 int regmap_uninit(struct regmap *map);