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