Documentation/nvmem/nvmem.txt

   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 Users of board files can define and register nvmem cells using the
  62 nvmem_cell_table struct:
  63
  64 static struct nvmem_cell_info foo_nvmem_cells[] = {
  65         {
  66                 .name           = "macaddr",
  67                 .offset         = 0x7f00,
  68                 .bytes          = ETH_ALEN,
  69         }
  70 };
  71
  72 static struct nvmem_cell_table foo_nvmem_cell_table = {
  73         .nvmem_name             = "i2c-eeprom",
  74         .cells                  = foo_nvmem_cells,
  75         .ncells                 = ARRAY_SIZE(foo_nvmem_cells),
  76 };
  77
  78 nvmem_add_cell_table(&foo_nvmem_cell_table);
  79
  80 Additionally it is possible to create nvmem cell lookup entries and register
  81 them with the nvmem framework from machine code as shown in the example below:
  82
  83 static struct nvmem_cell_lookup foo_nvmem_lookup = {
  84         .nvmem_name             = "i2c-eeprom",
  85         .cell_name              = "macaddr",
  86         .dev_id                 = "foo_mac.0",
  87         .con_id                 = "mac-address",
  88 };
  89
  90 nvmem_add_cell_lookups(&foo_nvmem_lookup, 1);
  91
  92 NVMEM Consumers
  93 +++++++++++++++
  94
  95 NVMEM consumers are the entities which make use of the NVMEM provider to
  96 read from and to NVMEM.
  97
  98 3. NVMEM cell based consumer APIs
  99 =================================
 100
 101 NVMEM cells are the data entries/fields in the NVMEM.
 102 The NVMEM framework provides 3 APIs to read/write NVMEM cells.
 103
 104 struct nvmem_cell *nvmem_cell_get(struct device *dev, const char *name);
 105 struct nvmem_cell *devm_nvmem_cell_get(struct device *dev, const char *name);
 106
 107 void nvmem_cell_put(struct nvmem_cell *cell);
 108 void devm_nvmem_cell_put(struct device *dev, struct nvmem_cell *cell);
 109
 110 void *nvmem_cell_read(struct nvmem_cell *cell, ssize_t *len);
 111 int nvmem_cell_write(struct nvmem_cell *cell, void *buf, ssize_t len);
 112
 113 *nvmem_cell_get() apis will get a reference to nvmem cell for a given id,
 114 and nvmem_cell_read/write() can then read or write to the cell.
 115 Once the usage of the cell is finished the consumer should call *nvmem_cell_put()
 116 to free all the allocation memory for the cell.
 117
 118 4. Direct NVMEM device based consumer APIs
 119 ==========================================
 120
 121 In some instances it is necessary to directly read/write the NVMEM.
 122 To facilitate such consumers NVMEM framework provides below apis.
 123
 124 struct nvmem_device *nvmem_device_get(struct device *dev, const char *name);
 125 struct nvmem_device *devm_nvmem_device_get(struct device *dev,
 126                                            const char *name);
 127 void nvmem_device_put(struct nvmem_device *nvmem);
 128 int nvmem_device_read(struct nvmem_device *nvmem, unsigned int offset,
 129                       size_t bytes, void *buf);
 130 int nvmem_device_write(struct nvmem_device *nvmem, unsigned int offset,
 131                        size_t bytes, void *buf);
 132 int nvmem_device_cell_read(struct nvmem_device *nvmem,
 133                            struct nvmem_cell_info *info, void *buf);
 134 int nvmem_device_cell_write(struct nvmem_device *nvmem,
 135                             struct nvmem_cell_info *info, void *buf);
 136
 137 Before the consumers can read/write NVMEM directly, it should get hold
 138 of nvmem_controller from one of the *nvmem_device_get() api.
 139
 140 The difference between these apis and cell based apis is that these apis always
 141 take nvmem_device as parameter.
 142
 143 5. Releasing a reference to the NVMEM
 144 =====================================
 145
 146 When a consumer no longer needs the NVMEM, it has to release the reference
 147 to the NVMEM it has obtained using the APIs mentioned in the above section.
 148 The NVMEM framework provides 2 APIs to release a reference to the NVMEM.
 149
 150 void nvmem_cell_put(struct nvmem_cell *cell);
 151 void devm_nvmem_cell_put(struct device *dev, struct nvmem_cell *cell);
 152 void nvmem_device_put(struct nvmem_device *nvmem);
 153 void devm_nvmem_device_put(struct device *dev, struct nvmem_device *nvmem);
 154
 155 Both these APIs are used to release a reference to the NVMEM and
 156 devm_nvmem_cell_put and devm_nvmem_device_put destroys the devres associated
 157 with this NVMEM.
 158
 159 Userspace
 160 +++++++++
 161
 162 6. Userspace binary interface
 163 ==============================
 164
 165 Userspace can read/write the raw NVMEM file located at
 166 /sys/bus/nvmem/devices/*/nvmem
 167
 168 ex:
 169
 170 hexdump /sys/bus/nvmem/devices/qfprom0/nvmem
 171
 172 0000000 0000 0000 0000 0000 0000 0000 0000 0000
 173 *
 174 00000a0 db10 2240 0000 e000 0c00 0c00 0000 0c00
 175 0000000 0000 0000 0000 0000 0000 0000 0000 0000
 176 ...
 177 *
 178 0001000
 179
 180 7. DeviceTree Binding
 181 =====================
 182
 183 See Documentation/devicetree/bindings/nvmem/nvmem.txt