lkml.org 
[lkml]   [2019]   [Apr]   [22]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    Patch in this message
    /
    From
    Subject[PATCH v2 53/79] docs: nvmem: convert docs to ReST and rename to *.rst
    Date
    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>
    ---
    Documentation/nvmem/{nvmem.txt => nvmem.rst} | 112 ++++++++++---------
    1 file changed, 59 insertions(+), 53 deletions(-)
    rename Documentation/nvmem/{nvmem.txt => nvmem.rst} (62%)

    diff --git a/Documentation/nvmem/nvmem.txt b/Documentation/nvmem/nvmem.rst
    similarity index 62%
    rename from Documentation/nvmem/nvmem.txt
    rename to Documentation/nvmem/nvmem.rst
    index fc2fe4b18655..3866b6e066d5 100644
    --- a/Documentation/nvmem/nvmem.txt
    +++ b/Documentation/nvmem/nvmem.rst
    @@ -1,5 +1,10 @@
    - NVMEM SUBSYSTEM
    - Srinivas Kandagatla <srinivas.kandagatla@linaro.org>
    +: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.
    @@ -40,54 +45,54 @@ 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 = {
    + static struct nvmem_config econfig = {
    .name = "qfprom",
    .owner = THIS_MODULE,
    -};
    + };

    -static int qfprom_probe(struct platform_device *pdev)
    -{
    + 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:
    +nvmem_cell_table struct::

    -static struct nvmem_cell_info foo_nvmem_cells[] = {
    + static struct nvmem_cell_info foo_nvmem_cells[] = {
    {
    .name = "macaddr",
    .offset = 0x7f00,
    .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",
    .cells = 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
    -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",
    .cell_name = "macaddr",
    .dev_id = "foo_mac.0",
    .con_id = "mac-address",
    -};
    + };

    -nvmem_add_cell_lookups(&foo_nvmem_lookup, 1);
    + nvmem_add_cell_lookups(&foo_nvmem_lookup, 1);

    NVMEM Consumers
    +++++++++++++++
    @@ -99,43 +104,43 @@ 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);
    + 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_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);
    + 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,
    + 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,
    + 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,
    + 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,
    + 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,
    + 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,12 +150,12 @@ 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);
    -void nvmem_device_put(struct nvmem_device *nvmem);
    -void devm_nvmem_device_put(struct device *dev, struct nvmem_device *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
    @@ -162,20 +167,21 @@ Userspace
    6. Userspace binary interface
    ==============================

    -Userspace can read/write the raw NVMEM file located at
    -/sys/bus/nvmem/devices/*/nvmem
    +Userspace can read/write the raw NVMEM file located at::

    -ex:
    + /sys/bus/nvmem/devices/*/nvmem

    -hexdump /sys/bus/nvmem/devices/qfprom0/nvmem
    +ex::

    -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
    + 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
    =====================
    --
    2.20.1
    \
     
     \ /
      Last update: 2019-04-22 15:32    [W:3.539 / U:0.128 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site