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_plat() - 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_plat(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 533