diff options
Diffstat (limited to 'Documentation/gpu')
| -rw-r--r-- | Documentation/gpu/amdgpu.rst | 65 | ||||
| -rw-r--r-- | Documentation/gpu/drivers.rst | 1 | ||||
| -rw-r--r-- | Documentation/gpu/drm-internals.rst | 4 | ||||
| -rw-r--r-- | Documentation/gpu/drm-kms-helpers.rst | 15 | ||||
| -rw-r--r-- | Documentation/gpu/drm-kms.rst | 19 | ||||
| -rw-r--r-- | Documentation/gpu/drm-mm.rst | 119 | ||||
| -rw-r--r-- | Documentation/gpu/drm-uapi.rst | 49 | ||||
| -rw-r--r-- | Documentation/gpu/i915.rst | 94 | ||||
| -rw-r--r-- | Documentation/gpu/introduction.rst | 16 | ||||
| -rw-r--r-- | Documentation/gpu/mcde.rst | 2 | ||||
| -rw-r--r-- | Documentation/gpu/tinydrm.rst | 30 | ||||
| -rw-r--r-- | Documentation/gpu/todo.rst | 262 |
12 files changed, 408 insertions, 268 deletions
diff --git a/Documentation/gpu/amdgpu.rst b/Documentation/gpu/amdgpu.rst index 5acdd1842ea2..0efede580039 100644 --- a/Documentation/gpu/amdgpu.rst +++ b/Documentation/gpu/amdgpu.rst @@ -79,16 +79,71 @@ AMDGPU XGMI Support .. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_xgmi.c :internal: -AMDGPU RAS debugfs control interface -==================================== +AMDGPU RAS Support +================== + +The AMDGPU RAS interfaces are exposed via sysfs (for informational queries) and +debugfs (for error injection). + +RAS debugfs/sysfs Control and Error Injection Interfaces +-------------------------------------------------------- .. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_ras.c :doc: AMDGPU RAS debugfs control interface +RAS Reboot Behavior for Unrecoverable Errors +-------------------------------------------------------- + +.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_ras.c + :doc: AMDGPU RAS Reboot Behavior for Unrecoverable Errors + +RAS Error Count sysfs Interface +------------------------------- + +.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_ras.c + :doc: AMDGPU RAS sysfs Error Count Interface + +RAS EEPROM debugfs Interface +---------------------------- + +.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_ras.c + :doc: AMDGPU RAS debugfs EEPROM table reset interface + +RAS VRAM Bad Pages sysfs Interface +---------------------------------- + +.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_ras.c + :doc: AMDGPU RAS sysfs gpu_vram_bad_pages Interface .. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_ras.c :internal: +Sample Code +----------- +Sample code for testing error injection can be found here: +https://cgit.freedesktop.org/mesa/drm/tree/tests/amdgpu/ras_tests.c + +This is part of the libdrm amdgpu unit tests which cover several areas of the GPU. +There are four sets of tests: + +RAS Basic Test + +The test verifies the RAS feature enabled status and makes sure the necessary sysfs and debugfs files +are present. + +RAS Query Test + +This test checks the RAS availability and enablement status for each supported IP block as well as +the error counts. + +RAS Inject Test + +This test injects errors for each IP. + +RAS Disable Test + +This test tests disabling of RAS features for each IP block. + GPU Power/Thermal Controls and Monitoring ========================================= @@ -130,11 +185,11 @@ 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 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +pp_dpm_* +~~~~~~~~ .. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_pm.c - :doc: pp_dpm_sclk pp_dpm_mclk pp_dpm_pcie + :doc: pp_dpm_sclk pp_dpm_mclk pp_dpm_socclk pp_dpm_fclk pp_dpm_dcefclk pp_dpm_pcie pp_power_profile_mode ~~~~~~~~~~~~~~~~~~~~~ diff --git a/Documentation/gpu/drivers.rst b/Documentation/gpu/drivers.rst index 4bfb7068e9f7..b4a0ed3ca961 100644 --- a/Documentation/gpu/drivers.rst +++ b/Documentation/gpu/drivers.rst @@ -11,7 +11,6 @@ GPU Driver Documentation meson pl111 tegra - tinydrm tve200 v3d vc4 diff --git a/Documentation/gpu/drm-internals.rst b/Documentation/gpu/drm-internals.rst index 966bd2d9f0cc..a73320576ca9 100644 --- a/Documentation/gpu/drm-internals.rst +++ b/Documentation/gpu/drm-internals.rst @@ -24,9 +24,9 @@ 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 +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()`. +it accessible from userspace) using drm_dev_register(). The :c:type:`struct drm_driver <drm_driver>` structure contains static information that describes the driver and features it diff --git a/Documentation/gpu/drm-kms-helpers.rst b/Documentation/gpu/drm-kms-helpers.rst index b327bbc11182..9668a7fe2408 100644 --- a/Documentation/gpu/drm-kms-helpers.rst +++ b/Documentation/gpu/drm-kms-helpers.rst @@ -77,9 +77,6 @@ Atomic State Reset and Initialization Atomic State Helper Reference ----------------------------- -.. kernel-doc:: include/drm/drm_atomic_state_helper.h - :internal: - .. kernel-doc:: drivers/gpu/drm/drm_atomic_state_helper.c :export: @@ -263,6 +260,18 @@ the MST topology helpers easier to understand drm_dp_mst_topology_put_port drm_dp_mst_get_mstb_malloc drm_dp_mst_put_mstb_malloc +MIPI DBI Helper Functions Reference +=================================== + +.. kernel-doc:: drivers/gpu/drm/drm_mipi_dbi.c + :doc: overview + +.. kernel-doc:: include/drm/drm_mipi_dbi.h + :internal: + +.. kernel-doc:: drivers/gpu/drm/drm_mipi_dbi.c + :export: + MIPI DSI Helper Functions Reference =================================== diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst index 23a3c986ef6d..906771e03103 100644 --- a/Documentation/gpu/drm-kms.rst +++ b/Documentation/gpu/drm-kms.rst @@ -3,7 +3,7 @@ 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 +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. @@ -181,8 +181,7 @@ 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>`. +multiple times to different objects using drm_object_attach_property(). .. kernel-doc:: include/drm/drm_mode_object.h :internal: @@ -260,7 +259,8 @@ Taken all together there's two consequences for the atomic design: 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. + structures for their globally shared hardware functions, see :c:type:`struct + drm_private_state<drm_private_state>`. - 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>` @@ -269,6 +269,14 @@ Taken all together there's two consequences for the atomic design: to the driver and modeset objects. This way rolling back an update boils down to releasing memory and unreferencing objects like framebuffers. +Locking of atomic state structures is internally using :c:type:`struct +drm_modeset_lock <drm_modeset_lock>`. As a general rule the locking shouldn't be +exposed to drivers, instead the right locks should be automatically acquired by +any function that duplicates or peeks into a state, like e.g. +drm_atomic_get_crtc_state(). Locking only protects the software data +structure, ordering of committing state changes to hardware is sequenced using +:c:type:`struct drm_crtc_commit <drm_crtc_commit>`. + Read on in this chapter, and also in :ref:`drm_atomic_helper` for more detailed coverage of specific topics. @@ -479,6 +487,9 @@ Color Management Properties .. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c :export: +.. kernel-doc:: include/drm/drm_color_mgmt.h + :internal: + Tile Group Property ------------------- diff --git a/Documentation/gpu/drm-mm.rst b/Documentation/gpu/drm-mm.rst index c8ebd4f66a6a..c77b32601260 100644 --- a/Documentation/gpu/drm-mm.rst +++ b/Documentation/gpu/drm-mm.rst @@ -149,19 +149,19 @@ 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 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 +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. +calling 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 @@ -170,20 +170,18 @@ 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. +no shmfs backing (called private GEM objects) by initializing them with a call +to drm_gem_private_object_init() instead of 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 +acquired and release by calling drm_gem_object_get() and drm_gem_object_put() +respectively. The caller must hold the :c:type:`struct drm_device <drm_device>` +struct_mutex lock when calling drm_gem_object_get(). As a convenience, GEM +provides 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 @@ -194,7 +192,7 @@ 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()`. +drm_gem_object_release(). GEM Objects Naming ------------------ @@ -210,13 +208,11 @@ 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()`. +To create a handle for a GEM object drivers call 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 drm_gem_handle_delete(). Finally the GEM object associated with a +handle can be retrieved by a call to 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 @@ -258,7 +254,7 @@ 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 +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. @@ -267,23 +263,22 @@ The second method uses the mmap system call on the DRM file handle. void 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. +must call 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 +The GEM core provides a helper method 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. +<drm_driver>` gem_vm_ops field. Note that 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. +To use 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: @@ -298,9 +293,8 @@ made up of several fields, the more interesting ones being: 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. +count. Drivers can use the drm_gem_vm_open() and 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 @@ -312,12 +306,12 @@ 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. +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`. +To use 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 drm_gem_cma_get_unmapped_area(). More detailed information about get_unmapped_area can be found in Documentation/nommu-mmap.txt @@ -400,16 +394,13 @@ GEM VRAM Helper Functions Reference .. kernel-doc:: drivers/gpu/drm/drm_gem_vram_helper.c :export: -VRAM MM Helper Functions Reference ----------------------------------- +GEM TTM Helper Functions Reference +----------------------------------- -.. kernel-doc:: drivers/gpu/drm/drm_vram_mm_helper.c +.. kernel-doc:: drivers/gpu/drm/drm_gem_ttm_helper.c :doc: overview -.. kernel-doc:: include/drm/drm_vram_mm_helper.h - :internal: - -.. kernel-doc:: drivers/gpu/drm/drm_vram_mm_helper.c +.. kernel-doc:: drivers/gpu/drm/drm_gem_ttm_helper.c :export: VMA Offset Manager @@ -433,43 +424,11 @@ 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 ------------------------------ +Overview and Lifetime Rules +--------------------------- -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. +.. kernel-doc:: drivers/gpu/drm/drm_prime.c + :doc: overview and lifetime rules PRIME Helper Functions ---------------------- diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst index 94f90521f58c..56fec6ed1ad8 100644 --- a/Documentation/gpu/drm-uapi.rst +++ b/Documentation/gpu/drm-uapi.rst @@ -254,36 +254,45 @@ 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/. +its code and instructions to build and run can be found in +https://gitlab.freedesktop.org/drm/igt-gpu-tools/. -To build IGT, start by installing its build dependencies. In Debian-based -systems:: +Using VKMS to test DRM API +-------------------------- - # apt-get build-dep intel-gpu-tools +VKMS is a software-only model of a KMS driver that is useful for testing +and for running compositors. VKMS aims to enable a virtual display without +the need for a hardware display capability. These characteristics made VKMS +a perfect tool for validating the DRM core behavior and also support the +compositor developer. VKMS makes it possible to test DRM functions in a +virtual machine without display, simplifying the validation of some of the +core changes. -And in Fedora-based systems:: +To Validate changes in DRM API with VKMS, start setting the kernel: make +sure to enable VKMS module; compile the kernel with the VKMS enabled and +install it in the target machine. VKMS can be run in a Virtual Machine +(QEMU, virtme or similar). It's recommended the use of KVM with the minimum +of 1GB of RAM and four cores. - # dnf builddep intel-gpu-tools +It's possible to run the IGT-tests in a VM in two ways: -Then clone the repository:: + 1. Use IGT inside a VM + 2. Use IGT from the host machine and write the results in a shared directory. - $ git clone git://anongit.freedesktop.org/drm/igt-gpu-tools +As follow, there is an example of using a VM with a shared directory with +the host machine to run igt-tests. As an example it's used virtme:: -Configure the build system and start the build:: + $ virtme-run --rwdir /path/for/shared_dir --kdir=path/for/kernel/directory --mods=auto - $ cd igt-gpu-tools && ./autogen.sh && make -j6 +Run the igt-tests in the guest machine, as example it's ran the 'kms_flip' +tests:: -Download the piglit dependency:: + $ /path/for/igt-gpu-tools/scripts/run-tests.sh -p -s -t "kms_flip.*" -v - $ ./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. +In this example, instead of build the igt_runner, Piglit is used +(-p option); it's created html summary of the tests results and it's saved +in the folder "igt-gpu-tools/results"; it's executed only the igt-tests +matching the -t option. Display CRC Support ------------------- diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst index c38ef0dda605..e539c42a3e78 100644 --- a/Documentation/gpu/i915.rst +++ b/Documentation/gpu/i915.rst @@ -91,9 +91,6 @@ Frontbuffer Tracking .. kernel-doc:: drivers/gpu/drm/i915/display/intel_frontbuffer.c :internal: -.. kernel-doc:: drivers/gpu/drm/i915/i915_gem.c - :functions: i915_gem_track_fb - Display FIFO Underrun Reporting ------------------------------- @@ -249,6 +246,15 @@ Display PLLs .. kernel-doc:: drivers/gpu/drm/i915/display/intel_dpll_mgr.h :internal: +Display State Buffer +-------------------- + +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dsb.c + :doc: DSB + +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dsb.c + :internal: + Memory Management and Command Submission ======================================== @@ -361,15 +367,6 @@ Batchbuffer Parsing .. 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 -------------------------- @@ -418,44 +415,77 @@ Object Tiling IOCTLs .. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_tiling.c :doc: buffer object tiling +Microcontrollers +================ + +Starting from gen9, three microcontrollers are available on the HW: the +graphics microcontroller (GuC), the HEVC/H.265 microcontroller (HuC) and the +display microcontroller (DMC). The driver is responsible for loading the +firmwares on the microcontrollers; the GuC and HuC firmwares are transferred +to WOPCM using the DMA engine, while the DMC firmware is written through MMIO. + WOPCM -===== +----- WOPCM Layout ------------- +~~~~~~~~~~~~ .. kernel-doc:: drivers/gpu/drm/i915/intel_wopcm.c :doc: WOPCM Layout GuC -=== +--- + +.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc.c + :doc: GuC + +GuC Firmware Layout +~~~~~~~~~~~~~~~~~~~ + +.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_uc_fw_abi.h + :doc: Firmware Layout + +GuC Memory Management +~~~~~~~~~~~~~~~~~~~~~ + +.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc.c + :doc: GuC Memory Management +.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc.c + :functions: intel_guc_allocate_vma + GuC-specific firmware loader ----------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. kernel-doc:: drivers/gpu/drm/i915/intel_guc_fw.c +.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc_fw.c :internal: GuC-based command submission ----------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. kernel-doc:: drivers/gpu/drm/i915/intel_guc_submission.c +.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc_submission.c :doc: GuC-based command submission -.. kernel-doc:: drivers/gpu/drm/i915/intel_guc_submission.c - :internal: +HuC +--- +.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_huc.c + :doc: HuC +.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_huc.c + :functions: intel_huc_auth -GuC Firmware Layout -------------------- +HuC Memory Management +~~~~~~~~~~~~~~~~~~~~~ -.. kernel-doc:: drivers/gpu/drm/i915/intel_guc_fwif.h - :doc: GuC Firmware Layout +.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_huc.c + :doc: HuC Memory Management -GuC Address Space ------------------ +HuC Firmware Layout +~~~~~~~~~~~~~~~~~~~ +The HuC FW layout is the same as the GuC one, see `GuC Firmware Layout`_ -.. kernel-doc:: drivers/gpu/drm/i915/intel_guc.c - :doc: GuC Address Space +DMC +--- +See `CSR firmware support for DMC`_ Tracing ======= @@ -517,9 +547,9 @@ 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 +.. kernel-doc:: drivers/gpu/drm/i915/i915_perf_types.h :functions: i915_perf_stream -.. kernel-doc:: drivers/gpu/drm/i915/i915_drv.h +.. kernel-doc:: drivers/gpu/drm/i915/i915_perf_types.h :functions: i915_perf_stream_ops .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c @@ -544,7 +574,7 @@ for representing an i915 perf stream FD and associated file operations. i915 Perf Observation Architecture Stream ----------------------------------------- -.. kernel-doc:: drivers/gpu/drm/i915/i915_drv.h +.. kernel-doc:: drivers/gpu/drm/i915/i915_perf_types.h :functions: i915_oa_ops .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c diff --git a/Documentation/gpu/introduction.rst b/Documentation/gpu/introduction.rst index fccbe375244d..25a56e9c0cfd 100644 --- a/Documentation/gpu/introduction.rst +++ b/Documentation/gpu/introduction.rst @@ -51,6 +51,22 @@ and "FIXME" where the interface could be cleaned up. Also read the :ref:`guidelines for the kernel documentation at large <doc_guide>`. +Documentation Requirements for kAPI +----------------------------------- + +All kernel APIs exported to other modules must be documented, including their +datastructures and at least a short introductory section explaining the overall +concepts. Documentation should be put into the code itself as kerneldoc comments +as much as reasonable. + +Do not blindly document everything, but document only what's relevant for driver +authors: Internal functions of drm.ko and definitely static functions should not +have formal kerneldoc comments. Use normal C comments if you feel like a comment +is warranted. You may use kerneldoc syntax in the comment, but it shall not +start with a /** kerneldoc marker. Similar for data structures, annotate +anything entirely private with ``/* private: */`` comments as per the +documentation guide. + Getting Started =============== diff --git a/Documentation/gpu/mcde.rst b/Documentation/gpu/mcde.rst index c69e977defda..dd43dde379e0 100644 --- a/Documentation/gpu/mcde.rst +++ b/Documentation/gpu/mcde.rst @@ -5,4 +5,4 @@ ======================================================= .. kernel-doc:: drivers/gpu/drm/mcde/mcde_drv.c - :doc: ST-Ericsson MCDE DRM Driver + :doc: ST-Ericsson MCDE Driver diff --git a/Documentation/gpu/tinydrm.rst b/Documentation/gpu/tinydrm.rst deleted file mode 100644 index 33a41544f659..000000000000 --- a/Documentation/gpu/tinydrm.rst +++ /dev/null @@ -1,30 +0,0 @@ -============================ -drm/tinydrm Tiny DRM drivers -============================ - -tinydrm is a collection of DRM drivers that are so small they can fit in a -single source file. - -Helpers -======= - -.. kernel-doc:: include/drm/tinydrm/tinydrm-helpers.h - :internal: - -.. kernel-doc:: drivers/gpu/drm/tinydrm/core/tinydrm-helpers.c - :export: - -.. kernel-doc:: drivers/gpu/drm/tinydrm/core/tinydrm-pipe.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: diff --git a/Documentation/gpu/todo.rst b/Documentation/gpu/todo.rst index 0a49c5a1d9ce..bc869b23fc39 100644 --- a/Documentation/gpu/todo.rst +++ b/Documentation/gpu/todo.rst @@ -7,6 +7,22 @@ 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. +Difficulty +---------- + +To make it easier task are categorized into different levels: + +Starter: Good tasks to get started with the DRM subsystem. + +Intermediate: Tasks which need some experience with working in the DRM +subsystem, or some specific GPU/display graphics knowledge. For debugging issue +it's good to have the relevant hardware (or a virtual driver set up) available +for testing. + +Advanced: Tricky tasks that need fairly good understanding of the DRM subsystem +and graphics topics. Generally need the relevant hardware for development and +testing. + Subsystem-wide refactorings =========================== @@ -20,6 +36,8 @@ implementations), and then remove it. Contact: Daniel Vetter, respective driver maintainers +Level: Intermediate + Convert existing KMS drivers to atomic modesetting -------------------------------------------------- @@ -38,6 +56,8 @@ do by directly using the new atomic helper driver callbacks. Contact: Daniel Vetter, respective driver maintainers +Level: Advanced + Clean up the clipped coordination confusion around planes --------------------------------------------------------- @@ -50,6 +70,8 @@ helpers. Contact: Ville Syrjälä, Daniel Vetter, driver maintainers +Level: Advanced + Convert early atomic drivers to async commit helpers ---------------------------------------------------- @@ -63,6 +85,8 @@ events for atomic commits correctly. But fixing these bugs is good anyway. Contact: Daniel Vetter, respective driver maintainers +Level: Advanced + Fallout from atomic KMS ----------------------- @@ -91,6 +115,8 @@ interfaces to fix these issues: Contact: Daniel Vetter +Level: Intermediate + Get rid of dev->struct_mutex from GEM drivers --------------------------------------------- @@ -114,14 +140,16 @@ fine-grained per-buffer object and per-context lockings scheme. Currently only t Contact: Daniel Vetter, respective driver maintainers -Convert instances of dev_info/dev_err/dev_warn to their DRM_DEV_* equivalent ----------------------------------------------------------------------------- +Level: Advanced + +Convert logging to drm_* functions with drm_device paramater +------------------------------------------------------------ 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. +now have drm_* variants of the drm print functions, so we can start to convert +those drivers back to using drm-formatted 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 @@ -129,6 +157,8 @@ are better. Contact: Sean Paul, Maintainer of the driver you plan to convert +Level: Starter + Convert drivers to use simple modeset suspend/resume ---------------------------------------------------- @@ -139,41 +169,64 @@ of the atomic suspend/resume code in older atomic modeset drivers. Contact: Maintainer of the driver you plan to convert -Convert drivers to use drm_fb_helper_fbdev_setup/teardown() ------------------------------------------------------------ +Level: Intermediate -Most drivers can use drm_fb_helper_fbdev_setup() except maybe: +Convert drivers to use drm_fbdev_generic_setup() +------------------------------------------------ -- amdgpu which has special logic to decide whether to call - drm_helper_disable_unused_functions() +Most drivers can use drm_fbdev_generic_setup(). Driver have to implement +atomic modesetting and GEM vmap support. Current generic fbdev emulation +expects the framebuffer in system memory (or system-like memory). -- armada which isn't atomic and doesn't call - drm_helper_disable_unused_functions() +Contact: Maintainer of the driver you plan to convert -- i915 which calls drm_fb_helper_initial_config() in a worker +Level: Intermediate -Drivers that use drm_framebuffer_remove() to clean up the fbdev framebuffer can -probably use drm_fb_helper_fbdev_teardown(). +drm_framebuffer_funcs and drm_mode_config_funcs.fb_create cleanup +----------------------------------------------------------------- -Contact: Maintainer of the driver you plan to convert +A lot more drivers could be switched over to the drm_gem_framebuffer helpers. +Various hold-ups: + +- Need to switch over to the generic dirty tracking code using + drm_atomic_helper_dirtyfb first (e.g. qxl). + +- Need to switch to drm_fbdev_generic_setup(), otherwise a lot of the custom fb + setup code can't be deleted. + +- Many drivers wrap drm_gem_fb_create() only to check for valid formats. For + atomic drivers we could check for valid formats by calling + drm_plane_check_pixel_format() against all planes, and pass if any plane + supports the format. For non-atomic that's not possible since like the format + list for the primary plane is fake and we'd therefor reject valid formats. + +- Many drivers subclass drm_framebuffer, we'd need a embedding compatible + version of the varios drm_gem_fb_create functions. Maybe called + drm_gem_fb_create/_with_dirty/_with_funcs as needed. + +Contact: Daniel Vetter + +Level: Intermediate 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. +There's drm_gem_prime_mmap() for this now, but still needs to be rolled out. Contact: Daniel Vetter +Level: Intermediate + Generic fbdev defio support --------------------------- The defio support code in the fbdev core has some very specific requirements, -which means drivers need to have a special framebuffer for fbdev. Which prevents -us from using the generic fbdev emulation code everywhere. The main issue is -that it uses some fields in struct page itself, which breaks shmem gem objects -(and other things). +which means drivers need to have a special framebuffer for fbdev. The main +issue is that it uses some fields in struct page itself, which breaks shmem +gem objects (and other things). To support defio, affected drivers require +the use of a shadow buffer, which may add CPU and memory overhead. Possible solution would be to write our own defio mmap code in the drm fbdev emulation. It would need to fully wrap the existing mmap ops, forwarding @@ -196,14 +249,7 @@ Might be good to also have some igt testcases for this. Contact: Daniel Vetter, Noralf Tronnes -Remove the ->gem_prime_res_obj callback --------------------------------------------- - -The ->gem_prime_res_obj callback can be removed from drivers by using the -reservation_object in the drm_gem_object. It may also be possible to use the -generic drm_gem_reservation_object_wait helper for waiting for a bo. - -Contact: Daniel Vetter +Level: Advanced idr_init_base() --------------- @@ -215,12 +261,7 @@ efficient. Contact: Daniel Vetter -Defaults for .gem_prime_import and export ------------------------------------------ - -Most drivers don't need to set drm_driver->gem_prime_import and -->gem_prime_export now that drm_gem_prime_import() and drm_gem_prime_export() -are the default. +Level: Starter struct drm_gem_object_funcs --------------------------- @@ -228,12 +269,12 @@ struct drm_gem_object_funcs GEM objects can now have a function table instead of having the callbacks on the DRM driver struct. This is now the preferred way and drivers can be moved over. -DRM_GEM_CMA_VMAP_DRIVER_OPS, DRM_GEM_SHMEM_DRIVER_OPS already support this, but -DRM_GEM_VRAM_DRIVER_PRIME does not yet and needs to be aligned with the previous -two. We also need a 2nd version of the CMA define that doesn't require the +We also need a 2nd version of the CMA define that doesn't require the vmapping to be present (different hook for prime importing). Plus this needs to be rolled out to all drivers using their own implementations, too. +Level: Intermediate + Use DRM_MODESET_LOCK_ALL_* helpers instead of boilerplate --------------------------------------------------------- @@ -249,6 +290,8 @@ As a reference, take a look at the conversions already completed in drm core. Contact: Sean Paul, respective driver maintainers +Level: Starter + Rename CMA helpers to DMA helpers --------------------------------- @@ -259,6 +302,9 @@ no one knows what that means) since underneath they just use dma_alloc_coherent. Contact: Laurent Pinchart, Daniel Vetter +Level: Intermediate (mostly because it is a huge tasks without good partial +milestones, not technically itself that challenging) + Convert direct mode.vrefresh accesses to use drm_mode_vrefresh() ---------------------------------------------------------------- @@ -277,6 +323,8 @@ drm_display_mode to avoid future use. Contact: Sean Paul +Level: Starter + Remove drm_display_mode.hsync ----------------------------- @@ -287,6 +335,8 @@ it to use drm_mode_hsync() instead. Contact: Sean Paul +Level: Starter + drm_fb_helper tasks ------------------- @@ -295,41 +345,49 @@ drm_fb_helper tasks these igt tests need to be fixed: kms_fbcon_fbt@psr and kms_fbcon_fbt@psr-suspend. -- The max connector argument for drm_fb_helper_init() and - drm_fb_helper_fbdev_setup() isn't used anymore and can be removed. +- The max connector argument for drm_fb_helper_init() isn't used anymore and + can be removed. - The helper doesn't keep an array of connectors anymore so these can be removed: drm_fb_helper_single_add_all_connectors(), drm_fb_helper_add_one_connector() and drm_fb_helper_remove_one_connector(). -Core refactorings -================= +Level: Intermediate -Clean up the DRM header mess ----------------------------- +connector register/unregister fixes +----------------------------------- -The DRM subsystem originally had only one huge global header, ``drmP.h``. This -is now split up, but many source files still include it. The remaining part of -the cleanup work here is to replace any ``#include <drm/drmP.h>`` by only the -headers needed (and fixing up any missing pre-declarations in the headers). +- For most connectors it's a no-op to call drm_connector_register/unregister + directly from driver code, drm_dev_register/unregister take care of this + already. We can remove all of them. -In the end no .c file should need to include ``drmP.h`` anymore. +- For dp drivers it's a bit more a mess, since we need the connector to be + registered when calling drm_dp_aux_register. Fix this by instead calling + drm_dp_aux_init, and moving the actual registering into a late_register + callback as recommended in the kerneldoc. -Contact: Daniel Vetter +Level: Intermediate + +Remove load/unload callbacks from all non-DRIVER_LEGACY drivers +--------------------------------------------------------------- -Add missing kerneldoc for exported functions --------------------------------------------- +The load/unload callbacks in struct &drm_driver are very much midlayers, plus +for historical reasons they get the ordering wrong (and we can't fix that) +between setting up the &drm_driver structure and calling drm_dev_register(). -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. +- Rework drivers to no longer use the load/unload callbacks, directly coding the + load/unload sequence into the driver's probe function. -See https://dri.freedesktop.org/docs/drm/ for what's there already. +- Once all non-DRIVER_LEGACY drivers are converted, disallow the load/unload + callbacks for all modern drivers. Contact: Daniel Vetter +Level: Intermediate + +Core refactorings +================= + Make panic handling work ------------------------ @@ -369,6 +427,8 @@ This is a really varied tasks with lots of little bits and pieces: Contact: Daniel Vetter +Level: Advanced + Clean up the debugfs support ---------------------------- @@ -393,8 +453,13 @@ There's a bunch of issues with it: this (together with the drm_minor->drm_device move) would allow us to remove debugfs_init. +- Drop the return code and error checking from all debugfs functions. Greg KH is + working on this already. + Contact: Daniel Vetter +Level: Intermediate + KMS cleanups ------------ @@ -410,6 +475,8 @@ Some of these date from the very introduction of KMS in 2008 ... end, for which we could add drm_*_cleanup_kfree(). And then there's the (for historical reasons) misnamed drm_primary_helper_destroy() function. +Level: Intermediate + Better Testing ============== @@ -418,6 +485,8 @@ Enable trinity for DRM And fix up the fallout. Should be really interesting ... +Level: Advanced + Make KMS tests in i-g-t generic ------------------------------- @@ -431,6 +500,8 @@ 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. +Level: Advanced + Extend virtual test driver (VKMS) --------------------------------- @@ -440,38 +511,25 @@ fit the available time. Contact: Daniel Vetter -Driver Specific -=============== +Level: See details -tinydrm -------- +Backlight Refactoring +--------------------- -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 drivers have a triple enable/disable state, which is a bit overkill. +Plan to fix this: -- 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 +1. Roll out backlight_enable() and backlight_disable() helpers everywhere. This + has started already. +2. In all, only look at one of the three status bits set by the above helpers. +3. Remove the other two status bits. -- 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. +Contact: Daniel Vetter -- 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. +Level: Intermediate -Contact: Noralf Trønnes, Daniel Vetter +Driver Specific +=============== AMD DC Display Driver --------------------- @@ -483,13 +541,6 @@ 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 - Bootsplash ========== @@ -505,5 +556,36 @@ for fbdev. Contact: Sam Ravnborg +Level: Advanced + Outside DRM =========== + +Convert fbdev drivers to DRM +---------------------------- + +There are plenty of fbdev drivers for older hardware. Some hwardware has +become obsolete, but some still provides good(-enough) framebuffers. The +drivers that are still useful should be converted to DRM and afterwards +removed from fbdev. + +Very simple fbdev drivers can best be converted by starting with a new +DRM driver. Simple KMS helpers and SHMEM should be able to handle any +existing hardware. The new driver's call-back functions are filled from +existing fbdev code. + +More complex fbdev drivers can be refactored step-by-step into a DRM +driver with the help of the DRM fbconv helpers. [1] These helpers provide +the transition layer between the DRM core infrastructure and the fbdev +driver interface. Create a new DRM driver on top of the fbconv helpers, +copy over the fbdev driver, and hook it up to the DRM code. Examples for +several fbdev drivers are available at [1] and a tutorial of this process +available at [2]. The result is a primitive DRM driver that can run X11 +and Weston. + + - [1] https://gitlab.freedesktop.org/tzimmermann/linux/tree/fbconv + - [2] https://gitlab.freedesktop.org/tzimmermann/linux/blob/fbconv/drivers/gpu/drm/drm_fbconv_helper.c + +Contact: Thomas Zimmermann <tzimmermann@suse.de> + +Level: Advanced |
