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