xref: /openbmc/u-boot/include/regmap.h (revision f55db0af)
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_update_bits() - Perform a read/modify/write using a mask
244  *
245  * @map:	The map returned by regmap_init_mem*()
246  * @offset:	Offset of the memory
247  * @mask:	Mask to apply to the read value
248  * @val:	Value to apply to the value to write
249  * Return: 0 if OK, -ve on error
250  */
251 int regmap_update_bits(struct regmap *map, uint offset, uint mask, uint val);
252 
253 /**
254  * regmap_init_mem() - Set up a new register map that uses memory access
255  *
256  * @node:	Device node that uses this map
257  * @mapp:	Returns allocated map
258  * Return: 0 if OK, -ve on error
259  *
260  * Use regmap_uninit() to free it.
261  */
262 int regmap_init_mem(ofnode node, struct regmap **mapp);
263 
264 /**
265  * regmap_init_mem_platdata() - Set up a new memory register map for
266  *				of-platdata
267  *
268  * @dev:	Device that uses this map
269  * @reg:	List of address, size pairs
270  * @count:	Number of pairs (e.g. 1 if the regmap has a single entry)
271  * @mapp:	Returns allocated map
272  * Return: 0 if OK, -ve on error
273  *
274  * This creates a new regmap with a list of regions passed in, rather than
275  * using the device tree. It only supports 32-bit machines.
276  *
277  * Use regmap_uninit() to free it.
278  *
279  */
280 int regmap_init_mem_platdata(struct udevice *dev, fdt_val_t *reg, int count,
281 			     struct regmap **mapp);
282 
283 /**
284  * regmap_get_range() - Obtain the base memory address of a regmap range
285  *
286  * @map:	Regmap to query
287  * @range_num:	Range to look up
288  * Return: Pointer to the range in question if OK, NULL on error
289  */
290 void *regmap_get_range(struct regmap *map, unsigned int range_num);
291 
292 /**
293  * regmap_uninit() - free a previously inited regmap
294  *
295  * @map:	Regmap to free
296  * Return: 0 if OK, -ve on error
297  */
298 int regmap_uninit(struct regmap *map);
299 
300 #endif
301