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