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