Skip to contentSkip to conversation

vc4 RST documentation

PATCH In review Eric Anholt 2 participants 7 messages Feb 27, 2017 – Feb 28, 2017

Subsystems (4)
lore
Share & tools
lore
#0 lore raw

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
#1 lore raw

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
index 3f6704cf6608..7abcd9c5dbe2 100644
@@ -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
index e328cb86469c..160f981d1cf4 100644
@@ -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
index db920771bfb5..79f0099d17d0 100644
@@ -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
index 094bc6a475c1..cdc6e6760705 100644
@@ -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
index 9fd171c361c2..d696ed49e9f0 100644
@@ -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
#2 lore raw

PATCH 2/4 drm/vc4: Add RST to bring together vc4 kerneldoc.

In reply to Eric Anholt

This 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
index c9b08b02f57c..8effecb947a6 100644
@@ -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
#3 lore raw

PATCH 3/4 drm/vc4: Extend and edit documentation for output from the RST

In reply to Eric Anholt

I 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
index 764320156cce..7fa4c3d5cddf 100644
@@ -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
index 3f360cf6cf5a..71435796c710 100644
@@ -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
index 93d5994f3a04..1be1e8304720 100644
@@ -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
index f7f7677f6d8d..fd421ba3c5d7 100644
@@ -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
index 08886a309757..8fc2fb461ac3 100644
@@ -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
index d696ed49e9f0..da6f1e138e8d 100644
@@ -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
index 5dba13dd1e9b..0b2df5c6efb4 100644
@@ -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
index 32bb8ef985fb..09c1e05765fa 100644
@@ -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
#4 lore raw

PATCH 4/4 drm/vc4: Add a paragraph at the top of vc4 docs introducing what it is.

In reply to Eric Anholt

This 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
index b06117b5d495..5df1d98b9544 100644
@@ -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
index 4f93328a2f20..205c1961ffb4 100644
@@ -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
Acked-by on the v1 series
#5 lore raw
In reply to Eric Anholt
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 it

    is.

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.rst
Signature · 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
#6 lore raw
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 it

    is.
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:

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