jlaitine commented on a change in pull request #3834:
URL: https://github.com/apache/incubator-nuttx/pull/3834#discussion_r645304976
##########
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.
+ *
+ * Input Parameters:
+ * index - ordinal number of the set of erasable units of memory
+ *
+ * Returned Value:
+ * Erase size for erasable unit of memory, or negative value on error.
+ *
+ * The following errors are reported (errno is not set!):
+ *
+ * -EFAULT: On invalid unit of memory
*
****************************************************************************/
-size_t up_progmem_erasesize(size_t block);
+ssize_t up_progmem_erasesize(size_t index);
/****************************************************************************
- * Name: up_progmem_getpage
+ * Name: up_progmem_getindex
*
* Description:
- * Address to read/write page conversion
+ * Get the index of memory, given a FLASH memory address
*
* Input Parameters:
* addr - Address with or without flash offset
- * (absolute or aligned to page0)
+ * (absolute or aligned to the zeroeth unit of memory)
*
* Returned Value:
- * Page or negative value on error.
+ * Index or negative value on error.
* The following errors are reported (errno is not set!):
*
* -EFAULT: On invalid address
*
****************************************************************************/
-ssize_t up_progmem_getpage(size_t addr);
+ssize_t up_progmem_getindex(size_t addr);
Review comment:
In the original naming, the word "block" referred to smallest erasable
unit of flash, and "page" referred to the smallest writable unit. This
separation in naming should be kept consistent; On this line the function name
uses the word "index" referring to original "block" (smallest erasable unit).
This should really return the "write granule" and not the eraseblock!
So the function name here would be wrong.
##########
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.
+ *
+ * Input Parameters:
+ * index - ordinal number of the set of erasable units of memory
+ *
+ * Returned Value:
+ * Erase size for erasable unit of memory, or negative value on error.
+ *
+ * The following errors are reported (errno is not set!):
+ *
+ * -EFAULT: On invalid unit of memory
*
****************************************************************************/
-size_t up_progmem_erasesize(size_t block);
+ssize_t up_progmem_erasesize(size_t index);
/****************************************************************************
- * Name: up_progmem_getpage
+ * Name: up_progmem_getindex
*
* Description:
- * Address to read/write page conversion
+ * Get the index of memory, given a FLASH memory address
*
* Input Parameters:
* addr - Address with or without flash offset
- * (absolute or aligned to page0)
+ * (absolute or aligned to the zeroeth unit of memory)
*
* Returned Value:
- * Page or negative value on error.
+ * Index or negative value on error.
* The following errors are reported (errno is not set!):
*
* -EFAULT: On invalid address
*
****************************************************************************/
-ssize_t up_progmem_getpage(size_t addr);
+ssize_t up_progmem_getindex(size_t addr);
/****************************************************************************
* Name: up_progmem_getaddress
*
* Description:
- * Read/write page to address conversion
+ * Get the base address of a unit of memory, given an index
*
* Input Parameters:
- * page - page index
+ * index - ordinal number of the set of erasable units of memory
*
* Returned Value:
- * Base address of given page, SIZE_MAX if page index is not valid.
+ * Base address of given unit of memory, SIZE_MAX if index is not valid.
*
****************************************************************************/
-size_t up_progmem_getaddress(size_t page);
Review comment:
Same comment as above; word "index" is confusing, it is not obvious
whether this returns the address of the smalles erasable unit, or address of
the smalles writable unit
##########
File path: include/nuttx/progmem.h
##########
@@ -147,48 +178,50 @@ size_t up_progmem_getaddress(size_t page);
*
****************************************************************************/
-ssize_t up_progmem_eraseblock(size_t block);
+ssize_t up_progmem_erase(size_t index);
/****************************************************************************
- * Name: up_progmem_ispageerased
+ * Name: up_progmem_iserased
*
* Description:
- * Checks whether erase page is erased
+ * Checks whether a specified unit of memory is erased
*
* Input Parameters:
- * page - The page index to be checked.
+ * index - ordinal number of the set of erasable units of memory
*
* Returned Value:
* Returns number of bytes NOT erased or negative value on error. If it
- * returns zero then complete page is erased.
+ * returns zero then complete unit of memory is erased.
*
* The following errors are reported:
- * -EFAULT: On invalid page
+ * -EFAULT: On invalid index
*
****************************************************************************/
-ssize_t up_progmem_ispageerased(size_t page);
+ssize_t up_progmem_iserased(size_t index);
Review comment:
Same comment as above
--
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]
