Hi Peter,
On Tue, 23 Aug 2022 11:26:51 +0200
Peter Rosin <peda@xxxxxxxxxx> wrote:
> 2022-08-22 at 11:10, luca.ceresoli@xxxxxxxxxxx wrote:
> > From: Luca Ceresoli <luca.ceresoli@xxxxxxxxxxx>
> >
> > The sequence of sections is a bit confusing here:
> >
> > * we list the mux locking scheme for existing drivers before introducing
> > what mux locking schemes are
> > * we list the caveats for each locking scheme (which are tricky) before
> > the example of the simple use case
> >
> > Restructure it entirely with the following logic:
> >
> > * Intro ("I2C muxes and complex topologies")
> > * Locking
> > - mux-locked
> > - example
> > - caveats
> > - parent-locked
> > - example
> > - caveats
> > * Complex examples
> > * Mux type of existing device drivers
> >
> > While there, also apply some other improvements:
> >
> > * convert the caveat list from a table (with only one column carrying
> > content) to a bullet list.
>
> I want to be able to refer to a specific caveat if/when someone has
> questions, so I prefer to have the caveats "named". Not that this is
> very frequent, but if we do remove the tags now I'm sure I'm going
> to need them a few minutes later...
Now I realize the reason for those labels. Thank you for taking time to
explain!
What about this one:
[ML1]
If you build a topology with ...
It's a definition list, and the [ML1] gets rendered in bold.
The advantage is the text is still rendered as a regular paragraph,
with the same font etc, except the left margin is increased.
> > +Parent-locked Caveats
> > +~~~~~~~~~~~~~~~~~~~~~
> > +
> > +When using a parent-locked mux, be aware of the following restrictions:
> > +
> > +* If you build a topology with a parent-locked mux being the child
> > + of another mux, this might break a possible assumption from the
> > + child mux that the root adapter is unused between its select op
> > + and the actual transfer (e.g. if the child mux is auto-closing
> > + and the parent mux issues I2C transfers as part of its select).
> > + This is especially the case if the parent mux is mux-locked, but
> > + it may also happen if the parent mux is parent-locked.
> > +
> > +* If select/deselect calls out to other subsystems such as gpio,
> > + pinctrl, regmap or iio, it is essential that any I2C transfers
> > + caused by these subsystems are unlocked. This can be convoluted to
> > + accomplish, maybe even impossible if an acceptably clean solution
> > + is sought.
> > +
> > +
> >
>
> Three empty lines is excessive and inconsistent with the other two
> ===-headers.
Indeed! Fix ready for v3, waiting on the above proposal.
--
Luca Ceresoli, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com
