Re: [PATCH v9 5/9] docs/clocks: add device's clock documentation
On 4/17/20 5:52 PM, Peter Maydell wrote: > On Mon, 6 Apr 2020 at 14:53, Damien Hedde wrote: >> >> 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 >> Reviewed-by: Alistair Francis >> Reviewed-by: Edgar E. Iglesias > > I did an edit pass on this to address minor grammar/style > issues and some Sphinx syntax stuff (notably, using > "code-block:: c" renders nicer than a plain literal block). > Diff against this patch is below; it looks bigger than > you might expect because one of the changes was that I > rewrapped some of the paragraphs that were close to or > over 80 chars per line. Changes include the tweak Markus > asked for. > Thanks a lot, I thought that the maximum column size was 80, should we use a bit less in practice ? I'll apply this and do a respin along with your other patch 1 catcha bout the integer type in traces. Damien
Re: [PATCH v9 5/9] docs/clocks: add device's clock documentation
On Mon, 6 Apr 2020 at 14:53, Damien Hedde wrote: > > 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 > Reviewed-by: Alistair Francis > Reviewed-by: Edgar E. Iglesias I did an edit pass on this to address minor grammar/style issues and some Sphinx syntax stuff (notably, using "code-block:: c" renders nicer than a plain literal block). Diff against this patch is below; it looks bigger than you might expect because one of the changes was that I rewrapped some of the paragraphs that were close to or over 80 chars per line. Changes include the tweak Markus asked for. >From 995ea4cf6b815e3efe2dff93723d69b08418ff9b Mon Sep 17 00:00:00 2001 From: Peter Maydell Date: Fri, 17 Apr 2020 15:26:59 +0100 Subject: [PATCH] !fixup docs edit --- docs/devel/clocks.rst | 241 -- 1 file changed, 136 insertions(+), 105 deletions(-) diff --git a/docs/devel/clocks.rst b/docs/devel/clocks.rst index ead9f55561c..e5da28e2111 100644 --- a/docs/devel/clocks.rst +++ b/docs/devel/clocks.rst @@ -1,26 +1,27 @@ -Modeling a clock tree in QEMU -= +Modelling a clock tree in QEMU +== -What are clocks +What are clocks? + -Clocks are QOM objects developed for the purpose of modeling the +Clocks are QOM objects developed for the purpose of modelling 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``. +The object is *Clock* and its QOM name is ``clock`` (in C code, the macro +``TYPE_CLOCK``). Clocks are typically used with devices where they are used to model inputs -and outputs. They are created in a similar way as gpios. Inputs and outputs -of different devices can be connect together. +and outputs. They are created in a similar way to GPIOs. Inputs and outputs +of different devices can be connected together. -In these cases a Clock object is a child of a Device object but this is not -a requirement. Clocks can be independent of devices. For example it is possible -to create a clock outside of any device to model the main clock source of a -machine. +In these cases a Clock object is a child of a Device object, but this +is not a requirement. Clocks can be independent of devices. For +example it is possible to create a clock outside of any device to +model the main clock source of a machine. Here is an example of clocks:: @@ -45,40 +46,43 @@ Here is an example of clocks:: | +---+| +--+ -Clocks are defined in include/hw/clock.h header and device related functions -are defined in include/hw/qdev-clock.h header. +Clocks are defined in the ``include/hw/clock.h`` header and device +related functions are defined in the ``include/hw/qdev-clock.h`` +header. The clock state --- -The state of a clock is its period; it is stored as an integer representing -it in 2^-32ns unit. The special value of 0 is used to represent the clock being -inactive or gated. The clocks do not model the signal itself (pin toggling) -or other properties such as the duty cycle. +The state of a clock is its period; it is stored as an integer +representing it in units of 2 :sup:`-32` ns. The special value of 0 is used to +represent the clock being inactive or gated. The clocks do not model +the signal itself (pin toggling) or other properties such as the duty +cycle. -All clocks contain this state: outputs as well as inputs. It allows to fetch -the current period of a clock at any time. When a clock is updated, the -value is immediately propagated to all connected clocks in the tree. +All clocks contain this state: outputs as well as inputs. This allows +the current period of a clock to be fetched at any time. When a clock +is updated, the value is immediately propagated to all connected +clocks in the tree. -To ease interaction with clocks. Helpers with a unit suffix are defined for -every clock state setter or getter. They are: +To ease interaction with clocks, helpers with a unit suffix are defined for +every clock state setter or getter. The suffixes are: -- ``_ns`` for handling periods in nanosecond, -- ``_hz`` for handling frequencies in hertz. +- ``_ns`` for handling periods in nanoseconds +- ``_hz`` for handling frequencies in hertz The 0 period value is converted to 0 in hertz and vice versa. 0 always means that the clock is disabled. -Adding a new a clock - +Adding a new clock +-- Adding clocks to a device must be done during the init method of the Device instance. -To add an input clock to a device, the function
Re: [PATCH v9 5/9] docs/clocks: add device's clock documentation
Damien Hedde writes: > On 4/7/20 7:07 AM, Markus Armbruster wrote: >> Damien Hedde 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 >>> Reviewed-by: Alistair Francis >>> Reviewed-by: Edgar E. Iglesias >>> --- >>> 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 00..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 :)
Re: [PATCH v9 5/9] docs/clocks: add device's clock documentation
On 4/7/20 7:07 AM, Markus Armbruster wrote: > Damien Hedde 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 >> Reviewed-by: Alistair Francis >> Reviewed-by: Edgar E. Iglesias >> --- >> 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 00..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
Re: [PATCH v9 5/9] docs/clocks: add device's clock documentation
Damien Hedde 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 > Reviewed-by: Alistair Francis > Reviewed-by: Edgar E. Iglesias > --- > 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 00..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``? [...]
[PATCH v9 5/9] docs/clocks: add device's clock documentation
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 Reviewed-by: Alistair Francis Reviewed-by: Edgar E. Iglesias --- 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 00..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``. + +Clocks are typically used with devices where they are used to model inputs +and outputs. They are created in a similar way as gpios. Inputs and outputs +of different devices can be connect together. + +In these cases a Clock object is a child of a Device object but this is not +a requirement. Clocks can be independent of devices. For example it is possible +to create a clock outside of any device to model the main clock source of a +machine. + +Here is an example of clocks:: + ++-+ +--+ +--+ +| Clock 1 | | Device B | | Device C | +| | | +---+ +---+ | | +---+| +| |>>-+-->>|Clock 2| |Clock 3|>>--->>|Clock 6|| ++-+ | | | (in) | | (out) | | | | (in) || + | | +---+ +---+ | | +---+| + | |+---+ | +--+ + | ||Clock 4|>> + | || (out) | | +--+ + | |+---+ | | Device D | + | |+---+ | | +---+| + | ||Clock 5|>>--->>|Clock 7|| + | || (out) | | | | (in) || + | |+---+ | | +---+| + | +--+ | | + | | +---+| + +->>|Clock 8|| +| | (in) || +| +---+| ++--+ + +Clocks are defined in include/hw/clock.h header and device related functions +are defined in include/hw/qdev-clock.h header. + +The clock state +--- + +The state of a clock is its period; it is stored as an integer representing +it in 2^-32ns unit. The special value of 0 is used to represent the clock being +inactive or gated. The clocks do not model the signal itself (pin toggling) +or other properties such as the duty cycle. + +All clocks contain this state: outputs as well as inputs. It allows to fetch +the current period of a clock at any time. When a clock is updated, the +value is immediately propagated to all connected clocks in the tree. + +To ease interaction with clocks. Helpers with a unit suffix are defined for +every clock state setter or getter. They are: + +- ``_ns`` for handling periods in nanosecond, +- ``_hz`` for handling frequencies in hertz. + +The 0 period value is converted to 0 in hertz and vice versa. 0 always means +that the clock is disabled. + +Adding a new a clock + + +Adding clocks to a device must be done during the init method of the Device +instance. + +To add an input clock to a device, the function qdev_init_clock_in must be used. +It takes the name, a callback and an opaque parameter for the callback (this will +be explained in a following section below). +Output is more simple, only the name is required. Typically:: + +qdev_init_clock_in(DEVICE(dev), "clk_in", clk_in_callback, dev); +qdev_init_clock_out(DEVICE(dev), "clk_out"); + +Both functions return the created Clock pointer, which should be saved in the +device's state structure for further use. + +These objects will be automatically deleted by the QOM reference mechanism. + +Note that it is possible to create a static array describing clock inputs and +outputs. The function ``qdev_init_clocks()`` must be called with the array as +parameter to initialize the clocks: it has the same behaviour as calling the +``qdev_init_clock_in/out()`` for each clock in the array. To ease the array
