Flash IAP refers to program, not page

[jlangbridge]

Docs issue template

Page link

https://os.mbed.com/docs/mbed-os/v6.3/mbed-os-api-doxy/classmbed_1_1_flash_i_a_p.html

Expected to find...

size | Size to write in bytes, must be a multiple of page size

Found

size | Size to write in bytes, must be a multiple of program size

The program() function requires three parameters; parameter 2 talks about the address of the page to write to, parameter 3 talks about being a multiple of "program size", but should say page size?

[kjbracey]

They're synonyms here, but terminology seems inconsistent. Eg see "get_page_size()" -> "get the program page size"

Sector size = erase size/unit (can only erase whole sectors)
Page size = program size/unit (can only program whole pages)

I'm not sure the sector=erase and page=program terminology is industry universal, but it's what this API is using.

[0xc0170]

I'm not sure the sector=erase and page=program terminology is industry universal, but it's what this API is using.

program() comes from flash algo (what we use very often), defined by cmsis/keil. You program a page, and erase a sector.

The docs should be updated to:

     *  @param size   Size to write in bytes, must be a multiple of page size

As we have get_page_size()

@jlangbridge thanks for the report, would you be able to send a pull request fixing this in Mbed OS?

[jlangbridge]

I think there is a slight confusion here, maybe I didn't fill out the bug correctly. I agree with the programming a page and erasing a sector. What I'm referring to is one single function, the program() function. Parameter 3, size, states: "Size to write in bytes, must be a multiple of program size". I'm pretty sure that this instance should be "page size" (since we are writing a certain amount of pages, so we should be writing 4096 bytes, 8192 and so on), or at the very least, "programmable size"

@0xc0170 sure I can do that! I'll try and get it done this evening.

[ciarmcom]

Thank you for raising this detailed GitHub issue. I am now notifying our internal issue triagers.
Internal Jira reference: https://jira.arm.com/browse/IOTOSM-2443