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...
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
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
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
dri-devel@lists.freedesktop.org
-
Neil Armstrong