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 struct board_ops {
  35         /**
  36          * detect() - Run the hardware info detection procedure for this
  37          *            device.
  38          * @dev:      The device containing the information
  39          *
  40          * This operation might take a long time (e.g. read from EEPROM,
  41          * check the presence of a device on a bus etc.), hence this is not
  42          * done in the probe() method, but later during operation in this
  43          * dedicated method.
  44          *
  45          * Return: 0 if OK, -ve on error.
  46          */
  47         int (*detect)(struct udevice *dev);
  48
  49         /**
  50          * get_bool() - Read a specific bool data value that describes the
  51          *              hardware setup.
  52          * @dev:        The board instance to gather the data.
  53          * @id:         A unique identifier for the bool value to be read.
  54          * @val:        Pointer to a buffer that receives the value read.
  55          *
  56          * Return: 0 if OK, -ve on error.
  57          */
  58         int (*get_bool)(struct udevice *dev, int id, bool *val);
  59
  60         /**
  61          * get_int() - Read a specific int data value that describes the
  62          *             hardware setup.
  63          * @dev:       The board instance to gather the data.
  64          * @id:        A unique identifier for the int 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_int)(struct udevice *dev, int id, int *val);
  70
  71         /**
  72          * get_str() - Read a specific string data value that describes the
  73          *             hardware setup.
  74          * @dev:        The board instance to gather the data.
  75          * @id:         A unique identifier for the string value to be read.
  76          * @size:       The size of the buffer to receive the string data.
  77          * @val:        Pointer to a buffer that receives the value read.
  78          *
  79          * Return: 0 if OK, -ve on error.
  80          */
  81         int (*get_str)(struct udevice *dev, int id, size_t size, char *val);
  82 };
  83
  84 #define board_get_ops(dev)      ((struct board_ops *)(dev)->driver->ops)
  85
  86 /**
  87  * board_detect() - Run the hardware info detection procedure for this device.
  88  *
  89  * @dev:        The device containing the information
  90  *
  91  * Return: 0 if OK, -ve on error.
  92  */
  93 int board_detect(struct udevice *dev);
  94
  95 /**
  96  * board_get_bool() - Read a specific bool data value that describes the
  97  *                    hardware setup.
  98  * @dev:        The board instance to gather the data.
  99  * @id:         A unique identifier for the bool value to be read.
 100  * @val:        Pointer to a buffer that receives the value read.
 101  *
 102  * Return: 0 if OK, -ve on error.
 103  */
 104 int board_get_bool(struct udevice *dev, int id, bool *val);
 105
 106 /**
 107  * board_get_int() - Read a specific int data value that describes the
 108  *                   hardware setup.
 109  * @dev:        The board instance to gather the data.
 110  * @id:         A unique identifier for the int value to be read.
 111  * @val:        Pointer to a buffer that receives the value read.
 112  *
 113  * Return: 0 if OK, -ve on error.
 114  */
 115 int board_get_int(struct udevice *dev, int id, int *val);
 116
 117 /**
 118  * board_get_str() - Read a specific string data value that describes the
 119  *                   hardware setup.
 120  * @dev:        The board instance to gather the data.
 121  * @id:         A unique identifier for the string value to be read.
 122  * @size:       The size of the buffer to receive the string data.
 123  * @val:        Pointer to a buffer that receives the value read.
 124  *
 125  * Return: 0 if OK, -ve on error.
 126  */
 127 int board_get_str(struct udevice *dev, int id, size_t size, char *val);
 128
 129 /**
 130  * board_get() - Return the board device for the board in question.
 131  * @devp: Pointer to structure to receive the board device.
 132  *
 133  * Since there can only be at most one board instance, the API can supply a
 134  * function that returns the unique device. This is especially useful for use
 135  * in board files.
 136  *
 137  * Return: 0 if OK, -ve on error.
 138  */
 139 int board_get(struct udevice **devp);