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