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 <[email protected]> --- 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
