gustavonihei commented on a change in pull request #3834:
URL: https://github.com/apache/incubator-nuttx/pull/3834#discussion_r646692432
##########
File path: include/nuttx/progmem.h
##########
@@ -49,96 +49,127 @@ extern "C"
* Public Functions Definitions
****************************************************************************/
+/* NOTE: Since vendors use the terms page, block, and sector interchangably,
+ * it causes confusion and therefore a neutral term is used. We use the term
+ * "index" to refer to the ordinal number of erasable units of memory.
+ */
+
/****************************************************************************
- * Name: up_progmem_neraseblocks
+ * Name: up_progmem_maxeraseindex
*
* Description:
- * Return number of erase blocks
+ * Return the total number of erasable units of memory.
+ *
+ * Returned Value:
+ * Returns number of erasable units of memory, or 0 if there are no units
+ * available that can be programmed.
*
****************************************************************************/
-size_t up_progmem_neraseblocks(void);
+size_t up_progmem_maxeraseindex(void);
/****************************************************************************
* Name: up_progmem_isuniform
*
* Description:
- * Is program memory uniform or erase page and read/write page size differs?
+ * Are all erasable units of memory the same size?
+ *
+ * Returned Value:
+ * true if all erasable units are the same size, false if they vary in size
*
****************************************************************************/
bool up_progmem_isuniform(void);
/****************************************************************************
- * Name: up_progmem_pagesize
+ * Name: up_progmem_writegranularity
*
* Description:
- * Return read/write page size
+ * Return the number of bytes of the smallest allowable write operation.
+ * All writes MUST be a multiple of the granularity. Some FLASH memories
+ * require write operations in multiples of 8-bit, 16-bit, 32-bit, 128-bit,
+ * 256-bit, etc. The caller must ensure the size of the data passed into
+ * up_progmem_write is an even multiple of the writegranularity. Padding
+ * may be required.
+ *
+ * Returned Value:
+ * Required granularity of a write operation for the FLASH memory.
*
****************************************************************************/
-size_t up_progmem_pagesize(size_t page);
+size_t up_progmem_writegranularity(void);
/****************************************************************************
* Name: up_progmem_erasesize
*
* Description:
- * Return erase block size. Must be a multiple of the read/write page size.
+ * Return the erase size for a specified index. Will always be a multiple
+ * of the write granularity.
Review comment:
```suggestion
* Return the erase size for a specified index. Will always be a multiple
* of the write granularity indicated by up_progmem_writegranularity.
```
It may sound repetitive, but it is helpful for making the link between them
explicit.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
[email protected]
