drm/doc: Drop :c:func: markup

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

=========================

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.

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:

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.

: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 <drm_crtc_commit>`.

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

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

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

------------------

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

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.

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:

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

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