bd: Add get_erase_value function to the block device API

[geky]

This allows a user to determine the state of storage after an erase and take advantage of the NANDing nature of flash in the filesystem, NVStore, and FTL layers.

class BlockDevice {
    /** Get the value of storage when erased
     *
     *  If get_erase_value returns a non-negative byte value, the underlying
     *  storage will be set to that value when erased, and storage containing
     *  that value can be programmed without another erase.
     *
     *  @return         The value of storage when erased, or -1 if the value of
     *                  erased storage can't be relied on
     */
    virtual int get_erase_value() const;
}

should resolve #4023
cc @deepikabhavnani, @cmonr, @davidsaada

[deepikabhavnani]

Does -ve value indicate not supported by block device? Erase value or state can be either 0/1 is that correct? Can we mention what will be valid return values from this function?

[geky]

Good point, I'll add examples. I'm expecting 0x00, 0xff, any byte value between those, or negative for state between erase is undefined.

[davidsaada]

Two comments:

1. This is indeed a required functionality. I'd only pick a different name for the function. Looking at this name may lead one to think of another functionality - like the one discussed earlier with you, returning the blank value for this device (0xFF for flash, 0 for Heap etc.). get_erase_state or something like this should be more intuitive IMO.
2. Would it be safe to assume that the resolution of this API is in program units? If so, I'd add a word in the explanation, so that users would check the desired blocks more efficiently (as in check addresses per each program unit instead of each byte).

[deepikabhavnani]

Looking further in the implementation and based on @davidsaada queries, I have questions:

1. get_erase_value() can be called for each block? Shouldn't we pass block number as argument then?
   (Note: I thought it is related to underlying block device and will be called to know the behavior of device)
2. get_erase_value() API will be directly linked to erase, user calling erase function followed by get_erase_value will get the state of last erased block?

[geky]

This is indeed a required functionality. I'd only pick a different name for the function. Looking at this name may lead one to think of another functionality - like the one discussed earlier with you, returning the blank value for this device (0xFF for flash, 0 for Heap etc.). get_erase_state or something like this should be more intuitive IMO.

Uh, I think we might be on different pages. Definitely means the documentation should be improved. This was actually supposed to be the idea discussed earlier.

so:

SPIFBlockDevice::get_erase_value() -> 0xff
HeapBlockDevice::get_erase_value() -> 0x00
SDBlockDevice::get_erase_value() -> -1

Calling erase does not change the result of get_erase_value. Just like get_erase_size and friends.

---

It sounds like I used the word byte and state too much. How about this?

class BlockDevice {
    /** Get the value of storage when erased
     *
     *  If get_erase_value returns a non-negative byte value, the underlying
     *  storage will be set to that value when erased, and storage containing
     *  that value can be programmed without another erase.
     *
     *  @return         The value of storage when erased, or -1 if the value of
     *                  erased storage can't be relied on
     */
    virtual int get_erase_value() const;
}

[davidsaada]

Oh OK, then all clear now. No problem here.

[cmonr]

Marking as "needs work" for docs.

[deepikabhavnani]

👍

[cmonr]

@AnotherButler, could you take a look at this?

[cmonr]

/morph test

[geky]

@cmonr, sorry the documentation wasn't actually updated yet. Is updated now.

[AnotherButler]

Query: Should ExhaustibleBlockDevice, ObservingBlockDevice and ReadOnlyBlockDevice be listed in our API references on os.mbed.com/docs? They're not there now, but the others are.

[cmonr]

Query: Should ExhaustibleBlockDevice, ObservingBlockDevice and ReadOnlyBlockDevice be listed in our API references on os.mbed.com/docs? They're not there now, but the others are.

@AnotherButler, I think so, but that page would need to be updated a bit more than simply listing all supported block devices. Some block devices act as interfaces for specific hardware, whereas others serve as helper block devices. Some block devices have their own repos, with their own example code, whereas others exist within mbed-os.

I don't think it should be a part of this PR, but definitely think the page should be updated to list all supported block devices (with examples?).

[cmonr]

/morph build

[AnotherButler]

I guess what I'm asking is should they each get their own page the way HeapBlockDevice does: https://os.mbed.com/docs/v5.7/reference/heapblockdevice.html?

os.mbed.com/docs should only include code on master in mbed-os (perhaps with the exception of porting guide information, which we're in discussions about).

[cmonr]

@AnotherButler, I think for the block devices already a part of mbed-os, they should have a page of their own.

For the block devices that are not a part of mbed-os, I think they should also have their own docs page, but maybe in order to do that, they need to be merged into mbed-os first.

[mbed-ci]

Build : SUCCESS

Build number : 1005
Build artifacts/logs : http://mbed-os.s3-website-eu-west-1.amazonaws.com/?prefix=builds/5925/

Triggering tests

/morph test
/morph uvisor-test
/morph export-build

[mbed-ci]

Test : FAILURE

Build number : 813
Test logs :http://mbed-os-logs.s3-website-us-west-1.amazonaws.com/?prefix=logs/5925/813

[geky]

They are listed here:
https://os.mbed.com/docs/v5.7/reference/storage.html#utility-block-devices

But I agree with @cmonr, they should have individual pages.

[mbed-ci]

Exporter Build : SUCCESS

Build number : 696
Build artifacts/logs : http://mbed-os.s3-website-eu-west-1.amazonaws.com/?prefix=builds/exporter/5925/

[0xc0170]

/morph build

[mbed-ci]

Build : SUCCESS

Build number : 1008
Build artifacts/logs : http://mbed-os.s3-website-eu-west-1.amazonaws.com/?prefix=builds/5925/

Triggering tests

/morph test
/morph uvisor-test
/morph export-build

[mbed-ci]

Exporter Build : SUCCESS

Build number : 699
Build artifacts/logs : http://mbed-os.s3-website-eu-west-1.amazonaws.com/?prefix=builds/exporter/5925/

[mbed-ci]

Test : FAILURE

Build number : 819
Test logs :http://mbed-os-logs.s3-website-us-west-1.amazonaws.com/?prefix=logs/5925/819

[mbed-ci]

Test : SUCCESS

Build number : 823
Test logs :http://mbed-os-logs.s3-website-us-west-1.amazonaws.com/?prefix=logs/5925/823