Update dma.h (Fixes #1677) (Inline docs only) #1678

Merged

myklemykle merged 1 commit from patch-1 into develop

2024-06-04 20:00:55 -05:00

myklemykle commented

2024-03-24 22:46:35 -05:00

(Migrated from github.com)

I think It's important to be clear that how DMA timers are scaled on RP2040 is the opposite of how PWM clocks are scaled.

Specifically, pwm_config_set_clkdiv_int_frac() lets the user specifiy a fractional divider, but dma_timer_set_fraction() lets the user specify a fractional multiplier. So for instance the PWM divider is only effective if it's more than 1, while the DMA multiplier is only effective if it's less than 1.

This patch updates the inline doc of dma_timer_set_fraction() to reflect that it specifies a multiplier, not a divider, of clk_sys.

I think It's important to be clear that how DMA timers are scaled on RP2040 is the opposite of how PWM clocks are scaled. Specifically, pwm_config_set_clkdiv_int_frac() lets the user specifiy a fractional divider, but dma_timer_set_fraction() lets the user specify a fractional multiplier. So for instance the PWM divider is only effective if it's more than 1, while the DMA multiplier is only effective if it's less than 1. This patch updates the inline doc of dma_timer_set_fraction() to reflect that it specifies a multiplier, not a divider, of clk_sys.

lurch commented

2024-03-25 04:52:01 -05:00

(Migrated from github.com)

I think if this was called a "multiplier", that would imply that the DMA timer can run faster than the system-clock, but it can't, so IMHO this is still a "divider".
Page 118 of https://datasheets.raspberrypi.com/rp2040/rp2040-datasheet.pdf says "The pacing timer produces TREQ assertions at a rate set by ((X/Y) * sys_clk). This equation is evaluated every sys_clk cycles and therefore can only generate TREQs at a rate of 1 per sys_clk (i.e. permanent TREQ) or less."

OTOH, perhaps it makes sense for dma_timer_set_fraction to assert that numerator <= denominator ? 🤷

I think if this was called a "multiplier", that would imply that the DMA timer can run _faster_ than the system-clock, but it can't, so IMHO this is still a "divider". Page 118 of https://datasheets.raspberrypi.com/rp2040/rp2040-datasheet.pdf says "The pacing timer produces TREQ assertions at a rate set by ((X/Y) * sys_clk). This equation is evaluated every sys_clk cycles and therefore can only generate TREQs at a rate of 1 per sys_clk (i.e. permanent TREQ) or less." OTOH, _perhaps_ it makes sense for `dma_timer_set_fraction` to assert that `numerator <= denominator` ? :shrug:

myklemykle commented

2024-03-25 13:20:20 -05:00

(Migrated from github.com)

OK, I get now that those are the engineering flavors of those words, more than the math flavors. But in both cases the divider, really, is a piece of hardware in a clock; the specified fraction configures that divider. IMO "Set the divider" makes it sound like the value you're passing is itself the divider, and will be used to divide in a math sense. Maybe "Configure the divider" is better?

I just think it should be as clear as possible that PWM and DMA use opposite schemes for configuring clock dividers with fractions.

myklemykle commented

2024-03-25 13:22:09 -05:00

(Migrated from github.com)

OTOH, perhaps it makes sense for dma_timer_set_fraction to assert that numerator <= denominator ? 🤷

Seems sensible. And the opposite for pwm_config_set_clkdiv_int_frac .

> OTOH, _perhaps_ it makes sense for `dma_timer_set_fraction` to assert that `numerator <= denominator` ? 🤷 Seems sensible. And the opposite for `pwm_config_set_clkdiv_int_frac` .

lurch commented

2024-03-25 13:38:26 -05:00

(Migrated from github.com)

And the opposite for pwm_config_set_clkdiv_int_frac .

That already checks that integer >= 1 🙂

> And the opposite for `pwm_config_set_clkdiv_int_frac` . That [already checks](https://github.com/raspberrypi/pico-sdk/blob/master/src/rp2_common/hardware_pwm/include/hardware/pwm.h#L135) that `integer >= 1` :slightly_smiling_face:

kilograham (Migrated from github.com) approved these changes

2024-06-04 20:00:48 -05:00