[PATCH] drm/i915/cdclk: Document CDCLK components

[Gustavo Sousa]

Quoting Ville Syrjälä (2024-02-19 17:12:17-03:00)
>On Fri, Feb 16, 2024 at 01:45:25PM -0300, Gustavo Sousa wrote:
>> Improve documentation by giving an overview of the components involved
>> in the generation of the CDCLK.
>> 
>> Signed-off-by: Gustavo Sousa <gustavo.sousa at intel.com>
>
>Reviewed-by: Ville Syrjälä <ville.syrjala at linux.intel.com>
>
>> ---
>>  drivers/gpu/drm/i915/display/intel_cdclk.c | 25 ++++++++++++++++++++++
>>  1 file changed, 25 insertions(+)
>> 
>> diff --git a/drivers/gpu/drm/i915/display/intel_cdclk.c b/drivers/gpu/drm/i915/display/intel_cdclk.c
>> index 30dae4fef6cb..ef1660f94e46 100644
>> --- a/drivers/gpu/drm/i915/display/intel_cdclk.c
>> +++ b/drivers/gpu/drm/i915/display/intel_cdclk.c
>> @@ -63,6 +63,31 @@
>>   * DMC will not change the active CDCLK frequency however, so that part
>>   * will still be performed by the driver directly.
>>   *
>> + * There are multiple components involved in the generation of the CDCLK
>> + * frequency:

Looks like we need a blank line here to get `make htmldocs` to parse
this without warnings. There is a similar fix[1] that's currently
in-flight, which also adds blank lines between list items, but that
doesn't seem to be strictly necessary.

Let's wait to see how that series gets applied so that we make a fix
that is consistent with that one.

[1]: https://patchwork.freedesktop.org/series/130159/

--
Gustavo Sousa

>> + * - We have the CDCLK PLL, which generates an output clock based on a
>> + *   reference clock and a ratio parameter.
>> + * - The CD2X Divider, which divides the output of the PLL based on a
>> + *   divisor selected from a set of pre-defined choices.
>> + * - The CD2X Squasher, which further divides the output based on a
>> + *   waveform represented as a sequence of bits where each zero
>> + *   "squashes out" a clock cycle.
>> + * - And, finally, a fixed divider that divides the output frequency by 2.
>> + *
>> + * As such, the resulting CDCLK frequency can be calculated with the
>> + * following formula:
>> + *
>> + *     cdclk = vco / cd2x_div / (sq_len / sq_div) / 2
>> + *
>> + * , where vco is the frequency generated by the PLL; cd2x_div
>> + * represents the CD2X Divider; sq_len and sq_div are the bit length
>> + * and the number of high bits for the CD2X Squasher waveform, respectively;
>> + * and 2 represents the fixed divider.
>> + *
>> + * Note that some older platforms do not contain the CD2X Divider
>> + * and/or CD2X Squasher, in which case we can ignore their respective
>> + * factors in the formula above.
>> + *
>>   * Several methods exist to change the CDCLK frequency, which ones are
>>   * supported depends on the platform:
>>   * - Full PLL disable + re-enable with new VCO frequency. Pipes must be inactive.
>> -- 
>> 2.43.0
>
>-- 
>Ville Syrjälä
>Intel