blob: 678b652b0aa3fc547c01689f6f69cf6478a4504b [file] [log] [blame]
Mario Six5381c282018-07-31 11:44:11 +02001/* SPDX-License-Identifier: GPL-2.0+ */
2/*
3 * (C) Copyright 2017
4 * Mario Six, Guntermann & Drunck GmbH, mario.six@gdsys.cc
5 */
6
7/*
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.
11 *
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).
15 *
16 * If for example the board had a read-only serial number flash IC, we could
17 * call
18 *
19 * ret = board_detect(dev);
20 * if (ret) {
21 * debug("board device not found.");
22 * return ret;
23 * }
24 *
25 * ret = board_get_int(dev, ID_SERIAL_NUMBER, &serial);
26 * if (ret) {
27 * debug("Error when reading serial number from device.");
28 * return ret;
29 * }
30 *
31 * to read the serial number.
32 */
33
Jean-Jacques Hiblot02806e92019-10-22 16:39:20 +020034#if CONFIG_IS_ENABLED(BOARD)
Mario Six5381c282018-07-31 11:44:11 +020035struct board_ops {
36 /**
37 * detect() - Run the hardware info detection procedure for this
38 * device.
39 * @dev: The device containing the information
40 *
41 * This operation might take a long time (e.g. read from EEPROM,
42 * check the presence of a device on a bus etc.), hence this is not
43 * done in the probe() method, but later during operation in this
44 * dedicated method.
45 *
46 * Return: 0 if OK, -ve on error.
47 */
48 int (*detect)(struct udevice *dev);
49
50 /**
51 * get_bool() - Read a specific bool data value that describes the
52 * hardware setup.
53 * @dev: The board instance to gather the data.
54 * @id: A unique identifier for the bool value to be read.
55 * @val: Pointer to a buffer that receives the value read.
56 *
57 * Return: 0 if OK, -ve on error.
58 */
59 int (*get_bool)(struct udevice *dev, int id, bool *val);
60
61 /**
62 * get_int() - Read a specific int data value that describes the
63 * hardware setup.
64 * @dev: The board instance to gather the data.
65 * @id: A unique identifier for the int value to be read.
66 * @val: Pointer to a buffer that receives the value read.
67 *
68 * Return: 0 if OK, -ve on error.
69 */
70 int (*get_int)(struct udevice *dev, int id, int *val);
71
72 /**
73 * get_str() - Read a specific string data value that describes the
74 * hardware setup.
75 * @dev: The board instance to gather the data.
76 * @id: A unique identifier for the string value to be read.
77 * @size: The size of the buffer to receive the string data.
78 * @val: Pointer to a buffer that receives the value read.
79 *
80 * Return: 0 if OK, -ve on error.
81 */
82 int (*get_str)(struct udevice *dev, int id, size_t size, char *val);
Jean-Jacques Hiblotd42730e2019-10-22 16:39:19 +020083
84 /**
85 * get_fit_loadable - Get the name of an image to load from FIT
86 * This function can be used to provide the image names based on runtime
87 * detection. A classic use-case would when DTBOs are used to describe
88 * additionnal daughter cards.
89 *
90 * @dev: The board instance to gather the data.
91 * @index: Index of the image. Starts at 0 and gets incremented
92 * after each call to this function.
93 * @type: The type of image. For example, "fdt" for DTBs
94 * @strp: A pointer to string. Untouched if the function fails
95 *
96 * Return: 0 if OK, -ENOENT if no loadable is available else -ve on
97 * error.
98 */
99 int (*get_fit_loadable)(struct udevice *dev, int index,
100 const char *type, const char **strp);
Mario Six5381c282018-07-31 11:44:11 +0200101};
102
103#define board_get_ops(dev) ((struct board_ops *)(dev)->driver->ops)
104
105/**
106 * board_detect() - Run the hardware info detection procedure for this device.
107 *
108 * @dev: The device containing the information
109 *
110 * Return: 0 if OK, -ve on error.
111 */
112int board_detect(struct udevice *dev);
113
114/**
115 * board_get_bool() - Read a specific bool data value that describes the
116 * hardware setup.
117 * @dev: The board instance to gather the data.
118 * @id: A unique identifier for the bool value to be read.
119 * @val: Pointer to a buffer that receives the value read.
120 *
121 * Return: 0 if OK, -ve on error.
122 */
123int board_get_bool(struct udevice *dev, int id, bool *val);
124
125/**
126 * board_get_int() - Read a specific int data value that describes the
127 * hardware setup.
128 * @dev: The board instance to gather the data.
129 * @id: A unique identifier for the int value to be read.
130 * @val: Pointer to a buffer that receives the value read.
131 *
132 * Return: 0 if OK, -ve on error.
133 */
134int board_get_int(struct udevice *dev, int id, int *val);
135
136/**
137 * board_get_str() - Read a specific string data value that describes the
138 * hardware setup.
139 * @dev: The board instance to gather the data.
140 * @id: A unique identifier for the string value to be read.
141 * @size: The size of the buffer to receive the string data.
142 * @val: Pointer to a buffer that receives the value read.
143 *
144 * Return: 0 if OK, -ve on error.
145 */
146int board_get_str(struct udevice *dev, int id, size_t size, char *val);
147
148/**
149 * board_get() - Return the board device for the board in question.
150 * @devp: Pointer to structure to receive the board device.
151 *
152 * Since there can only be at most one board instance, the API can supply a
153 * function that returns the unique device. This is especially useful for use
154 * in board files.
155 *
156 * Return: 0 if OK, -ve on error.
157 */
158int board_get(struct udevice **devp);
Jean-Jacques Hiblotd42730e2019-10-22 16:39:19 +0200159
160/**
161 * board_get_fit_loadable - Get the name of an image to load from FIT
162 * This function can be used to provide the image names based on runtime
163 * detection. A classic use-case would when DTBOs are used to describe
164 * additionnal daughter cards.
165 *
166 * @dev: The board instance to gather the data.
167 * @index: Index of the image. Starts at 0 and gets incremented
168 * after each call to this function.
169 * @type: The type of image. For example, "fdt" for DTBs
170 * @strp: A pointer to string. Untouched if the function fails
171 *
172 *
173 * Return: 0 if OK, -ENOENT if no loadable is available else -ve on
174 * error.
175 */
176int board_get_fit_loadable(struct udevice *dev, int index,
177 const char *type, const char **strp);
Jean-Jacques Hiblot02806e92019-10-22 16:39:20 +0200178
179#else
180
181static inline int board_detect(struct udevice *dev)
182{
183 return -ENOSYS;
184}
185
186static inline int board_get_bool(struct udevice *dev, int id, bool *val)
187{
188 return -ENOSYS;
189}
190
191static inline int board_get_int(struct udevice *dev, int id, int *val)
192{
193 return -ENOSYS;
194}
195
196static inline int board_get_str(struct udevice *dev, int id, size_t size,
197 char *val)
198{
199 return -ENOSYS;
200}
201
202static inline int board_get(struct udevice **devp)
203{
204 return -ENOSYS;
205}
206
207static inline int board_get_fit_loadable(struct udevice *dev, int index,
208 const char *type, const char **strp)
209{
210 return -ENOSYS;
211}
212
213#endif