From 72f793f14afcec9697fadb8cd4e5d33327b108cd Mon Sep 17 00:00:00 2001 From: Eric Anholt Date: Mon, 27 Feb 2017 12:11:41 -0800 Subject: [PATCH] drm/vc4: Convert existing documentation to actual kerneldoc. I'm going to hook vc4 up to the sphinx build, so clean up its comments to not generate warnings when we do. Signed-off-by: Eric Anholt Acked-by: Daniel Vetter Link: http://patchwork.freedesktop.org/patch/msgid/20170227201144.10970-2-eric@anholt.net --- drivers/gpu/drm/vc4/vc4_bo.c | 5 ++++- drivers/gpu/drm/vc4/vc4_dsi.c | 5 +++-- drivers/gpu/drm/vc4/vc4_gem.c | 26 +++++++++++++++++++++----- drivers/gpu/drm/vc4/vc4_irq.c | 3 ++- drivers/gpu/drm/vc4/vc4_validate.c | 10 +++++++--- 5 files changed, 37 insertions(+), 12 deletions(-) diff --git a/drivers/gpu/drm/vc4/vc4_bo.c b/drivers/gpu/drm/vc4/vc4_bo.c index 3f6704cf6608..7abcd9c5dbe2 100644 --- a/drivers/gpu/drm/vc4/vc4_bo.c +++ b/drivers/gpu/drm/vc4/vc4_bo.c @@ -6,7 +6,8 @@ * published by the Free Software Foundation. */ -/* DOC: VC4 GEM BO management support. +/** + * DOC: VC4 GEM BO management support * * The VC4 GPU architecture (both scanout and rendering) has direct * access to system memory with no MMU in between. To support it, we @@ -186,6 +187,8 @@ out: /** * vc4_gem_create_object - Implementation of driver->gem_create_object. + * @dev: DRM device + * @size: Size in bytes of the memory the object will reference * * This lets the CMA helpers allocate object structs for us, and keep * our BO stats correct. diff --git a/drivers/gpu/drm/vc4/vc4_dsi.c b/drivers/gpu/drm/vc4/vc4_dsi.c index e328cb86469c..160f981d1cf4 100644 --- a/drivers/gpu/drm/vc4/vc4_dsi.c +++ b/drivers/gpu/drm/vc4/vc4_dsi.c @@ -1453,8 +1453,9 @@ static irqreturn_t vc4_dsi_irq_handler(int irq, void *data) } /** - * Exposes clocks generated by the analog PHY that are consumed by - * CPRMAN (clk-bcm2835.c). + * vc4_dsi_init_phy_clocks - Exposes clocks generated by the analog + * PHY that are consumed by CPRMAN (clk-bcm2835.c). + * @dsi: DSI encoder */ static int vc4_dsi_init_phy_clocks(struct vc4_dsi *dsi) diff --git a/drivers/gpu/drm/vc4/vc4_gem.c b/drivers/gpu/drm/vc4/vc4_gem.c index ab3016982466..d962000184ee 100644 --- a/drivers/gpu/drm/vc4/vc4_gem.c +++ b/drivers/gpu/drm/vc4/vc4_gem.c @@ -511,9 +511,18 @@ vc4_queue_submit(struct drm_device *dev, struct vc4_exec_info *exec) } /** - * Looks up a bunch of GEM handles for BOs and stores the array for - * use in the command validator that actually writes relocated - * addresses pointing to them. + * vc4_cl_lookup_bos() - Sets up exec->bo[] with the GEM objects + * referenced by the job. + * @dev: DRM device + * @file_priv: DRM file for this fd + * @exec: V3D job being set up + * + * The command validator needs to reference BOs by their index within + * the submitted job's BO list. This does the validation of the job's + * BO list and reference counting for the lifetime of the job. + * + * Note that this function doesn't need to unreference the BOs on + * failure, because that will happen at vc4_complete_exec() time. */ static int vc4_cl_lookup_bos(struct drm_device *dev, @@ -846,9 +855,16 @@ vc4_wait_bo_ioctl(struct drm_device *dev, void *data, } /** - * Submits a command list to the VC4. + * vc4_submit_cl_ioctl() - Submits a job (frame) to the VC4. + * @dev: DRM device + * @data: ioctl argument + * @file_priv: DRM file for this fd * - * This is what is called batchbuffer emitting on other hardware. + * This is the main entrypoint for userspace to submit a 3D frame to + * the GPU. Userspace provides the binner command list (if + * applicable), and the kernel sets up the render command list to draw + * to the framebuffer described in the ioctl, using the command lists + * that the 3D engine's binner will produce. */ int vc4_submit_cl_ioctl(struct drm_device *dev, void *data, diff --git a/drivers/gpu/drm/vc4/vc4_irq.c b/drivers/gpu/drm/vc4/vc4_irq.c index 094bc6a475c1..cdc6e6760705 100644 --- a/drivers/gpu/drm/vc4/vc4_irq.c +++ b/drivers/gpu/drm/vc4/vc4_irq.c @@ -21,7 +21,8 @@ * IN THE SOFTWARE. */ -/** DOC: Interrupt management for the V3D engine. +/** + * DOC: Interrupt management for the V3D engine * * We have an interrupt status register (V3D_INTCTL) which reports * interrupts, and where writing 1 bits clears those interrupts. diff --git a/drivers/gpu/drm/vc4/vc4_validate.c b/drivers/gpu/drm/vc4/vc4_validate.c index 9fd171c361c2..d696ed49e9f0 100644 --- a/drivers/gpu/drm/vc4/vc4_validate.c +++ b/drivers/gpu/drm/vc4/vc4_validate.c @@ -22,7 +22,7 @@ */ /** - * Command list validator for VC4. + * DOC: Command list validator for VC4. * * The VC4 has no IOMMU between it and system memory. So, a user with * access to execute command lists could escalate privilege by @@ -84,8 +84,12 @@ utile_height(int cpp) } /** - * The texture unit decides what tiling format a particular miplevel is using - * this function, so we lay out our miptrees accordingly. + * size_is_lt() - Returns whether a miplevel of the given size will + * use the lineartile (LT) tiling layout rather than the normal T + * tiling layout. + * @width: Width in pixels of the miplevel + * @height: Height in pixels of the miplevel + * @cpp: Bytes per pixel of the pixel format */ static bool size_is_lt(uint32_t width, uint32_t height, int cpp) -- 2.20.1