From: Luca Ceresoli <luca.ceresoli@bootlin.com>
To: Peter Rosin <peda@axentia.se>
Cc: linux-doc@vger.kernel.org, linux-i2c@vger.kernel.org,
Wolfram Sang <wsa@kernel.org>,
linux-kernel@vger.kernel.org
Subject: Re: [PATCH v2 2/3] docs: i2c: i2c-topology: reorder sections more logically
Date: Tue, 23 Aug 2022 23:01:10 +0200 [thread overview]
Message-ID: <20220823230110.115a3fc5@booty> (raw)
In-Reply-To: <19a22449-c9fb-1eba-9a47-3e3d340a13a1@axentia.se>
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
next prev parent reply other threads:[~2022-08-23 21:01 UTC|newest]
Thread overview: 11+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-08-22 9:10 [PATCH v2 0/3] docs: i2c: rework I2C documentation, part II luca.ceresoli
2022-08-22 9:10 ` [PATCH v2 1/3] docs: i2c: i2c-topology: fix incorrect heading luca.ceresoli
2022-08-23 9:19 ` Peter Rosin
2022-08-22 9:10 ` [PATCH v2 2/3] docs: i2c: i2c-topology: reorder sections more logically luca.ceresoli
2022-08-23 9:26 ` Peter Rosin
2022-08-23 21:01 ` Luca Ceresoli [this message]
2022-08-24 7:25 ` Peter Rosin
2022-08-22 9:10 ` [PATCH v2 3/3] docs: i2c: i2c-topology: fix typo luca.ceresoli
2022-08-22 13:40 ` Bagas Sanjaya
2022-08-23 8:33 ` Luca Ceresoli
2022-08-23 9:28 ` Peter Rosin
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20220823230110.115a3fc5@booty \
--to=luca.ceresoli@bootlin.com \
--cc=linux-doc@vger.kernel.org \
--cc=linux-i2c@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=peda@axentia.se \
--cc=wsa@kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).