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#ifndef __SYSINFO_H__
8#define __SYSINFO_H__
9
10#include <linux/errno.h>
11
12struct udevice;
13
14/*
15 * This uclass encapsulates hardware methods to gather information about a
16 * sysinfo or a specific device such as hard-wired GPIOs on GPIO expanders,
17 * read-only data in flash ICs, or similar.
18 *
19 * The interface offers functions to read the usual standard data types (bool,
20 * int, string) from the device, each of which is identified by a static
21 * numeric ID (which will usually be defined as a enum in a header file).
22 *
23 * If for example the sysinfo had a read-only serial number flash IC, we could
24 * call
25 *
26 * ret = sysinfo_detect(dev);
27 * if (ret) {
28 *	debug("sysinfo device not found.");
29 *	return ret;
30 * }
31 *
32 * ret = sysinfo_get_int(dev, ID_SERIAL_NUMBER, &serial);
33 * if (ret) {
34 *	debug("Error when reading serial number from device.");
35 *	return ret;
36 * }
37 *
38 * to read the serial number.
39 */
40
41/** enum sysinfo_id - Standard IDs defined by U-Boot */
42enum sysinfo_id {
43	SYSINFO_ID_NONE,
44
45	/* For SMBIOS tables */
46	SYSINFO_ID_SMBIOS_SYSTEM_VERSION,
47	SYSINFO_ID_SMBIOS_BASEBOARD_VERSION,
48
49	/* For show_board_info() */
50	SYSINFO_ID_BOARD_MODEL,
51	SYSINFO_ID_BOARD_MANUFACTURER,
52	SYSINFO_ID_PRIOR_STAGE_VERSION,
53	SYSINFO_ID_PRIOR_STAGE_DATE,
54
55	/* First value available for downstream/board used */
56	SYSINFO_ID_USER = 0x1000,
57};
58
59struct sysinfo_ops {
60	/**
61	 * detect() - Run the hardware info detection procedure for this
62	 *	      device.
63	 * @dev:      The device containing the information
64	 *
65	 * This operation might take a long time (e.g. read from EEPROM,
66	 * check the presence of a device on a bus etc.), hence this is not
67	 * done in the probe() method, but later during operation in this
68	 * dedicated method. This method will be called before any other
69	 * methods.
70	 *
71	 * Return: 0 if OK, -ve on error.
72	 */
73	int (*detect)(struct udevice *dev);
74
75	/**
76	 * get_bool() - Read a specific bool data value that describes the
77	 *		hardware setup.
78	 * @dev:	The sysinfo instance to gather the data.
79	 * @id:		A unique identifier for the bool value to be read.
80	 * @val:	Pointer to a buffer that receives the value read.
81	 *
82	 * Return: 0 if OK, -ve on error.
83	 */
84	int (*get_bool)(struct udevice *dev, int id, bool *val);
85
86	/**
87	 * get_int() - Read a specific int data value that describes the
88	 *	       hardware setup.
89	 * @dev:       The sysinfo instance to gather the data.
90	 * @id:        A unique identifier for the int value to be read.
91	 * @val:       Pointer to a buffer that receives the value read.
92	 *
93	 * Return: 0 if OK, -ve on error.
94	 */
95	int (*get_int)(struct udevice *dev, int id, int *val);
96
97	/**
98	 * get_str() - Read a specific string data value that describes the
99	 *	       hardware setup.
100	 * @dev:	The sysinfo instance to gather the data.
101	 * @id:		A unique identifier for the string value to be read.
102	 * @size:	The size of the buffer to receive the string data.
103	 * @val:	Pointer to a buffer that receives the value read.
104	 *
105	 * Return: 0 if OK, -ve on error.
106	 */
107	int (*get_str)(struct udevice *dev, int id, size_t size, char *val);
108
109	/**
110	 * get_fit_loadable - Get the name of an image to load from FIT
111	 * This function can be used to provide the image names based on runtime
112	 * detection. A classic use-case would when DTBOs are used to describe
113	 * additional daughter cards.
114	 *
115	 * @dev:	The sysinfo instance to gather the data.
116	 * @index:	Index of the image. Starts at 0 and gets incremented
117	 *		after each call to this function.
118	 * @type:	The type of image. For example, "fdt" for DTBs
119	 * @strp:	A pointer to string. Untouched if the function fails
120	 *
121	 * Return: 0 if OK, -ENOENT if no loadable is available else -ve on
122	 * error.
123	 */
124	int (*get_fit_loadable)(struct udevice *dev, int index,
125				const char *type, const char **strp);
126};
127
128#define sysinfo_get_ops(dev)	((struct sysinfo_ops *)(dev)->driver->ops)
129
130#if CONFIG_IS_ENABLED(SYSINFO)
131/**
132 * sysinfo_detect() - Run the hardware info detection procedure for this device.
133 *
134 * @dev:	The device containing the information
135 *
136 * This function must be called before any other accessor function for this
137 * device.
138 *
139 * Return: 0 if OK, -ve on error.
140 */
141int sysinfo_detect(struct udevice *dev);
142
143/**
144 * sysinfo_get_bool() - Read a specific bool data value that describes the
145 *		      hardware setup.
146 * @dev:	The sysinfo instance to gather the data.
147 * @id:		A unique identifier for the bool value to be read.
148 * @val:	Pointer to a buffer that receives the value read.
149 *
150 * Return: 0 if OK, -EPERM if called before sysinfo_detect(), else -ve on
151 * error.
152 */
153int sysinfo_get_bool(struct udevice *dev, int id, bool *val);
154
155/**
156 * sysinfo_get_int() - Read a specific int data value that describes the
157 *		     hardware setup.
158 * @dev:	The sysinfo instance to gather the data.
159 * @id:		A unique identifier for the int value to be read.
160 * @val:	Pointer to a buffer that receives the value read.
161 *
162 * Return: 0 if OK, -EPERM if called before sysinfo_detect(), else -ve on
163 * error.
164 */
165int sysinfo_get_int(struct udevice *dev, int id, int *val);
166
167/**
168 * sysinfo_get_str() - Read a specific string data value that describes the
169 *		     hardware setup.
170 * @dev:	The sysinfo instance to gather the data.
171 * @id:		A unique identifier for the string value to be read.
172 * @size:	The size of the buffer to receive the string data.
173 * @val:	Pointer to a buffer that receives the value read.
174 *
175 * Return: 0 if OK, -EPERM if called before sysinfo_detect(), else -ve on
176 * error.
177 */
178int sysinfo_get_str(struct udevice *dev, int id, size_t size, char *val);
179
180/**
181 * sysinfo_get() - Return the sysinfo device for the sysinfo in question.
182 * @devp: Pointer to structure to receive the sysinfo device.
183 *
184 * Since there can only be at most one sysinfo instance, the API can supply a
185 * function that returns the unique device. This is especially useful for use
186 * in sysinfo files.
187 *
188 * Return: 0 if OK, -EPERM if called before sysinfo_detect(), else -ve on
189 * error.
190 */
191int sysinfo_get(struct udevice **devp);
192
193/**
194 * sysinfo_get_fit_loadable - Get the name of an image to load from FIT
195 * This function can be used to provide the image names based on runtime
196 * detection. A classic use-case would when DTBOs are used to describe
197 * additional daughter cards.
198 *
199 * @dev:	The sysinfo instance to gather the data.
200 * @index:	Index of the image. Starts at 0 and gets incremented
201 *		after each call to this function.
202 * @type:	The type of image. For example, "fdt" for DTBs
203 * @strp:	A pointer to string. Untouched if the function fails
204 *
205 *
206 * Return: 0 if OK, -EPERM if called before sysinfo_detect(), -ENOENT if no
207 * loadable is available else -ve on error.
208 */
209int sysinfo_get_fit_loadable(struct udevice *dev, int index, const char *type,
210			     const char **strp);
211
212#else
213
214static inline int sysinfo_detect(struct udevice *dev)
215{
216	return -ENOSYS;
217}
218
219static inline int sysinfo_get_bool(struct udevice *dev, int id, bool *val)
220{
221	return -ENOSYS;
222}
223
224static inline int sysinfo_get_int(struct udevice *dev, int id, int *val)
225{
226	return -ENOSYS;
227}
228
229static inline int sysinfo_get_str(struct udevice *dev, int id, size_t size,
230				  char *val)
231{
232	return -ENOSYS;
233}
234
235static inline int sysinfo_get(struct udevice **devp)
236{
237	return -ENOSYS;
238}
239
240static inline int sysinfo_get_fit_loadable(struct udevice *dev, int index,
241					   const char *type, const char **strp)
242{
243	return -ENOSYS;
244}
245
246#endif
247#endif
248