drm/mediatek: Clarify/finish documentation for some driver structures
Commit Message
The documentation for some of the driver structures in mediatek-drm
was set to be kerneldoc but some code additions didn't actually update
the comments accordingly and this caused triggering some warnings.
Add comments for the remaining undocumented entries; while at it, also
clarify some acronyms for various display HW blocks and fix some comment
blocks to actually get parsed as kerneldoc.
Signed-off-by: AngeloGioacchino Del Regno <angelogioacchino.delregno@collabora.com>
---
drivers/gpu/drm/mediatek/mtk_disp_aal.c | 8 +++++---
drivers/gpu/drm/mediatek/mtk_disp_ccorr.c | 8 +++++---
drivers/gpu/drm/mediatek/mtk_disp_color.c | 11 +++++++----
drivers/gpu/drm/mediatek/mtk_disp_gamma.c | 8 ++++++--
drivers/gpu/drm/mediatek/mtk_disp_ovl.c | 13 +++++++++----
drivers/gpu/drm/mediatek/mtk_disp_rdma.c | 12 +++++++++---
6 files changed, 41 insertions(+), 19 deletions(-)
Comments
Il 21/03/23 12:14, AngeloGioacchino Del Regno ha scritto:
> The documentation for some of the driver structures in mediatek-drm
> was set to be kerneldoc but some code additions didn't actually update
> the comments accordingly and this caused triggering some warnings.
>
> Add comments for the remaining undocumented entries; while at it, also
> clarify some acronyms for various display HW blocks and fix some comment
> blocks to actually get parsed as kerneldoc.
>
> Signed-off-by: AngeloGioacchino Del Regno <angelogioacchino.delregno@collabora.com>
Hello CK,
I just noticed that this patch is getting stale and forgotten.
Please take a look at it, as this solves kerneldoc warnings during kernel build.
Regards,
Angelo
> --- > drivers/gpu/drm/mediatek/mtk_disp_aal.c | 8 +++++---
> drivers/gpu/drm/mediatek/mtk_disp_ccorr.c | 8 +++++---
> drivers/gpu/drm/mediatek/mtk_disp_color.c | 11 +++++++----
> drivers/gpu/drm/mediatek/mtk_disp_gamma.c | 8 ++++++--
> drivers/gpu/drm/mediatek/mtk_disp_ovl.c | 13 +++++++++----
> drivers/gpu/drm/mediatek/mtk_disp_rdma.c | 12 +++++++++---
> 6 files changed, 41 insertions(+), 19 deletions(-)
>
> diff --git a/drivers/gpu/drm/mediatek/mtk_disp_aal.c b/drivers/gpu/drm/mediatek/mtk_disp_aal.c
> index 434e8a9ce8ab..12d1800c1d34 100644
> --- a/drivers/gpu/drm/mediatek/mtk_disp_aal.c
> +++ b/drivers/gpu/drm/mediatek/mtk_disp_aal.c
> @@ -27,9 +27,11 @@ struct mtk_disp_aal_data {
> };
>
> /**
> - * struct mtk_disp_aal - DISP_AAL driver structure
> - * @ddp_comp - structure containing type enum and hardware resources
> - * @crtc - associated crtc to report irq events to
> + * struct mtk_disp_aal - Display Adaptive Ambient Light driver structure
> + * @clk: clock for DISP_AAL controller
> + * @regs: MMIO registers base
> + * @cmdq_reg: CMDQ Client register
> + * @data: platform specific data for DISP_AAL
> */
> struct mtk_disp_aal {
> struct clk *clk;
> diff --git a/drivers/gpu/drm/mediatek/mtk_disp_ccorr.c b/drivers/gpu/drm/mediatek/mtk_disp_ccorr.c
> index 1773379b2439..b173aa058573 100644
> --- a/drivers/gpu/drm/mediatek/mtk_disp_ccorr.c
> +++ b/drivers/gpu/drm/mediatek/mtk_disp_ccorr.c
> @@ -35,9 +35,11 @@ struct mtk_disp_ccorr_data {
> };
>
> /**
> - * struct mtk_disp_ccorr - DISP_CCORR driver structure
> - * @ddp_comp - structure containing type enum and hardware resources
> - * @crtc - associated crtc to report irq events to
> + * struct mtk_disp_ccorr - Display Color Correction driver structure
> + * @clk: clock for DISP_CCORR block
> + * @regs: MMIO registers base
> + * @cmdq_reg: CMDQ Client register
> + * @data: platform specific data for DISP_CCORR
> */
> struct mtk_disp_ccorr {
> struct clk *clk;
> diff --git a/drivers/gpu/drm/mediatek/mtk_disp_color.c b/drivers/gpu/drm/mediatek/mtk_disp_color.c
> index cac9206079e7..7884f4736b7c 100644
> --- a/drivers/gpu/drm/mediatek/mtk_disp_color.c
> +++ b/drivers/gpu/drm/mediatek/mtk_disp_color.c
> @@ -31,10 +31,13 @@ struct mtk_disp_color_data {
> unsigned int color_offset;
> };
>
> -/*
> - * struct mtk_disp_color - DISP_COLOR driver structure
> - * @crtc: associated crtc to report irq events to
> - * @data: platform colour driver data
> +/**
> + * struct mtk_disp_color - DISP_COLOR (Display Color) driver structure
> + * @crtc: associated crtc to report irq events to
> + * @clk: clock for DISP_COLOR block
> + * @regs: MMIO registers base
> + * @cmdq_reg: CMDQ Client register
> + * @data: platform specific data for DISP_COLOR
> */
> struct mtk_disp_color {
> struct drm_crtc *crtc;
> diff --git a/drivers/gpu/drm/mediatek/mtk_disp_gamma.c b/drivers/gpu/drm/mediatek/mtk_disp_gamma.c
> index c844942603f7..7e748613fccb 100644
> --- a/drivers/gpu/drm/mediatek/mtk_disp_gamma.c
> +++ b/drivers/gpu/drm/mediatek/mtk_disp_gamma.c
> @@ -31,8 +31,12 @@ struct mtk_disp_gamma_data {
> bool lut_diff;
> };
>
> -/*
> - * struct mtk_disp_gamma - DISP_GAMMA driver structure
> +/**
> + * struct mtk_disp_gamma - Display Gamma driver structure
> + * @clk: clock for DISP_GAMMA block
> + * @regs: MMIO registers base
> + * @cmdq_reg: CMDQ Client register
> + * @data: platform data for DISP_GAMMA
> */
> struct mtk_disp_gamma {
> struct clk *clk;
> diff --git a/drivers/gpu/drm/mediatek/mtk_disp_ovl.c b/drivers/gpu/drm/mediatek/mtk_disp_ovl.c
> index 9d8c986700ee..00f2871fd1a4 100644
> --- a/drivers/gpu/drm/mediatek/mtk_disp_ovl.c
> +++ b/drivers/gpu/drm/mediatek/mtk_disp_ovl.c
> @@ -76,10 +76,15 @@ struct mtk_disp_ovl_data {
> bool supports_afbc;
> };
>
> -/*
> - * struct mtk_disp_ovl - DISP_OVL driver structure
> - * @crtc: associated crtc to report vblank events to
> - * @data: platform data
> +/**
> + * struct mtk_disp_ovl - Display Overlay driver structure
> + * @crtc: associated crtc to report vblank events to
> + * @clk: clock for DISP_OVL block
> + * @regs: MMIO registers base
> + * @cmdq_reg: CMDQ Client register
> + * @data: platform data
> + * @vblank_cb: vblank callback function
> + * @vblank_cb_data: pointer to data that will be passed to vblank_cb()
> */
> struct mtk_disp_ovl {
> struct drm_crtc *crtc;
> diff --git a/drivers/gpu/drm/mediatek/mtk_disp_rdma.c b/drivers/gpu/drm/mediatek/mtk_disp_rdma.c
> index e8e337903b0d..74f4a0bce5cc 100644
> --- a/drivers/gpu/drm/mediatek/mtk_disp_rdma.c
> +++ b/drivers/gpu/drm/mediatek/mtk_disp_rdma.c
> @@ -59,9 +59,15 @@ struct mtk_disp_rdma_data {
> unsigned int fifo_size;
> };
>
> -/*
> - * struct mtk_disp_rdma - DISP_RDMA driver structure
> - * @data: local driver data
> +/**
> + * struct mtk_disp_rdma - Display Read DMA driver structure
> + * @clk: clock for DISP_RDMA block
> + * @regs: MMIO registers base
> + * @cmdq_reg: CMDQ Client register
> + * @data: platform data
> + * @vblank_cb: vblank callback function
> + * @vblank_cb_data: pointer to data that will be passed to vblank_cb()
> + * @fifo_size: size of DISP_RDMA block's FIFO
> */
> struct mtk_disp_rdma {
> struct clk *clk;
Hi, Angelo:
AngeloGioacchino Del Regno <angelogioacchino.delregno@collabora.com> 於
2023年4月19日 週三 下午2:16寫道：
>
> Il 21/03/23 12:14, AngeloGioacchino Del Regno ha scritto:
> > The documentation for some of the driver structures in mediatek-drm
> > was set to be kerneldoc but some code additions didn't actually update
> > the comments accordingly and this caused triggering some warnings.
> >
> > Add comments for the remaining undocumented entries; while at it, also
> > clarify some acronyms for various display HW blocks and fix some comment
> > blocks to actually get parsed as kerneldoc.
> >
> > Signed-off-by: AngeloGioacchino Del Regno <angelogioacchino.delregno@collabora.com>
>
> Hello CK,
> I just noticed that this patch is getting stale and forgotten.
>
> Please take a look at it, as this solves kerneldoc warnings during kernel build.
There is conflict when I apply this patch. Please base on
mediatek-drm-next to send patch.
Regards,
Chun-Kuang.
>
> Regards,
> Angelo
>
> > --- > drivers/gpu/drm/mediatek/mtk_disp_aal.c | 8 +++++---
> > drivers/gpu/drm/mediatek/mtk_disp_ccorr.c | 8 +++++---
> > drivers/gpu/drm/mediatek/mtk_disp_color.c | 11 +++++++----
> > drivers/gpu/drm/mediatek/mtk_disp_gamma.c | 8 ++++++--
> > drivers/gpu/drm/mediatek/mtk_disp_ovl.c | 13 +++++++++----
> > drivers/gpu/drm/mediatek/mtk_disp_rdma.c | 12 +++++++++---
> > 6 files changed, 41 insertions(+), 19 deletions(-)
> >
> > diff --git a/drivers/gpu/drm/mediatek/mtk_disp_aal.c b/drivers/gpu/drm/mediatek/mtk_disp_aal.c
> > index 434e8a9ce8ab..12d1800c1d34 100644
> > --- a/drivers/gpu/drm/mediatek/mtk_disp_aal.c
> > +++ b/drivers/gpu/drm/mediatek/mtk_disp_aal.c
> > @@ -27,9 +27,11 @@ struct mtk_disp_aal_data {
> > };
> >
> > /**
> > - * struct mtk_disp_aal - DISP_AAL driver structure
> > - * @ddp_comp - structure containing type enum and hardware resources
> > - * @crtc - associated crtc to report irq events to
> > + * struct mtk_disp_aal - Display Adaptive Ambient Light driver structure
> > + * @clk: clock for DISP_AAL controller
> > + * @regs: MMIO registers base
> > + * @cmdq_reg: CMDQ Client register
> > + * @data: platform specific data for DISP_AAL
> > */
> > struct mtk_disp_aal {
> > struct clk *clk;
> > diff --git a/drivers/gpu/drm/mediatek/mtk_disp_ccorr.c b/drivers/gpu/drm/mediatek/mtk_disp_ccorr.c
> > index 1773379b2439..b173aa058573 100644
> > --- a/drivers/gpu/drm/mediatek/mtk_disp_ccorr.c
> > +++ b/drivers/gpu/drm/mediatek/mtk_disp_ccorr.c
> > @@ -35,9 +35,11 @@ struct mtk_disp_ccorr_data {
> > };
> >
> > /**
> > - * struct mtk_disp_ccorr - DISP_CCORR driver structure
> > - * @ddp_comp - structure containing type enum and hardware resources
> > - * @crtc - associated crtc to report irq events to
> > + * struct mtk_disp_ccorr - Display Color Correction driver structure
> > + * @clk: clock for DISP_CCORR block
> > + * @regs: MMIO registers base
> > + * @cmdq_reg: CMDQ Client register
> > + * @data: platform specific data for DISP_CCORR
> > */
> > struct mtk_disp_ccorr {
> > struct clk *clk;
> > diff --git a/drivers/gpu/drm/mediatek/mtk_disp_color.c b/drivers/gpu/drm/mediatek/mtk_disp_color.c
> > index cac9206079e7..7884f4736b7c 100644
> > --- a/drivers/gpu/drm/mediatek/mtk_disp_color.c
> > +++ b/drivers/gpu/drm/mediatek/mtk_disp_color.c
> > @@ -31,10 +31,13 @@ struct mtk_disp_color_data {
> > unsigned int color_offset;
> > };
> >
> > -/*
> > - * struct mtk_disp_color - DISP_COLOR driver structure
> > - * @crtc: associated crtc to report irq events to
> > - * @data: platform colour driver data
> > +/**
> > + * struct mtk_disp_color - DISP_COLOR (Display Color) driver structure
> > + * @crtc: associated crtc to report irq events to
> > + * @clk: clock for DISP_COLOR block
> > + * @regs: MMIO registers base
> > + * @cmdq_reg: CMDQ Client register
> > + * @data: platform specific data for DISP_COLOR
> > */
> > struct mtk_disp_color {
> > struct drm_crtc *crtc;
> > diff --git a/drivers/gpu/drm/mediatek/mtk_disp_gamma.c b/drivers/gpu/drm/mediatek/mtk_disp_gamma.c
> > index c844942603f7..7e748613fccb 100644
> > --- a/drivers/gpu/drm/mediatek/mtk_disp_gamma.c
> > +++ b/drivers/gpu/drm/mediatek/mtk_disp_gamma.c
> > @@ -31,8 +31,12 @@ struct mtk_disp_gamma_data {
> > bool lut_diff;
> > };
> >
> > -/*
> > - * struct mtk_disp_gamma - DISP_GAMMA driver structure
> > +/**
> > + * struct mtk_disp_gamma - Display Gamma driver structure
> > + * @clk: clock for DISP_GAMMA block
> > + * @regs: MMIO registers base
> > + * @cmdq_reg: CMDQ Client register
> > + * @data: platform data for DISP_GAMMA
> > */
> > struct mtk_disp_gamma {
> > struct clk *clk;
> > diff --git a/drivers/gpu/drm/mediatek/mtk_disp_ovl.c b/drivers/gpu/drm/mediatek/mtk_disp_ovl.c
> > index 9d8c986700ee..00f2871fd1a4 100644
> > --- a/drivers/gpu/drm/mediatek/mtk_disp_ovl.c
> > +++ b/drivers/gpu/drm/mediatek/mtk_disp_ovl.c
> > @@ -76,10 +76,15 @@ struct mtk_disp_ovl_data {
> > bool supports_afbc;
> > };
> >
> > -/*
> > - * struct mtk_disp_ovl - DISP_OVL driver structure
> > - * @crtc: associated crtc to report vblank events to
> > - * @data: platform data
> > +/**
> > + * struct mtk_disp_ovl - Display Overlay driver structure
> > + * @crtc: associated crtc to report vblank events to
> > + * @clk: clock for DISP_OVL block
> > + * @regs: MMIO registers base
> > + * @cmdq_reg: CMDQ Client register
> > + * @data: platform data
> > + * @vblank_cb: vblank callback function
> > + * @vblank_cb_data: pointer to data that will be passed to vblank_cb()
> > */
> > struct mtk_disp_ovl {
> > struct drm_crtc *crtc;
> > diff --git a/drivers/gpu/drm/mediatek/mtk_disp_rdma.c b/drivers/gpu/drm/mediatek/mtk_disp_rdma.c
> > index e8e337903b0d..74f4a0bce5cc 100644
> > --- a/drivers/gpu/drm/mediatek/mtk_disp_rdma.c
> > +++ b/drivers/gpu/drm/mediatek/mtk_disp_rdma.c
> > @@ -59,9 +59,15 @@ struct mtk_disp_rdma_data {
> > unsigned int fifo_size;
> > };
> >
> > -/*
> > - * struct mtk_disp_rdma - DISP_RDMA driver structure
> > - * @data: local driver data
> > +/**
> > + * struct mtk_disp_rdma - Display Read DMA driver structure
> > + * @clk: clock for DISP_RDMA block
> > + * @regs: MMIO registers base
> > + * @cmdq_reg: CMDQ Client register
> > + * @data: platform data
> > + * @vblank_cb: vblank callback function
> > + * @vblank_cb_data: pointer to data that will be passed to vblank_cb()
> > + * @fifo_size: size of DISP_RDMA block's FIFO
> > */
> > struct mtk_disp_rdma {
> > struct clk *clk;
>
> --
> AngeloGioacchino Del Regno
> Software Engineer
>
> Collabora Ltd.
> Platinum Building, St John's Innovation Park, Cambridge CB4 0DS, UK
> Registered in England & Wales, no. 5513718
>
@@ -27,9 +27,11 @@ struct mtk_disp_aal_data {
};
/**
- * struct mtk_disp_aal - DISP_AAL driver structure
- * @ddp_comp - structure containing type enum and hardware resources
- * @crtc - associated crtc to report irq events to
+ * struct mtk_disp_aal - Display Adaptive Ambient Light driver structure
+ * @clk: clock for DISP_AAL controller
+ * @regs: MMIO registers base
+ * @cmdq_reg: CMDQ Client register
+ * @data: platform specific data for DISP_AAL
*/
struct mtk_disp_aal {
struct clk *clk;
@@ -35,9 +35,11 @@ struct mtk_disp_ccorr_data {
};
/**
- * struct mtk_disp_ccorr - DISP_CCORR driver structure
- * @ddp_comp - structure containing type enum and hardware resources
- * @crtc - associated crtc to report irq events to
+ * struct mtk_disp_ccorr - Display Color Correction driver structure
+ * @clk: clock for DISP_CCORR block
+ * @regs: MMIO registers base
+ * @cmdq_reg: CMDQ Client register
+ * @data: platform specific data for DISP_CCORR
*/
struct mtk_disp_ccorr {
struct clk *clk;
@@ -31,10 +31,13 @@ struct mtk_disp_color_data {
unsigned int color_offset;
};
-/*
- * struct mtk_disp_color - DISP_COLOR driver structure
- * @crtc: associated crtc to report irq events to
- * @data: platform colour driver data
+/**
+ * struct mtk_disp_color - DISP_COLOR (Display Color) driver structure
+ * @crtc: associated crtc to report irq events to
+ * @clk: clock for DISP_COLOR block
+ * @regs: MMIO registers base
+ * @cmdq_reg: CMDQ Client register
+ * @data: platform specific data for DISP_COLOR
*/
struct mtk_disp_color {
struct drm_crtc *crtc;
@@ -31,8 +31,12 @@ struct mtk_disp_gamma_data {
bool lut_diff;
};
-/*
- * struct mtk_disp_gamma - DISP_GAMMA driver structure
+/**
+ * struct mtk_disp_gamma - Display Gamma driver structure
+ * @clk: clock for DISP_GAMMA block
+ * @regs: MMIO registers base
+ * @cmdq_reg: CMDQ Client register
+ * @data: platform data for DISP_GAMMA
*/
struct mtk_disp_gamma {
struct clk *clk;
@@ -76,10 +76,15 @@ struct mtk_disp_ovl_data {
bool supports_afbc;
};
-/*
- * struct mtk_disp_ovl - DISP_OVL driver structure
- * @crtc: associated crtc to report vblank events to
- * @data: platform data
+/**
+ * struct mtk_disp_ovl - Display Overlay driver structure
+ * @crtc: associated crtc to report vblank events to
+ * @clk: clock for DISP_OVL block
+ * @regs: MMIO registers base
+ * @cmdq_reg: CMDQ Client register
+ * @data: platform data
+ * @vblank_cb: vblank callback function
+ * @vblank_cb_data: pointer to data that will be passed to vblank_cb()
*/
struct mtk_disp_ovl {
struct drm_crtc *crtc;
@@ -59,9 +59,15 @@ struct mtk_disp_rdma_data {
unsigned int fifo_size;
};
-/*
- * struct mtk_disp_rdma - DISP_RDMA driver structure
- * @data: local driver data
+/**
+ * struct mtk_disp_rdma - Display Read DMA driver structure
+ * @clk: clock for DISP_RDMA block
+ * @regs: MMIO registers base
+ * @cmdq_reg: CMDQ Client register
+ * @data: platform data
+ * @vblank_cb: vblank callback function
+ * @vblank_cb_data: pointer to data that will be passed to vblank_cb()
+ * @fifo_size: size of DISP_RDMA block's FIFO
*/
struct mtk_disp_rdma {
struct clk *clk;