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