rust: clk: document overflow panics in `Hertz` constructors
Subsystems (2)
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.
--- rust/kernel/clk.rs | 15 +++++++++++++++ 1 file changed, 15 insertions(+)
rust/kernel/clk.rs +15 -0
@@ -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
Quoted 11 lines · Georgios Androutsopoulos
Hertz::from_khz(),from_mhz()andfrom_ghz()multiply their argument by 1_000, 1_000_000 and 1_000_000_000 respectively without checking for overflow. WhenCONFIG_RUST_OVERFLOW_CHECKSis enabled, each panics once its argument exceedsc_ulong::MAXdivided 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
# Panicssections stating the bound for each unit.Fixes d01d70205601 ("rust: clk: Add initial abstractions")Signed-off-by Georgios Androutsopoulos <[email protected]>
As we just discussed at Kangrejos we might want to harden these a bit, but meanwhile documenting the behavior is indeed a good idea.
Brian Masney
Acked-byQuoted 10 lines · Alexandre Courbot
Quoted 9 lines · Georgios Androutsopoulos
Hertz::from_khz(),from_mhz()andfrom_ghz()multiply their argument by 1_000, 1_000_000 and 1_000_000_000 respectively without checking for overflow. WhenCONFIG_RUST_OVERFLOW_CHECKSis enabled, each panics once its argument exceedsc_ulong::MAXdivided 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
# Panicssections stating the bound for each unit.
Quoted 7 lines
Quoted 2 lines
Fixes d01d70205601 ("rust: clk: Add initial abstractions")Signed-off-by Georgios Androutsopoulos <[email protected]>As we just discussed at Kangrejos we might want to harden these a bit, but meanwhile documenting the behavior is indeed a good idea.
Reviewed-by Alexandre Courbot <[email protected]>
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
Alice Ryhl
reviewerQuoted 18 lines · Brian Masney
Quoted 16 lines · Alexandre Courbot
Quoted 11 lines · Georgios Androutsopoulos
Hertz::from_khz(),from_mhz()andfrom_ghz()multiply their argument by 1_000, 1_000_000 and 1_000_000_000 respectively without checking for overflow. WhenCONFIG_RUST_OVERFLOW_CHECKSis enabled, each panics once its argument exceedsc_ulong::MAXdivided 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
# Panicssections stating the bound for each unit.Fixes d01d70205601 ("rust: clk: Add initial abstractions")Signed-off-by Georgios Androutsopoulos <[email protected]>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
Reviewed-by Alexandre Courbot <[email protected]>Acked-by Brian Masney <[email protected]>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
Miguel Ojeda
Acked-byQuoted 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
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
MAINTAINERSentries 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
Acked-by Miguel Ojeda <[email protected]>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
Brian Masney
AppliedQuoted 1 line · Georgios Androutsopoulos
rust: clk: document overflow panics in
Hertzconstructors
Applied, thanks!
[1/1] rust: clk: document overflow panics in Hertz constructors
commit: 45a68afbd4b632538a0956ba783fca45b8ceb446
Best regards,
Signature · 1 line
Brian Masney <[email protected]>