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

[Bjorn Helgaas <helgaas@kernel.org>]

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.