embassy_rp: improve calculate_pio_clock_divider

[ericseppanen]

The current implementation of calculate_pio_clock_divider only computes an integer divider, which is a missed opportunity since the return type explicitly represents an 8-bit fractional part.

This implementation ensures that the fractional part of the clock divider is accurately calculated. It uses additional u32 division/mod operations; I think this is preferable to one u64 division, but that would work as well. I don't have a great understanding of how division works on rp2040, so any advice is welcome.

Other changes:

• Add additional asserts to catch out-of-bounds results.
• Make the version that accepts the system clock as a parameter const and public, so if anyone wants to hardcode the system frequency they can avoid any runtime computation.
• Remove the inline attributes because the function has grown quite a bit.
• Add unit tests to verify that the math works.

Fixes #5048.

[ericseppanen]

I hit compile errors with defmt::assert! in the const fn. Result by using core::assert without a string literal instead; not sure if that's the right approach. I could add an error enum, or split this into three functions (runtime-with-defmt, const-without-defmt, and math-inner), but maybe that would be overkill?

Or I could just drop the public const fn idea entirely, and this will always be calculated at runtime.

[katazina0]

I hit compile errors with defmt::assert! in the const fn. Result by using core::assert without a string literal instead; not sure if that's the right approach. I could add an error enum, or split this into three functions (runtime-with-defmt, const-without-defmt, and math-inner), but maybe that would be overkill?

Or I could just drop the public const fn idea entirely, and this will always be calculated at runtime.

Could two functions work, one const and one not? That way things could be asserted at compile time and if needed, at runtime too. Would probably be a good idea to gate defmt asserts behind the "defmt" feature flag as well.

[ericseppanen]

Could two functions work, one const and one not?

Perhaps, with some code repetition. There are many possible permutations, so I'm hoping to hear what style the maintainers prefer.

Would probably be a good idea to gate defmt asserts behind the "defmt" feature flag as well.

This is already handled by embassy_rp's assert macro:

embassy/embassy-rp/src/fmt.rs

Lines 10 to 19 in c33a861

	macro_rules! assert {
	($($x:tt)*) => {
	{
	#[cfg(not(feature = "defmt"))]
	::core::assert!($($x)*);
	#[cfg(feature = "defmt")]
	::defmt::assert!($($x)*);
	}
	};
	}