Commit | Line | Data |
---|---|---|
baa293e9 | 1 | .. SPDX-License-Identifier: GPL-2.0 |
a278295c MCC |
2 | |
3 | =============== | |
4 | NVMEM Subsystem | |
5 | =============== | |
6 | ||
7 | Srinivas Kandagatla <srinivas.kandagatla@linaro.org> | |
354ebb54 SK |
8 | |
9 | This document explains the NVMEM Framework along with the APIs provided, | |
10 | and how to use it. | |
11 | ||
12 | 1. Introduction | |
13 | =============== | |
14 | *NVMEM* is the abbreviation for Non Volatile Memory layer. It is used to | |
15 | retrieve configuration of SOC or Device specific data from non volatile | |
16 | memories like eeprom, efuses and so on. | |
17 | ||
18 | Before this framework existed, NVMEM drivers like eeprom were stored in | |
19 | drivers/misc, where they all had to duplicate pretty much the same code to | |
20 | register a sysfs file, allow in-kernel users to access the content of the | |
21 | devices they were driving, etc. | |
22 | ||
23 | This was also a problem as far as other in-kernel users were involved, since | |
24 | the solutions used were pretty much different from one driver to another, there | |
25 | was a rather big abstraction leak. | |
26 | ||
27 | This framework aims at solve these problems. It also introduces DT | |
28 | representation for consumer devices to go get the data they require (MAC | |
29 | Addresses, SoC/Revision ID, part numbers, and so on) from the NVMEMs. This | |
30 | framework is based on regmap, so that most of the abstraction available in | |
31 | regmap can be reused, across multiple types of buses. | |
32 | ||
33 | NVMEM Providers | |
34 | +++++++++++++++ | |
35 | ||
36 | NVMEM provider refers to an entity that implements methods to initialize, read | |
37 | and write the non-volatile memory. | |
38 | ||
39 | 2. Registering/Unregistering the NVMEM provider | |
40 | =============================================== | |
41 | ||
42 | A NVMEM provider can register with NVMEM core by supplying relevant | |
43 | nvmem configuration to nvmem_register(), on success core would return a valid | |
44 | nvmem_device pointer. | |
45 | ||
46 | nvmem_unregister(nvmem) is used to unregister a previously registered provider. | |
47 | ||
a278295c | 48 | For example, a simple qfprom case:: |
354ebb54 | 49 | |
a278295c | 50 | static struct nvmem_config econfig = { |
354ebb54 SK |
51 | .name = "qfprom", |
52 | .owner = THIS_MODULE, | |
a278295c | 53 | }; |
354ebb54 | 54 | |
a278295c MCC |
55 | static int qfprom_probe(struct platform_device *pdev) |
56 | { | |
354ebb54 SK |
57 | ... |
58 | econfig.dev = &pdev->dev; | |
59 | nvmem = nvmem_register(&econfig); | |
60 | ... | |
a278295c | 61 | } |
354ebb54 SK |
62 | |
63 | It is mandatory that the NVMEM provider has a regmap associated with its | |
64 | struct device. Failure to do would return error code from nvmem_register(). | |
65 | ||
4903d19c | 66 | Users of board files can define and register nvmem cells using the |
a278295c | 67 | nvmem_cell_table struct:: |
4903d19c | 68 | |
a278295c | 69 | static struct nvmem_cell_info foo_nvmem_cells[] = { |
4903d19c BG |
70 | { |
71 | .name = "macaddr", | |
72 | .offset = 0x7f00, | |
73 | .bytes = ETH_ALEN, | |
74 | } | |
a278295c | 75 | }; |
4903d19c | 76 | |
a278295c | 77 | static struct nvmem_cell_table foo_nvmem_cell_table = { |
4903d19c BG |
78 | .nvmem_name = "i2c-eeprom", |
79 | .cells = foo_nvmem_cells, | |
80 | .ncells = ARRAY_SIZE(foo_nvmem_cells), | |
a278295c | 81 | }; |
4903d19c | 82 | |
a278295c | 83 | nvmem_add_cell_table(&foo_nvmem_cell_table); |
4903d19c BG |
84 | |
85 | Additionally it is possible to create nvmem cell lookup entries and register | |
a278295c | 86 | them with the nvmem framework from machine code as shown in the example below:: |
4903d19c | 87 | |
a278295c | 88 | static struct nvmem_cell_lookup foo_nvmem_lookup = { |
4903d19c BG |
89 | .nvmem_name = "i2c-eeprom", |
90 | .cell_name = "macaddr", | |
91 | .dev_id = "foo_mac.0", | |
92 | .con_id = "mac-address", | |
a278295c | 93 | }; |
4903d19c | 94 | |
a278295c | 95 | nvmem_add_cell_lookups(&foo_nvmem_lookup, 1); |
4903d19c | 96 | |
354ebb54 SK |
97 | NVMEM Consumers |
98 | +++++++++++++++ | |
99 | ||
100 | NVMEM consumers are the entities which make use of the NVMEM provider to | |
101 | read from and to NVMEM. | |
102 | ||
103 | 3. NVMEM cell based consumer APIs | |
104 | ================================= | |
105 | ||
106 | NVMEM cells are the data entries/fields in the NVMEM. | |
a278295c | 107 | The NVMEM framework provides 3 APIs to read/write NVMEM cells:: |
354ebb54 | 108 | |
a278295c MCC |
109 | struct nvmem_cell *nvmem_cell_get(struct device *dev, const char *name); |
110 | struct nvmem_cell *devm_nvmem_cell_get(struct device *dev, const char *name); | |
354ebb54 | 111 | |
a278295c MCC |
112 | void nvmem_cell_put(struct nvmem_cell *cell); |
113 | void devm_nvmem_cell_put(struct device *dev, struct nvmem_cell *cell); | |
354ebb54 | 114 | |
a278295c MCC |
115 | void *nvmem_cell_read(struct nvmem_cell *cell, ssize_t *len); |
116 | int nvmem_cell_write(struct nvmem_cell *cell, void *buf, ssize_t len); | |
354ebb54 | 117 | |
a278295c | 118 | `*nvmem_cell_get()` apis will get a reference to nvmem cell for a given id, |
354ebb54 | 119 | and nvmem_cell_read/write() can then read or write to the cell. |
a278295c MCC |
120 | Once the usage of the cell is finished the consumer should call |
121 | `*nvmem_cell_put()` to free all the allocation memory for the cell. | |
354ebb54 SK |
122 | |
123 | 4. Direct NVMEM device based consumer APIs | |
124 | ========================================== | |
125 | ||
126 | In some instances it is necessary to directly read/write the NVMEM. | |
a278295c | 127 | To facilitate such consumers NVMEM framework provides below apis:: |
354ebb54 | 128 | |
a278295c MCC |
129 | struct nvmem_device *nvmem_device_get(struct device *dev, const char *name); |
130 | struct nvmem_device *devm_nvmem_device_get(struct device *dev, | |
354ebb54 | 131 | const char *name); |
a278295c MCC |
132 | void nvmem_device_put(struct nvmem_device *nvmem); |
133 | int nvmem_device_read(struct nvmem_device *nvmem, unsigned int offset, | |
354ebb54 | 134 | size_t bytes, void *buf); |
a278295c | 135 | int nvmem_device_write(struct nvmem_device *nvmem, unsigned int offset, |
354ebb54 | 136 | size_t bytes, void *buf); |
a278295c | 137 | int nvmem_device_cell_read(struct nvmem_device *nvmem, |
354ebb54 | 138 | struct nvmem_cell_info *info, void *buf); |
a278295c | 139 | int nvmem_device_cell_write(struct nvmem_device *nvmem, |
354ebb54 SK |
140 | struct nvmem_cell_info *info, void *buf); |
141 | ||
142 | Before the consumers can read/write NVMEM directly, it should get hold | |
a278295c | 143 | of nvmem_controller from one of the `*nvmem_device_get()` api. |
354ebb54 SK |
144 | |
145 | The difference between these apis and cell based apis is that these apis always | |
146 | take nvmem_device as parameter. | |
147 | ||
148 | 5. Releasing a reference to the NVMEM | |
149 | ===================================== | |
150 | ||
be629b44 | 151 | When a consumer no longer needs the NVMEM, it has to release the reference |
354ebb54 | 152 | to the NVMEM it has obtained using the APIs mentioned in the above section. |
a278295c | 153 | The NVMEM framework provides 2 APIs to release a reference to the NVMEM:: |
354ebb54 | 154 | |
a278295c MCC |
155 | void nvmem_cell_put(struct nvmem_cell *cell); |
156 | void devm_nvmem_cell_put(struct device *dev, struct nvmem_cell *cell); | |
157 | void nvmem_device_put(struct nvmem_device *nvmem); | |
158 | void devm_nvmem_device_put(struct device *dev, struct nvmem_device *nvmem); | |
354ebb54 SK |
159 | |
160 | Both these APIs are used to release a reference to the NVMEM and | |
161 | devm_nvmem_cell_put and devm_nvmem_device_put destroys the devres associated | |
162 | with this NVMEM. | |
163 | ||
164 | Userspace | |
165 | +++++++++ | |
166 | ||
167 | 6. Userspace binary interface | |
168 | ============================== | |
169 | ||
a278295c MCC |
170 | Userspace can read/write the raw NVMEM file located at:: |
171 | ||
172 | /sys/bus/nvmem/devices/*/nvmem | |
354ebb54 | 173 | |
a278295c | 174 | ex:: |
354ebb54 | 175 | |
a278295c | 176 | hexdump /sys/bus/nvmem/devices/qfprom0/nvmem |
354ebb54 | 177 | |
a278295c MCC |
178 | 0000000 0000 0000 0000 0000 0000 0000 0000 0000 |
179 | * | |
180 | 00000a0 db10 2240 0000 e000 0c00 0c00 0000 0c00 | |
181 | 0000000 0000 0000 0000 0000 0000 0000 0000 0000 | |
182 | ... | |
183 | * | |
184 | 0001000 | |
354ebb54 SK |
185 | |
186 | 7. DeviceTree Binding | |
187 | ===================== | |
188 | ||
189 | See Documentation/devicetree/bindings/nvmem/nvmem.txt |