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 /**
  11  * DOC: Overview
  12  *
  13  * Regmaps are an abstraction mechanism that allows device drivers to access
  14  * register maps irrespective of the underlying bus architecture. This entails
  15  * that for devices that support multiple busses (e.g. I2C and SPI for a GPIO
  16  * expander chip) only one driver has to be written. This driver will
  17  * instantiate a regmap with a backend depending on the bus the device is
  18  * attached to, and use the regmap API to access the register map through that
  19  * bus transparently.
  20  *
  21  * Read and write functions are supplied, which can read/write data of
  22  * arbitrary length from/to the regmap.
  23  *
  24  * The endianness of regmap accesses is selectable for each map through device
  25  * tree settings via the boolean "little-endian", "big-endian", and
  26  * "native-endian" properties.
  27  *
  28  * Furthermore, the register map described by a regmap can be split into
  29  * multiple disjoint areas called ranges. In this way, register maps with
  30  * "holes", i.e. areas of addressable memory that are not part of the register
  31  * map, can be accessed in a concise manner.
  32  *
  33  * Currently, only a bare "mem" backend for regmaps is supported, which
  34  * accesses the register map as regular IO-mapped memory.
  35  */
  36
  37 /**
  38  * enum regmap_size_t - Access sizes for regmap reads and writes
  39  *
  40  * @REGMAP_SIZE_8: 8-bit read/write access size
  41  * @REGMAP_SIZE_16: 16-bit read/write access size
  42  * @REGMAP_SIZE_32: 32-bit read/write access size
  43  * @REGMAP_SIZE_64: 64-bit read/write access size
  44  */
  45 enum regmap_size_t {
  46         REGMAP_SIZE_8 = 1,
  47         REGMAP_SIZE_16 = 2,
  48         REGMAP_SIZE_32 = 4,
  49         REGMAP_SIZE_64 = 8,
  50 };
  51
  52 /**
  53  * enum regmap_endianness_t - Endianness for regmap reads and writes
  54  *
  55  * @REGMAP_NATIVE_ENDIAN: Native endian read/write accesses
  56  * @REGMAP_LITTLE_ENDIAN: Little endian read/write accesses
  57  * @REGMAP_BIG_ENDIAN: Big endian read/write accesses
  58  */
  59 enum regmap_endianness_t {
  60         REGMAP_NATIVE_ENDIAN,
  61         REGMAP_LITTLE_ENDIAN,
  62         REGMAP_BIG_ENDIAN,
  63 };
  64
  65 /**
  66  * struct regmap_range - a register map range
  67  *
  68  * @start:      Start address
  69  * @size:       Size in bytes
  70  */
  71 struct regmap_range {
  72         ulong start;
  73         ulong size;
  74 };
  75
  76 /**
  77  * struct regmap - a way of accessing hardware/bus registers
  78  *
  79  * @range_count:        Number of ranges available within the map
  80  * @ranges:             Array of ranges
  81  */
  82 struct regmap {
  83         enum regmap_endianness_t endianness;
  84         int range_count;
  85         struct regmap_range ranges[0];
  86 };
  87
  88 /*
  89  * Interface to provide access to registers either through a direct memory
  90  * bus or through a peripheral bus like I2C, SPI.
  91  */
  92
  93 /**
  94  * regmap_write() - Write a 32-bit value to a regmap
  95  *
  96  * @map:        Regmap to write to
  97  * @offset:     Offset in the regmap to write to
  98  * @val:        Data to write to the regmap at the specified offset
  99  *
 100  * Note that this function will only write values of 32 bit width to the
 101  * regmap; if the size of data to be read is different, the regmap_raw_write
 102  * function can be used.
 103  *
 104  * Return: 0 if OK, -ve on error
 105  */
 106 int regmap_write(struct regmap *map, uint offset, uint val);
 107
 108 /**
 109  * regmap_read() - Read a 32-bit value from a regmap
 110  *
 111  * @map:        Regmap to read from
 112  * @offset:     Offset in the regmap to read from
 113  * @valp:       Pointer to the buffer to receive the data read from the regmap
 114  *              at the specified offset
 115  *
 116  * Note that this function will only read values of 32 bit width from the
 117  * regmap; if the size of data to be read is different, the regmap_raw_read
 118  * function can be used.
 119  *
 120  * Return: 0 if OK, -ve on error
 121  */
 122 int regmap_read(struct regmap *map, uint offset, uint *valp);
 123
 124 /**
 125  * regmap_raw_write() - Write a value of specified length to a regmap
 126  *
 127  * @map:        Regmap to write to
 128  * @offset:     Offset in the regmap to write to
 129  * @val:        Value to write to the regmap at the specified offset
 130  * @val_len:    Length of the data to be written to the regmap
 131  *
 132  * Note that this function will, as opposed to regmap_write, write data of
 133  * arbitrary length to the regmap, and not just 32-bit values, and is thus a
 134  * generalized version of regmap_write.
 135  *
 136  * Return: 0 if OK, -ve on error
 137  */
 138 int regmap_raw_write(struct regmap *map, uint offset, const void *val,
 139                      size_t val_len);
 140
 141 /**
 142  * regmap_raw_read() - Read a value of specified length from a regmap
 143  *
 144  * @map:        Regmap to read from
 145  * @offset:     Offset in the regmap to read from
 146  * @valp:       Pointer to the buffer to receive the data read from the regmap
 147  *              at the specified offset
 148  * @val_len:    Length of the data to be read from the regmap
 149  *
 150  * Note that this function will, as opposed to regmap_read, read data of
 151  * arbitrary length from the regmap, and not just 32-bit values, and is thus a
 152  * generalized version of regmap_read.
 153  *
 154  * Return: 0 if OK, -ve on error
 155  */
 156 int regmap_raw_read(struct regmap *map, uint offset, void *valp,
 157                     size_t val_len);
 158
 159 /**
 160  * regmap_raw_write_range() - Write a value of specified length to a range of a
 161  *                            regmap
 162  *
 163  * @map:        Regmap to write to
 164  * @range_num:  Number of the range in the regmap to write to
 165  * @offset:     Offset in the regmap to write to
 166  * @val:        Value to write to the regmap at the specified offset
 167  * @val_len:    Length of the data to be written to the regmap
 168  *
 169  * Return: 0 if OK, -ve on error
 170  */
 171 int regmap_raw_write_range(struct regmap *map, uint range_num, uint offset,
 172                            const void *val, size_t val_len);
 173
 174 /**
 175  * regmap_raw_read_range() - Read a value of specified length from a range of a
 176  *                           regmap
 177  *
 178  * @map:        Regmap to read from
 179  * @range_num:  Number of the range in the regmap to write to
 180  * @offset:     Offset in the regmap to read from
 181  * @valp:       Pointer to the buffer to receive the data read from the regmap
 182  *              at the specified offset
 183  * @val_len:    Length of the data to be read from the regmap
 184  *
 185  * Return: 0 if OK, -ve on error
 186  */
 187 int regmap_raw_read_range(struct regmap *map, uint range_num, uint offset,
 188                           void *valp, size_t val_len);
 189
 190 /**
 191  * regmap_range_set() - Set a value in a regmap range described by a struct
 192  * @map:    Regmap in which a value should be set
 193  * @range:  Range of the regmap in which a value should be set
 194  * @type:   Structure type that describes the memory layout of the regmap range
 195  * @member: Member of the describing structure that should be set in the regmap
 196  *          range
 197  * @val:    Value which should be written to the regmap range
 198  */
 199 #define regmap_range_set(map, range, type, member, val) \
 200         do { \
 201                 typeof(((type *)0)->member) __tmp = val; \
 202                 regmap_raw_write_range(map, range, offsetof(type, member), \
 203                                        &__tmp, sizeof(((type *)0)->member)); \
 204         } while (0)
 205
 206 /**
 207  * regmap_set() - Set a value in a regmap described by a struct
 208  * @map:    Regmap in which a value should be set
 209  * @type:   Structure type that describes the memory layout of the regmap
 210  * @member: Member of the describing structure that should be set in the regmap
 211  * @val:    Value which should be written to the regmap
 212  */
 213 #define regmap_set(map, type, member, val) \
 214         regmap_range_set(map, 0, type, member, val)
 215
 216 /**
 217  * regmap_range_get() - Get a value from a regmap range described by a struct
 218  * @map:    Regmap from which a value should be read
 219  * @range:  Range of the regmap from which a value should be read
 220  * @type:   Structure type that describes the memory layout of the regmap
 221  *          range
 222  * @member: Member of the describing structure that should be read in the
 223  *          regmap range
 224  * @valp:   Variable that receives the value read from the regmap range
 225  */
 226 #define regmap_range_get(map, range, type, member, valp) \
 227         regmap_raw_read_range(map, range, offsetof(type, member), \
 228                               (void *)valp, sizeof(((type *)0)->member))
 229
 230 /**
 231  * regmap_get() - Get a value from a regmap described by a struct
 232  * @map:    Regmap from which a value should be read
 233  * @type:   Structure type that describes the memory layout of the regmap
 234  *          range
 235  * @member: Member of the describing structure that should be read in the
 236  *          regmap
 237  * @valp:   Variable that receives the value read from the regmap
 238  */
 239 #define regmap_get(map, type, member, valp) \
 240         regmap_range_get(map, 0, type, member, valp)
 241
 242 /**
 243  * regmap_read_poll_timeout - Poll until a condition is met or a timeout occurs
 244  *
 245  * @map:        Regmap to read from
 246  * @addr:       Offset to poll
 247  * @val:        Unsigned integer variable to read the value into
 248  * @cond:       Break condition (usually involving @val)
 249  * @sleep_us:   Maximum time to sleep between reads in us (0 tight-loops).
 250  * @timeout_ms: Timeout in ms, 0 means never timeout
 251  * @test_add_time: Used for sandbox testing - amount of time to add after
 252  *              starting the loop (0 if not testing)
 253  *
 254  * Returns 0 on success and -ETIMEDOUT upon a timeout or the regmap_read
 255  * error return value in case of a error read. In the two former cases,
 256  * the last read value at @addr is stored in @val. Must not be called
 257  * from atomic context if sleep_us or timeout_us are used.
 258  *
 259  * This is modelled after the regmap_read_poll_timeout macros in linux but
 260  * with millisecond timeout.
 261  *
 262  * The _test version is for sandbox testing only. Do not use this in normal
 263  * code as it advances the timer.
 264  */
 265 #define regmap_read_poll_timeout_test(map, addr, val, cond, sleep_us, \
 266                                       timeout_ms, test_add_time) \
 267 ({ \
 268         unsigned long __start = get_timer(0); \
 269         int __ret; \
 270         for (;;) { \
 271                 __ret = regmap_read((map), (addr), &(val)); \
 272                 if (__ret) \
 273                         break; \
 274                 if (cond) \
 275                         break; \
 276                 if (IS_ENABLED(CONFIG_SANDBOX) && test_add_time) \
 277                         timer_test_add_offset(test_add_time); \
 278                 if ((timeout_ms) && get_timer(__start) > (timeout_ms)) { \
 279                         __ret = regmap_read((map), (addr), &(val)); \
 280                         break; \
 281                 } \
 282                 if ((sleep_us)) \
 283                         udelay((sleep_us)); \
 284         } \
 285         __ret ?: ((cond) ? 0 : -ETIMEDOUT); \
 286 })
 287
 288 #define regmap_read_poll_timeout(map, addr, val, cond, sleep_us, timeout_ms) \
 289         regmap_read_poll_timeout_test(map, addr, val, cond, sleep_us, \
 290                                       timeout_ms, 0) \
 291
 292 /**
 293  * regmap_update_bits() - Perform a read/modify/write using a mask
 294  *
 295  * @map:        The map returned by regmap_init_mem*()
 296  * @offset:     Offset of the memory
 297  * @mask:       Mask to apply to the read value
 298  * @val:        Value to OR with the read value after masking. Note that any
 299  *      bits set in @val which are not set in @mask are ignored
 300  * Return: 0 if OK, -ve on error
 301  */
 302 int regmap_update_bits(struct regmap *map, uint offset, uint mask, uint val);
 303
 304 /**
 305  * regmap_init_mem() - Set up a new register map that uses memory access
 306  *
 307  * @node:       Device node that uses this map
 308  * @mapp:       Returns allocated map
 309  * Return: 0 if OK, -ve on error
 310  *
 311  * Use regmap_uninit() to free it.
 312  */
 313 int regmap_init_mem(ofnode node, struct regmap **mapp);
 314
 315 /**
 316  * regmap_init_mem_platdata() - Set up a new memory register map for
 317  *                              of-platdata
 318  *
 319  * @dev:        Device that uses this map
 320  * @reg:        List of address, size pairs
 321  * @count:      Number of pairs (e.g. 1 if the regmap has a single entry)
 322  * @mapp:       Returns allocated map
 323  * Return: 0 if OK, -ve on error
 324  *
 325  * This creates a new regmap with a list of regions passed in, rather than
 326  * using the device tree. It only supports 32-bit machines.
 327  *
 328  * Use regmap_uninit() to free it.
 329  *
 330  */
 331 int regmap_init_mem_platdata(struct udevice *dev, fdt_val_t *reg, int count,
 332                              struct regmap **mapp);
 333
 334 int regmap_init_mem_index(ofnode node, struct regmap **mapp, int index);
 335
 336 /**
 337  * regmap_get_range() - Obtain the base memory address of a regmap range
 338  *
 339  * @map:        Regmap to query
 340  * @range_num:  Range to look up
 341  * Return: Pointer to the range in question if OK, NULL on error
 342  */
 343 void *regmap_get_range(struct regmap *map, unsigned int range_num);
 344
 345 /**
 346  * regmap_uninit() - free a previously inited regmap
 347  *
 348  * @map:        Regmap to free
 349  * Return: 0 if OK, -ve on error
 350  */
 351 int regmap_uninit(struct regmap *map);
 352
 353 #endif