1=============================================== 2 drm/tegra NVIDIA Tegra GPU and display driver 3=============================================== 4 5NVIDIA Tegra SoCs support a set of display, graphics and video functions via 6the host1x controller. host1x supplies command streams, gathered from a push 7buffer provided directly by the CPU, to its clients via channels. Software, 8or blocks amongst themselves, can use syncpoints for synchronization. 9 10Up until, but not including, Tegra124 (aka Tegra K1) the drm/tegra driver 11supports the built-in GPU, comprised of the gr2d and gr3d engines. Starting 12with Tegra124 the GPU is based on the NVIDIA desktop GPU architecture and 13supported by the drm/nouveau driver. 14 15The drm/tegra driver supports NVIDIA Tegra SoC generations since Tegra20. It 16has three parts: 17 18 - A host1x driver that provides infrastructure and access to the host1x 19 services. 20 21 - A KMS driver that supports the display controllers as well as a number of 22 outputs, such as RGB, HDMI, DSI, and DisplayPort. 23 24 - A set of custom userspace IOCTLs that can be used to submit jobs to the 25 GPU and video engines via host1x. 26 27Driver Infrastructure 28===================== 29 30The various host1x clients need to be bound together into a logical device in 31order to expose their functionality to users. The infrastructure that supports 32this is implemented in the host1x driver. When a driver is registered with the 33infrastructure it provides a list of compatible strings specifying the devices 34that it needs. The infrastructure creates a logical device and scan the device 35tree for matching device nodes, adding the required clients to a list. Drivers 36for individual clients register with the infrastructure as well and are added 37to the logical host1x device. 38 39Once all clients are available, the infrastructure will initialize the logical 40device using a driver-provided function which will set up the bits specific to 41the subsystem and in turn initialize each of its clients. 42 43Similarly, when one of the clients is unregistered, the infrastructure will 44destroy the logical device by calling back into the driver, which ensures that 45the subsystem specific bits are torn down and the clients destroyed in turn. 46 47Host1x Infrastructure Reference 48------------------------------- 49 50.. kernel-doc:: include/linux/host1x.h 51 52.. kernel-doc:: drivers/gpu/host1x/bus.c 53 :export: 54 55Host1x Syncpoint Reference 56-------------------------- 57 58.. kernel-doc:: drivers/gpu/host1x/syncpt.c 59 :export: 60 61KMS driver 62========== 63 64The display hardware has remained mostly backwards compatible over the various 65Tegra SoC generations, up until Tegra186 which introduces several changes that 66make it difficult to support with a parameterized driver. 67 68Display Controllers 69------------------- 70 71Tegra SoCs have two display controllers, each of which can be associated with 72zero or more outputs. Outputs can also share a single display controller, but 73only if they run with compatible display timings. Two display controllers can 74also share a single framebuffer, allowing cloned configurations even if modes 75on two outputs don't match. A display controller is modelled as a CRTC in KMS 76terms. 77 78On Tegra186, the number of display controllers has been increased to three. A 79display controller can no longer drive all of the outputs. While two of these 80controllers can drive both DSI outputs and both SOR outputs, the third cannot 81drive any DSI. 82 83Windows 84~~~~~~~ 85 86A display controller controls a set of windows that can be used to composite 87multiple buffers onto the screen. While it is possible to assign arbitrary Z 88ordering to individual windows (by programming the corresponding blending 89registers), this is currently not supported by the driver. Instead, it will 90assume a fixed Z ordering of the windows (window A is the root window, that 91is, the lowest, while windows B and C are overlaid on top of window A). The 92overlay windows support multiple pixel formats and can automatically convert 93from YUV to RGB at scanout time. This makes them useful for displaying video 94content. In KMS, each window is modelled as a plane. Each display controller 95has a hardware cursor that is exposed as a cursor plane. 96 97Outputs 98------- 99 100The type and number of supported outputs varies between Tegra SoC generations. 101All generations support at least HDMI. While earlier generations supported the 102very simple RGB interfaces (one per display controller), recent generations no 103longer do and instead provide standard interfaces such as DSI and eDP/DP. 104 105Outputs are modelled as a composite encoder/connector pair. 106 107RGB/LVDS 108~~~~~~~~ 109 110This interface is no longer available since Tegra124. It has been replaced by 111the more standard DSI and eDP interfaces. 112 113HDMI 114~~~~ 115 116HDMI is supported on all Tegra SoCs. Starting with Tegra210, HDMI is provided 117by the versatile SOR output, which supports eDP, DP and HDMI. The SOR is able 118to support HDMI 2.0, though support for this is currently not merged. 119 120DSI 121~~~ 122 123Although Tegra has supported DSI since Tegra30, the controller has changed in 124several ways in Tegra114. Since none of the publicly available development 125boards prior to Dalmore (Tegra114) have made use of DSI, only Tegra114 and 126later are supported by the drm/tegra driver. 127 128eDP/DP 129~~~~~~ 130 131eDP was first introduced in Tegra124 where it was used to drive the display 132panel for notebook form factors. Tegra210 added support for full DisplayPort 133support, though this is currently not implemented in the drm/tegra driver. 134 135Userspace Interface 136=================== 137 138The userspace interface provided by drm/tegra allows applications to create 139GEM buffers, access and control syncpoints as well as submit command streams 140to host1x. 141 142GEM Buffers 143----------- 144 145The ``DRM_IOCTL_TEGRA_GEM_CREATE`` IOCTL is used to create a GEM buffer object 146with Tegra-specific flags. This is useful for buffers that should be tiled, or 147that are to be scanned out upside down (useful for 3D content). 148 149After a GEM buffer object has been created, its memory can be mapped by an 150application using the mmap offset returned by the ``DRM_IOCTL_TEGRA_GEM_MMAP`` 151IOCTL. 152 153Syncpoints 154---------- 155 156The current value of a syncpoint can be obtained by executing the 157``DRM_IOCTL_TEGRA_SYNCPT_READ`` IOCTL. Incrementing the syncpoint is achieved 158using the ``DRM_IOCTL_TEGRA_SYNCPT_INCR`` IOCTL. 159 160Userspace can also request blocking on a syncpoint. To do so, it needs to 161execute the ``DRM_IOCTL_TEGRA_SYNCPT_WAIT`` IOCTL, specifying the value of 162the syncpoint to wait for. The kernel will release the application when the 163syncpoint reaches that value or after a specified timeout. 164 165Command Stream Submission 166------------------------- 167 168Before an application can submit command streams to host1x it needs to open a 169channel to an engine using the ``DRM_IOCTL_TEGRA_OPEN_CHANNEL`` IOCTL. Client 170IDs are used to identify the target of the channel. When a channel is no 171longer needed, it can be closed using the ``DRM_IOCTL_TEGRA_CLOSE_CHANNEL`` 172IOCTL. To retrieve the syncpoint associated with a channel, an application 173can use the ``DRM_IOCTL_TEGRA_GET_SYNCPT``. 174 175After opening a channel, submitting command streams is easy. The application 176writes commands into the memory backing a GEM buffer object and passes these 177to the ``DRM_IOCTL_TEGRA_SUBMIT`` IOCTL along with various other parameters, 178such as the syncpoints or relocations used in the job submission. 179