diff options
Diffstat (limited to 'Documentation/gpu')
| -rw-r--r-- | Documentation/gpu/drm-internals.rst | 66 | ||||
| -rw-r--r-- | Documentation/gpu/drm-kms-helpers.rst | 6 | ||||
| -rw-r--r-- | Documentation/gpu/drm-kms.rst | 4 | ||||
| -rw-r--r-- | Documentation/gpu/drm-mm.rst | 12 | ||||
| -rw-r--r-- | Documentation/gpu/index.rst | 2 | ||||
| -rw-r--r-- | Documentation/gpu/pl111.rst | 6 | ||||
| -rw-r--r-- | Documentation/gpu/tegra.rst | 178 | ||||
| -rw-r--r-- | Documentation/gpu/todo.rst | 15 |
8 files changed, 219 insertions, 70 deletions
diff --git a/Documentation/gpu/drm-internals.rst b/Documentation/gpu/drm-internals.rst index babfb6143bd9..0d936c67bf7d 100644 --- a/Documentation/gpu/drm-internals.rst +++ b/Documentation/gpu/drm-internals.rst @@ -98,6 +98,9 @@ DRIVER_ATOMIC implement appropriate obj->atomic_get_property() vfuncs for any modeset objects with driver specific properties. +DRIVER_SYNCOBJ + Driver support drm sync objects. + Major, Minor and Patchlevel ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -149,60 +152,15 @@ Device Instance and Driver Handling Driver Load ----------- -IRQ Registration -~~~~~~~~~~~~~~~~ - -The DRM core tries to facilitate IRQ handler registration and -unregistration by providing :c:func:`drm_irq_install()` and -:c:func:`drm_irq_uninstall()` functions. Those functions only -support a single interrupt per device, devices that use more than one -IRQs need to be handled manually. - -Managed IRQ Registration -'''''''''''''''''''''''' - -:c:func:`drm_irq_install()` starts by calling the irq_preinstall -driver operation. The operation is optional and must make sure that the -interrupt will not get fired by clearing all pending interrupt flags or -disabling the interrupt. - -The passed-in IRQ will then be requested by a call to -:c:func:`request_irq()`. If the DRIVER_IRQ_SHARED driver feature -flag is set, a shared (IRQF_SHARED) IRQ handler will be requested. - -The IRQ handler function must be provided as the mandatory irq_handler -driver operation. It will get passed directly to -:c:func:`request_irq()` and thus has the same prototype as all IRQ -handlers. It will get called with a pointer to the DRM device as the -second argument. - -Finally the function calls the optional irq_postinstall driver -operation. The operation usually enables interrupts (excluding the -vblank interrupt, which is enabled separately), but drivers may choose -to enable/disable interrupts at a different time. - -:c:func:`drm_irq_uninstall()` is similarly used to uninstall an -IRQ handler. It starts by waking up all processes waiting on a vblank -interrupt to make sure they don't hang, and then calls the optional -irq_uninstall driver operation. The operation must disable all hardware -interrupts. Finally the function frees the IRQ by calling -:c:func:`free_irq()`. - -Manual IRQ Registration -''''''''''''''''''''''' - -Drivers that require multiple interrupt handlers can't use the managed -IRQ registration functions. In that case IRQs must be registered and -unregistered manually (usually with the :c:func:`request_irq()` and -:c:func:`free_irq()` functions, or their :c:func:`devm_request_irq()` and -:c:func:`devm_free_irq()` equivalents). - -When manually registering IRQs, drivers must not set the -DRIVER_HAVE_IRQ driver feature flag, and must not provide the -irq_handler driver operation. They must set the :c:type:`struct -drm_device <drm_device>` irq_enabled field to 1 upon -registration of the IRQs, and clear it to 0 after unregistering the -IRQs. + +IRQ Helper Library +~~~~~~~~~~~~~~~~~~ + +.. kernel-doc:: drivers/gpu/drm/drm_irq.c + :doc: irq helpers + +.. kernel-doc:: drivers/gpu/drm/drm_irq.c + :export: Memory Manager Initialization ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/Documentation/gpu/drm-kms-helpers.rst b/Documentation/gpu/drm-kms-helpers.rst index c075aadd7078..7c5e2549a58a 100644 --- a/Documentation/gpu/drm-kms-helpers.rst +++ b/Documentation/gpu/drm-kms-helpers.rst @@ -143,6 +143,12 @@ Bridge Helper Reference .. kernel-doc:: drivers/gpu/drm/drm_bridge.c :export: +Panel-Bridge Helper Reference +----------------------------- + +.. kernel-doc:: drivers/gpu/drm/bridge/panel.c + :export: + .. _drm_panel_helper: Panel Helper Reference diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst index bfecd21a8cdf..2d77c9580164 100644 --- a/Documentation/gpu/drm-kms.rst +++ b/Documentation/gpu/drm-kms.rst @@ -612,8 +612,8 @@ operation handler. Vertical Blanking and Interrupt Handling Functions Reference ------------------------------------------------------------ -.. kernel-doc:: include/drm/drm_irq.h +.. kernel-doc:: include/drm/drm_vblank.h :internal: -.. kernel-doc:: drivers/gpu/drm/drm_irq.c +.. kernel-doc:: drivers/gpu/drm/drm_vblank.c :export: diff --git a/Documentation/gpu/drm-mm.rst b/Documentation/gpu/drm-mm.rst index 96b9c34c21e4..9412798645c1 100644 --- a/Documentation/gpu/drm-mm.rst +++ b/Documentation/gpu/drm-mm.rst @@ -484,3 +484,15 @@ DRM Cache Handling .. kernel-doc:: drivers/gpu/drm/drm_cache.c :export: + +DRM Sync Objects +=========================== + +.. kernel-doc:: drivers/gpu/drm/drm_syncobj.c + :doc: Overview + +.. kernel-doc:: include/drm/drm_syncobj.h + :export: + +.. kernel-doc:: drivers/gpu/drm/drm_syncobj.c + :export: diff --git a/Documentation/gpu/index.rst b/Documentation/gpu/index.rst index c572f092739e..35d673bf9b56 100644 --- a/Documentation/gpu/index.rst +++ b/Documentation/gpu/index.rst @@ -12,6 +12,8 @@ Linux GPU Driver Developer's Guide drm-uapi i915 meson + pl111 + tegra tinydrm vc4 vga-switcheroo diff --git a/Documentation/gpu/pl111.rst b/Documentation/gpu/pl111.rst new file mode 100644 index 000000000000..9b03736d33dd --- /dev/null +++ b/Documentation/gpu/pl111.rst @@ -0,0 +1,6 @@ +========================================== + drm/pl111 ARM PrimeCell PL111 CLCD Driver +========================================== + +.. kernel-doc:: drivers/gpu/drm/pl111/pl111_drv.c + :doc: ARM PrimeCell PL111 CLCD Driver 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. diff --git a/Documentation/gpu/todo.rst b/Documentation/gpu/todo.rst index 1bdb7356a310..1ae42006deea 100644 --- a/Documentation/gpu/todo.rst +++ b/Documentation/gpu/todo.rst @@ -177,19 +177,6 @@ following drivers still use ``struct_mutex``: ``msm``, ``omapdrm`` and Contact: Daniel Vetter, respective driver maintainers -Switch to drm_connector_list_iter for any connector_list walking ----------------------------------------------------------------- - -Connectors can be hotplugged, and we now have a special list of helpers to walk -the connector_list in a race-free fashion, without incurring deadlocks on -mutexes and other fun stuff. - -Unfortunately most drivers are not converted yet. At least all those supporting -DP MST hotplug should be converted, since for those drivers the difference -matters. See drm_for_each_connector_iter() vs. drm_for_each_connector(). - -Contact: Daniel Vetter - Core refactorings ================= @@ -228,7 +215,7 @@ The DRM reference documentation is still lacking kerneldoc in a few areas. The task would be to clean up interfaces like moving functions around between files to better group them and improving the interfaces like dropping return values for functions that never fail. Then write kerneldoc for all exported -functions and an overview section and integrate it all into the drm DocBook. +functions and an overview section and integrate it all into the drm book. See https://dri.freedesktop.org/docs/drm/ for what's there already. |