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 /**
  79  * struct regmap - a way of accessing hardware/bus registers
  80  *
  81  * @range_count:        Number of ranges available within the map
  82  * @ranges:             Array of ranges
  83  */
  84 struct regmap {
  85         enum regmap_endianness_t endianness;
  86         int range_count;
  87         struct regmap_range ranges[0];
  88 };
  89
  90 /*
  91  * Interface to provide access to registers either through a direct memory
  92  * bus or through a peripheral bus like I2C, SPI.
  93  */
  94
  95 /**
  96  * regmap_write() - Write a 32-bit value to a regmap
  97  *
  98  * @map:        Regmap to write to
  99  * @offset:     Offset in the regmap to write to
 100  * @val:        Data to write to the regmap at the specified offset
 101  *
 102  * Note that this function will only write values of 32 bit width to the
 103  * regmap; if the size of data to be read is different, the regmap_raw_write
 104  * function can be used.
 105  *
 106  * Return: 0 if OK, -ve on error
 107  */
 108 int regmap_write(struct regmap *map, uint offset, uint val);
 109
 110 /**
 111  * regmap_read() - Read a 32-bit value from a regmap
 112  *
 113  * @map:        Regmap to read from
 114  * @offset:     Offset in the regmap to read from
 115  * @valp:       Pointer to the buffer to receive the data read from the regmap
 116  *              at the specified offset
 117  *
 118  * Note that this function will only read values of 32 bit width from the
 119  * regmap; if the size of data to be read is different, the regmap_raw_read
 120  * function can be used.
 121  *
 122  * Return: 0 if OK, -ve on error
 123  */
 124 int regmap_read(struct regmap *map, uint offset, uint *valp);
 125
 126 /**
 127  * regmap_raw_write() - Write a value of specified length to a regmap
 128  *
 129  * @map:        Regmap to write to
 130  * @offset:     Offset in the regmap to write to
 131  * @val:        Value to write to the regmap at the specified offset
 132  * @val_len:    Length of the data to be written to the regmap
 133  *
 134  * Note that this function will, as opposed to regmap_write, write data of
 135  * arbitrary length to the regmap, and not just 32-bit values, and is thus a
 136  * generalized version of regmap_write.
 137  *
 138  * Return: 0 if OK, -ve on error
 139  */
 140 int regmap_raw_write(struct regmap *map, uint offset, const void *val,
 141                      size_t val_len);
 142
 143 /**
 144  * regmap_raw_read() - Read a value of specified length from a regmap
 145  *
 146  * @map:        Regmap to read from
 147  * @offset:     Offset in the regmap to read from
 148  * @valp:       Pointer to the buffer to receive the data read from the regmap
 149  *              at the specified offset
 150  * @val_len:    Length of the data to be read from the regmap
 151  *
 152  * Note that this function will, as opposed to regmap_read, read data of
 153  * arbitrary length from the regmap, and not just 32-bit values, and is thus a
 154  * generalized version of regmap_read.
 155  *
 156  * Return: 0 if OK, -ve on error
 157  */
 158 int regmap_raw_read(struct regmap *map, uint offset, void *valp,
 159                     size_t val_len);
 160
 161 /**
 162  * regmap_raw_write_range() - Write a value of specified length to a range of a
 163  *                            regmap
 164  *
 165  * @map:        Regmap to write to
 166  * @range_num:  Number of the range in the regmap to write to
 167  * @offset:     Offset in the regmap to write to
 168  * @val:        Value to write to the regmap at the specified offset
 169  * @val_len:    Length of the data to be written to the regmap
 170  *
 171  * Return: 0 if OK, -ve on error
 172  */
 173 int regmap_raw_write_range(struct regmap *map, uint range_num, uint offset,
 174                            const void *val, size_t val_len);
 175
 176 /**
 177  * regmap_raw_read_range() - Read a value of specified length from a range of a
 178  *                           regmap
 179  *
 180  * @map:        Regmap to read from
 181  * @range_num:  Number of the range in the regmap to write to
 182  * @offset:     Offset in the regmap to read from
 183  * @valp:       Pointer to the buffer to receive the data read from the regmap
 184  *              at the specified offset
 185  * @val_len:    Length of the data to be read from the regmap
 186  *
 187  * Return: 0 if OK, -ve on error
 188  */
 189 int regmap_raw_read_range(struct regmap *map, uint range_num, uint offset,
 190                           void *valp, size_t val_len);
 191
 192 /**
 193  * regmap_range_set() - Set a value in a regmap range described by a struct
 194  * @map:    Regmap in which a value should be set
 195  * @range:  Range of the regmap in which a value should be set
 196  * @type:   Structure type that describes the memory layout of the regmap range
 197  * @member: Member of the describing structure that should be set in the regmap
 198  *          range
 199  * @val:    Value which should be written to the regmap range
 200  */
 201 #define regmap_range_set(map, range, type, member, val) \
 202         do { \
 203                 typeof(((type *)0)->member) __tmp = val; \
 204                 regmap_raw_write_range(map, range, offsetof(type, member), \
 205                                        &__tmp, sizeof(((type *)0)->member)); \
 206         } while (0)
 207
 208 /**
 209  * regmap_set() - Set a value in a regmap described by a struct
 210  * @map:    Regmap in which a value should be set
 211  * @type:   Structure type that describes the memory layout of the regmap
 212  * @member: Member of the describing structure that should be set in the regmap
 213  * @val:    Value which should be written to the regmap
 214  */
 215 #define regmap_set(map, type, member, val) \
 216         regmap_range_set(map, 0, type, member, val)
 217
 218 /**
 219  * regmap_range_get() - Get a value from a regmap range described by a struct
 220  * @map:    Regmap from which a value should be read
 221  * @range:  Range of the regmap from which a value should be read
 222  * @type:   Structure type that describes the memory layout of the regmap
 223  *          range
 224  * @member: Member of the describing structure that should be read in the
 225  *          regmap range
 226  * @valp:   Variable that receives the value read from the regmap range
 227  */
 228 #define regmap_range_get(map, range, type, member, valp) \
 229         regmap_raw_read_range(map, range, offsetof(type, member), \
 230                               (void *)valp, sizeof(((type *)0)->member))
 231
 232 /**
 233  * regmap_get() - Get a value from a regmap described by a struct
 234  * @map:    Regmap from which a value should be read
 235  * @type:   Structure type that describes the memory layout of the regmap
 236  *          range
 237  * @member: Member of the describing structure that should be read in the
 238  *          regmap
 239  * @valp:   Variable that receives the value read from the regmap
 240  */
 241 #define regmap_get(map, type, member, valp) \
 242         regmap_range_get(map, 0, type, member, valp)
 243
 244 /**
 245  * regmap_read_poll_timeout - Poll until a condition is met or a timeout occurs
 246  *
 247  * @map:        Regmap to read from
 248  * @addr:       Offset to poll
 249  * @val:        Unsigned integer variable to read the value into
 250  * @cond:       Break condition (usually involving @val)
 251  * @sleep_us:   Maximum time to sleep between reads in us (0 tight-loops).
 252  * @timeout_ms: Timeout in ms, 0 means never timeout
 253  * @test_add_time: Used for sandbox testing - amount of time to add after
 254  *              starting the loop (0 if not testing)
 255  *
 256  * Returns 0 on success and -ETIMEDOUT upon a timeout or the regmap_read
 257  * error return value in case of a error read. In the two former cases,
 258  * the last read value at @addr is stored in @val. Must not be called
 259  * from atomic context if sleep_us or timeout_us are used.
 260  *
 261  * This is modelled after the regmap_read_poll_timeout macros in linux but
 262  * with millisecond timeout.
 263  *
 264  * The _test version is for sandbox testing only. Do not use this in normal
 265  * code as it advances the timer.
 266  */
 267 #define regmap_read_poll_timeout_test(map, addr, val, cond, sleep_us, \
 268                                       timeout_ms, test_add_time) \
 269 ({ \
 270         unsigned long __start = get_timer(0); \
 271         int __ret; \
 272         for (;;) { \
 273                 __ret = regmap_read((map), (addr), &(val)); \
 274                 if (__ret) \
 275                         break; \
 276                 if (cond) \
 277                         break; \
 278                 if (IS_ENABLED(CONFIG_SANDBOX) && test_add_time) \
 279                         timer_test_add_offset(test_add_time); \
 280                 if ((timeout_ms) && get_timer(__start) > (timeout_ms)) { \
 281                         __ret = regmap_read((map), (addr), &(val)); \
 282                         break; \
 283                 } \
 284                 if ((sleep_us)) \
 285                         udelay((sleep_us)); \
 286         } \
 287         __ret ?: ((cond) ? 0 : -ETIMEDOUT); \
 288 })
 289
 290 #define regmap_read_poll_timeout(map, addr, val, cond, sleep_us, timeout_ms) \
 291         regmap_read_poll_timeout_test(map, addr, val, cond, sleep_us, \
 292                                       timeout_ms, 0) \
 293
 294 /**
 295  * regmap_update_bits() - Perform a read/modify/write using a mask
 296  *
 297  * @map:        The map returned by regmap_init_mem*()
 298  * @offset:     Offset of the memory
 299  * @mask:       Mask to apply to the read value
 300  * @val:        Value to OR with the read value after masking. Note that any
 301  *      bits set in @val which are not set in @mask are ignored
 302  * Return: 0 if OK, -ve on error
 303  */
 304 int regmap_update_bits(struct regmap *map, uint offset, uint mask, uint val);
 305
 306 /**
 307  * regmap_init_mem() - Set up a new register map that uses memory access
 308  *
 309  * @node:       Device node that uses this map
 310  * @mapp:       Returns allocated map
 311  * Return: 0 if OK, -ve on error
 312  *
 313  * Use regmap_uninit() to free it.
 314  */
 315 int regmap_init_mem(ofnode node, struct regmap **mapp);
 316
 317 /**
 318  * regmap_init_mem_platdata() - Set up a new memory register map for
 319  *                              of-platdata
 320  *
 321  * @dev:        Device that uses this map
 322  * @reg:        List of address, size pairs
 323  * @count:      Number of pairs (e.g. 1 if the regmap has a single entry)
 324  * @mapp:       Returns allocated map
 325  * Return: 0 if OK, -ve on error
 326  *
 327  * This creates a new regmap with a list of regions passed in, rather than
 328  * using the device tree. It only supports 32-bit machines.
 329  *
 330  * Use regmap_uninit() to free it.
 331  *
 332  */
 333 int regmap_init_mem_platdata(struct udevice *dev, fdt_val_t *reg, int count,
 334                              struct regmap **mapp);
 335
 336 int regmap_init_mem_index(ofnode node, struct regmap **mapp, int index);
 337
 338 /**
 339  * regmap_get_range() - Obtain the base memory address of a regmap range
 340  *
 341  * @map:        Regmap to query
 342  * @range_num:  Range to look up
 343  * Return: Pointer to the range in question if OK, NULL on error
 344  */
 345 void *regmap_get_range(struct regmap *map, unsigned int range_num);
 346
 347 /**
 348  * regmap_uninit() - free a previously inited regmap
 349  *
 350  * @map:        Regmap to free
 351  * Return: 0 if OK, -ve on error
 352  */
 353 int regmap_uninit(struct regmap *map);
 354
 355 #endif