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 */ 47enum 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 */ 61enum 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 */ 73struct regmap_range { 74 ulong start; 75 ulong size; 76}; 77 78struct 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 */ 92struct 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 */ 109struct 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 */ 131int 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 */ 143int 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 */ 160int 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 */ 179int 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 */ 194int 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 */ 210int 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 */ 362int 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 */ 373int 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 * @size: Size of one reg array item 382 * @count: Number of pairs (e.g. 1 if the regmap has a single entry) 383 * @mapp: Returns allocated map 384 * Return: 0 if OK, -ve on error 385 * 386 * This creates a new regmap with a list of regions passed in, rather than 387 * using the device tree. 388 * 389 * Use regmap_uninit() to free it. 390 * 391 */ 392int regmap_init_mem_plat(struct udevice *dev, void *reg, int size, int count, 393 struct regmap **mapp); 394 395int regmap_init_mem_index(ofnode node, struct regmap **mapp, int index); 396 397/** 398 * regmap_init_mem_range() - Set up a new memory region for ofnode with the 399 * specified range. 400 * 401 * @node: The ofnode for the map. 402 * @r_start: Start of the range. 403 * @r_size: Size of the range. 404 * @mapp: Returns allocated map. 405 * 406 * Return: 0 in success, -errno otherwise 407 * 408 * This creates a regmap with one range where instead of extracting the range 409 * from 'node', it is created based on the parameters specified. This is 410 * useful when a driver needs to calculate the base of the regmap at runtime, 411 * and can't specify it in device tree. 412 */ 413int regmap_init_mem_range(ofnode node, ulong r_start, ulong r_size, 414 struct regmap **mapp); 415 416/** 417 * devm_regmap_init() - Initialise register map (device managed) 418 * 419 * @dev: Device that will be interacted with 420 * @bus: Bus-specific callbacks to use with device (IGNORED) 421 * @bus_context: Data passed to bus-specific callbacks (IGNORED) 422 * @config: Configuration for register map 423 * 424 * @Return a valid pointer to a struct regmap or a ERR_PTR() on error. 425 * The structure is automatically freed when the device is unbound 426 */ 427struct regmap *devm_regmap_init(struct udevice *dev, 428 const struct regmap_bus *bus, 429 void *bus_context, 430 const struct regmap_config *config); 431/** 432 * regmap_get_range() - Obtain the base memory address of a regmap range 433 * 434 * @map: Regmap to query 435 * @range_num: Range to look up 436 * Return: Pointer to the range in question if OK, NULL on error 437 */ 438void *regmap_get_range(struct regmap *map, unsigned int range_num); 439 440/** 441 * regmap_uninit() - free a previously inited regmap 442 * 443 * @map: Regmap to free 444 * Return: 0 if OK, -ve on error 445 */ 446int regmap_uninit(struct regmap *map); 447 448/** 449 * struct reg_field - Description of an register field 450 * 451 * @reg: Offset of the register within the regmap bank 452 * @lsb: lsb of the register field. 453 * @msb: msb of the register field. 454 */ 455struct reg_field { 456 unsigned int reg; 457 unsigned int lsb; 458 unsigned int msb; 459}; 460 461struct regmap_field; 462 463/** 464 * REG_FIELD() - A convenient way to initialize a 'struct reg_field'. 465 * 466 * @_reg: Offset of the register within the regmap bank 467 * @_lsb: lsb of the register field. 468 * @_msb: msb of the register field. 469 * 470 * Register fields are often described in terms of 3 things: the register it 471 * belongs to, its LSB, and its MSB. This macro can be used by drivers to 472 * clearly and easily initialize a 'struct regmap_field'. 473 * 474 * For example, say a device has a register at offset DEV_REG1 (0x100) and a 475 * field of DEV_REG1 is on bits [7:3]. So a driver can initialize a regmap 476 * field for this by doing: 477 * struct reg_field field = REG_FIELD(DEV_REG1, 3, 7); 478 */ 479#define REG_FIELD(_reg, _lsb, _msb) { \ 480 .reg = _reg, \ 481 .lsb = _lsb, \ 482 .msb = _msb, \ 483 } 484 485/** 486 * devm_regmap_field_alloc() - Allocate and initialise a register field. 487 * 488 * @dev: Device that will be interacted with 489 * @regmap: regmap bank in which this register field is located. 490 * @reg_field: Register field with in the bank. 491 * 492 * The return value will be an ERR_PTR() on error or a valid pointer 493 * to a struct regmap_field. The regmap_field will be automatically freed 494 * by the device management code. 495 */ 496struct regmap_field *devm_regmap_field_alloc(struct udevice *dev, 497 struct regmap *regmap, 498 struct reg_field reg_field); 499/** 500 * devm_regmap_field_free() - Free a register field allocated using 501 * devm_regmap_field_alloc. 502 * 503 * @dev: Device that will be interacted with 504 * @field: regmap field which should be freed. 505 * 506 * Free register field allocated using devm_regmap_field_alloc(). Usually 507 * drivers need not call this function, as the memory allocated via devm 508 * will be freed as per device-driver life-cyle. 509 */ 510void devm_regmap_field_free(struct udevice *dev, struct regmap_field *field); 511 512/** 513 * regmap_field_write() - Write a value to a regmap field 514 * 515 * @field: Regmap field to write to 516 * @val: Data to write to the regmap at the specified offset 517 * 518 * Return: 0 if OK, -ve on error 519 */ 520int regmap_field_write(struct regmap_field *field, unsigned int val); 521 522/** 523 * regmap_field_read() - Read a 32-bit value from a regmap 524 * 525 * @field: Regmap field to read from 526 * @valp: Pointer to the buffer to receive the data read from the regmap 527 * field 528 * 529 * Return: 0 if OK, -ve on error 530 */ 531int regmap_field_read(struct regmap_field *field, unsigned int *val); 532 533#endif 534