regmap.h 17 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532
  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. struct regmap_bus;
  72. /**
  73. * struct regmap_config - Configure the behaviour of a regmap
  74. *
  75. * @width: Width of the read/write operations. Defaults to
  76. * REGMAP_SIZE_32 if set to 0.
  77. * @reg_offset_shift Left shift the register offset by this value before
  78. * performing read or write.
  79. * @r_start: If specified, the regmap is created with one range
  80. * which starts at this address, instead of finding the
  81. * start from device tree.
  82. * @r_size: Same as above for the range size
  83. */
  84. struct regmap_config {
  85. enum regmap_size_t width;
  86. u32 reg_offset_shift;
  87. ulong r_start;
  88. ulong r_size;
  89. };
  90. /**
  91. * struct regmap - a way of accessing hardware/bus registers
  92. *
  93. * @width: Width of the read/write operations. Defaults to
  94. * REGMAP_SIZE_32 if set to 0.
  95. * @reg_offset_shift Left shift the register offset by this value before
  96. * performing read or write.
  97. * @range_count: Number of ranges available within the map
  98. * @ranges: Array of ranges
  99. */
  100. struct regmap {
  101. enum regmap_endianness_t endianness;
  102. enum regmap_size_t width;
  103. u32 reg_offset_shift;
  104. int range_count;
  105. struct regmap_range ranges[0];
  106. };
  107. /*
  108. * Interface to provide access to registers either through a direct memory
  109. * bus or through a peripheral bus like I2C, SPI.
  110. */
  111. /**
  112. * regmap_write() - Write a value to a regmap
  113. *
  114. * @map: Regmap to write to
  115. * @offset: Offset in the regmap to write to
  116. * @val: Data to write to the regmap at the specified offset
  117. *
  118. * Return: 0 if OK, -ve on error
  119. */
  120. int regmap_write(struct regmap *map, uint offset, uint val);
  121. /**
  122. * regmap_read() - Read a value from a regmap
  123. *
  124. * @map: Regmap to read from
  125. * @offset: Offset in the regmap to read from
  126. * @valp: Pointer to the buffer to receive the data read from the regmap
  127. * at the specified offset
  128. *
  129. * Return: 0 if OK, -ve on error
  130. */
  131. int regmap_read(struct regmap *map, uint offset, uint *valp);
  132. /**
  133. * regmap_raw_write() - Write a value of specified length to a regmap
  134. *
  135. * @map: Regmap to write to
  136. * @offset: Offset in the regmap to write to
  137. * @val: Value to write to the regmap at the specified offset
  138. * @val_len: Length of the data to be written to the regmap
  139. *
  140. * Note that this function will, as opposed to regmap_write, write data of
  141. * arbitrary length to the regmap, and not just the size configured in the
  142. * regmap (defaults to 32-bit) and is thus a generalized version of
  143. * regmap_write.
  144. *
  145. * Return: 0 if OK, -ve on error
  146. */
  147. int regmap_raw_write(struct regmap *map, uint offset, const void *val,
  148. size_t val_len);
  149. /**
  150. * regmap_raw_read() - Read a value of specified length from a regmap
  151. *
  152. * @map: Regmap to read from
  153. * @offset: Offset in the regmap to read from
  154. * @valp: Pointer to the buffer to receive the data read from the regmap
  155. * at the specified offset
  156. * @val_len: Length of the data to be read from the regmap
  157. *
  158. * Note that this function will, as opposed to regmap_read, read data of
  159. * arbitrary length from the regmap, and not just the size configured in the
  160. * regmap (defaults to 32-bit) and is thus a generalized version of
  161. * regmap_read.
  162. *
  163. * Return: 0 if OK, -ve on error
  164. */
  165. int regmap_raw_read(struct regmap *map, uint offset, void *valp,
  166. size_t val_len);
  167. /**
  168. * regmap_raw_write_range() - Write a value of specified length to a range of a
  169. * regmap
  170. *
  171. * @map: Regmap to write to
  172. * @range_num: Number of the range in the regmap to write to
  173. * @offset: Offset in the regmap to write to
  174. * @val: Value to write to the regmap at the specified offset
  175. * @val_len: Length of the data to be written to the regmap
  176. *
  177. * Return: 0 if OK, -ve on error
  178. */
  179. int regmap_raw_write_range(struct regmap *map, uint range_num, uint offset,
  180. const void *val, size_t val_len);
  181. /**
  182. * regmap_raw_read_range() - Read a value of specified length from a range of a
  183. * regmap
  184. *
  185. * @map: Regmap to read from
  186. * @range_num: Number of the range in the regmap to write to
  187. * @offset: Offset in the regmap to read from
  188. * @valp: Pointer to the buffer to receive the data read from the regmap
  189. * at the specified offset
  190. * @val_len: Length of the data to be read from the regmap
  191. *
  192. * Return: 0 if OK, -ve on error
  193. */
  194. int regmap_raw_read_range(struct regmap *map, uint range_num, uint offset,
  195. void *valp, size_t val_len);
  196. /**
  197. * regmap_range_set() - Set a value in a regmap range described by a struct
  198. * @map: Regmap in which a value should be set
  199. * @range: Range of the regmap in which a value should be set
  200. * @type: Structure type that describes the memory layout of the regmap range
  201. * @member: Member of the describing structure that should be set in the regmap
  202. * range
  203. * @val: Value which should be written to the regmap range
  204. */
  205. #define regmap_range_set(map, range, type, member, val) \
  206. do { \
  207. typeof(((type *)0)->member) __tmp = val; \
  208. regmap_raw_write_range(map, range, offsetof(type, member), \
  209. &__tmp, sizeof(((type *)0)->member)); \
  210. } while (0)
  211. /**
  212. * regmap_set() - Set a value in a regmap described by a struct
  213. * @map: Regmap in which a value should be set
  214. * @type: Structure type that describes the memory layout of the regmap
  215. * @member: Member of the describing structure that should be set in the regmap
  216. * @val: Value which should be written to the regmap
  217. */
  218. #define regmap_set(map, type, member, val) \
  219. regmap_range_set(map, 0, type, member, val)
  220. /**
  221. * regmap_range_get() - Get a value from a regmap range described by a struct
  222. * @map: Regmap from which a value should be read
  223. * @range: Range of the regmap from which a value should be read
  224. * @type: Structure type that describes the memory layout of the regmap
  225. * range
  226. * @member: Member of the describing structure that should be read in the
  227. * regmap range
  228. * @valp: Variable that receives the value read from the regmap range
  229. */
  230. #define regmap_range_get(map, range, type, member, valp) \
  231. regmap_raw_read_range(map, range, offsetof(type, member), \
  232. (void *)valp, sizeof(((type *)0)->member))
  233. /**
  234. * regmap_get() - Get a value from a regmap described by a struct
  235. * @map: Regmap from which a value should be read
  236. * @type: Structure type that describes the memory layout of the regmap
  237. * range
  238. * @member: Member of the describing structure that should be read in the
  239. * regmap
  240. * @valp: Variable that receives the value read from the regmap
  241. */
  242. #define regmap_get(map, type, member, valp) \
  243. regmap_range_get(map, 0, type, member, valp)
  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. #define regmap_read_poll_timeout(map, addr, val, cond, sleep_us, timeout_ms) \
  290. regmap_read_poll_timeout_test(map, addr, val, cond, sleep_us, \
  291. timeout_ms, 0) \
  292. /**
  293. * regmap_field_read_poll_timeout - Poll until a condition is met or a timeout
  294. * occurs
  295. *
  296. * @field: Regmap field to read from
  297. * @val: Unsigned integer variable to read the value into
  298. * @cond: Break condition (usually involving @val)
  299. * @sleep_us: Maximum time to sleep between reads in us (0 tight-loops).
  300. * @timeout_ms: Timeout in ms, 0 means never timeout
  301. *
  302. * Returns 0 on success and -ETIMEDOUT upon a timeout or the regmap_field_read
  303. * error return value in case of a error read. In the two former cases,
  304. * the last read value at @addr is stored in @val.
  305. *
  306. * This is modelled after the regmap_read_poll_timeout macros in linux but
  307. * with millisecond timeout.
  308. */
  309. #define regmap_field_read_poll_timeout(field, val, cond, sleep_us, timeout_ms) \
  310. ({ \
  311. unsigned long __start = get_timer(0); \
  312. int __ret; \
  313. for (;;) { \
  314. __ret = regmap_field_read((field), &(val)); \
  315. if (__ret) \
  316. break; \
  317. if (cond) \
  318. break; \
  319. if ((timeout_ms) && get_timer(__start) > (timeout_ms)) { \
  320. __ret = regmap_field_read((field), &(val)); \
  321. break; \
  322. } \
  323. if ((sleep_us)) \
  324. udelay((sleep_us)); \
  325. } \
  326. __ret ?: ((cond) ? 0 : -ETIMEDOUT); \
  327. })
  328. /**
  329. * regmap_update_bits() - Perform a read/modify/write using a mask
  330. *
  331. * @map: The map returned by regmap_init_mem*()
  332. * @offset: Offset of the memory
  333. * @mask: Mask to apply to the read value
  334. * @val: Value to OR with the read value after masking. Note that any
  335. * bits set in @val which are not set in @mask are ignored
  336. * Return: 0 if OK, -ve on error
  337. */
  338. int regmap_update_bits(struct regmap *map, uint offset, uint mask, uint val);
  339. /**
  340. * regmap_init_mem() - Set up a new register map that uses memory access
  341. *
  342. * @node: Device node that uses this map
  343. * @mapp: Returns allocated map
  344. * Return: 0 if OK, -ve on error
  345. *
  346. * Use regmap_uninit() to free it.
  347. */
  348. int regmap_init_mem(ofnode node, struct regmap **mapp);
  349. /**
  350. * regmap_init_mem_platdata() - Set up a new memory register map for
  351. * of-platdata
  352. *
  353. * @dev: Device that uses this map
  354. * @reg: List of address, size pairs
  355. * @count: Number of pairs (e.g. 1 if the regmap has a single entry)
  356. * @mapp: Returns allocated map
  357. * Return: 0 if OK, -ve on error
  358. *
  359. * This creates a new regmap with a list of regions passed in, rather than
  360. * using the device tree. It only supports 32-bit machines.
  361. *
  362. * Use regmap_uninit() to free it.
  363. *
  364. */
  365. int regmap_init_mem_platdata(struct udevice *dev, fdt_val_t *reg, int count,
  366. struct regmap **mapp);
  367. int regmap_init_mem_index(ofnode node, struct regmap **mapp, int index);
  368. /**
  369. * regmap_init_mem_range() - Set up a new memory region for ofnode with the
  370. * specified range.
  371. *
  372. * @node: The ofnode for the map.
  373. * @r_start: Start of the range.
  374. * @r_size: Size of the range.
  375. * @mapp: Returns allocated map.
  376. *
  377. * Return: 0 in success, -errno otherwise
  378. *
  379. * This creates a regmap with one range where instead of extracting the range
  380. * from 'node', it is created based on the parameters specified. This is
  381. * useful when a driver needs to calculate the base of the regmap at runtime,
  382. * and can't specify it in device tree.
  383. */
  384. int regmap_init_mem_range(ofnode node, ulong r_start, ulong r_size,
  385. struct regmap **mapp);
  386. /**
  387. * devm_regmap_init() - Initialise register map (device managed)
  388. *
  389. * @dev: Device that will be interacted with
  390. * @bus: Bus-specific callbacks to use with device (IGNORED)
  391. * @bus_context: Data passed to bus-specific callbacks (IGNORED)
  392. * @config: Configuration for register map
  393. *
  394. * @Return a valid pointer to a struct regmap or a ERR_PTR() on error.
  395. * The structure is automatically freed when the device is unbound
  396. */
  397. struct regmap *devm_regmap_init(struct udevice *dev,
  398. const struct regmap_bus *bus,
  399. void *bus_context,
  400. const struct regmap_config *config);
  401. /**
  402. * regmap_get_range() - Obtain the base memory address of a regmap range
  403. *
  404. * @map: Regmap to query
  405. * @range_num: Range to look up
  406. * Return: Pointer to the range in question if OK, NULL on error
  407. */
  408. void *regmap_get_range(struct regmap *map, unsigned int range_num);
  409. /**
  410. * regmap_uninit() - free a previously inited regmap
  411. *
  412. * @map: Regmap to free
  413. * Return: 0 if OK, -ve on error
  414. */
  415. int regmap_uninit(struct regmap *map);
  416. /**
  417. * struct reg_field - Description of an register field
  418. *
  419. * @reg: Offset of the register within the regmap bank
  420. * @lsb: lsb of the register field.
  421. * @msb: msb of the register field.
  422. */
  423. struct reg_field {
  424. unsigned int reg;
  425. unsigned int lsb;
  426. unsigned int msb;
  427. };
  428. struct regmap_field;
  429. /**
  430. * REG_FIELD() - A convenient way to initialize a 'struct reg_feild'.
  431. *
  432. * @_reg: Offset of the register within the regmap bank
  433. * @_lsb: lsb of the register field.
  434. * @_msb: msb of the register field.
  435. *
  436. * Register fields are often described in terms of 3 things: the register it
  437. * belongs to, its LSB, and its MSB. This macro can be used by drivers to
  438. * clearly and easily initialize a 'struct regmap_field'.
  439. *
  440. * For example, say a device has a register at offset DEV_REG1 (0x100) and a
  441. * field of DEV_REG1 is on bits [7:3]. So a driver can initialize a regmap
  442. * field for this by doing:
  443. * struct reg_field field = REG_FIELD(DEV_REG1, 3, 7);
  444. */
  445. #define REG_FIELD(_reg, _lsb, _msb) { \
  446. .reg = _reg, \
  447. .lsb = _lsb, \
  448. .msb = _msb, \
  449. }
  450. /**
  451. * devm_regmap_field_alloc() - Allocate and initialise a register field.
  452. *
  453. * @dev: Device that will be interacted with
  454. * @regmap: regmap bank in which this register field is located.
  455. * @reg_field: Register field with in the bank.
  456. *
  457. * The return value will be an ERR_PTR() on error or a valid pointer
  458. * to a struct regmap_field. The regmap_field will be automatically freed
  459. * by the device management code.
  460. */
  461. struct regmap_field *devm_regmap_field_alloc(struct udevice *dev,
  462. struct regmap *regmap,
  463. struct reg_field reg_field);
  464. /**
  465. * devm_regmap_field_free() - Free a register field allocated using
  466. * devm_regmap_field_alloc.
  467. *
  468. * @dev: Device that will be interacted with
  469. * @field: regmap field which should be freed.
  470. *
  471. * Free register field allocated using devm_regmap_field_alloc(). Usually
  472. * drivers need not call this function, as the memory allocated via devm
  473. * will be freed as per device-driver life-cyle.
  474. */
  475. void devm_regmap_field_free(struct udevice *dev, struct regmap_field *field);
  476. /**
  477. * regmap_field_write() - Write a value to a regmap field
  478. *
  479. * @field: Regmap field to write to
  480. * @val: Data to write to the regmap at the specified offset
  481. *
  482. * Return: 0 if OK, -ve on error
  483. */
  484. int regmap_field_write(struct regmap_field *field, unsigned int val);
  485. /**
  486. * regmap_read() - Read a 32-bit value from a regmap
  487. *
  488. * @field: Regmap field to write to
  489. * @valp: Pointer to the buffer to receive the data read from the regmap
  490. * field
  491. *
  492. * Return: 0 if OK, -ve on error
  493. */
  494. int regmap_field_read(struct regmap_field *field, unsigned int *val);
  495. #endif