[J-u-boot.git] / include / board.h

/* SPDX-License-Identifier: GPL-2.0+ */
/*
 * (C) Copyright 2017
 * Mario Six,  Guntermann & Drunck GmbH, [email protected]
 */

/*
 * This uclass encapsulates hardware methods to gather information about a
 * board or a specific device such as hard-wired GPIOs on GPIO expanders,
 * read-only data in flash ICs, or similar.
 *
 * The interface offers functions to read the usual standard data types (bool,
 * int, string) from the device, each of which is identified by a static
 * numeric ID (which will usually be defined as a enum in a header file).
 *
 * If for example the board had a read-only serial number flash IC, we could
 * call
 *
 * ret = board_detect(dev);
 * if (ret) {
 *	debug("board device not found.");
 *	return ret;
 * }
 *
 * ret = board_get_int(dev, ID_SERIAL_NUMBER, &serial);
 * if (ret) {
 *	debug("Error when reading serial number from device.");
 *	return ret;
 * }
 *
 * to read the serial number.
 */

struct board_ops {
	/**
	 * detect() - Run the hardware info detection procedure for this
	 *	      device.
	 * @dev:      The device containing the information
	 *
	 * This operation might take a long time (e.g. read from EEPROM,
	 * check the presence of a device on a bus etc.), hence this is not
	 * done in the probe() method, but later during operation in this
	 * dedicated method.
	 *
	 * Return: 0 if OK, -ve on error.
	 */
	int (*detect)(struct udevice *dev);

	/**
	 * get_bool() - Read a specific bool data value that describes the
	 *		hardware setup.
	 * @dev:	The board instance to gather the data.
	 * @id:		A unique identifier for the bool value to be read.
	 * @val:	Pointer to a buffer that receives the value read.
	 *
	 * Return: 0 if OK, -ve on error.
	 */
	int (*get_bool)(struct udevice *dev, int id, bool *val);

	/**
	 * get_int() - Read a specific int data value that describes the
	 *	       hardware setup.
	 * @dev:       The board instance to gather the data.
	 * @id:        A unique identifier for the int value to be read.
	 * @val:       Pointer to a buffer that receives the value read.
	 *
	 * Return: 0 if OK, -ve on error.
	 */
	int (*get_int)(struct udevice *dev, int id, int *val);

	/**
	 * get_str() - Read a specific string data value that describes the
	 *	       hardware setup.
	 * @dev:	The board instance to gather the data.
	 * @id:		A unique identifier for the string value to be read.
	 * @size:	The size of the buffer to receive the string data.
	 * @val:	Pointer to a buffer that receives the value read.
	 *
	 * Return: 0 if OK, -ve on error.
	 */
	int (*get_str)(struct udevice *dev, int id, size_t size, char *val);
};

#define board_get_ops(dev)	((struct board_ops *)(dev)->driver->ops)

/**
 * board_detect() - Run the hardware info detection procedure for this device.
 *
 * @dev:	The device containing the information
 *
 * Return: 0 if OK, -ve on error.
 */
int board_detect(struct udevice *dev);

/**
 * board_get_bool() - Read a specific bool data value that describes the
 *		      hardware setup.
 * @dev:	The board instance to gather the data.
 * @id:		A unique identifier for the bool value to be read.
 * @val:	Pointer to a buffer that receives the value read.
 *
 * Return: 0 if OK, -ve on error.
 */
int board_get_bool(struct udevice *dev, int id, bool *val);

/**
 * board_get_int() - Read a specific int data value that describes the
 *		     hardware setup.
 * @dev:	The board instance to gather the data.
 * @id:		A unique identifier for the int value to be read.
 * @val:	Pointer to a buffer that receives the value read.
 *
 * Return: 0 if OK, -ve on error.
 */
int board_get_int(struct udevice *dev, int id, int *val);

/**
 * board_get_str() - Read a specific string data value that describes the
 *		     hardware setup.
 * @dev:	The board instance to gather the data.
 * @id:		A unique identifier for the string value to be read.
 * @size:	The size of the buffer to receive the string data.
 * @val:	Pointer to a buffer that receives the value read.
 *
 * Return: 0 if OK, -ve on error.
 */
int board_get_str(struct udevice *dev, int id, size_t size, char *val);

/**
 * board_get() - Return the board device for the board in question.
 * @devp: Pointer to structure to receive the board device.
 *
 * Since there can only be at most one board instance, the API can supply a
 * function that returns the unique device. This is especially useful for use
 * in board files.
 *
 * Return: 0 if OK, -ve on error.
 */
int board_get(struct udevice **devp);
Commit	Line	Data
5381c285 MS	1	/* SPDX-License-Identifier: GPL-2.0+ */
	2	/*
	3	* (C) Copyright 2017
	4	* Mario Six, Guntermann & Drunck GmbH, [email protected]
	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);