include/sysinfo.h

   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 #ifndef __SYSINFO_H__
   8 #define __SYSINFO_H__
   9
  10 struct udevice;
  11
  12 /*
  13  * This uclass encapsulates hardware methods to gather information about a
  14  * sysinfo or a specific device such as hard-wired GPIOs on GPIO expanders,
  15  * read-only data in flash ICs, or similar.
  16  *
  17  * The interface offers functions to read the usual standard data types (bool,
  18  * int, string) from the device, each of which is identified by a static
  19  * numeric ID (which will usually be defined as a enum in a header file).
  20  *
  21  * If for example the sysinfo had a read-only serial number flash IC, we could
  22  * call
  23  *
  24  * ret = sysinfo_detect(dev);
  25  * if (ret) {
  26  *      debug("sysinfo device not found.");
  27  *      return ret;
  28  * }
  29  *
  30  * ret = sysinfo_get_int(dev, ID_SERIAL_NUMBER, &serial);
  31  * if (ret) {
  32  *      debug("Error when reading serial number from device.");
  33  *      return ret;
  34  * }
  35  *
  36  * to read the serial number.
  37  */
  38
  39 /** enum sysinfo_id - Standard IDs defined by U-Boot */
  40 enum sysinfo_id {
  41         SYSINFO_ID_NONE,
  42
  43         /* For SMBIOS tables */
  44         SYSINFO_ID_SMBIOS_SYSTEM_VERSION,
  45         SYSINFO_ID_SMBIOS_BASEBOARD_VERSION,
  46
  47         /* For show_board_info() */
  48         SYSINFO_ID_BOARD_MODEL,
  49
  50         /* First value available for downstream/board used */
  51         SYSINFO_ID_USER = 0x1000,
  52 };
  53
  54 struct sysinfo_ops {
  55         /**
  56          * detect() - Run the hardware info detection procedure for this
  57          *            device.
  58          * @dev:      The device containing the information
  59          *
  60          * This operation might take a long time (e.g. read from EEPROM,
  61          * check the presence of a device on a bus etc.), hence this is not
  62          * done in the probe() method, but later during operation in this
  63          * dedicated method.
  64          *
  65          * Return: 0 if OK, -ve on error.
  66          */
  67         int (*detect)(struct udevice *dev);
  68
  69         /**
  70          * get_bool() - Read a specific bool data value that describes the
  71          *              hardware setup.
  72          * @dev:        The sysinfo instance to gather the data.
  73          * @id:         A unique identifier for the bool value to be read.
  74          * @val:        Pointer to a buffer that receives the value read.
  75          *
  76          * Return: 0 if OK, -ve on error.
  77          */
  78         int (*get_bool)(struct udevice *dev, int id, bool *val);
  79
  80         /**
  81          * get_int() - Read a specific int data value that describes the
  82          *             hardware setup.
  83          * @dev:       The sysinfo instance to gather the data.
  84          * @id:        A unique identifier for the int value to be read.
  85          * @val:       Pointer to a buffer that receives the value read.
  86          *
  87          * Return: 0 if OK, -ve on error.
  88          */
  89         int (*get_int)(struct udevice *dev, int id, int *val);
  90
  91         /**
  92          * get_str() - Read a specific string data value that describes the
  93          *             hardware setup.
  94          * @dev:        The sysinfo instance to gather the data.
  95          * @id:         A unique identifier for the string value to be read.
  96          * @size:       The size of the buffer to receive the string data.
  97          * @val:        Pointer to a buffer that receives the value read.
  98          *
  99          * Return: 0 if OK, -ve on error.
 100          */
 101         int (*get_str)(struct udevice *dev, int id, size_t size, char *val);
 102
 103         /**
 104          * get_fit_loadable - Get the name of an image to load from FIT
 105          * This function can be used to provide the image names based on runtime
 106          * detection. A classic use-case would when DTBOs are used to describe
 107          * additionnal daughter cards.
 108          *
 109          * @dev:        The sysinfo instance to gather the data.
 110          * @index:      Index of the image. Starts at 0 and gets incremented
 111          *              after each call to this function.
 112          * @type:       The type of image. For example, "fdt" for DTBs
 113          * @strp:       A pointer to string. Untouched if the function fails
 114          *
 115          * Return: 0 if OK, -ENOENT if no loadable is available else -ve on
 116          * error.
 117          */
 118         int (*get_fit_loadable)(struct udevice *dev, int index,
 119                                 const char *type, const char **strp);
 120 };
 121
 122 #define sysinfo_get_ops(dev)    ((struct sysinfo_ops *)(dev)->driver->ops)
 123
 124 #if CONFIG_IS_ENABLED(SYSINFO)
 125 /**
 126  * sysinfo_detect() - Run the hardware info detection procedure for this device.
 127  *
 128  * @dev:        The device containing the information
 129  *
 130  * Return: 0 if OK, -ve on error.
 131  */
 132 int sysinfo_detect(struct udevice *dev);
 133
 134 /**
 135  * sysinfo_get_bool() - Read a specific bool data value that describes the
 136  *                    hardware setup.
 137  * @dev:        The sysinfo instance to gather the data.
 138  * @id:         A unique identifier for the bool value to be read.
 139  * @val:        Pointer to a buffer that receives the value read.
 140  *
 141  * Return: 0 if OK, -ve on error.
 142  */
 143 int sysinfo_get_bool(struct udevice *dev, int id, bool *val);
 144
 145 /**
 146  * sysinfo_get_int() - Read a specific int data value that describes the
 147  *                   hardware setup.
 148  * @dev:        The sysinfo instance to gather the data.
 149  * @id:         A unique identifier for the int value to be read.
 150  * @val:        Pointer to a buffer that receives the value read.
 151  *
 152  * Return: 0 if OK, -ve on error.
 153  */
 154 int sysinfo_get_int(struct udevice *dev, int id, int *val);
 155
 156 /**
 157  * sysinfo_get_str() - Read a specific string data value that describes the
 158  *                   hardware setup.
 159  * @dev:        The sysinfo instance to gather the data.
 160  * @id:         A unique identifier for the string value to be read.
 161  * @size:       The size of the buffer to receive the string data.
 162  * @val:        Pointer to a buffer that receives the value read.
 163  *
 164  * Return: 0 if OK, -ve on error.
 165  */
 166 int sysinfo_get_str(struct udevice *dev, int id, size_t size, char *val);
 167
 168 /**
 169  * sysinfo_get() - Return the sysinfo device for the sysinfo in question.
 170  * @devp: Pointer to structure to receive the sysinfo device.
 171  *
 172  * Since there can only be at most one sysinfo instance, the API can supply a
 173  * function that returns the unique device. This is especially useful for use
 174  * in sysinfo files.
 175  *
 176  * Return: 0 if OK, -ve on error.
 177  */
 178 int sysinfo_get(struct udevice **devp);
 179
 180 /**
 181  * sysinfo_get_fit_loadable - Get the name of an image to load from FIT
 182  * This function can be used to provide the image names based on runtime
 183  * detection. A classic use-case would when DTBOs are used to describe
 184  * additionnal daughter cards.
 185  *
 186  * @dev:        The sysinfo instance to gather the data.
 187  * @index:      Index of the image. Starts at 0 and gets incremented
 188  *              after each call to this function.
 189  * @type:       The type of image. For example, "fdt" for DTBs
 190  * @strp:       A pointer to string. Untouched if the function fails
 191  *
 192  *
 193  * Return: 0 if OK, -ENOENT if no loadable is available else -ve on
 194  * error.
 195  */
 196 int sysinfo_get_fit_loadable(struct udevice *dev, int index, const char *type,
 197                              const char **strp);
 198
 199 #else
 200
 201 static inline int sysinfo_detect(struct udevice *dev)
 202 {
 203         return -ENOSYS;
 204 }
 205
 206 static inline int sysinfo_get_bool(struct udevice *dev, int id, bool *val)
 207 {
 208         return -ENOSYS;
 209 }
 210
 211 static inline int sysinfo_get_int(struct udevice *dev, int id, int *val)
 212 {
 213         return -ENOSYS;
 214 }
 215
 216 static inline int sysinfo_get_str(struct udevice *dev, int id, size_t size,
 217                                   char *val)
 218 {
 219         return -ENOSYS;
 220 }
 221
 222 static inline int sysinfo_get(struct udevice **devp)
 223 {
 224         return -ENOSYS;
 225 }
 226
 227 static inline int sysinfo_get_fit_loadable(struct udevice *dev, int index,
 228                                            const char *type, const char **strp)
 229 {
 230         return -ENOSYS;
 231 }
 232
 233 #endif
 234 #endif