regmap.h 12 KB

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