summaryrefslogtreecommitdiffstats
path: root/Documentation/nvmem
diff options
context:
space:
mode:
authorMauro Carvalho Chehab <mchehab+samsung@kernel.org>2019-06-27 15:39:22 -0300
committerMauro Carvalho Chehab <mchehab+samsung@kernel.org>2019-07-15 11:03:02 -0300
commitbaa293e9544bea71361950d071579f0e4d5713ed (patch)
tree29e0400c806016783a3fd7a380be40a201956653 /Documentation/nvmem
parent4f4cfa6c560c93ba180c30675cf845e1597de44c (diff)
downloadlinux-baa293e9544bea71361950d071579f0e4d5713ed.tar.bz2
docs: driver-api: add a series of orphaned documents
There are lots of documents under Documentation/*.txt and a few other orphan documents elsehwere that belong to the driver-API book. Move them to their right place. Reviewed-by: Cornelia Huck <cohuck@redhat.com> # vfio-related parts Acked-by: Logan Gunthorpe <logang@deltatee.com> # switchtec Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Diffstat (limited to 'Documentation/nvmem')
-rw-r--r--Documentation/nvmem/nvmem.rst189
1 files changed, 0 insertions, 189 deletions
diff --git a/Documentation/nvmem/nvmem.rst b/Documentation/nvmem/nvmem.rst
deleted file mode 100644
index 3866b6e066d5..000000000000
--- a/Documentation/nvmem/nvmem.rst
+++ /dev/null
@@ -1,189 +0,0 @@
-:orphan:
-
-===============
-NVMEM Subsystem
-===============
-
- Srinivas Kandagatla <srinivas.kandagatla@linaro.org>
-
-This document explains the NVMEM Framework along with the APIs provided,
-and how to use it.
-
-1. Introduction
-===============
-*NVMEM* is the abbreviation for Non Volatile Memory layer. It is used to
-retrieve configuration of SOC or Device specific data from non volatile
-memories like eeprom, efuses and so on.
-
-Before this framework existed, NVMEM drivers like eeprom were stored in
-drivers/misc, where they all had to duplicate pretty much the same code to
-register a sysfs file, allow in-kernel users to access the content of the
-devices they were driving, etc.
-
-This was also a problem as far as other in-kernel users were involved, since
-the solutions used were pretty much different from one driver to another, there
-was a rather big abstraction leak.
-
-This framework aims at solve these problems. It also introduces DT
-representation for consumer devices to go get the data they require (MAC
-Addresses, SoC/Revision ID, part numbers, and so on) from the NVMEMs. This
-framework is based on regmap, so that most of the abstraction available in
-regmap can be reused, across multiple types of buses.
-
-NVMEM Providers
-+++++++++++++++
-
-NVMEM provider refers to an entity that implements methods to initialize, read
-and write the non-volatile memory.
-
-2. Registering/Unregistering the NVMEM provider
-===============================================
-
-A NVMEM provider can register with NVMEM core by supplying relevant
-nvmem configuration to nvmem_register(), on success core would return a valid
-nvmem_device pointer.
-
-nvmem_unregister(nvmem) is used to unregister a previously registered provider.
-
-For example, a simple qfprom case::
-
- static struct nvmem_config econfig = {
- .name = "qfprom",
- .owner = THIS_MODULE,
- };
-
- static int qfprom_probe(struct platform_device *pdev)
- {
- ...
- econfig.dev = &pdev->dev;
- nvmem = nvmem_register(&econfig);
- ...
- }
-
-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::
-
- static struct nvmem_cell_info foo_nvmem_cells[] = {
- {
- .name = "macaddr",
- .offset = 0x7f00,
- .bytes = ETH_ALEN,
- }
- };
-
- static struct nvmem_cell_table foo_nvmem_cell_table = {
- .nvmem_name = "i2c-eeprom",
- .cells = foo_nvmem_cells,
- .ncells = ARRAY_SIZE(foo_nvmem_cells),
- };
-
- 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::
-
- static struct nvmem_cell_lookup foo_nvmem_lookup = {
- .nvmem_name = "i2c-eeprom",
- .cell_name = "macaddr",
- .dev_id = "foo_mac.0",
- .con_id = "mac-address",
- };
-
- nvmem_add_cell_lookups(&foo_nvmem_lookup, 1);
-
-NVMEM Consumers
-+++++++++++++++
-
-NVMEM consumers are the entities which make use of the NVMEM provider to
-read from and to NVMEM.
-
-3. NVMEM cell based consumer APIs
-=================================
-
-NVMEM cells are the data entries/fields in the NVMEM.
-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);
-
- void nvmem_cell_put(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);
- 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,
-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.
-
-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::
-
- struct nvmem_device *nvmem_device_get(struct device *dev, const char *name);
- struct nvmem_device *devm_nvmem_device_get(struct device *dev,
- const char *name);
- void nvmem_device_put(struct nvmem_device *nvmem);
- int nvmem_device_read(struct nvmem_device *nvmem, unsigned int offset,
- size_t bytes, void *buf);
- int nvmem_device_write(struct nvmem_device *nvmem, unsigned int offset,
- size_t bytes, void *buf);
- int nvmem_device_cell_read(struct nvmem_device *nvmem,
- struct nvmem_cell_info *info, void *buf);
- 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.
-
-The difference between these apis and cell based apis is that these apis always
-take nvmem_device as parameter.
-
-5. Releasing a reference to the NVMEM
-=====================================
-
-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::
-
- void nvmem_cell_put(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 devm_nvmem_device_put(struct device *dev, struct nvmem_device *nvmem);
-
-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
-with this NVMEM.
-
-Userspace
-+++++++++
-
-6. Userspace binary interface
-==============================
-
-Userspace can read/write the raw NVMEM file located at::
-
- /sys/bus/nvmem/devices/*/nvmem
-
-ex::
-
- hexdump /sys/bus/nvmem/devices/qfprom0/nvmem
-
- 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
-
-7. DeviceTree Binding
-=====================
-
-See Documentation/devicetree/bindings/nvmem/nvmem.txt