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
nvmem_cell_read(struct nvmem_cell * cell,void * buf,int size)109 static inline int nvmem_cell_read(struct nvmem_cell *cell, void *buf, int size)
110 {
111 return -ENOSYS;
112 }
113
nvmem_cell_write(struct nvmem_cell * cell,const void * buf,int size)114 static inline int nvmem_cell_write(struct nvmem_cell *cell, const void *buf,
115 int size)
116 {
117 return -ENOSYS;
118 }
119
nvmem_cell_get_by_index(struct udevice * dev,int index,struct nvmem_cell * cell)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
nvmem_cell_get_by_name(struct udevice * dev,const char * name,struct nvmem_cell * cell)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 */
135