include/linux/regmap.h

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