[PATCH v4 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>
---
Changes in v4:
1. Added explicit documentation for all `@cell` parameters:
   - `@cell->offset` - Byte offset within NVMEM device
   - `@cell->size` - Size of cell in bytes
   - `@cell->nbits` - Number of bits (0 = byte-level mode)
   - `@cell->bit_offset` - Starting bit position
---
 include/nvmem.h | 36 ++++++++++++++++++++++++++++++++----
 1 file changed, 32 insertions(+), 4 deletions(-)

diff --git a/include/nvmem.h b/include/nvmem.h
index dd82122f16f..c3d845c3a7e 100644
--- a/include/nvmem.h
+++ b/include/nvmem.h
@@ -43,13 +43,27 @@ struct udevice;
 
 /**
  * nvmem_cell_read() - Read the value of an nvmem cell
- * @cell: The nvmem cell to read
+ * @cell: The nvmem cell to read, containing:
+ *        - @cell->offset: Byte offset within the NVMEM device
+ *        - @cell->size: Size of the cell in bytes
+ *        - @cell->nbits: Number of bits to extract (0 = read entire cell)
+ *        - @cell->bit_offset: Starting bit position for extraction
  * @buf: The buffer to read into
  * @size: The size of @buf
  *
+ * For cells with bit fields (@cell->nbits > 0), this function:
+ * - Reads the raw bytes from @cell->offset in hardware
+ * - Extracts the bit field using @cell->bit_offset and @cell->nbits
+ * - Returns the extracted value in @buf
+ * - Requires @size == sizeof(u32) and @cell->size <= sizeof(u32)
+ *
+ * For cells without bit fields (@cell->nbits == 0):
+ * - Reads raw bytes directly from @cell->offset
+ * - 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
  */
@@ -57,13 +71,27 @@ int nvmem_cell_read(struct nvmem_cell *cell, void *buf, size_t size);
 
 /**
  * nvmem_cell_write() - Write a value to an nvmem cell
- * @cell: The nvmem cell to write
+ * @cell: The nvmem cell to write, containing:
+ *        - @cell->offset: Byte offset within the NVMEM device
+ *        - @cell->size: Size of the cell in bytes
+ *        - @cell->nbits: Number of bits to write (0 = write entire cell)
+ *        - @cell->bit_offset: Starting bit position for insertion
  * @buf: The buffer to write from
  * @size: The size of @buf
  *
+ * For cells with bit fields (@cell->nbits > 0), this function:
+ * - Performs Read-Modify-Write to preserve other bits at @cell->offset
+ * - Masks and shifts the value to @cell->bit_offset position
+ * - Merges with existing bits outside the @cell->nbits field
+ * - Requires @size == sizeof(u32) and @cell->size <= sizeof(u32)
+ *
+ * For cells without bit fields (@cell->nbits == 0):
+ * - Writes raw bytes directly to @cell->offset
+ * - 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