projects/linux·blob master · refs

202 lines · 6.7 KiB

1.. SPDX-License-Identifier: GPL-2.0
2
3===============
4NVMEM Subsystem
5===============
6
7 Srinivas Kandagatla <[email protected]>
8
9This document explains the NVMEM Framework along with the APIs provided,
10and how to use it.
11
121. Introduction
13===============
14*NVMEM* is the abbreviation for Non Volatile Memory layer. It is used to
15retrieve configuration of SOC or Device specific data from non volatile
16memories like eeprom, efuses and so on.
17
18Before this framework existed, NVMEM drivers like eeprom were stored in
19drivers/misc, where they all had to duplicate pretty much the same code to
20register a sysfs file, allow in-kernel users to access the content of the
21devices they were driving, etc.
22
23This was also a problem as far as other in-kernel users were involved, since
24the solutions used were pretty much different from one driver to another, there
25was a rather big abstraction leak.
26
27This framework aims at solve these problems. It also introduces DT
28representation for consumer devices to go get the data they require (MAC
29Addresses, SoC/Revision ID, part numbers, and so on) from the NVMEMs.
30
31NVMEM Providers
32+++++++++++++++
33
34NVMEM provider refers to an entity that implements methods to initialize, read
35and write the non-volatile memory.
36
372. Registering/Unregistering the NVMEM provider
38===============================================
39
40A NVMEM provider can register with NVMEM core by supplying relevant
41nvmem configuration to nvmem_register(), on success core would return a valid
42nvmem_device pointer.
43
44nvmem_unregister() is used to unregister a previously registered provider.
45
46For example, a simple nvram case::
47
48 static int brcm_nvram_probe(struct platform_device *pdev)
49 {
50 struct nvmem_config config = {
51 .name = "brcm-nvram",
52 .reg_read = brcm_nvram_read,
53 };
54 ...
55 config.dev = &pdev->dev;
56 config.priv = priv;
57 config.size = resource_size(res);
58
59 devm_nvmem_register(&config);
60 }
61
62Device drivers can define and register an nvmem cell using the nvmem_cell_info
63struct::
64
65 static const struct nvmem_cell_info foo_nvmem_cell = {
66 {
67 .name = "macaddr",
68 .offset = 0x7f00,
69 .bytes = ETH_ALEN,
70 }
71 };
72
73 int nvmem_add_one_cell(nvmem, &foo_nvmem_cell);
74
75Additionally it is possible to create nvmem cell lookup entries and register
76them with the nvmem framework from machine code as shown in the example below::
77
78 static struct nvmem_cell_lookup foo_nvmem_lookup = {
79 .nvmem_name = "i2c-eeprom",
80 .cell_name = "macaddr",
81 .dev_id = "foo_mac.0",
82 .con_id = "mac-address",
83 };
84
85 nvmem_add_cell_lookups(&foo_nvmem_lookup, 1);
86
87NVMEM Consumers
88+++++++++++++++
89
90NVMEM consumers are the entities which make use of the NVMEM provider to
91read from and to NVMEM.
92
933. NVMEM cell based consumer APIs
94=================================
95
96NVMEM cells are the data entries/fields in the NVMEM.
97The NVMEM framework provides 3 APIs to read/write NVMEM cells::
98
99 struct nvmem_cell *nvmem_cell_get(struct device *dev, const char *name);
100 struct nvmem_cell *devm_nvmem_cell_get(struct device *dev, const char *name);
101
102 void nvmem_cell_put(struct nvmem_cell *cell);
103 void devm_nvmem_cell_put(struct device *dev, struct nvmem_cell *cell);
104
105 void *nvmem_cell_read(struct nvmem_cell *cell, ssize_t *len);
106 int nvmem_cell_write(struct nvmem_cell *cell, void *buf, ssize_t len);
107
108`*nvmem_cell_get()` apis will get a reference to nvmem cell for a given id,
109and nvmem_cell_read/write() can then read or write to the cell.
110Once the usage of the cell is finished the consumer should call
111`*nvmem_cell_put()` to free all the allocation memory for the cell.
112
1134. Direct NVMEM device based consumer APIs
114==========================================
115
116In some instances it is necessary to directly read/write the NVMEM.
117To facilitate such consumers NVMEM framework provides below apis::
118
119 struct nvmem_device *nvmem_device_get(struct device *dev, const char *name);
120 struct nvmem_device *devm_nvmem_device_get(struct device *dev,
121 const char *name);
122 struct nvmem_device *nvmem_device_find(void *data,
123 int (*match)(struct device *dev, const void *data));
124 void nvmem_device_put(struct nvmem_device *nvmem);
125 int nvmem_device_read(struct nvmem_device *nvmem, unsigned int offset,
126 size_t bytes, void *buf);
127 int nvmem_device_write(struct nvmem_device *nvmem, unsigned int offset,
128 size_t bytes, void *buf);
129 int nvmem_device_cell_read(struct nvmem_device *nvmem,
130 struct nvmem_cell_info *info, void *buf);
131 int nvmem_device_cell_write(struct nvmem_device *nvmem,
132 struct nvmem_cell_info *info, void *buf);
133
134Before the consumers can read/write NVMEM directly, it should get hold
135of nvmem_controller from one of the `*nvmem_device_get()` api.
136
137The difference between these apis and cell based apis is that these apis always
138take nvmem_device as parameter.
139
1405. Releasing a reference to the NVMEM
141=====================================
142
143When a consumer no longer needs the NVMEM, it has to release the reference
144to the NVMEM it has obtained using the APIs mentioned in the above section.
145The NVMEM framework provides 2 APIs to release a reference to the NVMEM::
146
147 void nvmem_cell_put(struct nvmem_cell *cell);
148 void devm_nvmem_cell_put(struct device *dev, struct nvmem_cell *cell);
149 void nvmem_device_put(struct nvmem_device *nvmem);
150 void devm_nvmem_device_put(struct device *dev, struct nvmem_device *nvmem);
151
152Both these APIs are used to release a reference to the NVMEM and
153devm_nvmem_cell_put and devm_nvmem_device_put destroys the devres associated
154with this NVMEM.
155
156Userspace
157+++++++++
158
1596. Userspace binary interface
160==============================
161
162Userspace can read/write the raw NVMEM file located at::
163
164 /sys/bus/nvmem/devices/*/nvmem
165
166ex::
167
168 hexdump /sys/bus/nvmem/devices/qfprom0/nvmem
169
170 0000000 0000 0000 0000 0000 0000 0000 0000 0000
171 *
172 00000a0 db10 2240 0000 e000 0c00 0c00 0000 0c00
173 0000000 0000 0000 0000 0000 0000 0000 0000 0000
174 ...
175 *
176 0001000
177
1787. DeviceTree Binding
179=====================
180
181See Documentation/devicetree/bindings/nvmem/nvmem.txt
182
1838. NVMEM layouts
184================
185
186NVMEM layouts are yet another mechanism to create cells. With the device
187tree binding it is possible to specify simple cells by using an offset
188and a length. Sometimes, the cells doesn't have a static offset, but
189the content is still well defined, e.g. tag-length-values. In this case,
190the NVMEM device content has to be first parsed and the cells need to
191be added accordingly. Layouts let you read the content of the NVMEM device
192and let you add cells dynamically.
193
194Another use case for layouts is the post processing of cells. With layouts,
195it is possible to associate a custom post processing hook to a cell. It
196even possible to add this hook to cells not created by the layout itself.
197
1989. Internal kernel API
199======================
200
201.. kernel-doc:: drivers/nvmem/core.c
202 :export: