board: engicam: Attach i.MX6 common code
[platform/kernel/u-boot.git] / include / regmap.h
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_init_mem() - Set up a new register map that uses memory access
366  *
367  * @node:       Device node that uses this map
368  * @mapp:       Returns allocated map
369  * Return: 0 if OK, -ve on error
370  *
371  * Use regmap_uninit() to free it.
372  */
373 int regmap_init_mem(ofnode node, struct regmap **mapp);
374
375 /**
376  * regmap_init_mem_platdata() - Set up a new memory register map for
377  *                              of-platdata
378  *
379  * @dev:        Device that uses this map
380  * @reg:        List of address, size pairs
381  * @count:      Number of pairs (e.g. 1 if the regmap has a single entry)
382  * @mapp:       Returns allocated map
383  * Return: 0 if OK, -ve on error
384  *
385  * This creates a new regmap with a list of regions passed in, rather than
386  * using the device tree. It only supports 32-bit machines.
387  *
388  * Use regmap_uninit() to free it.
389  *
390  */
391 int regmap_init_mem_platdata(struct udevice *dev, fdt_val_t *reg, int count,
392                              struct regmap **mapp);
393
394 int regmap_init_mem_index(ofnode node, struct regmap **mapp, int index);
395
396 /**
397  * regmap_init_mem_range() - Set up a new memory region for ofnode with the
398  *                           specified range.
399  *
400  * @node:       The ofnode for the map.
401  * @r_start:    Start of the range.
402  * @r_size:     Size of the range.
403  * @mapp:       Returns allocated map.
404  *
405  * Return: 0 in success, -errno otherwise
406  *
407  * This creates a regmap with one range where instead of extracting the range
408  * from 'node', it is created based on the parameters specified. This is
409  * useful when a driver needs to calculate the base of the regmap at runtime,
410  * and can't specify it in device tree.
411  */
412 int regmap_init_mem_range(ofnode node, ulong r_start, ulong r_size,
413                           struct regmap **mapp);
414
415 /**
416  * devm_regmap_init() - Initialise register map (device managed)
417  *
418  * @dev: Device that will be interacted with
419  * @bus: Bus-specific callbacks to use with device (IGNORED)
420  * @bus_context: Data passed to bus-specific callbacks (IGNORED)
421  * @config: Configuration for register map
422  *
423  * @Return a valid pointer to a struct regmap or a ERR_PTR() on error.
424  * The structure is automatically freed when the device is unbound
425  */
426 struct regmap *devm_regmap_init(struct udevice *dev,
427                                 const struct regmap_bus *bus,
428                                 void *bus_context,
429                                 const struct regmap_config *config);
430 /**
431  * regmap_get_range() - Obtain the base memory address of a regmap range
432  *
433  * @map:        Regmap to query
434  * @range_num:  Range to look up
435  * Return: Pointer to the range in question if OK, NULL on error
436  */
437 void *regmap_get_range(struct regmap *map, unsigned int range_num);
438
439 /**
440  * regmap_uninit() - free a previously inited regmap
441  *
442  * @map:        Regmap to free
443  * Return: 0 if OK, -ve on error
444  */
445 int regmap_uninit(struct regmap *map);
446
447 /**
448  * struct reg_field - Description of an register field
449  *
450  * @reg: Offset of the register within the regmap bank
451  * @lsb: lsb of the register field.
452  * @msb: msb of the register field.
453  */
454 struct reg_field {
455         unsigned int reg;
456         unsigned int lsb;
457         unsigned int msb;
458 };
459
460 struct regmap_field;
461
462 /**
463  * REG_FIELD() - A convenient way to initialize a 'struct reg_feild'.
464  *
465  * @_reg: Offset of the register within the regmap bank
466  * @_lsb: lsb of the register field.
467  * @_msb: msb of the register field.
468  *
469  * Register fields are often described in terms of 3 things: the register it
470  * belongs to, its LSB, and its MSB. This macro can be used by drivers to
471  * clearly and easily initialize a 'struct regmap_field'.
472  *
473  * For example, say a device has a register at offset DEV_REG1 (0x100) and a
474  * field of DEV_REG1 is on bits [7:3]. So a driver can initialize a regmap
475  * field for this by doing:
476  *     struct reg_field field = REG_FIELD(DEV_REG1, 3, 7);
477  */
478 #define REG_FIELD(_reg, _lsb, _msb) {           \
479                                 .reg = _reg,    \
480                                 .lsb = _lsb,    \
481                                 .msb = _msb,    \
482                                 }
483
484 /**
485  * devm_regmap_field_alloc() - Allocate and initialise a register field.
486  *
487  * @dev: Device that will be interacted with
488  * @regmap: regmap bank in which this register field is located.
489  * @reg_field: Register field with in the bank.
490  *
491  * The return value will be an ERR_PTR() on error or a valid pointer
492  * to a struct regmap_field. The regmap_field will be automatically freed
493  * by the device management code.
494  */
495 struct regmap_field *devm_regmap_field_alloc(struct udevice *dev,
496                                              struct regmap *regmap,
497                                              struct reg_field reg_field);
498 /**
499  * devm_regmap_field_free() - Free a register field allocated using
500  *                            devm_regmap_field_alloc.
501  *
502  * @dev: Device that will be interacted with
503  * @field: regmap field which should be freed.
504  *
505  * Free register field allocated using devm_regmap_field_alloc(). Usually
506  * drivers need not call this function, as the memory allocated via devm
507  * will be freed as per device-driver life-cyle.
508  */
509 void devm_regmap_field_free(struct udevice *dev, struct regmap_field *field);
510
511 /**
512  * regmap_field_write() - Write a value to a regmap field
513  *
514  * @field:      Regmap field to write to
515  * @val:        Data to write to the regmap at the specified offset
516  *
517  * Return: 0 if OK, -ve on error
518  */
519 int regmap_field_write(struct regmap_field *field, unsigned int val);
520
521 /**
522  * regmap_read() - Read a 32-bit value from a regmap
523  *
524  * @field:      Regmap field to write to
525  * @valp:       Pointer to the buffer to receive the data read from the regmap
526  *              field
527  *
528  * Return: 0 if OK, -ve on error
529  */
530 int regmap_field_read(struct regmap_field *field, unsigned int *val);
531
532 #endif