mirror of
https://github.com/zephyrproject-rtos/zephyr
synced 2025-09-17 07:02:54 +00:00
b1e45b413e
Zephyr supports fatfs, nffs and fcb as storage layer. fatfs and nffs are less suited for application in memory restricted IC's. fcb has a smaller footprint but has a complex api. The proposed module is a module with a even smaller footprint compared to fcb and a simple interface for reading and writing entries. The module provides wear levelling of flash. This allows the module to be used not only to store configuration settings but to store device state (e.g. state of a light switch over reboots) of a zephyr device. Fixes buffer overflow by introducing maximum read length in nvs_read() and nvs_read_hist(). Fixes nvs_write() not to reflash the same data. Allows the user to do call nvs_write() for all defined entries without worries about flash wear. Fixes garbage collection error where wrong data could be copied. Add nvs_delete() to allow deleting a stored entry. A deleted entry will not be copied to a new flash sector Include flash wear information in the README.md documentation 0/25 Update module after reviewers remarks, added documentation to nvs.h, removed README.md by nvs.rst in doc/subsystems folder 04/26 Update module after reviewers remarks, updated nvs.rst, added more documentation to samples/subsys/nvs/src/main.c, updated doxygen info in nvs.h (hope this time it works). 04/26 Update subsystems.rst to include nvs.restart 04/27 Updated nvs.c and nvs.h to avoid a possible flash deletion loop when the file system is full. 04/29 Updated nvs_write to detect and ignore deletes of non-existing items 05/06 Update NVS module to return standard error codes, removed low level API, added configuration options. NVS now uses the board dts to determine the flash storage location (FLASH_AREA_STORAGE_OFFSET). 05/06 Update nvs.rst. Updated intendation and added intermediate variables in nvs.c to make the code easier to read. 05/06 Update nvs.rst. 05/07 Update nvs.rst 05/08 Changed the API to a more standard file system API. 05/08 Removed cnt_max from nvs_read() as it is not used. 05/08 Removed #ifdef(CONFIG_NVS_LOG) from nvs_priv.h, now the module can be build with debugging off. 05/09 Removed configuration options for SECTOR_SIZE, SECTOR_COUNT and MAX_ELEM_SIZE. It is now easy to support multiple NVS filesystems on one or multiple devices. Changed logging to support newlib systems. Thanks to Olivier Martin for reporting and proposed changes. Signed-off-by: Laczen JMS <laczenjms@gmail.com> |
||
|---|---|---|
| .. | ||
| api | ||
| application | ||
| contribute | ||
| crypto | ||
| devices | ||
| extensions | ||
| getting_started | ||
| introduction | ||
| kernel | ||
| porting | ||
| reference/kconfig | ||
| scripts | ||
| security | ||
| static | ||
| subsystems | ||
| templates | ||
| themes/zephyr | ||
| tools | ||
| 404.rst | ||
| conf.py | ||
| copyright.rst | ||
| glossary.rst | ||
| index.rst | ||
| LICENSING.rst | ||
| Makefile | ||
| README.rst | ||
| release-notes-1.5.rst | ||
| release-notes-1.6.rst | ||
| release-notes-1.7.rst | ||
| release-notes-1.8.rst | ||
| release-notes-1.9.rst | ||
| release-notes-1.10.rst | ||
| release-notes-1.11.rst | ||
| release-notes-1.12.rst | ||
| release-notes.rst | ||
| substitutions.txt | ||
| Zephyr-Kite-in-tree.png | ||
| zephyr.doxyfile | ||
.. _zephyr_doc: Zephyr documentation Generation ############################### These instructions will walk you through generating the Zephyr Project's documentation on your local system using the same documentation sources as we use to create the online documentation found at http://docs.zephyrproject.org Documentation overview ********************** Zephyr Project content is written using the reStructuredText markup language (.rst file extension) with Sphinx extensions, and processed using Sphinx to create a formatted stand-alone website. Developers can view this content either in its raw form as .rst markup files, or you can generate the HTML content and view it with a web browser directly on your workstation. This same .rst content is also fed into the Zephyr Project's public website documentation area (with a different theme applied). You can read details about `reStructuredText`_, and `Sphinx`_ from their respective websites. The project's documentation contains the following items: * ReStructuredText source files used to generate documentation found at the http://docs.zephyrproject.org website. Most of the reStructuredText sources are found in the ``/doc`` directory, but others are stored within the code source tree near their specific component (such as ``/samples`` and ``/boards``) * Doxygen-generated material used to create all API-specific documents also found at http://docs.zephyrproject.org * Script-generated material for kernel configuration options based on Kconfig files found in the source code tree The reStructuredText files are processed by the Sphinx documentation system, and make use of the breathe extension for including the doxygen-generated API material. Additional tools are required to generate the documentation locally, as described in the following sections. Installing the documentation processors *************************************** Our documentation processing has been tested to run with: * Doxygen version 1.8.13 * Sphinx version 1.6.7 * Breathe version 4.7.3 * docutils version 0.14 * sphinx_rtd_theme version 0.2.4 Begin by cloning a copy of the git repository for the Zephyr project and setting up your development environment as described in :ref:`getting_started` or specifically for Ubuntu in :ref:`installation_linux`. Other than ``doxygen``, the documentation tools should be installed using ``pip3`` (as documented in the development environment set up instructions). The documentation generation tools are included in the set of tools expected for the Zephyr build environment and so are included in ``requirements.txt`` Documentation presentation theme ******************************** Sphinx supports easy customization of the generated documentation appearance through the use of themes. Replace the theme files and do another ``make htmldocs`` and the output layout and style is changed. The ``read-the-docs`` theme is installed as part of the ``requirements.txt`` list above, and will be used if it's available, for local doc generation. Running the documentation processors ************************************ The ``/doc`` directory in your cloned copy of the Zephyr project git repo has all the .rst source files, extra tools, and Makefile for generating a local copy of the Zephyr project's technical documentation. Assuming the local Zephyr project copy is ``~/zephyr``, here are the commands to generate the html content locally: .. code-block:: bash $ cd ~/zephyr $ source zephyr-env.sh $ make htmldocs Depending on your development system, it will take about 15 minutes to collect and generate the HTML content. When done, you can view the HTML output with your browser started at ``~/zephyr/doc/_build/html/index.html`` Filtering expected warnings *************************** Alas, there are some known issues with the doxygen/Sphinx/Breathe processing that generates warnings for some constructs, in particular around unnamed structures in nested unions or structs. While these issues are being considered for fixing in Sphinx/Breathe, we've added a post-processing filter on the output of the documentation build process to check for "expected" messages from the generation process output. The output from the Sphinx build is processed by the python script ``scripts/filter-known-issues.py`` together with a set of filter configuration files in the ``.known-issues/doc`` folder. (This filtering is done as part of the ``doc/Makefile``.) If you're contributing components included in the Zephyr API documentation and run across these warnings, you can include filtering them out as "expected" warnings by adding a conf file to the ``.known-issues/doc`` folder, following the example of other conf files found there. .. _reStructuredText: http://sphinx-doc.org/rest.html .. _Sphinx: http://sphinx-doc.org/