Commit a278295c authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab
Browse files

docs: nvmem: convert docs to ReST and rename to *.rst 



In order to be able to add it into a doc book, we need first
convert it to ReST.

The conversion is actually:
  - add blank lines and identation in order to identify paragraphs;
  - mark literal blocks;
  - adjust title markups.

While this is not part of any book, mark it as :orphan:, in order
to avoid build warnings.

Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+samsung@kernel.org>
parent 619ba451

Documentation/nvmem/nvmem.txt→Documentation/nvmem/nvmem.rst

+59 −53
Original line number Diff line number Diff line 
			    NVMEM SUBSYSTEM

:orphan:



===============

NVMEM Subsystem

===============



 Srinivas Kandagatla <srinivas.kandagatla@linaro.org>



This document explains the NVMEM Framework along with the APIs provided,
@@ -40,7 +45,7 @@ nvmem_device pointer. 


nvmem_unregister(nvmem) is used to unregister a previously registered provider.



For example, a simple qfprom case:

For example, a simple qfprom case::



  static struct nvmem_config econfig = {

	.name = "qfprom",
@@ -59,7 +64,7 @@ It is mandatory that the NVMEM provider has a regmap associated with its 
struct device. Failure to do would return error code from nvmem_register().



Users of board files can define and register nvmem cells using the

nvmem_cell_table struct:

nvmem_cell_table struct::



  static struct nvmem_cell_info foo_nvmem_cells[] = {

	{
@@ -78,7 +83,7 @@ static struct nvmem_cell_table foo_nvmem_cell_table = { 
  nvmem_add_cell_table(&foo_nvmem_cell_table);



Additionally it is possible to create nvmem cell lookup entries and register

them with the nvmem framework from machine code as shown in the example below:

them with the nvmem framework from machine code as shown in the example below::



  static struct nvmem_cell_lookup foo_nvmem_lookup = {

	.nvmem_name		= "i2c-eeprom",
@@ -99,7 +104,7 @@ read from and to NVMEM. 
=================================



NVMEM cells are the data entries/fields in the NVMEM.

The NVMEM framework provides 3 APIs to read/write NVMEM cells.

The NVMEM framework provides 3 APIs to read/write NVMEM cells::



  struct nvmem_cell *nvmem_cell_get(struct device *dev, const char *name);

  struct nvmem_cell *devm_nvmem_cell_get(struct device *dev, const char *name);
@@ -110,16 +115,16 @@ void devm_nvmem_cell_put(struct device *dev, struct nvmem_cell *cell); 
  void *nvmem_cell_read(struct nvmem_cell *cell, ssize_t *len);

  int nvmem_cell_write(struct nvmem_cell *cell, void *buf, ssize_t len);



*nvmem_cell_get() apis will get a reference to nvmem cell for a given id,

`*nvmem_cell_get()` apis will get a reference to nvmem cell for a given id,

and nvmem_cell_read/write() can then read or write to the cell.

Once the usage of the cell is finished the consumer should call *nvmem_cell_put()

to free all the allocation memory for the cell.

Once the usage of the cell is finished the consumer should call

`*nvmem_cell_put()` to free all the allocation memory for the cell.



4. Direct NVMEM device based consumer APIs

==========================================



In some instances it is necessary to directly read/write the NVMEM.

To facilitate such consumers NVMEM framework provides below apis.

To facilitate such consumers NVMEM framework provides below apis::



  struct nvmem_device *nvmem_device_get(struct device *dev, const char *name);

  struct nvmem_device *devm_nvmem_device_get(struct device *dev,
@@ -135,7 +140,7 @@ int nvmem_device_cell_write(struct nvmem_device *nvmem, 
			    struct nvmem_cell_info *info, void *buf);



Before the consumers can read/write NVMEM directly, it should get hold

of nvmem_controller from one of the *nvmem_device_get() api.

of nvmem_controller from one of the `*nvmem_device_get()` api.



The difference between these apis and cell based apis is that these apis always

take nvmem_device as parameter.
@@ -145,7 +150,7 @@ take nvmem_device as parameter. 


When a consumer no longer needs the NVMEM, it has to release the reference

to the NVMEM it has obtained using the APIs mentioned in the above section.

The NVMEM framework provides 2 APIs to release a reference to the NVMEM.

The NVMEM framework provides 2 APIs to release a reference to the NVMEM::



  void nvmem_cell_put(struct nvmem_cell *cell);

  void devm_nvmem_cell_put(struct device *dev, struct nvmem_cell *cell);
@@ -162,10 +167,11 @@ Userspace 
6. Userspace binary interface

==============================



Userspace can read/write the raw NVMEM file located at

Userspace can read/write the raw NVMEM file located at::



	/sys/bus/nvmem/devices/*/nvmem



ex:

ex::



  hexdump /sys/bus/nvmem/devices/qfprom0/nvmem