openkylin
/
linux
mirror of https://gitee.com/openkylin/linux.git
9
0
Fork 0
Code Issues Projects Releases Wiki Activity

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: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
This commit is contained in:
Mauro Carvalho Chehab 2019-04-15 19:25:27 -03:00
parent 619ba45167
commit a278295ccc
1 changed files with 59 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

112
Documentation/nvmem/nvmem.txt → Documentation/nvmem/nvmem.rst
View File

@ -1,5 +1,10 @@
NVMEM SUBSYSTEM :orphan:
Srinivas Kandagatla <srinivas.kandagatla@linaro.org>
===============
NVMEM Subsystem
===============
Srinivas Kandagatla <srinivas.kandagatla@linaro.org>
This document explains the NVMEM Framework along with the APIs provided, This document explains the NVMEM Framework along with the APIs provided,
and how to use it. and how to use it.
@ -40,54 +45,54 @@ nvmem_device pointer.
nvmem_unregister(nvmem) is used to unregister a previously registered provider. 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 = { static struct nvmem_config econfig = {
.name = "qfprom", .name = "qfprom",
.owner = THIS_MODULE, .owner = THIS_MODULE,
}; };
static int qfprom_probe(struct platform_device *pdev) static int qfprom_probe(struct platform_device *pdev)
{ {
... ...
econfig.dev = &pdev->dev; econfig.dev = &pdev->dev;
nvmem = nvmem_register(&econfig); nvmem = nvmem_register(&econfig);
... ...
} }
It is mandatory that the NVMEM provider has a regmap associated with its 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(). struct device. Failure to do would return error code from nvmem_register().
Users of board files can define and register nvmem cells using the 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[] = { static struct nvmem_cell_info foo_nvmem_cells[] = {
{ {
.name = "macaddr", .name = "macaddr",
.offset = 0x7f00, .offset = 0x7f00,
.bytes = ETH_ALEN, .bytes = ETH_ALEN,
} }
}; };
static struct nvmem_cell_table foo_nvmem_cell_table = { static struct nvmem_cell_table foo_nvmem_cell_table = {
.nvmem_name = "i2c-eeprom", .nvmem_name = "i2c-eeprom",
.cells = foo_nvmem_cells, .cells = foo_nvmem_cells,
.ncells = ARRAY_SIZE(foo_nvmem_cells), .ncells = ARRAY_SIZE(foo_nvmem_cells),
}; };
nvmem_add_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 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 = { static struct nvmem_cell_lookup foo_nvmem_lookup = {
.nvmem_name = "i2c-eeprom", .nvmem_name = "i2c-eeprom",
.cell_name = "macaddr", .cell_name = "macaddr",
.dev_id = "foo_mac.0", .dev_id = "foo_mac.0",
.con_id = "mac-address", .con_id = "mac-address",
}; };
nvmem_add_cell_lookups(&foo_nvmem_lookup, 1); nvmem_add_cell_lookups(&foo_nvmem_lookup, 1);
NVMEM Consumers NVMEM Consumers
+++++++++++++++ +++++++++++++++
@ -99,43 +104,43 @@ read from and to NVMEM.
================================= =================================
NVMEM cells are the data entries/fields in the 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 *nvmem_cell_get(struct device *dev, const char *name);
struct nvmem_cell *devm_nvmem_cell_get(struct device *dev, const char *name); struct nvmem_cell *devm_nvmem_cell_get(struct device *dev, const char *name);
void nvmem_cell_put(struct nvmem_cell *cell); void nvmem_cell_put(struct nvmem_cell *cell);
void devm_nvmem_cell_put(struct device *dev, struct nvmem_cell *cell); void devm_nvmem_cell_put(struct device *dev, struct nvmem_cell *cell);
void *nvmem_cell_read(struct nvmem_cell *cell, ssize_t *len); void *nvmem_cell_read(struct nvmem_cell *cell, ssize_t *len);
int nvmem_cell_write(struct nvmem_cell *cell, void *buf, 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. 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() Once the usage of the cell is finished the consumer should call
to free all the allocation memory for the cell. `*nvmem_cell_put()` to free all the allocation memory for the cell.
4. Direct NVMEM device based consumer APIs 4. Direct NVMEM device based consumer APIs
========================================== ==========================================
In some instances it is necessary to directly read/write the NVMEM. 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 *nvmem_device_get(struct device *dev, const char *name);
struct nvmem_device *devm_nvmem_device_get(struct device *dev, struct nvmem_device *devm_nvmem_device_get(struct device *dev,
const char *name); const char *name);
void nvmem_device_put(struct nvmem_device *nvmem); void nvmem_device_put(struct nvmem_device *nvmem);
int nvmem_device_read(struct nvmem_device *nvmem, unsigned int offset, int nvmem_device_read(struct nvmem_device *nvmem, unsigned int offset,
size_t bytes, void *buf); size_t bytes, void *buf);
int nvmem_device_write(struct nvmem_device *nvmem, unsigned int offset, int nvmem_device_write(struct nvmem_device *nvmem, unsigned int offset,
size_t bytes, void *buf); size_t bytes, void *buf);
int nvmem_device_cell_read(struct nvmem_device *nvmem, int nvmem_device_cell_read(struct nvmem_device *nvmem,
struct nvmem_cell_info *info, void *buf); struct nvmem_cell_info *info, void *buf);
int nvmem_device_cell_write(struct nvmem_device *nvmem, int nvmem_device_cell_write(struct nvmem_device *nvmem,
struct nvmem_cell_info *info, void *buf); struct nvmem_cell_info *info, void *buf);
Before the consumers can read/write NVMEM directly, it should get hold 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 The difference between these apis and cell based apis is that these apis always
take nvmem_device as parameter. take nvmem_device as parameter.
@ -145,12 +150,12 @@ take nvmem_device as parameter.
When a consumer no longer needs the NVMEM, it has to release the reference 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. 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 nvmem_cell_put(struct nvmem_cell *cell);
void devm_nvmem_cell_put(struct device *dev, struct nvmem_cell *cell); void devm_nvmem_cell_put(struct device *dev, struct nvmem_cell *cell);
void nvmem_device_put(struct nvmem_device *nvmem); void nvmem_device_put(struct nvmem_device *nvmem);
void devm_nvmem_device_put(struct device *dev, struct nvmem_device *nvmem); void devm_nvmem_device_put(struct device *dev, struct nvmem_device *nvmem);
Both these APIs are used to release a reference to the NVMEM and Both these APIs are used to release a reference to the NVMEM and
devm_nvmem_cell_put and devm_nvmem_device_put destroys the devres associated devm_nvmem_cell_put and devm_nvmem_device_put destroys the devres associated
@ -162,20 +167,21 @@ Userspace
6. Userspace binary interface 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: /sys/bus/nvmem/devices/*/nvmem
hexdump /sys/bus/nvmem/devices/qfprom0/nvmem ex::
0000000 0000 0000 0000 0000 0000 0000 0000 0000 hexdump /sys/bus/nvmem/devices/qfprom0/nvmem
*
00000a0 db10 2240 0000 e000 0c00 0c00 0000 0c00 0000000 0000 0000 0000 0000 0000 0000 0000 0000
0000000 0000 0000 0000 0000 0000 0000 0000 0000 *
... 00000a0 db10 2240 0000 e000 0c00 0c00 0000 0c00
* 0000000 0000 0000 0000 0000 0000 0000 0000 0000
0001000 ...
*
0001000
7. DeviceTree Binding 7. DeviceTree Binding
===================== =====================