Re: [PATCH v9 5/9] docs/clocks: add device's clock documentation

[Markus Armbruster <armbru@redhat.com>]

Damien Hedde <damien.hedde@greensocs.com> writes:

> On 4/7/20 7:07 AM, Markus Armbruster wrote:
>> Damien Hedde <damien.hedde@greensocs.com> writes:
>> 
>>> Add the documentation about the clock inputs and outputs in devices.
>>>
>>> This is based on the original work of Frederic Konrad.
>>>
>>> Signed-off-by: Damien Hedde <damien.hedde@greensocs.com>
>>> Reviewed-by: Alistair Francis <alistair.francis@wdc.com>
>>> Reviewed-by: Edgar E. Iglesias <edgar.iglesias@xilinx.com>
>>> ---
>>> v9:
>>>  + fix a few typos (Alistair)
>>>
>>> v8:
>>>  + fix list indentation
>>>  + reduce title size
>>>
>>> v7:
>>>  + update ClockIn/Out types
>>>  + switch to rst format
>>> ---
>>>  docs/devel/clocks.rst | 360 ++++++++++++++++++++++++++++++++++++++++++
>>>  docs/devel/index.rst  |   1 +
>>>  2 files changed, 361 insertions(+)
>>>  create mode 100644 docs/devel/clocks.rst
>>>
>>> diff --git a/docs/devel/clocks.rst b/docs/devel/clocks.rst
>>> new file mode 100644
>>> index 0000000000..ead9f55561
>>> --- /dev/null
>>> +++ b/docs/devel/clocks.rst
>>> @@ -0,0 +1,360 @@
>>> +Modeling a clock tree in QEMU
>>> +=============================
>>> +
>>> +What are clocks
>>> +---------------
>>> +
>>> +Clocks are QOM objects developed for the purpose of modeling the
>>> +distribution of clocks in QEMU.
>>> +
>>> +They allow us to model the clock distribution of a platform and detect
>>> +configuration errors in the clock tree such as badly configured PLL, clock
>>> +source selection or disabled clock.
>>> +
>>> +The object is *Clock* and its QOM name is ``CLOCK``.
>> 
>> PATCH 1 has
>> 
>>     #define TYPE_CLOCK "clock"
>> 
>> Ignorant question: how is this related to *Clock* and ``CLOCK``?
>> 
>> [...]
>> 
>
> Hi Markus,
>
>
> *Clock* refer to the C type
>> typedef struct Clock Clock;

Okay.

> I think I've put ``CLOCK`` in uppercase because, in practical, we only
> use the upper case macro.

True for internal code, not true at external interfaces.

>> #define TYPE_CLOCK "clock"
>> #define CLOCK(obj) OBJECT_CHECK(Clock, (obj), TYPE_CLOCK)
>
> I'm not sure what is the right terminology here. Maybe I can replace by
> the following:
>
>> The QOM name of a clock is ``"clock"`` (or the macro ``TYPE_CLOCK``).
> The C type object is *Clock*.

Better.

Maybe (in C, the macro ``TYPE_CLOCK'') or (C macro ``TYPE_CLOCK'').
Your choice :)