1.. SPDX-License-Identifier: GPL-2.0 2 3=============== 4NVMEM Subsystem 5=============== 6 7 Srinivas Kandagatla <srinivas.kandagatla@linaro.org> 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. This 30framework is based on regmap, so that most of the abstraction available in 31regmap can be reused, across multiple types of buses. 32 33NVMEM Providers 34+++++++++++++++ 35 36NVMEM provider refers to an entity that implements methods to initialize, read 37and write the non-volatile memory. 38 392. Registering/Unregistering the NVMEM provider 40=============================================== 41 42A NVMEM provider can register with NVMEM core by supplying relevant 43nvmem configuration to nvmem_register(), on success core would return a valid 44nvmem_device pointer. 45 46nvmem_unregister(nvmem) is used to unregister a previously registered provider. 47 48For example, a simple qfprom case:: 49 50 static struct nvmem_config econfig = { 51 .name = "qfprom", 52 .owner = THIS_MODULE, 53 }; 54 55 static int qfprom_probe(struct platform_device *pdev) 56 { 57 ... 58 econfig.dev = &pdev->dev; 59 nvmem = nvmem_register(&econfig); 60 ... 61 } 62 63It is mandatory that the NVMEM provider has a regmap associated with its 64struct device. Failure to do would return error code from nvmem_register(). 65 66Users of board files can define and register nvmem cells using the 67nvmem_cell_table struct:: 68 69 static struct nvmem_cell_info foo_nvmem_cells[] = { 70 { 71 .name = "macaddr", 72 .offset = 0x7f00, 73 .bytes = ETH_ALEN, 74 } 75 }; 76 77 static struct nvmem_cell_table foo_nvmem_cell_table = { 78 .nvmem_name = "i2c-eeprom", 79 .cells = foo_nvmem_cells, 80 .ncells = ARRAY_SIZE(foo_nvmem_cells), 81 }; 82 83 nvmem_add_cell_table(&foo_nvmem_cell_table); 84 85Additionally it is possible to create nvmem cell lookup entries and register 86them with the nvmem framework from machine code as shown in the example below:: 87 88 static struct nvmem_cell_lookup foo_nvmem_lookup = { 89 .nvmem_name = "i2c-eeprom", 90 .cell_name = "macaddr", 91 .dev_id = "foo_mac.0", 92 .con_id = "mac-address", 93 }; 94 95 nvmem_add_cell_lookups(&foo_nvmem_lookup, 1); 96 97NVMEM Consumers 98+++++++++++++++ 99 100NVMEM consumers are the entities which make use of the NVMEM provider to 101read from and to NVMEM. 102 1033. NVMEM cell based consumer APIs 104================================= 105 106NVMEM cells are the data entries/fields in the NVMEM. 107The NVMEM framework provides 3 APIs to read/write NVMEM cells:: 108 109 struct nvmem_cell *nvmem_cell_get(struct device *dev, const char *name); 110 struct nvmem_cell *devm_nvmem_cell_get(struct device *dev, const char *name); 111 112 void nvmem_cell_put(struct nvmem_cell *cell); 113 void devm_nvmem_cell_put(struct device *dev, struct nvmem_cell *cell); 114 115 void *nvmem_cell_read(struct nvmem_cell *cell, ssize_t *len); 116 int nvmem_cell_write(struct nvmem_cell *cell, void *buf, ssize_t len); 117 118`*nvmem_cell_get()` apis will get a reference to nvmem cell for a given id, 119and nvmem_cell_read/write() can then read or write to the cell. 120Once the usage of the cell is finished the consumer should call 121`*nvmem_cell_put()` to free all the allocation memory for the cell. 122 1234. Direct NVMEM device based consumer APIs 124========================================== 125 126In some instances it is necessary to directly read/write the NVMEM. 127To facilitate such consumers NVMEM framework provides below apis:: 128 129 struct nvmem_device *nvmem_device_get(struct device *dev, const char *name); 130 struct nvmem_device *devm_nvmem_device_get(struct device *dev, 131 const char *name); 132 struct nvmem_device *nvmem_device_find(void *data, 133 int (*match)(struct device *dev, const void *data)); 134 void nvmem_device_put(struct nvmem_device *nvmem); 135 int nvmem_device_read(struct nvmem_device *nvmem, unsigned int offset, 136 size_t bytes, void *buf); 137 int nvmem_device_write(struct nvmem_device *nvmem, unsigned int offset, 138 size_t bytes, void *buf); 139 int nvmem_device_cell_read(struct nvmem_device *nvmem, 140 struct nvmem_cell_info *info, void *buf); 141 int nvmem_device_cell_write(struct nvmem_device *nvmem, 142 struct nvmem_cell_info *info, void *buf); 143 144Before the consumers can read/write NVMEM directly, it should get hold 145of nvmem_controller from one of the `*nvmem_device_get()` api. 146 147The difference between these apis and cell based apis is that these apis always 148take nvmem_device as parameter. 149 1505. Releasing a reference to the NVMEM 151===================================== 152 153When a consumer no longer needs the NVMEM, it has to release the reference 154to the NVMEM it has obtained using the APIs mentioned in the above section. 155The NVMEM framework provides 2 APIs to release a reference to the NVMEM:: 156 157 void nvmem_cell_put(struct nvmem_cell *cell); 158 void devm_nvmem_cell_put(struct device *dev, struct nvmem_cell *cell); 159 void nvmem_device_put(struct nvmem_device *nvmem); 160 void devm_nvmem_device_put(struct device *dev, struct nvmem_device *nvmem); 161 162Both these APIs are used to release a reference to the NVMEM and 163devm_nvmem_cell_put and devm_nvmem_device_put destroys the devres associated 164with this NVMEM. 165 166Userspace 167+++++++++ 168 1696. Userspace binary interface 170============================== 171 172Userspace can read/write the raw NVMEM file located at:: 173 174 /sys/bus/nvmem/devices/*/nvmem 175 176ex:: 177 178 hexdump /sys/bus/nvmem/devices/qfprom0/nvmem 179 180 0000000 0000 0000 0000 0000 0000 0000 0000 0000 181 * 182 00000a0 db10 2240 0000 e000 0c00 0c00 0000 0c00 183 0000000 0000 0000 0000 0000 0000 0000 0000 0000 184 ... 185 * 186 0001000 187 1887. DeviceTree Binding 189===================== 190 191See Documentation/devicetree/bindings/nvmem/nvmem.txt 192