diff options
Diffstat (limited to 'Documentation/gpu')
| -rw-r--r-- | Documentation/gpu/amdgpu/amdgpu-glossary.rst | 13 | ||||
| -rw-r--r-- | Documentation/gpu/drm-kms-helpers.rst | 43 | ||||
| -rw-r--r-- | Documentation/gpu/drm-mm.rst | 9 | ||||
| -rw-r--r-- | Documentation/gpu/drm-uapi.rst | 4 | ||||
| -rw-r--r-- | Documentation/gpu/drm-usage-stats.rst | 112 | ||||
| -rw-r--r-- | Documentation/gpu/i915.rst | 42 | ||||
| -rw-r--r-- | Documentation/gpu/index.rst | 1 | ||||
| -rw-r--r-- | Documentation/gpu/introduction.rst | 60 | ||||
| -rw-r--r-- | Documentation/gpu/todo.rst | 14 |
9 files changed, 264 insertions, 34 deletions
diff --git a/Documentation/gpu/amdgpu/amdgpu-glossary.rst b/Documentation/gpu/amdgpu/amdgpu-glossary.rst index 859dcec6c6f9..db924d37f93e 100644 --- a/Documentation/gpu/amdgpu/amdgpu-glossary.rst +++ b/Documentation/gpu/amdgpu/amdgpu-glossary.rst @@ -8,12 +8,19 @@ we have a dedicated glossary for Display Core at .. glossary:: + active_cu_number + The number of CUs that are active on the system. The number of active + CUs may be less than SE * SH * CU depending on the board configuration. + CP Command Processor CPLIB Content Protection Library + CU + Compute Unit + DFS Digital Frequency Synthesizer @@ -74,6 +81,12 @@ we have a dedicated glossary for Display Core at SDMA System DMA + SE + Shader Engine + + SH + SHader array + SMU System Management Unit diff --git a/Documentation/gpu/drm-kms-helpers.rst b/Documentation/gpu/drm-kms-helpers.rst index c3ce91eecbc1..2d473bc64c9f 100644 --- a/Documentation/gpu/drm-kms-helpers.rst +++ b/Documentation/gpu/drm-kms-helpers.rst @@ -226,40 +226,43 @@ Panel Self Refresh Helper Reference HDCP Helper Functions Reference =============================== -.. kernel-doc:: drivers/gpu/drm/drm_hdcp.c +.. kernel-doc:: drivers/gpu/drm/display/drm_hdcp_helper.c :export: Display Port Helper Functions Reference ======================================= -.. kernel-doc:: drivers/gpu/drm/dp/drm_dp.c +.. kernel-doc:: drivers/gpu/drm/display/drm_dp_helper.c :doc: dp helpers -.. kernel-doc:: include/drm/dp/drm_dp_helper.h +.. kernel-doc:: include/drm/display/drm_dp.h :internal: -.. kernel-doc:: drivers/gpu/drm/dp/drm_dp.c +.. kernel-doc:: include/drm/display/drm_dp_helper.h + :internal: + +.. kernel-doc:: drivers/gpu/drm/display/drm_dp_helper.c :export: Display Port CEC Helper Functions Reference =========================================== -.. kernel-doc:: drivers/gpu/drm/dp/drm_dp_cec.c +.. kernel-doc:: drivers/gpu/drm/display/drm_dp_cec.c :doc: dp cec helpers -.. kernel-doc:: drivers/gpu/drm/dp/drm_dp_cec.c +.. kernel-doc:: drivers/gpu/drm/display/drm_dp_cec.c :export: Display Port Dual Mode Adaptor Helper Functions Reference ========================================================= -.. kernel-doc:: drivers/gpu/drm/dp/drm_dp_dual_mode_helper.c +.. kernel-doc:: drivers/gpu/drm/display/drm_dp_dual_mode_helper.c :doc: dp dual mode helpers -.. kernel-doc:: include/drm/dp/drm_dp_dual_mode_helper.h +.. kernel-doc:: include/drm/display/drm_dp_dual_mode_helper.h :internal: -.. kernel-doc:: drivers/gpu/drm/dp/drm_dp_dual_mode_helper.c +.. kernel-doc:: drivers/gpu/drm/display/drm_dp_dual_mode_helper.c :export: Display Port MST Helpers @@ -268,19 +271,19 @@ Display Port MST Helpers Overview -------- -.. kernel-doc:: drivers/gpu/drm/dp/drm_dp_mst_topology.c +.. kernel-doc:: drivers/gpu/drm/display/drm_dp_mst_topology.c :doc: dp mst helper -.. kernel-doc:: drivers/gpu/drm/dp/drm_dp_mst_topology.c +.. kernel-doc:: drivers/gpu/drm/display/drm_dp_mst_topology.c :doc: Branch device and port refcounting Functions Reference ------------------- -.. kernel-doc:: include/drm/dp/drm_dp_mst_helper.h +.. kernel-doc:: include/drm/display/drm_dp_mst_helper.h :internal: -.. kernel-doc:: drivers/gpu/drm/dp/drm_dp_mst_topology.c +.. kernel-doc:: drivers/gpu/drm/display/drm_dp_mst_topology.c :export: Topology Lifetime Internals @@ -289,7 +292,7 @@ Topology Lifetime Internals These functions aren't exported to drivers, but are documented here to help make the MST topology helpers easier to understand -.. kernel-doc:: drivers/gpu/drm/dp/drm_dp_mst_topology.c +.. kernel-doc:: drivers/gpu/drm/display/drm_dp_mst_topology.c :functions: drm_dp_mst_topology_try_get_mstb drm_dp_mst_topology_get_mstb drm_dp_mst_topology_put_mstb drm_dp_mst_topology_try_get_port drm_dp_mst_topology_get_port @@ -323,13 +326,13 @@ MIPI DSI Helper Functions Reference Display Stream Compression Helper Functions Reference ===================================================== -.. kernel-doc:: drivers/gpu/drm/drm_dsc.c +.. kernel-doc:: drivers/gpu/drm/display/drm_dsc_helper.c :doc: dsc helpers -.. kernel-doc:: include/drm/drm_dsc.h +.. kernel-doc:: include/drm/display/drm_dsc.h :internal: -.. kernel-doc:: drivers/gpu/drm/drm_dsc.c +.. kernel-doc:: drivers/gpu/drm/display/drm_dsc_helper.c :export: Output Probing Helper Functions Reference @@ -353,13 +356,13 @@ EDID Helper Functions Reference SCDC Helper Functions Reference =============================== -.. kernel-doc:: drivers/gpu/drm/drm_scdc_helper.c +.. kernel-doc:: drivers/gpu/drm/display/drm_scdc_helper.c :doc: scdc helpers -.. kernel-doc:: include/drm/drm_scdc_helper.h +.. kernel-doc:: include/drm/display/drm_scdc_helper.h :internal: -.. kernel-doc:: drivers/gpu/drm/drm_scdc_helper.c +.. kernel-doc:: drivers/gpu/drm/display/drm_scdc_helper.c :export: HDMI Infoframes Helper Reference diff --git a/Documentation/gpu/drm-mm.rst b/Documentation/gpu/drm-mm.rst index 198bcc1affa1..f32ccce5722d 100644 --- a/Documentation/gpu/drm-mm.rst +++ b/Documentation/gpu/drm-mm.rst @@ -466,6 +466,15 @@ DRM MM Range Allocator Function References .. kernel-doc:: drivers/gpu/drm/drm_mm.c :export: +DRM Buddy Allocator +=================== + +DRM Buddy Function References +----------------------------- + +.. kernel-doc:: drivers/gpu/drm/drm_buddy.c + :export: + DRM Cache Handling and Fast WC memcpy() ======================================= diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst index 199afb503ab1..ce47b4292481 100644 --- a/Documentation/gpu/drm-uapi.rst +++ b/Documentation/gpu/drm-uapi.rst @@ -148,7 +148,9 @@ 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 +this node. Especially GEM_OPEN will be explicitly prohibited. For a +complete list of driver-independent ioctls that can be used on render +nodes, see the ioctls marked DRM_RENDER_ALLOW in drm_ioctl.c 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 diff --git a/Documentation/gpu/drm-usage-stats.rst b/Documentation/gpu/drm-usage-stats.rst new file mode 100644 index 000000000000..6c9f166a8d6f --- /dev/null +++ b/Documentation/gpu/drm-usage-stats.rst @@ -0,0 +1,112 @@ +.. _drm-client-usage-stats: + +====================== +DRM client usage stats +====================== + +DRM drivers can choose to export partly standardised text output via the +`fops->show_fdinfo()` as part of the driver specific file operations registered +in the `struct drm_driver` object registered with the DRM core. + +One purpose of this output is to enable writing as generic as practicaly +feasible `top(1)` like userspace monitoring tools. + +Given the differences between various DRM drivers the specification of the +output is split between common and driver specific parts. Having said that, +wherever possible effort should still be made to standardise as much as +possible. + +File format specification +========================= + +- File shall contain one key value pair per one line of text. +- Colon character (`:`) must be used to delimit keys and values. +- All keys shall be prefixed with `drm-`. +- Whitespace between the delimiter and first non-whitespace character shall be + ignored when parsing. +- Neither keys or values are allowed to contain whitespace characters. +- Numerical key value pairs can end with optional unit string. +- Data type of the value is fixed as defined in the specification. + +Key types +--------- + +1. Mandatory, fully standardised. +2. Optional, fully standardised. +3. Driver specific. + +Data types +---------- + +- <uint> - Unsigned integer without defining the maximum value. +- <str> - String excluding any above defined reserved characters or whitespace. + +Mandatory fully standardised keys +--------------------------------- + +- drm-driver: <str> + +String shall contain the name this driver registered as via the respective +`struct drm_driver` data structure. + +Optional fully standardised keys +-------------------------------- + +- drm-pdev: <aaaa:bb.cc.d> + +For PCI devices this should contain the PCI slot address of the device in +question. + +- drm-client-id: <uint> + +Unique value relating to the open DRM file descriptor used to distinguish +duplicated and shared file descriptors. Conceptually the value should map 1:1 +to the in kernel representation of `struct drm_file` instances. + +Uniqueness of the value shall be either globally unique, or unique within the +scope of each device, in which case `drm-pdev` shall be present as well. + +Userspace should make sure to not double account any usage statistics by using +the above described criteria in order to associate data to individual clients. + +- drm-engine-<str>: <uint> ns + +GPUs usually contain multiple execution engines. Each shall be given a stable +and unique name (str), with possible values documented in the driver specific +documentation. + +Value shall be in specified time units which the respective GPU engine spent +busy executing workloads belonging to this client. + +Values are not required to be constantly monotonic if it makes the driver +implementation easier, but are required to catch up with the previously reported +larger value within a reasonable period. Upon observing a value lower than what +was previously read, userspace is expected to stay with that larger previous +value until a monotonic update is seen. + +- drm-engine-capacity-<str>: <uint> + +Engine identifier string must be the same as the one specified in the +drm-engine-<str> tag and shall contain a greater than zero number in case the +exported engine corresponds to a group of identical hardware engines. + +In the absence of this tag parser shall assume capacity of one. Zero capacity +is not allowed. + +- drm-memory-<str>: <uint> [KiB|MiB] + +Each possible memory type which can be used to store buffer objects by the +GPU in question shall be given a stable and unique name to be returned as the +string here. + +Value shall reflect the amount of storage currently consumed by the buffer +object belong to this client, in the respective memory region. + +Default unit shall be bytes with optional unit specifiers of 'KiB' or 'MiB' +indicating kibi- or mebi-bytes. + +=============================== +Driver specific implementations +=============================== + +:ref:`i915-usage-stats` diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst index bcaefc952764..54060cd6c419 100644 --- a/Documentation/gpu/i915.rst +++ b/Documentation/gpu/i915.rst @@ -187,19 +187,7 @@ Display Refresh Rate Switching (DRRS) :doc: Display Refresh Rate Switching (DRRS) .. kernel-doc:: drivers/gpu/drm/i915/display/intel_drrs.c - :functions: intel_drrs_enable - -.. kernel-doc:: drivers/gpu/drm/i915/display/intel_drrs.c - :functions: intel_drrs_disable - -.. kernel-doc:: drivers/gpu/drm/i915/display/intel_drrs.c - :functions: intel_drrs_invalidate - -.. kernel-doc:: drivers/gpu/drm/i915/display/intel_drrs.c - :functions: intel_drrs_flush - -.. kernel-doc:: drivers/gpu/drm/i915/display/intel_drrs.c - :functions: intel_drrs_init + :internal: DPIO ---- @@ -709,3 +697,31 @@ The style guide for ``i915_reg.h``. .. kernel-doc:: drivers/gpu/drm/i915/i915_reg.h :doc: The i915 register macro definition style guide + +.. _i915-usage-stats: + +i915 DRM client usage stats implementation +========================================== + +The drm/i915 driver implements the DRM client usage stats specification as +documented in :ref:`drm-client-usage-stats`. + +Example of the output showing the implemented key value pairs and entirety of +the currently possible format options: + +:: + + pos: 0 + flags: 0100002 + mnt_id: 21 + drm-driver: i915 + drm-pdev: 0000:00:02.0 + drm-client-id: 7 + drm-engine-render: 9288864723 ns + drm-engine-copy: 2035071108 ns + drm-engine-video: 0 ns + drm-engine-capacity-video: 2 + drm-engine-video-enhance: 0 ns + +Possible `drm-engine-` key names are: `render`, `copy`, `video` and +`video-enhance`. diff --git a/Documentation/gpu/index.rst b/Documentation/gpu/index.rst index b9c1214d8f23..b99dede9a5b1 100644 --- a/Documentation/gpu/index.rst +++ b/Documentation/gpu/index.rst @@ -10,6 +10,7 @@ Linux GPU Driver Developer's Guide drm-kms drm-kms-helpers drm-uapi + drm-usage-stats driver-uapi drm-client drivers diff --git a/Documentation/gpu/introduction.rst b/Documentation/gpu/introduction.rst index 25a56e9c0cfd..f05eccd2c07c 100644 --- a/Documentation/gpu/introduction.rst +++ b/Documentation/gpu/introduction.rst @@ -112,3 +112,63 @@ 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. + +Simple DRM drivers to use as examples +===================================== + +The DRM subsystem contains a lot of helper functions to ease writing drivers for +simple graphic devices. For example, the `drivers/gpu/drm/tiny/` directory has a +set of drivers that are simple enough to be implemented in a single source file. + +These drivers make use of the `struct drm_simple_display_pipe_funcs`, that hides +any complexity of the DRM subsystem and just requires drivers to implement a few +functions needed to operate the device. This could be used for devices that just +need a display pipeline with one full-screen scanout buffer feeding one output. + +The tiny DRM drivers are good examples to understand how DRM drivers should look +like. Since are just a few hundreds lines of code, they are quite easy to read. + +External References +=================== + +Delving into a Linux kernel subsystem for the first time can be an overwhelming +experience, one needs to get familiar with all the concepts and learn about the +subsystem's internals, among other details. + +To shallow the learning curve, this section contains a list of presentations +and documents that can be used to learn about DRM/KMS and graphics in general. + +There are different reasons why someone might want to get into DRM: porting an +existing fbdev driver, write a DRM driver for a new hardware, fixing bugs that +could face when working on the graphics user-space stack, etc. For this reason, +the learning material covers many aspects of the Linux graphics stack. From an +overview of the kernel and user-space stacks to very specific topics. + +The list is sorted in reverse chronological order, to keep the most up-to-date +material at the top. But all of them contain useful information, and it can be +valuable to go through older material to understand the rationale and context +in which the changes to the DRM subsystem were made. + +Conference talks +---------------- + +* `An Overview of the Linux and Userspace Graphics Stack <https://www.youtube.com/watch?v=wjAJmqwg47k>`_ - Paul Kocialkowski (2020) +* `Getting pixels on screen on Linux: introduction to Kernel Mode Setting <https://www.youtube.com/watch?v=haes4_Xnc5Q>`_ - Simon Ser (2020) +* `Everything Great about Upstream Graphics <https://www.youtube.com/watch?v=kVzHOgt6WGE>`_ - Daniel Vetter (2019) +* `An introduction to the Linux DRM subsystem <https://www.youtube.com/watch?v=LbDOCJcDRoo>`_ - Maxime Ripard (2017) +* `Embrace the Atomic (Display) Age <https://www.youtube.com/watch?v=LjiB_JeDn2M>`_ - Daniel Vetter (2016) +* `Anatomy of an Atomic KMS Driver <https://www.youtube.com/watch?v=lihqR9sENpc>`_ - Laurent Pinchart (2015) +* `Atomic Modesetting for Drivers <https://www.youtube.com/watch?v=kl9suFgbTc8>`_ - Daniel Vetter (2015) +* `Anatomy of an Embedded KMS Driver <https://www.youtube.com/watch?v=Ja8fM7rTae4>`_ - Laurent Pinchart (2013) + +Slides and articles +------------------- + +* `Understanding the Linux Graphics Stack <https://bootlin.com/doc/training/graphics/graphics-slides.pdf>`_ - Bootlin (2022) +* `DRM KMS overview <https://wiki.st.com/stm32mpu/wiki/DRM_KMS_overview>`_ - STMicroelectronics (2021) +* `Linux graphic stack <https://studiopixl.com/2017-05-13/linux-graphic-stack-an-overview>`_ - Nathan Gauër (2017) +* `Atomic mode setting design overview, part 1 <https://lwn.net/Articles/653071/>`_ - Daniel Vetter (2015) +* `Atomic mode setting design overview, part 2 <https://lwn.net/Articles/653466/>`_ - Daniel Vetter (2015) +* `The DRM/KMS subsystem from a newbie’s point of view <https://bootlin.com/pub/conferences/2014/elce/brezillon-drm-kms/brezillon-drm-kms.pdf>`_ - Boris Brezillon (2014) +* `A brief introduction to the Linux graphics stack <https://blogs.igalia.com/itoral/2014/07/29/a-brief-introduction-to-the-linux-graphics-stack/>`_ - Iago Toral (2014) +* `The Linux Graphics Stack <https://blog.mecheye.net/2012/06/the-linux-graphics-stack/>`_ - Jasper St. Pierre (2012) diff --git a/Documentation/gpu/todo.rst b/Documentation/gpu/todo.rst index 127e76ee0b2d..10bfb50908d1 100644 --- a/Documentation/gpu/todo.rst +++ b/Documentation/gpu/todo.rst @@ -603,6 +603,20 @@ Level: Advanced Better Testing ============== +Add unit tests using the Kernel Unit Testing (KUnit) framework +-------------------------------------------------------------- + +The `KUnit <https://www.kernel.org/doc/html/latest/dev-tools/kunit/index.html>`_ +provides a common framework for unit tests within the Linux kernel. Having a +test suite would allow to identify regressions earlier. + +A good candidate for the first unit tests are the format-conversion helpers in +``drm_format_helper.c``. + +Contact: Javier Martinez Canillas <javierm@redhat.com> + +Level: Intermediate + Enable trinity for DRM ---------------------- |