Initial commit: Linux kernel 4.19 for Unplugged OS

This commit is contained in:
ziv committed 2025-10-06 13:52:42 +00:00
commit d30235b04c
80519 files changed
+35800681

No files matched your search

+129
View File
@@ -0,0 +1,129 @@
=========================
drm/amdgpu AMDgpu driver
=========================
The drm/amdgpu driver supports all AMD Radeon GPUs based on the Graphics Core
Next (GCN) architecture.
Module Parameters
=================
The amdgpu driver supports the following module parameters:
.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_drv.c
Core Driver Infrastructure
==========================
This section covers core driver infrastructure.
.. _amdgpu_memory_domains:
Memory Domains
--------------
.. kernel-doc:: include/uapi/drm/amdgpu_drm.h
:doc: memory domains
Buffer Objects
--------------
.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_object.c
:doc: amdgpu_object
.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_object.c
:internal:
PRIME Buffer Sharing
--------------------
.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_prime.c
:doc: PRIME Buffer Sharing
.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_prime.c
:internal:
MMU Notifier
------------
.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_mn.c
:doc: MMU Notifier
.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_mn.c
:internal:
AMDGPU Virtual Memory
---------------------
.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c
:doc: GPUVM
.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c
:internal:
Interrupt Handling
------------------
.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_irq.c
:doc: Interrupt Handling
.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_irq.c
:internal:
GPU Power/Thermal Controls and Monitoring
=========================================
This section covers hwmon and power/thermal controls.
HWMON Interfaces
----------------
.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_pm.c
:doc: hwmon
GPU sysfs Power State Interfaces
--------------------------------
GPU power controls are exposed via sysfs files.
power_dpm_state
~~~~~~~~~~~~~~~
.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_pm.c
:doc: power_dpm_state
power_dpm_force_performance_level
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_pm.c
:doc: power_dpm_force_performance_level
pp_table
~~~~~~~~
.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_pm.c
:doc: pp_table
pp_od_clk_voltage
~~~~~~~~~~~~~~~~~
.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_pm.c
:doc: pp_od_clk_voltage
pp_dpm_sclk pp_dpm_mclk pp_dpm_pcie
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_pm.c
:doc: pp_dpm_sclk pp_dpm_mclk pp_dpm_pcie
pp_power_profile_mode
~~~~~~~~~~~~~~~~~~~~~
.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_pm.c
:doc: pp_power_profile_mode
busy_percent
~~~~~~~~~~~~
.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_pm.c
:doc: busy_percent
+15
View File
@@ -0,0 +1,15 @@
=======================================================
drm/bridge/dw-hdmi Synopsys DesignWare HDMI Controller
=======================================================
Synopsys DesignWare HDMI Controller
===================================
This section covers everything related to the Synopsys DesignWare HDMI
Controller implemented as a DRM bridge.
Supported Input Formats and Encodings
-------------------------------------
.. kernel-doc:: include/drm/bridge/dw_hdmi.h
:doc: Supported input formats and encodings
+10
View File
@@ -0,0 +1,10 @@
# -*- coding: utf-8; mode: python -*-
project = "Linux GPU Driver Developer's Guide"
tags.add("subproject")
latex_documents = [
('index', 'gpu.tex', project,
'The kernel development community', 'manual'),
]
+24
View File
@@ -0,0 +1,24 @@
========================
GPU Driver Documentation
========================
.. toctree::
amdgpu
i915
meson
pl111
tegra
tinydrm
tve200
v3d
vc4
bridge/dw-hdmi
xen-front
.. only:: subproject and html
Indices
=======
* :ref:`genindex`
+12
View File
@@ -0,0 +1,12 @@
=================
Kernel clients
=================
.. kernel-doc:: drivers/gpu/drm/drm_client.c
:doc: overview
.. kernel-doc:: include/drm/drm_client.h
:internal:
.. kernel-doc:: drivers/gpu/drm/drm_client.c
:export:
+265
View File
@@ -0,0 +1,265 @@
=============
DRM Internals
=============
This chapter documents DRM internals relevant to driver authors and
developers working to add support for the latest features to existing
drivers.
First, we go over some typical driver initialization requirements, like
setting up command buffers, creating an initial output configuration,
and initializing core services. Subsequent sections cover core internals
in more detail, providing implementation notes and examples.
The DRM layer provides several services to graphics drivers, many of
them driven by the application interfaces it provides through libdrm,
the library that wraps most of the DRM ioctls. These include vblank
event handling, memory management, output management, framebuffer
management, command submission & fencing, suspend/resume support, and
DMA services.
Driver Initialization
=====================
At the core of every DRM driver is a :c:type:`struct drm_driver
<drm_driver>` structure. Drivers typically statically initialize
a drm_driver structure, and then pass it to
:c:func:`drm_dev_alloc()` to allocate a device instance. After the
device instance is fully initialized it can be registered (which makes
it accessible from userspace) using :c:func:`drm_dev_register()`.
The :c:type:`struct drm_driver <drm_driver>` structure
contains static information that describes the driver and features it
supports, and pointers to methods that the DRM core will call to
implement the DRM API. We will first go through the :c:type:`struct
drm_driver <drm_driver>` static information fields, and will
then describe individual operations in details as they get used in later
sections.
Driver Information
------------------
Driver Features
~~~~~~~~~~~~~~~
Drivers inform the DRM core about their requirements and supported
features by setting appropriate flags in the driver_features field.
Since those flags influence the DRM core behaviour since registration
time, most of them must be set to registering the :c:type:`struct
drm_driver <drm_driver>` instance.
u32 driver_features;
DRIVER_USE_AGP
Driver uses AGP interface, the DRM core will manage AGP resources.
DRIVER_LEGACY
Denote a legacy driver using shadow attach. Don't use.
DRIVER_KMS_LEGACY_CONTEXT
Used only by nouveau for backwards compatibility with existing userspace.
Don't use.
DRIVER_PCI_DMA
Driver is capable of PCI DMA, mapping of PCI DMA buffers to
userspace will be enabled. Deprecated.
DRIVER_SG
Driver can perform scatter/gather DMA, allocation and mapping of
scatter/gather buffers will be enabled. Deprecated.
DRIVER_HAVE_DMA
Driver supports DMA, the userspace DMA API will be supported.
Deprecated.
DRIVER_HAVE_IRQ; DRIVER_IRQ_SHARED
DRIVER_HAVE_IRQ indicates whether the driver has an IRQ handler
managed by the DRM Core. The core will support simple IRQ handler
installation when the flag is set. The installation process is
described in ?.
DRIVER_IRQ_SHARED indicates whether the device & handler support
shared IRQs (note that this is required of PCI drivers).
DRIVER_GEM
Driver use the GEM memory manager.
DRIVER_MODESET
Driver supports mode setting interfaces (KMS).
DRIVER_PRIME
Driver implements DRM PRIME buffer sharing.
DRIVER_RENDER
Driver supports dedicated render nodes.
DRIVER_ATOMIC
Driver supports atomic properties. In this case the driver must
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
~~~~~~~~~~~~~~~~~~~~~~~~~~~
int major; int minor; int patchlevel;
The DRM core identifies driver versions by a major, minor and patch
level triplet. The information is printed to the kernel log at
initialization time and passed to userspace through the
DRM_IOCTL_VERSION ioctl.
The major and minor numbers are also used to verify the requested driver
API version passed to DRM_IOCTL_SET_VERSION. When the driver API
changes between minor versions, applications can call
DRM_IOCTL_SET_VERSION to select a specific version of the API. If the
requested major isn't equal to the driver major, or the requested minor
is larger than the driver minor, the DRM_IOCTL_SET_VERSION call will
return an error. Otherwise the driver's set_version() method will be
called with the requested version.
Name, Description and Date
~~~~~~~~~~~~~~~~~~~~~~~~~~
char \*name; char \*desc; char \*date;
The driver name is printed to the kernel log at initialization time,
used for IRQ registration and passed to userspace through
DRM_IOCTL_VERSION.
The driver description is a purely informative string passed to
userspace through the DRM_IOCTL_VERSION ioctl and otherwise unused by
the kernel.
The driver date, formatted as YYYYMMDD, is meant to identify the date of
the latest modification to the driver. However, as most drivers fail to
update it, its value is mostly useless. The DRM core prints it to the
kernel log at initialization time and passes it to userspace through the
DRM_IOCTL_VERSION ioctl.
Device Instance and Driver Handling
-----------------------------------
.. kernel-doc:: drivers/gpu/drm/drm_drv.c
:doc: driver instance overview
.. kernel-doc:: include/drm/drm_drv.h
:internal:
.. kernel-doc:: drivers/gpu/drm/drm_drv.c
:export:
Driver Load
-----------
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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Every DRM driver requires a memory manager which must be initialized at
load time. DRM currently contains two memory managers, the Translation
Table Manager (TTM) and the Graphics Execution Manager (GEM). This
document describes the use of the GEM memory manager only. See ? for
details.
Miscellaneous Device Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Another task that may be necessary for PCI devices during configuration
is mapping the video BIOS. On many devices, the VBIOS describes device
configuration, LCD panel timings (if any), and contains flags indicating
device state. Mapping the BIOS can be done using the pci_map_rom()
call, a convenience function that takes care of mapping the actual ROM,
whether it has been shadowed into memory (typically at address 0xc0000)
or exists on the PCI device in the ROM BAR. Note that after the ROM has
been mapped and any necessary information has been extracted, it should
be unmapped; on many devices, the ROM address decoder is shared with
other BARs, so leaving it mapped could cause undesired behaviour like
hangs or memory corruption.
Bus-specific Device Registration and PCI Support
------------------------------------------------
A number of functions are provided to help with device registration. The
functions deal with PCI and platform devices respectively and are only
provided for historical reasons. These are all deprecated and shouldn't
be used in new drivers. Besides that there's a few helpers for pci
drivers.
.. kernel-doc:: drivers/gpu/drm/drm_pci.c
:export:
Open/Close, File Operations and IOCTLs
======================================
.. _drm_driver_fops:
File Operations
---------------
.. kernel-doc:: drivers/gpu/drm/drm_file.c
:doc: file operations
.. kernel-doc:: include/drm/drm_file.h
:internal:
.. kernel-doc:: drivers/gpu/drm/drm_file.c
:export:
Misc Utilities
==============
Printer
-------
.. kernel-doc:: include/drm/drm_print.h
:doc: print
.. kernel-doc:: include/drm/drm_print.h
:internal:
.. kernel-doc:: drivers/gpu/drm/drm_print.c
:export:
Legacy Support Code
===================
The section very briefly covers some of the old legacy support code
which is only used by old DRM drivers which have done a so-called
shadow-attach to the underlying device instead of registering as a real
driver. This also includes some of the old generic buffer management and
command submission code. Do not use any of this in new and modern
drivers.
Legacy Suspend/Resume
---------------------
The DRM core provides some suspend/resume code, but drivers wanting full
suspend/resume support should provide save() and restore() functions.
These are called at suspend, hibernate, or resume time, and should
perform any state save or restore required by your device across suspend
or hibernate states.
int (\*suspend) (struct drm_device \*, pm_message_t state); int
(\*resume) (struct drm_device \*);
Those are legacy suspend and resume methods which *only* work with the
legacy shadow-attach driver registration functions. New driver should
use the power management interface provided by their bus type (usually
through the :c:type:`struct device_driver <device_driver>`
dev_pm_ops) and set these methods to NULL.
Legacy DMA Services
-------------------
This should cover how DMA mapping etc. is supported by the core. These
functions are deprecated and should not be used.
+328
View File
@@ -0,0 +1,328 @@
=============================
Mode Setting Helper Functions
=============================
The DRM subsystem aims for a strong separation between core code and helper
libraries. Core code takes care of general setup and teardown and decoding
userspace requests to kernel internal objects. Everything else is handled by a
large set of helper libraries, which can be combined freely to pick and choose
for each driver what fits, and avoid shared code where special behaviour is
needed.
This distinction between core code and helpers is especially strong in the
modesetting code, where there's a shared userspace ABI for all drivers. This is
in contrast to the render side, where pretty much everything (with very few
exceptions) can be considered optional helper code.
There are a few areas these helpers can grouped into:
* Helpers to implement modesetting. The important ones here are the atomic
helpers. Old drivers still often use the legacy CRTC helpers. They both share
the same set of common helper vtables. For really simple drivers (anything
that would have been a great fit in the deprecated fbdev subsystem) there's
also the simple display pipe helpers.
* There's a big pile of helpers for handling outputs. First the generic bridge
helpers for handling encoder and transcoder IP blocks. Second the panel helpers
for handling panel-related information and logic. Plus then a big set of
helpers for the various sink standards (DisplayPort, HDMI, MIPI DSI). Finally
there's also generic helpers for handling output probing, and for dealing with
EDIDs.
* The last group of helpers concerns itself with the frontend side of a display
pipeline: Planes, handling rectangles for visibility checking and scissoring,
flip queues and assorted bits.
Modeset Helper Reference for Common Vtables
===========================================
.. kernel-doc:: include/drm/drm_modeset_helper_vtables.h
:doc: overview
.. kernel-doc:: include/drm/drm_modeset_helper_vtables.h
:internal:
.. _drm_atomic_helper:
Atomic Modeset Helper Functions Reference
=========================================
Overview
--------
.. kernel-doc:: drivers/gpu/drm/drm_atomic_helper.c
:doc: overview
Implementing Asynchronous Atomic Commit
---------------------------------------
.. kernel-doc:: drivers/gpu/drm/drm_atomic_helper.c
:doc: implementing nonblocking commit
Atomic State Reset and Initialization
-------------------------------------
.. kernel-doc:: drivers/gpu/drm/drm_atomic_helper.c
:doc: atomic state reset and initialization
Helper Functions Reference
--------------------------
.. kernel-doc:: include/drm/drm_atomic_helper.h
:internal:
.. kernel-doc:: drivers/gpu/drm/drm_atomic_helper.c
:export:
Simple KMS Helper Reference
===========================
.. kernel-doc:: drivers/gpu/drm/drm_simple_kms_helper.c
:doc: overview
.. kernel-doc:: include/drm/drm_simple_kms_helper.h
:internal:
.. kernel-doc:: drivers/gpu/drm/drm_simple_kms_helper.c
:export:
fbdev Helper Functions Reference
================================
.. kernel-doc:: drivers/gpu/drm/drm_fb_helper.c
:doc: fbdev helpers
.. kernel-doc:: include/drm/drm_fb_helper.h
:internal:
.. kernel-doc:: drivers/gpu/drm/drm_fb_helper.c
:export:
Framebuffer CMA Helper Functions Reference
==========================================
.. kernel-doc:: drivers/gpu/drm/drm_fb_cma_helper.c
:doc: framebuffer cma helper functions
.. kernel-doc:: drivers/gpu/drm/drm_fb_cma_helper.c
:export:
.. _drm_bridges:
Framebuffer GEM Helper Reference
================================
.. kernel-doc:: drivers/gpu/drm/drm_gem_framebuffer_helper.c
:doc: overview
.. kernel-doc:: drivers/gpu/drm/drm_gem_framebuffer_helper.c
:export:
Bridges
=======
Overview
--------
.. kernel-doc:: drivers/gpu/drm/drm_bridge.c
:doc: overview
Default bridge callback sequence
--------------------------------
.. kernel-doc:: drivers/gpu/drm/drm_bridge.c
:doc: bridge callbacks
Bridge Helper Reference
-------------------------
.. kernel-doc:: include/drm/drm_bridge.h
:internal:
.. 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
======================
.. kernel-doc:: drivers/gpu/drm/drm_panel.c
:doc: drm panel
.. kernel-doc:: include/drm/drm_panel.h
:internal:
.. kernel-doc:: drivers/gpu/drm/drm_panel.c
:export:
.. kernel-doc:: drivers/gpu/drm/drm_panel_orientation_quirks.c
:export:
Display Port Helper Functions Reference
=======================================
.. kernel-doc:: drivers/gpu/drm/drm_dp_helper.c
:doc: dp helpers
.. kernel-doc:: include/drm/drm_dp_helper.h
:internal:
.. kernel-doc:: drivers/gpu/drm/drm_dp_helper.c
:export:
Display Port CEC Helper Functions Reference
===========================================
.. kernel-doc:: drivers/gpu/drm/drm_dp_cec.c
:doc: dp cec helpers
.. kernel-doc:: drivers/gpu/drm/drm_dp_cec.c
:export:
Display Port Dual Mode Adaptor Helper Functions Reference
=========================================================
.. kernel-doc:: drivers/gpu/drm/drm_dp_dual_mode_helper.c
:doc: dp dual mode helpers
.. kernel-doc:: include/drm/drm_dp_dual_mode_helper.h
:internal:
.. kernel-doc:: drivers/gpu/drm/drm_dp_dual_mode_helper.c
:export:
Display Port MST Helper Functions Reference
===========================================
.. kernel-doc:: drivers/gpu/drm/drm_dp_mst_topology.c
:doc: dp mst helper
.. kernel-doc:: include/drm/drm_dp_mst_helper.h
:internal:
.. kernel-doc:: drivers/gpu/drm/drm_dp_mst_topology.c
:export:
MIPI DSI Helper Functions Reference
===================================
.. kernel-doc:: drivers/gpu/drm/drm_mipi_dsi.c
:doc: dsi helpers
.. kernel-doc:: include/drm/drm_mipi_dsi.h
:internal:
.. kernel-doc:: drivers/gpu/drm/drm_mipi_dsi.c
:export:
Output Probing Helper Functions Reference
=========================================
.. kernel-doc:: drivers/gpu/drm/drm_probe_helper.c
:doc: output probing helper overview
.. kernel-doc:: drivers/gpu/drm/drm_probe_helper.c
:export:
EDID Helper Functions Reference
===============================
.. kernel-doc:: include/drm/drm_edid.h
:internal:
.. kernel-doc:: drivers/gpu/drm/drm_edid.c
:export:
SCDC Helper Functions Reference
===============================
.. kernel-doc:: drivers/gpu/drm/drm_scdc_helper.c
:doc: scdc helpers
.. kernel-doc:: include/drm/drm_scdc_helper.h
:internal:
.. kernel-doc:: drivers/gpu/drm/drm_scdc_helper.c
:export:
Rectangle Utilities Reference
=============================
.. kernel-doc:: include/drm/drm_rect.h
:doc: rect utils
.. kernel-doc:: include/drm/drm_rect.h
:internal:
.. kernel-doc:: drivers/gpu/drm/drm_rect.c
:export:
HDMI Infoframes Helper Reference
================================
Strictly speaking this is not a DRM helper library but generally useable
by any driver interfacing with HDMI outputs like v4l or alsa drivers.
But it nicely fits into the overall topic of mode setting helper
libraries and hence is also included here.
.. kernel-doc:: include/linux/hdmi.h
:internal:
.. kernel-doc:: drivers/video/hdmi.c
:export:
Flip-work Helper Reference
==========================
.. kernel-doc:: include/drm/drm_flip_work.h
:doc: flip utils
.. kernel-doc:: include/drm/drm_flip_work.h
:internal:
.. kernel-doc:: drivers/gpu/drm/drm_flip_work.c
:export:
Auxiliary Modeset Helpers
=========================
.. kernel-doc:: drivers/gpu/drm/drm_modeset_helper.c
:doc: aux kms helpers
.. kernel-doc:: drivers/gpu/drm/drm_modeset_helper.c
:export:
OF/DT Helpers
=============
.. kernel-doc:: drivers/gpu/drm/drm_of.c
:doc: overview
.. kernel-doc:: drivers/gpu/drm/drm_of.c
:export:
Legacy Plane Helper Reference
=============================
.. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c
:doc: overview
.. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c
:export:
Legacy CRTC/Modeset Helper Functions Reference
==============================================
.. kernel-doc:: drivers/gpu/drm/drm_crtc_helper.c
:doc: overview
.. kernel-doc:: drivers/gpu/drm/drm_crtc_helper.c
:export:
+590
View File
@@ -0,0 +1,590 @@
=========================
Kernel Mode Setting (KMS)
=========================
Drivers must initialize the mode setting core by calling
:c:func:`drm_mode_config_init()` on the DRM device. The function
initializes the :c:type:`struct drm_device <drm_device>`
mode_config field and never fails. Once done, mode configuration must
be setup by initializing the following fields.
- int min_width, min_height; int max_width, max_height;
Minimum and maximum width and height of the frame buffers in pixel
units.
- struct drm_mode_config_funcs \*funcs;
Mode setting functions.
Overview
========
.. kernel-render:: DOT
:alt: KMS Display Pipeline
:caption: KMS Display Pipeline Overview
digraph "KMS" {
node [shape=box]
subgraph cluster_static {
style=dashed
label="Static Objects"
node [bgcolor=grey style=filled]
"drm_plane A" -> "drm_crtc"
"drm_plane B" -> "drm_crtc"
"drm_crtc" -> "drm_encoder A"
"drm_crtc" -> "drm_encoder B"
}
subgraph cluster_user_created {
style=dashed
label="Userspace-Created"
node [shape=oval]
"drm_framebuffer 1" -> "drm_plane A"
"drm_framebuffer 2" -> "drm_plane B"
}
subgraph cluster_connector {
style=dashed
label="Hotpluggable"
"drm_encoder A" -> "drm_connector A"
"drm_encoder B" -> "drm_connector B"
}
}
The basic object structure KMS presents to userspace is fairly simple.
Framebuffers (represented by :c:type:`struct drm_framebuffer <drm_framebuffer>`,
see `Frame Buffer Abstraction`_) feed into planes. Planes are represented by
:c:type:`struct drm_plane <drm_plane>`, see `Plane Abstraction`_ for more
details. One or more (or even no) planes feed their pixel data into a CRTC
(represented by :c:type:`struct drm_crtc <drm_crtc>`, see `CRTC Abstraction`_)
for blending. The precise blending step is explained in more detail in `Plane
Composition Properties`_ and related chapters.
For the output routing the first step is encoders (represented by
:c:type:`struct drm_encoder <drm_encoder>`, see `Encoder Abstraction`_). Those
are really just internal artifacts of the helper libraries used to implement KMS
drivers. Besides that they make it unecessarily more complicated for userspace
to figure out which connections between a CRTC and a connector are possible, and
what kind of cloning is supported, they serve no purpose in the userspace API.
Unfortunately encoders have been exposed to userspace, hence can't remove them
at this point. Futhermore the exposed restrictions are often wrongly set by
drivers, and in many cases not powerful enough to express the real restrictions.
A CRTC can be connected to multiple encoders, and for an active CRTC there must
be at least one encoder.
The final, and real, endpoint in the display chain is the connector (represented
by :c:type:`struct drm_connector <drm_connector>`, see `Connector
Abstraction`_). Connectors can have different possible encoders, but the kernel
driver selects which encoder to use for each connector. The use case is DVI,
which could switch between an analog and a digital encoder. Encoders can also
drive multiple different connectors. There is exactly one active connector for
every active encoder.
Internally the output pipeline is a bit more complex and matches today's
hardware more closely:
.. kernel-render:: DOT
:alt: KMS Output Pipeline
:caption: KMS Output Pipeline
digraph "Output Pipeline" {
node [shape=box]
subgraph {
"drm_crtc" [bgcolor=grey style=filled]
}
subgraph cluster_internal {
style=dashed
label="Internal Pipeline"
{
node [bgcolor=grey style=filled]
"drm_encoder A";
"drm_encoder B";
"drm_encoder C";
}
{
node [bgcolor=grey style=filled]
"drm_encoder B" -> "drm_bridge B"
"drm_encoder C" -> "drm_bridge C1"
"drm_bridge C1" -> "drm_bridge C2";
}
}
"drm_crtc" -> "drm_encoder A"
"drm_crtc" -> "drm_encoder B"
"drm_crtc" -> "drm_encoder C"
subgraph cluster_output {
style=dashed
label="Outputs"
"drm_encoder A" -> "drm_connector A";
"drm_bridge B" -> "drm_connector B";
"drm_bridge C2" -> "drm_connector C";
"drm_panel"
}
}
Internally two additional helper objects come into play. First, to be able to
share code for encoders (sometimes on the same SoC, sometimes off-chip) one or
more :ref:`drm_bridges` (represented by :c:type:`struct drm_bridge
<drm_bridge>`) can be linked to an encoder. This link is static and cannot be
changed, which means the cross-bar (if there is any) needs to be mapped between
the CRTC and any encoders. Often for drivers with bridges there's no code left
at the encoder level. Atomic drivers can leave out all the encoder callbacks to
essentially only leave a dummy routing object behind, which is needed for
backwards compatibility since encoders are exposed to userspace.
The second object is for panels, represented by :c:type:`struct drm_panel
<drm_panel>`, see :ref:`drm_panel_helper`. Panels do not have a fixed binding
point, but are generally linked to the driver private structure that embeds
:c:type:`struct drm_connector <drm_connector>`.
Note that currently the bridge chaining and interactions with connectors and
panels are still in-flux and not really fully sorted out yet.
KMS Core Structures and Functions
=================================
.. kernel-doc:: include/drm/drm_mode_config.h
:internal:
.. kernel-doc:: drivers/gpu/drm/drm_mode_config.c
:export:
Modeset Base Object Abstraction
===============================
.. kernel-render:: DOT
:alt: Mode Objects and Properties
:caption: Mode Objects and Properties
digraph {
node [shape=box]
"drm_property A" -> "drm_mode_object A"
"drm_property A" -> "drm_mode_object B"
"drm_property B" -> "drm_mode_object A"
}
The base structure for all KMS objects is :c:type:`struct drm_mode_object
<drm_mode_object>`. One of the base services it provides is tracking properties,
which are especially important for the atomic IOCTL (see `Atomic Mode
Setting`_). The somewhat surprising part here is that properties are not
directly instantiated on each object, but free-standing mode objects themselves,
represented by :c:type:`struct drm_property <drm_property>`, which only specify
the type and value range of a property. Any given property can be attached
multiple times to different objects using :c:func:`drm_object_attach_property()
<drm_object_attach_property>`.
.. kernel-doc:: include/drm/drm_mode_object.h
:internal:
.. kernel-doc:: drivers/gpu/drm/drm_mode_object.c
:export:
Atomic Mode Setting
===================
.. kernel-render:: DOT
:alt: Mode Objects and Properties
:caption: Mode Objects and Properties
digraph {
node [shape=box]
subgraph cluster_state {
style=dashed
label="Free-standing state"
"drm_atomic_state" -> "duplicated drm_plane_state A"
"drm_atomic_state" -> "duplicated drm_plane_state B"
"drm_atomic_state" -> "duplicated drm_crtc_state"
"drm_atomic_state" -> "duplicated drm_connector_state"
"drm_atomic_state" -> "duplicated driver private state"
}
subgraph cluster_current {
style=dashed
label="Current state"
"drm_device" -> "drm_plane A"
"drm_device" -> "drm_plane B"
"drm_device" -> "drm_crtc"
"drm_device" -> "drm_connector"
"drm_device" -> "driver private object"
"drm_plane A" -> "drm_plane_state A"
"drm_plane B" -> "drm_plane_state B"
"drm_crtc" -> "drm_crtc_state"
"drm_connector" -> "drm_connector_state"
"driver private object" -> "driver private state"
}
"drm_atomic_state" -> "drm_device" [label="atomic_commit"]
"duplicated drm_plane_state A" -> "drm_device"[style=invis]
}
Atomic provides transactional modeset (including planes) updates, but a
bit differently from the usual transactional approach of try-commit and
rollback:
- Firstly, no hardware changes are allowed when the commit would fail. This
allows us to implement the DRM_MODE_ATOMIC_TEST_ONLY mode, which allows
userspace to explore whether certain configurations would work or not.
- This would still allow setting and rollback of just the software state,
simplifying conversion of existing drivers. But auditing drivers for
correctness of the atomic_check code becomes really hard with that: Rolling
back changes in data structures all over the place is hard to get right.
- Lastly, for backwards compatibility and to support all use-cases, atomic
updates need to be incremental and be able to execute in parallel. Hardware
doesn't always allow it, but where possible plane updates on different CRTCs
should not interfere, and not get stalled due to output routing changing on
different CRTCs.
Taken all together there's two consequences for the atomic design:
- The overall state is split up into per-object state structures:
:c:type:`struct drm_plane_state <drm_plane_state>` for planes, :c:type:`struct
drm_crtc_state <drm_crtc_state>` for CRTCs and :c:type:`struct
drm_connector_state <drm_connector_state>` for connectors. These are the only
objects with userspace-visible and settable state. For internal state drivers
can subclass these structures through embeddeding, or add entirely new state
structures for their globally shared hardware functions.
- An atomic update is assembled and validated as an entirely free-standing pile
of structures within the :c:type:`drm_atomic_state <drm_atomic_state>`
container. Driver private state structures are also tracked in the same
structure; see the next chapter. Only when a state is committed is it applied
to the driver and modeset objects. This way rolling back an update boils down
to releasing memory and unreferencing objects like framebuffers.
Read on in this chapter, and also in :ref:`drm_atomic_helper` for more detailed
coverage of specific topics.
Handling Driver Private State
-----------------------------
.. kernel-doc:: drivers/gpu/drm/drm_atomic.c
:doc: handling driver private state
Atomic Mode Setting Function Reference
--------------------------------------
.. kernel-doc:: include/drm/drm_atomic.h
:internal:
.. kernel-doc:: drivers/gpu/drm/drm_atomic.c
:export:
.. kernel-doc:: drivers/gpu/drm/drm_atomic.c
:internal:
CRTC Abstraction
================
.. kernel-doc:: drivers/gpu/drm/drm_crtc.c
:doc: overview
CRTC Functions Reference
--------------------------------
.. kernel-doc:: include/drm/drm_crtc.h
:internal:
.. kernel-doc:: drivers/gpu/drm/drm_crtc.c
:export:
Frame Buffer Abstraction
========================
.. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c
:doc: overview
Frame Buffer Functions Reference
--------------------------------
.. kernel-doc:: include/drm/drm_framebuffer.h
:internal:
.. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c
:export:
DRM Format Handling
===================
.. kernel-doc:: include/drm/drm_fourcc.h
:internal:
.. kernel-doc:: drivers/gpu/drm/drm_fourcc.c
:export:
Dumb Buffer Objects
===================
.. kernel-doc:: drivers/gpu/drm/drm_dumb_buffers.c
:doc: overview
Plane Abstraction
=================
.. kernel-doc:: drivers/gpu/drm/drm_plane.c
:doc: overview
Plane Functions Reference
-------------------------
.. kernel-doc:: include/drm/drm_plane.h
:internal:
.. kernel-doc:: drivers/gpu/drm/drm_plane.c
:export:
Display Modes Function Reference
================================
.. kernel-doc:: include/drm/drm_modes.h
:internal:
.. kernel-doc:: drivers/gpu/drm/drm_modes.c
:export:
Connector Abstraction
=====================
.. kernel-doc:: drivers/gpu/drm/drm_connector.c
:doc: overview
Connector Functions Reference
-----------------------------
.. kernel-doc:: include/drm/drm_connector.h
:internal:
.. kernel-doc:: drivers/gpu/drm/drm_connector.c
:export:
Writeback Connectors
--------------------
.. kernel-doc:: drivers/gpu/drm/drm_writeback.c
:doc: overview
.. kernel-doc:: drivers/gpu/drm/drm_writeback.c
:export:
Encoder Abstraction
===================
.. kernel-doc:: drivers/gpu/drm/drm_encoder.c
:doc: overview
Encoder Functions Reference
---------------------------
.. kernel-doc:: include/drm/drm_encoder.h
:internal:
.. kernel-doc:: drivers/gpu/drm/drm_encoder.c
:export:
KMS Initialization and Cleanup
==============================
A KMS device is abstracted and exposed as a set of planes, CRTCs,
encoders and connectors. KMS drivers must thus create and initialize all
those objects at load time after initializing mode setting.
CRTCs (:c:type:`struct drm_crtc <drm_crtc>`)
--------------------------------------------
A CRTC is an abstraction representing a part of the chip that contains a
pointer to a scanout buffer. Therefore, the number of CRTCs available
determines how many independent scanout buffers can be active at any
given time. The CRTC structure contains several fields to support this:
a pointer to some video memory (abstracted as a frame buffer object), a
display mode, and an (x, y) offset into the video memory to support
panning or configurations where one piece of video memory spans multiple
CRTCs.
CRTC Initialization
~~~~~~~~~~~~~~~~~~~
A KMS device must create and register at least one struct
:c:type:`struct drm_crtc <drm_crtc>` instance. The instance is
allocated and zeroed by the driver, possibly as part of a larger
structure, and registered with a call to :c:func:`drm_crtc_init()`
with a pointer to CRTC functions.
Cleanup
-------
The DRM core manages its objects' lifetime. When an object is not needed
anymore the core calls its destroy function, which must clean up and
free every resource allocated for the object. Every
:c:func:`drm_\*_init()` call must be matched with a corresponding
:c:func:`drm_\*_cleanup()` call to cleanup CRTCs
(:c:func:`drm_crtc_cleanup()`), planes
(:c:func:`drm_plane_cleanup()`), encoders
(:c:func:`drm_encoder_cleanup()`) and connectors
(:c:func:`drm_connector_cleanup()`). Furthermore, connectors that
have been added to sysfs must be removed by a call to
:c:func:`drm_connector_unregister()` before calling
:c:func:`drm_connector_cleanup()`.
Connectors state change detection must be cleanup up with a call to
:c:func:`drm_kms_helper_poll_fini()`.
Output discovery and initialization example
-------------------------------------------
.. code-block:: c
void intel_crt_init(struct drm_device *dev)
{
struct drm_connector *connector;
struct intel_output *intel_output;
intel_output = kzalloc(sizeof(struct intel_output), GFP_KERNEL);
if (!intel_output)
return;
connector = &intel_output->base;
drm_connector_init(dev, &intel_output->base,
&intel_crt_connector_funcs, DRM_MODE_CONNECTOR_VGA);
drm_encoder_init(dev, &intel_output->enc, &intel_crt_enc_funcs,
DRM_MODE_ENCODER_DAC);
drm_connector_attach_encoder(&intel_output->base,
&intel_output->enc);
/* Set up the DDC bus. */
intel_output->ddc_bus = intel_i2c_create(dev, GPIOA, "CRTDDC_A");
if (!intel_output->ddc_bus) {
dev_printk(KERN_ERR, &dev->pdev->dev, "DDC bus registration "
"failed.\n");
return;
}
intel_output->type = INTEL_OUTPUT_ANALOG;
connector->interlace_allowed = 0;
connector->doublescan_allowed = 0;
drm_encoder_helper_add(&intel_output->enc, &intel_crt_helper_funcs);
drm_connector_helper_add(connector, &intel_crt_connector_helper_funcs);
drm_connector_register(connector);
}
In the example above (taken from the i915 driver), a CRTC, connector and
encoder combination is created. A device-specific i2c bus is also
created for fetching EDID data and performing monitor detection. Once
the process is complete, the new connector is registered with sysfs to
make its properties available to applications.
KMS Locking
===========
.. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c
:doc: kms locking
.. kernel-doc:: include/drm/drm_modeset_lock.h
:internal:
.. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c
:export:
KMS Properties
==============
Property Types and Blob Property Support
----------------------------------------
.. kernel-doc:: drivers/gpu/drm/drm_property.c
:doc: overview
.. kernel-doc:: include/drm/drm_property.h
:internal:
.. kernel-doc:: drivers/gpu/drm/drm_property.c
:export:
Standard Connector Properties
-----------------------------
.. kernel-doc:: drivers/gpu/drm/drm_connector.c
:doc: standard connector properties
HDMI Specific Connector Properties
----------------------------------
.. kernel-doc:: drivers/gpu/drm/drm_connector.c
:doc: HDMI connector properties
Plane Composition Properties
----------------------------
.. kernel-doc:: drivers/gpu/drm/drm_blend.c
:doc: overview
.. kernel-doc:: drivers/gpu/drm/drm_blend.c
:export:
Color Management Properties
---------------------------
.. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c
:doc: overview
.. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c
:export:
Tile Group Property
-------------------
.. kernel-doc:: drivers/gpu/drm/drm_connector.c
:doc: Tile group
Explicit Fencing Properties
---------------------------
.. kernel-doc:: drivers/gpu/drm/drm_atomic.c
:doc: explicit fencing properties
Existing KMS Properties
-----------------------
The following table gives description of drm properties exposed by various
modules/drivers. Because this table is very unwieldy, do not add any new
properties here. Instead document them in a section above.
.. csv-table::
:header-rows: 1
:file: kms-properties.csv
Vertical Blanking
=================
.. kernel-doc:: drivers/gpu/drm/drm_vblank.c
:doc: vblank handling
Vertical Blanking and Interrupt Handling Functions Reference
------------------------------------------------------------
.. kernel-doc:: include/drm/drm_vblank.h
:internal:
.. kernel-doc:: drivers/gpu/drm/drm_vblank.c
:export:
+518
View File
@@ -0,0 +1,518 @@
=====================
DRM Memory Management
=====================
Modern Linux systems require large amount of graphics memory to store
frame buffers, textures, vertices and other graphics-related data. Given
the very dynamic nature of many of that data, managing graphics memory
efficiently is thus crucial for the graphics stack and plays a central
role in the DRM infrastructure.
The DRM core includes two memory managers, namely Translation Table Maps
(TTM) and Graphics Execution Manager (GEM). TTM was the first DRM memory
manager to be developed and tried to be a one-size-fits-them all
solution. It provides a single userspace API to accommodate the need of
all hardware, supporting both Unified Memory Architecture (UMA) devices
and devices with dedicated video RAM (i.e. most discrete video cards).
This resulted in a large, complex piece of code that turned out to be
hard to use for driver development.
GEM started as an Intel-sponsored project in reaction to TTM's
complexity. Its design philosophy is completely different: instead of
providing a solution to every graphics memory-related problems, GEM
identified common code between drivers and created a support library to
share it. GEM has simpler initialization and execution requirements than
TTM, but has no video RAM management capabilities and is thus limited to
UMA devices.
The Translation Table Manager (TTM)
===================================
TTM design background and information belongs here.
TTM initialization
------------------
**Warning**
This section is outdated.
Drivers wishing to support TTM must pass a filled :c:type:`ttm_bo_driver
<ttm_bo_driver>` structure to ttm_bo_device_init, together with an
initialized global reference to the memory manager. The ttm_bo_driver
structure contains several fields with function pointers for
initializing the TTM, allocating and freeing memory, waiting for command
completion and fence synchronization, and memory migration.
The :c:type:`struct drm_global_reference <drm_global_reference>` is made
up of several fields:
.. code-block:: c
struct drm_global_reference {
enum ttm_global_types global_type;
size_t size;
void *object;
int (*init) (struct drm_global_reference *);
void (*release) (struct drm_global_reference *);
};
There should be one global reference structure for your memory manager
as a whole, and there will be others for each object created by the
memory manager at runtime. Your global TTM should have a type of
TTM_GLOBAL_TTM_MEM. The size field for the global object should be
sizeof(struct ttm_mem_global), and the init and release hooks should
point at your driver-specific init and release routines, which probably
eventually call ttm_mem_global_init and ttm_mem_global_release,
respectively.
Once your global TTM accounting structure is set up and initialized by
calling ttm_global_item_ref() on it, you need to create a buffer
object TTM to provide a pool for buffer object allocation by clients and
the kernel itself. The type of this object should be
TTM_GLOBAL_TTM_BO, and its size should be sizeof(struct
ttm_bo_global). Again, driver-specific init and release functions may
be provided, likely eventually calling ttm_bo_global_init() and
ttm_bo_global_release(), respectively. Also, like the previous
object, ttm_global_item_ref() is used to create an initial reference
count for the TTM, which will call your initialization function.
See the radeon_ttm.c file for an example of usage.
.. kernel-doc:: drivers/gpu/drm/drm_global.c
:export:
The Graphics Execution Manager (GEM)
====================================
The GEM design approach has resulted in a memory manager that doesn't
provide full coverage of all (or even all common) use cases in its
userspace or kernel API. GEM exposes a set of standard memory-related
operations to userspace and a set of helper functions to drivers, and
let drivers implement hardware-specific operations with their own
private API.
The GEM userspace API is described in the `GEM - the Graphics Execution
Manager <http://lwn.net/Articles/283798/>`__ article on LWN. While
slightly outdated, the document provides a good overview of the GEM API
principles. Buffer allocation and read and write operations, described
as part of the common GEM API, are currently implemented using
driver-specific ioctls.
GEM is data-agnostic. It manages abstract buffer objects without knowing
what individual buffers contain. APIs that require knowledge of buffer
contents or purpose, such as buffer allocation or synchronization
primitives, are thus outside of the scope of GEM and must be implemented
using driver-specific ioctls.
On a fundamental level, GEM involves several operations:
- Memory allocation and freeing
- Command execution
- Aperture management at command execution time
Buffer object allocation is relatively straightforward and largely
provided by Linux's shmem layer, which provides memory to back each
object.
Device-specific operations, such as command execution, pinning, buffer
read & write, mapping, and domain ownership transfers are left to
driver-specific ioctls.
GEM Initialization
------------------
Drivers that use GEM must set the DRIVER_GEM bit in the struct
:c:type:`struct drm_driver <drm_driver>` driver_features
field. The DRM core will then automatically initialize the GEM core
before calling the load operation. Behind the scene, this will create a
DRM Memory Manager object which provides an address space pool for
object allocation.
In a KMS configuration, drivers need to allocate and initialize a
command ring buffer following core GEM initialization if required by the
hardware. UMA devices usually have what is called a "stolen" memory
region, which provides space for the initial framebuffer and large,
contiguous memory regions required by the device. This space is
typically not managed by GEM, and must be initialized separately into
its own DRM MM object.
GEM Objects Creation
--------------------
GEM splits creation of GEM objects and allocation of the memory that
backs them in two distinct operations.
GEM objects are represented by an instance of struct :c:type:`struct
drm_gem_object <drm_gem_object>`. Drivers usually need to
extend GEM objects with private information and thus create a
driver-specific GEM object structure type that embeds an instance of
struct :c:type:`struct drm_gem_object <drm_gem_object>`.
To create a GEM object, a driver allocates memory for an instance of its
specific GEM object type and initializes the embedded struct
:c:type:`struct drm_gem_object <drm_gem_object>` with a call
to :c:func:`drm_gem_object_init()`. The function takes a pointer
to the DRM device, a pointer to the GEM object and the buffer object
size in bytes.
GEM uses shmem to allocate anonymous pageable memory.
:c:func:`drm_gem_object_init()` will create an shmfs file of the
requested size and store it into the struct :c:type:`struct
drm_gem_object <drm_gem_object>` filp field. The memory is
used as either main storage for the object when the graphics hardware
uses system memory directly or as a backing store otherwise.
Drivers are responsible for the actual physical pages allocation by
calling :c:func:`shmem_read_mapping_page_gfp()` for each page.
Note that they can decide to allocate pages when initializing the GEM
object, or to delay allocation until the memory is needed (for instance
when a page fault occurs as a result of a userspace memory access or
when the driver needs to start a DMA transfer involving the memory).
Anonymous pageable memory allocation is not always desired, for instance
when the hardware requires physically contiguous system memory as is
often the case in embedded devices. Drivers can create GEM objects with
no shmfs backing (called private GEM objects) by initializing them with
a call to :c:func:`drm_gem_private_object_init()` instead of
:c:func:`drm_gem_object_init()`. Storage for private GEM objects
must be managed by drivers.
GEM Objects Lifetime
--------------------
All GEM objects are reference-counted by the GEM core. References can be
acquired and release by :c:func:`calling drm_gem_object_get()` and
:c:func:`drm_gem_object_put()` respectively. The caller must hold the
:c:type:`struct drm_device <drm_device>` struct_mutex lock when calling
:c:func:`drm_gem_object_get()`. As a convenience, GEM provides
:c:func:`drm_gem_object_put_unlocked()` functions that can be called without
holding the lock.
When the last reference to a GEM object is released the GEM core calls
the :c:type:`struct drm_driver <drm_driver>` gem_free_object_unlocked
operation. That operation is mandatory for GEM-enabled drivers and must
free the GEM object and all associated resources.
void (\*gem_free_object) (struct drm_gem_object \*obj); Drivers are
responsible for freeing all GEM object resources. This includes the
resources created by the GEM core, which need to be released with
:c:func:`drm_gem_object_release()`.
GEM Objects Naming
------------------
Communication between userspace and the kernel refers to GEM objects
using local handles, global names or, more recently, file descriptors.
All of those are 32-bit integer values; the usual Linux kernel limits
apply to the file descriptors.
GEM handles are local to a DRM file. Applications get a handle to a GEM
object through a driver-specific ioctl, and can use that handle to refer
to the GEM object in other standard or driver-specific ioctls. Closing a
DRM file handle frees all its GEM handles and dereferences the
associated GEM objects.
To create a handle for a GEM object drivers call
:c:func:`drm_gem_handle_create()`. The function takes a pointer
to the DRM file and the GEM object and returns a locally unique handle.
When the handle is no longer needed drivers delete it with a call to
:c:func:`drm_gem_handle_delete()`. Finally the GEM object
associated with a handle can be retrieved by a call to
:c:func:`drm_gem_object_lookup()`.
Handles don't take ownership of GEM objects, they only take a reference
to the object that will be dropped when the handle is destroyed. To
avoid leaking GEM objects, drivers must make sure they drop the
reference(s) they own (such as the initial reference taken at object
creation time) as appropriate, without any special consideration for the
handle. For example, in the particular case of combined GEM object and
handle creation in the implementation of the dumb_create operation,
drivers must drop the initial reference to the GEM object before
returning the handle.
GEM names are similar in purpose to handles but are not local to DRM
files. They can be passed between processes to reference a GEM object
globally. Names can't be used directly to refer to objects in the DRM
API, applications must convert handles to names and names to handles
using the DRM_IOCTL_GEM_FLINK and DRM_IOCTL_GEM_OPEN ioctls
respectively. The conversion is handled by the DRM core without any
driver-specific support.
GEM also supports buffer sharing with dma-buf file descriptors through
PRIME. GEM-based drivers must use the provided helpers functions to
implement the exporting and importing correctly. See ?. Since sharing
file descriptors is inherently more secure than the easily guessable and
global GEM names it is the preferred buffer sharing mechanism. Sharing
buffers through GEM names is only supported for legacy userspace.
Furthermore PRIME also allows cross-device buffer sharing since it is
based on dma-bufs.
GEM Objects Mapping
-------------------
Because mapping operations are fairly heavyweight GEM favours
read/write-like access to buffers, implemented through driver-specific
ioctls, over mapping buffers to userspace. However, when random access
to the buffer is needed (to perform software rendering for instance),
direct access to the object can be more efficient.
The mmap system call can't be used directly to map GEM objects, as they
don't have their own file handle. Two alternative methods currently
co-exist to map GEM objects to userspace. The first method uses a
driver-specific ioctl to perform the mapping operation, calling
:c:func:`do_mmap()` under the hood. This is often considered
dubious, seems to be discouraged for new GEM-enabled drivers, and will
thus not be described here.
The second method uses the mmap system call on the DRM file handle. void
\*mmap(void \*addr, size_t length, int prot, int flags, int fd, off_t
offset); DRM identifies the GEM object to be mapped by a fake offset
passed through the mmap offset argument. Prior to being mapped, a GEM
object must thus be associated with a fake offset. To do so, drivers
must call :c:func:`drm_gem_create_mmap_offset()` on the object.
Once allocated, the fake offset value must be passed to the application
in a driver-specific way and can then be used as the mmap offset
argument.
The GEM core provides a helper method :c:func:`drm_gem_mmap()` to
handle object mapping. The method can be set directly as the mmap file
operation handler. It will look up the GEM object based on the offset
value and set the VMA operations to the :c:type:`struct drm_driver
<drm_driver>` gem_vm_ops field. Note that
:c:func:`drm_gem_mmap()` doesn't map memory to userspace, but
relies on the driver-provided fault handler to map pages individually.
To use :c:func:`drm_gem_mmap()`, drivers must fill the struct
:c:type:`struct drm_driver <drm_driver>` gem_vm_ops field
with a pointer to VM operations.
The VM operations is a :c:type:`struct vm_operations_struct <vm_operations_struct>`
made up of several fields, the more interesting ones being:
.. code-block:: c
struct vm_operations_struct {
void (*open)(struct vm_area_struct * area);
void (*close)(struct vm_area_struct * area);
int (*fault)(struct vm_fault *vmf);
};
The open and close operations must update the GEM object reference
count. Drivers can use the :c:func:`drm_gem_vm_open()` and
:c:func:`drm_gem_vm_close()` helper functions directly as open
and close handlers.
The fault operation handler is responsible for mapping individual pages
to userspace when a page fault occurs. Depending on the memory
allocation scheme, drivers can allocate pages at fault time, or can
decide to allocate memory for the GEM object at the time the object is
created.
Drivers that want to map the GEM object upfront instead of handling page
faults can implement their own mmap file operation handler.
For platforms without MMU the GEM core provides a helper method
:c:func:`drm_gem_cma_get_unmapped_area`. The mmap() routines will call
this to get a proposed address for the mapping.
To use :c:func:`drm_gem_cma_get_unmapped_area`, drivers must fill the
struct :c:type:`struct file_operations <file_operations>` get_unmapped_area
field with a pointer on :c:func:`drm_gem_cma_get_unmapped_area`.
More detailed information about get_unmapped_area can be found in
Documentation/nommu-mmap.txt
Memory Coherency
----------------
When mapped to the device or used in a command buffer, backing pages for
an object are flushed to memory and marked write combined so as to be
coherent with the GPU. Likewise, if the CPU accesses an object after the
GPU has finished rendering to the object, then the object must be made
coherent with the CPU's view of memory, usually involving GPU cache
flushing of various kinds. This core CPU<->GPU coherency management is
provided by a device-specific ioctl, which evaluates an object's current
domain and performs any necessary flushing or synchronization to put the
object into the desired coherency domain (note that the object may be
busy, i.e. an active render target; in that case, setting the domain
blocks the client and waits for rendering to complete before performing
any necessary flushing operations).
Command Execution
-----------------
Perhaps the most important GEM function for GPU devices is providing a
command execution interface to clients. Client programs construct
command buffers containing references to previously allocated memory
objects, and then submit them to GEM. At that point, GEM takes care to
bind all the objects into the GTT, execute the buffer, and provide
necessary synchronization between clients accessing the same buffers.
This often involves evicting some objects from the GTT and re-binding
others (a fairly expensive operation), and providing relocation support
which hides fixed GTT offsets from clients. Clients must take care not
to submit command buffers that reference more objects than can fit in
the GTT; otherwise, GEM will reject them and no rendering will occur.
Similarly, if several objects in the buffer require fence registers to
be allocated for correct rendering (e.g. 2D blits on pre-965 chips),
care must be taken not to require more fence registers than are
available to the client. Such resource management should be abstracted
from the client in libdrm.
GEM Function Reference
----------------------
.. kernel-doc:: include/drm/drm_gem.h
:internal:
.. kernel-doc:: drivers/gpu/drm/drm_gem.c
:export:
GEM CMA Helper Functions Reference
----------------------------------
.. kernel-doc:: drivers/gpu/drm/drm_gem_cma_helper.c
:doc: cma helpers
.. kernel-doc:: include/drm/drm_gem_cma_helper.h
:internal:
.. kernel-doc:: drivers/gpu/drm/drm_gem_cma_helper.c
:export:
VMA Offset Manager
==================
.. kernel-doc:: drivers/gpu/drm/drm_vma_manager.c
:doc: vma offset manager
.. kernel-doc:: include/drm/drm_vma_manager.h
:internal:
.. kernel-doc:: drivers/gpu/drm/drm_vma_manager.c
:export:
.. _prime_buffer_sharing:
PRIME Buffer Sharing
====================
PRIME is the cross device buffer sharing framework in drm, originally
created for the OPTIMUS range of multi-gpu platforms. To userspace PRIME
buffers are dma-buf based file descriptors.
Overview and Driver Interface
-----------------------------
Similar to GEM global names, PRIME file descriptors are also used to
share buffer objects across processes. They offer additional security:
as file descriptors must be explicitly sent over UNIX domain sockets to
be shared between applications, they can't be guessed like the globally
unique GEM names.
Drivers that support the PRIME API must set the DRIVER_PRIME bit in the
struct :c:type:`struct drm_driver <drm_driver>`
driver_features field, and implement the prime_handle_to_fd and
prime_fd_to_handle operations.
int (\*prime_handle_to_fd)(struct drm_device \*dev, struct drm_file
\*file_priv, uint32_t handle, uint32_t flags, int \*prime_fd); int
(\*prime_fd_to_handle)(struct drm_device \*dev, struct drm_file
\*file_priv, int prime_fd, uint32_t \*handle); Those two operations
convert a handle to a PRIME file descriptor and vice versa. Drivers must
use the kernel dma-buf buffer sharing framework to manage the PRIME file
descriptors. Similar to the mode setting API PRIME is agnostic to the
underlying buffer object manager, as long as handles are 32bit unsigned
integers.
While non-GEM drivers must implement the operations themselves, GEM
drivers must use the :c:func:`drm_gem_prime_handle_to_fd()` and
:c:func:`drm_gem_prime_fd_to_handle()` helper functions. Those
helpers rely on the driver gem_prime_export and gem_prime_import
operations to create a dma-buf instance from a GEM object (dma-buf
exporter role) and to create a GEM object from a dma-buf instance
(dma-buf importer role).
struct dma_buf \* (\*gem_prime_export)(struct drm_device \*dev,
struct drm_gem_object \*obj, int flags); struct drm_gem_object \*
(\*gem_prime_import)(struct drm_device \*dev, struct dma_buf
\*dma_buf); These two operations are mandatory for GEM drivers that
support PRIME.
PRIME Helper Functions
----------------------
.. kernel-doc:: drivers/gpu/drm/drm_prime.c
:doc: PRIME Helpers
PRIME Function References
-------------------------
.. kernel-doc:: include/drm/drm_prime.h
:internal:
.. kernel-doc:: drivers/gpu/drm/drm_prime.c
:export:
DRM MM Range Allocator
======================
Overview
--------
.. kernel-doc:: drivers/gpu/drm/drm_mm.c
:doc: Overview
LRU Scan/Eviction Support
-------------------------
.. kernel-doc:: drivers/gpu/drm/drm_mm.c
:doc: lru scan roster
DRM MM Range Allocator Function References
------------------------------------------
.. kernel-doc:: include/drm/drm_mm.h
:internal:
.. kernel-doc:: drivers/gpu/drm/drm_mm.c
:export:
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
:internal:
.. kernel-doc:: drivers/gpu/drm/drm_syncobj.c
:export:
GPU Scheduler
=============
Overview
--------
.. kernel-doc:: drivers/gpu/drm/scheduler/gpu_scheduler.c
:doc: Overview
Scheduler Function References
-----------------------------
.. kernel-doc:: include/drm/gpu_scheduler.h
:internal:
.. kernel-doc:: drivers/gpu/drm/scheduler/gpu_scheduler.c
:export:
+318
View File
@@ -0,0 +1,318 @@
===================
Userland interfaces
===================
The DRM core exports several interfaces to applications, generally
intended to be used through corresponding libdrm wrapper functions. In
addition, drivers export device-specific interfaces for use by userspace
drivers & device-aware applications through ioctls and sysfs files.
External interfaces include: memory mapping, context management, DMA
operations, AGP management, vblank control, fence management, memory
management, and output management.
Cover generic ioctls and sysfs layout here. We only need high-level
info, since man pages should cover the rest.
libdrm Device Lookup
====================
.. kernel-doc:: drivers/gpu/drm/drm_ioctl.c
:doc: getunique and setversion story
.. _drm_primary_node:
Primary Nodes, DRM Master and Authentication
============================================
.. kernel-doc:: drivers/gpu/drm/drm_auth.c
:doc: master and authentication
.. kernel-doc:: drivers/gpu/drm/drm_auth.c
:export:
.. kernel-doc:: include/drm/drm_auth.h
:internal:
Open-Source Userspace Requirements
==================================
The DRM subsystem has stricter requirements than most other kernel subsystems on
what the userspace side for new uAPI needs to look like. This section here
explains what exactly those requirements are, and why they exist.
The short summary is that any addition of DRM uAPI requires corresponding
open-sourced userspace patches, and those patches must be reviewed and ready for
merging into a suitable and canonical upstream project.
GFX devices (both display and render/GPU side) are really complex bits of
hardware, with userspace and kernel by necessity having to work together really
closely. The interfaces, for rendering and modesetting, must be extremely wide
and flexible, and therefore it is almost always impossible to precisely define
them for every possible corner case. This in turn makes it really practically
infeasible to differentiate between behaviour that's required by userspace, and
which must not be changed to avoid regressions, and behaviour which is only an
accidental artifact of the current implementation.
Without access to the full source code of all userspace users that means it
becomes impossible to change the implementation details, since userspace could
depend upon the accidental behaviour of the current implementation in minute
details. And debugging such regressions without access to source code is pretty
much impossible. As a consequence this means:
- The Linux kernel's "no regression" policy holds in practice only for
open-source userspace of the DRM subsystem. DRM developers are perfectly fine
if closed-source blob drivers in userspace use the same uAPI as the open
drivers, but they must do so in the exact same way as the open drivers.
Creative (ab)use of the interfaces will, and in the past routinely has, lead
to breakage.
- Any new userspace interface must have an open-source implementation as
demonstration vehicle.
The other reason for requiring open-source userspace is uAPI review. Since the
kernel and userspace parts of a GFX stack must work together so closely, code
review can only assess whether a new interface achieves its goals by looking at
both sides. Making sure that the interface indeed covers the use-case fully
leads to a few additional requirements:
- The open-source userspace must not be a toy/test application, but the real
thing. Specifically it needs to handle all the usual error and corner cases.
These are often the places where new uAPI falls apart and hence essential to
assess the fitness of a proposed interface.
- The userspace side must be fully reviewed and tested to the standards of that
userspace project. For e.g. mesa this means piglit testcases and review on the
mailing list. This is again to ensure that the new interface actually gets the
job done.
- The userspace patches must be against the canonical upstream, not some vendor
fork. This is to make sure that no one cheats on the review and testing
requirements by doing a quick fork.
- The kernel patch can only be merged after all the above requirements are met,
but it **must** be merged **before** the userspace patches land. uAPI always flows
from the kernel, doing things the other way round risks divergence of the uAPI
definitions and header files.
These are fairly steep requirements, but have grown out from years of shared
pain and experience with uAPI added hastily, and almost always regretted about
just as fast. GFX devices change really fast, requiring a paradigm shift and
entire new set of uAPI interfaces every few years at least. Together with the
Linux kernel's guarantee to keep existing userspace running for 10+ years this
is already rather painful for the DRM subsystem, with multiple different uAPIs
for the same thing co-existing. If we add a few more complete mistakes into the
mix every year it would be entirely unmanageable.
.. _drm_render_node:
Render nodes
============
DRM core provides multiple character-devices for user-space to use.
Depending on which device is opened, user-space can perform a different
set of operations (mainly ioctls). The primary node is always created
and called card<num>. Additionally, a currently unused control node,
called controlD<num> is also created. The primary node provides all
legacy operations and historically was the only interface used by
userspace. With KMS, the control node was introduced. However, the
planned KMS control interface has never been written and so the control
node stays unused to date.
With the increased use of offscreen renderers and GPGPU applications,
clients no longer require running compositors or graphics servers to
make use of a GPU. But the DRM API required unprivileged clients to
authenticate to a DRM-Master prior to getting GPU access. To avoid this
step and to grant clients GPU access without authenticating, render
nodes were introduced. Render nodes solely serve render clients, that
is, no modesetting or privileged ioctls can be issued on render nodes.
Only non-global rendering commands are allowed. If a driver supports
render nodes, it must advertise it via the DRIVER_RENDER DRM driver
capability. If not supported, the primary node must be used for render
clients together with the legacy drmAuth authentication procedure.
If a driver advertises render node support, DRM core will create a
separate render node called renderD<num>. There will be one render node
per device. No ioctls except PRIME-related ioctls will be allowed on
this node. Especially GEM_OPEN will be explicitly prohibited. Render
nodes are designed to avoid the buffer-leaks, which occur if clients
guess the flink names or mmap offsets on the legacy interface.
Additionally to this basic interface, drivers must mark their
driver-dependent render-only ioctls as DRM_RENDER_ALLOW so render
clients can use them. Driver authors must be careful not to allow any
privileged ioctls on render nodes.
With render nodes, user-space can now control access to the render node
via basic file-system access-modes. A running graphics server which
authenticates clients on the privileged primary/legacy node is no longer
required. Instead, a client can open the render node and is immediately
granted GPU access. Communication between clients (or servers) is done
via PRIME. FLINK from render node to legacy node is not supported. New
clients must not use the insecure FLINK interface.
Besides dropping all modeset/global ioctls, render nodes also drop the
DRM-Master concept. There is no reason to associate render clients with
a DRM-Master as they are independent of any graphics server. Besides,
they must work without any running master, anyway. Drivers must be able
to run without a master object if they support render nodes. If, on the
other hand, a driver requires shared state between clients which is
visible to user-space and accessible beyond open-file boundaries, they
cannot support render nodes.
.. _drm_driver_ioctl:
IOCTL Support on Device Nodes
=============================
.. kernel-doc:: drivers/gpu/drm/drm_ioctl.c
:doc: driver specific ioctls
Recommended IOCTL Return Values
-------------------------------
In theory a driver's IOCTL callback is only allowed to return very few error
codes. In practice it's good to abuse a few more. This section documents common
practice within the DRM subsystem:
ENOENT:
Strictly this should only be used when a file doesn't exist e.g. when
calling the open() syscall. We reuse that to signal any kind of object
lookup failure, e.g. for unknown GEM buffer object handles, unknown KMS
object handles and similar cases.
ENOSPC:
Some drivers use this to differentiate "out of kernel memory" from "out
of VRAM". Sometimes also applies to other limited gpu resources used for
rendering (e.g. when you have a special limited compression buffer).
Sometimes resource allocation/reservation issues in command submission
IOCTLs are also signalled through EDEADLK.
Simply running out of kernel/system memory is signalled through ENOMEM.
EPERM/EACCESS:
Returned for an operation that is valid, but needs more privileges.
E.g. root-only or much more common, DRM master-only operations return
this when when called by unpriviledged clients. There's no clear
difference between EACCESS and EPERM.
ENODEV:
Feature (like PRIME, modesetting, GEM) is not supported by the driver.
ENXIO:
Remote failure, either a hardware transaction (like i2c), but also used
when the exporting driver of a shared dma-buf or fence doesn't support a
feature needed.
EINTR:
DRM drivers assume that userspace restarts all IOCTLs. Any DRM IOCTL can
return EINTR and in such a case should be restarted with the IOCTL
parameters left unchanged.
EIO:
The GPU died and couldn't be resurrected through a reset. Modesetting
hardware failures are signalled through the "link status" connector
property.
EINVAL:
Catch-all for anything that is an invalid argument combination which
cannot work.
IOCTL also use other error codes like ETIME, EFAULT, EBUSY, ENOTTY but their
usage is in line with the common meanings. The above list tries to just document
DRM specific patterns. Note that ENOTTY has the slightly unintuitive meaning of
"this IOCTL does not exist", and is used exactly as such in DRM.
.. kernel-doc:: include/drm/drm_ioctl.h
:internal:
.. kernel-doc:: drivers/gpu/drm/drm_ioctl.c
:export:
.. kernel-doc:: drivers/gpu/drm/drm_ioc32.c
:export:
Testing and validation
======================
Validating changes with IGT
---------------------------
There's a collection of tests that aims to cover the whole functionality of
DRM drivers and that can be used to check that changes to DRM drivers or the
core don't regress existing functionality. This test suite is called IGT and
its code can be found in https://cgit.freedesktop.org/drm/igt-gpu-tools/.
To build IGT, start by installing its build dependencies. In Debian-based
systems::
# apt-get build-dep intel-gpu-tools
And in Fedora-based systems::
# dnf builddep intel-gpu-tools
Then clone the repository::
$ git clone git://anongit.freedesktop.org/drm/igt-gpu-tools
Configure the build system and start the build::
$ cd igt-gpu-tools && ./autogen.sh && make -j6
Download the piglit dependency::
$ ./scripts/run-tests.sh -d
And run the tests::
$ ./scripts/run-tests.sh -t kms -t core -s
run-tests.sh is a wrapper around piglit that will execute the tests matching
the -t options. A report in HTML format will be available in
./results/html/index.html. Results can be compared with piglit.
Display CRC Support
-------------------
.. kernel-doc:: drivers/gpu/drm/drm_debugfs_crc.c
:doc: CRC ABI
.. kernel-doc:: drivers/gpu/drm/drm_debugfs_crc.c
:export:
Debugfs Support
---------------
.. kernel-doc:: include/drm/drm_debugfs.h
:internal:
.. kernel-doc:: drivers/gpu/drm/drm_debugfs.c
:export:
Sysfs Support
=============
.. kernel-doc:: drivers/gpu/drm/drm_sysfs.c
:doc: overview
.. kernel-doc:: drivers/gpu/drm/drm_sysfs.c
:export:
VBlank event handling
=====================
The DRM core exposes two vertical blank related ioctls:
DRM_IOCTL_WAIT_VBLANK
This takes a struct drm_wait_vblank structure as its argument, and
it is used to block or request a signal when a specified vblank
event occurs.
DRM_IOCTL_MODESET_CTL
This was only used for user-mode-settind drivers around modesetting
changes to allow the kernel to update the vblank interrupt after
mode setting, since on many devices the vertical blank counter is
reset to 0 at some point during modeset. Modern drivers should not
call this any more since with kernel mode setting it is a no-op.
+594
View File
@@ -0,0 +1,594 @@
===========================
drm/i915 Intel GFX Driver
===========================
The drm/i915 driver supports all (with the exception of some very early
models) integrated GFX chipsets with both Intel display and rendering
blocks. This excludes a set of SoC platforms with an SGX rendering unit,
those have basic support through the gma500 drm driver.
Core Driver Infrastructure
==========================
This section covers core driver infrastructure used by both the display
and the GEM parts of the driver.
Runtime Power Management
------------------------
.. kernel-doc:: drivers/gpu/drm/i915/intel_runtime_pm.c
:doc: runtime pm
.. kernel-doc:: drivers/gpu/drm/i915/intel_runtime_pm.c
:internal:
.. kernel-doc:: drivers/gpu/drm/i915/intel_uncore.c
:internal:
Interrupt Handling
------------------
.. kernel-doc:: drivers/gpu/drm/i915/i915_irq.c
:doc: interrupt handling
.. kernel-doc:: drivers/gpu/drm/i915/i915_irq.c
:functions: intel_irq_init intel_irq_init_hw intel_hpd_init
.. kernel-doc:: drivers/gpu/drm/i915/i915_irq.c
:functions: intel_runtime_pm_disable_interrupts
.. kernel-doc:: drivers/gpu/drm/i915/i915_irq.c
:functions: intel_runtime_pm_enable_interrupts
Intel GVT-g Guest Support(vGPU)
-------------------------------
.. kernel-doc:: drivers/gpu/drm/i915/i915_vgpu.c
:doc: Intel GVT-g guest support
.. kernel-doc:: drivers/gpu/drm/i915/i915_vgpu.c
:internal:
Intel GVT-g Host Support(vGPU device model)
-------------------------------------------
.. kernel-doc:: drivers/gpu/drm/i915/intel_gvt.c
:doc: Intel GVT-g host support
.. kernel-doc:: drivers/gpu/drm/i915/intel_gvt.c
:internal:
Workarounds
-----------
.. kernel-doc:: drivers/gpu/drm/i915/intel_workarounds.c
:doc: Hardware workarounds
Display Hardware Handling
=========================
This section covers everything related to the display hardware including
the mode setting infrastructure, plane, sprite and cursor handling and
display, output probing and related topics.
Mode Setting Infrastructure
---------------------------
The i915 driver is thus far the only DRM driver which doesn't use the
common DRM helper code to implement mode setting sequences. Thus it has
its own tailor-made infrastructure for executing a display configuration
change.
Frontbuffer Tracking
--------------------
.. kernel-doc:: drivers/gpu/drm/i915/intel_frontbuffer.c
:doc: frontbuffer tracking
.. kernel-doc:: drivers/gpu/drm/i915/intel_frontbuffer.h
:internal:
.. kernel-doc:: drivers/gpu/drm/i915/intel_frontbuffer.c
:internal:
.. kernel-doc:: drivers/gpu/drm/i915/i915_gem.c
:functions: i915_gem_track_fb
Display FIFO Underrun Reporting
-------------------------------
.. kernel-doc:: drivers/gpu/drm/i915/intel_fifo_underrun.c
:doc: fifo underrun handling
.. kernel-doc:: drivers/gpu/drm/i915/intel_fifo_underrun.c
:internal:
Plane Configuration
-------------------
This section covers plane configuration and composition with the primary
plane, sprites, cursors and overlays. This includes the infrastructure
to do atomic vsync'ed updates of all this state and also tightly coupled
topics like watermark setup and computation, framebuffer compression and
panel self refresh.
Atomic Plane Helpers
--------------------
.. kernel-doc:: drivers/gpu/drm/i915/intel_atomic_plane.c
:doc: atomic plane helpers
.. kernel-doc:: drivers/gpu/drm/i915/intel_atomic_plane.c
:internal:
Output Probing
--------------
This section covers output probing and related infrastructure like the
hotplug interrupt storm detection and mitigation code. Note that the
i915 driver still uses most of the common DRM helper code for output
probing, so those sections fully apply.
Hotplug
-------
.. kernel-doc:: drivers/gpu/drm/i915/intel_hotplug.c
:doc: Hotplug
.. kernel-doc:: drivers/gpu/drm/i915/intel_hotplug.c
:internal:
High Definition Audio
---------------------
.. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
:doc: High Definition Audio over HDMI and Display Port
.. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
:internal:
.. kernel-doc:: include/drm/i915_component.h
:internal:
Intel HDMI LPE Audio Support
----------------------------
.. kernel-doc:: drivers/gpu/drm/i915/intel_lpe_audio.c
:doc: LPE Audio integration for HDMI or DP playback
.. kernel-doc:: drivers/gpu/drm/i915/intel_lpe_audio.c
:internal:
Panel Self Refresh PSR (PSR/SRD)
--------------------------------
.. kernel-doc:: drivers/gpu/drm/i915/intel_psr.c
:doc: Panel Self Refresh (PSR/SRD)
.. kernel-doc:: drivers/gpu/drm/i915/intel_psr.c
:internal:
Frame Buffer Compression (FBC)
------------------------------
.. kernel-doc:: drivers/gpu/drm/i915/intel_fbc.c
:doc: Frame Buffer Compression (FBC)
.. kernel-doc:: drivers/gpu/drm/i915/intel_fbc.c
:internal:
Display Refresh Rate Switching (DRRS)
-------------------------------------
.. kernel-doc:: drivers/gpu/drm/i915/intel_dp.c
:doc: Display Refresh Rate Switching (DRRS)
.. kernel-doc:: drivers/gpu/drm/i915/intel_dp.c
:functions: intel_dp_set_drrs_state
.. kernel-doc:: drivers/gpu/drm/i915/intel_dp.c
:functions: intel_edp_drrs_enable
.. kernel-doc:: drivers/gpu/drm/i915/intel_dp.c
:functions: intel_edp_drrs_disable
.. kernel-doc:: drivers/gpu/drm/i915/intel_dp.c
:functions: intel_edp_drrs_invalidate
.. kernel-doc:: drivers/gpu/drm/i915/intel_dp.c
:functions: intel_edp_drrs_flush
.. kernel-doc:: drivers/gpu/drm/i915/intel_dp.c
:functions: intel_dp_drrs_init
DPIO
----
.. kernel-doc:: drivers/gpu/drm/i915/intel_dpio_phy.c
:doc: DPIO
CSR firmware support for DMC
----------------------------
.. kernel-doc:: drivers/gpu/drm/i915/intel_csr.c
:doc: csr support for dmc
.. kernel-doc:: drivers/gpu/drm/i915/intel_csr.c
:internal:
Video BIOS Table (VBT)
----------------------
.. kernel-doc:: drivers/gpu/drm/i915/intel_bios.c
:doc: Video BIOS Table (VBT)
.. kernel-doc:: drivers/gpu/drm/i915/intel_bios.c
:internal:
.. kernel-doc:: drivers/gpu/drm/i915/intel_vbt_defs.h
:internal:
Display clocks
--------------
.. kernel-doc:: drivers/gpu/drm/i915/intel_cdclk.c
:doc: CDCLK / RAWCLK
.. kernel-doc:: drivers/gpu/drm/i915/intel_cdclk.c
:internal:
Display PLLs
------------
.. kernel-doc:: drivers/gpu/drm/i915/intel_dpll_mgr.c
:doc: Display PLLs
.. kernel-doc:: drivers/gpu/drm/i915/intel_dpll_mgr.c
:internal:
.. kernel-doc:: drivers/gpu/drm/i915/intel_dpll_mgr.h
:internal:
Memory Management and Command Submission
========================================
This sections covers all things related to the GEM implementation in the
i915 driver.
Intel GPU Basics
----------------
An Intel GPU has multiple engines. There are several engine types.
- RCS engine is for rendering 3D and performing compute, this is named
`I915_EXEC_RENDER` in user space.
- BCS is a blitting (copy) engine, this is named `I915_EXEC_BLT` in user
space.
- VCS is a video encode and decode engine, this is named `I915_EXEC_BSD`
in user space
- VECS is video enhancement engine, this is named `I915_EXEC_VEBOX` in user
space.
- The enumeration `I915_EXEC_DEFAULT` does not refer to specific engine;
instead it is to be used by user space to specify a default rendering
engine (for 3D) that may or may not be the same as RCS.
The Intel GPU family is a family of integrated GPU's using Unified
Memory Access. For having the GPU "do work", user space will feed the
GPU batch buffers via one of the ioctls `DRM_IOCTL_I915_GEM_EXECBUFFER2`
or `DRM_IOCTL_I915_GEM_EXECBUFFER2_WR`. Most such batchbuffers will
instruct the GPU to perform work (for example rendering) and that work
needs memory from which to read and memory to which to write. All memory
is encapsulated within GEM buffer objects (usually created with the ioctl
`DRM_IOCTL_I915_GEM_CREATE`). An ioctl providing a batchbuffer for the GPU
to create will also list all GEM buffer objects that the batchbuffer reads
and/or writes. For implementation details of memory management see
`GEM BO Management Implementation Details`_.
The i915 driver allows user space to create a context via the ioctl
`DRM_IOCTL_I915_GEM_CONTEXT_CREATE` which is identified by a 32-bit
integer. Such a context should be viewed by user-space as -loosely-
analogous to the idea of a CPU process of an operating system. The i915
driver guarantees that commands issued to a fixed context are to be
executed so that writes of a previously issued command are seen by
reads of following commands. Actions issued between different contexts
(even if from the same file descriptor) are NOT given that guarantee
and the only way to synchronize across contexts (even from the same
file descriptor) is through the use of fences. At least as far back as
Gen4, also have that a context carries with it a GPU HW context;
the HW context is essentially (most of atleast) the state of a GPU.
In addition to the ordering guarantees, the kernel will restore GPU
state via HW context when commands are issued to a context, this saves
user space the need to restore (most of atleast) the GPU state at the
start of each batchbuffer. The non-deprecated ioctls to submit batchbuffer
work can pass that ID (in the lower bits of drm_i915_gem_execbuffer2::rsvd1)
to identify what context to use with the command.
The GPU has its own memory management and address space. The kernel
driver maintains the memory translation table for the GPU. For older
GPUs (i.e. those before Gen8), there is a single global such translation
table, a global Graphics Translation Table (GTT). For newer generation
GPUs each context has its own translation table, called Per-Process
Graphics Translation Table (PPGTT). Of important note, is that although
PPGTT is named per-process it is actually per context. When user space
submits a batchbuffer, the kernel walks the list of GEM buffer objects
used by the batchbuffer and guarantees that not only is the memory of
each such GEM buffer object resident but it is also present in the
(PP)GTT. If the GEM buffer object is not yet placed in the (PP)GTT,
then it is given an address. Two consequences of this are: the kernel
needs to edit the batchbuffer submitted to write the correct value of
the GPU address when a GEM BO is assigned a GPU address and the kernel
might evict a different GEM BO from the (PP)GTT to make address room
for another GEM BO. Consequently, the ioctls submitting a batchbuffer
for execution also include a list of all locations within buffers that
refer to GPU-addresses so that the kernel can edit the buffer correctly.
This process is dubbed relocation.
GEM BO Management Implementation Details
----------------------------------------
.. kernel-doc:: drivers/gpu/drm/i915/i915_vma.h
:doc: Virtual Memory Address
Buffer Object Eviction
----------------------
This section documents the interface functions for evicting buffer
objects to make space available in the virtual gpu address spaces. Note
that this is mostly orthogonal to shrinking buffer objects caches, which
has the goal to make main memory (shared with the gpu through the
unified memory architecture) available.
.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_evict.c
:internal:
Buffer Object Memory Shrinking
------------------------------
This section documents the interface function for shrinking memory usage
of buffer object caches. Shrinking is used to make main memory
available. Note that this is mostly orthogonal to evicting buffer
objects, which has the goal to make space in gpu virtual address spaces.
.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_shrinker.c
:internal:
Batchbuffer Parsing
-------------------
.. kernel-doc:: drivers/gpu/drm/i915/i915_cmd_parser.c
:doc: batch buffer command parser
.. kernel-doc:: drivers/gpu/drm/i915/i915_cmd_parser.c
:internal:
Batchbuffer Pools
-----------------
.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_batch_pool.c
:doc: batch pool
.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_batch_pool.c
:internal:
User Batchbuffer Execution
--------------------------
.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_execbuffer.c
:doc: User command execution
Logical Rings, Logical Ring Contexts and Execlists
--------------------------------------------------
.. kernel-doc:: drivers/gpu/drm/i915/intel_lrc.c
:doc: Logical Rings, Logical Ring Contexts and Execlists
.. kernel-doc:: drivers/gpu/drm/i915/intel_lrc.c
:internal:
Global GTT views
----------------
.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_gtt.c
:doc: Global GTT views
.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_gtt.c
:internal:
GTT Fences and Swizzling
------------------------
.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_fence_reg.c
:internal:
Global GTT Fence Handling
~~~~~~~~~~~~~~~~~~~~~~~~~
.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_fence_reg.c
:doc: fence register handling
Hardware Tiling and Swizzling Details
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_fence_reg.c
:doc: tiling swizzling details
Object Tiling IOCTLs
--------------------
.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_tiling.c
:internal:
.. kernel-doc:: drivers/gpu/drm/i915/i915_gem_tiling.c
:doc: buffer object tiling
WOPCM
=====
WOPCM Layout
------------
.. kernel-doc:: drivers/gpu/drm/i915/intel_wopcm.c
:doc: WOPCM Layout
GuC
===
GuC-specific firmware loader
----------------------------
.. kernel-doc:: drivers/gpu/drm/i915/intel_guc_fw.c
:internal:
GuC-based command submission
----------------------------
.. kernel-doc:: drivers/gpu/drm/i915/intel_guc_submission.c
:doc: GuC-based command submission
.. kernel-doc:: drivers/gpu/drm/i915/intel_guc_submission.c
:internal:
GuC Firmware Layout
-------------------
.. kernel-doc:: drivers/gpu/drm/i915/intel_guc_fwif.h
:doc: GuC Firmware Layout
GuC Address Space
-----------------
.. kernel-doc:: drivers/gpu/drm/i915/intel_guc.c
:doc: GuC Address Space
Tracing
=======
This sections covers all things related to the tracepoints implemented
in the i915 driver.
i915_ppgtt_create and i915_ppgtt_release
----------------------------------------
.. kernel-doc:: drivers/gpu/drm/i915/i915_trace.h
:doc: i915_ppgtt_create and i915_ppgtt_release tracepoints
i915_context_create and i915_context_free
-----------------------------------------
.. kernel-doc:: drivers/gpu/drm/i915/i915_trace.h
:doc: i915_context_create and i915_context_free tracepoints
switch_mm
---------
.. kernel-doc:: drivers/gpu/drm/i915/i915_trace.h
:doc: switch_mm tracepoint
Perf
====
Overview
--------
.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
:doc: i915 Perf Overview
Comparison with Core Perf
-------------------------
.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
:doc: i915 Perf History and Comparison with Core Perf
i915 Driver Entry Points
------------------------
This section covers the entrypoints exported outside of i915_perf.c to
integrate with drm/i915 and to handle the `DRM_I915_PERF_OPEN` ioctl.
.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
:functions: i915_perf_init
.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
:functions: i915_perf_fini
.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
:functions: i915_perf_register
.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
:functions: i915_perf_unregister
.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
:functions: i915_perf_open_ioctl
.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
:functions: i915_perf_release
.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
:functions: i915_perf_add_config_ioctl
.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
:functions: i915_perf_remove_config_ioctl
i915 Perf Stream
----------------
This section covers the stream-semantics-agnostic structures and functions
for representing an i915 perf stream FD and associated file operations.
.. kernel-doc:: drivers/gpu/drm/i915/i915_drv.h
:functions: i915_perf_stream
.. kernel-doc:: drivers/gpu/drm/i915/i915_drv.h
:functions: i915_perf_stream_ops
.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
:functions: read_properties_unlocked
.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
:functions: i915_perf_open_ioctl_locked
.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
:functions: i915_perf_destroy_locked
.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
:functions: i915_perf_read
.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
:functions: i915_perf_ioctl
.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
:functions: i915_perf_enable_locked
.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
:functions: i915_perf_disable_locked
.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
:functions: i915_perf_poll
.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
:functions: i915_perf_poll_locked
i915 Perf Observation Architecture Stream
-----------------------------------------
.. kernel-doc:: drivers/gpu/drm/i915/i915_drv.h
:functions: i915_oa_ops
.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
:functions: i915_oa_stream_init
.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
:functions: i915_oa_read
.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
:functions: i915_oa_stream_enable
.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
:functions: i915_oa_stream_disable
.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
:functions: i915_oa_wait_unlocked
.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
:functions: i915_oa_poll_wait
All i915 Perf Internals
-----------------------
This section simply includes all currently documented i915 perf internals, in
no particular order, but may include some more minor utilities or platform
specific details than found in the more high-level sections.
.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
:internal:
Style
=====
The drm/i915 driver codebase has some style rules in addition to (and, in some
cases, deviating from) the kernel coding style.
Register macro definition style
-------------------------------
The style guide for ``i915_reg.h``.
.. kernel-doc:: drivers/gpu/drm/i915/i915_reg.h
:doc: The i915 register macro definition style guide
+24
View File
@@ -0,0 +1,24 @@
==================================
Linux GPU Driver Developer's Guide
==================================
.. toctree::
introduction
drm-internals
drm-mm
drm-kms
drm-kms-helpers
drm-uapi
drm-client
drivers
vga-switcheroo
vgaarbiter
todo
.. only:: subproject and html
Indices
=======
* :ref:`genindex`
+98
View File
@@ -0,0 +1,98 @@
============
Introduction
============
The Linux DRM layer contains code intended to support the needs of
complex graphics devices, usually containing programmable pipelines well
suited to 3D graphics acceleration. Graphics drivers in the kernel may
make use of DRM functions to make tasks like memory management,
interrupt handling and DMA easier, and provide a uniform interface to
applications.
A note on versions: this guide covers features found in the DRM tree,
including the TTM memory manager, output configuration and mode setting,
and the new vblank internals, in addition to all the regular features
found in current kernels.
[Insert diagram of typical DRM stack here]
Style Guidelines
================
For consistency this documentation uses American English. Abbreviations
are written as all-uppercase, for example: DRM, KMS, IOCTL, CRTC, and so
on. To aid in reading, documentations make full use of the markup
characters kerneldoc provides: @parameter for function parameters,
@member for structure members (within the same structure), &struct structure to
reference structures and function() for functions. These all get automatically
hyperlinked if kerneldoc for the referenced objects exists. When referencing
entries in function vtables (and structure members in general) please use
&vtable_name.vfunc. Unfortunately this does not yet yield a direct link to the
member, only the structure.
Except in special situations (to separate locked from unlocked variants)
locking requirements for functions aren't documented in the kerneldoc.
Instead locking should be check at runtime using e.g.
``WARN_ON(!mutex_is_locked(...));``. Since it's much easier to ignore
documentation than runtime noise this provides more value. And on top of
that runtime checks do need to be updated when the locking rules change,
increasing the chances that they're correct. Within the documentation
the locking rules should be explained in the relevant structures: Either
in the comment for the lock explaining what it protects, or data fields
need a note about which lock protects them, or both.
Functions which have a non-\ ``void`` return value should have a section
called "Returns" explaining the expected return values in different
cases and their meanings. Currently there's no consensus whether that
section name should be all upper-case or not, and whether it should end
in a colon or not. Go with the file-local style. Other common section
names are "Notes" with information for dangerous or tricky corner cases,
and "FIXME" where the interface could be cleaned up.
Also read the :ref:`guidelines for the kernel documentation at large <doc_guide>`.
Getting Started
===============
Developers interested in helping out with the DRM subsystem are very welcome.
Often people will resort to sending in patches for various issues reported by
checkpatch or sparse. We welcome such contributions.
Anyone looking to kick it up a notch can find a list of janitorial tasks on
the :ref:`TODO list <todo>`.
Contribution Process
====================
Mostly the DRM subsystem works like any other kernel subsystem, see :ref:`the
main process guidelines and documentation <process_index>` for how things work.
Here we just document some of the specialities of the GPU subsystem.
Feature Merge Deadlines
-----------------------
All feature work must be in the linux-next tree by the -rc6 release of the
current release cycle, otherwise they must be postponed and can't reach the next
merge window. All patches must have landed in the drm-next tree by latest -rc7,
but if your branch is not in linux-next then this must have happened by -rc6
already.
After that point only bugfixes (like after the upstream merge window has closed
with the -rc1 release) are allowed. No new platform enabling or new drivers are
allowed.
This means that there's a blackout-period of about one month where feature work
can't be merged. The recommended way to deal with that is having a -next tree
that's always open, but making sure to not feed it into linux-next during the
blackout period. As an example, drm-misc works like that.
Code of Conduct
---------------
As a freedesktop.org project, dri-devel, and the DRM community, follows the
Contributor Covenant, found at: https://www.freedesktop.org/wiki/CodeOfConduct
Please conduct yourself in a respectful and civilised manner when
interacting with community members on mailing lists, IRC, or bug
trackers. The community represents the project as a whole, and abusive
or bullying behaviour is not tolerated by the project.
+102
View File
@@ -0,0 +1,102 @@
Owner Module/Drivers,Group,Property Name,Type,Property Values,Object attached,Description/Restrictions
,DVI-I,“subconnector”,ENUM,"{ “Unknown”, “DVI-D”, “DVI-A” }",Connector,TBD
,,“select subconnector”,ENUM,"{ “Automatic”, “DVI-D”, “DVI-A” }",Connector,TBD
,TV,“subconnector”,ENUM,"{ ""Unknown"", ""Composite"", ""SVIDEO"", ""Component"", ""SCART"" }",Connector,TBD
,,“select subconnector”,ENUM,"{ ""Automatic"", ""Composite"", ""SVIDEO"", ""Component"", ""SCART"" }",Connector,TBD
,,“mode”,ENUM,"{ ""NTSC_M"", ""NTSC_J"", ""NTSC_443"", ""PAL_B"" } etc.",Connector,TBD
,,“left margin”,RANGE,"Min=0, Max=100",Connector,TBD
,,“right margin”,RANGE,"Min=0, Max=100",Connector,TBD
,,“top margin”,RANGE,"Min=0, Max=100",Connector,TBD
,,“bottom margin”,RANGE,"Min=0, Max=100",Connector,TBD
,,“brightness”,RANGE,"Min=0, Max=100",Connector,TBD
,,“contrast”,RANGE,"Min=0, Max=100",Connector,TBD
,,“flicker reduction”,RANGE,"Min=0, Max=100",Connector,TBD
,,“overscan”,RANGE,"Min=0, Max=100",Connector,TBD
,,“saturation”,RANGE,"Min=0, Max=100",Connector,TBD
,,“hue”,RANGE,"Min=0, Max=100",Connector,TBD
,Virtual GPU,“suggested X”,RANGE,"Min=0, Max=0xffffffff",Connector,property to suggest an X offset for a connector
,,“suggested Y”,RANGE,"Min=0, Max=0xffffffff",Connector,property to suggest an Y offset for a connector
,Optional,"""aspect ratio""",ENUM,"{ ""None"", ""4:3"", ""16:9"" }",Connector,TDB
,Optional,"""content type""",ENUM,"{ ""No Data"", ""Graphics"", ""Photo"", ""Cinema"", ""Game"" }",Connector,TBD
i915,Generic,"""Broadcast RGB""",ENUM,"{ ""Automatic"", ""Full"", ""Limited 16:235"" }",Connector,"When this property is set to Limited 16:235 and CTM is set, the hardware will be programmed with the result of the multiplication of CTM by the limited range matrix to ensure the pixels normaly in the range 0..1.0 are remapped to the range 16/255..235/255."
,,“audio”,ENUM,"{ ""force-dvi"", ""off"", ""auto"", ""on"" }",Connector,TBD
,SDVO-TV,“mode”,ENUM,"{ ""NTSC_M"", ""NTSC_J"", ""NTSC_443"", ""PAL_B"" } etc.",Connector,TBD
,,"""left_margin""",RANGE,"Min=0, Max= SDVO dependent",Connector,TBD
,,"""right_margin""",RANGE,"Min=0, Max= SDVO dependent",Connector,TBD
,,"""top_margin""",RANGE,"Min=0, Max= SDVO dependent",Connector,TBD
,,"""bottom_margin""",RANGE,"Min=0, Max= SDVO dependent",Connector,TBD
,,“hpos”,RANGE,"Min=0, Max= SDVO dependent",Connector,TBD
,,“vpos”,RANGE,"Min=0, Max= SDVO dependent",Connector,TBD
,,“contrast”,RANGE,"Min=0, Max= SDVO dependent",Connector,TBD
,,“saturation”,RANGE,"Min=0, Max= SDVO dependent",Connector,TBD
,,“hue”,RANGE,"Min=0, Max= SDVO dependent",Connector,TBD
,,“sharpness”,RANGE,"Min=0, Max= SDVO dependent",Connector,TBD
,,“flicker_filter”,RANGE,"Min=0, Max= SDVO dependent",Connector,TBD
,,“flicker_filter_adaptive”,RANGE,"Min=0, Max= SDVO dependent",Connector,TBD
,,“flicker_filter_2d”,RANGE,"Min=0, Max= SDVO dependent",Connector,TBD
,,“tv_chroma_filter”,RANGE,"Min=0, Max= SDVO dependent",Connector,TBD
,,“tv_luma_filter”,RANGE,"Min=0, Max= SDVO dependent",Connector,TBD
,,“dot_crawl”,RANGE,"Min=0, Max=1",Connector,TBD
,SDVO-TV/LVDS,“brightness”,RANGE,"Min=0, Max= SDVO dependent",Connector,TBD
CDV gma-500,Generic,"""Broadcast RGB""",ENUM,"{ “Full”, “Limited 16:235” }",Connector,TBD
,,"""Broadcast RGB""",ENUM,"{ “off”, “auto”, “on” }",Connector,TBD
Poulsbo,Generic,“backlight”,RANGE,"Min=0, Max=100",Connector,TBD
,SDVO-TV,“mode”,ENUM,"{ ""NTSC_M"", ""NTSC_J"", ""NTSC_443"", ""PAL_B"" } etc.",Connector,TBD
,,"""left_margin""",RANGE,"Min=0, Max= SDVO dependent",Connector,TBD
,,"""right_margin""",RANGE,"Min=0, Max= SDVO dependent",Connector,TBD
,,"""top_margin""",RANGE,"Min=0, Max= SDVO dependent",Connector,TBD
,,"""bottom_margin""",RANGE,"Min=0, Max= SDVO dependent",Connector,TBD
,,“hpos”,RANGE,"Min=0, Max= SDVO dependent",Connector,TBD
,,“vpos”,RANGE,"Min=0, Max= SDVO dependent",Connector,TBD
,,“contrast”,RANGE,"Min=0, Max= SDVO dependent",Connector,TBD
,,“saturation”,RANGE,"Min=0, Max= SDVO dependent",Connector,TBD
,,“hue”,RANGE,"Min=0, Max= SDVO dependent",Connector,TBD
,,“sharpness”,RANGE,"Min=0, Max= SDVO dependent",Connector,TBD
,,“flicker_filter”,RANGE,"Min=0, Max= SDVO dependent",Connector,TBD
,,“flicker_filter_adaptive”,RANGE,"Min=0, Max= SDVO dependent",Connector,TBD
,,“flicker_filter_2d”,RANGE,"Min=0, Max= SDVO dependent",Connector,TBD
,,“tv_chroma_filter”,RANGE,"Min=0, Max= SDVO dependent",Connector,TBD
,,“tv_luma_filter”,RANGE,"Min=0, Max= SDVO dependent",Connector,TBD
,,“dot_crawl”,RANGE,"Min=0, Max=1",Connector,TBD
,SDVO-TV/LVDS,“brightness”,RANGE,"Min=0, Max= SDVO dependent",Connector,TBD
armada,CRTC,"""CSC_YUV""",ENUM,"{ ""Auto"" , ""CCIR601"", ""CCIR709"" }",CRTC,TBD
,,"""CSC_RGB""",ENUM,"{ ""Auto"", ""Computer system"", ""Studio"" }",CRTC,TBD
,Overlay,"""colorkey""",RANGE,"Min=0, Max=0xffffff",Plane,TBD
,,"""colorkey_min""",RANGE,"Min=0, Max=0xffffff",Plane,TBD
,,"""colorkey_max""",RANGE,"Min=0, Max=0xffffff",Plane,TBD
,,"""colorkey_val""",RANGE,"Min=0, Max=0xffffff",Plane,TBD
,,"""colorkey_alpha""",RANGE,"Min=0, Max=0xffffff",Plane,TBD
,,"""colorkey_mode""",ENUM,"{ ""disabled"", ""Y component"", ""U component"" , ""V component"", ""RGB"", “R component"", ""G component"", ""B component"" }",Plane,TBD
,,"""brightness""",RANGE,"Min=0, Max=256 + 255",Plane,TBD
,,"""contrast""",RANGE,"Min=0, Max=0x7fff",Plane,TBD
,,"""saturation""",RANGE,"Min=0, Max=0x7fff",Plane,TBD
exynos,CRTC,“mode”,ENUM,"{ ""normal"", ""blank"" }",CRTC,TBD
i2c/ch7006_drv,Generic,“scale”,RANGE,"Min=0, Max=2",Connector,TBD
,TV,“mode”,ENUM,"{ ""PAL"", ""PAL-M"",""PAL-N""}, ”PAL-Nc"" , ""PAL-60"", ""NTSC-M"", ""NTSC-J"" }",Connector,TBD
nouveau,NV10 Overlay,"""colorkey""",RANGE,"Min=0, Max=0x01ffffff",Plane,TBD
,,“contrast”,RANGE,"Min=0, Max=8192-1",Plane,TBD
,,“brightness”,RANGE,"Min=0, Max=1024",Plane,TBD
,,“hue”,RANGE,"Min=0, Max=359",Plane,TBD
,,“saturation”,RANGE,"Min=0, Max=8192-1",Plane,TBD
,,“iturbt_709”,RANGE,"Min=0, Max=1",Plane,TBD
,Nv04 Overlay,“colorkey”,RANGE,"Min=0, Max=0x01ffffff",Plane,TBD
,,“brightness”,RANGE,"Min=0, Max=1024",Plane,TBD
,Display,“dithering mode”,ENUM,"{ ""auto"", ""off"", ""on"" }",Connector,TBD
,,“dithering depth”,ENUM,"{ ""auto"", ""off"", ""on"", ""static 2x2"", ""dynamic 2x2"", ""temporal"" }",Connector,TBD
,,“underscan”,ENUM,"{ ""auto"", ""6 bpc"", ""8 bpc"" }",Connector,TBD
,,“underscan hborder”,RANGE,"Min=0, Max=128",Connector,TBD
,,“underscan vborder”,RANGE,"Min=0, Max=128",Connector,TBD
,,“vibrant hue”,RANGE,"Min=0, Max=180",Connector,TBD
,,“color vibrance”,RANGE,"Min=0, Max=200",Connector,TBD
omap,Generic,“zorder”,RANGE,"Min=0, Max=3","CRTC, Plane",TBD
qxl,Generic,"“hotplug_mode_update""",RANGE,"Min=0, Max=1",Connector,TBD
radeon,DVI-I,“coherent”,RANGE,"Min=0, Max=1",Connector,TBD
,DAC enable load detect,“load detection”,RANGE,"Min=0, Max=1",Connector,TBD
,TV Standard,"""tv standard""",ENUM,"{ ""ntsc"", ""pal"", ""pal-m"", ""pal-60"", ""ntsc-j"" , ""scart-pal"", ""pal-cn"", ""secam"" }",Connector,TBD
,legacy TMDS PLL detect,"""tmds_pll""",ENUM,"{ ""driver"", ""bios"" }",-,TBD
,Underscan,"""underscan""",ENUM,"{ ""off"", ""on"", ""auto"" }",Connector,TBD
,,"""underscan hborder""",RANGE,"Min=0, Max=128",Connector,TBD
,,"""underscan vborder""",RANGE,"Min=0, Max=128",Connector,TBD
,Audio,“audio”,ENUM,"{ ""off"", ""on"", ""auto"" }",Connector,TBD
,FMT Dithering,“dither”,ENUM,"{ ""off"", ""on"" }",Connector,TBD
,,"""colorkey""",RANGE,"Min=0, Max=0x01ffffff",Plane,TBD
1 Owner Module/Drivers Group Property Name Type Property Values Object attached Description/Restrictions
2 DVI-I “subconnector” ENUM { “Unknown”, “DVI-D”, “DVI-A” } Connector TBD
3 “select subconnector” ENUM { “Automatic”, “DVI-D”, “DVI-A” } Connector TBD
4 TV “subconnector” ENUM { "Unknown", "Composite", "SVIDEO", "Component", "SCART" } Connector TBD
5 “select subconnector” ENUM { "Automatic", "Composite", "SVIDEO", "Component", "SCART" } Connector TBD
6 “mode” ENUM { "NTSC_M", "NTSC_J", "NTSC_443", "PAL_B" } etc. Connector TBD
7 “left margin” RANGE Min=0, Max=100 Connector TBD
8 “right margin” RANGE Min=0, Max=100 Connector TBD
9 “top margin” RANGE Min=0, Max=100 Connector TBD
10 “bottom margin” RANGE Min=0, Max=100 Connector TBD
11 “brightness” RANGE Min=0, Max=100 Connector TBD
12 “contrast” RANGE Min=0, Max=100 Connector TBD
13 “flicker reduction” RANGE Min=0, Max=100 Connector TBD
14 “overscan” RANGE Min=0, Max=100 Connector TBD
15 “saturation” RANGE Min=0, Max=100 Connector TBD
16 “hue” RANGE Min=0, Max=100 Connector TBD
17 Virtual GPU “suggested X” RANGE Min=0, Max=0xffffffff Connector property to suggest an X offset for a connector
18 “suggested Y” RANGE Min=0, Max=0xffffffff Connector property to suggest an Y offset for a connector
19 Optional "aspect ratio" ENUM { "None", "4:3", "16:9" } Connector TDB
20 Optional "content type" ENUM { "No Data", "Graphics", "Photo", "Cinema", "Game" } Connector TBD
21 i915 Generic "Broadcast RGB" ENUM { "Automatic", "Full", "Limited 16:235" } Connector When this property is set to Limited 16:235 and CTM is set, the hardware will be programmed with the result of the multiplication of CTM by the limited range matrix to ensure the pixels normaly in the range 0..1.0 are remapped to the range 16/255..235/255.
22 “audio” ENUM { "force-dvi", "off", "auto", "on" } Connector TBD
23 SDVO-TV “mode” ENUM { "NTSC_M", "NTSC_J", "NTSC_443", "PAL_B" } etc. Connector TBD
24 "left_margin" RANGE Min=0, Max= SDVO dependent Connector TBD
25 "right_margin" RANGE Min=0, Max= SDVO dependent Connector TBD
26 "top_margin" RANGE Min=0, Max= SDVO dependent Connector TBD
27 "bottom_margin" RANGE Min=0, Max= SDVO dependent Connector TBD
28 “hpos” RANGE Min=0, Max= SDVO dependent Connector TBD
29 “vpos” RANGE Min=0, Max= SDVO dependent Connector TBD
30 “contrast” RANGE Min=0, Max= SDVO dependent Connector TBD
31 “saturation” RANGE Min=0, Max= SDVO dependent Connector TBD
32 “hue” RANGE Min=0, Max= SDVO dependent Connector TBD
33 “sharpness” RANGE Min=0, Max= SDVO dependent Connector TBD
34 “flicker_filter” RANGE Min=0, Max= SDVO dependent Connector TBD
35 “flicker_filter_adaptive” RANGE Min=0, Max= SDVO dependent Connector TBD
36 “flicker_filter_2d” RANGE Min=0, Max= SDVO dependent Connector TBD
37 “tv_chroma_filter” RANGE Min=0, Max= SDVO dependent Connector TBD
38 “tv_luma_filter” RANGE Min=0, Max= SDVO dependent Connector TBD
39 “dot_crawl” RANGE Min=0, Max=1 Connector TBD
40 SDVO-TV/LVDS “brightness” RANGE Min=0, Max= SDVO dependent Connector TBD
41 CDV gma-500 Generic "Broadcast RGB" ENUM { “Full”, “Limited 16:235” } Connector TBD
42 "Broadcast RGB" ENUM { “off”, “auto”, “on” } Connector TBD
43 Poulsbo Generic “backlight” RANGE Min=0, Max=100 Connector TBD
44 SDVO-TV “mode” ENUM { "NTSC_M", "NTSC_J", "NTSC_443", "PAL_B" } etc. Connector TBD
45 "left_margin" RANGE Min=0, Max= SDVO dependent Connector TBD
46 "right_margin" RANGE Min=0, Max= SDVO dependent Connector TBD
47 "top_margin" RANGE Min=0, Max= SDVO dependent Connector TBD
48 "bottom_margin" RANGE Min=0, Max= SDVO dependent Connector TBD
49 “hpos” RANGE Min=0, Max= SDVO dependent Connector TBD
50 “vpos” RANGE Min=0, Max= SDVO dependent Connector TBD
51 “contrast” RANGE Min=0, Max= SDVO dependent Connector TBD
52 “saturation” RANGE Min=0, Max= SDVO dependent Connector TBD
53 “hue” RANGE Min=0, Max= SDVO dependent Connector TBD
54 “sharpness” RANGE Min=0, Max= SDVO dependent Connector TBD
55 “flicker_filter” RANGE Min=0, Max= SDVO dependent Connector TBD
56 “flicker_filter_adaptive” RANGE Min=0, Max= SDVO dependent Connector TBD
57 “flicker_filter_2d” RANGE Min=0, Max= SDVO dependent Connector TBD
58 “tv_chroma_filter” RANGE Min=0, Max= SDVO dependent Connector TBD
59 “tv_luma_filter” RANGE Min=0, Max= SDVO dependent Connector TBD
60 “dot_crawl” RANGE Min=0, Max=1 Connector TBD
61 SDVO-TV/LVDS “brightness” RANGE Min=0, Max= SDVO dependent Connector TBD
62 armada CRTC "CSC_YUV" ENUM { "Auto" , "CCIR601", "CCIR709" } CRTC TBD
63 "CSC_RGB" ENUM { "Auto", "Computer system", "Studio" } CRTC TBD
64 Overlay "colorkey" RANGE Min=0, Max=0xffffff Plane TBD
65 "colorkey_min" RANGE Min=0, Max=0xffffff Plane TBD
66 "colorkey_max" RANGE Min=0, Max=0xffffff Plane TBD
67 "colorkey_val" RANGE Min=0, Max=0xffffff Plane TBD
68 "colorkey_alpha" RANGE Min=0, Max=0xffffff Plane TBD
69 "colorkey_mode" ENUM { "disabled", "Y component", "U component" , "V component", "RGB", “R component", "G component", "B component" } Plane TBD
70 "brightness" RANGE Min=0, Max=256 + 255 Plane TBD
71 "contrast" RANGE Min=0, Max=0x7fff Plane TBD
72 "saturation" RANGE Min=0, Max=0x7fff Plane TBD
73 exynos CRTC “mode” ENUM { "normal", "blank" } CRTC TBD
74 i2c/ch7006_drv Generic “scale” RANGE Min=0, Max=2 Connector TBD
75 TV “mode” ENUM { "PAL", "PAL-M","PAL-N"}, ”PAL-Nc" , "PAL-60", "NTSC-M", "NTSC-J" } Connector TBD
76 nouveau NV10 Overlay "colorkey" RANGE Min=0, Max=0x01ffffff Plane TBD
77 “contrast” RANGE Min=0, Max=8192-1 Plane TBD
78 “brightness” RANGE Min=0, Max=1024 Plane TBD
79 “hue” RANGE Min=0, Max=359 Plane TBD
80 “saturation” RANGE Min=0, Max=8192-1 Plane TBD
81 “iturbt_709” RANGE Min=0, Max=1 Plane TBD
82 Nv04 Overlay “colorkey” RANGE Min=0, Max=0x01ffffff Plane TBD
83 “brightness” RANGE Min=0, Max=1024 Plane TBD
84 Display “dithering mode” ENUM { "auto", "off", "on" } Connector TBD
85 “dithering depth” ENUM { "auto", "off", "on", "static 2x2", "dynamic 2x2", "temporal" } Connector TBD
86 “underscan” ENUM { "auto", "6 bpc", "8 bpc" } Connector TBD
87 “underscan hborder” RANGE Min=0, Max=128 Connector TBD
88 “underscan vborder” RANGE Min=0, Max=128 Connector TBD
89 “vibrant hue” RANGE Min=0, Max=180 Connector TBD
90 “color vibrance” RANGE Min=0, Max=200 Connector TBD
91 omap Generic “zorder” RANGE Min=0, Max=3 CRTC, Plane TBD
92 qxl Generic “hotplug_mode_update" RANGE Min=0, Max=1 Connector TBD
93 radeon DVI-I “coherent” RANGE Min=0, Max=1 Connector TBD
94 DAC enable load detect “load detection” RANGE Min=0, Max=1 Connector TBD
95 TV Standard "tv standard" ENUM { "ntsc", "pal", "pal-m", "pal-60", "ntsc-j" , "scart-pal", "pal-cn", "secam" } Connector TBD
96 legacy TMDS PLL detect "tmds_pll" ENUM { "driver", "bios" } - TBD
97 Underscan "underscan" ENUM { "off", "on", "auto" } Connector TBD
98 "underscan hborder" RANGE Min=0, Max=128 Connector TBD
99 "underscan vborder" RANGE Min=0, Max=128 Connector TBD
100 Audio “audio” ENUM { "off", "on", "auto" } Connector TBD
101 FMT Dithering “dither” ENUM { "off", "on" } Connector TBD
102 "colorkey" RANGE Min=0, Max=0x01ffffff Plane TBD
+61
View File
@@ -0,0 +1,61 @@
=============================================
drm/meson AmLogic Meson Video Processing Unit
=============================================
.. kernel-doc:: drivers/gpu/drm/meson/meson_drv.c
:doc: Video Processing Unit
Video Processing Unit
=====================
The Amlogic Meson Display controller is composed of several components
that are going to be documented below:
.. code::
DMC|---------------VPU (Video Processing Unit)----------------|------HHI------|
| vd1 _______ _____________ _________________ | |
D |-------| |----| | | | | HDMI PLL |
D | vd2 | VIU | | Video Post | | Video Encoders |<---|-----VCLK |
R |-------| |----| Processing | | | | |
| osd2 | | | |---| Enci ----------|----|-----VDAC------|
R |-------| CSC |----| Scalers | | Encp ----------|----|----HDMI-TX----|
A | osd1 | | | Blenders | | Encl ----------|----|---------------|
M |-------|______|----|____________| |________________| | |
___|__________________________________________________________|_______________|
Video Input Unit
================
.. kernel-doc:: drivers/gpu/drm/meson/meson_viu.c
:doc: Video Input Unit
Video Post Processing
=====================
.. kernel-doc:: drivers/gpu/drm/meson/meson_vpp.c
:doc: Video Post Processing
Video Encoder
=============
.. kernel-doc:: drivers/gpu/drm/meson/meson_venc.c
:doc: Video Encoder
Video Canvas Management
=======================
.. kernel-doc:: drivers/gpu/drm/meson/meson_canvas.c
:doc: Canvas
Video Clocks
============
.. kernel-doc:: drivers/gpu/drm/meson/meson_vclk.c
:doc: Video Clocks
HDMI Video Output
=================
.. kernel-doc:: drivers/gpu/drm/meson/meson_dw_hdmi.c
:doc: HDMI Output
+96
View File
@@ -0,0 +1,96 @@
=====================
MSM Crash Dump Format
=====================
Following a GPU hang the MSM driver outputs debugging information via
/sys/kernel/dri/X/show or via devcoredump (/sys/class/devcoredump/dcdX/data).
This document describes how the output is formatted.
Each entry is in the form key: value. Sections headers will not have a value
and all the contents of a section will be indented two spaces from the header.
Each section might have multiple array entries the start of which is designated
by a (-).
Mappings
--------
kernel
The kernel version that generated the dump (UTS_RELEASE).
module
The module that generated the crashdump.
time
The kernel time at crash formated as seconds.microseconds.
comm
Comm string for the binary that generated the fault.
cmdline
Command line for the binary that generated the fault.
revision
ID of the GPU that generated the crash formatted as
core.major.minor.patchlevel separated by dots.
rbbm-status
The current value of RBBM_STATUS which shows what top level GPU
components are in use at the time of crash.
ringbuffer
Section containing the contents of each ringbuffer. Each ringbuffer is
identified with an id number.
id
Ringbuffer ID (0 based index). Each ringbuffer in the section
will have its own unique id.
iova
GPU address of the ringbuffer.
last-fence
The last fence that was issued on the ringbuffer
retired-fence
The last fence retired on the ringbuffer.
rptr
The current read pointer (rptr) for the ringbuffer.
wptr
The current write pointer (wptr) for the ringbuffer.
size
Maximum size of the ringbuffer programmed in the hardware.
data
The contents of the ring encoded as ascii85. Only the used
portions of the ring will be printed.
bo
List of buffers from the hanging submission if available.
Each buffer object will have a uinque iova.
iova
GPU address of the buffer object.
size
Allocated size of the buffer object.
data
The contents of the buffer object encoded with ascii85. Only
Trailing zeros at the end of the buffer will be skipped.
registers
Set of registers values. Each entry is on its own line enclosed
by brackets { }.
offset
Byte offset of the register from the start of the
GPU memory region.
value
Hexadecimal value of the register.
registers-hlsq
(5xx only) Register values from the HLSQ aperture.
Same format as the register section.
+6
View File
@@ -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
+178
View File
@@ -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.
+42
View File
@@ -0,0 +1,42 @@
==========================
drm/tinydrm Driver library
==========================
.. kernel-doc:: drivers/gpu/drm/tinydrm/core/tinydrm-core.c
:doc: overview
Core functionality
==================
.. kernel-doc:: drivers/gpu/drm/tinydrm/core/tinydrm-core.c
:doc: core
.. kernel-doc:: include/drm/tinydrm/tinydrm.h
:internal:
.. kernel-doc:: drivers/gpu/drm/tinydrm/core/tinydrm-core.c
:export:
.. kernel-doc:: drivers/gpu/drm/tinydrm/core/tinydrm-pipe.c
:export:
Additional helpers
==================
.. kernel-doc:: include/drm/tinydrm/tinydrm-helpers.h
:internal:
.. kernel-doc:: drivers/gpu/drm/tinydrm/core/tinydrm-helpers.c
:export:
MIPI DBI Compatible Controllers
===============================
.. kernel-doc:: drivers/gpu/drm/tinydrm/mipi-dbi.c
:doc: overview
.. kernel-doc:: include/drm/tinydrm/mipi-dbi.h
:internal:
.. kernel-doc:: drivers/gpu/drm/tinydrm/mipi-dbi.c
:export:
+479
View File
@@ -0,0 +1,479 @@
.. _todo:
=========
TODO list
=========
This section contains a list of smaller janitorial tasks in the kernel DRM
graphics subsystem useful as newbie projects. Or for slow rainy days.
Subsystem-wide refactorings
===========================
De-midlayer drivers
-------------------
With the recent ``drm_bus`` cleanup patches for 3.17 it is no longer required
to have a ``drm_bus`` structure set up. Drivers can directly set up the
``drm_device`` structure instead of relying on bus methods in ``drm_usb.c``
and ``drm_pci.c``. The goal is to get rid of the driver's ``->load`` /
``->unload`` callbacks and open-code the load/unload sequence properly, using
the new two-stage ``drm_device`` setup/teardown.
Once all existing drivers are converted we can also remove those bus support
files for USB and platform devices.
All you need is a GPU for a non-converted driver (currently almost all of
them, but also all the virtual ones used by KVM, so everyone qualifies).
Contact: Daniel Vetter, Thierry Reding, respective driver maintainers
Switch from reference/unreference to get/put
--------------------------------------------
For some reason DRM core uses ``reference``/``unreference`` suffixes for
refcounting functions, but kernel uses ``get``/``put`` (e.g.
``kref_get``/``put()``). It would be good to switch over for consistency, and
it's shorter. Needs to be done in 3 steps for each pair of functions:
* Create new ``get``/``put`` functions, define the old names as compatibility
wrappers
* Switch over each file/driver using a cocci-generated spatch.
* Once all users of the old names are gone, remove them.
This way drivers/patches in the progress of getting merged won't break.
Contact: Daniel Vetter
Convert existing KMS drivers to atomic modesetting
--------------------------------------------------
3.19 has the atomic modeset interfaces and helpers, so drivers can now be
converted over. Modern compositors like Wayland or Surfaceflinger on Android
really want an atomic modeset interface, so this is all about the bright
future.
There is a conversion guide for atomic and all you need is a GPU for a
non-converted driver (again virtual HW drivers for KVM are still all
suitable).
As part of this drivers also need to convert to universal plane (which means
exposing primary & cursor as proper plane objects). But that's much easier to
do by directly using the new atomic helper driver callbacks.
Contact: Daniel Vetter, respective driver maintainers
Clean up the clipped coordination confusion around planes
---------------------------------------------------------
We have a helper to get this right with drm_plane_helper_check_update(), but
it's not consistently used. This should be fixed, preferrably in the atomic
helpers (and drivers then moved over to clipped coordinates). Probably the
helper should also be moved from drm_plane_helper.c to the atomic helpers, to
avoid confusion - the other helpers in that file are all deprecated legacy
helpers.
Contact: Ville Syrjälä, Daniel Vetter, driver maintainers
Convert early atomic drivers to async commit helpers
----------------------------------------------------
For the first year the atomic modeset helpers didn't support asynchronous /
nonblocking commits, and every driver had to hand-roll them. This is fixed
now, but there's still a pile of existing drivers that easily could be
converted over to the new infrastructure.
One issue with the helpers is that they require that drivers handle completion
events for atomic commits correctly. But fixing these bugs is good anyway.
Contact: Daniel Vetter, respective driver maintainers
Better manual-upload support for atomic
---------------------------------------
This would be especially useful for tinydrm:
- Add a struct drm_rect dirty_clip to drm_crtc_state. When duplicating the
crtc state, clear that to the max values, x/y = 0 and w/h = MAX_INT, in
__drm_atomic_helper_crtc_duplicate_state().
- Move tinydrm_merge_clips into drm_framebuffer.c, dropping the tinydrm\_
prefix ofc and using drm_fb\_. drm_framebuffer.c makes sense since this
is a function useful to implement the fb->dirty function.
- Create a new drm_fb_dirty function which does essentially what e.g.
mipi_dbi_fb_dirty does. You can use e.g. drm_atomic_helper_update_plane as the
template. But instead of doing a simple full-screen plane update, this new
helper also sets crtc_state->dirty_clip to the right coordinates. And of
course it needs to check whether the fb is actually active (and maybe where),
so there's some book-keeping involved. There's also some good fun involved in
scaling things appropriately. For that case we might simply give up and
declare the entire area covered by the plane as dirty.
Contact: Noralf Trønnes, Daniel Vetter
Fallout from atomic KMS
-----------------------
``drm_atomic_helper.c`` provides a batch of functions which implement legacy
IOCTLs on top of the new atomic driver interface. Which is really nice for
gradual conversion of drivers, but unfortunately the semantic mismatches are
a bit too severe. So there's some follow-up work to adjust the function
interfaces to fix these issues:
* atomic needs the lock acquire context. At the moment that's passed around
implicitly with some horrible hacks, and it's also allocate with
``GFP_NOFAIL`` behind the scenes. All legacy paths need to start allocating
the acquire context explicitly on stack and then also pass it down into
drivers explicitly so that the legacy-on-atomic functions can use them.
Except for some driver code this is done.
* A bunch of the vtable hooks are now in the wrong place: DRM has a split
between core vfunc tables (named ``drm_foo_funcs``), which are used to
implement the userspace ABI. And then there's the optional hooks for the
helper libraries (name ``drm_foo_helper_funcs``), which are purely for
internal use. Some of these hooks should be move from ``_funcs`` to
``_helper_funcs`` since they are not part of the core ABI. There's a
``FIXME`` comment in the kerneldoc for each such case in ``drm_crtc.h``.
* There's a new helper ``drm_atomic_helper_best_encoder()`` which could be
used by all atomic drivers which don't select the encoder for a given
connector at runtime. That's almost all of them, and would allow us to get
rid of a lot of ``best_encoder`` boilerplate in drivers.
This was almost done, but new drivers added a few more cases again.
Contact: Daniel Vetter
Get rid of dev->struct_mutex from GEM drivers
---------------------------------------------
``dev->struct_mutex`` is the Big DRM Lock from legacy days and infested
everything. Nowadays in modern drivers the only bit where it's mandatory is
serializing GEM buffer object destruction. Which unfortunately means drivers
have to keep track of that lock and either call ``unreference`` or
``unreference_locked`` depending upon context.
Core GEM doesn't have a need for ``struct_mutex`` any more since kernel 4.8,
and there's a ``gem_free_object_unlocked`` callback for any drivers which are
entirely ``struct_mutex`` free.
For drivers that need ``struct_mutex`` it should be replaced with a driver-
private lock. The tricky part is the BO free functions, since those can't
reliably take that lock any more. Instead state needs to be protected with
suitable subordinate locks or some cleanup work pushed to a worker thread. For
performance-critical drivers it might also be better to go with a more
fine-grained per-buffer object and per-context lockings scheme. Currently the
following drivers still use ``struct_mutex``: ``msm``, ``omapdrm`` and
``udl``.
Contact: Daniel Vetter, respective driver maintainers
Convert instances of dev_info/dev_err/dev_warn to their DRM_DEV_* equivalent
----------------------------------------------------------------------------
For drivers which could have multiple instances, it is necessary to
differentiate between which is which in the logs. Since DRM_INFO/WARN/ERROR
don't do this, drivers used dev_info/warn/err to make this differentiation. We
now have DRM_DEV_* variants of the drm print macros, so we can start to convert
those drivers back to using drm-formwatted specific log messages.
Before you start this conversion please contact the relevant maintainers to make
sure your work will be merged - not everyone agrees that the DRM dmesg macros
are better.
Contact: Sean Paul, Maintainer of the driver you plan to convert
Convert drivers to use simple modeset suspend/resume
----------------------------------------------------
Most drivers (except i915 and nouveau) that use
drm_atomic_helper_suspend/resume() can probably be converted to use
drm_mode_config_helper_suspend/resume().
Contact: Maintainer of the driver you plan to convert
Convert drivers to use drm_fb_helper_fbdev_setup/teardown()
-----------------------------------------------------------
Most drivers can use drm_fb_helper_fbdev_setup() except maybe:
- amdgpu which has special logic to decide whether to call
drm_helper_disable_unused_functions()
- armada which isn't atomic and doesn't call
drm_helper_disable_unused_functions()
- i915 which calls drm_fb_helper_initial_config() in a worker
Drivers that use drm_framebuffer_remove() to clean up the fbdev framebuffer can
probably use drm_fb_helper_fbdev_teardown().
Contact: Maintainer of the driver you plan to convert
Clean up mmap forwarding
------------------------
A lot of drivers forward gem mmap calls to dma-buf mmap for imported buffers.
And also a lot of them forward dma-buf mmap to the gem mmap implementations.
Would be great to refactor this all into a set of small common helpers.
Contact: Daniel Vetter
Put a reservation_object into drm_gem_object
--------------------------------------------
This would remove the need for the ->gem_prime_res_obj callback. It would also
allow us to implement generic helpers for waiting for a bo, allowing for quite a
bit of refactoring in the various wait ioctl implementations.
Contact: Daniel Vetter
idr_init_base()
---------------
DRM core&drivers uses a lot of idr (integer lookup directories) for mapping
userspace IDs to internal objects, and in most places ID=0 means NULL and hence
is never used. Switching to idr_init_base() for these would make the idr more
efficient.
Contact: Daniel Vetter
Core refactorings
=================
Clean up the DRM header mess
----------------------------
Currently the DRM subsystem has only one global header, ``drmP.h``. This is
used both for functions exported to helper libraries and drivers and functions
only used internally in the ``drm.ko`` module. The goal would be to move all
header declarations not needed outside of ``drm.ko`` into
``drivers/gpu/drm/drm_*_internal.h`` header files. ``EXPORT_SYMBOL`` also
needs to be dropped for these functions.
This would nicely tie in with the below task to create kerneldoc after the API
is cleaned up. Or with the "hide legacy cruft better" task.
Note that this is well in progress, but ``drmP.h`` is still huge. The updated
plan is to switch to per-file driver API headers, which will also structure
the kerneldoc better. This should also allow more fine-grained ``#include``
directives.
In the end no .c file should need to include ``drmP.h`` anymore.
Contact: Daniel Vetter
Add missing kerneldoc for exported functions
--------------------------------------------
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 book.
See https://dri.freedesktop.org/docs/drm/ for what's there already.
Contact: Daniel Vetter
Hide legacy cruft better
------------------------
Way back DRM supported only drivers which shadow-attached to PCI devices with
userspace or fbdev drivers setting up outputs. Modern DRM drivers take charge
of the entire device, you can spot them with the DRIVER_MODESET flag.
Unfortunately there's still large piles of legacy code around which needs to
be hidden so that driver writers don't accidentally end up using it. And to
prevent security issues in those legacy IOCTLs from being exploited on modern
drivers. This has multiple possible subtasks:
* Extract support code for legacy features into a ``drm-legacy.ko`` kernel
module and compile it only when one of the legacy drivers is enabled.
This is mostly done, the only thing left is to split up ``drm_irq.c`` into
legacy cruft and the parts needed by modern KMS drivers.
Contact: Daniel Vetter
Make panic handling work
------------------------
This is a really varied tasks with lots of little bits and pieces:
* The panic path can't be tested currently, leading to constant breaking. The
main issue here is that panics can be triggered from hardirq contexts and
hence all panic related callback can run in hardirq context. It would be
awesome if we could test at least the fbdev helper code and driver code by
e.g. trigger calls through drm debugfs files. hardirq context could be
achieved by using an IPI to the local processor.
* There's a massive confusion of different panic handlers. DRM fbdev emulation
helpers have one, but on top of that the fbcon code itself also has one. We
need to make sure that they stop fighting over each another.
* ``drm_can_sleep()`` is a mess. It hides real bugs in normal operations and
isn't a full solution for panic paths. We need to make sure that it only
returns true if there's a panic going on for real, and fix up all the
fallout.
* The panic handler must never sleep, which also means it can't ever
``mutex_lock()``. Also it can't grab any other lock unconditionally, not
even spinlocks (because NMI and hardirq can panic too). We need to either
make sure to not call such paths, or trylock everything. Really tricky.
* For the above locking troubles reasons it's pretty much impossible to
attempt a synchronous modeset from panic handlers. The only thing we could
try to achive is an atomic ``set_base`` of the primary plane, and hope that
it shows up. Everything else probably needs to be delayed to some worker or
something else which happens later on. Otherwise it just kills the box
harder, prevent the panic from going out on e.g. netconsole.
* There's also proposal for a simplied DRM console instead of the full-blown
fbcon and DRM fbdev emulation. Any kind of panic handling tricks should
obviously work for both console, in case we ever get kmslog merged.
Contact: Daniel Vetter
Clean up the debugfs support
----------------------------
There's a bunch of issues with it:
- The drm_info_list ->show() function doesn't even bother to cast to the drm
structure for you. This is lazy.
- We probably want to have some support for debugfs files on crtc/connectors and
maybe other kms objects directly in core. There's even drm_print support in
the funcs for these objects to dump kms state, so it's all there. And then the
->show() functions should obviously give you a pointer to the right object.
- The drm_info_list stuff is centered on drm_minor instead of drm_device. For
anything we want to print drm_device (or maybe drm_file) is the right thing.
- The drm_driver->debugfs_init hooks we have is just an artifact of the old
midlayered load sequence. DRM debugfs should work more like sysfs, where you
can create properties/files for an object anytime you want, and the core
takes care of publishing/unpuplishing all the files at register/unregister
time. Drivers shouldn't need to worry about these technicalities, and fixing
this (together with the drm_minor->drm_device move) would allow us to remove
debugfs_init.
Contact: Daniel Vetter
KMS cleanups
------------
Some of these date from the very introduction of KMS in 2008 ...
- drm_mode_config.crtc_idr is misnamed, since it contains all KMS object. Should
be renamed to drm_mode_config.object_idr.
- drm_display_mode doesn't need to be derived from drm_mode_object. That's
leftovers from older (never merged into upstream) KMS designs where modes
where set using their ID, including support to add/remove modes.
Better Testing
==============
Enable trinity for DRM
----------------------
And fix up the fallout. Should be really interesting ...
Make KMS tests in i-g-t generic
-------------------------------
The i915 driver team maintains an extensive testsuite for the i915 DRM driver,
including tons of testcases for corner-cases in the modesetting API. It would
be awesome if those tests (at least the ones not relying on Intel-specific GEM
features) could be made to run on any KMS driver.
Basic work to run i-g-t tests on non-i915 is done, what's now missing is mass-
converting things over. For modeset tests we also first need a bit of
infrastructure to use dumb buffers for untiled buffers, to be able to run all
the non-i915 specific modeset tests.
Contact: Daniel Vetter
Create a virtual KMS driver for testing (vkms)
----------------------------------------------
With all the latest helpers it should be fairly simple to create a virtual KMS
driver useful for testing, or for running X or similar on headless machines
(to be able to still use the GPU). This would be similar to vgem, but aimed at
the modeset side.
Once the basics are there there's tons of possibilities to extend it.
Contact: Daniel Vetter
Driver Specific
===============
tinydrm
-------
Tinydrm is the helper driver for really simple fb drivers. The goal is to make
those drivers as simple as possible, so lots of room for refactoring:
- backlight helpers, probably best to put them into a new drm_backlight.c.
This is because drivers/video is de-facto unmaintained. We could also
move drivers/video/backlight to drivers/gpu/backlight and take it all
over within drm-misc, but that's more work. Backlight helpers require a fair
bit of reworking and refactoring. A simple example is the enabling of a backlight.
Tinydrm has helpers for this. It would be good if other drivers can also use the
helper. However, there are various cases we need to consider i.e different
drivers seem to have different ways of enabling/disabling a backlight.
We also need to consider the backlight drivers (like gpio_backlight). The situation
is further complicated by the fact that the backlight is tied to fbdev
via fb_notifier_callback() which has complicated logic. For further details, refer
to the following discussion thread:
https://groups.google.com/forum/#!topic/outreachy-kernel/8rBe30lwtdA
- spi helpers, probably best put into spi core/helper code. Thierry said
the spi maintainer is fast&reactive, so shouldn't be a big issue.
- extract the mipi-dbi helper (well, the non-tinydrm specific parts at
least) into a separate helper, like we have for mipi-dsi already. Or follow
one of the ideas for having a shared dsi/dbi helper, abstracting away the
transport details more.
- tinydrm_gem_cma_prime_import_sg_table should probably go into the cma
helpers, as a _vmapped variant (since not every driver needs the vmap).
And tinydrm_gem_cma_free_object could the be merged into
drm_gem_cma_free_object().
- tinydrm_fb_create we could move into drm_simple_pipe, only need to add
the fb_create hook to drm_simple_pipe_funcs, which would again simplify a
bunch of things (since it gives you a one-stop vfunc for simple drivers).
- Quick aside: The unregister devm stuff is kinda getting the lifetimes of
a drm_device wrong. Doesn't matter, since everyone else gets it wrong
too :-)
- also rework the drm_framebuffer_funcs->dirty hook wire-up, see above.
Contact: Noralf Trønnes, Daniel Vetter
AMD DC Display Driver
---------------------
AMD DC is the display driver for AMD devices starting with Vega. There has been
a bunch of progress cleaning it up but there's still plenty of work to be done.
See drivers/gpu/drm/amd/display/TODO for tasks.
Contact: Harry Wentland, Alex Deucher
i915
----
- Our early/late pm callbacks could be removed in favour of using
device_link_add to model the dependency between i915 and snd_had. See
https://dri.freedesktop.org/docs/drm/driver-api/device_link.html
Outside DRM
===========
+6
View File
@@ -0,0 +1,6 @@
==================================
drm/tve200 Faraday TV Encoder 200
==================================
.. kernel-doc:: drivers/gpu/drm/tve200/tve200_drv.c
:doc: Faraday TV Encoder TVE200 DRM Driver
+28
View File
@@ -0,0 +1,28 @@
=====================================
drm/v3d Broadcom V3D Graphics Driver
=====================================
.. kernel-doc:: drivers/gpu/drm/v3d/v3d_drv.c
:doc: Broadcom V3D Graphics Driver
GPU buffer object (BO) management
---------------------------------
.. kernel-doc:: drivers/gpu/drm/v3d/v3d_bo.c
:doc: V3D GEM BO management support
Address space management
===========================================
.. kernel-doc:: drivers/gpu/drm/v3d/v3d_mmu.c
:doc: Broadcom V3D MMU
GPU Scheduling
===========================================
.. kernel-doc:: drivers/gpu/drm/v3d/v3d_sched.c
:doc: Broadcom V3D scheduling
Interrupts
--------------
.. kernel-doc:: drivers/gpu/drm/v3d/v3d_irq.c
:doc: Interrupt management for the V3D engine
+89
View File
@@ -0,0 +1,89 @@
=====================================
drm/vc4 Broadcom VC4 Graphics Driver
=====================================
.. kernel-doc:: drivers/gpu/drm/vc4/vc4_drv.c
:doc: Broadcom VC4 Graphics Driver
Display Hardware Handling
=========================
This section covers everything related to the display hardware including
the mode setting infrastructure, plane, sprite and cursor handling and
display, output probing and related topics.
Pixel Valve (DRM CRTC)
----------------------
.. kernel-doc:: drivers/gpu/drm/vc4/vc4_crtc.c
:doc: VC4 CRTC module
HVS
---
.. kernel-doc:: drivers/gpu/drm/vc4/vc4_hvs.c
:doc: VC4 HVS module.
HVS planes
----------
.. kernel-doc:: drivers/gpu/drm/vc4/vc4_plane.c
:doc: VC4 plane module
HDMI encoder
------------
.. kernel-doc:: drivers/gpu/drm/vc4/vc4_hdmi.c
:doc: VC4 Falcon HDMI module
DSI encoder
-----------
.. kernel-doc:: drivers/gpu/drm/vc4/vc4_dsi.c
:doc: VC4 DSI0/DSI1 module
DPI encoder
-----------
.. kernel-doc:: drivers/gpu/drm/vc4/vc4_dpi.c
:doc: VC4 DPI module
VEC (Composite TV out) encoder
------------------------------
.. kernel-doc:: drivers/gpu/drm/vc4/vc4_vec.c
:doc: VC4 SDTV module
Memory Management and 3D Command Submission
===========================================
This section covers the GEM implementation in the vc4 driver.
GPU buffer object (BO) management
---------------------------------
.. kernel-doc:: drivers/gpu/drm/vc4/vc4_bo.c
:doc: VC4 GEM BO management support
V3D binner command list (BCL) validation
----------------------------------------
.. kernel-doc:: drivers/gpu/drm/vc4/vc4_validate.c
:doc: Command list validator for VC4.
V3D render command list (RCL) generation
----------------------------------------
.. kernel-doc:: drivers/gpu/drm/vc4/vc4_render_cl.c
:doc: Render command list generation
Shader validator for VC4
---------------------------
.. kernel-doc:: drivers/gpu/drm/vc4/vc4_validate_shaders.c
:doc: Shader validator for VC4.
V3D Interrupts
--------------
.. kernel-doc:: drivers/gpu/drm/vc4/vc4_irq.c
:doc: Interrupt management for the V3D engine
+98
View File
@@ -0,0 +1,98 @@
.. _vga_switcheroo:
==============
VGA Switcheroo
==============
.. kernel-doc:: drivers/gpu/vga/vga_switcheroo.c
:doc: Overview
Modes of Use
============
Manual switching and manual power control
-----------------------------------------
.. kernel-doc:: drivers/gpu/vga/vga_switcheroo.c
:doc: Manual switching and manual power control
Driver power control
--------------------
.. kernel-doc:: drivers/gpu/vga/vga_switcheroo.c
:doc: Driver power control
API
===
Public functions
----------------
.. kernel-doc:: drivers/gpu/vga/vga_switcheroo.c
:export:
Public structures
-----------------
.. kernel-doc:: include/linux/vga_switcheroo.h
:functions: vga_switcheroo_handler
.. kernel-doc:: include/linux/vga_switcheroo.h
:functions: vga_switcheroo_client_ops
Public constants
----------------
.. kernel-doc:: include/linux/vga_switcheroo.h
:functions: vga_switcheroo_handler_flags_t
.. kernel-doc:: include/linux/vga_switcheroo.h
:functions: vga_switcheroo_client_id
.. kernel-doc:: include/linux/vga_switcheroo.h
:functions: vga_switcheroo_state
Private structures
------------------
.. kernel-doc:: drivers/gpu/vga/vga_switcheroo.c
:functions: vgasr_priv
.. kernel-doc:: drivers/gpu/vga/vga_switcheroo.c
:functions: vga_switcheroo_client
Handlers
========
apple-gmux Handler
------------------
.. kernel-doc:: drivers/platform/x86/apple-gmux.c
:doc: Overview
.. kernel-doc:: drivers/platform/x86/apple-gmux.c
:doc: Interrupt
Graphics mux
~~~~~~~~~~~~
.. kernel-doc:: drivers/platform/x86/apple-gmux.c
:doc: Graphics mux
Power control
~~~~~~~~~~~~~
.. kernel-doc:: drivers/platform/x86/apple-gmux.c
:doc: Power control
Backlight control
~~~~~~~~~~~~~~~~~
.. kernel-doc:: drivers/platform/x86/apple-gmux.c
:doc: Backlight control
Public functions
~~~~~~~~~~~~~~~~
.. kernel-doc:: include/linux/apple-gmux.h
:internal:
+191
View File
@@ -0,0 +1,191 @@
===========
VGA Arbiter
===========
Graphic devices are accessed through ranges in I/O or memory space. While most
modern devices allow relocation of such ranges, some "Legacy" VGA devices
implemented on PCI will typically have the same "hard-decoded" addresses as
they did on ISA. For more details see "PCI Bus Binding to IEEE Std 1275-1994
Standard for Boot (Initialization Configuration) Firmware Revision 2.1"
Section 7, Legacy Devices.
The Resource Access Control (RAC) module inside the X server [0] existed for
the legacy VGA arbitration task (besides other bus management tasks) when more
than one legacy device co-exists on the same machine. But the problem happens
when these devices are trying to be accessed by different userspace clients
(e.g. two server in parallel). Their address assignments conflict. Moreover,
ideally, being a userspace application, it is not the role of the X server to
control bus resources. Therefore an arbitration scheme outside of the X server
is needed to control the sharing of these resources. This document introduces
the operation of the VGA arbiter implemented for the Linux kernel.
vgaarb kernel/userspace ABI
---------------------------
The vgaarb is a module of the Linux Kernel. When it is initially loaded, it
scans all PCI devices and adds the VGA ones inside the arbitration. The
arbiter then enables/disables the decoding on different devices of the VGA
legacy instructions. Devices which do not want/need to use the arbiter may
explicitly tell it by calling vga_set_legacy_decoding().
The kernel exports a char device interface (/dev/vga_arbiter) to the clients,
which has the following semantics:
open
Opens a user instance of the arbiter. By default, it's attached to the
default VGA device of the system.
close
Close a user instance. Release locks made by the user
read
Return a string indicating the status of the target like:
"<card_ID>,decodes=<io_state>,owns=<io_state>,locks=<io_state> (ic,mc)"
An IO state string is of the form {io,mem,io+mem,none}, mc and
ic are respectively mem and io lock counts (for debugging/
diagnostic only). "decodes" indicate what the card currently
decodes, "owns" indicates what is currently enabled on it, and
"locks" indicates what is locked by this card. If the card is
unplugged, we get "invalid" then for card_ID and an -ENODEV
error is returned for any command until a new card is targeted.
write
Write a command to the arbiter. List of commands:
target <card_ID>
switch target to card <card_ID> (see below)
lock <io_state>
acquires locks on target ("none" is an invalid io_state)
trylock <io_state>
non-blocking acquire locks on target (returns EBUSY if
unsuccessful)
unlock <io_state>
release locks on target
unlock all
release all locks on target held by this user (not implemented
yet)
decodes <io_state>
set the legacy decoding attributes for the card
poll
event if something changes on any card (not just the target)
card_ID is of the form "PCI:domain:bus:dev.fn". It can be set to "default"
to go back to the system default card (TODO: not implemented yet). Currently,
only PCI is supported as a prefix, but the userland API may support other bus
types in the future, even if the current kernel implementation doesn't.
Note about locks:
The driver keeps track of which user has which locks on which card. It
supports stacking, like the kernel one. This complexifies the implementation
a bit, but makes the arbiter more tolerant to user space problems and able
to properly cleanup in all cases when a process dies.
Currently, a max of 16 cards can have locks simultaneously issued from
user space for a given user (file descriptor instance) of the arbiter.
In the case of devices hot-{un,}plugged, there is a hook - pci_notify() - to
notify them being added/removed in the system and automatically added/removed
in the arbiter.
There is also an in-kernel API of the arbiter in case DRM, vgacon, or other
drivers want to use it.
In-kernel interface
-------------------
.. kernel-doc:: include/linux/vgaarb.h
:internal:
.. kernel-doc:: drivers/gpu/vga/vgaarb.c
:export:
libpciaccess
------------
To use the vga arbiter char device it was implemented an API inside the
libpciaccess library. One field was added to struct pci_device (each device
on the system)::
/* the type of resource decoded by the device */
int vgaarb_rsrc;
Besides it, in pci_system were added::
int vgaarb_fd;
int vga_count;
struct pci_device *vga_target;
struct pci_device *vga_default_dev;
The vga_count is used to track how many cards are being arbitrated, so for
instance, if there is only one card, then it can completely escape arbitration.
These functions below acquire VGA resources for the given card and mark those
resources as locked. If the resources requested are "normal" (and not legacy)
resources, the arbiter will first check whether the card is doing legacy
decoding for that type of resource. If yes, the lock is "converted" into a
legacy resource lock. The arbiter will first look for all VGA cards that
might conflict and disable their IOs and/or Memory access, including VGA
forwarding on P2P bridges if necessary, so that the requested resources can
be used. Then, the card is marked as locking these resources and the IO and/or
Memory access is enabled on the card (including VGA forwarding on parent
P2P bridges if any). In the case of vga_arb_lock(), the function will block
if some conflicting card is already locking one of the required resources (or
any resource on a different bus segment, since P2P bridges don't differentiate
VGA memory and IO afaik). If the card already owns the resources, the function
succeeds. vga_arb_trylock() will return (-EBUSY) instead of blocking. Nested
calls are supported (a per-resource counter is maintained).
Set the target device of this client. ::
int pci_device_vgaarb_set_target (struct pci_device *dev);
For instance, in x86 if two devices on the same bus want to lock different
resources, both will succeed (lock). If devices are in different buses and
trying to lock different resources, only the first who tried succeeds. ::
int pci_device_vgaarb_lock (void);
int pci_device_vgaarb_trylock (void);
Unlock resources of device. ::
int pci_device_vgaarb_unlock (void);
Indicates to the arbiter if the card decodes legacy VGA IOs, legacy VGA
Memory, both, or none. All cards default to both, the card driver (fbdev for
example) should tell the arbiter if it has disabled legacy decoding, so the
card can be left out of the arbitration process (and can be safe to take
interrupts at any time. ::
int pci_device_vgaarb_decodes (int new_vgaarb_rsrc);
Connects to the arbiter device, allocates the struct ::
int pci_device_vgaarb_init (void);
Close the connection ::
void pci_device_vgaarb_fini (void);
xf86VGAArbiter (X server implementation)
----------------------------------------
X server basically wraps all the functions that touch VGA registers somehow.
References
----------
Benjamin Herrenschmidt (IBM?) started this work when he discussed such design
with the Xorg community in 2005 [1, 2]. In the end of 2007, Paulo Zanoni and
Tiago Vignatti (both of C3SL/Federal University of Paraná) proceeded his work
enhancing the kernel code to adapt as a kernel module and also did the
implementation of the user space side [3]. Now (2009) Tiago Vignatti and Dave
Airlie finally put this work in shape and queued to Jesse Barnes' PCI tree.
0) http://cgit.freedesktop.org/xorg/xserver/commit/?id=4b42448a2388d40f257774fbffdccaea87bd0347
1) http://lists.freedesktop.org/archives/xorg/2005-March/006663.html
2) http://lists.freedesktop.org/archives/xorg/2005-March/006745.html
3) http://lists.freedesktop.org/archives/xorg/2007-October/029507.html
+31
View File
@@ -0,0 +1,31 @@
====================================================
drm/xen-front Xen para-virtualized frontend driver
====================================================
This frontend driver implements Xen para-virtualized display
according to the display protocol described at
include/xen/interface/io/displif.h
Driver modes of operation in terms of display buffers used
==========================================================
.. kernel-doc:: drivers/gpu/drm/xen/xen_drm_front.h
:doc: Driver modes of operation in terms of display buffers used
Buffers allocated by the frontend driver
----------------------------------------
.. kernel-doc:: drivers/gpu/drm/xen/xen_drm_front.h
:doc: Buffers allocated by the frontend driver
Buffers allocated by the backend
--------------------------------
.. kernel-doc:: drivers/gpu/drm/xen/xen_drm_front.h
:doc: Buffers allocated by the backend
Driver limitations
==================
.. kernel-doc:: drivers/gpu/drm/xen/xen_drm_front.h
:doc: Driver limitations