lkml.org 
[lkml]   [2022]   [Aug]   [23]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    /
    Date
    From
    SubjectRe: [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

    \
     
     \ /
      Last update: 2022-08-23 23:02    [W:3.381 / U:0.340 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site