include/regmap.h

   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  * @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  */
 392 int regmap_init_mem_plat(struct udevice *dev, void *reg, int size, int count,
 393                          struct regmap **mapp);
 394
 395 int 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  */
 413 int 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  */
 427 struct 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  */
 438 void *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  */
 446 int 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  */
 455 struct reg_field {
 456         unsigned int reg;
 457         unsigned int lsb;
 458         unsigned int msb;
 459 };
 460
 461 struct 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  */
 496 struct 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  */
 510 void 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  */
 520 int 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  */
 531 int regmap_field_read(struct regmap_field *field, unsigned int *val);
 532
 533 #endif