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