[PATCH v2] regmap: Clarify regmap_update_bits_base() 'async' kernel-doc

[PATCH v2] regmap: Clarify regmap_update_bits_base() 'async' kernel-doc

[Bjorn Helgaas]

The kernel-doc for the regmap_update_bits_base() 'async' parameter didn't
actually say what it does.

Reword it to clarify the read-modify-write mechanics: when 'async' is true,
the write is queued asynchronously, but the read will still be synchronous
unless the device uses a register cache.

Signed-off-by: Bjorn Helgaas <bhelgaas@google.com>
---
Changes since v1:
  - Shorten doc, mention the correct function in subject

v1: https://lore.kernel.org/all/20260717205031.197980-1-bhelgaas@google.com

 drivers/base/regmap/regmap.c | 8 +++-----
 1 file changed, 3 insertions(+), 5 deletions(-)

diff --git a/drivers/base/regmap/regmap.c b/drivers/base/regmap/regmap.c
index e6e022b02637..d0deddec516f 100644
--- a/drivers/base/regmap/regmap.c
+++ b/drivers/base/regmap/regmap.c
@@ -3296,11 +3296,9 @@ static int _regmap_update_bits(struct regmap *map, unsigned int reg,
  * Perform a read/modify/write cycle on a register map with change, async, force
  * options.
  *
- * If async is true:
- *
- * With most buses the read must be done synchronously so this is most useful
- * for devices with a cache which do not need to interact with the hardware to
- * determine the current register value.
+ * If async is true, queue an asynchronous write. However, reads are
+ * synchronous on most buses, so they will still block unless the device
+ * uses a register cache.
  *
  * Returns zero for success, a negative number on error.
  */
-- 
2.53.0

Re: [PATCH v2] regmap: Clarify regmap_update_bits_base() 'async' kernel-doc

[Mark Brown]

[-- Attachment #1: Type: text/plain, Size: 651 bytes --]

On Tue, Jul 21, 2026 at 10:49:02AM -0500, Bjorn Helgaas wrote:

> The kernel-doc for the regmap_update_bits_base() 'async' parameter didn't
> actually say what it does.

It does?

> Reword it to clarify the read-modify-write mechanics: when 'async' is true,
> the write is queued asynchronously, but the read will still be synchronous
> unless the device uses a register cache.

The API here is that we'll use async as much as is supported, there are
actually some buses that have a read/modify/write operation in the
protocol so if one of them supported async I/O we could use it here
(we'd need to plumb that through, but the users shouldn't care).

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]