Re: [PATCH 01/14] staging: clocking-wizard: Add principles of operation

[Michal Simek <michal.simek@xilinx.com>]

Hi James,

On 11.5.2018 09:31, James Kelly wrote:
> Hi Michal,
> 
> On 11 May 2018 at 16:04, Michal Simek <michal.simek@xilinx.com> wrote:
> 
>> Hi,
>>
>> On 7.5.2018 03:20, James Kelly wrote:
>>> Add a description for how the Xilinx Clocking Wizard IP works to guide
>>> subsequent patches.
>>>
>>> Signed-off-by: James Kelly <jamespeterkelly@gmail.com>
>>> ---
>>>  .../clocking-wizard/clk-xlnx-clock-wizard.c        | 52
>> ++++++++++++++++++++++
>>>  1 file changed, 52 insertions(+)
>>>
>>> diff --git a/drivers/staging/clocking-wizard/clk-xlnx-clock-wizard.c
>> b/drivers/staging/clocking-wizard/clk-xlnx-clock-wizard.c
>>> index cae7e6e695b0..babbed42f96d 100644
>>> --- a/drivers/staging/clocking-wizard/clk-xlnx-clock-wizard.c
>>> +++ b/drivers/staging/clocking-wizard/clk-xlnx-clock-wizard.c
>>> @@ -5,6 +5,58 @@
>>>   *  Copyright (C) 2013 - 2014 Xilinx
>>>   *
>>>   *  Sören Brinkmann <soren.brinkmann@xilinx.com>
>>> + *
>>> + * Principles of Operation:
>>> + *
>>> + * The Xilinx clocking wizard IP implements a clock complex that can be
>>> + * modelled as a collection of dividers and a PLL multiplier arranged in
>>> + * the following configuration:
>>> + *
>>> + *                         +-------------------------------> clk_fbout
>>> + *                         |
>>> + *          fin  +-----+   |    +-----+  vco   +-----+
>>> + * clk_in1 ----->| DIV |---+--->| PLL |---+--->| DIV |-----> clk_out1
>>> + *               +-----+  pfd   +-----+   |    +-----+
>>> + *                                        |
>>> + *                                        |    +-----+
>>> + *                                        +--->| DIV |-----> clk_out2
>>> + *                                        |    +-----+
>>> + *                                        |
>>> + *                                        |      ...
>>> + *                                        |    +-----+
>>> + *                                        +--->| DIV |-----> clk_outn
>>> + *                                             +-----+
>>> + *
>>> + * Each divider and the PLL multiplier correspond to a distinct common
>>> + * clock framework struct clk.
>>> + *
>>> + * The number of clock outputs depends the clock primitive type (MMCM
>> or PLL)
>>> + * and FPGA family and can range from 2 to 7, not including clk_fbout.
>>> + * Xilinx documentation is inconsistent in the numbering of these
>> outputs.
>>> + * The clocking wizard uses 1 thru n whereas the clocking primitives
>> wrapped
>>> + * by the wizard use 0 through n-1.
>>> + *
>>> + * This driver publishes the n output clocks in the device tree using
>> addresses
>>> + * 0 through n-1.  The remaining two clocks (DIV and PLL) are not
>> published in
>>> + * the device tree but can be obtained using calls to clk_get_parent on
>> one
>>> + * of the output clocks.
>>> + *
>>> + * There are constraints on the input rate (fin), phase-frequency
>>> + * detector rate (pfd), the voltage controlled oscillator rate (vco)
>>> + * and output clock rates. These depend on FPGA family, clock primitive
>> type
>>> + * and chip speed grade.
>>> + *
>>> + * The available ratios for the dividers and PLL multiplier depend on
>>> + * FPGA family and clock primitive type.  MMCM primitves support
>> fractional
>>> + * ratios for the PLL multipler and first output divider, whereas PLL
>>> + * primitives do not.  Fractional ratios have a resolution of 0.125
>> (1/8) or 3
>>> + * fractional bits.
>>> + *
>>> + * Clock ratios can be dynamically changed via two different register
>>> + * interfaces depending on how the "Write to DRP" configuration option
>> is set
>>> + * when the clocking wizard IP is customized.  This driver requires that
>>> + * the "Write to DRP" configuration option is disabled in customization
>>> + * as it currently uses the higher-level of the two register interfaces.
>>>   */
>>>
>>>  #include <linux/platform_device.h>
>>>
>>
>> There are some double spaces in the text without any reason.
>>
>>
>> Thanks,
>> Michal
>>
>>
> Thanks for the feedback.
> 
> Actually they are there for a reason ... back when I learned to type on
> typewriters
> it was normal to use double spaces between sentences.  I sometimes fall
> back into
> that habit when using monospace fonts because I am used to that look.
> 
> However, I'm happy to change to the modern convention as it would appear the
> the world has moved on - at least according to Wikipedia:
> https://en.wikipedia.org/wiki/Sentence_spacing.
> 
> Will be fixed in version 2.

I am not a person to judge what's the right style because I am not
native speaker. But I am parsing all double spaces and spaces
before/after tabs because this is quite common issue that people have
incorrect editor setting.

Thanks,
Michal