Documentation for speed_in_khz needs updating with its restrictions

[xross]

Not all values of unsigned speed_in_khz can be achieved using the xcore divider. E.g. using 20000 will result in a 12.5MHz clock due to:

unsigned d = (XS1_TIMER_KHZ + 4_speed_in_khz - 1)/(4_speed_in_khz);
configure_clock_ref(cb0, d);

The speed is essentially a "maximum". This needs to be documented as causing confusion with users/support tickets where the data-rate is not as expected.

Suggest even a build warning should be emitted at build time,

[rlsosborne]

Rather than using configure_clock_ref, the code could use configure_clock_rate_at_most

configure_clock_rate_at_most(clk, speed_in_khz * 1000, 1);

configure_clock_rate_at_most will use either the divided down reference clock or the divided down processor clock, whichever gets closest to the desired frequency. For example with a 500MHz part, it would divide the processor clock by 26 for a clock frequency of 19.23MHz. While this still isn't exact (and there would still be a need to document speed_in_khz as being a maximum frequency) , it is quite a bit closer.

[xross]

configure_clock_rate_at_most(clk, speed_in_khz * 1000, 1);

Doesn't work,

configure_clock_rate_at_most(clk, speed_in_khz, 1000);

is fine.

[rlsosborne]

Quite right, sorry for the confusion - I forgot that configure_clock_rate_at_most wants a frequency in MHz, not a frequency in Hz.

[xross]

I think it actually needs to be:

 configure_clock_rate_at_most(cb0, speed_in_khz * 2, 1000);

Since the ports are clocked from this clock, so there is an implicit divide of 2.

[ed-xmos]

I am thinking about making the get_actual_speed function part of the public API. It is common for SPI dividers to get a bit granular at the top end so is good to know (from the API) what is actually being driven speed-wise