vc4 RST documentation
Subsystems (4)
cover vc4 RST documentation
danvet asked me a while ago to try generating documentation with the new RST-based infrastructure. I had a couple of hours to do some editing, so here it is.
So far I'm not including any kerneldoc for functions. I don't think I have enough documentation coverage yet to make it useful to start including the current ones in the output.
Eric Anholt (4):
drm/vc4: Convert existing documentation to actual kerneldoc. drm/vc4: Add RST to bring together vc4 kerneldoc. drm/vc4: Extend and edit documentation for output from the RST drm/vc4: Add a paragraph at the top of vc4 docs introducing what it
is.
Documentation/gpu/index.rst | 1 + Documentation/gpu/vc4.rst | 89 ++++++++++++++++++++++++++++++ drivers/gpu/drm/vc4/vc4_bo.c | 5 +- drivers/gpu/drm/vc4/vc4_crtc.c | 7 ++- drivers/gpu/drm/vc4/vc4_dpi.c | 3 +- drivers/gpu/drm/vc4/vc4_drv.c | 16 ++++++ drivers/gpu/drm/vc4/vc4_dsi.c | 5 +- drivers/gpu/drm/vc4/vc4_gem.c | 26 +++++++-- drivers/gpu/drm/vc4/vc4_hdmi.c | 23 +++++++- drivers/gpu/drm/vc4/vc4_hvs.c | 12 ++-- drivers/gpu/drm/vc4/vc4_irq.c | 3 +- drivers/gpu/drm/vc4/vc4_render_cl.c | 4 ++ drivers/gpu/drm/vc4/vc4_validate.c | 34 +++++++----- drivers/gpu/drm/vc4/vc4_validate_shaders.c | 21 ++++--- drivers/gpu/drm/vc4/vc4_vec.c | 6 ++ 15 files changed, 212 insertions(+), 43 deletions(-) create mode 100644 Documentation/gpu/vc4.rst
Signature · 6 lines
2.11.0 _______________________________________________ dri-devel mailing list [email protected] https://lists.freedesktop.org/mailman/listinfo/dri-devel
PATCH 1/4 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.
--- 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(-)
drivers/gpu/drm/vc4/vc4_bo.c +4 -1
@@ -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 @@ static struct vc4_bo *vc4_bo_get_from_cache(struct drm_device *dev,/** * 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.
drivers/gpu/drm/vc4/vc4_dsi.c +3 -2
@@ -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)
drivers/gpu/drm/vc4/vc4_gem.c +21 -5
@@ -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,
@@ -844,9 +853,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,
drivers/gpu/drm/vc4/vc4_irq.c +2 -1
@@ -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.
drivers/gpu/drm/vc4/vc4_validate.c +7 -3
@@ -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)
Signature · 6 lines
2.11.0 _______________________________________________ dri-devel mailing list [email protected] https://lists.freedesktop.org/mailman/listinfo/dri-devel
PATCH 2/4 drm/vc4: Add RST to bring together vc4 kerneldoc.
In reply to Eric AnholtThis doesn't yet produce coherent documentation of the module, but at least gets the kerneldoc built and somewhat glued together.
--- Documentation/gpu/index.rst | 1 + Documentation/gpu/vc4.rst | 86 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 87 insertions(+) create mode 100644 Documentation/gpu/vc4.rst
Documentation/gpu/index.rst +1 -0
@@ -11,6 +11,7 @@ Linux GPU Driver Developer's Guide drm-kms-helpers drm-uapi i915 + vc4 vga-switcheroo vgaarbiter todo
Documentation/gpu/vc4.rst new file +86 -0
86 lines not on this page · raw message
Signature · 6 lines
2.11.0 _______________________________________________ dri-devel mailing list [email protected] https://lists.freedesktop.org/mailman/listinfo/dri-devel
PATCH 3/4 drm/vc4: Extend and edit documentation for output from the RST
In reply to Eric AnholtI had written most of my comments as if I was describing the individual code files the way I used to for doxygen, while for RST we want to describe things in a more chapter/section way where there's no obvious relation to .c files.
Additionally, several of the files had stub descriptions that I've taken this opportunity to extend.
--- drivers/gpu/drm/vc4/vc4_crtc.c | 7 ++++--- drivers/gpu/drm/vc4/vc4_dpi.c | 3 ++- drivers/gpu/drm/vc4/vc4_hdmi.c | 23 ++++++++++++++++++++--- drivers/gpu/drm/vc4/vc4_hvs.c | 12 ++++++------ drivers/gpu/drm/vc4/vc4_render_cl.c | 4 ++++ drivers/gpu/drm/vc4/vc4_validate.c | 24 ++++++++++++++---------- drivers/gpu/drm/vc4/vc4_validate_shaders.c | 21 +++++++++++++-------- drivers/gpu/drm/vc4/vc4_vec.c | 6 ++++++ 8 files changed, 69 insertions(+), 31 deletions(-)
drivers/gpu/drm/vc4/vc4_crtc.c +4 -3
@@ -11,12 +11,13 @@* * In VC4, the Pixel Valve is what most closely corresponds to the * DRM's concept of a CRTC. The PV generates video timings from the -* output's clock plus its configuration. It pulls scaled pixels from +* encoder's clock plus its configuration. It pulls scaled pixels from * the HVS at that timing, and feeds it to the encoder. * * However, the DRM CRTC also collects the configuration of all the -* DRM planes attached to it. As a result, this file also manages -* setup of the VC4 HVS's display elements on the CRTC. +* DRM planes attached to it. As a result, the CRTC is also +* responsible for writing the display list for the HVS channel that +* the CRTC will use. * * The 2835 has 3 different pixel valves. pv0 in the audio power * domain feeds DSI0 or DPI, while pv1 feeds DS1 or SMI. pv2 in the
drivers/gpu/drm/vc4/vc4_dpi.c +2 -1
@@ -18,7 +18,8 @@* DOC: VC4 DPI module * * The VC4 DPI hardware supports MIPI DPI type 4 and Nokia ViSSI -* signals, which are routed out to GPIO0-27 with the ALT2 function. +* signals. On BCM2835, these can be routed out to GPIO0-27 with the +* ALT2 function. */ #include "drm_atomic_helper.h"
drivers/gpu/drm/vc4/vc4_hdmi.c +20 -3
@@ -20,9 +20,26 @@/** * DOC: VC4 Falcon HDMI module * -* The HDMI core has a state machine and a PHY. Most of the unit -* operates off of the HSM clock from CPRMAN. It also internally uses -* the PLLH_PIX clock for the PHY. +* The HDMI core has a state machine and a PHY. On BCM2835, most of +* the unit operates off of the HSM clock from CPRMAN. It also +* internally uses the PLLH_PIX clock for the PHY. +* +* HDMI infoframes are kept within a small packet ram, where each +* packet can be individually enabled for including in a frame. +* +* HDMI audio is implemented entirely within the HDMI IP block. A +* register in the HDMI encoder takes SPDIF frames from the DMA engine +* and transfers them over an internal MAI (multi-channel audio +* interconnect) bus to the encoder side for insertion into the video +* blank regions. +* +* The driver's HDMI encoder does not yet support power management. +* The HDMI encoder's power domain and the HSM/pixel clocks are kept +* continuously running, and only the HDMI logic and packet ram are +* powered off/on at disable/enable time. +* +* The driver does not yet support CEC control, though the HDMI +* encoder block has CEC support. */ #include "drm_atomic_helper.h"
drivers/gpu/drm/vc4/vc4_hvs.c +6 -6
@@ -9,12 +9,12 @@/** * DOC: VC4 HVS module. * -* The HVS is the piece of hardware that does translation, scaling, -* colorspace conversion, and compositing of pixels stored in -* framebuffers into a FIFO of pixels going out to the Pixel Valve -* (CRTC). It operates at the system clock rate (the system audio -* clock gate, specifically), which is much higher than the pixel -* clock rate. +* The Hardware Video Scaler (HVS) is the piece of hardware that does +* translation, scaling, colorspace conversion, and compositing of +* pixels stored in framebuffers into a FIFO of pixels going out to +* the Pixel Valve (CRTC). It operates at the system clock rate (the +* system audio clock gate, specifically), which is much higher than +* the pixel clock rate. * * There is a single global HVS, with multiple output FIFOs that can * be consumed by the PVs. This file just manages the resources for
drivers/gpu/drm/vc4/vc4_render_cl.c +4 -0
@@ -24,6 +24,10 @@/** * DOC: Render command list generation * +* In the V3D hardware, render command lists are what load and store +* tiles of a framebuffer and optionally call out to binner-generated +* command lists to do the 3D drawing for that tile. +* * In the VC4 driver, render command list generation is performed by the * kernel instead of userspace. We do this because validating a * user-submitted command list is hard to get right and has high CPU overhead,
drivers/gpu/drm/vc4/vc4_validate.c +14 -10
@@ -24,19 +24,23 @@/** * 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 +* Since the VC4 has no IOMMU between it and system memory, a user +* with access to execute command lists could escalate privilege by * overwriting system memory (drawing to it as a framebuffer) or -* reading system memory it shouldn't (reading it as a texture, or -* uniform data, or vertex data). +* reading system memory it shouldn't (reading it as a vertex buffer +* or index buffer) * -* This validates command lists to ensure that all accesses are within -* the bounds of the GEM objects referenced. It explicitly whitelists -* packets, and looks at the offsets in any address fields to make -* sure they're constrained within the BOs they reference. +* We validate binner command lists to ensure that all accesses are +* within the bounds of the GEM objects referenced by the submitted +* job. It explicitly whitelists packets, and looks at the offsets in +* any address fields to make sure they're contained within the BOs +* they reference. * -* Note that because of the validation that's happening anyway, this -* is where GEM relocation processing happens. +* Note that because CL validation is already reading the +* user-submitted CL and writing the validated copy out to the memory +* that the GPU will actually read, this is also where GEM relocation +* processing (turning BO references into actual addresses for the GPU +* to use) happens. */ #include "uapi/drm/vc4_drm.h"
drivers/gpu/drm/vc4/vc4_validate_shaders.c +13 -8
@@ -24,16 +24,21 @@/** * DOC: Shader validator for VC4. * -* The VC4 has no IOMMU between it and system memory, so a user with -* access to execute shaders could escalate privilege by overwriting -* system memory (using the VPM write address register in the -* general-purpose DMA mode) or reading system memory it shouldn't -* (reading it as a texture, or uniform data, or vertex data). +* Since the VC4 has no IOMMU between it and system memory, a user +* with access to execute shaders could escalate privilege by +* overwriting system memory (using the VPM write address register in +* the general-purpose DMA mode) or reading system memory it shouldn't +* (reading it as a texture, uniform data, or direct-addressed TMU +* lookup). * -* This walks over a shader BO, ensuring that its accesses are -* appropriately bounded, and recording how many texture accesses are -* made and where so that we can do relocations for them in the +* The shader validator walks over a shader's BO, ensuring that its +* accesses are appropriately bounded, and recording where texture +* accesses are made so that we can do relocations for them in the * uniform stream. +* +* Shader BO are immutable for their lifetimes (enforced by not +* allowing mmaps, GEM prime export, or rendering to from a CL), so +* this validation is only performed at BO creation time. */ #include "vc4_drv.h"
drivers/gpu/drm/vc4/vc4_vec.c +6 -0
@@ -16,6 +16,12 @@/** * DOC: VC4 SDTV module +* +* The VEC encoder generates PAL or NTSC composite video output. +* +* TV mode selection is done by an atomic property on the encoder, +* because a drm_mode_modeinfo is insufficient to distinguish between +* PAL and PAL-M or NTSC and NTSC-J. */ #include <drm/drm_atomic_helper.h>
Signature · 6 lines
2.11.0 _______________________________________________ dri-devel mailing list [email protected] https://lists.freedesktop.org/mailman/listinfo/dri-devel
PATCH 4/4 drm/vc4: Add a paragraph at the top of vc4 docs introducing what it is.
In reply to Eric AnholtThis makes for more sensible documentation of the whole module than jumping straight into the details of display.
--- Documentation/gpu/vc4.rst | 3 +++ drivers/gpu/drm/vc4/vc4_drv.c | 16 ++++++++++++++++ 2 files changed, 19 insertions(+)
Documentation/gpu/vc4.rst +3 -0
@@ -2,6 +2,9 @@ drm/vc4 Broadcom VC4 Graphics Driver ===================================== +.. kernel-doc:: drivers/gpu/drm/vc4/vc4_drv.c + :doc: Broadcom VC4 Graphics Driver + Display Hardware Handling =========================
drivers/gpu/drm/vc4/vc4_drv.c +16 -0
@@ -7,6 +7,22 @@* published by the Free Software Foundation. */ +/** +* DOC: Broadcom VC4 Graphics Driver +* +* The Broadcom VideoCore 4 (present in the Raspberry Pi) contains a +* OpenGL ES 2.0-compatible 3D engine called V3D, and a highly +* configurable display output pipeline that supports HDMI, DSI, DPI, +* and Composite TV output. +* +* The 3D engine also has an interface for submitting arbitrary +* compute shader-style jobs using the same shader processor as is +* used for vertex and fragment shaders in GLES 2.0. However, given +* that the hardware isn't able to expose any standard interfaces like +* OpenGL compute shaders or OpenCL, it isn't supported by this +* driver. +*/ +#include <linux/clk.h> #include <linux/component.h> #include <linux/device.h>
Signature · 6 lines
2.11.0 _______________________________________________ dri-devel mailing list [email protected] https://lists.freedesktop.org/mailman/listinfo/dri-devel
Quoted 8 lines · Eric Anholt
danvet asked me a while ago to try generating documentation with the new RST-based infrastructure. I had a couple of hours to do some editing, so here it is.
So far I'm not including any kerneldoc for functions. I don't think I have enough documentation coverage yet to make it useful to start including the current ones in the output.
Quoted 6 lines
Eric Anholt (4):
drm/vc4: Convert existing documentation to actual kerneldoc. drm/vc4: Add RST to bring together vc4 kerneldoc. drm/vc4: Extend and edit documentation for output from the RST drm/vc4: Add a paragraph at the top of vc4 docs introducing what itis.
Wooohooooo, this is sweet! I know it's just a rough just, but I think i915 is even rougher, and we just need to get going somewhere. Really awesome. On the series:
Quoted 26 lines
Documentation/gpu/index.rst | 1 + Documentation/gpu/vc4.rst | 89 ++++++++++++++++++++++++++++++ drivers/gpu/drm/vc4/vc4_bo.c | 5 +- drivers/gpu/drm/vc4/vc4_crtc.c | 7 ++- drivers/gpu/drm/vc4/vc4_dpi.c | 3 +- drivers/gpu/drm/vc4/vc4_drv.c | 16 ++++++ drivers/gpu/drm/vc4/vc4_dsi.c | 5 +- drivers/gpu/drm/vc4/vc4_gem.c | 26 +++++++-- drivers/gpu/drm/vc4/vc4_hdmi.c | 23 +++++++- drivers/gpu/drm/vc4/vc4_hvs.c | 12 ++-- drivers/gpu/drm/vc4/vc4_irq.c | 3 +- drivers/gpu/drm/vc4/vc4_render_cl.c | 4 ++ drivers/gpu/drm/vc4/vc4_validate.c | 34 +++++++----- drivers/gpu/drm/vc4/vc4_validate_shaders.c | 21 ++++--- drivers/gpu/drm/vc4/vc4_vec.c | 6 ++ 15 files changed, 212 insertions(+), 43 deletions(-) create mode 100644 Documentation/gpu/vc4.rstSignature · 6 lines
2.11.0 _______________________________________________ dri-devel mailing list [email protected] https://lists.freedesktop.org/mailman/listinfo/dri-devel
Signature · 7 lines
Daniel Vetter Software Engineer, Intel Corporation http://blog.ffwll.ch _______________________________________________ dri-devel mailing list [email protected] https://lists.freedesktop.org/mailman/listinfo/dri-devel
Quoted 16 lines · Daniel Vetter
Quoted 8 lines · Eric Anholt
danvet asked me a while ago to try generating documentation with the new RST-based infrastructure. I had a couple of hours to do some editing, so here it is.
So far I'm not including any kerneldoc for functions. I don't think I have enough documentation coverage yet to make it useful to start including the current ones in the output.
Quoted 6 lines
Eric Anholt (4):
drm/vc4: Convert existing documentation to actual kerneldoc. drm/vc4: Add RST to bring together vc4 kerneldoc. drm/vc4: Extend and edit documentation for output from the RST drm/vc4: Add a paragraph at the top of vc4 docs introducing what itis.
Quoted 5 lines
Wooohooooo, this is sweet! I know it's just a rough just, but I think i915 is even rougher, and we just need to get going somewhere. Really awesome. On the series:
Acked-by Daniel Vetter <[email protected]>
Getting started on this was easy enough, I'm definitely hoping to do more.
Applied the ack and pushed. Thanks!
_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel