Re: [PATCH v3 7/7] misc: update API documentation for bit field support in NVMEM

[Heinrich Schuchardt]

Am 30. März 2026 19:14:19 MESZ schrieb Aswin Murugan <aswin.murugan at oss.qualcomm.com>:
>Update the nvmem_cell_read() and nvmem_cell_write() documentation to
>describe the new bit field operation mode.
>
>The documentation now clearly explains:
>
>For bit field mode (nbits > 0):

Thank you for updating this documentation. 

Please refer to @cell->nbits in the function documentation and also mention @cell->offset.

Best regards

Heinrich

>- Read: extracts the bit field from raw hardware bytes
>- Write: performs read-modify-write to preserve other bits
>- Requirements: buffer size must be sizeof(u32), cell size <= 4 bytes
>
>For non-bit-field mode (nbits == 0):
>- Read/Write: direct byte-level access
>- Requirements: buffer size must equal the cell size
>
>This helps developers understand when to use each mode and the
>associated buffer size requirements.
>
>Signed-off-by: Aswin Murugan <aswin.murugan at oss.qualcomm.com>
>---
> include/nvmem.h | 24 ++++++++++++++++++++++--
> 1 file changed, 22 insertions(+), 2 deletions(-)
>
>diff --git a/include/nvmem.h b/include/nvmem.h
>index dd82122f16f..af1d2594bd6 100644
>--- a/include/nvmem.h
>+++ b/include/nvmem.h
>@@ -47,9 +47,19 @@ struct udevice;
>  * @buf: The buffer to read into
>  * @size: The size of @buf
>  *
>+ * For cells with bit fields (nbits > 0), this function:
>+ * - Reads the raw bytes from hardware
>+ * - Extracts the bit field using bit_offset and nbits
>+ * - Returns the extracted value in @buf
>+ * - Requires @size == sizeof(u32) and @cell->size <= 4
>+ *
>+ * For cells without bit fields (nbits == 0):
>+ * - Reads raw bytes directly
>+ * - Requires @size == @cell->size
>+ *
>  * Return:
>  * * 0 on success
>- * * -EINVAL if @buf is not the same size as @cell.
>+ * * -EINVAL if @size doesn't match requirements
>  * * -ENOSYS if CONFIG_NVMEM is disabled
>  * * A negative error if there was a problem reading the underlying storage
>  */
>@@ -61,9 +71,19 @@ int nvmem_cell_read(struct nvmem_cell *cell, void *buf, size_t size);
>  * @buf: The buffer to write from
>  * @size: The size of @buf
>  *
>+ * For cells with bit fields (nbits > 0), this function:
>+ * - Performs Read-Modify-Write to preserve other bits
>+ * - Masks and shifts the value to the correct bit position
>+ * - Merges with existing bits outside the field
>+ * - Requires @size == sizeof(u32) and @cell->size <= 4
>+ *
>+ * For cells without bit fields (nbits == 0):
>+ * - Writes raw bytes directly
>+ * - Requires @size == @cell->size
>+ *
>  * Return:
>  * * 0 on success
>- * * -EINVAL if @buf is not the same size as @cell
>+ * * -EINVAL if @size doesn't match requirements
>  * * -ENOSYS if @cell is read-only, or if CONFIG_NVMEM is disabled
>  * * A negative error if there was a problem writing the underlying storage
>  */