1 /* SPDX-License-Identifier: GPL-2.0+ */
2 /*
3 * Copyright (c) 2015 Google, Inc
4 * Written by Simon Glass <sjg@chromium.org>
5 */
6
7 #ifndef __REGMAP_H
8 #define __REGMAP_H
9
10 #include <linux/delay.h>
11
12 /**
13 * 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 /**
40 * 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 */
47 enum 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 /**
55 * 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 */
61 enum regmap_endianness_t {
62 REGMAP_NATIVE_ENDIAN,
63 REGMAP_LITTLE_ENDIAN,
64 REGMAP_BIG_ENDIAN,
65 };
66
67 /**
68 * struct regmap_range - a register map range
69 *
70 * @start: Start address
71 * @size: Size in bytes
72 */
73 struct regmap_range {
74 ulong start;
75 ulong size;
76 };
77
78 struct regmap_bus;
79
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.
85 * @reg_offset_shift Left shift the register offset by this value before
86 * performing read or write.
87 * @r_start: If specified, the regmap is created with one range
88 * which starts at this address, instead of finding the
89 * start from device tree.
90 * @r_size: Same as above for the range size
91 */
92 struct regmap_config {
93 enum regmap_size_t width;
94 u32 reg_offset_shift;
95 ulong r_start;
96 ulong r_size;
97 };
98
99 /**
100 * struct regmap - a way of accessing hardware/bus registers
101 *
102 * @width: Width of the read/write operations. Defaults to
103 * REGMAP_SIZE_32 if set to 0.
104 * @reg_offset_shift Left shift the register offset by this value before
105 * performing read or write.
106 * @range_count: Number of ranges available within the map
107 * @ranges: Array of ranges
108 */
109 struct regmap {
110 enum regmap_endianness_t endianness;
111 enum regmap_size_t width;
112 u32 reg_offset_shift;
113 int range_count;
114 struct regmap_range ranges[0];
115 };
116
117 /*
118 * Interface to provide access to registers either through a direct memory
119 * bus or through a peripheral bus like I2C, SPI.
120 */
121
122 /**
123 * regmap_write() - Write a value to a regmap
124 *
125 * @map: Regmap to write to
126 * @offset: Offset in the regmap to write to
127 * @val: Data to write to the regmap at the specified offset
128 *
129 * Return: 0 if OK, -ve on error
130 */
131 int regmap_write(struct regmap *map, uint offset, uint val);
132
133 /**
134 * regmap_read() - Read a value from a regmap
135 *
136 * @map: Regmap to read from
137 * @offset: Offset in the regmap to read from
138 * @valp: Pointer to the buffer to receive the data read from the regmap
139 * at the specified offset
140 *
141 * Return: 0 if OK, -ve on error
142 */
143 int regmap_read(struct regmap *map, uint offset, uint *valp);
144
145 /**
146 * regmap_raw_write() - Write a value of specified length to a regmap
147 *
148 * @map: Regmap to write to
149 * @offset: Offset in the regmap to write to
150 * @val: Value to write to the regmap at the specified offset
151 * @val_len: Length of the data to be written to the regmap
152 *
153 * Note that this function will, as opposed to regmap_write, write data of
154 * arbitrary length to the regmap, and not just the size configured in the
155 * regmap (defaults to 32-bit) and is thus a generalized version of
156 * regmap_write.
157 *
158 * Return: 0 if OK, -ve on error
159 */
160 int regmap_raw_write(struct regmap *map, uint offset, const void *val,
161 size_t val_len);
162
163 /**
164 * regmap_raw_read() - Read a value of specified length from a regmap
165 *
166 * @map: Regmap to read from
167 * @offset: Offset in the regmap to read from
168 * @valp: Pointer to the buffer to receive the data read from the regmap
169 * at the specified offset
170 * @val_len: Length of the data to be read from the regmap
171 *
172 * Note that this function will, as opposed to regmap_read, read data of
173 * arbitrary length from the regmap, and not just the size configured in the
174 * regmap (defaults to 32-bit) and is thus a generalized version of
175 * regmap_read.
176 *
177 * Return: 0 if OK, -ve on error
178 */
179 int regmap_raw_read(struct regmap *map, uint offset, void *valp,
180 size_t val_len);
181
182 /**
183 * regmap_raw_write_range() - Write a value of specified length to a range of a
184 * regmap
185 *
186 * @map: Regmap to write to
187 * @range_num: Number of the range in the regmap to write to
188 * @offset: Offset in the regmap to write to
189 * @val: Value to write to the regmap at the specified offset
190 * @val_len: Length of the data to be written to the regmap
191 *
192 * Return: 0 if OK, -ve on error
193 */
194 int regmap_raw_write_range(struct regmap *map, uint range_num, uint offset,
195 const void *val, size_t val_len);
196
197 /**
198 * regmap_raw_read_range() - Read a value of specified length from a range of a
199 * regmap
200 *
201 * @map: Regmap to read from
202 * @range_num: Number of the range in the regmap to write to
203 * @offset: Offset in the regmap to read from
204 * @valp: Pointer to the buffer to receive the data read from the regmap
205 * at the specified offset
206 * @val_len: Length of the data to be read from the regmap
207 *
208 * Return: 0 if OK, -ve on error
209 */
210 int regmap_raw_read_range(struct regmap *map, uint range_num, uint offset,
211 void *valp, size_t val_len);
212
213 /**
214 * regmap_range_set() - Set a value in a regmap range described by a struct
215 * @map: Regmap in which a value should be set
216 * @range: Range of the regmap in which a value should be set
217 * @type: Structure type that describes the memory layout of the regmap range
218 * @member: Member of the describing structure that should be set in the regmap
219 * range
220 * @val: Value which should be written to the regmap range
221 */
222 #define regmap_range_set(map, range, type, member, val) \
223 do { \
224 typeof(((type *)0)->member) __tmp = val; \
225 regmap_raw_write_range(map, range, offsetof(type, member), \
226 &__tmp, sizeof(((type *)0)->member)); \
227 } while (0)
228
229 /**
230 * regmap_set() - Set a value in a regmap described by a struct
231 * @map: Regmap in which a value should be set
232 * @type: Structure type that describes the memory layout of the regmap
233 * @member: Member of the describing structure that should be set in the regmap
234 * @val: Value which should be written to the regmap
235 */
236 #define regmap_set(map, type, member, val) \
237 regmap_range_set(map, 0, type, member, val)
238
239 /**
240 * regmap_range_get() - Get a value from a regmap range described by a struct
241 * @map: Regmap from which a value should be read
242 * @range: Range of the regmap from which a value should be read
243 * @type: Structure type that describes the memory layout of the regmap
244 * range
245 * @member: Member of the describing structure that should be read in the
246 * regmap range
247 * @valp: Variable that receives the value read from the regmap range
248 */
249 #define regmap_range_get(map, range, type, member, valp) \
250 regmap_raw_read_range(map, range, offsetof(type, member), \
251 (void *)valp, sizeof(((type *)0)->member))
252
253 /**
254 * regmap_get() - Get a value from a regmap described by a struct
255 * @map: Regmap from which a value should be read
256 * @type: Structure type that describes the memory layout of the regmap
257 * range
258 * @member: Member of the describing structure that should be read in the
259 * regmap
260 * @valp: Variable that receives the value read from the regmap
261 */
262 #define regmap_get(map, type, member, valp) \
263 regmap_range_get(map, 0, type, member, valp)
264
265 /**
266 * regmap_read_poll_timeout - Poll until a condition is met or a timeout occurs
267 *
268 * @map: Regmap to read from
269 * @addr: Offset to poll
270 * @val: Unsigned integer variable to read the value into
271 * @cond: Break condition (usually involving @val)
272 * @sleep_us: Maximum time to sleep between reads in us (0 tight-loops).
273 * @timeout_ms: Timeout in ms, 0 means never timeout
274 * @test_add_time: Used for sandbox testing - amount of time to add after
275 * starting the loop (0 if not testing)
276 *
277 * Returns 0 on success and -ETIMEDOUT upon a timeout or the regmap_read
278 * error return value in case of a error read. In the two former cases,
279 * the last read value at @addr is stored in @val. Must not be called
280 * from atomic context if sleep_us or timeout_us are used.
281 *
282 * This is modelled after the regmap_read_poll_timeout macros in linux but
283 * with millisecond timeout.
284 *
285 * The _test version is for sandbox testing only. Do not use this in normal
286 * code as it advances the timer.
287 */
288 #define regmap_read_poll_timeout_test(map, addr, val, cond, sleep_us, \
289 timeout_ms, test_add_time) \
290 ({ \
291 unsigned long __start = get_timer(0); \
292 int __ret; \
293 for (;;) { \
294 __ret = regmap_read((map), (addr), &(val)); \
295 if (__ret) \
296 break; \
297 if (cond) \
298 break; \
299 if (IS_ENABLED(CONFIG_SANDBOX) && test_add_time) \
300 timer_test_add_offset(test_add_time); \
301 if ((timeout_ms) && get_timer(__start) > (timeout_ms)) { \
302 __ret = regmap_read((map), (addr), &(val)); \
303 break; \
304 } \
305 if ((sleep_us)) \
306 udelay((sleep_us)); \
307 } \
308 __ret ?: ((cond) ? 0 : -ETIMEDOUT); \
309 })
310
311 #define regmap_read_poll_timeout(map, addr, val, cond, sleep_us, timeout_ms) \
312 regmap_read_poll_timeout_test(map, addr, val, cond, sleep_us, \
313 timeout_ms, 0) \
314
315 /**
316 * regmap_field_read_poll_timeout - Poll until a condition is met or a timeout
317 * occurs
318 *
319 * @field: Regmap field to read from
320 * @val: Unsigned integer variable to read the value into
321 * @cond: Break condition (usually involving @val)
322 * @sleep_us: Maximum time to sleep between reads in us (0 tight-loops).
323 * @timeout_ms: Timeout in ms, 0 means never timeout
324 *
325 * Returns 0 on success and -ETIMEDOUT upon a timeout or the regmap_field_read
326 * error return value in case of a error read. In the two former cases,
327 * the last read value at @addr is stored in @val.
328 *
329 * This is modelled after the regmap_read_poll_timeout macros in linux but
330 * with millisecond timeout.
331 */
332 #define regmap_field_read_poll_timeout(field, val, cond, sleep_us, timeout_ms) \
333 ({ \
334 unsigned long __start = get_timer(0); \
335 int __ret; \
336 for (;;) { \
337 __ret = regmap_field_read((field), &(val)); \
338 if (__ret) \
339 break; \
340 if (cond) \
341 break; \
342 if ((timeout_ms) && get_timer(__start) > (timeout_ms)) { \
343 __ret = regmap_field_read((field), &(val)); \
344 break; \
345 } \
346 if ((sleep_us)) \
347 udelay((sleep_us)); \
348 } \
349 __ret ?: ((cond) ? 0 : -ETIMEDOUT); \
350 })
351
352 /**
353 * regmap_update_bits() - Perform a read/modify/write using a mask
354 *
355 * @map: The map returned by regmap_init_mem*()
356 * @offset: Offset of the memory
357 * @mask: Mask to apply to the read value
358 * @val: Value to OR with the read value after masking. Note that any
359 * bits set in @val which are not set in @mask are ignored
360 * Return: 0 if OK, -ve on error
361 */
362 int regmap_update_bits(struct regmap *map, uint offset, uint mask, uint val);
363
364 /**
365 * regmap_set_bits() - Set bits to a regmap
366 *
367 * @map: Regmap to write bits to
368 * @offset: Offset in the regmap to write to
369 * @bits: Bits to set to the regmap at the specified offset
370 *
371 * Return: 0 if OK, -ve on error
372 */
regmap_set_bits(struct regmap * map,uint offset,uint bits)373 static inline int regmap_set_bits(struct regmap *map, uint offset, uint bits)
374 {
375 return regmap_update_bits(map, offset, bits, bits);
376 }
377
378 /**
379 * regmap_clear_bits() - Clear bits to a regmap
380 *
381 * @map: Regmap to write bits to
382 * @offset: Offset in the regmap to write to
383 * @bits: Bits to clear to the regmap at the specified offset
384 *
385 * Return: 0 if OK, -ve on error
386 */
regmap_clear_bits(struct regmap * map,uint offset,uint bits)387 static inline int regmap_clear_bits(struct regmap *map, uint offset, uint bits)
388 {
389 return regmap_update_bits(map, offset, bits, 0);
390 }
391
392 /**
393 * regmap_init_mem() - Set up a new register map that uses memory access
394 *
395 * @node: Device node that uses this map
396 * @mapp: Returns allocated map
397 * Return: 0 if OK, -ve on error
398 *
399 * Use regmap_uninit() to free it.
400 */
401 int regmap_init_mem(ofnode node, struct regmap **mapp);
402
403 /**
404 * regmap_init_mem_plat() - Set up a new memory register map for
405 * of-platdata
406 *
407 * @dev: Device that uses this map
408 * @reg: List of address, size pairs
409 * @size: Size of one reg array item
410 * @count: Number of pairs (e.g. 1 if the regmap has a single entry)
411 * @mapp: Returns allocated map
412 * Return: 0 if OK, -ve on error
413 *
414 * This creates a new regmap with a list of regions passed in, rather than
415 * using the device tree.
416 *
417 * Use regmap_uninit() to free it.
418 *
419 */
420 int regmap_init_mem_plat(struct udevice *dev, void *reg, int size, int count,
421 struct regmap **mapp);
422
423 int regmap_init_mem_index(ofnode node, struct regmap **mapp, int index);
424
425 /**
426 * regmap_init_mem_range() - Set up a new memory region for ofnode with the
427 * specified range.
428 *
429 * @node: The ofnode for the map.
430 * @r_start: Start of the range.
431 * @r_size: Size of the range.
432 * @mapp: Returns allocated map.
433 *
434 * Return: 0 in success, -errno otherwise
435 *
436 * This creates a regmap with one range where instead of extracting the range
437 * from 'node', it is created based on the parameters specified. This is
438 * useful when a driver needs to calculate the base of the regmap at runtime,
439 * and can't specify it in device tree.
440 */
441 int regmap_init_mem_range(ofnode node, ulong r_start, ulong r_size,
442 struct regmap **mapp);
443
444 /**
445 * devm_regmap_init() - Initialise register map (device managed)
446 *
447 * @dev: Device that will be interacted with
448 * @bus: Bus-specific callbacks to use with device (IGNORED)
449 * @bus_context: Data passed to bus-specific callbacks (IGNORED)
450 * @config: Configuration for register map
451 *
452 * @Return a valid pointer to a struct regmap or a ERR_PTR() on error.
453 * The structure is automatically freed when the device is unbound
454 */
455 struct regmap *devm_regmap_init(struct udevice *dev,
456 const struct regmap_bus *bus,
457 void *bus_context,
458 const struct regmap_config *config);
459 /**
460 * regmap_get_range() - Obtain the base memory address of a regmap range
461 *
462 * @map: Regmap to query
463 * @range_num: Range to look up
464 * Return: Pointer to the range in question if OK, NULL on error
465 */
466 void *regmap_get_range(struct regmap *map, unsigned int range_num);
467
468 /**
469 * regmap_uninit() - free a previously inited regmap
470 *
471 * @map: Regmap to free
472 * Return: 0 if OK, -ve on error
473 */
474 int regmap_uninit(struct regmap *map);
475
476 /**
477 * struct reg_field - Description of an register field
478 *
479 * @reg: Offset of the register within the regmap bank
480 * @lsb: lsb of the register field.
481 * @msb: msb of the register field.
482 */
483 struct reg_field {
484 unsigned int reg;
485 unsigned int lsb;
486 unsigned int msb;
487 };
488
489 struct regmap_field;
490
491 /**
492 * REG_FIELD() - A convenient way to initialize a 'struct reg_field'.
493 *
494 * @_reg: Offset of the register within the regmap bank
495 * @_lsb: lsb of the register field.
496 * @_msb: msb of the register field.
497 *
498 * Register fields are often described in terms of 3 things: the register it
499 * belongs to, its LSB, and its MSB. This macro can be used by drivers to
500 * clearly and easily initialize a 'struct regmap_field'.
501 *
502 * For example, say a device has a register at offset DEV_REG1 (0x100) and a
503 * field of DEV_REG1 is on bits [7:3]. So a driver can initialize a regmap
504 * field for this by doing:
505 * struct reg_field field = REG_FIELD(DEV_REG1, 3, 7);
506 */
507 #define REG_FIELD(_reg, _lsb, _msb) { \
508 .reg = _reg, \
509 .lsb = _lsb, \
510 .msb = _msb, \
511 }
512
513 /**
514 * devm_regmap_field_alloc() - Allocate and initialise a register field.
515 *
516 * @dev: Device that will be interacted with
517 * @regmap: regmap bank in which this register field is located.
518 * @reg_field: Register field with in the bank.
519 *
520 * The return value will be an ERR_PTR() on error or a valid pointer
521 * to a struct regmap_field. The regmap_field will be automatically freed
522 * by the device management code.
523 */
524 struct regmap_field *devm_regmap_field_alloc(struct udevice *dev,
525 struct regmap *regmap,
526 struct reg_field reg_field);
527 /**
528 * devm_regmap_field_free() - Free a register field allocated using
529 * devm_regmap_field_alloc.
530 *
531 * @dev: Device that will be interacted with
532 * @field: regmap field which should be freed.
533 *
534 * Free register field allocated using devm_regmap_field_alloc(). Usually
535 * drivers need not call this function, as the memory allocated via devm
536 * will be freed as per device-driver life-cyle.
537 */
538 void devm_regmap_field_free(struct udevice *dev, struct regmap_field *field);
539
540 /**
541 * regmap_field_write() - Write a value to a regmap field
542 *
543 * @field: Regmap field to write to
544 * @val: Data to write to the regmap at the specified offset
545 *
546 * Return: 0 if OK, -ve on error
547 */
548 int regmap_field_write(struct regmap_field *field, unsigned int val);
549
550 /**
551 * regmap_field_read() - Read a 32-bit value from a regmap
552 *
553 * @field: Regmap field to read from
554 * @valp: Pointer to the buffer to receive the data read from the regmap
555 * field
556 *
557 * Return: 0 if OK, -ve on error
558 */
559 int regmap_field_read(struct regmap_field *field, unsigned int *val);
560
561 #endif
562