Skip to contentSkip to conversation

rust: clk: document overflow panics in `Hertz` constructors

PATCH Applied Georgios Androutsopoulos 5 participants 7 messages Sep 8 – Sep 23

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

PATCH 1/1 rust: clk: document overflow panics in `Hertz` constructors

Hertz::from_khz(), from_mhz() and from_ghz() multiply their argument by 1_000, 1_000_000 and 1_000_000_000 respectively without checking for overflow. When CONFIG_RUST_OVERFLOW_CHECKS is enabled, each panics once its argument exceeds c_ulong::MAX divided by that factor. None of the three documents this. The panic occurs only at runtime, when the argument is not a constant expression.

Add the missing # Panics sections stating the bound for each unit.

Fixes d01d70205601 ("rust: clk: Add initial abstractions")
---
 rust/kernel/clk.rs | 15 +++++++++++++++
 1 file changed, 15 insertions(+)
rust/kernel/clk.rs +15 -0
index 7abbd0767d8c..f04f5c4a03d6 100644
@@ -35,16 +35,31 @@ impl Hertz {
     const GHZ_TO_HZ: c_ulong = 1_000_000_000;
 
     /// Create a new instance from kilohertz (kHz)
+    ///
+    /// # Panics
+    ///
+    /// Panics if `CONFIG_RUST_OVERFLOW_CHECKS` is enabled and `khz` is greater
+    /// than `c_ulong::MAX / 1_000`.
     pub const fn from_khz(khz: c_ulong) -> Self {
         Self(khz * Self::KHZ_TO_HZ)
     }
 
     /// Create a new instance from megahertz (MHz)
+    ///
+    /// # Panics
+    ///
+    /// Panics if `CONFIG_RUST_OVERFLOW_CHECKS` is enabled and `mhz` is greater
+    /// than `c_ulong::MAX / 1_000_000`.
     pub const fn from_mhz(mhz: c_ulong) -> Self {
         Self(mhz * Self::MHZ_TO_HZ)
     }
 
     /// Create a new instance from gigahertz (GHz)
+    ///
+    /// # Panics
+    ///
+    /// Panics if `CONFIG_RUST_OVERFLOW_CHECKS` is enabled and `ghz` is greater
+    /// than `c_ulong::MAX / 1_000_000_000`.
     pub const fn from_ghz(ghz: c_ulong) -> Self {
         Self(ghz * Self::GHZ_TO_HZ)
     }

base-commit: 73e3f0710014fe6d4ed98cfc02292f6121db7558

Signature · 1 line
2.47.3
reviewer Reviewed-by on v1 1/1
#1 lore raw
Quoted 11 lines · Georgios Androutsopoulos

Hertz::from_khz(), from_mhz() and from_ghz() multiply their argument by 1_000, 1_000_000 and 1_000_000_000 respectively without checking for overflow. When CONFIG_RUST_OVERFLOW_CHECKS is enabled, each panics once its argument exceeds c_ulong::MAX divided by that factor. None of the three documents this. The panic occurs only at runtime, when the argument is not a constant expression.

Add the missing # Panics sections stating the bound for each unit.

Fixes d01d70205601 ("rust: clk: Add initial abstractions")

As we just discussed at Kangrejos we might want to harden these a bit, but meanwhile documenting the behavior is indeed a good idea.

Acked-by
#2 lore raw
Quoted 10 lines · Alexandre Courbot
Quoted 9 lines · Georgios Androutsopoulos

Hertz::from_khz(), from_mhz() and from_ghz() multiply their argument by 1_000, 1_000_000 and 1_000_000_000 respectively without checking for overflow. When CONFIG_RUST_OVERFLOW_CHECKS is enabled, each panics once its argument exceeds c_ulong::MAX divided by that factor. None of the three documents this. The panic occurs only at runtime, when the argument is not a constant expression.

Add the missing # Panics sections stating the bound for each unit.

Quoted 7 lines
Quoted 2 lines
Fixes d01d70205601 ("rust: clk: Add initial abstractions")

As we just discussed at Kangrejos we might want to harden these a bit, but meanwhile documenting the behavior is indeed a good idea.

I assume this will go through the rust tree? If not, I'm happy to take it through the clk tree, assuming the rust devs are happy with this.

Brian

reviewer
#3 lore raw
Quoted 18 lines · Brian Masney
Quoted 16 lines · Alexandre Courbot
Quoted 11 lines · Georgios Androutsopoulos

Hertz::from_khz(), from_mhz() and from_ghz() multiply their argument by 1_000, 1_000_000 and 1_000_000_000 respectively without checking for overflow. When CONFIG_RUST_OVERFLOW_CHECKS is enabled, each panics once its argument exceeds c_ulong::MAX divided by that factor. None of the three documents this. The panic occurs only at runtime, when the argument is not a constant expression.

Add the missing # Panics sections stating the bound for each unit.

Fixes d01d70205601 ("rust: clk: Add initial abstractions")

As we just discussed at Kangrejos we might want to harden these a bit, but meanwhile documenting the behavior is indeed a good idea.

Quoted 6 lines
Quoted 1 line

I assume this will go through the rust tree? If not, I'm happy to take it through the clk tree, assuming the rust devs are happy with this.

My understanding is that the "default" way patches land is that the subsystem also takes Rust patches related to the subsystem, and that the rust tree is a fallback tree.

Alice

Acked-by
#4 lore raw
Quoted 4 lines · Alice Ryhl

My understanding is that the "default" way patches land is that the subsystem also takes Rust patches related to the subsystem, and that the rust tree is a fallback tree.

Indeed, the idea on how we suggest setting up the MAINTAINERS entries is that, by default, maintainers keep control of both sides (they are the experts, after all) and that, hopefully, they get more involved on the Rust side etc.

It makes sense for reworking the subsystem, too, since it may happen that a rework on the C side may need adjustments on the Rust side etc.

The file is already under "COMMON CLK FRAMEWORK", so in this instance it seems fine.

Brian: in case you want it (but it wouldn't be needed!):

As Alexandre said, we may want to rework how these work (instead of panicking), but documenting helps for now (and whether this counts as a Fix or not is, I guess, up to what you usually do in your subsystem).

I hope that helps!

Cheers,
Miguel

#5 lore raw
Quoted 19 lines · Miguel Ojeda
Quoted 4 lines · Alice Ryhl

My understanding is that the "default" way patches land is that the subsystem also takes Rust patches related to the subsystem, and that the rust tree is a fallback tree.

Indeed, the idea on how we suggest setting up the MAINTAINERS entries is that, by default, maintainers keep control of both sides (they are the experts, after all) and that, hopefully, they get more involved on the Rust side etc.

It makes sense for reworking the subsystem, too, since it may happen that a rework on the C side may need adjustments on the Rust side etc.

The file is already under "COMMON CLK FRAMEWORK", so in this instance it seems fine.

Brian: in case you want it (but it wouldn't be needed!):

Quoted 8 lines

As Alexandre said, we may want to rework how these work (instead of panicking), but documenting helps for now (and whether this counts as a Fix or not is, I guess, up to what you usually do in your subsystem).

I hope that helps!

Sounds good, I'll pick this up.

Learning Rust is something that I want to start to do this coming Winter. I have an existing userspace project that I'm going to convert from python to rust.

Brian

Applied
#6 lore raw
In reply to Georgios Androutsopoulos
Quoted 1 line · Georgios Androutsopoulos

rust: clk: document overflow panics in Hertz constructors

Applied, thanks!

[1/1] rust: clk: document overflow panics in Hertz constructors

      commit: 45a68afbd4b632538a0956ba783fca45b8ceb446

Best regards,

Signature · 1 line
Brian Masney <[email protected]>