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