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. This method will be called before any other
  64          * methods.
  65          *
  66          * Return: 0 if OK, -ve on error.
  67          */
  68         int (*detect)(struct udevice *dev);
  69
  70         /**
  71          * get_bool() - Read a specific bool data value that describes the
  72          *              hardware setup.
  73          * @dev:        The sysinfo instance to gather the data.
  74          * @id:         A unique identifier for the bool value to be read.
  75          * @val:        Pointer to a buffer that receives the value read.
  76          *
  77          * Return: 0 if OK, -ve on error.
  78          */
  79         int (*get_bool)(struct udevice *dev, int id, bool *val);
  80
  81         /**
  82          * get_int() - Read a specific int data value that describes the
  83          *             hardware setup.
  84          * @dev:       The sysinfo instance to gather the data.
  85          * @id:        A unique identifier for the int value to be read.
  86          * @val:       Pointer to a buffer that receives the value read.
  87          *
  88          * Return: 0 if OK, -ve on error.
  89          */
  90         int (*get_int)(struct udevice *dev, int id, int *val);
  91
  92         /**
  93          * get_str() - Read a specific string data value that describes the
  94          *             hardware setup.
  95          * @dev:        The sysinfo instance to gather the data.
  96          * @id:         A unique identifier for the string value to be read.
  97          * @size:       The size of the buffer to receive the string data.
  98          * @val:        Pointer to a buffer that receives the value read.
  99          *
 100          * Return: 0 if OK, -ve on error.
 101          */
 102         int (*get_str)(struct udevice *dev, int id, size_t size, char *val);
 103
 104         /**
 105          * get_fit_loadable - Get the name of an image to load from FIT
 106          * This function can be used to provide the image names based on runtime
 107          * detection. A classic use-case would when DTBOs are used to describe
 108          * additional daughter cards.
 109          *
 110          * @dev:        The sysinfo instance to gather the data.
 111          * @index:      Index of the image. Starts at 0 and gets incremented
 112          *              after each call to this function.
 113          * @type:       The type of image. For example, "fdt" for DTBs
 114          * @strp:       A pointer to string. Untouched if the function fails
 115          *
 116          * Return: 0 if OK, -ENOENT if no loadable is available else -ve on
 117          * error.
 118          */
 119         int (*get_fit_loadable)(struct udevice *dev, int index,
 120                                 const char *type, const char **strp);
 121 };
 122
 123 #define sysinfo_get_ops(dev)    ((struct sysinfo_ops *)(dev)->driver->ops)
 124
 125 #if CONFIG_IS_ENABLED(SYSINFO)
 126 /**
 127  * sysinfo_detect() - Run the hardware info detection procedure for this device.
 128  *
 129  * @dev:        The device containing the information
 130  *
 131  * This function must be called before any other accessor function for this
 132  * device.
 133  *
 134  * Return: 0 if OK, -ve on error.
 135  */
 136 int sysinfo_detect(struct udevice *dev);
 137
 138 /**
 139  * sysinfo_get_bool() - Read a specific bool data value that describes the
 140  *                    hardware setup.
 141  * @dev:        The sysinfo instance to gather the data.
 142  * @id:         A unique identifier for the bool value to be read.
 143  * @val:        Pointer to a buffer that receives the value read.
 144  *
 145  * Return: 0 if OK, -EPERM if called before sysinfo_detect(), else -ve on
 146  * error.
 147  */
 148 int sysinfo_get_bool(struct udevice *dev, int id, bool *val);
 149
 150 /**
 151  * sysinfo_get_int() - Read a specific int data value that describes the
 152  *                   hardware setup.
 153  * @dev:        The sysinfo instance to gather the data.
 154  * @id:         A unique identifier for the int value to be read.
 155  * @val:        Pointer to a buffer that receives the value read.
 156  *
 157  * Return: 0 if OK, -EPERM if called before sysinfo_detect(), else -ve on
 158  * error.
 159  */
 160 int sysinfo_get_int(struct udevice *dev, int id, int *val);
 161
 162 /**
 163  * sysinfo_get_str() - Read a specific string data value that describes the
 164  *                   hardware setup.
 165  * @dev:        The sysinfo instance to gather the data.
 166  * @id:         A unique identifier for the string value to be read.
 167  * @size:       The size of the buffer to receive the string data.
 168  * @val:        Pointer to a buffer that receives the value read.
 169  *
 170  * Return: 0 if OK, -EPERM if called before sysinfo_detect(), else -ve on
 171  * error.
 172  */
 173 int sysinfo_get_str(struct udevice *dev, int id, size_t size, char *val);
 174
 175 /**
 176  * sysinfo_get() - Return the sysinfo device for the sysinfo in question.
 177  * @devp: Pointer to structure to receive the sysinfo device.
 178  *
 179  * Since there can only be at most one sysinfo instance, the API can supply a
 180  * function that returns the unique device. This is especially useful for use
 181  * in sysinfo files.
 182  *
 183  * Return: 0 if OK, -EPERM if called before sysinfo_detect(), else -ve on
 184  * error.
 185  */
 186 int sysinfo_get(struct udevice **devp);
 187
 188 /**
 189  * sysinfo_get_fit_loadable - Get the name of an image to load from FIT
 190  * This function can be used to provide the image names based on runtime
 191  * detection. A classic use-case would when DTBOs are used to describe
 192  * additional daughter cards.
 193  *
 194  * @dev:        The sysinfo instance to gather the data.
 195  * @index:      Index of the image. Starts at 0 and gets incremented
 196  *              after each call to this function.
 197  * @type:       The type of image. For example, "fdt" for DTBs
 198  * @strp:       A pointer to string. Untouched if the function fails
 199  *
 200  *
 201  * Return: 0 if OK, -EPERM if called before sysinfo_detect(), -ENOENT if no
 202  * loadable is available else -ve on error.
 203  */
 204 int sysinfo_get_fit_loadable(struct udevice *dev, int index, const char *type,
 205                              const char **strp);
 206
 207 #else
 208
 209 static inline int sysinfo_detect(struct udevice *dev)
 210 {
 211         return -ENOSYS;
 212 }
 213
 214 static inline int sysinfo_get_bool(struct udevice *dev, int id, bool *val)
 215 {
 216         return -ENOSYS;
 217 }
 218
 219 static inline int sysinfo_get_int(struct udevice *dev, int id, int *val)
 220 {
 221         return -ENOSYS;
 222 }
 223
 224 static inline int sysinfo_get_str(struct udevice *dev, int id, size_t size,
 225                                   char *val)
 226 {
 227         return -ENOSYS;
 228 }
 229
 230 static inline int sysinfo_get(struct udevice **devp)
 231 {
 232         return -ENOSYS;
 233 }
 234
 235 static inline int sysinfo_get_fit_loadable(struct udevice *dev, int index,
 236                                            const char *type, const char **strp)
 237 {
 238         return -ENOSYS;
 239 }
 240
 241 #endif
 242 #endif