uefi-raw: improve convenience of net types #1699

phip1611 · 2025-06-15T19:25:08Z

This prepares my vision for #1575, a split-out from #1645.

This adds much more convenience to the network types in uefi-raw, better integrating them with core::net types but also "typical" workflows. This "higher-level" logic is still low-level enough that I think it is perfectly fine to keep it. It will also not hinder Rust-based UEFI implementations.

Steps to Undraft

merge and rebase onto uefi-raw: move types to net module #1747
merge and rebase onto uefi-raw: various small net improvements #1748

Checklist

Sensible git history (for example, squash "typo" or "fix" commits). See the Rewriting History guide for help.
Update the changelog (if necessary)

uefi-raw/CHANGELOG.md

phip1611 · 2025-07-09T10:54:29Z

For the record. Starting Friday, I'll be on vacation until July 30th. My plan is to program-detox for the whole period 😀 Restarting the work afterwards

phip1611 · 2025-08-17T11:40:10Z

I'm unsure how I could fix the rustdoc error best. I want the documentation of the net module to be publicly available (it is a clear value-add), but earlier you suggested exporting its exports in a flat way, i.e., directly from the top-level.

However: making the module public allows to import the same types from uefi_raw::Type and uefi_raw::net::Type, which is not ideal. Perhaps we should export all net::* types also publicly?

nicholasbishop · 2025-08-18T15:45:51Z

What if we removed the module doc and instead added this information to the individual types? The module doc is basically saying "you can convert between core::net types and uefi_raw net type". E.g. for Ipv4Address it could be something like:

/// An IPv4 internet protocol address.
///
/// This type can be converted to and from [`core::net::Ipv4Addr`] using the [`From`] trait.

phip1611 · 2025-08-19T08:31:00Z

What if we removed the module doc and instead added this information to the individual types?

Yeah, good idea, why not :) What do you think about the latest state?

nicholasbishop · 2025-08-21T19:47:28Z

Generally looks good, but I haven't reviewed the details yet. Could you open a PR that just does the copy-paste move of stuff to a new module first? That should be very quick to review and merge, and then it won't get mixed in with the other changes. (I realize it's already broken down that way by commit, but there are still a lot of changes in commit 870aced that I would like to review more thoroughly, and it'll be easier for me if the module-move has already been merged.)

phip1611 · 2025-08-25T15:58:48Z

should be much easier to review now

nicholasbishop · 2025-08-25T16:07:24Z

uefi-raw/src/net.rs

@@ -83,19 +119,65 @@ pub union IpAddress {
 }

 impl IpAddress {
+    /// Construct a new zeroed address.
+    #[must_use]
+    pub const fn new_zeroed() -> Self {


How about an associated const instead of a function?

pub const ZERO: Self = Self { addr: [0; 4] };

I like the idea, thanks

nicholasbishop · 2025-08-26T15:53:10Z

uefi-raw/src/net.rs

@@ -24,19 +32,32 @@ impl Ipv4Address {
    }
 }

-impl From<core::net::Ipv4Addr> for Ipv4Address {
-    fn from(ip: core::net::Ipv4Addr) -> Self {
+impl From<StdIpv4Addr> for Ipv4Address {


nit: I guess this is a personal preference thing, but I don't think it's clearer to introduce type aliases for the core::net types. core::net:: isn't that long to write out, and is more explicit.

nicholasbishop · 2025-08-26T16:05:47Z

uefi-raw/src/net.rs

-            v4: Ipv4Address(ip_addr),
-        }
+    pub const fn new_v4(octets: [u8; 4]) -> Self {
+        // Initialize all bytes to zero first.


Can you say more about why this is desired? Perhaps a specific example of code where it would be useful to have this property.

My thought here was that:

make code safer if someone accidentally use the v6 variant afterwards

this initialization overhead is negligible

I just thought about this again, and I think we should drop. This only made sense in my previous design, which we discarded.

nicholasbishop · 2025-08-26T16:08:13Z

uefi-raw/src/net.rs

+
+    /// Returns a raw pointer to the IP address.
+    #[must_use]
+    pub const fn as_ptr(&self) -> *const Self {


I don't think a method is needed when it's just returning a pointer to self, instead the caller can write &raw addr/&raw mut addr (those operators were stabilized in 1.82)

You are right, it is not needed. UEFI protocols consuming *mut IpAddress can also consume a &mut IpAddress and Rust does the right thing behind the scenes.

nicholasbishop · 2025-08-26T16:13:37Z

uefi-raw/src/net.rs

@@ -158,9 +278,10 @@ impl From<[u8; 6]> for MacAddress {
    }
 }

-impl From<MacAddress> for [u8; 6] {


Was removing MacAddress -> [u8; 6] intentional?

good catch; rebase glitch

nicholasbishop · 2025-08-26T16:14:51Z

uefi-raw/src/net.rs

+
+    /// Tries to interpret the MAC address as normal 6-byte MAC address, as used
+    /// in ethernet.
+    pub fn try_into_ethernet_mac_addr(self) -> Result<[u8; 6], [u8; 32]> {


This seems to make an assumption about zero being invalid, but is that true? If so, let's point to relevant documentation. If not, let's drop this method.

This originates from my naive assumption that triviality applies here. Why would one have a fully non-null initialized byte array that takes more bytes than just a normal MAC address?

IMHO, this is a common use-case that will simplify things. In most cases, people want to work with Ethernet Mac addresses and they need a convenient conversion for that.

What do you think?

nicholasbishop · 2025-08-26T16:17:11Z

uefi-raw/src/net.rs

+    ///   IPv4 address.
+    ///
+    /// # Safety
+    /// Callers must be sure that all underlying bytes were initialized.


nit: This is a bit ambiguous. "all underlying bytes" could be read as "all bytes in the type", but that's not required for ipv4. Maybe something like: "Callers must ensure that the v4 field is valid if is_ipv6 is false, and that the v6 field is valid if is_ipv6 is true"

I like this much better, thanks!

nicholasbishop · 2025-08-26T16:19:14Z

uefi-raw/src/net.rs

+    /// # Safety
+    /// Callers must be sure that all underlying bytes were initialized.
+    #[must_use]
+    pub unsafe fn into_std_ip_addr(self, is_ipv6: bool) -> StdIpAddr {


nit: Should this be into_core_ip_addr? I'm not sure if there's an existing ecosystem convention either way, just want to make clear to end users that this method works in a no_std env.

phip1611 · 2025-09-07T14:48:18Z

Thanks for your valuable input :) I think we are getting closer to merging the additional convenience.

This will help in the following to better distinct between all the types from core::net (Std prefix) and EFI (no prefix). It is also slightly shorter than writing `core::net::` prefix all the time. This renaming is only internally and not exposed.

- added missing conversions between core::net types and the uefi-raw net types - added missing conversions for "typical byte arrays"

phip1611 requested a review from nicholasbishop June 15, 2025 19:25

phip1611 force-pushed the core-net-v2 branch 3 times, most recently from 2b8f102 to 85838ce Compare June 15, 2025 19:36

nicholasbishop reviewed Jun 16, 2025

View reviewed changes

uefi-raw/CHANGELOG.md Outdated Show resolved Hide resolved

phip1611 marked this pull request as draft July 9, 2025 10:53

phip1611 changed the title ~~uefi-raw: move types to new net module, improve convenience~~ [WIP] uefi-raw: move types to new net module, improve convenience Jul 9, 2025

phip1611 marked this pull request as ready for review August 15, 2025 13:32

phip1611 force-pushed the core-net-v2 branch from 85838ce to 1b7a7be Compare August 15, 2025 13:38

phip1611 mentioned this pull request Aug 15, 2025

cargo xtask improvements #1741

Closed

2 tasks

phip1611 force-pushed the core-net-v2 branch from 1b7a7be to 2ecc76c Compare August 15, 2025 13:53

phip1611 changed the title ~~[WIP] uefi-raw: move types to new net module, improve convenience~~ uefi-raw: move types to new net module, improve convenience Aug 16, 2025

phip1611 force-pushed the core-net-v2 branch from 2ecc76c to a76f20e Compare August 16, 2025 11:40

phip1611 requested a review from nicholasbishop August 16, 2025 11:42

phip1611 force-pushed the core-net-v2 branch from a76f20e to 1f7cd1b Compare August 16, 2025 11:43

phip1611 force-pushed the core-net-v2 branch 2 times, most recently from c2d44b0 to 24d5443 Compare August 19, 2025 08:30

phip1611 force-pushed the core-net-v2 branch 8 times, most recently from 411d16e to f2b5198 Compare August 19, 2025 08:58

phip1611 mentioned this pull request Aug 22, 2025

uefi-raw: move types to net module #1747

Merged

2 tasks

phip1611 marked this pull request as draft August 22, 2025 07:41

phip1611 force-pushed the core-net-v2 branch 2 times, most recently from aa1b362 to 4261a10 Compare August 23, 2025 12:52

phip1611 changed the title ~~uefi-raw: move types to new net module, improve convenience~~ [WIP] uefi-raw: move types to new net module, improve convenience Aug 23, 2025

phip1611 mentioned this pull request Aug 23, 2025

uefi-raw: various small net improvements #1748

Merged

2 tasks

phip1611 self-assigned this Aug 23, 2025

phip1611 force-pushed the core-net-v2 branch from 4261a10 to 0d4fe50 Compare August 25, 2025 15:56

phip1611 changed the title ~~[WIP] uefi-raw: move types to new net module, improve convenience~~ uefi-raw: improve convenience of net types Aug 25, 2025

phip1611 marked this pull request as ready for review August 25, 2025 15:57

phip1611 force-pushed the core-net-v2 branch from 0d4fe50 to 3bfe5a2 Compare August 25, 2025 16:03

nicholasbishop reviewed Aug 26, 2025

View reviewed changes

phip1611 force-pushed the core-net-v2 branch from 3bfe5a2 to 69b3116 Compare September 7, 2025 14:47

phip1611 requested a review from nicholasbishop September 7, 2025 14:48

phip1611 force-pushed the core-net-v2 branch from 69b3116 to d613641 Compare September 7, 2025 14:49

phip1611 added 2 commits September 7, 2025 16:49

uefi-raw: small code improvements for IpAddress

864620d

phip1611 force-pushed the core-net-v2 branch from d613641 to 684c89f Compare September 7, 2025 14:51

uefi-raw: add convenient From impls + integration with core::net

b7bc97f

- added missing conversions between core::net types and the uefi-raw net types - added missing conversions for "typical byte arrays"

phip1611 force-pushed the core-net-v2 branch from 684c89f to 6e6a2a0 Compare September 7, 2025 15:02

phip1611 added 2 commits September 7, 2025 17:02

uefi-raw: add convenient into_* helpers

a657688

uefi-raw: add unit test for typical high-level net API usage

6e6a2a0

Uh oh!

uefi-raw: improve convenience of net types #1699

Are you sure you want to change the base?

uefi-raw: improve convenience of net types #1699

Uh oh!

Conversation

phip1611 commented Jun 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Steps to Undraft

Checklist

Uh oh!

Uh oh!

phip1611 commented Jul 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

phip1611 commented Aug 17, 2025

Uh oh!

nicholasbishop commented Aug 18, 2025

Uh oh!

phip1611 commented Aug 19, 2025

Uh oh!

nicholasbishop commented Aug 21, 2025

Uh oh!

phip1611 commented Aug 25, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

phip1611 Sep 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

phip1611 commented Sep 7, 2025

Uh oh!

Uh oh!

phip1611 commented Jun 15, 2025 •

edited

Loading

phip1611 commented Jul 9, 2025 •

edited

Loading

phip1611 Sep 7, 2025 •

edited

Loading