blob: 9dc78684f8e0f6e49c77b941a32927491a44f2bc [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
34struct 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 */
93int 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 */
104int 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 */
115int 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 */
127int 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 */
139int board_get(struct udevice **devp);