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

[Damien Hedde <damien.hedde@greensocs.com>]

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;

I think I've put ``CLOCK`` in uppercase because, in practical, we only
use the upper case macro.
> #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*.

Thanks,
Damien