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

[Aswin Murugan]

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):
- 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
  */
-- 
2.34.1