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