=============================================== drm/tegra NVIDIA Tegra GPU and display driver=============================================== NVIDIA Tegra SoCs support a set of display, graphics and video functions viathe host1x controller. host1x supplies command streams, gathered from a pushbuffer 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 driversupports the built-in GPU, comprised of the gr2d and gr3d engines. Startingwith Tegra124 the GPU is based on the NVIDIA desktop GPU architecture andsupported by the drm/nouveau driver. The drm/tegra driver supports NVIDIA Tegra SoC generations since Tegra20. Ithas 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 inorder to expose their functionality to users. The infrastructure that supportsthis is implemented in the host1x driver. When a driver is registered with theinfrastructure it provides a list of compatible strings specifying the devicesthat it needs. The infrastructure creates a logical device and scan the devicetree for matching device nodes, adding the required clients to a list. Driversfor individual clients register with the infrastructure as well and are addedto the logical host1x device. Once all clients are available, the infrastructure will initialize the logicaldevice using a driver-provided function which will set up the bits specific tothe subsystem and in turn initialize each of its clients. Similarly, when one of the clients is unregistered, the infrastructure willdestroy the logical device by calling back into the driver, which ensures thatthe 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 variousTegra SoC generations, up until Tegra186 which introduces several changes thatmake it difficult to support with a parameterized driver. Display Controllers------------------- Tegra SoCs have two display controllers, each of which can be associated withzero or more outputs. Outputs can also share a single display controller, butonly if they run with compatible display timings. Two display controllers canalso share a single framebuffer, allowing cloned configurations even if modeson two outputs don't match. A display controller is modelled as a CRTC in KMSterms. On Tegra186, the number of display controllers has been increased to three. Adisplay controller can no longer drive all of the outputs. While two of thesecontrollers can drive both DSI outputs and both SOR outputs, the third cannotdrive any DSI. Windows~~~~~~~ A display controller controls a set of windows that can be used to compositemultiple buffers onto the screen. While it is possible to assign arbitrary Zordering to individual windows (by programming the corresponding blendingregisters), this is currently not supported by the driver. Instead, it willassume a fixed Z ordering of the windows (window A is the root window, thatis, the lowest, while windows B and C are overlaid on top of window A). Theoverlay windows support multiple pixel formats and can automatically convertfrom YUV to RGB at scanout time. This makes them useful for displaying videocontent. In KMS, each window is modelled as a plane. Each display controllerhas 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 thevery simple RGB interfaces (one per display controller), recent generations nolonger 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 bythe more standard DSI and eDP interfaces. HDMI~~~~ HDMI is supported on all Tegra SoCs. Starting with Tegra210, HDMI is providedby the versatile SOR output, which supports eDP, DP and HDMI. The SOR is ableto support HDMI 2.0, though support for this is currently not merged. DSI~~~ Although Tegra has supported DSI since Tegra30, the controller has changed inseveral ways in Tegra114. Since none of the publicly available developmentboards prior to Dalmore (Tegra114) have made use of DSI, only Tegra114 andlater are supported by the drm/tegra driver. eDP/DP~~~~~~ eDP was first introduced in Tegra124 where it was used to drive the displaypanel for notebook form factors. Tegra210 added support for full DisplayPortsupport, though this is currently not implemented in the drm/tegra driver. Userspace Interface=================== The userspace interface provided by drm/tegra allows applications to createGEM buffers, access and control syncpoints as well as submit command streamsto host1x. GEM Buffers----------- The ``DRM_IOCTL_TEGRA_GEM_CREATE`` IOCTL is used to create a GEM buffer objectwith Tegra-specific flags. This is useful for buffers that should be tiled, orthat 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 anapplication 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 achievedusing the ``DRM_IOCTL_TEGRA_SYNCPT_INCR`` IOCTL. Userspace can also request blocking on a syncpoint. To do so, it needs toexecute the ``DRM_IOCTL_TEGRA_SYNCPT_WAIT`` IOCTL, specifying the value ofthe syncpoint to wait for. The kernel will release the application when thesyncpoint reaches that value or after a specified timeout. Command Stream Submission------------------------- Before an application can submit command streams to host1x it needs to open achannel to an engine using the ``DRM_IOCTL_TEGRA_OPEN_CHANNEL`` IOCTL. ClientIDs are used to identify the target of the channel. When a channel is nolonger needed, it can be closed using the ``DRM_IOCTL_TEGRA_CLOSE_CHANNEL``IOCTL. To retrieve the syncpoint associated with a channel, an applicationcan use the ``DRM_IOCTL_TEGRA_GET_SYNCPT``. After opening a channel, submitting command streams is easy. The applicationwrites commands into the memory backing a GEM buffer object and passes theseto the ``DRM_IOCTL_TEGRA_SUBMIT`` IOCTL along with various other parameters,such as the syncpoints or relocations used in the job submission.