[PATCH 2/2] drm/tegra: Add driver documentation

Mon Apr 10 12:05:15 UTC 2017

On Mon, Apr 10, 2017 at 12:27:02PM +0200, Thierry Reding wrote:
> From: Thierry Reding <treding at nvidia.com>
> 
> Adds some driver documentation for Tegra. It provides a short overview
> of the hardware and software architectures.
> 
> Signed-off-by: Thierry Reding <treding at nvidia.com>

Yay for docs! On both patches:

Acked-by: Daniel Vetter <daniel.vetter at ffwll.ch>
> ---
>  Documentation/gpu/index.rst |   1 +
>  Documentation/gpu/tegra.rst | 178 ++++++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 179 insertions(+)
>  create mode 100644 Documentation/gpu/tegra.rst
> 
> diff --git a/Documentation/gpu/index.rst b/Documentation/gpu/index.rst
> index c572f092739e..feae37fa7ca3 100644
> --- a/Documentation/gpu/index.rst
> +++ b/Documentation/gpu/index.rst
> @@ -12,6 +12,7 @@ Linux GPU Driver Developer's Guide
>     drm-uapi
>     i915
>     meson
> +   tegra
>     tinydrm
>     vc4
>     vga-switcheroo
> diff --git a/Documentation/gpu/tegra.rst b/Documentation/gpu/tegra.rst
> new file mode 100644
> index 000000000000..d2ed8938ca43
> --- /dev/null
> +++ b/Documentation/gpu/tegra.rst
> @@ -0,0 +1,178 @@
> +===============================================
> + drm/tegra NVIDIA Tegra GPU and display driver
> +===============================================
> +
> +NVIDIA Tegra SoCs support a set of display, graphics and video functions via
> +the host1x controller. host1x supplies command streams, gathered from a push
> +buffer provided directly by the CPU, to its clients via channels. Software,
> +or blocks amongst themselves, can use syncpoints for synchronization.
> +
> +Up until, but not including, Tegra124 (aka Tegra K1) the drm/tegra driver
> +supports the built-in GPU, comprised of the gr2d and gr3d engines. Starting
> +with Tegra124 the GPU is based on the NVIDIA desktop GPU architecture and
> +supported by the drm/nouveau driver.
> +
> +The drm/tegra driver supports NVIDIA Tegra SoC generations since Tegra20. It
> +has three parts:
> +
> +  - A host1x driver that provides infrastructure and access to the host1x
> +    services.
> +
> +  - A KMS driver that supports the display controllers as well as a number of
> +    outputs, such as RGB, HDMI, DSI, and DisplayPort.
> +
> +  - A set of custom userspace IOCTLs that can be used to submit jobs to the
> +    GPU and video engines via host1x.
> +
> +Driver Infrastructure
> +=====================
> +
> +The various host1x clients need to be bound together into a logical device in
> +order to expose their functionality to users. The infrastructure that supports
> +this is implemented in the host1x driver. When a driver is registered with the
> +infrastructure it provides a list of compatible strings specifying the devices
> +that it needs. The infrastructure creates a logical device and scan the device
> +tree for matching device nodes, adding the required clients to a list. Drivers
> +for individual clients register with the infrastructure as well and are added
> +to the logical host1x device.
> +
> +Once all clients are available, the infrastructure will initialize the logical
> +device using a driver-provided function which will set up the bits specific to
> +the subsystem and in turn initialize each of its clients.
> +
> +Similarly, when one of the clients is unregistered, the infrastructure will
> +destroy the logical device by calling back into the driver, which ensures that
> +the subsystem specific bits are torn down and the clients destroyed in turn.
> +
> +Host1x Infrastructure Reference
> +-------------------------------
> +
> +.. kernel-doc:: include/linux/host1x.h
> +
> +.. kernel-doc:: drivers/gpu/host1x/bus.c
> +   :export:
> +
> +Host1x Syncpoint Reference
> +--------------------------
> +
> +.. kernel-doc:: drivers/gpu/host1x/syncpt.c
> +   :export:
> +
> +KMS driver
> +==========
> +
> +The display hardware has remained mostly backwards compatible over the various
> +Tegra SoC generations, up until Tegra186 which introduces several changes that
> +make it difficult to support with a parameterized driver.
> +
> +Display Controllers
> +-------------------
> +
> +Tegra SoCs have two display controllers, each of which can be associated with
> +zero or more outputs. Outputs can also share a single display controller, but
> +only if they run with compatible display timings. Two display controllers can
> +also share a single framebuffer, allowing cloned configurations even if modes
> +on two outputs don't match. A display controller is modelled as a CRTC in KMS
> +terms.
> +
> +On Tegra186, the number of display controllers has been increased to three. A
> +display controller can no longer drive all of the outputs. While two of these
> +controllers can drive both DSI outputs and both SOR outputs, the third cannot
> +drive any DSI.
> +
> +Windows
> +~~~~~~~
> +
> +A display controller controls a set of windows that can be used to composite
> +multiple buffers onto the screen. While it is possible to assign arbitrary Z
> +ordering to individual windows (by programming the corresponding blending
> +registers), this is currently not supported by the driver. Instead, it will
> +assume a fixed Z ordering of the windows (window A is the root window, that
> +is, the lowest, while windows B and C are overlaid on top of window A). The
> +overlay windows support multiple pixel formats and can automatically convert
> +from YUV to RGB at scanout time. This makes them useful for displaying video
> +content. In KMS, each window is modelled as a plane. Each display controller
> +has a hardware cursor that is exposed as a cursor plane.
> +
> +Outputs
> +-------
> +
> +The type and number of supported outputs varies between Tegra SoC generations.
> +All generations support at least HDMI. While earlier generations supported the
> +very simple RGB interfaces (one per display controller), recent generations no
> +longer do and instead provide standard interfaces such as DSI and eDP/DP.
> +
> +Outputs are modelled as a composite encoder/connector pair.
> +
> +RGB/LVDS
> +~~~~~~~~
> +
> +This interface is no longer available since Tegra124. It has been replaced by
> +the more standard DSI and eDP interfaces.
> +
> +HDMI
> +~~~~
> +
> +HDMI is supported on all Tegra SoCs. Starting with Tegra210, HDMI is provided
> +by the versatile SOR output, which supports eDP, DP and HDMI. The SOR is able
> +to support HDMI 2.0, though support for this is currently not merged.
> +
> +DSI
> +~~~
> +
> +Although Tegra has supported DSI since Tegra30, the controller has changed in
> +several ways in Tegra114. Since none of the publicly available development
> +boards prior to Dalmore (Tegra114) have made use of DSI, only Tegra114 and
> +later are supported by the drm/tegra driver.
> +
> +eDP/DP
> +~~~~~~
> +
> +eDP was first introduced in Tegra124 where it was used to drive the display
> +panel for notebook form factors. Tegra210 added support for full DisplayPort
> +support, though this is currently not implemented in the drm/tegra driver.
> +
> +Userspace Interface
> +===================
> +
> +The userspace interface provided by drm/tegra allows applications to create
> +GEM buffers, access and control syncpoints as well as submit command streams
> +to host1x.
> +
> +GEM Buffers
> +-----------
> +
> +The ``DRM_IOCTL_TEGRA_GEM_CREATE`` IOCTL is used to create a GEM buffer object
> +with Tegra-specific flags. This is useful for buffers that should be tiled, or
> +that are to be scanned out upside down (useful for 3D content).
> +
> +After a GEM buffer object has been created, its memory can be mapped by an
> +application using the mmap offset returned by the ``DRM_IOCTL_TEGRA_GEM_MMAP``
> +IOCTL.
> +
> +Syncpoints
> +----------
> +
> +The current value of a syncpoint can be obtained by executing the
> +``DRM_IOCTL_TEGRA_SYNCPT_READ`` IOCTL. Incrementing the syncpoint is achieved
> +using the ``DRM_IOCTL_TEGRA_SYNCPT_INCR`` IOCTL.
> +
> +Userspace can also request blocking on a syncpoint. To do so, it needs to
> +execute the ``DRM_IOCTL_TEGRA_SYNCPT_WAIT`` IOCTL, specifying the value of
> +the syncpoint to wait for. The kernel will release the application when the
> +syncpoint reaches that value or after a specified timeout.
> +
> +Command Stream Submission
> +-------------------------
> +
> +Before an application can submit command streams to host1x it needs to open a
> +channel to an engine using the ``DRM_IOCTL_TEGRA_OPEN_CHANNEL`` IOCTL. Client
> +IDs are used to identify the target of the channel. When a channel is no
> +longer needed, it can be closed using the ``DRM_IOCTL_TEGRA_CLOSE_CHANNEL``
> +IOCTL. To retrieve the syncpoint associated with a channel, an application
> +can use the ``DRM_IOCTL_TEGRA_GET_SYNCPT``.
> +
> +After opening a channel, submitting command streams is easy. The application
> +writes commands into the memory backing a GEM buffer object and passes these
> +to the ``DRM_IOCTL_TEGRA_SUBMIT`` IOCTL along with various other parameters,
> +such as the syncpoints or relocations used in the job submission.
> -- 
> 2.12.0
> 
> _______________________________________________
> dri-devel mailing list
> dri-devel at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/dri-devel

-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch