[Intel-gfx] [PATCH v7 10/10] drm/i915/dsb: Documentation for DSB.

[Sharma, Shashank]

On 9/18/2019 1:27 PM, Animesh Manna wrote:
> Added docbook info regarding Display State Buffer(DSB) which
> is added from gen12 onwards to batch submit display HW programming.
>
> v1: Initial version as RFC.
>
> Cc: Jani Nikula <jani.nikula at intel.com>
> Cc: Rodrigo Vivi <rodrigo.vivi at intel.com>
> Cc: Shashank Sharma <shashank.sharma at intel.com>
> Signed-off-by: Animesh Manna <animesh.manna at intel.com>
> ---
>   Documentation/gpu/i915.rst               |  9 ++++
>   drivers/gpu/drm/i915/display/intel_dsb.c | 68 ++++++++++++++++++++++++
>   2 files changed, 77 insertions(+)
>
> diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
> index e249ea7b0ec7..465779670fd4 100644
> --- a/Documentation/gpu/i915.rst
> +++ b/Documentation/gpu/i915.rst
> @@ -246,6 +246,15 @@ Display PLLs
>   .. kernel-doc:: drivers/gpu/drm/i915/display/intel_dpll_mgr.h
>      :internal:
>   
> +Display State Buffer
> +--------------------
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dsb.c
> +   :doc: DSB
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dsb.c
> +   :internal:
> +
>   Memory Management and Command Submission
>   ========================================
>   
> diff --git a/drivers/gpu/drm/i915/display/intel_dsb.c b/drivers/gpu/drm/i915/display/intel_dsb.c
> index cbf7f2c3300c..5b5278c94ca7 100644
> --- a/drivers/gpu/drm/i915/display/intel_dsb.c
> +++ b/drivers/gpu/drm/i915/display/intel_dsb.c
> @@ -9,6 +9,23 @@
>   
>   #define DSB_BUF_SIZE    (2 * PAGE_SIZE)
>   
> +/**
> + * DOC: DSB
> + *
> + * A DSB (Display State Buffer) is a queue of MMIO instructions in the memory
> + * which can be offloaded to DSB HW in Display Controller. DSB HW is a DMA
> + * engine that can be programmed to download the DSB from memory.
> + * It allows driver to batch submit display HW programming. This helps to
> + * reduce loading time and CPU activity, thereby making the context switch
> + * faster. DSB Support added from Gen12 Intel graphics based platform.
> + *
> + * DSB's can access only the pipe, plane, and transcoder Data Island Packet
> + * registers.
> + *
> + * DSB HW can support only register writes (both indexed and direct MMIO
> + * writes). There are no registers reads possible with DSB HW engine.
> + */
> +
>   /* DSB opcodes. */
>   #define DSB_OPCODE_SHIFT		24
>   #define DSB_OPCODE_MMIO_WRITE		0x1
> @@ -66,6 +83,17 @@ static inline bool intel_dsb_disable_engine(struct intel_dsb *dsb)
>   	return true;
>   }
>   
> +/**
> + * intel_dsb_get() - Allocate dsb context and return a dsb instance.
we are using 'dsb' and 'DSB' both. Please use one of these, and make it 
uniform across the doc. I will prefer DSB (expect function names of 
course :))
> + * @crtc: intel_crtc structure to get pipe info.
> + *
> + * This function will give handle of the DSB instance which
> + * user want to operate on.
Little re-arrangement: This function provides handle of a DSB instance, 
for the further DSB operations.
> + *
> + * Return : address of Intel_dsb instance requested for.
Returns:
> + * In failure case, the dsb instance will not have any command buffer.
Failure: Returns the same DSB instance, but without a command buffer.
> + */
> +
>   struct intel_dsb *
>   intel_dsb_get(struct intel_crtc *crtc)
>   {
> @@ -116,6 +144,14 @@ intel_dsb_get(struct intel_crtc *crtc)
>   	return dsb;
>   }
>   
> +/**
> + * intel_dsb_put() - To destroy DSB context.
> + * @dsb: intel_dsb structure.
> + *
> + * This function is used to destroy the dsb-context by doing unpin
> + * and release the vma object.
This function destroys the DSB context allocated by a dsb_get(), by 
unpinning and releasing the VMA object associated with it.
> + */
> +
>   void intel_dsb_put(struct intel_dsb *dsb)
>   {
>   	struct intel_crtc *crtc = container_of(dsb, typeof(*crtc), dsb);
> @@ -137,6 +173,19 @@ void intel_dsb_put(struct intel_dsb *dsb)
>   	}
>   }
>   
> +/**
> + * intel_dsb_indexed_reg_write() -Write to the dsb context for auto
> + * increment register.
> + * @dsb: intel_dsb structure.
> + * @reg: register address.
> + * @val: value.
> + *
> + * This function is used for auto-increment register and intel_dsb_reg_write()
> + * is used for normal register.

I am not able to get the message out of this line. why are we adding the 
description of intel_dsb_reg_write() here ?

Please keep this simple and explain only function under description.

> During command buffer overflow, a warning
> + * is thrown and rest all erroneous condition register programming is done
> + * through mmio write.
> + */
> +
>   void intel_dsb_indexed_reg_write(struct intel_dsb *dsb, i915_reg_t reg,
>   				 u32 val)
>   {
> @@ -201,6 +250,18 @@ void intel_dsb_indexed_reg_write(struct intel_dsb *dsb, i915_reg_t reg,
>   		buf[dsb->free_pos] = 0;
>   }
>   
> +/**
> + * intel_dsb_reg_write() -Write to the dsb context for normal
> + * register.
> + * @dsb: intel_dsb structure.
> + * @reg: register address.
> + * @val: value.
> + *
> + * This function is used for writing register-value pair in command
> + * buffer of DSB. During command buffer overflow, a warning
> + * is thrown and rest all erroneous condition register programming is done
> + * through mmio write.
> + */
>   void intel_dsb_reg_write(struct intel_dsb *dsb, i915_reg_t reg, u32 val)
>   {
>   	struct intel_crtc *crtc = container_of(dsb, typeof(*crtc), dsb);
> @@ -223,6 +284,13 @@ void intel_dsb_reg_write(struct intel_dsb *dsb, i915_reg_t reg, u32 val)
>   			       i915_mmio_reg_offset(reg);
>   }
>   
> +/**
> + * intel_dsb_commit() - Trigger workload execution of DSB.
> + * @dsb: intel_dsb structure.
> + *
> + * This function is used to do actual write to hardware using DSB.
> + * On errors, fall back to MMIO. Also this function help to reset the context.
> + */
>   void intel_dsb_commit(struct intel_dsb *dsb)
>   {
>   	struct intel_crtc *crtc = container_of(dsb, typeof(*crtc), dsb);

With the comments above fixed, Please feel free to use:

Reviewed-by: Shashank Sharma <shashank.sharma at intel.com>

Regards

Shashank