Commit | Line | Data |
---|---|---|
354ebb54 SK |
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 |