[PATCH 05/25] dt-bindings: net: dwmac: Elaborate stmmaceth/pclk description

[Rob Herring]

On Mon, 14 Dec 2020 12:15:55 +0300, Serge Semin wrote:
> Current clocks description doesn't provide a comprehensive notion about
> what "stmmaceth" and "pclk" actually represent from the IP-core manual
> point of view. The bindings file states:
> stmmaceth - "GMAC main clock",
> apb - "Peripheral registers interface clock".
> It isn't that easy to understand what they actually mean especially seeing
> the DW *MAC manual operates with clock definitions like Application,
> System, Host, CSR, Transmit, Receive, etc clocks. Moreover the clocks
> usage in the driver doesn't shade a full light on their essence. What
> inferred from there is that the "stmmaceth" name has been assigned to the
> common clock, which feeds both system and CSR interfaces. But what about
> "apb"? The bindings defines it as the clock for "peripheral registers
> interface". So it's close to the CSR clock in the IP-core manual notation.
> If so then when "apb" clock is specified aside with the "stmmaceth", it
> represents a case when the DW *MAC is synthesized with CSR_SLV_CLK=y
> (separate system and CSR clocks). But even though the "apb" clock is
> requested in the MAC driver, the driver doesn't actually use it as a
> separate CSR clock where the IP-core manual requires. All of that makes me
> thinking that the case of separate system and CSR clocks isn't correctly
> implemented in the driver.
> 
> Let's start with elaborating the clocks description so anyone reading
> the DW *MAC bindings file would understand that "stmmaceth" is the
> system clock and "pclk" is actually the CSR clock. Indeed in accordance
> with sheets depicted in [1]:
> system/application clock can be either of: hclk_i, aclk_i, clk_app_i;
> CSR clock can be either of: hclk_i, aclk_i, clk_app_i, clk_csr_i.
> (Most likely the similar definitions present in the others IP-core
> manuals.) So the CSR clock can be tied to the application clock
> considering the later as the main clock, but not the other way around. In
> case if there is only "stmmaceth" clock specified in a DT node, then it
> will be considered as a source of clocks for both application and CSR. But
> if "pclk" is also specified in the list of the device clocks, then it will
> be perceived as the separate CSR clock.
> 
> [1] DesignWare Cores Ethernet MAC Universal Databook, Revision 3.73a,
>     October 2013, p. 564.
> 
> Signed-off-by: Serge Semin <Sergey.Semin at baikalelectronics.ru>
> ---
>  .../devicetree/bindings/net/snps,dwmac.yaml          | 12 ++++++++++--
>  1 file changed, 10 insertions(+), 2 deletions(-)
> 

Reviewed-by: Rob Herring <robh at kernel.org>