sysinfo.h 6.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213
  1. /* SPDX-License-Identifier: GPL-2.0+ */
  2. /*
  3. * (C) Copyright 2017
  4. * Mario Six, Guntermann & Drunck GmbH, mario.six@gdsys.cc
  5. */
  6. /*
  7. * This uclass encapsulates hardware methods to gather information about a
  8. * sysinfo or a specific device such as hard-wired GPIOs on GPIO expanders,
  9. * read-only data in flash ICs, or similar.
  10. *
  11. * The interface offers functions to read the usual standard data types (bool,
  12. * int, string) from the device, each of which is identified by a static
  13. * numeric ID (which will usually be defined as a enum in a header file).
  14. *
  15. * If for example the sysinfo had a read-only serial number flash IC, we could
  16. * call
  17. *
  18. * ret = sysinfo_detect(dev);
  19. * if (ret) {
  20. * debug("sysinfo device not found.");
  21. * return ret;
  22. * }
  23. *
  24. * ret = sysinfo_get_int(dev, ID_SERIAL_NUMBER, &serial);
  25. * if (ret) {
  26. * debug("Error when reading serial number from device.");
  27. * return ret;
  28. * }
  29. *
  30. * to read the serial number.
  31. */
  32. #if CONFIG_IS_ENABLED(SYSINFO)
  33. struct sysinfo_ops {
  34. /**
  35. * detect() - Run the hardware info detection procedure for this
  36. * device.
  37. * @dev: The device containing the information
  38. *
  39. * This operation might take a long time (e.g. read from EEPROM,
  40. * check the presence of a device on a bus etc.), hence this is not
  41. * done in the probe() method, but later during operation in this
  42. * dedicated method.
  43. *
  44. * Return: 0 if OK, -ve on error.
  45. */
  46. int (*detect)(struct udevice *dev);
  47. /**
  48. * get_bool() - Read a specific bool data value that describes the
  49. * hardware setup.
  50. * @dev: The sysinfo instance to gather the data.
  51. * @id: A unique identifier for the bool value to be read.
  52. * @val: Pointer to a buffer that receives the value read.
  53. *
  54. * Return: 0 if OK, -ve on error.
  55. */
  56. int (*get_bool)(struct udevice *dev, int id, bool *val);
  57. /**
  58. * get_int() - Read a specific int data value that describes the
  59. * hardware setup.
  60. * @dev: The sysinfo instance to gather the data.
  61. * @id: A unique identifier for the int value to be read.
  62. * @val: Pointer to a buffer that receives the value read.
  63. *
  64. * Return: 0 if OK, -ve on error.
  65. */
  66. int (*get_int)(struct udevice *dev, int id, int *val);
  67. /**
  68. * get_str() - Read a specific string data value that describes the
  69. * hardware setup.
  70. * @dev: The sysinfo instance to gather the data.
  71. * @id: A unique identifier for the string value to be read.
  72. * @size: The size of the buffer to receive the string data.
  73. * @val: Pointer to a buffer that receives the value read.
  74. *
  75. * Return: 0 if OK, -ve on error.
  76. */
  77. int (*get_str)(struct udevice *dev, int id, size_t size, char *val);
  78. /**
  79. * get_fit_loadable - Get the name of an image to load from FIT
  80. * This function can be used to provide the image names based on runtime
  81. * detection. A classic use-case would when DTBOs are used to describe
  82. * additionnal daughter cards.
  83. *
  84. * @dev: The sysinfo instance to gather the data.
  85. * @index: Index of the image. Starts at 0 and gets incremented
  86. * after each call to this function.
  87. * @type: The type of image. For example, "fdt" for DTBs
  88. * @strp: A pointer to string. Untouched if the function fails
  89. *
  90. * Return: 0 if OK, -ENOENT if no loadable is available else -ve on
  91. * error.
  92. */
  93. int (*get_fit_loadable)(struct udevice *dev, int index,
  94. const char *type, const char **strp);
  95. };
  96. #define sysinfo_get_ops(dev) ((struct sysinfo_ops *)(dev)->driver->ops)
  97. /**
  98. * sysinfo_detect() - Run the hardware info detection procedure for this device.
  99. *
  100. * @dev: The device containing the information
  101. *
  102. * Return: 0 if OK, -ve on error.
  103. */
  104. int sysinfo_detect(struct udevice *dev);
  105. /**
  106. * sysinfo_get_bool() - Read a specific bool data value that describes the
  107. * hardware setup.
  108. * @dev: The sysinfo instance to gather the data.
  109. * @id: A unique identifier for the bool value to be read.
  110. * @val: Pointer to a buffer that receives the value read.
  111. *
  112. * Return: 0 if OK, -ve on error.
  113. */
  114. int sysinfo_get_bool(struct udevice *dev, int id, bool *val);
  115. /**
  116. * sysinfo_get_int() - Read a specific int data value that describes the
  117. * hardware setup.
  118. * @dev: The sysinfo instance to gather the data.
  119. * @id: A unique identifier for the int value to be read.
  120. * @val: Pointer to a buffer that receives the value read.
  121. *
  122. * Return: 0 if OK, -ve on error.
  123. */
  124. int sysinfo_get_int(struct udevice *dev, int id, int *val);
  125. /**
  126. * sysinfo_get_str() - Read a specific string data value that describes the
  127. * hardware setup.
  128. * @dev: The sysinfo instance to gather the data.
  129. * @id: A unique identifier for the string value to be read.
  130. * @size: The size of the buffer to receive the string data.
  131. * @val: Pointer to a buffer that receives the value read.
  132. *
  133. * Return: 0 if OK, -ve on error.
  134. */
  135. int sysinfo_get_str(struct udevice *dev, int id, size_t size, char *val);
  136. /**
  137. * sysinfo_get() - Return the sysinfo device for the sysinfo in question.
  138. * @devp: Pointer to structure to receive the sysinfo device.
  139. *
  140. * Since there can only be at most one sysinfo instance, the API can supply a
  141. * function that returns the unique device. This is especially useful for use
  142. * in sysinfo files.
  143. *
  144. * Return: 0 if OK, -ve on error.
  145. */
  146. int sysinfo_get(struct udevice **devp);
  147. /**
  148. * sysinfo_get_fit_loadable - Get the name of an image to load from FIT
  149. * This function can be used to provide the image names based on runtime
  150. * detection. A classic use-case would when DTBOs are used to describe
  151. * additionnal daughter cards.
  152. *
  153. * @dev: The sysinfo instance to gather the data.
  154. * @index: Index of the image. Starts at 0 and gets incremented
  155. * after each call to this function.
  156. * @type: The type of image. For example, "fdt" for DTBs
  157. * @strp: A pointer to string. Untouched if the function fails
  158. *
  159. *
  160. * Return: 0 if OK, -ENOENT if no loadable is available else -ve on
  161. * error.
  162. */
  163. int sysinfo_get_fit_loadable(struct udevice *dev, int index, const char *type,
  164. const char **strp);
  165. #else
  166. static inline int sysinfo_detect(struct udevice *dev)
  167. {
  168. return -ENOSYS;
  169. }
  170. static inline int sysinfo_get_bool(struct udevice *dev, int id, bool *val)
  171. {
  172. return -ENOSYS;
  173. }
  174. static inline int sysinfo_get_int(struct udevice *dev, int id, int *val)
  175. {
  176. return -ENOSYS;
  177. }
  178. static inline int sysinfo_get_str(struct udevice *dev, int id, size_t size,
  179. char *val)
  180. {
  181. return -ENOSYS;
  182. }
  183. static inline int sysinfo_get(struct udevice **devp)
  184. {
  185. return -ENOSYS;
  186. }
  187. static inline int sysinfo_get_fit_loadable(struct udevice *dev, int index,
  188. const char *type, const char **strp)
  189. {
  190. return -ENOSYS;
  191. }
  192. #endif