board.h 4.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139
  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. * board 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 board had a read-only serial number flash IC, we could
  16. * call
  17. *
  18. * ret = board_detect(dev);
  19. * if (ret) {
  20. * debug("board device not found.");
  21. * return ret;
  22. * }
  23. *
  24. * ret = board_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. struct board_ops {
  33. /**
  34. * detect() - Run the hardware info detection procedure for this
  35. * device.
  36. * @dev: The device containing the information
  37. *
  38. * This operation might take a long time (e.g. read from EEPROM,
  39. * check the presence of a device on a bus etc.), hence this is not
  40. * done in the probe() method, but later during operation in this
  41. * dedicated method.
  42. *
  43. * Return: 0 if OK, -ve on error.
  44. */
  45. int (*detect)(struct udevice *dev);
  46. /**
  47. * get_bool() - Read a specific bool data value that describes the
  48. * hardware setup.
  49. * @dev: The board instance to gather the data.
  50. * @id: A unique identifier for the bool value to be read.
  51. * @val: Pointer to a buffer that receives the value read.
  52. *
  53. * Return: 0 if OK, -ve on error.
  54. */
  55. int (*get_bool)(struct udevice *dev, int id, bool *val);
  56. /**
  57. * get_int() - Read a specific int data value that describes the
  58. * hardware setup.
  59. * @dev: The board instance to gather the data.
  60. * @id: A unique identifier for the int value to be read.
  61. * @val: Pointer to a buffer that receives the value read.
  62. *
  63. * Return: 0 if OK, -ve on error.
  64. */
  65. int (*get_int)(struct udevice *dev, int id, int *val);
  66. /**
  67. * get_str() - Read a specific string data value that describes the
  68. * hardware setup.
  69. * @dev: The board instance to gather the data.
  70. * @id: A unique identifier for the string value to be read.
  71. * @size: The size of the buffer to receive the string data.
  72. * @val: Pointer to a buffer that receives the value read.
  73. *
  74. * Return: 0 if OK, -ve on error.
  75. */
  76. int (*get_str)(struct udevice *dev, int id, size_t size, char *val);
  77. };
  78. #define board_get_ops(dev) ((struct board_ops *)(dev)->driver->ops)
  79. /**
  80. * board_detect() - Run the hardware info detection procedure for this device.
  81. *
  82. * @dev: The device containing the information
  83. *
  84. * Return: 0 if OK, -ve on error.
  85. */
  86. int board_detect(struct udevice *dev);
  87. /**
  88. * board_get_bool() - Read a specific bool data value that describes the
  89. * hardware setup.
  90. * @dev: The board instance to gather the data.
  91. * @id: A unique identifier for the bool value to be read.
  92. * @val: Pointer to a buffer that receives the value read.
  93. *
  94. * Return: 0 if OK, -ve on error.
  95. */
  96. int board_get_bool(struct udevice *dev, int id, bool *val);
  97. /**
  98. * board_get_int() - Read a specific int data value that describes the
  99. * hardware setup.
  100. * @dev: The board instance to gather the data.
  101. * @id: A unique identifier for the int value to be read.
  102. * @val: Pointer to a buffer that receives the value read.
  103. *
  104. * Return: 0 if OK, -ve on error.
  105. */
  106. int board_get_int(struct udevice *dev, int id, int *val);
  107. /**
  108. * board_get_str() - Read a specific string data value that describes the
  109. * hardware setup.
  110. * @dev: The board instance to gather the data.
  111. * @id: A unique identifier for the string value to be read.
  112. * @size: The size of the buffer to receive the string data.
  113. * @val: Pointer to a buffer that receives the value read.
  114. *
  115. * Return: 0 if OK, -ve on error.
  116. */
  117. int board_get_str(struct udevice *dev, int id, size_t size, char *val);
  118. /**
  119. * board_get() - Return the board device for the board in question.
  120. * @devp: Pointer to structure to receive the board device.
  121. *
  122. * Since there can only be at most one board instance, the API can supply a
  123. * function that returns the unique device. This is especially useful for use
  124. * in board files.
  125. *
  126. * Return: 0 if OK, -ve on error.
  127. */
  128. int board_get(struct udevice **devp);