Messages in this thread | | | Date | Tue, 23 Aug 2022 23:01:10 +0200 | From | Luca Ceresoli <> | Subject | Re: [PATCH v2 2/3] docs: i2c: i2c-topology: reorder sections more logically |
| |
Hi Peter,
On Tue, 23 Aug 2022 11:26:51 +0200 Peter Rosin <peda@axentia.se> wrote:
> 2022-08-22 at 11:10, luca.ceresoli@bootlin.com wrote: > > From: Luca Ceresoli <luca.ceresoli@bootlin.com> > > > > 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
| |