[RFC PATCH 0/2] drm/meson: RST Documentation

[RFC PATCH 0/2] drm/meson: RST Documentation

[Neil Armstrong]

To be aligned with the other DRM drivers, this patchset converts the
actual drivers documentation to RST format, adds a top RTS meson file
and adds an entry in the gpu/index.rst file.

This patchser depends on the HDMI patchset at [1]

Sample output can be found at [2]

[2] http://people.freedesktop.org/~narmstrong/meson_drm_doc/gpu/meson.html
[1] http://lkml.kernel.org/r/1488469207-523-1-git-send-email-narmstrong@baylibre.com

Neil Armstrong (2):
  drm/meson: Convert existing documentation to actual kerneldoc
  drm/meson: Add RST to bring together kerneldoc

 Documentation/gpu/index.rst           |  1 +
 Documentation/gpu/meson.rst           | 61 +++++++++++++++++++++++++++++++++++
 drivers/gpu/drm/meson/meson_canvas.c  |  4 ++-
 drivers/gpu/drm/meson/meson_drv.c     |  5 +--
 drivers/gpu/drm/meson/meson_dw_hdmi.c | 25 +++++++++-----
 drivers/gpu/drm/meson/meson_vclk.c    | 22 +++++++++----
 drivers/gpu/drm/meson/meson_venc.c    | 25 ++++++++------
 drivers/gpu/drm/meson/meson_viu.c     |  6 +++-
 drivers/gpu/drm/meson/meson_vpp.c     |  8 +++--
 9 files changed, 127 insertions(+), 30 deletions(-)
 create mode 100644 Documentation/gpu/meson.rst

-- 
1.9.1

[RFC PATCH 1/2] drm/meson: Convert existing documentation to actual kerneldoc

[Neil Armstrong]

Signed-off-by: Neil Armstrong <narmstrong@baylibre.com>
---
 drivers/gpu/drm/meson/meson_canvas.c  |  4 +++-
 drivers/gpu/drm/meson/meson_drv.c     |  5 +++--
 drivers/gpu/drm/meson/meson_dw_hdmi.c | 25 +++++++++++++++++--------
 drivers/gpu/drm/meson/meson_vclk.c    | 22 +++++++++++++++-------
 drivers/gpu/drm/meson/meson_venc.c    | 25 ++++++++++++++++---------
 drivers/gpu/drm/meson/meson_viu.c     |  6 +++++-
 drivers/gpu/drm/meson/meson_vpp.c     |  8 ++++++--
 7 files changed, 65 insertions(+), 30 deletions(-)

diff --git a/drivers/gpu/drm/meson/meson_canvas.c b/drivers/gpu/drm/meson/meson_canvas.c
index 4109e36..08f6073 100644
--- a/drivers/gpu/drm/meson/meson_canvas.c
+++ b/drivers/gpu/drm/meson/meson_canvas.c
@@ -24,7 +24,9 @@
 #include "meson_canvas.h"
 #include "meson_registers.h"
 
-/*
+/**
+ * DOC: Canvas
+ *
  * CANVAS is a memory zone where physical memory frames information
  * are stored for the VIU to scanout.
  */
diff --git a/drivers/gpu/drm/meson/meson_drv.c b/drivers/gpu/drm/meson/meson_drv.c
index f381088..a3f6b79 100644
--- a/drivers/gpu/drm/meson/meson_drv.c
+++ b/drivers/gpu/drm/meson/meson_drv.c
@@ -52,13 +52,14 @@
 #define DRIVER_NAME "meson"
 #define DRIVER_DESC "Amlogic Meson DRM driver"
 
-/*
- * Video Processing Unit
+/**
+ * DOC: Video Processing Unit
  *
  * VPU Handles the Global Video Processing, it includes management of the
  * clocks gates, blocks reset lines and power domains.
  *
  * What is missing :
+ *
  * - Full reset of entire video processing HW blocks
  * - Scaling and setup of the VPU clock
  * - Bus clock gates
diff --git a/drivers/gpu/drm/meson/meson_dw_hdmi.c b/drivers/gpu/drm/meson/meson_dw_hdmi.c
index 3250140..21f18c3 100644
--- a/drivers/gpu/drm/meson/meson_dw_hdmi.c
+++ b/drivers/gpu/drm/meson/meson_dw_hdmi.c
@@ -39,18 +39,25 @@
 #define DRIVER_NAME "meson-dw-hdmi"
 #define DRIVER_DESC "Amlogic Meson HDMI-TX DRM driver"
 
-/*
+/**
+ * DOC: HDMI Output
+ *
  * HDMI Output is composed of :
+ *
  * - A Synopsys DesignWare HDMI Controller IP
  * - A TOP control block controlling the Clocks and PHY
  * - A custom HDMI PHY in order convert video to TMDS signal
- *  ___________________________________
- * |            HDMI TOP               |<= HPD
- * |___________________________________|
- * |                  |                |
- * |  Synopsys HDMI   |   HDMI PHY     |=> TMDS
- * |    Controller    |________________|
- * |___________________________________|<=> DDC
+ *
+ * .. code::
+ *
+ *    ___________________________________
+ *   |            HDMI TOP               |<= HPD
+ *   |___________________________________|
+ *   |                  |                |
+ *   |  Synopsys HDMI   |   HDMI PHY     |=> TMDS
+ *   |    Controller    |________________|
+ *   |___________________________________|<=> DDC
+ *
  *
  * The HDMI TOP block only supports HPD sensing.
  * The Synopsys HDMI Controller interrupt is routed
@@ -75,6 +82,7 @@
  * audio source interfaces.
  *
  * We handle the following features :
+ *
  * - HPD Rise & Fall interrupt
  * - HDMI Controller Interrupt
  * - HDMI PHY Init for 480i to 1080p60
@@ -82,6 +90,7 @@
  * - VENC Mode setup for 480i to 1080p60
  *
  * What is missing :
+ *
  * - PHY, Clock and Mode setup for 2k && 4k modes
  * - SDDC Scrambling mode for HDMI 2.0a
  * - HDCP Setup
diff --git a/drivers/gpu/drm/meson/meson_vclk.c b/drivers/gpu/drm/meson/meson_vclk.c
index 45cf1f6..a096571 100644
--- a/drivers/gpu/drm/meson/meson_vclk.c
+++ b/drivers/gpu/drm/meson/meson_vclk.c
@@ -23,21 +23,29 @@
 #include "meson_drv.h"
 #include "meson_vclk.h"
 
-/*
+/**
+ * DOC: Video Clocks
+ *
  * VCLK is the "Pixel Clock" frequency generator from a dedicated PLL.
  * We handle the following encodings :
+ *
  * - CVBS 27MHz generator via the VCLK2 to the VENCI and VDAC blocks
  * - HDMI Pixel Clocks generation
+ *
  * What is missing :
+ *
  * - Genenate Pixel clocks for 2K/4K 10bit formats
  *
  * Clock generator scheme :
- *  __________   _________            _____
- * |          | |         |          |     |--ENCI
- * | HDMI PLL |-| PLL_DIV |--- VCLK--|     |--ENCL
- * |__________| |_________| \        | MUX |--ENCP
- *                           --VCLK2-|     |--VDAC
- *                                   |_____|--HDMI-TX
+ *
+ * .. code::
+ *
+ *    __________   _________            _____
+ *   |          | |         |          |     |--ENCI
+ *   | HDMI PLL |-| PLL_DIV |--- VCLK--|     |--ENCL
+ *   |__________| |_________| \        | MUX |--ENCP
+ *                             --VCLK2-|     |--VDAC
+ *                                     |_____|--HDMI-TX
  *
  * Final clocks can take input for either VCLK or VCLK2, but
  * VCLK is the preferred path for HDMI clocking and VCLK2 is the
diff --git a/drivers/gpu/drm/meson/meson_venc.c b/drivers/gpu/drm/meson/meson_venc.c
index 31dc275..9509017 100644
--- a/drivers/gpu/drm/meson/meson_venc.c
+++ b/drivers/gpu/drm/meson/meson_venc.c
@@ -26,26 +26,33 @@
 #include "meson_vclk.h"
 #include "meson_registers.h"
 
-/*
+/**
+ * DOC: Video Encoder
+ *
  * VENC Handle the pixels encoding to the output formats.
  * We handle the following encodings :
+ *
  * - CVBS Encoding via the ENCI encoder and VDAC digital to analog converter
  * - TMDS/HDMI Encoding via ENCI_DIV and ENCP
  * - Setup of more clock rates for HDMI modes
  *
  * What is missing :
+ *
  * - LCD Panel encoding via ENCL
  * - TV Panel encoding via ENCT
  *
  * VENC paths :
- *        _____   _____   ____________________
- * vd1---|     |-|     | | VENC     /---------|----VDAC
- * vd2---| VIU |-| VPP |-|-----ENCI/-ENCI_DVI-|\
- * osd1--|     |-|     | | \                  | X--HDMI-TX
- * osd2--|_____|-|_____| |  |\-ENCP--ENCP_DVI-|/
- *                       |  |                 |
- *                       |  \--ENCL-----------|----LVDS
- *                       |____________________|
+ *
+ * .. code::
+ *
+ *          _____   _____   ____________________
+ *   vd1---|     |-|     | | VENC     /---------|----VDAC
+ *   vd2---| VIU |-| VPP |-|-----ENCI/-ENCI_DVI-|-|
+ *   osd1--|     |-|     | | \                  | X--HDMI-TX
+ *   osd2--|_____|-|_____| |  |\-ENCP--ENCP_DVI-|-|
+ *                         |  |                 |
+ *                         |  \--ENCL-----------|----LVDS
+ *                         |____________________|
  *
  * The ENCI is designed for PAl or NTSC encoding and can go through the VDAC
  * directly for CVBS encoding or through the ENCI_DVI encoder for HDMI.
diff --git a/drivers/gpu/drm/meson/meson_viu.c b/drivers/gpu/drm/meson/meson_viu.c
index a6de8ba..6bcfa52 100644
--- a/drivers/gpu/drm/meson/meson_viu.c
+++ b/drivers/gpu/drm/meson/meson_viu.c
@@ -28,9 +28,12 @@
 #include "meson_canvas.h"
 #include "meson_registers.h"
 
-/*
+/**
+ * DOC: Video Input Unit
+ *
  * VIU Handles the Pixel scanout and the basic Colorspace conversions
  * We handle the following features :
+ *
  * - OSD1 RGB565/RGB888/xRGB8888 scanout
  * - RGB conversion to x/cb/cr
  * - Progressive or Interlace buffer scanout
@@ -38,6 +41,7 @@
  * - HDR OSD matrix for GXL/GXM
  *
  * What is missing :
+ *
  * - BGR888/xBGR8888/BGRx8888/BGRx8888 modes
  * - YUV4:2:2 Y0CbY1Cr scanout
  * - Conversion to YUV 4:4:4 from 4:2:2 input
diff --git a/drivers/gpu/drm/meson/meson_vpp.c b/drivers/gpu/drm/meson/meson_vpp.c
index 671909d..27356f8 100644
--- a/drivers/gpu/drm/meson/meson_vpp.c
+++ b/drivers/gpu/drm/meson/meson_vpp.c
@@ -25,16 +25,20 @@
 #include "meson_vpp.h"
 #include "meson_registers.h"
 
-/*
+/**
+ * DOC: Video Post Processing
+ *
  * VPP Handles all the Post Processing after the Scanout from the VIU
  * We handle the following post processings :
- * - Postblend : Blends the OSD1 only
+ *
+ * - Postblend, Blends the OSD1 only
  *	We exclude OSD2, VS1, VS1 and Preblend output
  * - Vertical OSD Scaler for OSD1 only, we disable vertical scaler and
  *	use it only for interlace scanout
  * - Intermediate FIFO with default Amlogic values
  *
  * What is missing :
+ *
  * - Preblend for video overlay pre-scaling
  * - OSD2 support for cursor framebuffer
  * - Video pre-scaling before postblend
-- 
1.9.1

[RFC PATCH 2/2] drm/meson: Add RST to bring together kerneldoc

[Neil Armstrong]

Signed-off-by: Neil Armstrong <narmstrong@baylibre.com>
---
 Documentation/gpu/index.rst |  1 +
 Documentation/gpu/meson.rst | 61 +++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 62 insertions(+)
 create mode 100644 Documentation/gpu/meson.rst

diff --git a/Documentation/gpu/index.rst b/Documentation/gpu/index.rst
index e998ee0..7eceb97 100644
--- a/Documentation/gpu/index.rst
+++ b/Documentation/gpu/index.rst
@@ -11,6 +11,7 @@ Linux GPU Driver Developer's Guide
    drm-kms-helpers
    drm-uapi
    i915
+   meson
    tinydrm
    vc4
    vga-switcheroo
diff --git a/Documentation/gpu/meson.rst b/Documentation/gpu/meson.rst
new file mode 100644
index 0000000..479f6f5
--- /dev/null
+++ b/Documentation/gpu/meson.rst
@@ -0,0 +1,61 @@
+=============================================
+drm/meson AmLogic Meson Video Processing Unit
+=============================================
+
+.. kernel-doc:: drivers/gpu/drm/meson/meson_drv.c
+   :doc: Video Processing Unit
+
+Video Processing Unit
+=====================
+
+The Amlogic Meson Display controller is composed of several components
+that are going to be documented below:
+
+.. code::
+
+  DMC|---------------VPU (Video Processing Unit)----------------|------HHI------|
+     | vd1   _______     _____________    _________________     |               |
+  D  |-------|      |----|            |   |                |    |   HDMI PLL    |
+  D  | vd2   | VIU  |    | Video Post |   | Video Encoders |<---|-----VCLK      |
+  R  |-------|      |----| Processing |   |                |    |               |
+     | osd2  |      |    |            |---| Enci ----------|----|-----VDAC------|
+  R  |-------| CSC  |----| Scalers    |   | Encp ----------|----|----HDMI-TX----|
+  A  | osd1  |      |    | Blenders   |   | Encl ----------|----|---------------|
+  M  |-------|______|----|____________|   |________________|    |               |
+  ___|__________________________________________________________|_______________|
+
+Video Input Unit
+================
+
+.. kernel-doc:: drivers/gpu/drm/meson/meson_viu.c
+   :doc: Video Input Unit
+
+Video Post Processing
+=====================
+
+.. kernel-doc:: drivers/gpu/drm/meson/meson_vpp.c
+   :doc: Video Post Processing
+
+Video Encoder
+=============
+
+.. kernel-doc:: drivers/gpu/drm/meson/meson_venc.c
+   :doc: Video Encoder
+
+Video Canvas Management
+=======================
+
+.. kernel-doc:: drivers/gpu/drm/meson/meson_canvas.c
+   :doc: Canvas
+
+Video Clocks
+============
+
+.. kernel-doc:: drivers/gpu/drm/meson/meson_vclk.c
+   :doc: Video Clocks
+
+HDMI Video Output
+=================
+
+.. kernel-doc:: drivers/gpu/drm/meson/meson_dw_hdmi.c
+   :doc: HDMI Output
-- 
1.9.1