blob: 7c8ad04759937900c4d0c01a7869e6b96048422a [file] [log] [blame]
Tom Rini83d290c2018-05-06 17:58:06 -04001/* SPDX-License-Identifier: GPL-2.0+ */
Simon Glass6f98b752015-06-23 15:38:42 -06002/*
3 * Copyright (c) 2015 Google, Inc
4 * Written by Simon Glass <sjg@chromium.org>
Simon Glass6f98b752015-06-23 15:38:42 -06005 */
6
7#ifndef __REGMAP_H
8#define __REGMAP_H
9
Simon Glassc05ed002020-05-10 11:40:11 -060010#include <linux/delay.h>
11
Simon Glass6f98b752015-06-23 15:38:42 -060012/**
Mario Sixa6d4b062018-10-15 09:24:15 +020013 * DOC: Overview
14 *
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
21 * bus transparently.
22 *
23 * Read and write functions are supplied, which can read/write data of
24 * arbitrary length from/to the regmap.
25 *
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.
29 *
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.
34 *
35 * Currently, only a bare "mem" backend for regmaps is supported, which
36 * accesses the register map as regular IO-mapped memory.
37 */
38
39/**
Mario Six84ff8f62018-10-15 09:24:10 +020040 * enum regmap_size_t - Access sizes for regmap reads and writes
41 *
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
46 */
47enum regmap_size_t {
48 REGMAP_SIZE_8 = 1,
49 REGMAP_SIZE_16 = 2,
50 REGMAP_SIZE_32 = 4,
51 REGMAP_SIZE_64 = 8,
52};
53
54/**
Mario Six9b77fe32018-10-15 09:24:14 +020055 * enum regmap_endianness_t - Endianness for regmap reads and writes
56 *
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
60 */
61enum regmap_endianness_t {
62 REGMAP_NATIVE_ENDIAN,
63 REGMAP_LITTLE_ENDIAN,
64 REGMAP_BIG_ENDIAN,
65};
66
67/**
Simon Glass6f98b752015-06-23 15:38:42 -060068 * struct regmap_range - a register map range
69 *
70 * @start: Start address
71 * @size: Size in bytes
72 */
73struct regmap_range {
74 ulong start;
75 ulong size;
76};
77
Jean-Jacques Hiblotffb22f62020-09-24 10:04:10 +053078struct regmap_bus;
Pratyush Yadav78aaedb2020-09-24 10:04:12 +053079
80/**
81 * struct regmap_config - Configure the behaviour of a regmap
82 *
83 * @width: Width of the read/write operations. Defaults to
84 * REGMAP_SIZE_32 if set to 0.
Pratyush Yadav7aa5ddf2020-09-24 10:04:13 +053085 * @reg_offset_shift Left shift the register offset by this value before
86 * performing read or write.
Pratyush Yadav78aaedb2020-09-24 10:04:12 +053087 */
88struct regmap_config {
89 enum regmap_size_t width;
Pratyush Yadav7aa5ddf2020-09-24 10:04:13 +053090 u32 reg_offset_shift;
Pratyush Yadav78aaedb2020-09-24 10:04:12 +053091};
Jean-Jacques Hiblotffb22f62020-09-24 10:04:10 +053092
Simon Glass6f98b752015-06-23 15:38:42 -060093/**
94 * struct regmap - a way of accessing hardware/bus registers
95 *
Pratyush Yadav78aaedb2020-09-24 10:04:12 +053096 * @width: Width of the read/write operations. Defaults to
97 * REGMAP_SIZE_32 if set to 0.
Pratyush Yadav7aa5ddf2020-09-24 10:04:13 +053098 * @reg_offset_shift Left shift the register offset by this value before
99 * performing read or write.
Mario Six604b6692018-10-04 09:00:41 +0200100 * @range_count: Number of ranges available within the map
101 * @ranges: Array of ranges
Simon Glass6f98b752015-06-23 15:38:42 -0600102 */
103struct regmap {
Mario Six9b77fe32018-10-15 09:24:14 +0200104 enum regmap_endianness_t endianness;
Pratyush Yadav78aaedb2020-09-24 10:04:12 +0530105 enum regmap_size_t width;
Pratyush Yadav7aa5ddf2020-09-24 10:04:13 +0530106 u32 reg_offset_shift;
Simon Glass6f98b752015-06-23 15:38:42 -0600107 int range_count;
Masahiro Yamada8c1de5e2018-04-19 12:14:01 +0900108 struct regmap_range ranges[0];
Simon Glass6f98b752015-06-23 15:38:42 -0600109};
110
111/*
112 * Interface to provide access to registers either through a direct memory
113 * bus or through a peripheral bus like I2C, SPI.
114 */
Mario Six604b6692018-10-04 09:00:41 +0200115
116/**
Pratyush Yadav78aaedb2020-09-24 10:04:12 +0530117 * regmap_write() - Write a value to a regmap
Mario Six604b6692018-10-04 09:00:41 +0200118 *
119 * @map: Regmap to write to
120 * @offset: Offset in the regmap to write to
121 * @val: Data to write to the regmap at the specified offset
122 *
123 * Return: 0 if OK, -ve on error
124 */
Simon Glass6f98b752015-06-23 15:38:42 -0600125int regmap_write(struct regmap *map, uint offset, uint val);
Mario Six604b6692018-10-04 09:00:41 +0200126
127/**
Pratyush Yadav78aaedb2020-09-24 10:04:12 +0530128 * regmap_read() - Read a value from a regmap
Mario Six604b6692018-10-04 09:00:41 +0200129 *
130 * @map: Regmap to read from
131 * @offset: Offset in the regmap to read from
132 * @valp: Pointer to the buffer to receive the data read from the regmap
133 * at the specified offset
134 *
135 * Return: 0 if OK, -ve on error
136 */
Simon Glass6f98b752015-06-23 15:38:42 -0600137int regmap_read(struct regmap *map, uint offset, uint *valp);
138
Mario Six84ff8f62018-10-15 09:24:10 +0200139/**
140 * regmap_raw_write() - Write a value of specified length to a regmap
141 *
142 * @map: Regmap to write to
143 * @offset: Offset in the regmap to write to
144 * @val: Value to write to the regmap at the specified offset
145 * @val_len: Length of the data to be written to the regmap
146 *
147 * Note that this function will, as opposed to regmap_write, write data of
Pratyush Yadav78aaedb2020-09-24 10:04:12 +0530148 * arbitrary length to the regmap, and not just the size configured in the
149 * regmap (defaults to 32-bit) and is thus a generalized version of
150 * regmap_write.
Mario Six84ff8f62018-10-15 09:24:10 +0200151 *
152 * Return: 0 if OK, -ve on error
153 */
154int regmap_raw_write(struct regmap *map, uint offset, const void *val,
155 size_t val_len);
156
157/**
158 * regmap_raw_read() - Read a value of specified length from a regmap
159 *
160 * @map: Regmap to read from
161 * @offset: Offset in the regmap to read from
162 * @valp: Pointer to the buffer to receive the data read from the regmap
163 * at the specified offset
164 * @val_len: Length of the data to be read from the regmap
165 *
166 * Note that this function will, as opposed to regmap_read, read data of
Pratyush Yadav78aaedb2020-09-24 10:04:12 +0530167 * arbitrary length from the regmap, and not just the size configured in the
168 * regmap (defaults to 32-bit) and is thus a generalized version of
169 * regmap_read.
Mario Six84ff8f62018-10-15 09:24:10 +0200170 *
171 * Return: 0 if OK, -ve on error
172 */
173int regmap_raw_read(struct regmap *map, uint offset, void *valp,
174 size_t val_len);
175
Mario Sixd5c7bd92018-10-15 09:24:11 +0200176/**
177 * regmap_raw_write_range() - Write a value of specified length to a range of a
178 * regmap
179 *
180 * @map: Regmap to write to
181 * @range_num: Number of the range in the regmap to write to
182 * @offset: Offset in the regmap to write to
183 * @val: Value to write to the regmap at the specified offset
184 * @val_len: Length of the data to be written to the regmap
185 *
186 * Return: 0 if OK, -ve on error
187 */
188int regmap_raw_write_range(struct regmap *map, uint range_num, uint offset,
189 const void *val, size_t val_len);
190
191/**
192 * regmap_raw_read_range() - Read a value of specified length from a range of a
193 * regmap
194 *
195 * @map: Regmap to read from
196 * @range_num: Number of the range in the regmap to write to
197 * @offset: Offset in the regmap to read from
198 * @valp: Pointer to the buffer to receive the data read from the regmap
199 * at the specified offset
200 * @val_len: Length of the data to be read from the regmap
201 *
202 * Return: 0 if OK, -ve on error
203 */
204int regmap_raw_read_range(struct regmap *map, uint range_num, uint offset,
205 void *valp, size_t val_len);
206
Mario Sixe9363972018-10-15 09:24:12 +0200207/**
208 * regmap_range_set() - Set a value in a regmap range described by a struct
209 * @map: Regmap in which a value should be set
210 * @range: Range of the regmap in which a value should be set
211 * @type: Structure type that describes the memory layout of the regmap range
212 * @member: Member of the describing structure that should be set in the regmap
213 * range
214 * @val: Value which should be written to the regmap range
215 */
216#define regmap_range_set(map, range, type, member, val) \
217 do { \
218 typeof(((type *)0)->member) __tmp = val; \
219 regmap_raw_write_range(map, range, offsetof(type, member), \
220 &__tmp, sizeof(((type *)0)->member)); \
221 } while (0)
Simon Glass6f98b752015-06-23 15:38:42 -0600222
Mario Sixe9363972018-10-15 09:24:12 +0200223/**
224 * regmap_set() - Set a value in a regmap described by a struct
225 * @map: Regmap in which a value should be set
226 * @type: Structure type that describes the memory layout of the regmap
227 * @member: Member of the describing structure that should be set in the regmap
228 * @val: Value which should be written to the regmap
229 */
230#define regmap_set(map, type, member, val) \
231 regmap_range_set(map, 0, type, member, val)
232
233/**
234 * regmap_range_get() - Get a value from a regmap range described by a struct
235 * @map: Regmap from which a value should be read
236 * @range: Range of the regmap from which a value should be read
237 * @type: Structure type that describes the memory layout of the regmap
238 * range
239 * @member: Member of the describing structure that should be read in the
240 * regmap range
241 * @valp: Variable that receives the value read from the regmap range
242 */
243#define regmap_range_get(map, range, type, member, valp) \
244 regmap_raw_read_range(map, range, offsetof(type, member), \
245 (void *)valp, sizeof(((type *)0)->member))
246
247/**
248 * regmap_get() - Get a value from a regmap described by a struct
249 * @map: Regmap from which a value should be read
250 * @type: Structure type that describes the memory layout of the regmap
251 * range
252 * @member: Member of the describing structure that should be read in the
253 * regmap
254 * @valp: Variable that receives the value read from the regmap
255 */
256#define regmap_get(map, type, member, valp) \
257 regmap_range_get(map, 0, type, member, valp)
Simon Glass6f98b752015-06-23 15:38:42 -0600258
259/**
Neil Armstrongd13801e2018-11-22 11:01:03 +0100260 * regmap_read_poll_timeout - Poll until a condition is met or a timeout occurs
261 *
262 * @map: Regmap to read from
263 * @addr: Offset to poll
264 * @val: Unsigned integer variable to read the value into
265 * @cond: Break condition (usually involving @val)
266 * @sleep_us: Maximum time to sleep between reads in us (0 tight-loops).
267 * @timeout_ms: Timeout in ms, 0 means never timeout
Simon Glassdf9cf1c2018-12-09 17:11:10 -0700268 * @test_add_time: Used for sandbox testing - amount of time to add after
269 * starting the loop (0 if not testing)
Neil Armstrongd13801e2018-11-22 11:01:03 +0100270 *
271 * Returns 0 on success and -ETIMEDOUT upon a timeout or the regmap_read
272 * error return value in case of a error read. In the two former cases,
273 * the last read value at @addr is stored in @val. Must not be called
274 * from atomic context if sleep_us or timeout_us are used.
275 *
276 * This is modelled after the regmap_read_poll_timeout macros in linux but
277 * with millisecond timeout.
Simon Glassdf9cf1c2018-12-09 17:11:10 -0700278 *
279 * The _test version is for sandbox testing only. Do not use this in normal
280 * code as it advances the timer.
Neil Armstrongd13801e2018-11-22 11:01:03 +0100281 */
Simon Glassdf9cf1c2018-12-09 17:11:10 -0700282#define regmap_read_poll_timeout_test(map, addr, val, cond, sleep_us, \
283 timeout_ms, test_add_time) \
Neil Armstrongd13801e2018-11-22 11:01:03 +0100284({ \
285 unsigned long __start = get_timer(0); \
286 int __ret; \
287 for (;;) { \
288 __ret = regmap_read((map), (addr), &(val)); \
289 if (__ret) \
290 break; \
291 if (cond) \
292 break; \
Simon Glassdf9cf1c2018-12-09 17:11:10 -0700293 if (IS_ENABLED(CONFIG_SANDBOX) && test_add_time) \
Neil Armstrongd0a9b822019-04-11 17:01:23 +0200294 timer_test_add_offset(test_add_time); \
Neil Armstrongd13801e2018-11-22 11:01:03 +0100295 if ((timeout_ms) && get_timer(__start) > (timeout_ms)) { \
296 __ret = regmap_read((map), (addr), &(val)); \
297 break; \
298 } \
299 if ((sleep_us)) \
300 udelay((sleep_us)); \
301 } \
302 __ret ?: ((cond) ? 0 : -ETIMEDOUT); \
303})
304
Simon Glassdf9cf1c2018-12-09 17:11:10 -0700305#define regmap_read_poll_timeout(map, addr, val, cond, sleep_us, timeout_ms) \
306 regmap_read_poll_timeout_test(map, addr, val, cond, sleep_us, \
307 timeout_ms, 0) \
308
Neil Armstrongd13801e2018-11-22 11:01:03 +0100309/**
Neil Armstrong285cbcf2018-04-27 11:56:14 +0200310 * regmap_update_bits() - Perform a read/modify/write using a mask
311 *
312 * @map: The map returned by regmap_init_mem*()
313 * @offset: Offset of the memory
314 * @mask: Mask to apply to the read value
Simon Glass5ca5ec12019-10-11 16:16:49 -0600315 * @val: Value to OR with the read value after masking. Note that any
316 * bits set in @val which are not set in @mask are ignored
Mario Six604b6692018-10-04 09:00:41 +0200317 * Return: 0 if OK, -ve on error
Neil Armstrong285cbcf2018-04-27 11:56:14 +0200318 */
319int regmap_update_bits(struct regmap *map, uint offset, uint mask, uint val);
320
321/**
Simon Glass6f98b752015-06-23 15:38:42 -0600322 * regmap_init_mem() - Set up a new register map that uses memory access
323 *
Masahiro Yamadad3581232018-04-19 12:14:03 +0900324 * @node: Device node that uses this map
Simon Glass6f98b752015-06-23 15:38:42 -0600325 * @mapp: Returns allocated map
Mario Six604b6692018-10-04 09:00:41 +0200326 * Return: 0 if OK, -ve on error
327 *
328 * Use regmap_uninit() to free it.
Simon Glass6f98b752015-06-23 15:38:42 -0600329 */
Masahiro Yamadad3581232018-04-19 12:14:03 +0900330int regmap_init_mem(ofnode node, struct regmap **mapp);
Simon Glass6f98b752015-06-23 15:38:42 -0600331
Simon Glass1e6ca1a2016-07-04 11:58:22 -0600332/**
Mario Six604b6692018-10-04 09:00:41 +0200333 * regmap_init_mem_platdata() - Set up a new memory register map for
334 * of-platdata
335 *
336 * @dev: Device that uses this map
337 * @reg: List of address, size pairs
338 * @count: Number of pairs (e.g. 1 if the regmap has a single entry)
339 * @mapp: Returns allocated map
340 * Return: 0 if OK, -ve on error
Simon Glass1e6ca1a2016-07-04 11:58:22 -0600341 *
342 * This creates a new regmap with a list of regions passed in, rather than
343 * using the device tree. It only supports 32-bit machines.
344 *
345 * Use regmap_uninit() to free it.
346 *
Simon Glass1e6ca1a2016-07-04 11:58:22 -0600347 */
Simon Glassc20ee0e2017-08-29 14:15:50 -0600348int regmap_init_mem_platdata(struct udevice *dev, fdt_val_t *reg, int count,
Simon Glass3b2a29e2016-07-04 11:57:59 -0600349 struct regmap **mapp);
350
Faiz Abbas55a1a092019-06-11 00:43:33 +0530351int regmap_init_mem_index(ofnode node, struct regmap **mapp, int index);
352
Simon Glass6f98b752015-06-23 15:38:42 -0600353/**
Pratyush Yadav0e01a7c2020-09-24 10:04:14 +0530354 * regmap_init_mem_range() - Set up a new memory region for ofnode with the
355 * specified range.
356 *
357 * @node: The ofnode for the map.
358 * @r_start: Start of the range.
359 * @r_size: Size of the range.
360 * @mapp: Returns allocated map.
361 *
362 * Return: 0 in success, -errno otherwise
363 *
364 * This creates a regmap with one range where instead of extracting the range
365 * from 'node', it is created based on the parameters specified. This is
366 * useful when a driver needs to calculate the base of the regmap at runtime,
367 * and can't specify it in device tree.
368 */
369int regmap_init_mem_range(ofnode node, ulong r_start, ulong r_size,
370 struct regmap **mapp);
371
372/**
Jean-Jacques Hiblotffb22f62020-09-24 10:04:10 +0530373 * devm_regmap_init() - Initialise register map (device managed)
374 *
375 * @dev: Device that will be interacted with
376 * @bus: Bus-specific callbacks to use with device (IGNORED)
377 * @bus_context: Data passed to bus-specific callbacks (IGNORED)
Pratyush Yadav78aaedb2020-09-24 10:04:12 +0530378 * @config: Configuration for register map
Jean-Jacques Hiblotffb22f62020-09-24 10:04:10 +0530379 *
380 * @Return a valid pointer to a struct regmap or a ERR_PTR() on error.
381 * The structure is automatically freed when the device is unbound
382 */
383struct regmap *devm_regmap_init(struct udevice *dev,
384 const struct regmap_bus *bus,
385 void *bus_context,
386 const struct regmap_config *config);
387/**
Simon Glass6f98b752015-06-23 15:38:42 -0600388 * regmap_get_range() - Obtain the base memory address of a regmap range
389 *
390 * @map: Regmap to query
391 * @range_num: Range to look up
Mario Six604b6692018-10-04 09:00:41 +0200392 * Return: Pointer to the range in question if OK, NULL on error
Simon Glass6f98b752015-06-23 15:38:42 -0600393 */
394void *regmap_get_range(struct regmap *map, unsigned int range_num);
395
396/**
397 * regmap_uninit() - free a previously inited regmap
Mario Six604b6692018-10-04 09:00:41 +0200398 *
399 * @map: Regmap to free
400 * Return: 0 if OK, -ve on error
Simon Glass6f98b752015-06-23 15:38:42 -0600401 */
402int regmap_uninit(struct regmap *map);
403
404#endif