Re: [PATCH v9 5/5] docs: i2c: i2c-topology: add section about bus speed

[Wolfram Sang]

> +Multiple muxes in series
> +--------------------------
> +
> +When multiple muxes are used in series the same rules applies.
> +
> +Transfers to D3 may interleave between select-transfer-deselect to D1, which
> +results that the bus speed to D2 or D3 will be at 100KHz.
> +
> +Transfers to D2 may interleave between select-transfer-deselect to D1, which
> +results in that the bus speed to D1 may be at 400kHz as the transfer to D2
> +will set the bus speed to before the transfer to D1 starts.
> +
> +This is probably a bad topology ::

In documentation, we probably shouldn't say "probably" ;)

> +
> +                     .----------. 400kHz .----------. 100kHz .--------.
> +    .--------.400kHz |   mux-   |--------|   mux-   |--------| dev D1 |
> +    |  root  |--+----|  locked  | 400kHz |  locked  |        '--------'
> +    '--------'  |    |  mux M1  |--.     |  mux M2  |
> +                |    '----------'  |     '----------'
> +                |  .--------.      |  .--------.
> +                '--| dev D3 |      '--| dev D2 |
> +                   '--------'         '--------'

400kHz leaking to a 100kHz device is bad. I guess we cannot do much
about it here because the bus speed is a board specific parameter...

> +Idle state
> +-----------
> +
> +Muxes have an idle state, which is the state the channels are put into when no channel
> +is active. The state is typically one of the following:
> +
> +- All channels are disconnected
> +- The last selected channel is left as-is
> +- A predefined channel is selected
> +
> +Muxes that support an idle state where all channels are disconnected are preferred when using
> +different bus speeds. Otherwise high bus speeds may "leak" through to devices that
> +may not support that higher speed.
> +
> +Consider the following example: ::
> +
> +                          .----------. 100kHz .--------.
> +        .--------. 400kHz |   mux-   |--------| dev D1 |
> +        |  root  |--+-----|  locked  |        '--------'
> +        '--------'  |     |  mux M1  |--. 400kHz .--------.
> +                    |     '----------'  '--------| dev D2 |
> +                    |  .--------.                '--------'
> +                    '--| dev D3 |
> +                       '--------'
> +
> +If the idle state of M1 is:
> +
> +- All channels disconnected: No problem, D1 and D2 are not affected by communication
> +  to D3.
> +- Last selected channel: Problem if D1 was the last selected channel. High speed
> +  communication to D3 will be "leaked" to D1.
> +- Predefined channel: Problem if the predefined channel D1. Set predefined channel
> +  to D2 as D2 may handle 400kHz.

... unlike here. We have MUX_IDLE_AS_IS and MUX_IDLE_DISCONNECT defined
already. And I'd think we should only allow bus speed switching for
MUX_IDLE_DISCONNECT to avoid out-of-spec scenarios. Opinions?

> +Supported controllers
> +-----------------------
> +
> +Not all I2C controllers support setting the bus speed dynamically.
> +At the time of writing, the following controllers have support:
> +
> +============================   =============================================
> +i2c-davinci                    Supports dynamic bus speed
> +============================   =============================================

This paragaph is easy to get outdated. We can document that only
controller drivers with the callback function implemented will work.
People then can find out if that applies for their driver...

There are some grammar correction in the Sashiko-review[1]. Most of them
look correct to me. Can you have a look at these, too, please?

[1] https://sashiko.dev/#/patchset/20260324-i2c-mux-v9-0-5292b0608243%40gmail.com