Received-SPF: pass (google.com: domain of linux-kernel+bounces-162669-linux.lists.archive=gmail.com@vger.kernel.org designates 147.75.80.249 as permitted sender) client-ip=147.75.80.249;
Date: Mon, 29 Apr 2024 17:17:16 +0100
From: Simon Horman <horms@kernel.org>
To: Parthiban Veerasooran <Parthiban.Veerasooran@microchip.com>
Cc: davem@davemloft.net, edumazet@google.com, kuba@kernel.org,
	pabeni@redhat.com, saeedm@nvidia.com, anthony.l.nguyen@intel.com,
	netdev@vger.kernel.org, linux-kernel@vger.kernel.org,
	andrew@lunn.ch, corbet@lwn.net, linux-doc@vger.kernel.org,
	robh+dt@kernel.org, krzysztof.kozlowski+dt@linaro.org,
	conor+dt@kernel.org, devicetree@vger.kernel.org,
	horatiu.vultur@microchip.com, ruanjinjie@huawei.com,
	steen.hegelund@microchip.com, vladimir.oltean@nxp.com,
	UNGLinuxDriver@microchip.com, Thorsten.Kummermehr@microchip.com,
	Pier.Beruto@onsemi.com, Selvamani.Rajagopal@onsemi.com,
	Nicolas.Ferre@microchip.com, benjamin.bigler@bernformulastudent.ch
Subject: Re: [PATCH net-next v4 01/12] Documentation: networking: add OPEN
 Alliance 10BASE-T1x MAC-PHY serial interface
Message-ID: <20240429161716.GZ516117@kernel.org>
References: <20240418125648.372526-1-Parthiban.Veerasooran@microchip.com>
 <20240418125648.372526-2-Parthiban.Veerasooran@microchip.com>
Precedence: bulk
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <20240418125648.372526-2-Parthiban.Veerasooran@microchip.com>

On Thu, Apr 18, 2024 at 06:26:37PM +0530, Parthiban Veerasooran wrote:
> The IEEE 802.3cg project defines two 10 Mbit/s PHYs operating over a
> single pair of conductors. The 10BASE-T1L (Clause 146) is a long reach
> PHY supporting full duplex point-to-point operation over 1 km of single
> balanced pair of conductors. The 10BASE-T1S (Clause 147) is a short reach
> PHY supporting full / half duplex point-to-point operation over 15 m of
> single balanced pair of conductors, or half duplex multidrop bus
> operation over 25 m of single balanced pair of conductors.
> 
> Furthermore, the IEEE 802.3cg project defines the new Physical Layer
> Collision Avoidance (PLCA) Reconciliation Sublayer (Clause 148) meant to
> provide improved determinism to the CSMA/CD media access method. PLCA
> works in conjunction with the 10BASE-T1S PHY operating in multidrop mode.
> 
> The aforementioned PHYs are intended to cover the low-speed / low-cost
> applications in industrial and automotive environment. The large number
> of pins (16) required by the MII interface, which is specified by the
> IEEE 802.3 in Clause 22, is one of the major cost factors that need to be
> addressed to fulfil this objective.
> 
> The MAC-PHY solution integrates an IEEE Clause 4 MAC and a 10BASE-T1x PHY
> exposing a low pin count Serial Peripheral Interface (SPI) to the host
> microcontroller. This also enables the addition of Ethernet functionality
> to existing low-end microcontrollers which do not integrate a MAC
> controller.
> 
> Signed-off-by: Parthiban Veerasooran <Parthiban.Veerasooran@microchip.com>

Hi Parthiban,

Some minor feedback from my side.

> ---
>  Documentation/networking/oa-tc6-framework.rst | 491 ++++++++++++++++++

Please add oa-tc6-framework to 

Flagged by: make SPHINXDIRS="networking" htmldocs

>  MAINTAINERS                                   |   6 +
>  2 files changed, 497 insertions(+)
>  create mode 100644 Documentation/networking/oa-tc6-framework.rst
> 
> diff --git a/Documentation/networking/oa-tc6-framework.rst b/Documentation/networking/oa-tc6-framework.rst

..

> +Device drivers API
> +==================
> +
> +The include/linux/oa_tc6.h defines the following functions:
> +
> +.. c:function:: struct oa_tc6 *oa_tc6_init(struct spi_device *spi,
> +                                           struct net_device *netdev)

I think that you need to use a '\' to escape newlines
for a for a multi-line c:function.

e.g.
. c:function:: struct oa_tc6 *oa_tc6_init(struct spi_device *spi, \
                                           struct net_device *netdev)

Link: https://www.sphinx-doc.org/en/master/usage/domains/index.html

Flagged by make SPHINXDIRS="networking" htmldocs
when using Sphinx 7.2.6

> +
> +Initialize OA TC6 lib.
> +
> +.. c:function:: void oa_tc6_exit(struct oa_tc6 *tc6)
> +
> +Free allocated OA TC6 lib.
> +
> +.. c:function:: int oa_tc6_write_register(struct oa_tc6 *tc6, u32 address,
> +                                          u32 value)
> +
> +Write a single register in the MAC-PHY.
> +
> +.. c:function:: int oa_tc6_write_registers(struct oa_tc6 *tc6, u32 address,
> +                                           u32 value[], u8 length)
> +
> +Writing multiple consecutive registers starting from @address in the MAC-PHY.
> +Maximum of 128 consecutive registers can be written starting at @address.
> +
> +.. c:function:: int oa_tc6_read_register(struct oa_tc6 *tc6, u32 address,
> +                                         u32 *value)
> +
> +Read a single register in the MAC-PHY.
> +
> +.. c:function:: int oa_tc6_read_registers(struct oa_tc6 *tc6, u32 address,
> +                                          u32 value[], u8 length)
> +
> +Reading multiple consecutive registers starting from @address in the MAC-PHY.
> +Maximum of 128 consecutive registers can be read starting at @address.
> +
> +.. c:function:: netdev_tx_t oa_tc6_start_xmit(struct oa_tc6 *tc6,
> +                                              struct sk_buff *skb);
> +
> +The transmit Ethernet frame in the skb is or going to be transmitted through
> +the MAC-PHY.

..