Purpose of aSwapIndex for flash platform functions

[atar13]

Hello!

I am porting OpenThread to an embedded OS and am in the midst of porting flash functionality defined in this flash.h.

I am struggling to figure out what the aSwapIndex parameter means for several of the flash functions. Here is the signature of one of them:

/**
 * Reads @p aSize bytes into @p aData.
 *
 * @param[in]  aInstance   The OpenThread instance structure.
 * @param[in]  aSwapIndex  A value in [0, 1] that indicates the swap space.
 * @param[in]  aOffset     A byte offset within the swap space.
 * @param[out] aData       A pointer to the data buffer for reading.
 * @param[in]  aSize       Number of bytes to read.
 *
 */
void otPlatFlashRead(otInstance *aInstance, uint8_t aSwapIndex, uint32_t aOffset, void *aData, uint32_t aSize);

I have already tried looking around came across this PR. As I understand it, the swap is used as a buffer for writing settings. However, I was confused when I came across a flash implementation that just stored swap data in another region of flash. I don't understand why you would buffer to the same storage medium. Originally I thought it would make sense to store swap in RAM, however the PR I linked advises against that to avoid loss of data during power outage.

Could anyone explain what aSwapIndex is intended for and how I should implement its functionality?

Pinging @jwhui since they are the ones who committed this file (b3d05af).

Thank you!

[jwhui]

Flash storage typically performs erase operations on units of pages. To support atomic updates to settings in non-volatiles storage with flash, we switch between different swap spaces on flash by writing new data to a different page and then updating the pointer to the latest page. The swap index indicates which swap space to use.