1 /* SPDX-License-Identifier: GPL-2.0+ */
4 * Mario Six, Guntermann & Drunck GmbH, mario.six@gdsys.cc
8 * This uclass encapsulates hardware methods to gather information about a
9 * board or a specific device such as hard-wired GPIOs on GPIO expanders,
10 * read-only data in flash ICs, or similar.
12 * The interface offers functions to read the usual standard data types (bool,
13 * int, string) from the device, each of which is identified by a static
14 * numeric ID (which will usually be defined as a enum in a header file).
16 * If for example the board had a read-only serial number flash IC, we could
19 * ret = board_detect(dev);
21 * debug("board device not found.");
25 * ret = board_get_int(dev, ID_SERIAL_NUMBER, &serial);
27 * debug("Error when reading serial number from device.");
31 * to read the serial number.
36 * detect() - Run the hardware info detection procedure for this
38 * @dev: The device containing the information
40 * This operation might take a long time (e.g. read from EEPROM,
41 * check the presence of a device on a bus etc.), hence this is not
42 * done in the probe() method, but later during operation in this
45 * Return: 0 if OK, -ve on error.
47 int (*detect)(struct udevice *dev);
50 * get_bool() - Read a specific bool data value that describes the
52 * @dev: The board instance to gather the data.
53 * @id: A unique identifier for the bool value to be read.
54 * @val: Pointer to a buffer that receives the value read.
56 * Return: 0 if OK, -ve on error.
58 int (*get_bool)(struct udevice *dev, int id, bool *val);
61 * get_int() - Read a specific int data value that describes the
63 * @dev: The board instance to gather the data.
64 * @id: A unique identifier for the int value to be read.
65 * @val: Pointer to a buffer that receives the value read.
67 * Return: 0 if OK, -ve on error.
69 int (*get_int)(struct udevice *dev, int id, int *val);
72 * get_str() - Read a specific string data value that describes the
74 * @dev: The board instance to gather the data.
75 * @id: A unique identifier for the string value to be read.
76 * @size: The size of the buffer to receive the string data.
77 * @val: Pointer to a buffer that receives the value read.
79 * Return: 0 if OK, -ve on error.
81 int (*get_str)(struct udevice *dev, int id, size_t size, char *val);
84 * get_fit_loadable - Get the name of an image to load from FIT
85 * This function can be used to provide the image names based on runtime
86 * detection. A classic use-case would when DTBOs are used to describe
87 * additionnal daughter cards.
89 * @dev: The board instance to gather the data.
90 * @index: Index of the image. Starts at 0 and gets incremented
91 * after each call to this function.
92 * @type: The type of image. For example, "fdt" for DTBs
93 * @strp: A pointer to string. Untouched if the function fails
95 * Return: 0 if OK, -ENOENT if no loadable is available else -ve on
98 int (*get_fit_loadable)(struct udevice *dev, int index,
99 const char *type, const char **strp);
102 #define board_get_ops(dev) ((struct board_ops *)(dev)->driver->ops)
105 * board_detect() - Run the hardware info detection procedure for this device.
107 * @dev: The device containing the information
109 * Return: 0 if OK, -ve on error.
111 int board_detect(struct udevice *dev);
114 * board_get_bool() - Read a specific bool data value that describes the
116 * @dev: The board instance to gather the data.
117 * @id: A unique identifier for the bool value to be read.
118 * @val: Pointer to a buffer that receives the value read.
120 * Return: 0 if OK, -ve on error.
122 int board_get_bool(struct udevice *dev, int id, bool *val);
125 * board_get_int() - Read a specific int data value that describes the
127 * @dev: The board instance to gather the data.
128 * @id: A unique identifier for the int value to be read.
129 * @val: Pointer to a buffer that receives the value read.
131 * Return: 0 if OK, -ve on error.
133 int board_get_int(struct udevice *dev, int id, int *val);
136 * board_get_str() - Read a specific string data value that describes the
138 * @dev: The board instance to gather the data.
139 * @id: A unique identifier for the string value to be read.
140 * @size: The size of the buffer to receive the string data.
141 * @val: Pointer to a buffer that receives the value read.
143 * Return: 0 if OK, -ve on error.
145 int board_get_str(struct udevice *dev, int id, size_t size, char *val);
148 * board_get() - Return the board device for the board in question.
149 * @devp: Pointer to structure to receive the board device.
151 * Since there can only be at most one board instance, the API can supply a
152 * function that returns the unique device. This is especially useful for use
155 * Return: 0 if OK, -ve on error.
157 int board_get(struct udevice **devp);
160 * board_get_fit_loadable - Get the name of an image to load from FIT
161 * This function can be used to provide the image names based on runtime
162 * detection. A classic use-case would when DTBOs are used to describe
163 * additionnal daughter cards.
165 * @dev: The board instance to gather the data.
166 * @index: Index of the image. Starts at 0 and gets incremented
167 * after each call to this function.
168 * @type: The type of image. For example, "fdt" for DTBs
169 * @strp: A pointer to string. Untouched if the function fails
172 * Return: 0 if OK, -ENOENT if no loadable is available else -ve on
175 int board_get_fit_loadable(struct udevice *dev, int index,
176 const char *type, const char **strp);