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