blob: 3cd7a66cea70a16ad3161ac73ab25146e1263743 [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
10/**
Mario Sixa6d4b062018-10-15 09:24:15 +020011 * 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/**
Mario Six84ff8f62018-10-15 09:24:10 +020038 * 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 */
45enum 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/**
Mario Six9b77fe32018-10-15 09:24:14 +020053 * 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 */
59enum regmap_endianness_t {
60 REGMAP_NATIVE_ENDIAN,
61 REGMAP_LITTLE_ENDIAN,
62 REGMAP_BIG_ENDIAN,
63};
64
65/**
Simon Glass6f98b752015-06-23 15:38:42 -060066 * struct regmap_range - a register map range
67 *
68 * @start: Start address
69 * @size: Size in bytes
70 */
71struct regmap_range {
72 ulong start;
73 ulong size;
74};
75
76/**
77 * struct regmap - a way of accessing hardware/bus registers
78 *
Mario Six604b6692018-10-04 09:00:41 +020079 * @range_count: Number of ranges available within the map
80 * @ranges: Array of ranges
Simon Glass6f98b752015-06-23 15:38:42 -060081 */
82struct regmap {
Mario Six9b77fe32018-10-15 09:24:14 +020083 enum regmap_endianness_t endianness;
Simon Glass6f98b752015-06-23 15:38:42 -060084 int range_count;
Masahiro Yamada8c1de5e2018-04-19 12:14:01 +090085 struct regmap_range ranges[0];
Simon Glass6f98b752015-06-23 15:38:42 -060086};
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 */
Mario Six604b6692018-10-04 09:00:41 +020092
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 *
Mario Six84ff8f62018-10-15 09:24:10 +0200100 * 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 *
Mario Six604b6692018-10-04 09:00:41 +0200104 * Return: 0 if OK, -ve on error
105 */
Simon Glass6f98b752015-06-23 15:38:42 -0600106int regmap_write(struct regmap *map, uint offset, uint val);
Mario Six604b6692018-10-04 09:00:41 +0200107
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 *
Mario Six84ff8f62018-10-15 09:24:10 +0200116 * 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 *
Mario Six604b6692018-10-04 09:00:41 +0200120 * Return: 0 if OK, -ve on error
121 */
Simon Glass6f98b752015-06-23 15:38:42 -0600122int regmap_read(struct regmap *map, uint offset, uint *valp);
123
Mario Six84ff8f62018-10-15 09:24:10 +0200124/**
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 */
138int 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 */
156int regmap_raw_read(struct regmap *map, uint offset, void *valp,
157 size_t val_len);
158
Mario Sixd5c7bd92018-10-15 09:24:11 +0200159/**
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 */
171int 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 */
187int regmap_raw_read_range(struct regmap *map, uint range_num, uint offset,
188 void *valp, size_t val_len);
189
Mario Sixe9363972018-10-15 09:24:12 +0200190/**
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)
Simon Glass6f98b752015-06-23 15:38:42 -0600205
Mario Sixe9363972018-10-15 09:24:12 +0200206/**
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)
Simon Glass6f98b752015-06-23 15:38:42 -0600241
242/**
Neil Armstrongd13801e2018-11-22 11:01:03 +0100243 * 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
Simon Glassdf9cf1c2018-12-09 17:11:10 -0700251 * @test_add_time: Used for sandbox testing - amount of time to add after
252 * starting the loop (0 if not testing)
Neil Armstrongd13801e2018-11-22 11:01:03 +0100253 *
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.
Simon Glassdf9cf1c2018-12-09 17:11:10 -0700261 *
262 * The _test version is for sandbox testing only. Do not use this in normal
263 * code as it advances the timer.
Neil Armstrongd13801e2018-11-22 11:01:03 +0100264 */
Simon Glassdf9cf1c2018-12-09 17:11:10 -0700265#define regmap_read_poll_timeout_test(map, addr, val, cond, sleep_us, \
266 timeout_ms, test_add_time) \
Neil Armstrongd13801e2018-11-22 11:01:03 +0100267({ \
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; \
Simon Glassdf9cf1c2018-12-09 17:11:10 -0700276 if (IS_ENABLED(CONFIG_SANDBOX) && test_add_time) \
Neil Armstrongd0a9b822019-04-11 17:01:23 +0200277 timer_test_add_offset(test_add_time); \
Neil Armstrongd13801e2018-11-22 11:01:03 +0100278 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
Simon Glassdf9cf1c2018-12-09 17:11:10 -0700288#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
Neil Armstrongd13801e2018-11-22 11:01:03 +0100292/**
Neil Armstrong285cbcf2018-04-27 11:56:14 +0200293 * 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
Mario Six604b6692018-10-04 09:00:41 +0200299 * Return: 0 if OK, -ve on error
Neil Armstrong285cbcf2018-04-27 11:56:14 +0200300 */
301int regmap_update_bits(struct regmap *map, uint offset, uint mask, uint val);
302
303/**
Simon Glass6f98b752015-06-23 15:38:42 -0600304 * regmap_init_mem() - Set up a new register map that uses memory access
305 *
Masahiro Yamadad3581232018-04-19 12:14:03 +0900306 * @node: Device node that uses this map
Simon Glass6f98b752015-06-23 15:38:42 -0600307 * @mapp: Returns allocated map
Mario Six604b6692018-10-04 09:00:41 +0200308 * Return: 0 if OK, -ve on error
309 *
310 * Use regmap_uninit() to free it.
Simon Glass6f98b752015-06-23 15:38:42 -0600311 */
Masahiro Yamadad3581232018-04-19 12:14:03 +0900312int regmap_init_mem(ofnode node, struct regmap **mapp);
Simon Glass6f98b752015-06-23 15:38:42 -0600313
Simon Glass1e6ca1a2016-07-04 11:58:22 -0600314/**
Mario Six604b6692018-10-04 09:00:41 +0200315 * 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
Simon Glass1e6ca1a2016-07-04 11:58:22 -0600323 *
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 *
Simon Glass1e6ca1a2016-07-04 11:58:22 -0600329 */
Simon Glassc20ee0e2017-08-29 14:15:50 -0600330int regmap_init_mem_platdata(struct udevice *dev, fdt_val_t *reg, int count,
Simon Glass3b2a29e2016-07-04 11:57:59 -0600331 struct regmap **mapp);
332
Simon Glass6f98b752015-06-23 15:38:42 -0600333/**
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
Mario Six604b6692018-10-04 09:00:41 +0200338 * Return: Pointer to the range in question if OK, NULL on error
Simon Glass6f98b752015-06-23 15:38:42 -0600339 */
340void *regmap_get_range(struct regmap *map, unsigned int range_num);
341
342/**
343 * regmap_uninit() - free a previously inited regmap
Mario Six604b6692018-10-04 09:00:41 +0200344 *
345 * @map: Regmap to free
346 * Return: 0 if OK, -ve on error
Simon Glass6f98b752015-06-23 15:38:42 -0600347 */
348int regmap_uninit(struct regmap *map);
349
350#endif