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_update_bits() - Perform a read/modify/write using a mask 244 * 245 * @map: The map returned by regmap_init_mem*() 246 * @offset: Offset of the memory 247 * @mask: Mask to apply to the read value 248 * @val: Value to apply to the value to write 249 * Return: 0 if OK, -ve on error 250 */ 251 int regmap_update_bits(struct regmap *map, uint offset, uint mask, uint val); 252 253 /** 254 * regmap_init_mem() - Set up a new register map that uses memory access 255 * 256 * @node: Device node that uses this map 257 * @mapp: Returns allocated map 258 * Return: 0 if OK, -ve on error 259 * 260 * Use regmap_uninit() to free it. 261 */ 262 int regmap_init_mem(ofnode node, struct regmap **mapp); 263 264 /** 265 * regmap_init_mem_platdata() - Set up a new memory register map for 266 * of-platdata 267 * 268 * @dev: Device that uses this map 269 * @reg: List of address, size pairs 270 * @count: Number of pairs (e.g. 1 if the regmap has a single entry) 271 * @mapp: Returns allocated map 272 * Return: 0 if OK, -ve on error 273 * 274 * This creates a new regmap with a list of regions passed in, rather than 275 * using the device tree. It only supports 32-bit machines. 276 * 277 * Use regmap_uninit() to free it. 278 * 279 */ 280 int regmap_init_mem_platdata(struct udevice *dev, fdt_val_t *reg, int count, 281 struct regmap **mapp); 282 283 /** 284 * regmap_get_range() - Obtain the base memory address of a regmap range 285 * 286 * @map: Regmap to query 287 * @range_num: Range to look up 288 * Return: Pointer to the range in question if OK, NULL on error 289 */ 290 void *regmap_get_range(struct regmap *map, unsigned int range_num); 291 292 /** 293 * regmap_uninit() - free a previously inited regmap 294 * 295 * @map: Regmap to free 296 * Return: 0 if OK, -ve on error 297 */ 298 int regmap_uninit(struct regmap *map); 299 300 #endif 301