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