1 #ifndef __LINUX_REGMAP_H 2 #define __LINUX_REGMAP_H 3 4 /* 5 * Register map access API 6 * 7 * Copyright 2011 Wolfson Microelectronics plc 8 * 9 * Author: Mark Brown <[email protected]> 10 * 11 * This program is free software; you can redistribute it and/or modify 12 * it under the terms of the GNU General Public License version 2 as 13 * published by the Free Software Foundation. 14 */ 15 16 #include <linux/list.h> 17 #include <linux/rbtree.h> 18 #include <linux/err.h> 19 #include <linux/bug.h> 20 21 struct module; 22 struct device; 23 struct i2c_client; 24 struct irq_domain; 25 struct spi_device; 26 struct regmap; 27 struct regmap_range_cfg; 28 struct regmap_field; 29 30 /* An enum of all the supported cache types */ 31 enum regcache_type { 32 REGCACHE_NONE, 33 REGCACHE_RBTREE, 34 REGCACHE_COMPRESSED, 35 REGCACHE_FLAT, 36 }; 37 38 /** 39 * Default value for a register. We use an array of structs rather 40 * than a simple array as many modern devices have very sparse 41 * register maps. 42 * 43 * @reg: Register address. 44 * @def: Register default value. 45 */ 46 struct reg_default { 47 unsigned int reg; 48 unsigned int def; 49 }; 50 51 #ifdef CONFIG_REGMAP 52 53 enum regmap_endian { 54 /* Unspecified -> 0 -> Backwards compatible default */ 55 REGMAP_ENDIAN_DEFAULT = 0, 56 REGMAP_ENDIAN_BIG, 57 REGMAP_ENDIAN_LITTLE, 58 REGMAP_ENDIAN_NATIVE, 59 }; 60 61 /** 62 * A register range, used for access related checks 63 * (readable/writeable/volatile/precious checks) 64 * 65 * @range_min: address of first register 66 * @range_max: address of last register 67 */ 68 struct regmap_range { 69 unsigned int range_min; 70 unsigned int range_max; 71 }; 72 73 /* 74 * A table of ranges including some yes ranges and some no ranges. 75 * If a register belongs to a no_range, the corresponding check function 76 * will return false. If a register belongs to a yes range, the corresponding 77 * check function will return true. "no_ranges" are searched first. 78 * 79 * @yes_ranges : pointer to an array of regmap ranges used as "yes ranges" 80 * @n_yes_ranges: size of the above array 81 * @no_ranges: pointer to an array of regmap ranges used as "no ranges" 82 * @n_no_ranges: size of the above array 83 */ 84 struct regmap_access_table { 85 const struct regmap_range *yes_ranges; 86 unsigned int n_yes_ranges; 87 const struct regmap_range *no_ranges; 88 unsigned int n_no_ranges; 89 }; 90 91 typedef void (*regmap_lock)(void *); 92 typedef void (*regmap_unlock)(void *); 93 94 /** 95 * Configuration for the register map of a device. 96 * 97 * @name: Optional name of the regmap. Useful when a device has multiple 98 * register regions. 99 * 100 * @reg_bits: Number of bits in a register address, mandatory. 101 * @reg_stride: The register address stride. Valid register addresses are a 102 * multiple of this value. If set to 0, a value of 1 will be 103 * used. 104 * @pad_bits: Number of bits of padding between register and value. 105 * @val_bits: Number of bits in a register value, mandatory. 106 * 107 * @writeable_reg: Optional callback returning true if the register 108 * can be written to. If this field is NULL but wr_table 109 * (see below) is not, the check is performed on such table 110 * (a register is writeable if it belongs to one of the ranges 111 * specified by wr_table). 112 * @readable_reg: Optional callback returning true if the register 113 * can be read from. If this field is NULL but rd_table 114 * (see below) is not, the check is performed on such table 115 * (a register is readable if it belongs to one of the ranges 116 * specified by rd_table). 117 * @volatile_reg: Optional callback returning true if the register 118 * value can't be cached. If this field is NULL but 119 * volatile_table (see below) is not, the check is performed on 120 * such table (a register is volatile if it belongs to one of 121 * the ranges specified by volatile_table). 122 * @precious_reg: Optional callback returning true if the rgister 123 * should not be read outside of a call from the driver 124 * (eg, a clear on read interrupt status register). If this 125 * field is NULL but precious_table (see below) is not, the 126 * check is performed on such table (a register is precious if 127 * it belongs to one of the ranges specified by precious_table). 128 * @lock: Optional lock callback (overrides regmap's default lock 129 * function, based on spinlock or mutex). 130 * @unlock: As above for unlocking. 131 * @lock_arg: this field is passed as the only argument of lock/unlock 132 * functions (ignored in case regular lock/unlock functions 133 * are not overridden). 134 * @reg_read: Optional callback that if filled will be used to perform 135 * all the reads from the registers. Should only be provided for 136 * devices whos read operation cannot be represented as a simple read 137 * operation on a bus such as SPI, I2C, etc. Most of the devices do 138 * not need this. 139 * @reg_write: Same as above for writing. 140 * @fast_io: Register IO is fast. Use a spinlock instead of a mutex 141 * to perform locking. This field is ignored if custom lock/unlock 142 * functions are used (see fields lock/unlock of struct regmap_config). 143 * This field is a duplicate of a similar file in 144 * 'struct regmap_bus' and serves exact same purpose. 145 * Use it only for "no-bus" cases. 146 * @max_register: Optional, specifies the maximum valid register index. 147 * @wr_table: Optional, points to a struct regmap_access_table specifying 148 * valid ranges for write access. 149 * @rd_table: As above, for read access. 150 * @volatile_table: As above, for volatile registers. 151 * @precious_table: As above, for precious registers. 152 * @reg_defaults: Power on reset values for registers (for use with 153 * register cache support). 154 * @num_reg_defaults: Number of elements in reg_defaults. 155 * 156 * @read_flag_mask: Mask to be set in the top byte of the register when doing 157 * a read. 158 * @write_flag_mask: Mask to be set in the top byte of the register when doing 159 * a write. If both read_flag_mask and write_flag_mask are 160 * empty the regmap_bus default masks are used. 161 * @use_single_rw: If set, converts the bulk read and write operations into 162 * a series of single read and write operations. This is useful 163 * for device that does not support bulk read and write. 164 * 165 * @cache_type: The actual cache type. 166 * @reg_defaults_raw: Power on reset values for registers (for use with 167 * register cache support). 168 * @num_reg_defaults_raw: Number of elements in reg_defaults_raw. 169 * @reg_format_endian: Endianness for formatted register addresses. If this is 170 * DEFAULT, the @reg_format_endian_default value from the 171 * regmap bus is used. 172 * @val_format_endian: Endianness for formatted register values. If this is 173 * DEFAULT, the @reg_format_endian_default value from the 174 * regmap bus is used. 175 * 176 * @ranges: Array of configuration entries for virtual address ranges. 177 * @num_ranges: Number of range configuration entries. 178 */ 179 struct regmap_config { 180 const char *name; 181 182 int reg_bits; 183 int reg_stride; 184 int pad_bits; 185 int val_bits; 186 187 bool (*writeable_reg)(struct device *dev, unsigned int reg); 188 bool (*readable_reg)(struct device *dev, unsigned int reg); 189 bool (*volatile_reg)(struct device *dev, unsigned int reg); 190 bool (*precious_reg)(struct device *dev, unsigned int reg); 191 regmap_lock lock; 192 regmap_unlock unlock; 193 void *lock_arg; 194 195 int (*reg_read)(void *context, unsigned int reg, unsigned int *val); 196 int (*reg_write)(void *context, unsigned int reg, unsigned int val); 197 198 bool fast_io; 199 200 unsigned int max_register; 201 const struct regmap_access_table *wr_table; 202 const struct regmap_access_table *rd_table; 203 const struct regmap_access_table *volatile_table; 204 const struct regmap_access_table *precious_table; 205 const struct reg_default *reg_defaults; 206 unsigned int num_reg_defaults; 207 enum regcache_type cache_type; 208 const void *reg_defaults_raw; 209 unsigned int num_reg_defaults_raw; 210 211 u8 read_flag_mask; 212 u8 write_flag_mask; 213 214 bool use_single_rw; 215 216 enum regmap_endian reg_format_endian; 217 enum regmap_endian val_format_endian; 218 219 const struct regmap_range_cfg *ranges; 220 unsigned int num_ranges; 221 }; 222 223 /** 224 * Configuration for indirectly accessed or paged registers. 225 * Registers, mapped to this virtual range, are accessed in two steps: 226 * 1. page selector register update; 227 * 2. access through data window registers. 228 * 229 * @name: Descriptive name for diagnostics 230 * 231 * @range_min: Address of the lowest register address in virtual range. 232 * @range_max: Address of the highest register in virtual range. 233 * 234 * @page_sel_reg: Register with selector field. 235 * @page_sel_mask: Bit shift for selector value. 236 * @page_sel_shift: Bit mask for selector value. 237 * 238 * @window_start: Address of first (lowest) register in data window. 239 * @window_len: Number of registers in data window. 240 */ 241 struct regmap_range_cfg { 242 const char *name; 243 244 /* Registers of virtual address range */ 245 unsigned int range_min; 246 unsigned int range_max; 247 248 /* Page selector for indirect addressing */ 249 unsigned int selector_reg; 250 unsigned int selector_mask; 251 int selector_shift; 252 253 /* Data window (per each page) */ 254 unsigned int window_start; 255 unsigned int window_len; 256 }; 257 258 struct regmap_async; 259 260 typedef int (*regmap_hw_write)(void *context, const void *data, 261 size_t count); 262 typedef int (*regmap_hw_gather_write)(void *context, 263 const void *reg, size_t reg_len, 264 const void *val, size_t val_len); 265 typedef int (*regmap_hw_async_write)(void *context, 266 const void *reg, size_t reg_len, 267 const void *val, size_t val_len, 268 struct regmap_async *async); 269 typedef int (*regmap_hw_read)(void *context, 270 const void *reg_buf, size_t reg_size, 271 void *val_buf, size_t val_size); 272 typedef struct regmap_async *(*regmap_hw_async_alloc)(void); 273 typedef void (*regmap_hw_free_context)(void *context); 274 275 /** 276 * Description of a hardware bus for the register map infrastructure. 277 * 278 * @fast_io: Register IO is fast. Use a spinlock instead of a mutex 279 * to perform locking. This field is ignored if custom lock/unlock 280 * functions are used (see fields lock/unlock of 281 * struct regmap_config). 282 * @write: Write operation. 283 * @gather_write: Write operation with split register/value, return -ENOTSUPP 284 * if not implemented on a given device. 285 * @async_write: Write operation which completes asynchronously, optional and 286 * must serialise with respect to non-async I/O. 287 * @read: Read operation. Data is returned in the buffer used to transmit 288 * data. 289 * @async_alloc: Allocate a regmap_async() structure. 290 * @read_flag_mask: Mask to be set in the top byte of the register when doing 291 * a read. 292 * @reg_format_endian_default: Default endianness for formatted register 293 * addresses. Used when the regmap_config specifies DEFAULT. If this is 294 * DEFAULT, BIG is assumed. 295 * @val_format_endian_default: Default endianness for formatted register 296 * values. Used when the regmap_config specifies DEFAULT. If this is 297 * DEFAULT, BIG is assumed. 298 * @async_size: Size of struct used for async work. 299 */ 300 struct regmap_bus { 301 bool fast_io; 302 regmap_hw_write write; 303 regmap_hw_gather_write gather_write; 304 regmap_hw_async_write async_write; 305 regmap_hw_read read; 306 regmap_hw_free_context free_context; 307 regmap_hw_async_alloc async_alloc; 308 u8 read_flag_mask; 309 enum regmap_endian reg_format_endian_default; 310 enum regmap_endian val_format_endian_default; 311 }; 312 313 struct regmap *regmap_init(struct device *dev, 314 const struct regmap_bus *bus, 315 void *bus_context, 316 const struct regmap_config *config); 317 struct regmap *regmap_init_i2c(struct i2c_client *i2c, 318 const struct regmap_config *config); 319 struct regmap *regmap_init_spi(struct spi_device *dev, 320 const struct regmap_config *config); 321 struct regmap *regmap_init_mmio_clk(struct device *dev, const char *clk_id, 322 void __iomem *regs, 323 const struct regmap_config *config); 324 325 struct regmap *devm_regmap_init(struct device *dev, 326 const struct regmap_bus *bus, 327 void *bus_context, 328 const struct regmap_config *config); 329 struct regmap *devm_regmap_init_i2c(struct i2c_client *i2c, 330 const struct regmap_config *config); 331 struct regmap *devm_regmap_init_spi(struct spi_device *dev, 332 const struct regmap_config *config); 333 struct regmap *devm_regmap_init_mmio_clk(struct device *dev, const char *clk_id, 334 void __iomem *regs, 335 const struct regmap_config *config); 336 337 /** 338 * regmap_init_mmio(): Initialise register map 339 * 340 * @dev: Device that will be interacted with 341 * @regs: Pointer to memory-mapped IO region 342 * @config: Configuration for register map 343 * 344 * The return value will be an ERR_PTR() on error or a valid pointer to 345 * a struct regmap. 346 */ 347 static inline struct regmap *regmap_init_mmio(struct device *dev, 348 void __iomem *regs, 349 const struct regmap_config *config) 350 { 351 return regmap_init_mmio_clk(dev, NULL, regs, config); 352 } 353 354 /** 355 * devm_regmap_init_mmio(): Initialise managed register map 356 * 357 * @dev: Device that will be interacted with 358 * @regs: Pointer to memory-mapped IO region 359 * @config: Configuration for register map 360 * 361 * The return value will be an ERR_PTR() on error or a valid pointer 362 * to a struct regmap. The regmap will be automatically freed by the 363 * device management code. 364 */ 365 static inline struct regmap *devm_regmap_init_mmio(struct device *dev, 366 void __iomem *regs, 367 const struct regmap_config *config) 368 { 369 return devm_regmap_init_mmio_clk(dev, NULL, regs, config); 370 } 371 372 void regmap_exit(struct regmap *map); 373 int regmap_reinit_cache(struct regmap *map, 374 const struct regmap_config *config); 375 struct regmap *dev_get_regmap(struct device *dev, const char *name); 376 int regmap_write(struct regmap *map, unsigned int reg, unsigned int val); 377 int regmap_raw_write(struct regmap *map, unsigned int reg, 378 const void *val, size_t val_len); 379 int regmap_bulk_write(struct regmap *map, unsigned int reg, const void *val, 380 size_t val_count); 381 int regmap_raw_write_async(struct regmap *map, unsigned int reg, 382 const void *val, size_t val_len); 383 int regmap_read(struct regmap *map, unsigned int reg, unsigned int *val); 384 int regmap_raw_read(struct regmap *map, unsigned int reg, 385 void *val, size_t val_len); 386 int regmap_bulk_read(struct regmap *map, unsigned int reg, void *val, 387 size_t val_count); 388 int regmap_update_bits(struct regmap *map, unsigned int reg, 389 unsigned int mask, unsigned int val); 390 int regmap_update_bits_check(struct regmap *map, unsigned int reg, 391 unsigned int mask, unsigned int val, 392 bool *change); 393 int regmap_get_val_bytes(struct regmap *map); 394 int regmap_async_complete(struct regmap *map); 395 bool regmap_can_raw_write(struct regmap *map); 396 397 int regcache_sync(struct regmap *map); 398 int regcache_sync_region(struct regmap *map, unsigned int min, 399 unsigned int max); 400 int regcache_drop_region(struct regmap *map, unsigned int min, 401 unsigned int max); 402 void regcache_cache_only(struct regmap *map, bool enable); 403 void regcache_cache_bypass(struct regmap *map, bool enable); 404 void regcache_mark_dirty(struct regmap *map); 405 406 bool regmap_check_range_table(struct regmap *map, unsigned int reg, 407 const struct regmap_access_table *table); 408 409 int regmap_register_patch(struct regmap *map, const struct reg_default *regs, 410 int num_regs); 411 412 static inline bool regmap_reg_in_range(unsigned int reg, 413 const struct regmap_range *range) 414 { 415 return reg >= range->range_min && reg <= range->range_max; 416 } 417 418 bool regmap_reg_in_ranges(unsigned int reg, 419 const struct regmap_range *ranges, 420 unsigned int nranges); 421 422 /** 423 * Description of an register field 424 * 425 * @reg: Offset of the register within the regmap bank 426 * @lsb: lsb of the register field. 427 * @reg: msb of the register field. 428 */ 429 struct reg_field { 430 unsigned int reg; 431 unsigned int lsb; 432 unsigned int msb; 433 }; 434 435 #define REG_FIELD(_reg, _lsb, _msb) { \ 436 .reg = _reg, \ 437 .lsb = _lsb, \ 438 .msb = _msb, \ 439 } 440 441 struct regmap_field *regmap_field_alloc(struct regmap *regmap, 442 struct reg_field reg_field); 443 void regmap_field_free(struct regmap_field *field); 444 445 struct regmap_field *devm_regmap_field_alloc(struct device *dev, 446 struct regmap *regmap, struct reg_field reg_field); 447 void devm_regmap_field_free(struct device *dev, struct regmap_field *field); 448 449 int regmap_field_read(struct regmap_field *field, unsigned int *val); 450 int regmap_field_write(struct regmap_field *field, unsigned int val); 451 452 /** 453 * Description of an IRQ for the generic regmap irq_chip. 454 * 455 * @reg_offset: Offset of the status/mask register within the bank 456 * @mask: Mask used to flag/control the register. 457 */ 458 struct regmap_irq { 459 unsigned int reg_offset; 460 unsigned int mask; 461 }; 462 463 /** 464 * Description of a generic regmap irq_chip. This is not intended to 465 * handle every possible interrupt controller, but it should handle a 466 * substantial proportion of those that are found in the wild. 467 * 468 * @name: Descriptive name for IRQ controller. 469 * 470 * @status_base: Base status register address. 471 * @mask_base: Base mask register address. 472 * @ack_base: Base ack address. If zero then the chip is clear on read. 473 * @wake_base: Base address for wake enables. If zero unsupported. 474 * @irq_reg_stride: Stride to use for chips where registers are not contiguous. 475 * @runtime_pm: Hold a runtime PM lock on the device when accessing it. 476 * 477 * @num_regs: Number of registers in each control bank. 478 * @irqs: Descriptors for individual IRQs. Interrupt numbers are 479 * assigned based on the index in the array of the interrupt. 480 * @num_irqs: Number of descriptors. 481 */ 482 struct regmap_irq_chip { 483 const char *name; 484 485 unsigned int status_base; 486 unsigned int mask_base; 487 unsigned int ack_base; 488 unsigned int wake_base; 489 unsigned int irq_reg_stride; 490 unsigned int mask_invert; 491 unsigned int wake_invert; 492 bool runtime_pm; 493 494 int num_regs; 495 496 const struct regmap_irq *irqs; 497 int num_irqs; 498 }; 499 500 struct regmap_irq_chip_data; 501 502 int regmap_add_irq_chip(struct regmap *map, int irq, int irq_flags, 503 int irq_base, const struct regmap_irq_chip *chip, 504 struct regmap_irq_chip_data **data); 505 void regmap_del_irq_chip(int irq, struct regmap_irq_chip_data *data); 506 int regmap_irq_chip_get_base(struct regmap_irq_chip_data *data); 507 int regmap_irq_get_virq(struct regmap_irq_chip_data *data, int irq); 508 struct irq_domain *regmap_irq_get_domain(struct regmap_irq_chip_data *data); 509 510 #else 511 512 /* 513 * These stubs should only ever be called by generic code which has 514 * regmap based facilities, if they ever get called at runtime 515 * something is going wrong and something probably needs to select 516 * REGMAP. 517 */ 518 519 static inline int regmap_write(struct regmap *map, unsigned int reg, 520 unsigned int val) 521 { 522 WARN_ONCE(1, "regmap API is disabled"); 523 return -EINVAL; 524 } 525 526 static inline int regmap_raw_write(struct regmap *map, unsigned int reg, 527 const void *val, size_t val_len) 528 { 529 WARN_ONCE(1, "regmap API is disabled"); 530 return -EINVAL; 531 } 532 533 static inline int regmap_raw_write_async(struct regmap *map, unsigned int reg, 534 const void *val, size_t val_len) 535 { 536 WARN_ONCE(1, "regmap API is disabled"); 537 return -EINVAL; 538 } 539 540 static inline int regmap_bulk_write(struct regmap *map, unsigned int reg, 541 const void *val, size_t val_count) 542 { 543 WARN_ONCE(1, "regmap API is disabled"); 544 return -EINVAL; 545 } 546 547 static inline int regmap_read(struct regmap *map, unsigned int reg, 548 unsigned int *val) 549 { 550 WARN_ONCE(1, "regmap API is disabled"); 551 return -EINVAL; 552 } 553 554 static inline int regmap_raw_read(struct regmap *map, unsigned int reg, 555 void *val, size_t val_len) 556 { 557 WARN_ONCE(1, "regmap API is disabled"); 558 return -EINVAL; 559 } 560 561 static inline int regmap_bulk_read(struct regmap *map, unsigned int reg, 562 void *val, size_t val_count) 563 { 564 WARN_ONCE(1, "regmap API is disabled"); 565 return -EINVAL; 566 } 567 568 static inline int regmap_update_bits(struct regmap *map, unsigned int reg, 569 unsigned int mask, unsigned int val) 570 { 571 WARN_ONCE(1, "regmap API is disabled"); 572 return -EINVAL; 573 } 574 575 static inline int regmap_update_bits_check(struct regmap *map, 576 unsigned int reg, 577 unsigned int mask, unsigned int val, 578 bool *change) 579 { 580 WARN_ONCE(1, "regmap API is disabled"); 581 return -EINVAL; 582 } 583 584 static inline int regmap_get_val_bytes(struct regmap *map) 585 { 586 WARN_ONCE(1, "regmap API is disabled"); 587 return -EINVAL; 588 } 589 590 static inline int regcache_sync(struct regmap *map) 591 { 592 WARN_ONCE(1, "regmap API is disabled"); 593 return -EINVAL; 594 } 595 596 static inline int regcache_sync_region(struct regmap *map, unsigned int min, 597 unsigned int max) 598 { 599 WARN_ONCE(1, "regmap API is disabled"); 600 return -EINVAL; 601 } 602 603 static inline int regcache_drop_region(struct regmap *map, unsigned int min, 604 unsigned int max) 605 { 606 WARN_ONCE(1, "regmap API is disabled"); 607 return -EINVAL; 608 } 609 610 static inline void regcache_cache_only(struct regmap *map, bool enable) 611 { 612 WARN_ONCE(1, "regmap API is disabled"); 613 } 614 615 static inline void regcache_cache_bypass(struct regmap *map, bool enable) 616 { 617 WARN_ONCE(1, "regmap API is disabled"); 618 } 619 620 static inline void regcache_mark_dirty(struct regmap *map) 621 { 622 WARN_ONCE(1, "regmap API is disabled"); 623 } 624 625 static inline void regmap_async_complete(struct regmap *map) 626 { 627 WARN_ONCE(1, "regmap API is disabled"); 628 } 629 630 static inline int regmap_register_patch(struct regmap *map, 631 const struct reg_default *regs, 632 int num_regs) 633 { 634 WARN_ONCE(1, "regmap API is disabled"); 635 return -EINVAL; 636 } 637 638 static inline struct regmap *dev_get_regmap(struct device *dev, 639 const char *name) 640 { 641 return NULL; 642 } 643 644 #endif 645 646 #endif 647