Re: [PATCH] Documentation: Fix build error for cpu-idle-cooling.rst and client.rst
From: Randy Dunlap
Date: Sat Feb 01 2020 - 01:34:06 EST
On 1/31/20 10:25 PM, Changbin Du wrote:
> This fixed some errors and warnings in cpu-idle-cooling.rst and client.rst.
>
> Sphinx parallel build error:
> docutils.utils.SystemMessage: ...Documentation/driver-api/thermal/cpu-idle-cooling.rst:96: (SEVERE/4) Unexpected section title.
>
> Sphinx parallel build error:
> docutils.utils.SystemMessage: ...Documentation/driver-api/dmaengine/client.rst:155: (SEVERE/4) Unexpected section title.
>
> Signed-off-by: Changbin Du <changbin.du@xxxxxxxxx>
Hi,
This commit has been merged:
commit fe27f13d677ccd826386094df6977cfbc13ccf5e
Author: Randy Dunlap <rdunlap@xxxxxxxxxxxxx>
Date: Mon Jan 20 14:33:16 2020 -0800
Documentation: cpu-idle-cooling: fix a SEVERE docs build failure
Feel free to send patches against current Linus git tree.
Thanks.
> ---
> Documentation/driver-api/dmaengine/client.rst | 14 ++++++---
> .../driver-api/thermal/cpu-idle-cooling.rst | 29 +++++++++++--------
> Documentation/driver-api/thermal/index.rst | 1 +
> 3 files changed, 28 insertions(+), 16 deletions(-)
>
> diff --git a/Documentation/driver-api/dmaengine/client.rst b/Documentation/driver-api/dmaengine/client.rst
> index a9a7a3c84c63..2104830a99ae 100644
> --- a/Documentation/driver-api/dmaengine/client.rst
> +++ b/Documentation/driver-api/dmaengine/client.rst
> @@ -151,8 +151,8 @@ The details of these operations are:
> Note that callbacks will always be invoked from the DMA
> engines tasklet, never from interrupt context.
>
> - Optional: per descriptor metadata
> - ---------------------------------
> + **Optional: per descriptor metadata**
> +
> DMAengine provides two ways for metadata support.
>
> DESC_METADATA_CLIENT
> @@ -199,12 +199,15 @@ The details of these operations are:
> DESC_METADATA_CLIENT
>
> - DMA_MEM_TO_DEV / DEV_MEM_TO_MEM:
> +
> 1. prepare the descriptor (dmaengine_prep_*)
> construct the metadata in the client's buffer
> 2. use dmaengine_desc_attach_metadata() to attach the buffer to the
> descriptor
> 3. submit the transfer
> +
> - DMA_DEV_TO_MEM:
> +
> 1. prepare the descriptor (dmaengine_prep_*)
> 2. use dmaengine_desc_attach_metadata() to attach the buffer to the
> descriptor
> @@ -215,6 +218,7 @@ The details of these operations are:
> DESC_METADATA_ENGINE
>
> - DMA_MEM_TO_DEV / DEV_MEM_TO_MEM:
> +
> 1. prepare the descriptor (dmaengine_prep_*)
> 2. use dmaengine_desc_get_metadata_ptr() to get the pointer to the
> engine's metadata area
> @@ -222,7 +226,9 @@ The details of these operations are:
> 4. use dmaengine_desc_set_metadata_len() to tell the DMA engine the
> amount of data the client has placed into the metadata buffer
> 5. submit the transfer
> +
> - DMA_DEV_TO_MEM:
> +
> 1. prepare the descriptor (dmaengine_prep_*)
> 2. submit the transfer
> 3. on transfer completion, use dmaengine_desc_get_metadata_ptr() to get
> @@ -278,8 +284,8 @@ The details of these operations are:
>
> void dma_async_issue_pending(struct dma_chan *chan);
>
> -Further APIs:
> --------------
> +Further APIs
> +------------
>
> 1. Terminate APIs
>
> diff --git a/Documentation/driver-api/thermal/cpu-idle-cooling.rst b/Documentation/driver-api/thermal/cpu-idle-cooling.rst
> index e4f0859486c7..d8b522d37eb9 100644
> --- a/Documentation/driver-api/thermal/cpu-idle-cooling.rst
> +++ b/Documentation/driver-api/thermal/cpu-idle-cooling.rst
> @@ -1,6 +1,9 @@
> +================
> +CPU Idle Cooling
> +================
>
> -Situation:
> -----------
> +Situation
> +---------
>
> Under certain circumstances a SoC can reach a critical temperature
> limit and is unable to stabilize the temperature around a temperature
> @@ -24,8 +27,8 @@ with a power less than the requested power budget and the next OPP
> exceeds the power budget. An intermediate OPP could have been used if
> it were present.
>
> -Solutions:
> -----------
> +Solutions
> +---------
>
> If we can remove the static and the dynamic leakage for a specific
> duration in a controlled period, the SoC temperature will
> @@ -45,12 +48,12 @@ idle state target residency, we lead to dropping the static and the
> dynamic leakage for this period (modulo the energy needed to enter
> this state). So the sustainable power with idle cycles has a linear
> relation with the OPPâs sustainable power and can be computed with a
> -coefficient similar to:
> +coefficient similar to::
>
> Power(IdleCycle) = Coef x Power(OPP)
>
> -Idle Injection:
> ----------------
> +Idle Injection
> +--------------
>
> The base concept of the idle injection is to force the CPU to go to an
> idle state for a specified time each control cycle, it provides
> @@ -64,6 +67,7 @@ latencies as the CPUs will have to wakeup from a deep sleep state.
> We use a fixed duration of idle injection that gives an acceptable
> performance penalty and a fixed latency. Mitigation can be increased
> or decreased by modulating the duty cycle of the idle injection.
> +::
>
> ^
> |
> @@ -90,6 +94,7 @@ computed.
>
> The governor will change the cooling device state thus the duty cycle
> and this variation will modulate the cooling effect.
> +::
>
> ^
> |
> @@ -132,7 +137,7 @@ Power considerations
> --------------------
>
> When we reach the thermal trip point, we have to sustain a specified
> -power for a specific temperature but at this time we consume:
> +power for a specific temperature but at this time we consume::
>
> Power = Capacitance x Voltage^2 x Frequency x Utilisation
>
> @@ -141,7 +146,7 @@ wrong in the system setup). The âCapacitanceâ and âUtilisationâ are a
> fixed value, âVoltageâ and the âFrequencyâ are fixed artificially
> because we donât want to change the OPP. We can group the
> âCapacitanceâ and the âUtilisationâ into a single term which is the
> -âDynamic Power Coefficient (Cdyn)â Simplifying the above, we have:
> +âDynamic Power Coefficient (Cdyn)â Simplifying the above, we have::
>
> Pdyn = Cdyn x Voltage^2 x Frequency
>
> @@ -150,7 +155,7 @@ in order to target the sustainable power defined in the device
> tree. So with the idle injection mechanism, we want an average power
> (Ptarget) resulting in an amount of time running at full power on a
> specific OPP and idle another amount of time. That could be put in a
> -equation:
> +equation::
>
> P(opp)target = ((Trunning x (P(opp)running) + (Tidle x P(opp)idle)) /
> (Trunning + Tidle)
> @@ -160,7 +165,7 @@ equation:
>
> At this point if we know the running period for the CPU, that gives us
> the idle injection we need. Alternatively if we have the idle
> -injection duration, we can compute the running duration with:
> +injection duration, we can compute the running duration with::
>
> Trunning = Tidle / ((P(opp)running / P(opp)target) - 1)
>
> @@ -183,7 +188,7 @@ However, in this demonstration we ignore three aspects:
> target residency, otherwise we end up consuming more energy and
> potentially invert the mitigation effect
>
> -So the final equation is:
> +So the final equation is::
>
> Trunning = (Tidle - Twakeup ) x
> (((P(opp)dyn + P(opp)static ) - P(opp)target) / P(opp)target )
> diff --git a/Documentation/driver-api/thermal/index.rst b/Documentation/driver-api/thermal/index.rst
> index 5ba61d19c6ae..4cb0b9b6bfb8 100644
> --- a/Documentation/driver-api/thermal/index.rst
> +++ b/Documentation/driver-api/thermal/index.rst
> @@ -8,6 +8,7 @@ Thermal
> :maxdepth: 1
>
> cpu-cooling-api
> + cpu-idle-cooling
> sysfs-api
> power_allocator
>
>
--
~Randy