diff options
Diffstat (limited to 'Documentation/gpu')
| -rw-r--r-- | Documentation/gpu/drm-kms.rst | 8 | ||||
| -rw-r--r-- | Documentation/gpu/drm-mm.rst | 61 | ||||
| -rw-r--r-- | Documentation/gpu/drm-uapi.rst | 25 | ||||
| -rw-r--r-- | Documentation/gpu/i915.rst | 103 | ||||
| -rw-r--r-- | Documentation/gpu/index.rst | 1 | ||||
| -rw-r--r-- | Documentation/gpu/introduction.rst | 15 | ||||
| -rw-r--r-- | Documentation/gpu/tinydrm.rst | 42 |
7 files changed, 218 insertions, 37 deletions
diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst index 0c9abdc0ee31..4d4068855ec4 100644 --- a/Documentation/gpu/drm-kms.rst +++ b/Documentation/gpu/drm-kms.rst @@ -48,11 +48,17 @@ CRTC Abstraction ================ .. kernel-doc:: drivers/gpu/drm/drm_crtc.c - :export: + :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 ======================== diff --git a/Documentation/gpu/drm-mm.rst b/Documentation/gpu/drm-mm.rst index cb5daffcd6be..f5760b140f13 100644 --- a/Documentation/gpu/drm-mm.rst +++ b/Documentation/gpu/drm-mm.rst @@ -34,25 +34,26 @@ TTM initialization ------------------ **Warning** - This section is outdated. -Drivers wishing to support TTM must fill out a drm_bo_driver -structure. The 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. See -the radeon_ttm.c file for an example of usage. +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 ttm_global_reference structure is made up of several fields: +The :c:type:`struct drm_global_reference <drm_global_reference>` is made +up of several fields: .. code-block:: c - struct ttm_global_reference { + struct drm_global_reference { enum ttm_global_types global_type; size_t size; void *object; - int (*init) (struct ttm_global_reference *); - void (*release) (struct ttm_global_reference *); + int (*init) (struct drm_global_reference *); + void (*release) (struct drm_global_reference *); }; @@ -76,6 +77,12 @@ 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) ==================================== @@ -284,10 +291,17 @@ 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. -struct vm_operations_struct \*gem_vm_ops struct -vm_operations_struct { void (\*open)(struct vm_area_struct \* area); -void (\*close)(struct vm_area_struct \* area); int (\*fault)(struct -vm_area_struct \*vma, struct vm_fault \*vmf); }; +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 @@ -303,6 +317,17 @@ 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 ---------------- @@ -442,7 +467,7 @@ LRU Scan/Eviction Support ------------------------- .. kernel-doc:: drivers/gpu/drm/drm_mm.c - :doc: lru scan roaster + :doc: lru scan roster DRM MM Range Allocator Function References ------------------------------------------ @@ -452,3 +477,9 @@ DRM MM Range Allocator Function References .. kernel-doc:: include/drm/drm_mm.h :internal: + +DRM Cache Handling +================== + +.. kernel-doc:: drivers/gpu/drm/drm_cache.c + :export: diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst index de3ac9f90f8f..fcc228ef5bc4 100644 --- a/Documentation/gpu/drm-uapi.rst +++ b/Documentation/gpu/drm-uapi.rst @@ -156,8 +156,12 @@ 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. + +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 @@ -193,6 +197,12 @@ 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 + VBlank event handling ===================== @@ -209,16 +219,3 @@ DRM_IOCTL_MODESET_CTL 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. - -This second part of the GPU Driver Developer's Guide documents driver -code, implementation details and also all the driver-specific userspace -interfaces. Especially since all hardware-acceleration interfaces to -userspace are driver specific for efficiency and other reasons these -interfaces can be rather substantial. Hence every driver has its own -chapter. - -Testing and validation -====================== - -.. kernel-doc:: drivers/gpu/drm/drm_debugfs_crc.c - :doc: CRC ABI diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst index 7fb605af090e..b0d6709b8600 100644 --- a/Documentation/gpu/i915.rst +++ b/Documentation/gpu/i915.rst @@ -222,6 +222,18 @@ Video BIOS Table (VBT) .. kernel-doc:: drivers/gpu/drm/i915/intel_vbt_defs.h :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 ======================================== @@ -365,4 +377,95 @@ 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 + +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: + .. WARNING: DOCPROC directive not supported: !Cdrivers/gpu/drm/i915/i915_irq.c diff --git a/Documentation/gpu/index.rst b/Documentation/gpu/index.rst index 367d7c36b8e9..f81278a7c2cc 100644 --- a/Documentation/gpu/index.rst +++ b/Documentation/gpu/index.rst @@ -11,6 +11,7 @@ Linux GPU Driver Developer's Guide drm-kms-helpers drm-uapi i915 + tinydrm vga-switcheroo vgaarbiter diff --git a/Documentation/gpu/introduction.rst b/Documentation/gpu/introduction.rst index 1903595b5310..eb284eb748ba 100644 --- a/Documentation/gpu/introduction.rst +++ b/Documentation/gpu/introduction.rst @@ -23,13 +23,12 @@ 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, &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 please use ->vfunc(). Note that kerneldoc does not -support referencing struct members directly, so please add a reference -to the vtable struct somewhere in the same paragraph or at least -section. +@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. @@ -49,3 +48,5 @@ 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>`. diff --git a/Documentation/gpu/tinydrm.rst b/Documentation/gpu/tinydrm.rst new file mode 100644 index 000000000000..a913644bfc19 --- /dev/null +++ b/Documentation/gpu/tinydrm.rst @@ -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: |