rust: net: phy: intent for MAE0621A (out-of-tree C -> Rust), request for target guidance

rust: net: phy: intent for MAE0621A (out-of-tree C -> Rust), request for target guidance

[wenzhaoliao]

Hello PHY and Rust maintainers,


I am a PhD student working on a C-to-Rust migration tool for systems code.
We would like to validate it in Linux with one concrete PHY target and would
like to confirm direction before posting a larger RFC series.


Scope of this intent:
- Initial target: MAE0621A (currently out-of-tree C driver).
- We do NOT intend to submit a duplicate Rust rewrite of an existing in-tree C PHY driver.
- Goal: evaluate a semi-automatic abstraction completion workflow:
  reuse existing Rust PHY abstractions where possible, and add only minimal missing abstractions.


Planned deliverables:
- A gap analysis between MAE0621A C callbacks and current rust/kernel/net/phy.rs coverage.
- A small RFC patch series with minimal abstraction additions (if needed).
- A MAE0621A Rust driver prototype on top of those abstractions for linux-next/rust-next evaluation.


Quality and process commitments:
- Full human review by submitters; we can explain all submitted code.
- Transparent disclosure of tool assistance in cover letters/changelogs.
- Hardware-backed test results and explicit limitations in each posting.


Questions:
1. Is MAE0621A an acceptable first target for this direction?
2. If MAE0621A is not suitable, could you recommend one or two better out-of-tree PHY drivers for a first Rust submission?
3. For review flow, do you prefer:
   (a) abstractions-first RFC, then driver, or
   (b) minimal abstractions + concrete driver in one RFC series?


If there are no objections, we plan to post an RFC 0/N in about 2 weeks.


Thanks for your guidance.


Best regards,
Liao Wenzhao
Renmin University of China

Re: rust: net: phy: intent for MAE0621A (out-of-tree C -> Rust), request for target guidance

[Andrew Lunn]

On Wed, Apr 15, 2026 at 05:59:58PM +0800, wenzhaoliao wrote:
> 
> Hello PHY and Rust maintainers,
> 
> 
> I am a PhD student working on a C-to-Rust migration tool for systems code.
> We would like to validate it in Linux with one concrete PHY target and would
> like to confirm direction before posting a larger RFC series.
> 
> 
> Scope of this intent:
> - Initial target: MAE0621A (currently out-of-tree C driver).
> - We do NOT intend to submit a duplicate Rust rewrite of an existing in-tree C PHY driver.
> - Goal: evaluate a semi-automatic abstraction completion workflow:
>   reuse existing Rust PHY abstractions where possible, and add only minimal missing abstractions.
> 
> 
> Planned deliverables:
> - A gap analysis between MAE0621A C callbacks and current rust/kernel/net/phy.rs coverage.
> - A small RFC patch series with minimal abstraction additions (if needed).
> - A MAE0621A Rust driver prototype on top of those abstractions for linux-next/rust-next evaluation.

When done correctly, this sounds reasonable. However, i do have some
further questions.

Do you have hardware? What board do you intent to test this on. Does
the board boot using Mainline?

Do you have the datasheet?

What out of tree C driver do you intend to start from. I had a quick
look around and the first one i found is:

https://github.com/CoreELEC/linux-amlogic/blob/amlogic-5.4.210/drivers/net/phy/maxio.c

As is often the case of an out of tree driver, it is not up to the
quality of a Mainline driver. Doing a tool based C to Rust migration
based on this code will just give you a poor quality Rust driver,
which will not be accepted. Do you have the knowledge to fix all the
issues?

Maybe you can tell us what C driver you are plan to use, and do a
review of it, list all the issues you see with it, what needs
fixing. That will give us an idea if you can produce a Mainline
quality driver.

	Andrew

Re:rust: net: phy: intent for MAE0621A (out-of-tree C -> Rust), request for target guidance

[wenzhaoliao]

Hello Andrew,


Thank you for the concrete questions. They were very helpful.


We agree with your main concern: using a low-quality out-of-tree C driver as a
mechanical translation baseline would not produce something acceptable
upstream. If we continue with MAE0621A, the existing out-of-tree C code would
only be one input for behavior discovery, not the quality baseline for the
submitted driver.


After your reply, we reviewed the public `maxio.c` driver you pointed to, and
we agree that it has a number of issues that would need to be fixed before any
upstreamable Rust driver could be justified. For example:


- paged register access is open-coded and does not robustly propagate or
  restore errors;
- several vendor sequences use magic page/register values with no documented
  rationale in the driver;
- there are unconditional resets and fixed `mdelay`/`msleep` delays without a
  clear completion check or justification;
- debugging uses raw `printk()` calls;
- some helper return values are ignored, and `ret |= ...` is not a good fit
  for mainline-style error handling;
- the MMD / EEE handling looks narrowly special-cased and would need to be
  re-checked against phylib conventions and proper documentation.


So our plan, if we continue with this direction, would be to treat it as a
clean-room, mainline-quality driver effort informed by documentation, phylib
conventions, and board-level requirements, and only secondarily by the
existing out-of-tree code.


At the same time, we should also be explicit that we do not currently have
MAE0621A hardware in hand, nor sufficient public documentation to claim that
it is already a well-grounded first target. Our current local setup is useful
for Rust-for-Linux build/tooling validation and limited non-hardware checks,
but not for real hardware-backed PHY validation.


That is exactly why we wanted to ask early, before investing too much work in
the wrong target.


If there is a more suitable out-of-tree PHY target, PHY variant, or board/PHY
setup for an initial Rust PHY submission, we would greatly appreciate your
guidance. We are specifically trying to avoid duplicating an existing in-tree
C PHY driver, and if a realistic and useful target requires buying suitable
hardware, we are willing to do that.


Likewise, if there is some PHY-side Rust task that would be more useful than a
device-specific Rust port, we would also appreciate that guidance. We do not
want to force a C-to-Rust migration target where maintainers would prefer a
different kind of contribution.


If recommending a target is not practical, our fallback would be to stay at
the analysis stage for now:


- write up a short review of the public MAE0621A C driver and the issues that
  would need to be fixed for mainline quality; and
- map those requirements against the current Rust PHY abstraction surface,
  without claiming hardware-backed validation yet.


Would that limited analysis-first step still be useful, or would you prefer
that we pause the driver-RFC direction until we have a better target and
hardware setup?


Thank you again for the guidance.


Best regards,
Liao Wenzhao






发件人：wenzhaoliao <wenzhaoliao@ruc.edu.cn>
发送日期：2026-04-15 17:59:58
收件人：andrew@lunn.ch,hkallweit1@gmail.com,fujita.tomonori@gmail.com
抄送人：linux@armlinux.org.uk,tmgross@umich.edu,ojeda@kernel.org,netdev@vger.kernel.org,rust-for-linux@vger.kernel.org
主题：rust: net: phy: intent for MAE0621A (out-of-tree C -> Rust), request for target guidance>
>Hello PHY and Rust maintainers,
>
>
>I am a PhD student working on a C-to-Rust migration tool for systems code.
>We would like to validate it in Linux with one concrete PHY target and would
>like to confirm direction before posting a larger RFC series.
>
>
>Scope of this intent:
>- Initial target: MAE0621A (currently out-of-tree C driver).
>- We do NOT intend to submit a duplicate Rust rewrite of an existing in-tree C PHY driver.
>- Goal: evaluate a semi-automatic abstraction completion workflow:
>  reuse existing Rust PHY abstractions where possible, and add only minimal missing abstractions.
>
>
>Planned deliverables:
>- A gap analysis between MAE0621A C callbacks and current rust/kernel/net/phy.rs coverage.
>- A small RFC patch series with minimal abstraction additions (if needed).
>- A MAE0621A Rust driver prototype on top of those abstractions for linux-next/rust-next evaluation.
>
>
>Quality and process commitments:
>- Full human review by submitters; we can explain all submitted code.
>- Transparent disclosure of tool assistance in cover letters/changelogs.
>- Hardware-backed test results and explicit limitations in each posting.
>
>
>Questions:
>1. Is MAE0621A an acceptable first target for this direction?
>2. If MAE0621A is not suitable, could you recommend one or two better out-of-tree PHY drivers for a first Rust submission?
>3. For review flow, do you prefer:
>   (a) abstractions-first RFC, then driver, or
>   (b) minimal abstractions + concrete driver in one RFC series?
>
>
>If there are no objections, we plan to post an RFC 0/N in about 2 weeks.
>
>
>Thanks for your guidance.
>
>
>Best regards,
>Liao Wenzhao
>Renmin University of China
>

Re: rust: net: phy: intent for MAE0621A (out-of-tree C -> Rust), request for target guidance

[Andrew Lunn]

> - paged register access is open-coded and does not robustly propagate or
>   restore errors;
> - several vendor sequences use magic page/register values with no documented
>   rationale in the driver;
> - there are unconditional resets and fixed `mdelay`/`msleep` delays without a
>   clear completion check or justification;
> - debugging uses raw `printk()` calls;
> - some helper return values are ignored, and `ret |= ...` is not a good fit
>   for mainline-style error handling;
> - the MMD / EEE handling looks narrowly special-cased and would need to be
>   re-checked against phylib conventions and proper documentation.

Nice, you spotted many of the issues in that code. That gives me a
better feeling, you have some understanding of Ethernet PHYs.

> At the same time, we should also be explicit that we do not currently have
> MAE0621A hardware in hand, nor sufficient public documentation to claim that
> it is already a well-grounded first target. Our current local setup is useful
> for Rust-for-Linux build/tooling validation and limited non-hardware checks,
> but not for real hardware-backed PHY validation.

My personal experience is that anything which is not tested is
broken. For a driver to be merged, it needs to be tested on real
hardware.

Can you get one of the amlogic boards? TrustOnX Player (TOX3)? Radxa
A5E? I've no idea how easy it is to get Mainline running on these
boards.

	Andrew

Re:Re: rust: net: phy: intent for MAE0621A (out-of-tree C -> Rust), request for target guidance

[wenzhaoliao]

Hello Andrew,


Thank you, this is very helpful.


We agree with your point that for a driver to be merged, it needs to be tested
on real hardware. So we will not push the driver-RFC direction further without
getting hardware into the loop first.


We will now look into obtaining one of the suggested boards and check what it
takes to get a near-mainline or mainline kernel running on it. Based on that,
we will decide whether this is a realistic first target before investing more
time in the Rust driver work itself.


At the moment, Radxa A5E looks like the more concrete option from our side,
mainly because there seems to be visible public discussion around MAE0621A on
that board. But we are still checking the practical side of board availability
and software support.


If you have a preference between TrustOnX Player (TOX3) and Radxa A5E as a
first board to try, that would be very helpful. Otherwise, we will investigate
the A5E path first and come back once we have a clearer hardware/testing plan.


Thank you again for the guidance.


Best regards,
Liao Wenzhao









发件人：Andrew Lunn <andrew@lunn.ch>
发送日期：2026-04-15 22:53:17
收件人：wenzhaoliao <wenzhaoliao@ruc.edu.cn>
抄送人：hkallweit1@gmail.com,fujita.tomonori@gmail.com,linux@armlinux.org.uk,tmgross@umich.edu,ojeda@kernel.org,netdev@vger.kernel.org,rust-for-linux@vger.kernel.org
主题：Re: rust: net: phy: intent for MAE0621A (out-of-tree C -> Rust), request for target guidance>> - paged register access is open-coded and does not robustly propagate or
>>   restore errors;
>> - several vendor sequences use magic page/register values with no documented
>>   rationale in the driver;
>> - there are unconditional resets and fixed `mdelay`/`msleep` delays without a
>>   clear completion check or justification;
>> - debugging uses raw `printk()` calls;
>> - some helper return values are ignored, and `ret |= ...` is not a good fit
>>   for mainline-style error handling;
>> - the MMD / EEE handling looks narrowly special-cased and would need to be
>>   re-checked against phylib conventions and proper documentation.
>
>Nice, you spotted many of the issues in that code. That gives me a
>better feeling, you have some understanding of Ethernet PHYs.
>
>> At the same time, we should also be explicit that we do not currently have
>> MAE0621A hardware in hand, nor sufficient public documentation to claim that
>> it is already a well-grounded first target. Our current local setup is useful
>> for Rust-for-Linux build/tooling validation and limited non-hardware checks,
>> but not for real hardware-backed PHY validation.
>
>My personal experience is that anything which is not tested is
>broken. For a driver to be merged, it needs to be tested on real
>hardware.
>
>Can you get one of the amlogic boards? TrustOnX Player (TOX3)? Radxa
>A5E? I've no idea how easy it is to get Mainline running on these
>boards.
>
>	Andrew
>

Re: Re: rust: net: phy: intent for MAE0621A (out-of-tree C -> Rust), request for target guidance

[Andrew Lunn]

> If you have a preference between TrustOnX Player (TOX3) and Radxa A5E as a
> first board to try, that would be very helpful. Otherwise, we will investigate
> the A5E path first and come back once we have a clearer hardware/testing plan.

Makes no difference to me. Use whatever is simplest for you.

If you want to do more than just convert the C driver to Rust, but add
new features, made see if the LEDs are controlled by the PHY? Is there
an interrupt output from the PHY to the SoC? Does the board support
WoL? These are all features which the Rust binding is missing, and
could be added, if you have a device to test them on, and the needed
register information.

      Andrew