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