Fixed the warnings: Function parameter or member 'xxx' not described when make htmldocs
This patch depends on: - https://patchwork.freedesktop.org/series/54448/ - https://patchwork.freedesktop.org/series/54449/ - https://patchwork.freedesktop.org/series/54450/
Signed-off-by: James Qian Wang (Arm Technology China) james.qian.wang@arm.com --- .../gpu/drm/arm/display/komeda/komeda_crtc.c | 14 ++++-- .../gpu/drm/arm/display/komeda/komeda_dev.h | 16 +++++-- .../arm/display/komeda/komeda_framebuffer.h | 9 +++- .../gpu/drm/arm/display/komeda/komeda_kms.h | 18 ++++++-- .../drm/arm/display/komeda/komeda_pipeline.h | 43 ++++++++++++++----- .../gpu/drm/arm/display/komeda/komeda_plane.c | 8 ++++ 6 files changed, 85 insertions(+), 23 deletions(-)
diff --git a/drivers/gpu/drm/arm/display/komeda/komeda_crtc.c b/drivers/gpu/drm/arm/display/komeda/komeda_crtc.c index 053b1e3e74be..d335fec1b727 100644 --- a/drivers/gpu/drm/arm/display/komeda/komeda_crtc.c +++ b/drivers/gpu/drm/arm/display/komeda/komeda_crtc.c @@ -18,9 +18,17 @@ #include "komeda_dev.h" #include "komeda_kms.h"
-/* crtc_atomic_check is the final check stage, so beside build a display data - * pipeline according the crtc_state, but still needs to release/disable the - * unclaimed pipeline resources. +/** + * komeda_crtc_atomic_check - build display output data flow + * @crtc: DRM crtc + * @state: the crtc state object + * + * crtc_atomic_check is the final check stage, so beside build a display data + * pipeline according to the crtc_state, but still needs to release or disable + * the unclaimed pipeline resources. + * + * RETURNS: + * Zero for success or -errno */ static int komeda_crtc_atomic_check(struct drm_crtc *crtc, diff --git a/drivers/gpu/drm/arm/display/komeda/komeda_dev.h b/drivers/gpu/drm/arm/display/komeda/komeda_dev.h index 0c3e32b596d9..29e03c4e1ffc 100644 --- a/drivers/gpu/drm/arm/display/komeda/komeda_dev.h +++ b/drivers/gpu/drm/arm/display/komeda/komeda_dev.h @@ -120,7 +120,7 @@ struct komeda_dev_funcs { int master_pipe, u32 active_pipes); };
-/** +/* * DISPLAY_MODE describes how many display been enabled, and which will be * passed to CHIP by &komeda_dev_funcs->change_opmode(), then CHIP can do the * pipeline resources assignment according to this usage hint. @@ -145,24 +145,31 @@ enum { * control-abilites of device. */ struct komeda_dev { + /** @dev: the base device structure */ struct device *dev; + /** @reg_base: the base address of komeda io space */ u32 __iomem *reg_base;
+ /** @chip: the basic chip information */ struct komeda_chip_info chip; /** @fmt_tbl: initialized by &komeda_dev_funcs->init_format_table */ struct komeda_format_caps_table fmt_tbl; /** @pclk: APB clock for register access */ struct clk *pclk; - /** @mck: HW main engine clk */ + /** @mclk: HW main engine clk */ struct clk *mclk;
/** @irq: irq number */ int irq;
- struct mutex lock; /* used to protect dpmode */ - u32 dpmode; /* current display mode */ + /** @lock: used to protect dpmode */ + struct mutex lock; + /** @dpmode: current display mode */ + u32 dpmode;
+ /** @n_pipelines: the number of pipe in @pipelines */ int n_pipelines; + /** @pipelines: the komeda pipelines */ struct komeda_pipeline *pipelines[KOMEDA_MAX_PIPELINES];
/** @funcs: chip funcs to access to HW */ @@ -175,6 +182,7 @@ struct komeda_dev { */ void *chip_data;
+ /** @debugfs_root: root directory of komeda debugfs */ struct dentry *debugfs_root; };
diff --git a/drivers/gpu/drm/arm/display/komeda/komeda_framebuffer.h b/drivers/gpu/drm/arm/display/komeda/komeda_framebuffer.h index 0de2e4a2afd2..ea2fe190c1e3 100644 --- a/drivers/gpu/drm/arm/display/komeda/komeda_framebuffer.h +++ b/drivers/gpu/drm/arm/display/komeda/komeda_framebuffer.h @@ -10,11 +10,16 @@ #include <drm/drm_framebuffer.h> #include "komeda_format_caps.h"
-/** struct komeda_fb - entend drm_framebuffer with komeda attribute */ +/** + * struct komeda_fb - Entending drm_framebuffer with komeda attribute + */ struct komeda_fb { /** @base: &drm_framebuffer */ struct drm_framebuffer base; - /* @format_caps: &komeda_format_caps */ + /** + * @format_caps: + * extends drm_format_info for komeda specific information + */ const struct komeda_format_caps *format_caps; /** @aligned_w: aligned frame buffer width */ u32 aligned_w; diff --git a/drivers/gpu/drm/arm/display/komeda/komeda_kms.h b/drivers/gpu/drm/arm/display/komeda/komeda_kms.h index b53db1d5b8e1..1d9bc33ba54f 100644 --- a/drivers/gpu/drm/arm/display/komeda/komeda_kms.h +++ b/drivers/gpu/drm/arm/display/komeda/komeda_kms.h @@ -16,7 +16,9 @@ #include <video/videomode.h> #include <video/display_timing.h>
-/** struct komeda_plane - komeda instance of drm_plane */ +/** + * struct komeda_plane - komeda instance of drm_plane + */ struct komeda_plane { /** @base: &drm_plane */ struct drm_plane base; @@ -72,11 +74,13 @@ struct komeda_crtc { */ struct komeda_pipeline *slave;
- /* this flip_done is for tracing the disable */ + /** @disable_done: this flip_done is for tracing the disable */ struct completion *disable_done; };
-/** struct komeda_crtc_state */ +/** + * struct komeda_crtc_state + */ struct komeda_crtc_state { /** @base: &drm_crtc_state */ struct drm_crtc_state base; @@ -84,7 +88,15 @@ struct komeda_crtc_state { /* private properties */
/* computed state which are used by validate/check */ + /** + * @affected_pipes: + * the affected pipelines in once display instance + */ u32 affected_pipes; + /** + * @active_pipes: + * the active pipelines in once display instance + */ u32 active_pipes; };
diff --git a/drivers/gpu/drm/arm/display/komeda/komeda_pipeline.h b/drivers/gpu/drm/arm/display/komeda/komeda_pipeline.h index 233e512319e8..b1f813a349a4 100644 --- a/drivers/gpu/drm/arm/display/komeda/komeda_pipeline.h +++ b/drivers/gpu/drm/arm/display/komeda/komeda_pipeline.h @@ -90,32 +90,35 @@ struct komeda_component { u32 __iomem *reg; /** @id: component id */ u32 id; - /** @hw_ic: component hw id, - * which is initialized by chip and used by chip only + /** + * @hw_id: component hw id, + * which is initialized by chip and used by chip only */ u32 hw_id;
/** * @max_active_inputs: - * @max_active_outpus: + * @max_active_outputs: * - * maximum number of inputs/outputs that can be active in the same time + * maximum number of inputs/outputs that can be active at the same time * Note: * the number isn't the bit number of @supported_inputs or * @supported_outputs, but may be less than it, since component may not * support enabling all @supported_inputs/outputs at the same time. */ u8 max_active_inputs; + /** @max_active_outputs: maximum number of outputs */ u8 max_active_outputs; /** * @supported_inputs: * @supported_outputs: * - * bitmask of BIT(component->id) for the supported inputs/outputs + * bitmask of BIT(component->id) for the supported inputs/outputs, * describes the possibilities of how a component is linked into a * pipeline. */ u32 supported_inputs; + /** @supported_outputs: bitmask of supported output componenet ids */ u32 supported_outputs;
/** @@ -134,7 +137,8 @@ struct komeda_component { struct komeda_component_output { /** @component: indicate which component the data comes from */ struct komeda_component *component; - /** @output_port: + /** + * @output_port: * the output port of the &komeda_component_output.component */ u8 output_port; @@ -150,11 +154,12 @@ struct komeda_component_output { struct komeda_component_state { /** @obj: tracking component_state by drm_atomic_state */ struct drm_private_state obj; + /** @component: backpointer to the component */ struct komeda_component *component; /** * @binding_user: - * currently bound user, the user can be crtc/plane/wb_conn, which is - * valid decided by @component and @inputs + * currently bound user, the user can be @crtc, @plane or @wb_conn, + * which is valid decided by @component and @inputs * * - Layer: its user always is plane. * - compiz/improc/timing_ctrlr: the user is crtc. @@ -162,20 +167,24 @@ struct komeda_component_state { * - scaler: plane when input is layer, wb_conn if input is compiz. */ union { + /** @crtc: backpointer for user crtc */ struct drm_crtc *crtc; + /** @plane: backpointer for user plane */ struct drm_plane *plane; + /** @wb_conn: backpointer for user wb_connector */ struct drm_connector *wb_conn; void *binding_user; }; + /** * @active_inputs: * * active_inputs is bitmask of @inputs index * - * - active_inputs = changed_active_inputs + unchanged_active_inputs - * - affected_inputs = old->active_inputs + new->active_inputs; + * - active_inputs = changed_active_inputs | unchanged_active_inputs + * - affected_inputs = old->active_inputs | new->active_inputs; * - disabling_inputs = affected_inputs ^ active_inputs; - * - changed_inputs = disabling_inputs + changed_active_inputs; + * - changed_inputs = disabling_inputs | changed_active_inputs; * * NOTE: * changed_inputs doesn't include all active_input but only @@ -183,7 +192,9 @@ struct komeda_component_state { * level for dirty update. */ u16 active_inputs; + /** @changed_active_inputs: bitmask of the changed @active_inputs */ u16 changed_active_inputs; + /** @affected_inputs: bitmask for affected @inputs */ u16 affected_inputs; /** * @inputs: @@ -319,14 +330,23 @@ struct komeda_pipeline { int id; /** @avail_comps: available components mask of pipeline */ u32 avail_comps; + /** @n_layers: the number of layer on @layers */ int n_layers; + /** @layers: the pipeline layers */ struct komeda_layer *layers[KOMEDA_PIPELINE_MAX_LAYERS]; + /** @n_scalers: the number of scaler on @scalers */ int n_scalers; + /** @scalers: the pipeline scalers */ struct komeda_scaler *scalers[KOMEDA_PIPELINE_MAX_SCALERS]; + /** @compiz: compositor */ struct komeda_compiz *compiz; + /** @wb_layer: writeback layer */ struct komeda_layer *wb_layer; + /** @improc: post image processor */ struct komeda_improc *improc; + /** @ctrlr: timing controller */ struct komeda_timing_ctrlr *ctrlr; + /** @funcs: chip pipeline functions */ struct komeda_pipeline_funcs *funcs; /* private pipeline functions */
/** @of_node: pipeline dt node */ @@ -347,6 +367,7 @@ struct komeda_pipeline { struct komeda_pipeline_state { /** @obj: tracking pipeline_state by drm_atomic_state */ struct drm_private_state obj; + /** @pipe: backpointer to the pipeline */ struct komeda_pipeline *pipe; /** @crtc: currently bound crtc */ struct drm_crtc *crtc; diff --git a/drivers/gpu/drm/arm/display/komeda/komeda_plane.c b/drivers/gpu/drm/arm/display/komeda/komeda_plane.c index af51f0cc9c16..68cd2c9e53e8 100644 --- a/drivers/gpu/drm/arm/display/komeda/komeda_plane.c +++ b/drivers/gpu/drm/arm/display/komeda/komeda_plane.c @@ -38,6 +38,14 @@ komeda_plane_init_data_flow(struct drm_plane_state *st, return 0; }
+/** + * komeda_plane_atomic_check - build input data flow + * @plane: DRM plane + * @state: the plane state object + * + * RETURNS: + * Zero for success or -errno + */ int komeda_plane_atomic_check(struct drm_plane *plane, struct drm_plane_state *state) {