From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:43697) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bUW0M-0005OG-Uq for qemu-devel@nongnu.org; Tue, 02 Aug 2016 05:29:00 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1bUW0H-0003K3-8W for qemu-devel@nongnu.org; Tue, 02 Aug 2016 05:28:53 -0400 Received: from greensocs.com ([193.104.36.180]:57433) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bUW09-0003Ia-Ub for qemu-devel@nongnu.org; Tue, 02 Aug 2016 05:28:49 -0400 References: <1465835259-21449-1-git-send-email-fred.konrad@greensocs.com> <1465835259-21449-6-git-send-email-fred.konrad@greensocs.com> From: KONRAD Frederic Message-ID: <216c4a07-ec61-96df-7145-1f19f4355162@greensocs.com> Date: Tue, 2 Aug 2016 11:29:19 +0200 MIME-Version: 1.0 In-Reply-To: Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: quoted-printable Subject: Re: [Qemu-devel] [RFC PATCH 05/11] docs: add qemu-clock documentation List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: Alistair Francis Cc: "qemu-devel@nongnu.org Developers" , Edgar Iglesias , Peter Maydell , Mark Burton Le 29/06/2016 =C3=A0 02:38, Alistair Francis a =C3=A9crit : > On Mon, Jun 13, 2016 at 9:27 AM, wrote: >> From: KONRAD Frederic >> >> This adds the qemu-clock documentation. >> >> Signed-off-by: KONRAD Frederic >> --- >> docs/clock.txt | 112 +++++++++++++++++++++++++++++++++++++++++++++++= ++++++++++ >> 1 file changed, 112 insertions(+) >> create mode 100644 docs/clock.txt >> >> diff --git a/docs/clock.txt b/docs/clock.txt >> new file mode 100644 >> index 0000000..f4ad4c8 >> --- /dev/null >> +++ b/docs/clock.txt >> @@ -0,0 +1,112 @@ >> + >> +What is a QEMU_CLOCK >> +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D >> + >> +A QEMU_CLOCK is a QOM Object developed for the purpose of modeling a = clock tree >> +with QEMU. >> + >> +It only simulates the clock by keeping a copy of the current frequenc= y and >> +doesn't model the signal itself such as pin toggle or duty cycle. >> + >> +It allows to model the impact of badly configured PLL, clock source s= election >> +or disabled clock on the models. >> + >> +Bounding the clock together to create a tree >> +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D >> + >> +In order to create a clock tree with QEMU_CLOCK two or more clock mus= t be bound >> +together. Let's say there are two clocks clk_a and clk_b: >> +Using qemu_clk_bound(clk_a, clk_b) will bound clk_a and clk_b. >> + >> +Binding two qemu-clk together is a unidirectional link which means th= at changing >> +the rate of clk_a will propagate to clk_b and not the opposite. The b= ound >> +process automatically refresh clk_b rate. >> + >> +Clock can be bound and unbound during execution for modeling eg: a cl= ock >> +selector. >> + >> +A clock can drive more than one other clock. eg with this code: >> +qemu_clk_bound(clk_a, clk_b); >> +qemu_clk_bound(clk_a, clk_c); >> + >> +A clock rate change one clk_a will propagate to clk_b and clk_c. >> + >> +Implementing a callback on a rate change >> +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D >> + >> +The function prototype is the following: >> +typedef float (*qemu_clk_rate_change_cb)(void *opaque, float rate); >> + >> +It's main goal is to modify the rate before it's passed to the next c= locks in >> +the tree. >> + >> +eg: for a 4x PLL the function will be: >> +float qemu_clk_rate_change_cb(void *opaque, float rate) >> +{ >> + return 4.0 * rate; >> +} >> + >> +To set the callback for the clock: >> +void qemu_clk_set_callback(qemu_clk clk, qemu_clk_on_rate_update_cb c= b, >> + void *opaque); >> +can be called. >> + >> +NOTE: It's not recommended that the clock is driven by more than one = clock as it >> +would mean that we don't know which clock trigger the callback. > Would this not be something worth knowing? I think it shouldn't be the case as connecting two inputs on an output=20 doesn't mean anything? Maybe worth adding something to ensure it can't happen and modify=20 qemu_clk_bind_clock to automatically unbind the old clock? Fred > > Thanks, > > Alistair > >> +The rate update process >> +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D >> + >> +The rate update happen in this way: >> +When a model wants to update a clock frequency (eg: based on a regist= er change >> +or something similar) it will call qemu_clk_update_rate(..) on the cl= ock: >> + * The callback associated to the clock is called with the new rate. >> + * qemu_clk_update_rate(..) is then called on all bound clock with t= he >> + value returned by the callback. >> + >> +NOTE: When no callback is attached the clock qemu_clk_update_rate(..)= is called >> +with the unmodified rate. >> + >> +Attaching a QEMU_CLOCK to a DeviceState >> +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D >> + >> +Attaching a qemu-clk to a DeviceState is required to be able to get t= he clock >> +outside the model through qemu_clk_get_pin(..). >> + >> +It is also required to be able to print the clock and its rate with i= nfo qtree. >> +For example: >> + >> + type System >> + dev: xlnx.zynqmp_crf, id "" >> + gpio-out "sysbus-irq" 1 >> + gpio-out "RST_A9" 4 >> + qemu-clk "dbg_trace" 0.0 >> + qemu-clk "vpll_to_lpd" 625000000.0 >> + qemu-clk "dp_stc_ref" 0.0 >> + qemu-clk "dpll_to_lpd" 12500000.0 >> + qemu-clk "acpu_clk" 0.0 >> + qemu-clk "pcie_ref" 0.0 >> + qemu-clk "topsw_main" 0.0 >> + qemu-clk "topsw_lsbus" 0.0 >> + qemu-clk "dp_audio_ref" 0.0 >> + qemu-clk "sata_ref" 0.0 >> + qemu-clk "dp_video_ref" 71428568.0 >> + qemu-clk "vpll_clk" 2500000000.0 >> + qemu-clk "apll_to_lpd" 12500000.0 >> + qemu-clk "dpll_clk" 50000000.0 >> + qemu-clk "gpu_ref" 0.0 >> + qemu-clk "aux_refclk" 0.0 >> + qemu-clk "video_clk" 27000000.0 >> + qemu-clk "gdma_ref" 0.0 >> + qemu-clk "gt_crx_ref_clk" 0.0 >> + qemu-clk "dbg_fdp" 0.0 >> + qemu-clk "apll_clk" 50000000.0 >> + qemu-clk "pss_alt_ref_clk" 0.0 >> + qemu-clk "ddr" 0.0 >> + qemu-clk "pss_ref_clk" 50000000.0 >> + qemu-clk "dpdma_ref" 0.0 >> + qemu-clk "dbg_tstmp" 0.0 >> + mmio 00000000fd1a0000/000000000000010c >> + >> +This way a DeviceState can have multiple clock input or output. >> + >> -- >> 2.5.5 >> >>