xref: /openbmc/u-boot/include/regmap.h (revision 9dde167e)
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 /**
11  * DOC: Overview
12  *
13  * Regmaps are an abstraction mechanism that allows device drivers to access
14  * register maps irrespective of the underlying bus architecture. This entails
15  * that for devices that support multiple busses (e.g. I2C and SPI for a GPIO
16  * expander chip) only one driver has to be written. This driver will
17  * instantiate a regmap with a backend depending on the bus the device is
18  * attached to, and use the regmap API to access the register map through that
19  * bus transparently.
20  *
21  * Read and write functions are supplied, which can read/write data of
22  * arbitrary length from/to the regmap.
23  *
24  * The endianness of regmap accesses is selectable for each map through device
25  * tree settings via the boolean "little-endian", "big-endian", and
26  * "native-endian" properties.
27  *
28  * Furthermore, the register map described by a regmap can be split into
29  * multiple disjoint areas called ranges. In this way, register maps with
30  * "holes", i.e. areas of addressable memory that are not part of the register
31  * map, can be accessed in a concise manner.
32  *
33  * Currently, only a bare "mem" backend for regmaps is supported, which
34  * accesses the register map as regular IO-mapped memory.
35  */
36 
37 /**
38  * enum regmap_size_t - Access sizes for regmap reads and writes
39  *
40  * @REGMAP_SIZE_8: 8-bit read/write access size
41  * @REGMAP_SIZE_16: 16-bit read/write access size
42  * @REGMAP_SIZE_32: 32-bit read/write access size
43  * @REGMAP_SIZE_64: 64-bit read/write access size
44  */
45 enum regmap_size_t {
46 	REGMAP_SIZE_8 = 1,
47 	REGMAP_SIZE_16 = 2,
48 	REGMAP_SIZE_32 = 4,
49 	REGMAP_SIZE_64 = 8,
50 };
51 
52 /**
53  * enum regmap_endianness_t - Endianness for regmap reads and writes
54  *
55  * @REGMAP_NATIVE_ENDIAN: Native endian read/write accesses
56  * @REGMAP_LITTLE_ENDIAN: Little endian read/write accesses
57  * @REGMAP_BIG_ENDIAN: Big endian read/write accesses
58  */
59 enum regmap_endianness_t {
60 	REGMAP_NATIVE_ENDIAN,
61 	REGMAP_LITTLE_ENDIAN,
62 	REGMAP_BIG_ENDIAN,
63 };
64 
65 /**
66  * struct regmap_range - a register map range
67  *
68  * @start:	Start address
69  * @size:	Size in bytes
70  */
71 struct regmap_range {
72 	ulong start;
73 	ulong size;
74 };
75 
76 /**
77  * struct regmap - a way of accessing hardware/bus registers
78  *
79  * @range_count:	Number of ranges available within the map
80  * @ranges:		Array of ranges
81  */
82 struct regmap {
83 	enum regmap_endianness_t endianness;
84 	int range_count;
85 	struct regmap_range ranges[0];
86 };
87 
88 /*
89  * Interface to provide access to registers either through a direct memory
90  * bus or through a peripheral bus like I2C, SPI.
91  */
92 
93 /**
94  * regmap_write() - Write a 32-bit value to a regmap
95  *
96  * @map:	Regmap to write to
97  * @offset:	Offset in the regmap to write to
98  * @val:	Data to write to the regmap at the specified offset
99  *
100  * Note that this function will only write values of 32 bit width to the
101  * regmap; if the size of data to be read is different, the regmap_raw_write
102  * function can be used.
103  *
104  * Return: 0 if OK, -ve on error
105  */
106 int regmap_write(struct regmap *map, uint offset, uint val);
107 
108 /**
109  * regmap_read() - Read a 32-bit value from a regmap
110  *
111  * @map:	Regmap to read from
112  * @offset:	Offset in the regmap to read from
113  * @valp:	Pointer to the buffer to receive the data read from the regmap
114  *		at the specified offset
115  *
116  * Note that this function will only read values of 32 bit width from the
117  * regmap; if the size of data to be read is different, the regmap_raw_read
118  * function can be used.
119  *
120  * Return: 0 if OK, -ve on error
121  */
122 int regmap_read(struct regmap *map, uint offset, uint *valp);
123 
124 /**
125  * regmap_raw_write() - Write a value of specified length to a regmap
126  *
127  * @map:	Regmap to write to
128  * @offset:	Offset in the regmap to write to
129  * @val:	Value to write to the regmap at the specified offset
130  * @val_len:	Length of the data to be written to the regmap
131  *
132  * Note that this function will, as opposed to regmap_write, write data of
133  * arbitrary length to the regmap, and not just 32-bit values, and is thus a
134  * generalized version of regmap_write.
135  *
136  * Return: 0 if OK, -ve on error
137  */
138 int regmap_raw_write(struct regmap *map, uint offset, const void *val,
139 		     size_t val_len);
140 
141 /**
142  * regmap_raw_read() - Read a value of specified length from a regmap
143  *
144  * @map:	Regmap to read from
145  * @offset:	Offset in the regmap to read from
146  * @valp:	Pointer to the buffer to receive the data read from the regmap
147  *		at the specified offset
148  * @val_len:	Length of the data to be read from the regmap
149  *
150  * Note that this function will, as opposed to regmap_read, read data of
151  * arbitrary length from the regmap, and not just 32-bit values, and is thus a
152  * generalized version of regmap_read.
153  *
154  * Return: 0 if OK, -ve on error
155  */
156 int regmap_raw_read(struct regmap *map, uint offset, void *valp,
157 		    size_t val_len);
158 
159 /**
160  * regmap_raw_write_range() - Write a value of specified length to a range of a
161  *			      regmap
162  *
163  * @map:	Regmap to write to
164  * @range_num:	Number of the range in the regmap to write to
165  * @offset:	Offset in the regmap to write to
166  * @val:	Value to write to the regmap at the specified offset
167  * @val_len:	Length of the data to be written to the regmap
168  *
169  * Return: 0 if OK, -ve on error
170  */
171 int regmap_raw_write_range(struct regmap *map, uint range_num, uint offset,
172 			   const void *val, size_t val_len);
173 
174 /**
175  * regmap_raw_read_range() - Read a value of specified length from a range of a
176  *			     regmap
177  *
178  * @map:	Regmap to read from
179  * @range_num:	Number of the range in the regmap to write to
180  * @offset:	Offset in the regmap to read from
181  * @valp:	Pointer to the buffer to receive the data read from the regmap
182  *		at the specified offset
183  * @val_len:	Length of the data to be read from the regmap
184  *
185  * Return: 0 if OK, -ve on error
186  */
187 int regmap_raw_read_range(struct regmap *map, uint range_num, uint offset,
188 			  void *valp, size_t val_len);
189 
190 /**
191  * regmap_range_set() - Set a value in a regmap range described by a struct
192  * @map:    Regmap in which a value should be set
193  * @range:  Range of the regmap in which a value should be set
194  * @type:   Structure type that describes the memory layout of the regmap range
195  * @member: Member of the describing structure that should be set in the regmap
196  *          range
197  * @val:    Value which should be written to the regmap range
198  */
199 #define regmap_range_set(map, range, type, member, val) \
200 	do { \
201 		typeof(((type *)0)->member) __tmp = val; \
202 		regmap_raw_write_range(map, range, offsetof(type, member), \
203 				       &__tmp, sizeof(((type *)0)->member)); \
204 	} while (0)
205 
206 /**
207  * regmap_set() - Set a value in a regmap described by a struct
208  * @map:    Regmap in which a value should be set
209  * @type:   Structure type that describes the memory layout of the regmap
210  * @member: Member of the describing structure that should be set in the regmap
211  * @val:    Value which should be written to the regmap
212  */
213 #define regmap_set(map, type, member, val) \
214 	regmap_range_set(map, 0, type, member, val)
215 
216 /**
217  * regmap_range_get() - Get a value from a regmap range described by a struct
218  * @map:    Regmap from which a value should be read
219  * @range:  Range of the regmap from which a value should be read
220  * @type:   Structure type that describes the memory layout of the regmap
221  *          range
222  * @member: Member of the describing structure that should be read in the
223  *          regmap range
224  * @valp:   Variable that receives the value read from the regmap range
225  */
226 #define regmap_range_get(map, range, type, member, valp) \
227 	regmap_raw_read_range(map, range, offsetof(type, member), \
228 			      (void *)valp, sizeof(((type *)0)->member))
229 
230 /**
231  * regmap_get() - Get a value from a regmap described by a struct
232  * @map:    Regmap from which a value should be read
233  * @type:   Structure type that describes the memory layout of the regmap
234  *          range
235  * @member: Member of the describing structure that should be read in the
236  *          regmap
237  * @valp:   Variable that receives the value read from the regmap
238  */
239 #define regmap_get(map, type, member, valp) \
240 	regmap_range_get(map, 0, type, member, valp)
241 
242 /**
243  * regmap_read_poll_timeout - Poll until a condition is met or a timeout occurs
244  *
245  * @map:	Regmap to read from
246  * @addr:	Offset to poll
247  * @val:	Unsigned integer variable to read the value into
248  * @cond:	Break condition (usually involving @val)
249  * @sleep_us:	Maximum time to sleep between reads in us (0 tight-loops).
250  * @timeout_ms:	Timeout in ms, 0 means never timeout
251  * @test_add_time: Used for sandbox testing - amount of time to add after
252  *		starting the loop (0 if not testing)
253  *
254  * Returns 0 on success and -ETIMEDOUT upon a timeout or the regmap_read
255  * error return value in case of a error read. In the two former cases,
256  * the last read value at @addr is stored in @val. Must not be called
257  * from atomic context if sleep_us or timeout_us are used.
258  *
259  * This is modelled after the regmap_read_poll_timeout macros in linux but
260  * with millisecond timeout.
261  *
262  * The _test version is for sandbox testing only. Do not use this in normal
263  * code as it advances the timer.
264  */
265 #define regmap_read_poll_timeout_test(map, addr, val, cond, sleep_us, \
266 				      timeout_ms, test_add_time) \
267 ({ \
268 	unsigned long __start = get_timer(0); \
269 	int __ret; \
270 	for (;;) { \
271 		__ret = regmap_read((map), (addr), &(val)); \
272 		if (__ret) \
273 			break; \
274 		if (cond) \
275 			break; \
276 		if (IS_ENABLED(CONFIG_SANDBOX) && test_add_time) \
277 			sandbox_timer_add_offset(test_add_time); \
278 		if ((timeout_ms) && get_timer(__start) > (timeout_ms)) { \
279 			__ret = regmap_read((map), (addr), &(val)); \
280 			break; \
281 		} \
282 		if ((sleep_us)) \
283 			udelay((sleep_us)); \
284 	} \
285 	__ret ?: ((cond) ? 0 : -ETIMEDOUT); \
286 })
287 
288 #define regmap_read_poll_timeout(map, addr, val, cond, sleep_us, timeout_ms) \
289 	regmap_read_poll_timeout_test(map, addr, val, cond, sleep_us, \
290 				      timeout_ms, 0) \
291 
292 /**
293  * regmap_update_bits() - Perform a read/modify/write using a mask
294  *
295  * @map:	The map returned by regmap_init_mem*()
296  * @offset:	Offset of the memory
297  * @mask:	Mask to apply to the read value
298  * @val:	Value to apply to the value to write
299  * Return: 0 if OK, -ve on error
300  */
301 int regmap_update_bits(struct regmap *map, uint offset, uint mask, uint val);
302 
303 /**
304  * regmap_init_mem() - Set up a new register map that uses memory access
305  *
306  * @node:	Device node that uses this map
307  * @mapp:	Returns allocated map
308  * Return: 0 if OK, -ve on error
309  *
310  * Use regmap_uninit() to free it.
311  */
312 int regmap_init_mem(ofnode node, struct regmap **mapp);
313 
314 /**
315  * regmap_init_mem_platdata() - Set up a new memory register map for
316  *				of-platdata
317  *
318  * @dev:	Device that uses this map
319  * @reg:	List of address, size pairs
320  * @count:	Number of pairs (e.g. 1 if the regmap has a single entry)
321  * @mapp:	Returns allocated map
322  * Return: 0 if OK, -ve on error
323  *
324  * This creates a new regmap with a list of regions passed in, rather than
325  * using the device tree. It only supports 32-bit machines.
326  *
327  * Use regmap_uninit() to free it.
328  *
329  */
330 int regmap_init_mem_platdata(struct udevice *dev, fdt_val_t *reg, int count,
331 			     struct regmap **mapp);
332 
333 /**
334  * regmap_get_range() - Obtain the base memory address of a regmap range
335  *
336  * @map:	Regmap to query
337  * @range_num:	Range to look up
338  * Return: Pointer to the range in question if OK, NULL on error
339  */
340 void *regmap_get_range(struct regmap *map, unsigned int range_num);
341 
342 /**
343  * regmap_uninit() - free a previously inited regmap
344  *
345  * @map:	Regmap to free
346  * Return: 0 if OK, -ve on error
347  */
348 int regmap_uninit(struct regmap *map);
349 
350 #endif
351