summaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
authorDave Airlie <airlied@redhat.com>2017-01-10 08:06:56 +1000
committerDave Airlie <airlied@redhat.com>2017-01-10 08:06:56 +1000
commit282d0a35c8c42c3ac4dd86a7e408ed1b30db4897 (patch)
tree2a2242f3d257098fd52b7bd83dfd8271cdf9e082 /Documentation
parent5c37daf5dd2e63090abba4ea200b56176f6e4781 (diff)
parenta009e975da5c7d42a7f5eaadc54946eb5f76c9af (diff)
Merge tag 'drm-misc-next-2017-01-09' of git://anongit.freedesktop.org/git/drm-misc into drm-next
Back to regular -misc pulls with reasonable sizes: - dma_fence error clarification (Chris) - drm_crtc_from_index helper (Shawn), pile more patches on the m-l to roll this out to drivers - mmu-less support for fbdev helpers from Benjamin - piles of kerneldoc work - some polish for crc support from Tomeu and Benjamin - odd misc stuff all over * tag 'drm-misc-next-2017-01-09' of git://anongit.freedesktop.org/git/drm-misc: (48 commits) dma-fence: Introduce drm_fence_set_error() helper dma-fence: Wrap querying the fence->status dma-fence: Clear fence->status during dma_fence_init() drm: fix compilations issues introduced by "drm: allow to use mmuless SoC" drm: Change the return type of the unload hook to void drm: add more document for drm_crtc_from_index() drm: remove useless parameters from drm_pick_cmdline_mode function drm: crc: Call wake_up_interruptible() each time there is a new CRC entry drm: allow to use mmuless SoC drm: compile drm_vm.c only when needed fbmem: add a default get_fb_unmapped_area function drm: crc: Wait for a frame before returning from open() drm: Move locking into drm_debugfs_crtc_crc_add drm/imx: imx-tve: Remove unused variable Revert "drm: nouveau: fix build when LEDS_CLASS=m" drm: Add kernel-doc for drm_crtc_commit_get/put drm/atomic: Fix outdated comment. drm: reference count event->completion gpu: drm: mgag200: mgag200_main:- Handle error from pci_iomap drm: Document deprecated load/unload hook ...
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/gpu/drm-mm.rst40
-rw-r--r--Documentation/gpu/drm-uapi.rst25
-rw-r--r--Documentation/gpu/introduction.rst15
3 files changed, 48 insertions, 32 deletions
diff --git a/Documentation/gpu/drm-mm.rst b/Documentation/gpu/drm-mm.rst
index cb5daffcd6be..1ea94fc86caa 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)
====================================
@@ -303,6 +310,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 +460,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
------------------------------------------
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/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>`.