^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) .. SPDX-License-Identifier: GPL-2.0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) ===============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4) NVMEM Subsystem
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) ===============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) Srinivas Kandagatla <srinivas.kandagatla@linaro.org>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) This document explains the NVMEM Framework along with the APIs provided,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) and how to use it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) 1. Introduction
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) ===============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) *NVMEM* is the abbreviation for Non Volatile Memory layer. It is used to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) retrieve configuration of SOC or Device specific data from non volatile
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) memories like eeprom, efuses and so on.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) Before this framework existed, NVMEM drivers like eeprom were stored in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) drivers/misc, where they all had to duplicate pretty much the same code to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) register a sysfs file, allow in-kernel users to access the content of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) devices they were driving, etc.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) This was also a problem as far as other in-kernel users were involved, since
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) the solutions used were pretty much different from one driver to another, there
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) was a rather big abstraction leak.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) This framework aims at solve these problems. It also introduces DT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) representation for consumer devices to go get the data they require (MAC
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) Addresses, SoC/Revision ID, part numbers, and so on) from the NVMEMs. This
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) framework is based on regmap, so that most of the abstraction available in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) regmap can be reused, across multiple types of buses.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) NVMEM Providers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) +++++++++++++++
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) NVMEM provider refers to an entity that implements methods to initialize, read
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) and write the non-volatile memory.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) 2. Registering/Unregistering the NVMEM provider
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) ===============================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) A NVMEM provider can register with NVMEM core by supplying relevant
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) nvmem configuration to nvmem_register(), on success core would return a valid
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) nvmem_device pointer.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) nvmem_unregister(nvmem) is used to unregister a previously registered provider.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) For example, a simple qfprom case::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) static struct nvmem_config econfig = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) .name = "qfprom",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) .owner = THIS_MODULE,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) static int qfprom_probe(struct platform_device *pdev)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) econfig.dev = &pdev->dev;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) nvmem = nvmem_register(&econfig);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) It is mandatory that the NVMEM provider has a regmap associated with its
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) struct device. Failure to do would return error code from nvmem_register().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) Users of board files can define and register nvmem cells using the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) nvmem_cell_table struct::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) static struct nvmem_cell_info foo_nvmem_cells[] = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) .name = "macaddr",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) .offset = 0x7f00,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) .bytes = ETH_ALEN,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) static struct nvmem_cell_table foo_nvmem_cell_table = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) .nvmem_name = "i2c-eeprom",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) .cells = foo_nvmem_cells,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) .ncells = ARRAY_SIZE(foo_nvmem_cells),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) nvmem_add_cell_table(&foo_nvmem_cell_table);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) Additionally it is possible to create nvmem cell lookup entries and register
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) them with the nvmem framework from machine code as shown in the example below::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) static struct nvmem_cell_lookup foo_nvmem_lookup = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) .nvmem_name = "i2c-eeprom",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) .cell_name = "macaddr",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) .dev_id = "foo_mac.0",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) .con_id = "mac-address",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) nvmem_add_cell_lookups(&foo_nvmem_lookup, 1);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) NVMEM Consumers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) +++++++++++++++
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) NVMEM consumers are the entities which make use of the NVMEM provider to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) read from and to NVMEM.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) 3. NVMEM cell based consumer APIs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) =================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) NVMEM cells are the data entries/fields in the NVMEM.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) The NVMEM framework provides 3 APIs to read/write NVMEM cells::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) struct nvmem_cell *nvmem_cell_get(struct device *dev, const char *name);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) struct nvmem_cell *devm_nvmem_cell_get(struct device *dev, const char *name);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) void nvmem_cell_put(struct nvmem_cell *cell);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) void devm_nvmem_cell_put(struct device *dev, struct nvmem_cell *cell);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) void *nvmem_cell_read(struct nvmem_cell *cell, ssize_t *len);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) int nvmem_cell_write(struct nvmem_cell *cell, void *buf, ssize_t len);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) `*nvmem_cell_get()` apis will get a reference to nvmem cell for a given id,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) and nvmem_cell_read/write() can then read or write to the cell.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) Once the usage of the cell is finished the consumer should call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) `*nvmem_cell_put()` to free all the allocation memory for the cell.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) 4. Direct NVMEM device based consumer APIs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) ==========================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) In some instances it is necessary to directly read/write the NVMEM.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) To facilitate such consumers NVMEM framework provides below apis::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) struct nvmem_device *nvmem_device_get(struct device *dev, const char *name);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) struct nvmem_device *devm_nvmem_device_get(struct device *dev,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) const char *name);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) struct nvmem_device *nvmem_device_find(void *data,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) int (*match)(struct device *dev, const void *data));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) void nvmem_device_put(struct nvmem_device *nvmem);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) int nvmem_device_read(struct nvmem_device *nvmem, unsigned int offset,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) size_t bytes, void *buf);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) int nvmem_device_write(struct nvmem_device *nvmem, unsigned int offset,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) size_t bytes, void *buf);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) int nvmem_device_cell_read(struct nvmem_device *nvmem,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) struct nvmem_cell_info *info, void *buf);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) int nvmem_device_cell_write(struct nvmem_device *nvmem,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) struct nvmem_cell_info *info, void *buf);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) Before the consumers can read/write NVMEM directly, it should get hold
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) of nvmem_controller from one of the `*nvmem_device_get()` api.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) The difference between these apis and cell based apis is that these apis always
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) take nvmem_device as parameter.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) 5. Releasing a reference to the NVMEM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) =====================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) When a consumer no longer needs the NVMEM, it has to release the reference
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) to the NVMEM it has obtained using the APIs mentioned in the above section.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) The NVMEM framework provides 2 APIs to release a reference to the NVMEM::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) void nvmem_cell_put(struct nvmem_cell *cell);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) void devm_nvmem_cell_put(struct device *dev, struct nvmem_cell *cell);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) void nvmem_device_put(struct nvmem_device *nvmem);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) void devm_nvmem_device_put(struct device *dev, struct nvmem_device *nvmem);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) Both these APIs are used to release a reference to the NVMEM and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) devm_nvmem_cell_put and devm_nvmem_device_put destroys the devres associated
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) with this NVMEM.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) Userspace
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) +++++++++
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) 6. Userspace binary interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) ==============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) Userspace can read/write the raw NVMEM file located at::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) /sys/bus/nvmem/devices/*/nvmem
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) ex::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) hexdump /sys/bus/nvmem/devices/qfprom0/nvmem
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) 0000000 0000 0000 0000 0000 0000 0000 0000 0000
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) 00000a0 db10 2240 0000 e000 0c00 0c00 0000 0c00
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) 0000000 0000 0000 0000 0000 0000 0000 0000 0000
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) 0001000
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) 7. DeviceTree Binding
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) =====================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) See Documentation/devicetree/bindings/nvmem/nvmem.txt
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags