0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 ===============
0004 NVMEM Subsystem
0005 ===============
0006
0007 Srinivas Kandagatla <srinivas.kandagatla@linaro.org>
0008
0009 This document explains the NVMEM Framework along with the APIs provided,
0010 and how to use it.
0011
0012 1. Introduction
0013 ===============
0014 *NVMEM* is the abbreviation for Non Volatile Memory layer. It is used to
0015 retrieve configuration of SOC or Device specific data from non volatile
0016 memories like eeprom, efuses and so on.
0017
0018 Before this framework existed, NVMEM drivers like eeprom were stored in
0019 drivers/misc, where they all had to duplicate pretty much the same code to
0020 register a sysfs file, allow in-kernel users to access the content of the
0021 devices they were driving, etc.
0022
0023 This was also a problem as far as other in-kernel users were involved, since
0024 the solutions used were pretty much different from one driver to another, there
0025 was a rather big abstraction leak.
0026
0027 This framework aims at solve these problems. It also introduces DT
0028 representation for consumer devices to go get the data they require (MAC
0029 Addresses, SoC/Revision ID, part numbers, and so on) from the NVMEMs.
0030
0031 NVMEM Providers
0032 +++++++++++++++
0033
0034 NVMEM provider refers to an entity that implements methods to initialize, read
0035 and write the non-volatile memory.
0036
0037 2. Registering/Unregistering the NVMEM provider
0038 ===============================================
0039
0040 A NVMEM provider can register with NVMEM core by supplying relevant
0041 nvmem configuration to nvmem_register(), on success core would return a valid
0042 nvmem_device pointer.
0043
0044 nvmem_unregister(nvmem) is used to unregister a previously registered provider.
0045
0046 For example, a simple nvram case::
0047
0048 static int brcm_nvram_probe(struct platform_device *pdev)
0049 {
0050 struct nvmem_config config = {
0051 .name = "brcm-nvram",
0052 .reg_read = brcm_nvram_read,
0053 };
0054 ...
0055 config.dev = &pdev->dev;
0056 config.priv = priv;
0057 config.size = resource_size(res);
0058
0059 devm_nvmem_register(&config);
0060 }
0061
0062 Users of board files can define and register nvmem cells using the
0063 nvmem_cell_table struct::
0064
0065 static struct nvmem_cell_info foo_nvmem_cells[] = {
0066 {
0067 .name = "macaddr",
0068 .offset = 0x7f00,
0069 .bytes = ETH_ALEN,
0070 }
0071 };
0072
0073 static struct nvmem_cell_table foo_nvmem_cell_table = {
0074 .nvmem_name = "i2c-eeprom",
0075 .cells = foo_nvmem_cells,
0076 .ncells = ARRAY_SIZE(foo_nvmem_cells),
0077 };
0078
0079 nvmem_add_cell_table(&foo_nvmem_cell_table);
0080
0081 Additionally it is possible to create nvmem cell lookup entries and register
0082 them with the nvmem framework from machine code as shown in the example below::
0083
0084 static struct nvmem_cell_lookup foo_nvmem_lookup = {
0085 .nvmem_name = "i2c-eeprom",
0086 .cell_name = "macaddr",
0087 .dev_id = "foo_mac.0",
0088 .con_id = "mac-address",
0089 };
0090
0091 nvmem_add_cell_lookups(&foo_nvmem_lookup, 1);
0092
0093 NVMEM Consumers
0094 +++++++++++++++
0095
0096 NVMEM consumers are the entities which make use of the NVMEM provider to
0097 read from and to NVMEM.
0098
0099 3. NVMEM cell based consumer APIs
0100 =================================
0101
0102 NVMEM cells are the data entries/fields in the NVMEM.
0103 The NVMEM framework provides 3 APIs to read/write NVMEM cells::
0104
0105 struct nvmem_cell *nvmem_cell_get(struct device *dev, const char *name);
0106 struct nvmem_cell *devm_nvmem_cell_get(struct device *dev, const char *name);
0107
0108 void nvmem_cell_put(struct nvmem_cell *cell);
0109 void devm_nvmem_cell_put(struct device *dev, struct nvmem_cell *cell);
0110
0111 void *nvmem_cell_read(struct nvmem_cell *cell, ssize_t *len);
0112 int nvmem_cell_write(struct nvmem_cell *cell, void *buf, ssize_t len);
0113
0114 `*nvmem_cell_get()` apis will get a reference to nvmem cell for a given id,
0115 and nvmem_cell_read/write() can then read or write to the cell.
0116 Once the usage of the cell is finished the consumer should call
0117 `*nvmem_cell_put()` to free all the allocation memory for the cell.
0118
0119 4. Direct NVMEM device based consumer APIs
0120 ==========================================
0121
0122 In some instances it is necessary to directly read/write the NVMEM.
0123 To facilitate such consumers NVMEM framework provides below apis::
0124
0125 struct nvmem_device *nvmem_device_get(struct device *dev, const char *name);
0126 struct nvmem_device *devm_nvmem_device_get(struct device *dev,
0127 const char *name);
0128 struct nvmem_device *nvmem_device_find(void *data,
0129 int (*match)(struct device *dev, const void *data));
0130 void nvmem_device_put(struct nvmem_device *nvmem);
0131 int nvmem_device_read(struct nvmem_device *nvmem, unsigned int offset,
0132 size_t bytes, void *buf);
0133 int nvmem_device_write(struct nvmem_device *nvmem, unsigned int offset,
0134 size_t bytes, void *buf);
0135 int nvmem_device_cell_read(struct nvmem_device *nvmem,
0136 struct nvmem_cell_info *info, void *buf);
0137 int nvmem_device_cell_write(struct nvmem_device *nvmem,
0138 struct nvmem_cell_info *info, void *buf);
0139
0140 Before the consumers can read/write NVMEM directly, it should get hold
0141 of nvmem_controller from one of the `*nvmem_device_get()` api.
0142
0143 The difference between these apis and cell based apis is that these apis always
0144 take nvmem_device as parameter.
0145
0146 5. Releasing a reference to the NVMEM
0147 =====================================
0148
0149 When a consumer no longer needs the NVMEM, it has to release the reference
0150 to the NVMEM it has obtained using the APIs mentioned in the above section.
0151 The NVMEM framework provides 2 APIs to release a reference to the NVMEM::
0152
0153 void nvmem_cell_put(struct nvmem_cell *cell);
0154 void devm_nvmem_cell_put(struct device *dev, struct nvmem_cell *cell);
0155 void nvmem_device_put(struct nvmem_device *nvmem);
0156 void devm_nvmem_device_put(struct device *dev, struct nvmem_device *nvmem);
0157
0158 Both these APIs are used to release a reference to the NVMEM and
0159 devm_nvmem_cell_put and devm_nvmem_device_put destroys the devres associated
0160 with this NVMEM.
0161
0162 Userspace
0163 +++++++++
0164
0165 6. Userspace binary interface
0166 ==============================
0167
0168 Userspace can read/write the raw NVMEM file located at::
0169
0170 /sys/bus/nvmem/devices/*/nvmem
0171
0172 ex::
0173
0174 hexdump /sys/bus/nvmem/devices/qfprom0/nvmem
0175
0176 0000000 0000 0000 0000 0000 0000 0000 0000 0000
0177 *
0178 00000a0 db10 2240 0000 e000 0c00 0c00 0000 0c00
0179 0000000 0000 0000 0000 0000 0000 0000 0000 0000
0180 ...
0181 *
0182 0001000
0183
0184 7. DeviceTree Binding
0185 =====================
0186
0187 See Documentation/devicetree/bindings/nvmem/nvmem.txt
