blob: dbd40d879239456b6b17f815b6c1d86263d0c2e5 [file] [log] [blame]
Srinivas Kandagatla354ebb52015-07-27 12:14:14 +01001 NVMEM SUBSYSTEM
2 Srinivas Kandagatla <srinivas.kandagatla@linaro.org>
3
4This document explains the NVMEM Framework along with the APIs provided,
5and how to use it.
6
71. Introduction
8===============
9*NVMEM* is the abbreviation for Non Volatile Memory layer. It is used to
10retrieve configuration of SOC or Device specific data from non volatile
11memories like eeprom, efuses and so on.
12
13Before this framework existed, NVMEM drivers like eeprom were stored in
14drivers/misc, where they all had to duplicate pretty much the same code to
15register a sysfs file, allow in-kernel users to access the content of the
16devices they were driving, etc.
17
18This was also a problem as far as other in-kernel users were involved, since
19the solutions used were pretty much different from one driver to another, there
20was a rather big abstraction leak.
21
22This framework aims at solve these problems. It also introduces DT
23representation for consumer devices to go get the data they require (MAC
24Addresses, SoC/Revision ID, part numbers, and so on) from the NVMEMs. This
25framework is based on regmap, so that most of the abstraction available in
26regmap can be reused, across multiple types of buses.
27
28NVMEM Providers
29+++++++++++++++
30
31NVMEM provider refers to an entity that implements methods to initialize, read
32and write the non-volatile memory.
33
342. Registering/Unregistering the NVMEM provider
35===============================================
36
37A NVMEM provider can register with NVMEM core by supplying relevant
38nvmem configuration to nvmem_register(), on success core would return a valid
39nvmem_device pointer.
40
41nvmem_unregister(nvmem) is used to unregister a previously registered provider.
42
43For example, a simple qfprom case:
44
45static struct nvmem_config econfig = {
46 .name = "qfprom",
47 .owner = THIS_MODULE,
48};
49
50static int qfprom_probe(struct platform_device *pdev)
51{
52 ...
53 econfig.dev = &pdev->dev;
54 nvmem = nvmem_register(&econfig);
55 ...
56}
57
58It is mandatory that the NVMEM provider has a regmap associated with its
59struct device. Failure to do would return error code from nvmem_register().
60
61NVMEM Consumers
62+++++++++++++++
63
64NVMEM consumers are the entities which make use of the NVMEM provider to
65read from and to NVMEM.
66
673. NVMEM cell based consumer APIs
68=================================
69
70NVMEM cells are the data entries/fields in the NVMEM.
71The NVMEM framework provides 3 APIs to read/write NVMEM cells.
72
73struct nvmem_cell *nvmem_cell_get(struct device *dev, const char *name);
74struct nvmem_cell *devm_nvmem_cell_get(struct device *dev, const char *name);
75
76void nvmem_cell_put(struct nvmem_cell *cell);
77void devm_nvmem_cell_put(struct device *dev, struct nvmem_cell *cell);
78
79void *nvmem_cell_read(struct nvmem_cell *cell, ssize_t *len);
80int nvmem_cell_write(struct nvmem_cell *cell, void *buf, ssize_t len);
81
82*nvmem_cell_get() apis will get a reference to nvmem cell for a given id,
83and nvmem_cell_read/write() can then read or write to the cell.
84Once the usage of the cell is finished the consumer should call *nvmem_cell_put()
85to free all the allocation memory for the cell.
86
874. Direct NVMEM device based consumer APIs
88==========================================
89
90In some instances it is necessary to directly read/write the NVMEM.
91To facilitate such consumers NVMEM framework provides below apis.
92
93struct nvmem_device *nvmem_device_get(struct device *dev, const char *name);
94struct nvmem_device *devm_nvmem_device_get(struct device *dev,
95 const char *name);
96void nvmem_device_put(struct nvmem_device *nvmem);
97int nvmem_device_read(struct nvmem_device *nvmem, unsigned int offset,
98 size_t bytes, void *buf);
99int nvmem_device_write(struct nvmem_device *nvmem, unsigned int offset,
100 size_t bytes, void *buf);
101int nvmem_device_cell_read(struct nvmem_device *nvmem,
102 struct nvmem_cell_info *info, void *buf);
103int nvmem_device_cell_write(struct nvmem_device *nvmem,
104 struct nvmem_cell_info *info, void *buf);
105
106Before the consumers can read/write NVMEM directly, it should get hold
107of nvmem_controller from one of the *nvmem_device_get() api.
108
109The difference between these apis and cell based apis is that these apis always
110take nvmem_device as parameter.
111
1125. Releasing a reference to the NVMEM
113=====================================
114
115When a consumers no longer needs the NVMEM, it has to release the reference
116to the NVMEM it has obtained using the APIs mentioned in the above section.
117The NVMEM framework provides 2 APIs to release a reference to the NVMEM.
118
119void nvmem_cell_put(struct nvmem_cell *cell);
120void devm_nvmem_cell_put(struct device *dev, struct nvmem_cell *cell);
121void nvmem_device_put(struct nvmem_device *nvmem);
122void devm_nvmem_device_put(struct device *dev, struct nvmem_device *nvmem);
123
124Both these APIs are used to release a reference to the NVMEM and
125devm_nvmem_cell_put and devm_nvmem_device_put destroys the devres associated
126with this NVMEM.
127
128Userspace
129+++++++++
130
1316. Userspace binary interface
132==============================
133
134Userspace can read/write the raw NVMEM file located at
135/sys/bus/nvmem/devices/*/nvmem
136
137ex:
138
139hexdump /sys/bus/nvmem/devices/qfprom0/nvmem
140
1410000000 0000 0000 0000 0000 0000 0000 0000 0000
142*
14300000a0 db10 2240 0000 e000 0c00 0c00 0000 0c00
1440000000 0000 0000 0000 0000 0000 0000 0000 0000
145...
146*
1470001000
148
1497. DeviceTree Binding
150=====================
151
152See Documentation/devicetree/bindings/nvmem/nvmem.txt