include/nvmem.h

   1 /* SPDX-License-Identifier: GPL-2.0+ */
   2 /*
   3  * Copyright (c) 2022 Sean Anderson <sean.anderson@seco.com>
   4  */
   5
   6 #ifndef NVMEM_H
   7 #define NVMEM_H
   8
   9 /**
  10  * DOC: Design
  11  *
  12  * The NVMEM subsystem is a "meta-uclass" in that it abstracts over several
  13  * different uclasses all with read/write APIs. One approach to implementing
  14  * this could be to add a new sub-device for each nvmem-style device of
  15  * UCLASS_NVMEM. This subsystem has taken the approach of using the existing
  16  * access methods (i2c_eeprom_write, misc_write, etc.) directly. This has the
  17  * advantage of not requiring an extra device/driver, saving on binary size and
  18  * runtime memory usage. On the other hand, it is not idiomatic. Similar
  19  * efforts should generally use a new uclass.
  20  */
  21
  22 /**
  23  * struct nvmem_cell - One datum within non-volatile memory
  24  * @nvmem: The backing storage device
  25  * @offset: The offset of the cell from the start of @nvmem
  26  * @size: The size of the cell, in bytes
  27  */
  28 struct nvmem_cell {
  29         struct udevice *nvmem;
  30         unsigned int offset;
  31         size_t size;
  32 };
  33
  34 struct udevice;
  35
  36 #if CONFIG_IS_ENABLED(NVMEM)
  37
  38 /**
  39  * nvmem_cell_read() - Read the value of an nvmem cell
  40  * @cell: The nvmem cell to read
  41  * @buf: The buffer to read into
  42  * @size: The size of @buf
  43  *
  44  * Return:
  45  * * 0 on success
  46  * * -EINVAL if @buf is not the same size as @cell.
  47  * * -ENOSYS if CONFIG_NVMEM is disabled
  48  * * A negative error if there was a problem reading the underlying storage
  49  */
  50 int nvmem_cell_read(struct nvmem_cell *cell, void *buf, size_t size);
  51
  52 /**
  53  * nvmem_cell_write() - Write a value to an nvmem cell
  54  * @cell: The nvmem cell to write
  55  * @buf: The buffer to write from
  56  * @size: The size of @buf
  57  *
  58  * Return:
  59  * * 0 on success
  60  * * -EINVAL if @buf is not the same size as @cell
  61  * * -ENOSYS if @cell is read-only, or if CONFIG_NVMEM is disabled
  62  * * A negative error if there was a problem writing the underlying storage
  63  */
  64 int nvmem_cell_write(struct nvmem_cell *cell, const void *buf, size_t size);
  65
  66 /**
  67  * nvmem_cell_get_by_index() - Get an nvmem cell from a given device and index
  68  * @dev: The device that uses the nvmem cell
  69  * @index: The index of the cell in nvmem-cells
  70  * @cell: The cell to initialize
  71  *
  72  * Look up the nvmem cell referenced by the phandle at @index in nvmem-cells in
  73  * @dev.
  74  *
  75  * Return:
  76  * * 0 on success
  77  * * -EINVAL if the regs property is missing, empty, or undersized
  78  * * -ENODEV if the nvmem device is missing or unimplemented
  79  * * -ENOSYS if CONFIG_NVMEM is disabled
  80  * * A negative error if there was a problem reading nvmem-cells or getting the
  81  *   device
  82  */
  83 int nvmem_cell_get_by_index(struct udevice *dev, int index,
  84                             struct nvmem_cell *cell);
  85
  86 /**
  87  * nvmem_cell_get_by_name() - Get an nvmem cell from a given device and name
  88  * @dev: The device that uses the nvmem cell
  89  * @name: The name of the nvmem cell
  90  * @cell: The cell to initialize
  91  *
  92  * Look up the nvmem cell referenced by @name in the nvmem-cell-names property
  93  * of @dev.
  94  *
  95  * Return:
  96  * * 0 on success
  97  * * -EINVAL if the regs property is missing, empty, or undersized
  98  * * -ENODEV if the nvmem device is missing or unimplemented
  99  * * -ENODATA if @name is not in nvmem-cell-names
 100  * * -ENOSYS if CONFIG_NVMEM is disabled
 101  * * A negative error if there was a problem reading nvmem-cell-names,
 102  *   nvmem-cells, or getting the device
 103  */
 104 int nvmem_cell_get_by_name(struct udevice *dev, const char *name,
 105                            struct nvmem_cell *cell);
 106
 107 #else /* CONFIG_NVMEM */
 108
 109 static inline int nvmem_cell_read(struct nvmem_cell *cell, void *buf, int size)
 110 {
 111         return -ENOSYS;
 112 }
 113
 114 static inline int nvmem_cell_write(struct nvmem_cell *cell, const void *buf,
 115                                    int size)
 116 {
 117         return -ENOSYS;
 118 }
 119
 120 static inline int nvmem_cell_get_by_index(struct udevice *dev, int index,
 121                                           struct nvmem_cell *cell)
 122 {
 123         return -ENOSYS;
 124 }
 125
 126 static inline int nvmem_cell_get_by_name(struct udevice *dev, const char *name,
 127                                          struct nvmem_cell *cell)
 128 {
 129         return -ENOSYS;
 130 }
 131
 132 #endif /* CONFIG_NVMEM */
 133
 134 #endif /* NVMEM_H */