Flash IAP refers to program, not page
jlangbridge opened this issue · 4 comments
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?
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.
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?
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.
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