Documentation/driver-api/nvmem.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 ===============
   4 NVMEM Subsystem
   5 ===============
   6
   7  Srinivas Kandagatla <srinivas.kandagatla@linaro.org>
   8
   9 This document explains the NVMEM Framework along with the APIs provided,
  10 and how to use it.
  11
  12 1. Introduction
  13 ===============
  14 *NVMEM* is the abbreviation for Non Volatile Memory layer. It is used to
  15 retrieve configuration of SOC or Device specific data from non volatile
  16 memories like eeprom, efuses and so on.
  17
  18 Before this framework existed, NVMEM drivers like eeprom were stored in
  19 drivers/misc, where they all had to duplicate pretty much the same code to
  20 register a sysfs file, allow in-kernel users to access the content of the
  21 devices they were driving, etc.
  22
  23 This was also a problem as far as other in-kernel users were involved, since
  24 the solutions used were pretty much different from one driver to another, there
  25 was a rather big abstraction leak.
  26
  27 This framework aims at solve these problems. It also introduces DT
  28 representation for consumer devices to go get the data they require (MAC
  29 Addresses, SoC/Revision ID, part numbers, and so on) from the NVMEMs. This
  30 framework is based on regmap, so that most of the abstraction available in
  31 regmap can be reused, across multiple types of buses.
  32
  33 NVMEM Providers
  34 +++++++++++++++
  35
  36 NVMEM provider refers to an entity that implements methods to initialize, read
  37 and write the non-volatile memory.
  38
  39 2. Registering/Unregistering the NVMEM provider
  40 ===============================================
  41
  42 A NVMEM provider can register with NVMEM core by supplying relevant
  43 nvmem configuration to nvmem_register(), on success core would return a valid
  44 nvmem_device pointer.
  45
  46 nvmem_unregister(nvmem) is used to unregister a previously registered provider.
  47
  48 For 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
  63 It is mandatory that the NVMEM provider has a regmap associated with its
  64 struct device. Failure to do would return error code from nvmem_register().
  65
  66 Users of board files can define and register nvmem cells using the
  67 nvmem_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
  85 Additionally it is possible to create nvmem cell lookup entries and register
  86 them 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
  97 NVMEM Consumers
  98 +++++++++++++++
  99
 100 NVMEM consumers are the entities which make use of the NVMEM provider to
 101 read from and to NVMEM.
 102
 103 3. NVMEM cell based consumer APIs
 104 =================================
 105
 106 NVMEM cells are the data entries/fields in the NVMEM.
 107 The 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,
 119 and nvmem_cell_read/write() can then read or write to the cell.
 120 Once 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
 123 4. Direct NVMEM device based consumer APIs
 124 ==========================================
 125
 126 In some instances it is necessary to directly read/write the NVMEM.
 127 To 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
 144 Before the consumers can read/write NVMEM directly, it should get hold
 145 of nvmem_controller from one of the `*nvmem_device_get()` api.
 146
 147 The difference between these apis and cell based apis is that these apis always
 148 take nvmem_device as parameter.
 149
 150 5. Releasing a reference to the NVMEM
 151 =====================================
 152
 153 When a consumer no longer needs the NVMEM, it has to release the reference
 154 to the NVMEM it has obtained using the APIs mentioned in the above section.
 155 The 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
 162 Both these APIs are used to release a reference to the NVMEM and
 163 devm_nvmem_cell_put and devm_nvmem_device_put destroys the devres associated
 164 with this NVMEM.
 165
 166 Userspace
 167 +++++++++
 168
 169 6. Userspace binary interface
 170 ==============================
 171
 172 Userspace can read/write the raw NVMEM file located at::
 173
 174         /sys/bus/nvmem/devices/*/nvmem
 175
 176 ex::
 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
 188 7. DeviceTree Binding
 189 =====================
 190
 191 See Documentation/devicetree/bindings/nvmem/nvmem.txt