Docs: new documentation and warnings cleanup
This change set
- adds a high-level description of application startup flow. Some parts are missing, but hopefully we can use this description as a base to expand on.
- adds a few notes about memory regions and their use in ESP-IDF.
- add SPI flash and partition APIs page
- fixes all Doxygen warnings in header files
- enables build failures on new Doxygen warnings
See merge request !201
New makefile component_wrapper.mk allows some variables to be set
before component.mk is evaluated. This properly fixes problems with
sdkconfig being hard to access in all phases of the build.
Including component_common.mk is no longer necessary and will print a
deprecation warning for components which use it.
When read caching was added, Page::findItem started modifying itemIndex reference argument even if item wasn't found.
Incidentally, Storage::findItem reused itemIndex when starting search at next page.
So,
- if the first page had a cached index (findItem was called for that page), and it pointed to a non-zero index,
- first page has a few empty items at the end (but is marked full),
- next search looked up the item on the second page,
- index of the item on the second page was less than the cached index on the first page,
then the search would fail because cached starting index was reused.
This change fixes both sides of the problem:
- Page::findItem shouldn't modify itemIndex argument if item is not found
- Storage::findItem should not reuse itemIndex between pages
Two tests have been added.
Fix spi_flash_write regression and nvs error recovery
In the previous set of changes related to spi_flash, new alignment checks were added. One of these checks, word alignment of `src` buffer in `nvs_flas_write`, was unnecessary. ROM `SPIWrite` function can handle unaligned source buffers.
This change caused an error to be returned to nvs for some legitimate write operations. Due to a bug in nvs, further write operations were possible, while the internal state of `Page` instance was broken. In WiFi functional tests, this inflicted havoc on the nvs partition, creating multiple duplicate items in the affected page. Because multiple duplicate items per page were never supposed to be handled during page load, duplicates were not removed. Thankfully this caused an assert at a later point in the loading process, otherwise this bug would be very difficult to detect.
This change set fixes the original spi_flash regression, handling of `INVALID` state of `nvs::Page`, and handling of duplicate items.
See merge request !161
Due to previous flash write bug it was possible to create multiple duplicate entries in a single page.
Recovery logic detected that case and bailed out with an assert.
This change adds graceful recovery from this condition.
Tests included.
Currently a restart is required to recover a page from invalid state.
The long-term solution is to detect such a condition and recover automatically (without a restart). This will be implemented in a separate change set.
Previously the test bench would check failure recovery by introducing error after each write operation.
This makes checks a bit more extensive (and much longer) by failing after every word written. Surprisingly, this change didn't expose any bugs.
nvs: fix memory leaks in HashList and nvs_close
Fixes TW8162.
Associated test case is run under Instruments on macOS, until I set up valgrind to test this automatically on Linux.
See merge request !150
spi_flash_read and spi_flash_write currently have a limitation that source and destination must be word-aligned.
This can be fixed by adding code paths for various unaligned scenarios, but function signatures also need to be adjusted.
As a first step (since we are pre-1.0 and can still change function signatures) alignment checks are added, and pointer types are relaxed to uint8_t.
Later we will add handling of unaligned operations.
This change also introduces spi_flash_erase_range and spi_flash_get_chip_size functions.
We probably need something like spi_flash_chip_size_detect which will detect actual chip size.
This is to allow single application binary to be used on a variety of boards and modules.
Introduces new internal function, Page::alterEntryRangeState, which gathers changes to multiple elements of entry state table into a single write, provided that these changes fall into a single word. This allows changing state of up to 16 entries in a single write.
Also adds new function, writeEntryData, which writes the whole payload of SZ and BLOB type entries in one go, instead of splitting it into multiple 32-byte writes.
This reduces number of writes required for SZ and BLOB entries.
Fixes problems with Eclipse trying to build in directories it shouldn't.
This is a breaking change for existing repositories, they need to rename
any component Makefiles to component.mk and rename their references to
$(IDF_PATH)/make/component.mk to $(IDF_PATH)/make/component_common.mk
This commit fixes several issues with state handling in nvs::Page. It also adds extra consistency checks in nvs::PageManger initialization.
These changes were verified with a new long-running test ("test recovery from sudden poweroff"). This test works by repeatedly performing same pseudorandom sequence of calls to nvs_ APIs. Each time it repeats the sequence, it introduces a failure into one of flash operations (write or erase). So if one iteration of this test needs, say, 25000 flash operations, then this test will run 25000 iterations, each time introducing the failure point at different location.
