[PATCH v1] regmap: Clarify _regmap_update_bits() 'async' kernel-doc

[PATCH v1] regmap: Clarify _regmap_update_bits() 'async' kernel-doc

[Bjorn Helgaas]

The kernel-doc for the '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.

Assisted-by: Gemini:3.1 Pro
Signed-off-by: Bjorn Helgaas <bhelgaas@google.com>
---
 drivers/base/regmap/regmap.c | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/drivers/base/regmap/regmap.c b/drivers/base/regmap/regmap.c
index e6e022b02637..430dc8233c40 100644
--- a/drivers/base/regmap/regmap.c
+++ b/drivers/base/regmap/regmap.c
@@ -3296,11 +3296,11 @@ 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, most buses
+ * require synchronous reads, so the read-modify-write cycle will still
+ * block on the read unless the device uses a register cache.  Therefore,
+ * this flag is most useful for cached devices, where the current value can
+ * be read from memory without hardware I/O.
  *
  * Returns zero for success, a negative number on error.
  */
-- 
2.53.0

Re: [PATCH v1] regmap: Clarify _regmap_update_bits() 'async' kernel-doc

[Mark Brown]

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

On Fri, Jul 17, 2026 at 03:50:31PM -0500, Bjorn Helgaas wrote:

> 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.

> - * 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, most buses
> + * require synchronous reads, so the read-modify-write cycle will still
> + * block on the read unless the device uses a register cache.  Therefore,
> + * this flag is most useful for cached devices, where the current value can
> + * be read from memory without hardware I/O.

That's...  verbose.  If you want to add a statement that async mode
will be using async I/O then possibly I guess but there's a whole bunch
more there.

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

Re: [PATCH v1] regmap: Clarify _regmap_update_bits() 'async' kernel-doc

[Bjorn Helgaas]

On Fri, Jul 17, 2026 at 11:59:14PM +0100, Mark Brown wrote:
> On Fri, Jul 17, 2026 at 03:50:31PM -0500, Bjorn Helgaas wrote:
> 
> > 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.
> 
> > - * 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, most buses
> > + * require synchronous reads, so the read-modify-write cycle will still
> > + * block on the read unless the device uses a register cache.  Therefore,
> > + * this flag is most useful for cached devices, where the current value can
> > + * be read from memory without hardware I/O.
> 
> That's...  verbose.  If you want to add a statement that async mode
> will be using async I/O then possibly I guess but there's a whole bunch
> more there.

The main problem is that the current text doesn't read well because
"if async is true" isn't connected to the rest.

There are three functions that take an "async" parameter, but two just
pass it on to regmap_update_bits_base(), so that seems like a
reasonable single place to say something about it.

Maybe something like this would be enough?

  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.