From 700496fa11441b733c9e10a247e3a287d9b5a6e6 Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Wed, 23 Oct 2019 16:49:53 +0200 Subject: drm/todo: Add entry to remove load/unload hooks They're midlayer, broken, and because of the old gunk, we can't fix them. For examples see the various checks in drm_mode_object.c against dev->registered, which cannot be enforced if the driver still uses the load hook. Unfortunately our biggest driver still uses load/unload, so this would be really great to get fixed. Cc: Alex Deucher Cc: Harry Wentland Reviewed-by: Thierry Reding Signed-off-by: Daniel Vetter Link: https://patchwork.freedesktop.org/patch/msgid/20191023144953.28190-2-daniel.vetter@ffwll.ch --- Documentation/gpu/todo.rst | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) (limited to 'Documentation/gpu') diff --git a/Documentation/gpu/todo.rst b/Documentation/gpu/todo.rst index 6792fa9b6b6b..b3c0d517db93 100644 --- a/Documentation/gpu/todo.rst +++ b/Documentation/gpu/todo.rst @@ -351,6 +351,23 @@ connector register/unregister fixes Level: Intermediate +Remove load/unload callbacks from all non-DRIVER_LEGACY drivers +--------------------------------------------------------------- + +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(). + +- Rework drivers to no longer use the load/unload callbacks, directly coding the + load/unload sequence into the driver's probe function. + +- Once all non-DRIVER_LEGACY drivers are converted, disallow the load/unload + callbacks for all modern drivers. + +Contact: Daniel Vetter + +Level: Intermediate + Core refactorings ================= -- cgit v1.2.3 From 8a537de0f3d8b655cb901c948ed863bf0b23277b Mon Sep 17 00:00:00 2001 From: Leandro Ribeiro Date: Tue, 29 Oct 2019 22:12:11 -0300 Subject: drm/doc: Update IGT documentation The IGT documentation in this page is telling us to build it using make. According to commit 67993c1 ("automake: Point builders at meson") from the IGT project, this is deprecated and IGT should be built with meson. Instead of having a documentation for IGT in this page, point to their GitLab README, which should always be up to date. Signed-off-by: Leandro Ribeiro Signed-off-by: Daniel Vetter Link: https://patchwork.freedesktop.org/patch/msgid/20191030011211.47942-1-leandrohr@riseup.net --- Documentation/gpu/drm-uapi.rst | 32 ++------------------------------ 1 file changed, 2 insertions(+), 30 deletions(-) (limited to 'Documentation/gpu') diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst index 94f90521f58c..996f7354e05c 100644 --- a/Documentation/gpu/drm-uapi.rst +++ b/Documentation/gpu/drm-uapi.rst @@ -254,36 +254,8 @@ 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. +its code and instructions to build and run can be found in +https://gitlab.freedesktop.org/drm/igt-gpu-tools/. Display CRC Support ------------------- -- cgit v1.2.3 From 80ae0369d3e4b8559c04e2b4de2b86640908f2fd Mon Sep 17 00:00:00 2001 From: Thomas Zimmermann Date: Wed, 6 Nov 2019 13:47:26 +0100 Subject: drm/todo: Convert drivers to generic fbdev emulation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This replaces the original TODO item for drm_fb_helper_fbdev_setup() and _teardown(), which are deprecated. v2: * remove driver-specific comments * list some basic requirements * keep a TODO item on drm_fb_helper_init() Signed-off-by: Thomas Zimmermann Reviewed-by: Noralf Trønnes Link: https://patchwork.freedesktop.org/patch/msgid/20191106124727.11641-2-tzimmermann@suse.de --- Documentation/gpu/todo.rst | 23 +++++++---------------- 1 file changed, 7 insertions(+), 16 deletions(-) (limited to 'Documentation/gpu') diff --git a/Documentation/gpu/todo.rst b/Documentation/gpu/todo.rst index b3c0d517db93..3ec509381fc5 100644 --- a/Documentation/gpu/todo.rst +++ b/Documentation/gpu/todo.rst @@ -171,21 +171,12 @@ Contact: Maintainer of the driver you plan to convert Level: Intermediate -Convert drivers to use drm_fb_helper_fbdev_setup/teardown() ------------------------------------------------------------ +Convert drivers to use drm_fbdev_generic_setup() +------------------------------------------------ -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(). +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). Contact: Maintainer of the driver you plan to convert @@ -328,8 +319,8 @@ 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(), -- cgit v1.2.3 From 2c81bdc8024ef6f81dfecab86bcb97a8694dcd1e Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Wed, 27 Nov 2019 19:00:35 +0100 Subject: drm/todo: Add entry for fb funcs related cleanups We're doing a great job for really simple drivers right now, but still a lot of boilerplate for the bigger ones. Acked-by: Thomas Zimmermann Signed-off-by: Daniel Vetter Link: https://patchwork.freedesktop.org/patch/msgid/20191127180035.416209-3-daniel.vetter@ffwll.ch --- Documentation/gpu/todo.rst | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) (limited to 'Documentation/gpu') diff --git a/Documentation/gpu/todo.rst b/Documentation/gpu/todo.rst index 3ec509381fc5..2d85f37284a1 100644 --- a/Documentation/gpu/todo.rst +++ b/Documentation/gpu/todo.rst @@ -182,6 +182,32 @@ Contact: Maintainer of the driver you plan to convert Level: Intermediate +drm_framebuffer_funcs and drm_mode_config_funcs.fb_create cleanup +----------------------------------------------------------------- + +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 ------------------------ -- cgit v1.2.3 From 65b2f7c43c6f087784db309e8a75bae3d2266520 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ville=20Syrj=C3=A4l=C3=A4?= Date: Fri, 8 Nov 2019 15:56:54 +0200 Subject: drm: Inline drm_color_lut_extract() MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This thing can get called several thousand times per LUT so seems like we want to inline it to: - avoid the function call overhead - allow constant folding A quick synthetic test (w/o any hardware interaction) with a ridiculously large LUT size shows about 50% reduction in runtime on my HSW and BSW boxes. Slightly less with more reasonable LUT size but still easily measurable in tens of microseconds. v2: Include drm_color_mgmt.h in the .rst (Daniel) Cc: Daniel Vetter Signed-off-by: Ville Syrjälä Reviewed-by: Nicholas Kazlauskas Link: https://patchwork.freedesktop.org/patch/msgid/20191108135654.12907-1-ville.syrjala@linux.intel.com --- Documentation/gpu/drm-kms.rst | 3 +++ 1 file changed, 3 insertions(+) (limited to 'Documentation/gpu') diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst index 23a3c986ef6d..c68588ce4090 100644 --- a/Documentation/gpu/drm-kms.rst +++ b/Documentation/gpu/drm-kms.rst @@ -479,6 +479,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 ------------------- -- cgit v1.2.3 From 6f91f44dea701c7504dfe8af920f493ea0eed9cf Mon Sep 17 00:00:00 2001 From: Gabriela Bittencourt Date: Mon, 4 Nov 2019 13:27:05 -0300 Subject: drm/doc: Add VKMS module description and use to "Testing and Validation" Add a description on VKMS module and the cases in which it should be used. There's a brief explanation on how to set it and use it in a VM, along with an example of running an igt-test. Changes since V3: Rodrigo: - Change the log message to imperative - Fix some bad spelling/writing - Add a blank line before enumeration Changes since V2: Andre: - Avoid repetition of words in the same sentence; - Make the explanation on 'setting the kernel' shorter, eliminate the 'make menuconfig' command; - Add tab on enumeration to have one line per item; - Clarify from each machine igt-tests commands should be ran on. Reviewed-by: Rodrigo Siqueira Signed-off-by: Gabriela Bittencourt Signed-off-by: Rodrigo Siqueira Link: https://patchwork.freedesktop.org/patch/msgid/20191104162705.19735-1-gabrielabittencourt00@gmail.com --- Documentation/gpu/drm-uapi.rst | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) (limited to 'Documentation/gpu') diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst index 996f7354e05c..56fec6ed1ad8 100644 --- a/Documentation/gpu/drm-uapi.rst +++ b/Documentation/gpu/drm-uapi.rst @@ -257,6 +257,43 @@ core don't regress existing functionality. This test suite is called IGT and its code and instructions to build and run can be found in https://gitlab.freedesktop.org/drm/igt-gpu-tools/. +Using VKMS to test DRM API +-------------------------- + +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. + +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. + +It's possible to run the IGT-tests in a VM in two ways: + + 1. Use IGT inside a VM + 2. Use IGT from the host machine and write the results in a shared directory. + +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:: + + $ virtme-run --rwdir /path/for/shared_dir --kdir=path/for/kernel/directory --mods=auto + +Run the igt-tests in the guest machine, as example it's ran the 'kms_flip' +tests:: + + $ /path/for/igt-gpu-tools/scripts/run-tests.sh -p -s -t "kms_flip.*" -v + +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 ------------------- -- cgit v1.2.3 From 0380c6846a4be705b2d5c964b01ba1e5aaa3f5df Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Wed, 4 Dec 2019 11:00:11 +0100 Subject: drm/atomic: Update docs around locking and commit sequencing Both locking and especially sequencing of nonblocking commits have evolved a lot. The details are all there, but I noticed that the big picture and connections have fallen behind a bit. Apply polish. Motivated by some review discussions with Thierry. v2: Review from Thierry Reviewed-by: Thierry Reding Cc: Thierry Reding Signed-off-by: Daniel Vetter Link: https://patchwork.freedesktop.org/patch/msgid/20191204100011.859468-1-daniel.vetter@ffwll.ch --- Documentation/gpu/drm-kms.rst | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) (limited to 'Documentation/gpu') diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst index c68588ce4090..b9330343d1bc 100644 --- a/Documentation/gpu/drm-kms.rst +++ b/Documentation/gpu/drm-kms.rst @@ -260,7 +260,8 @@ Taken all together there's two consequences for the atomic design: 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`. - An atomic update is assembled and validated as an entirely free-standing pile of structures within the :c:type:`drm_atomic_state ` @@ -269,6 +270,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 `. 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. +:c:func:`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 `. + Read on in this chapter, and also in :ref:`drm_atomic_helper` for more detailed coverage of specific topics. -- cgit v1.2.3 From 6acc942c5eecad34a7623e01317f3d03d1e05462 Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Wed, 4 Dec 2019 11:19:33 +0100 Subject: drm/doc: Drop :c:func: markup Kernel sphinx has learned how to do that in commit d74b0d31dddeac2b44c715588d53d9a1e5b1158e Author: Jonathan Corbet Date: Thu Apr 25 07:55:07 2019 -0600 Docs: An initial automarkup extension for sphinx Unfortunately it hasn't learned that yet for structures, so we're stuck with the :c:type: noise for now still. Reviewed-by: Thierry Reding Cc: Jonathan Corbet Signed-off-by: Daniel Vetter Link: https://patchwork.freedesktop.org/patch/msgid/20191204101933.861169-1-daniel.vetter@ffwll.ch --- Documentation/gpu/drm-internals.rst | 4 +-- Documentation/gpu/drm-kms.rst | 7 ++-- Documentation/gpu/drm-mm.rst | 68 +++++++++++++++++-------------------- 3 files changed, 36 insertions(+), 43 deletions(-) (limited to 'Documentation/gpu') 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 ` 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 ` structure contains static information that describes the driver and features it diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst index b9330343d1bc..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 ` 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 `, 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() -`. +multiple times to different objects using drm_object_attach_property(). .. kernel-doc:: include/drm/drm_mode_object.h :internal: @@ -274,7 +273,7 @@ Locking of atomic state structures is internally using :c:type:`struct 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. -:c:func:`drm_atomic_get_crtc_state()`. Locking only protects the software data +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 `. diff --git a/Documentation/gpu/drm-mm.rst b/Documentation/gpu/drm-mm.rst index 59619296c84b..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 `. 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 ` 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 ` 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 ` 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 ` +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 -` 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. +` 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 ` 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 +` gem_vm_ops field with a pointer to VM operations. The VM operations is a :c:type:`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 ` 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 ` 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 -- cgit v1.2.3