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