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