xref: /openbmc/u-boot/include/board.h (revision a9484aa7)
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 /*
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 
34 struct board_ops {
35 	/**
36 	 * detect() - Run the hardware info detection procedure for this
37 	 *	      device.
38 	 * @dev:      The device containing the information
39 	 *
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
43 	 * dedicated method.
44 	 *
45 	 * Return: 0 if OK, -ve on error.
46 	 */
47 	int (*detect)(struct udevice *dev);
48 
49 	/**
50 	 * get_bool() - Read a specific bool data value that describes the
51 	 *		hardware setup.
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.
55 	 *
56 	 * Return: 0 if OK, -ve on error.
57 	 */
58 	int (*get_bool)(struct udevice *dev, int id, bool *val);
59 
60 	/**
61 	 * get_int() - Read a specific int data value that describes the
62 	 *	       hardware setup.
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.
66 	 *
67 	 * Return: 0 if OK, -ve on error.
68 	 */
69 	int (*get_int)(struct udevice *dev, int id, int *val);
70 
71 	/**
72 	 * get_str() - Read a specific string data value that describes the
73 	 *	       hardware setup.
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.
78 	 *
79 	 * Return: 0 if OK, -ve on error.
80 	 */
81 	int (*get_str)(struct udevice *dev, int id, size_t size, char *val);
82 };
83 
84 #define board_get_ops(dev)	((struct board_ops *)(dev)->driver->ops)
85 
86 /**
87  * board_detect() - Run the hardware info detection procedure for this device.
88  *
89  * @dev:	The device containing the information
90  *
91  * Return: 0 if OK, -ve on error.
92  */
93 int board_detect(struct udevice *dev);
94 
95 /**
96  * board_get_bool() - Read a specific bool data value that describes the
97  *		      hardware setup.
98  * @dev:	The board instance to gather the data.
99  * @id:		A unique identifier for the bool value to be read.
100  * @val:	Pointer to a buffer that receives the value read.
101  *
102  * Return: 0 if OK, -ve on error.
103  */
104 int board_get_bool(struct udevice *dev, int id, bool *val);
105 
106 /**
107  * board_get_int() - Read a specific int data value that describes the
108  *		     hardware setup.
109  * @dev:	The board instance to gather the data.
110  * @id:		A unique identifier for the int value to be read.
111  * @val:	Pointer to a buffer that receives the value read.
112  *
113  * Return: 0 if OK, -ve on error.
114  */
115 int board_get_int(struct udevice *dev, int id, int *val);
116 
117 /**
118  * board_get_str() - Read a specific string data value that describes the
119  *		     hardware setup.
120  * @dev:	The board instance to gather the data.
121  * @id:		A unique identifier for the string value to be read.
122  * @size:	The size of the buffer to receive the string data.
123  * @val:	Pointer to a buffer that receives the value read.
124  *
125  * Return: 0 if OK, -ve on error.
126  */
127 int board_get_str(struct udevice *dev, int id, size_t size, char *val);
128 
129 /**
130  * board_get() - Return the board device for the board in question.
131  * @devp: Pointer to structure to receive the board device.
132  *
133  * Since there can only be at most one board instance, the API can supply a
134  * function that returns the unique device. This is especially useful for use
135  * in board files.
136  *
137  * Return: 0 if OK, -ve on error.
138  */
139 int board_get(struct udevice **devp);
140