About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / nvmem


Based on kernel version 4.16.1. Page generated on 2018-04-09 11:53 EST.

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 consumer 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
Hide Line Numbers


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog