Linux GPU Driver Developer’s Guide¶

Driver Information¶

Device Instance and Driver Handling¶

A device instance for a drm driver is represented by struct drm_device. This is allocated with drm_dev_alloc(), usually from bus-specific ->:c:func:probe() callbacks implemented by the driver. The driver then needs to initialize all the various subsystems for the drm device like memory management, vblank handling, modesetting support and intial output configuration plus obviously initialize all the corresponding hardware bits. An important part of this is also calling drm_dev_set_unique() to set the userspace-visible unique name of this device instance. Finally when everything is up and running and ready for userspace the device instance can be published using drm_dev_register().

There is also deprecated support for initalizing device instances using bus-specific helpers and the ->:c:func:load() callback. But due to backwards-compatibility needs the device instance have to be published too early, which requires unpretty global locking to make safe and is therefore only support for existing drivers not yet converted to the new scheme.

When cleaning up a device instance everything needs to be done in reverse: First unpublish the device instance with drm_dev_unregister(). Then clean up any other resources allocated at device initialization and drop the driver’s reference to drm_device using drm_dev_unref().

Note that the lifetime rules for drm_device instance has still a lot of historical baggage. Hence use the reference counting provided by drm_dev_ref() and drm_dev_unref() only carefully.

Also note that embedding of drm_device is currently not (yet) supported (but it would be easy to add). Drivers can store driver-private data in the dev_priv field of drm_device.

void drm_put_dev(struct drm_device * dev)¶

Unregister and release a DRM device

Parameters

struct drm_device * dev

DRM device

Description

Called at module unload time or when a PCI device is unplugged.

Cleans up all DRM device, calling drm_lastclose().

Note

Use of this function is deprecated. It will eventually go away completely. Please use drm_dev_unregister() and drm_dev_unref() explicitly instead to make sure that the device isn’t userspace accessible any more while teardown is in progress, ensuring that userspace can’t access an inconsistent state.

int drm_dev_init(struct drm_device * dev, struct drm_driver * driver, struct device * parent)¶

Initialise new DRM device

Parameters

struct drm_device * dev

DRM device

struct drm_driver * driver

DRM driver

struct device * parent

Parent device object

Description

Initialize a new DRM device. No device registration is done. Call drm_dev_register() to advertice the device to user space and register it with other core subsystems. This should be done last in the device initialization sequence to make sure userspace can’t access an inconsistent state.

The initial ref-count of the object is 1. Use drm_dev_ref() and drm_dev_unref() to take and drop further ref-counts.

Note that for purely virtual devices parent can be NULL.

Drivers that do not want to allocate their own device struct embedding struct drm_device can call drm_dev_alloc() instead.

Return

0 on success, or error code on failure.

struct drm_device * drm_dev_alloc(struct drm_driver * driver, struct device * parent)¶

Allocate new DRM device

Parameters

struct drm_driver * driver

DRM driver to allocate device for

struct device * parent

Parent device object

Description

Allocate and initialize a new DRM device. No device registration is done. Call drm_dev_register() to advertice the device to user space and register it with other core subsystems. This should be done last in the device initialization sequence to make sure userspace can’t access an inconsistent state.

The initial ref-count of the object is 1. Use drm_dev_ref() and drm_dev_unref() to take and drop further ref-counts.

Note that for purely virtual devices parent can be NULL.

Drivers that wish to subclass or embed struct drm_device into their own struct should look at using drm_dev_init() instead.

Return

Pointer to new DRM device, or NULL if out of memory.

void drm_dev_ref(struct drm_device * dev)¶

Take reference of a DRM device

Parameters

struct drm_device * dev

device to take reference of or NULL

Description

This increases the ref-count of dev by one. You must already own a reference when calling this. Use drm_dev_unref() to drop this reference again.

This function never fails. However, this function does not provide any guarantee whether the device is alive or running. It only provides a reference to the object and the memory associated with it.

void drm_dev_unref(struct drm_device * dev)¶

Drop reference of a DRM device

Parameters

struct drm_device * dev

device to drop reference of or NULL

Description

This decreases the ref-count of dev by one. The device is destroyed if the ref-count drops to zero.

int drm_dev_register(struct drm_device * dev, unsigned long flags)¶

Register DRM device

Parameters

struct drm_device * dev

Device to register

unsigned long flags

Flags passed to the driver’s .:c:func:load() function

Description

Register the DRM device dev with the system, advertise device to user-space and start normal device operation. dev must be allocated via drm_dev_alloc() previously.

Never call this twice on any device!

NOTE

To ensure backward compatibility with existing drivers method this function calls the ->:c:func:load() method after registering the device nodes, creating race conditions. Usage of the ->:c:func:load() methods is therefore deprecated, drivers must perform all initialization before calling drm_dev_register().

Return

0 on success, negative error code on failure.

void drm_dev_unregister(struct drm_device * dev)¶

Unregister DRM device

Parameters

struct drm_device * dev

Device to unregister

Description

Unregister the DRM device from the system. This does the reverse of drm_dev_register() but does not deallocate the device. The caller must call drm_dev_unref() to drop their final reference.

This should be called first in the device teardown code to make sure userspace can’t access the device instance any more.

int drm_dev_set_unique(struct drm_device * dev, const char * name)¶

Set the unique name of a DRM device

Parameters

struct drm_device * dev

device of which to set the unique name

const char * name

unique name

Description

Sets the unique name of a DRM device using the specified string. Drivers can use this at driver probe time if the unique name of the devices they drive is static.

Return

0 on success or a negative error code on failure.

Driver Load¶

Bus-specific Device Registration and PCI Support¶

A number of functions are provided to help with device registration. The functions deal with PCI and platform devices respectively and are only provided for historical reasons. These are all deprecated and shouldn’t be used in new drivers. Besides that there’s a few helpers for pci drivers.

drm_dma_handle_t * drm_pci_alloc(struct drm_device * dev, size_t size, size_t align)¶

Allocate a PCI consistent memory block, for DMA.

Parameters

struct drm_device * dev

DRM device

size_t size

size of block to allocate

size_t align

alignment of block

Return

A handle to the allocated memory block on success or NULL on failure.

void drm_pci_free(struct drm_device * dev, drm_dma_handle_t * dmah)¶

Free a PCI consistent memory block

Parameters

struct drm_device * dev

DRM device

drm_dma_handle_t * dmah

handle to memory block

int drm_get_pci_dev(struct pci_dev * pdev, const struct pci_device_id * ent, struct drm_driver * driver)¶

Register a PCI device with the DRM subsystem

Parameters

struct pci_dev * pdev

PCI device

const struct pci_device_id * ent

entry from the PCI ID table that matches pdev

struct drm_driver * driver

DRM device driver

Description

Attempt to gets inter module “drm” information. If we are first then register the character device and inter module information. Try and register, if we fail to register, backout previous work.

NOTE

This function is deprecated, please use drm_dev_alloc() and drm_dev_register() instead and remove your ->:c:func:load() callback.

Return

0 on success or a negative error code on failure.

int drm_pci_init(struct drm_driver * driver, struct pci_driver * pdriver)¶

Register matching PCI devices with the DRM subsystem

Parameters

struct drm_driver * driver

DRM device driver

struct pci_driver * pdriver

PCI device driver

Description

Initializes a drm_device structures, registering the stubs and initializing the AGP device.

NOTE

This function is deprecated. Modern modesetting drm drivers should use pci_register_driver() directly, this function only provides shadow-binding support for old legacy drivers on top of that core pci function.

Return

0 on success or a negative error code on failure.

void drm_pci_exit(struct drm_driver * driver, struct pci_driver * pdriver)¶

Unregister matching PCI devices from the DRM subsystem

Parameters

struct drm_driver * driver

DRM device driver

struct pci_driver * pdriver

PCI device driver

Description

Unregisters one or more devices matched by a PCI driver from the DRM subsystem.

NOTE

This function is deprecated. Modern modesetting drm drivers should use pci_unregister_driver() directly, this function only provides shadow-binding support for old legacy drivers on top of that core pci function.

int drm_platform_init(struct drm_driver * driver, struct platform_device * platform_device)¶

Register a platform device with the DRM subsystem

Parameters

struct drm_driver * driver

DRM device driver

struct platform_device * platform_device

platform device to register

Description

Registers the specified DRM device driver and platform device with the DRM subsystem, initializing a drm_device structure and calling the driver’s .:c:func:load() function.

NOTE

This function is deprecated, please use drm_dev_alloc() and drm_dev_register() instead and remove your ->:c:func:load() callback.

Return

0 on success or a negative error code on failure.

The Translation Table Manager (TTM)¶

TTM design background and information belongs here.

struct ttm_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 *);
};

The Graphics Execution Manager (GEM)¶

The GEM design approach has resulted in a memory manager that doesn’t provide full coverage of all (or even all common) use cases in its userspace or kernel API. GEM exposes a set of standard memory-related operations to userspace and a set of helper functions to drivers, and let drivers implement hardware-specific operations with their own private API.

The GEM userspace API is described in the GEM - the Graphics Execution Manager article on LWN. While slightly outdated, the document provides a good overview of the GEM API principles. Buffer allocation and read and write operations, described as part of the common GEM API, are currently implemented using driver-specific ioctls.

GEM is data-agnostic. It manages abstract buffer objects without knowing what individual buffers contain. APIs that require knowledge of buffer contents or purpose, such as buffer allocation or synchronization primitives, are thus outside of the scope of GEM and must be implemented using driver-specific ioctls.

On a fundamental level, GEM involves several operations:

• Memory allocation and freeing
• Command execution
• Aperture management at command execution time

Buffer object allocation is relatively straightforward and largely provided by Linux’s shmem layer, which provides memory to back each object.

Device-specific operations, such as command execution, pinning, buffer read & write, mapping, and domain ownership transfers are left to driver-specific ioctls.

GEM Function Reference¶

int drm_gem_object_init(struct drm_device * dev, struct drm_gem_object * obj, size_t size)¶

initialize an allocated shmem-backed GEM object

Parameters

struct drm_device * dev

drm_device the object should be initialized for

struct drm_gem_object * obj

drm_gem_object to initialize

size_t size

object size

Description

Initialize an already allocated GEM object of the specified size with shmfs backing store.

void drm_gem_private_object_init(struct drm_device * dev, struct drm_gem_object * obj, size_t size)¶

initialize an allocated private GEM object

Parameters

struct drm_device * dev

drm_device the object should be initialized for

struct drm_gem_object * obj

drm_gem_object to initialize

size_t size

object size

Description

Initialize an already allocated GEM object of the specified size with no GEM provided backing store. Instead the caller is responsible for backing the object and handling it.

int drm_gem_handle_delete(struct drm_file * filp, u32 handle)¶

deletes the given file-private handle

Parameters

struct drm_file * filp

drm file-private structure to use for the handle look up

u32 handle

userspace handle to delete

Description

Removes the GEM handle from the filp lookup table which has been added with drm_gem_handle_create(). If this is the last handle also cleans up linked resources like GEM names.

int drm_gem_dumb_destroy(struct drm_file * file, struct drm_device * dev, uint32_t handle)¶

dumb fb callback helper for gem based drivers

Parameters

struct drm_file * file

drm file-private structure to remove the dumb handle from

struct drm_device * dev

corresponding drm_device

uint32_t handle

the dumb handle to remove

Description

This implements the ->dumb_destroy kms driver callback for drivers which use gem to manage their backing storage.

int drm_gem_handle_create(struct drm_file * file_priv, struct drm_gem_object * obj, u32 * handlep)¶

create a gem handle for an object

Parameters

struct drm_file * file_priv

drm file-private structure to register the handle for

struct drm_gem_object * obj

object to register

u32 * handlep

pionter to return the created handle to the caller

Description

Create a handle for this object. This adds a handle reference to the object, which includes a regular reference count. Callers will likely want to dereference the object afterwards.

void drm_gem_free_mmap_offset(struct drm_gem_object * obj)¶

release a fake mmap offset for an object

Parameters

struct drm_gem_object * obj

obj in question

Description

This routine frees fake offsets allocated by drm_gem_create_mmap_offset().

Note that drm_gem_object_release() already calls this function, so drivers don’t have to take care of releasing the mmap offset themselves when freeing the GEM object.

int drm_gem_create_mmap_offset_size(struct drm_gem_object * obj, size_t size)¶

create a fake mmap offset for an object

Parameters

struct drm_gem_object * obj

obj in question

size_t size

the virtual size

Description

GEM memory mapping works by handing back to userspace a fake mmap offset it can use in a subsequent mmap(2) call. The DRM core code then looks up the object based on the offset and sets up the various memory mapping structures.

This routine allocates and attaches a fake offset for obj, in cases where the virtual size differs from the physical size (ie. obj->size). Otherwise just use drm_gem_create_mmap_offset().

This function is idempotent and handles an already allocated mmap offset transparently. Drivers do not need to check for this case.

int drm_gem_create_mmap_offset(struct drm_gem_object * obj)¶

create a fake mmap offset for an object

Parameters

struct drm_gem_object * obj

obj in question

Description

GEM memory mapping works by handing back to userspace a fake mmap offset it can use in a subsequent mmap(2) call. The DRM core code then looks up the object based on the offset and sets up the various memory mapping structures.

This routine allocates and attaches a fake offset for obj.

Drivers can call drm_gem_free_mmap_offset() before freeing obj to release the fake offset again.

struct page ** drm_gem_get_pages(struct drm_gem_object * obj)¶

helper to allocate backing pages for a GEM object from shmem

Parameters

struct drm_gem_object * obj

obj in question

Description

This reads the page-array of the shmem-backing storage of the given gem object. An array of pages is returned. If a page is not allocated or swapped-out, this will allocate/swap-in the required pages. Note that the whole object is covered by the page-array and pinned in memory.

Use drm_gem_put_pages() to release the array and unpin all pages.

This uses the GFP-mask set on the shmem-mapping (see mapping_set_gfp_mask()). If you require other GFP-masks, you have to do those allocations yourself.

Note that you are not allowed to change gfp-zones during runtime. That is, shmem_read_mapping_page_gfp() must be called with the same gfp_zone(gfp) as set during initialization. If you have special zone constraints, set them after drm_gem_init_object() via mapping_set_gfp_mask(). shmem-core takes care to keep pages in the required zone during swap-in.

void drm_gem_put_pages(struct drm_gem_object * obj, struct page ** pages, bool dirty, bool accessed)¶

helper to free backing pages for a GEM object

Parameters

struct drm_gem_object * obj

obj in question

struct page ** pages

pages to free

bool dirty

if true, pages will be marked as dirty

bool accessed

if true, the pages will be marked as accessed

struct drm_gem_object * drm_gem_object_lookup(struct drm_file * filp, u32 handle)¶

look up a GEM object from it’s handle

Parameters

struct drm_file * filp

DRM file private date

u32 handle

userspace handle

Return

A reference to the object named by the handle if such exists on filp, NULL otherwise.

void drm_gem_object_release(struct drm_gem_object * obj)¶

release GEM buffer object resources

Parameters

struct drm_gem_object * obj

GEM buffer object

Description

This releases any structures and resources used by obj and is the invers of drm_gem_object_init().

void drm_gem_object_free(struct kref * kref)¶

free a GEM object

Parameters

struct kref * kref

kref of the object to free

Description

Called after the last reference to the object has been lost. Must be called holding drm_device->struct_mutex.

Frees the object

void drm_gem_object_unreference_unlocked(struct drm_gem_object * obj)¶

release a GEM BO reference

Parameters

struct drm_gem_object * obj

GEM buffer object

Description

This releases a reference to obj. Callers must not hold the dev->struct_mutex lock when calling this function.

See also __drm_gem_object_unreference().

void drm_gem_object_unreference(struct drm_gem_object * obj)¶

release a GEM BO reference

Parameters

struct drm_gem_object * obj

GEM buffer object

Description

This releases a reference to obj. Callers must hold the dev->struct_mutex lock when calling this function, even when the driver doesn’t use dev->struct_mutex for anything.

For drivers not encumbered with legacy locking use drm_gem_object_unreference_unlocked() instead.

void drm_gem_vm_open(struct vm_area_struct * vma)¶

vma->ops->open implementation for GEM

Parameters

struct vm_area_struct * vma

VM area structure

Description

This function implements the #vm_operations_struct open() callback for GEM drivers. This must be used together with drm_gem_vm_close().

void drm_gem_vm_close(struct vm_area_struct * vma)¶

vma->ops->close implementation for GEM

Parameters

struct vm_area_struct * vma

VM area structure

Description

This function implements the #vm_operations_struct close() callback for GEM drivers. This must be used together with drm_gem_vm_open().

int drm_gem_mmap_obj(struct drm_gem_object * obj, unsigned long obj_size, struct vm_area_struct * vma)¶

memory map a GEM object

Parameters

struct drm_gem_object * obj

the GEM object to map

unsigned long obj_size

the object size to be mapped, in bytes

struct vm_area_struct * vma

VMA for the area to be mapped

Description

Set up the VMA to prepare mapping of the GEM object using the gem_vm_ops provided by the driver. Depending on their requirements, drivers can either provide a fault handler in their gem_vm_ops (in which case any accesses to the object will be trapped, to perform migration, GTT binding, surface register allocation, or performance monitoring), or mmap the buffer memory synchronously after calling drm_gem_mmap_obj.

This function is mainly intended to implement the DMABUF mmap operation, when the GEM object is not looked up based on its fake offset. To implement the DRM mmap operation, drivers should use the drm_gem_mmap() function.

drm_gem_mmap_obj() assumes the user is granted access to the buffer while drm_gem_mmap() prevents unprivileged users from mapping random objects. So callers must verify access restrictions before calling this helper.

Return 0 or success or -EINVAL if the object size is smaller than the VMA size, or if no gem_vm_ops are provided.

int drm_gem_mmap(struct file * filp, struct vm_area_struct * vma)¶

memory map routine for GEM objects

Parameters

struct file * filp

DRM file pointer

struct vm_area_struct * vma

VMA for the area to be mapped

Description

If a driver supports GEM object mapping, mmap calls on the DRM file descriptor will end up here.

Look up the GEM object based on the offset passed in (vma->vm_pgoff will contain the fake offset we created when the GTT map ioctl was called on the object) and map it with a call to drm_gem_mmap_obj().

If the caller is not granted access to the buffer object, the mmap will fail with EACCES. Please see the vma manager for more information.

struct drm_gem_object¶

GEM buffer object

Definition

struct drm_gem_object {
  struct kref refcount;
  unsigned handle_count;
  struct drm_device * dev;
  struct file * filp;
  struct drm_vma_offset_node vma_node;
  size_t size;
  int name;
  uint32_t read_domains;
  uint32_t write_domain;
  uint32_t pending_read_domains;
  uint32_t pending_write_domain;
  struct dma_buf * dma_buf;
  struct dma_buf_attachment * import_attach;
};

Members

struct kref refcount

Reference count of this object

Please use drm_gem_object_reference() to acquire and drm_gem_object_unreference() or drm_gem_object_unreference_unlocked() to release a reference to a GEM buffer object.

unsigned handle_count

This is the GEM file_priv handle count of this object.

Each handle also holds a reference. Note that when the handle_count drops to 0 any global names (e.g. the id in the flink namespace) will be cleared.

Protected by dev->object_name_lock.

struct drm_device * dev

DRM dev this object belongs to.

struct file * filp

SHMEM file node used as backing storage for swappable buffer objects. GEM also supports driver private objects with driver-specific backing storage (contiguous CMA memory, special reserved blocks). In this case filp is NULL.

struct drm_vma_offset_node vma_node

Mapping info for this object to support mmap. Drivers are supposed to allocate the mmap offset using drm_gem_create_mmap_offset(). The offset itself can be retrieved using drm_vma_node_offset_addr().

Memory mapping itself is handled by drm_gem_mmap(), which also checks that userspace is allowed to access the object.

size_t size

Size of the object, in bytes. Immutable over the object’s lifetime.

int name

Global name for this object, starts at 1. 0 means unnamed. Access is covered by dev->object_name_lock. This is used by the GEM_FLINK and GEM_OPEN ioctls.

uint32_t read_domains

Read memory domains. These monitor which caches contain read/write data related to the object. When transitioning from one set of domains to another, the driver is called to ensure that caches are suitably flushed and invalidated.

uint32_t write_domain

Corresponding unique write memory domain.

uint32_t pending_read_domains

While validating an exec operation, the new read/write domain values are computed here. They will be transferred to the above values at the point that any cache flushing occurs

uint32_t pending_write_domain

Write domain similar to pending_read_domains.

struct dma_buf * dma_buf

dma-buf associated with this GEM object.

Pointer to the dma-buf associated with this gem object (either through importing or exporting). We break the resulting reference loop when the last gem handle for this object is released.

Protected by obj->object_name_lock.

struct dma_buf_attachment * import_attach

dma-buf attachment backing this object.

Any foreign dma_buf imported as a gem object has this set to the attachment point for the device. This is invariant over the lifetime of a gem object.

The driver’s ->gem_free_object callback is responsible for cleaning up the dma_buf attachment and references acquired at import time.

Note that the drm gem/prime core does not depend upon drivers setting this field any more. So for drivers where this doesn’t make sense (e.g. virtual devices or a displaylink behind an usb bus) they can simply leave it as NULL.

Description

This structure defines the generic parts for GEM buffer objects, which are mostly around handling mmap and userspace handles.

Buffer objects are often abbreviated to BO.

void drm_gem_object_reference(struct drm_gem_object * obj)¶

acquire a GEM BO reference

Parameters

struct drm_gem_object * obj

GEM buffer object

Description

This acquires additional reference to obj. It is illegal to call this without already holding a reference. No locks required.

void __drm_gem_object_unreference(struct drm_gem_object * obj)¶

raw function to release a GEM BO reference

Parameters

struct drm_gem_object * obj

GEM buffer object

Description

This function is meant to be used by drivers which are not encumbered with dev->struct_mutex legacy locking and which are using the gem_free_object_unlocked callback. It avoids all the locking checks and locking overhead of drm_gem_object_unreference() and drm_gem_object_unreference_unlocked().

Drivers should never call this directly in their code. Instead they should wrap it up into a driver_gem_object_unreference(struct driver_gem_object *obj) wrapper function, and use that. Shared code should never call this, to avoid breaking drivers by accident which still depend upon dev->struct_mutex locking.

VMA Offset Manager¶

The vma-manager is responsible to map arbitrary driver-dependent memory regions into the linear user address-space. It provides offsets to the caller which can then be used on the address_space of the drm-device. It takes care to not overlap regions, size them appropriately and to not confuse mm-core by inconsistent fake vm_pgoff fields. Drivers shouldn’t use this for object placement in VMEM. This manager should only be used to manage mappings into linear user-space VMs.

We use drm_mm as backend to manage object allocations. But it is highly optimized for alloc/free calls, not lookups. Hence, we use an rb-tree to speed up offset lookups.

You must not use multiple offset managers on a single address_space. Otherwise, mm-core will be unable to tear down memory mappings as the VM will no longer be linear.

This offset manager works on page-based addresses. That is, every argument and return code (with the exception of drm_vma_node_offset_addr()) is given in number of pages, not number of bytes. That means, object sizes and offsets must always be page-aligned (as usual). If you want to get a valid byte-based user-space address for a given offset, please see drm_vma_node_offset_addr().

Additionally to offset management, the vma offset manager also handles access management. For every open-file context that is allowed to access a given node, you must call drm_vma_node_allow(). Otherwise, an mmap() call on this open-file with the offset of the node will fail with -EACCES. To revoke access again, use drm_vma_node_revoke(). However, the caller is responsible for destroying already existing mappings, if required.

void drm_vma_offset_manager_init(struct drm_vma_offset_manager * mgr, unsigned long page_offset, unsigned long size)¶

Initialize new offset-manager

Parameters

struct drm_vma_offset_manager * mgr

Manager object

unsigned long page_offset

Offset of available memory area (page-based)

unsigned long size

Size of available address space range (page-based)

Description

Initialize a new offset-manager. The offset and area size available for the manager are given as page_offset and size. Both are interpreted as page-numbers, not bytes.

Adding/removing nodes from the manager is locked internally and protected against concurrent access. However, node allocation and destruction is left for the caller. While calling into the vma-manager, a given node must always be guaranteed to be referenced.

void drm_vma_offset_manager_destroy(struct drm_vma_offset_manager * mgr)¶

Destroy offset manager

Parameters

struct drm_vma_offset_manager * mgr

Manager object

Description

Destroy an object manager which was previously created via drm_vma_offset_manager_init(). The caller must remove all allocated nodes before destroying the manager. Otherwise, drm_mm will refuse to free the requested resources.

The manager must not be accessed after this function is called.

struct drm_vma_offset_node * drm_vma_offset_lookup_locked(struct drm_vma_offset_manager * mgr, unsigned long start, unsigned long pages)¶

Find node in offset space

Parameters

struct drm_vma_offset_manager * mgr

Manager object

unsigned long start

Start address for object (page-based)

unsigned long pages

Size of object (page-based)

Description

Find a node given a start address and object size. This returns the _best_ match for the given node. That is, start may point somewhere into a valid region and the given node will be returned, as long as the node spans the whole requested area (given the size in number of pages as pages).

Note that before lookup the vma offset manager lookup lock must be acquired with drm_vma_offset_lock_lookup(). See there for an example. This can then be used to implement weakly referenced lookups using kref_get_unless_zero().

Example

drm_vma_offset_lock_lookup(mgr);
node = drm_vma_offset_lookup_locked(mgr);
if (node)
    kref_get_unless_zero(container_of(node, sth, entr));
drm_vma_offset_unlock_lookup(mgr);

Return

Returns NULL if no suitable node can be found. Otherwise, the best match is returned. It’s the caller’s responsibility to make sure the node doesn’t get destroyed before the caller can access it.

int drm_vma_offset_add(struct drm_vma_offset_manager * mgr, struct drm_vma_offset_node * node, unsigned long pages)¶

Add offset node to manager

Parameters

struct drm_vma_offset_manager * mgr

Manager object

struct drm_vma_offset_node * node

Node to be added

unsigned long pages

Allocation size visible to user-space (in number of pages)

Description

Add a node to the offset-manager. If the node was already added, this does nothing and return 0. pages is the size of the object given in number of pages. After this call succeeds, you can access the offset of the node until it is removed again.

If this call fails, it is safe to retry the operation or call drm_vma_offset_remove(), anyway. However, no cleanup is required in that case.

pages is not required to be the same size as the underlying memory object that you want to map. It only limits the size that user-space can map into their address space.

Return

0 on success, negative error code on failure.

void drm_vma_offset_remove(struct drm_vma_offset_manager * mgr, struct drm_vma_offset_node * node)¶

Remove offset node from manager

Parameters

struct drm_vma_offset_manager * mgr

Manager object

struct drm_vma_offset_node * node

Node to be removed

Description

Remove a node from the offset manager. If the node wasn’t added before, this does nothing. After this call returns, the offset and size will be 0 until a new offset is allocated via drm_vma_offset_add() again. Helper functions like drm_vma_node_start() and drm_vma_node_offset_addr() will return 0 if no offset is allocated.

int drm_vma_node_allow(struct drm_vma_offset_node * node, struct file * filp)¶

Add open-file to list of allowed users

Parameters

struct drm_vma_offset_node * node

Node to modify

struct file * filp

Open file to add

Description

Add filp to the list of allowed open-files for this node. If filp is already on this list, the ref-count is incremented.

The list of allowed-users is preserved across drm_vma_offset_add() and drm_vma_offset_remove() calls. You may even call it if the node is currently not added to any offset-manager.

You must remove all open-files the same number of times as you added them before destroying the node. Otherwise, you will leak memory.

This is locked against concurrent access internally.

Return

0 on success, negative error code on internal failure (out-of-mem)

void drm_vma_node_revoke(struct drm_vma_offset_node * node, struct file * filp)¶

Remove open-file from list of allowed users

Parameters

struct drm_vma_offset_node * node

Node to modify

struct file * filp

Open file to remove

Description

Decrement the ref-count of filp in the list of allowed open-files on node. If the ref-count drops to zero, remove filp from the list. You must call this once for every drm_vma_node_allow() on filp.

This is locked against concurrent access internally.

If filp is not on the list, nothing is done.

bool drm_vma_node_is_allowed(struct drm_vma_offset_node * node, struct file * filp)¶

Check whether an open-file is granted access

Parameters

struct drm_vma_offset_node * node

Node to check

struct file * filp

Open-file to check for

Description

Search the list in node whether filp is currently on the list of allowed open-files (see drm_vma_node_allow()).

This is locked against concurrent access internally.

Return

true iff filp is on the list

struct drm_vma_offset_node * drm_vma_offset_exact_lookup_locked(struct drm_vma_offset_manager * mgr, unsigned long start, unsigned long pages)¶

Look up node by exact address

Parameters

struct drm_vma_offset_manager * mgr

Manager object

unsigned long start

Start address (page-based, not byte-based)

unsigned long pages

Size of object (page-based)

Description

Same as drm_vma_offset_lookup_locked() but does not allow any offset into the node. It only returns the exact object with the given start address.

Return

Node at exact start address start.

void drm_vma_offset_lock_lookup(struct drm_vma_offset_manager * mgr)¶

Lock lookup for extended private use

Parameters

struct drm_vma_offset_manager * mgr

Manager object

Description

Lock VMA manager for extended lookups. Only locked VMA function calls are allowed while holding this lock. All other contexts are blocked from VMA until the lock is released via drm_vma_offset_unlock_lookup().

Use this if you need to take a reference to the objects returned by drm_vma_offset_lookup_locked() before releasing this lock again.

This lock must not be used for anything else than extended lookups. You must not call any other VMA helpers while holding this lock.

Note

You’re in atomic-context while holding this lock!

void drm_vma_offset_unlock_lookup(struct drm_vma_offset_manager * mgr)¶

Unlock lookup for extended private use

Parameters

struct drm_vma_offset_manager * mgr

Manager object

Description

Release lookup-lock. See drm_vma_offset_lock_lookup() for more information.

void drm_vma_node_reset(struct drm_vma_offset_node * node)¶

Initialize or reset node object

Parameters

struct drm_vma_offset_node * node

Node to initialize or reset

Description

Reset a node to its initial state. This must be called before using it with any VMA offset manager.

This must not be called on an already allocated node, or you will leak memory.

unsigned long drm_vma_node_start(struct drm_vma_offset_node * node)¶

Return start address for page-based addressing

Parameters

struct drm_vma_offset_node * node

Node to inspect

Description

Return the start address of the given node. This can be used as offset into the linear VM space that is provided by the VMA offset manager. Note that this can only be used for page-based addressing. If you need a proper offset for user-space mappings, you must apply “<< PAGE_SHIFT” or use the drm_vma_node_offset_addr() helper instead.

Return

Start address of node for page-based addressing. 0 if the node does not have an offset allocated.

unsigned long drm_vma_node_size(struct drm_vma_offset_node * node)¶

Return size (page-based)

Parameters

struct drm_vma_offset_node * node

Node to inspect

Description

Return the size as number of pages for the given node. This is the same size that was passed to drm_vma_offset_add(). If no offset is allocated for the node, this is 0.

Return

Size of node as number of pages. 0 if the node does not have an offset allocated.

__u64 drm_vma_node_offset_addr(struct drm_vma_offset_node * node)¶

Return sanitized offset for user-space mmaps

Parameters

struct drm_vma_offset_node * node

Linked offset node

Description

Same as drm_vma_node_start() but returns the address as a valid offset that can be used for user-space mappings during mmap(). This must not be called on unlinked nodes.

Return

Offset of node for byte-based addressing. 0 if the node does not have an object allocated.

void drm_vma_node_unmap(struct drm_vma_offset_node * node, struct address_space * file_mapping)¶

Unmap offset node

Parameters

struct drm_vma_offset_node * node

Offset node

struct address_space * file_mapping

Address space to unmap node from

Description

Unmap all userspace mappings for a given offset node. The mappings must be associated with the file_mapping address-space. If no offset exists nothing is done.

This call is unlocked. The caller must guarantee that drm_vma_offset_remove() is not called on this node concurrently.

int drm_vma_node_verify_access(struct drm_vma_offset_node * node, struct file * filp)¶

Access verification helper for TTM

Parameters

struct drm_vma_offset_node * node

Offset node

struct file * filp

Open-file

Description

This checks whether filp is granted access to node. It is the same as drm_vma_node_is_allowed() but suitable as drop-in helper for TTM verify_access() callbacks.

Return

0 if access is granted, -EACCES otherwise.

PRIME Buffer Sharing¶

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.

PRIME Function References¶

void drm_gem_dmabuf_release(struct dma_buf * dma_buf)¶

dma_buf release implementation for GEM

Parameters

struct dma_buf * dma_buf

buffer to be released

Description

Generic release function for dma_bufs exported as PRIME buffers. GEM drivers must use this in their dma_buf ops structure as the release callback.

struct dma_buf * drm_gem_prime_export(struct drm_device * dev, struct drm_gem_object * obj, int flags)¶

helper library implementation of the export callback

Parameters

struct drm_device * dev

drm_device to export from

struct drm_gem_object * obj

GEM object to export

int flags

flags like DRM_CLOEXEC and DRM_RDWR

Description

This is the implementation of the gem_prime_export functions for GEM drivers using the PRIME helpers.

int drm_gem_prime_handle_to_fd(struct drm_device * dev, struct drm_file * file_priv, uint32_t handle, uint32_t flags, int * prime_fd)¶

PRIME export function for GEM drivers

Parameters

struct drm_device * dev

dev to export the buffer from

struct drm_file * file_priv

drm file-private structure

uint32_t handle

buffer handle to export

uint32_t flags

flags like DRM_CLOEXEC

int * prime_fd

pointer to storage for the fd id of the create dma-buf

Description

This is the PRIME export function which must be used mandatorily by GEM drivers to ensure correct lifetime management of the underlying GEM object. The actual exporting from GEM object to a dma-buf is done through the gem_prime_export driver callback.

struct drm_gem_object * drm_gem_prime_import(struct drm_device * dev, struct dma_buf * dma_buf)¶

helper library implementation of the import callback

Parameters

struct drm_device * dev

drm_device to import into

struct dma_buf * dma_buf

dma-buf object to import

Description

This is the implementation of the gem_prime_import functions for GEM drivers using the PRIME helpers.

int drm_gem_prime_fd_to_handle(struct drm_device * dev, struct drm_file * file_priv, int prime_fd, uint32_t * handle)¶

PRIME import function for GEM drivers

Parameters

struct drm_device * dev

dev to export the buffer from

struct drm_file * file_priv

drm file-private structure

int prime_fd

fd id of the dma-buf which should be imported

uint32_t * handle

pointer to storage for the handle of the imported buffer object

Description

This is the PRIME import function which must be used mandatorily by GEM drivers to ensure correct lifetime management of the underlying GEM object. The actual importing of GEM object from the dma-buf is done through the gem_import_export driver callback.

struct sg_table * drm_prime_pages_to_sg(struct page ** pages, unsigned int nr_pages)¶

converts a page array into an sg list

Parameters

struct page ** pages

pointer to the array of page pointers to convert

unsigned int nr_pages

length of the page vector

Description

This helper creates an sg table object from a set of pages the driver is responsible for mapping the pages into the importers address space for use with dma_buf itself.

int drm_prime_sg_to_page_addr_arrays(struct sg_table * sgt, struct page ** pages, dma_addr_t * addrs, int max_pages)¶

convert an sg table into a page array

Parameters

struct sg_table * sgt

scatter-gather table to convert

struct page ** pages

array of page pointers to store the page array in

dma_addr_t * addrs

optional array to store the dma bus address of each page

int max_pages

size of both the passed-in arrays

Description

Exports an sg table into an array of pages and addresses. This is currently required by the TTM driver in order to do correct fault handling.

void drm_prime_gem_destroy(struct drm_gem_object * obj, struct sg_table * sg)¶

helper to clean up a PRIME-imported GEM object

Parameters

struct drm_gem_object * obj

GEM object which was created from a dma-buf

struct sg_table * sg

the sg-table which was pinned at import time

Description

This is the cleanup functions which GEM drivers need to call when they use drm_gem_prime_import to import dma-bufs.

DRM MM Range Allocator¶

DRM MM Range Allocator Function References¶

int drm_mm_reserve_node(struct drm_mm * mm, struct drm_mm_node * node)¶

insert an pre-initialized node

Parameters

struct drm_mm * mm

drm_mm allocator to insert node into

struct drm_mm_node * node

drm_mm_node to insert

Description

This functions inserts an already set-up drm_mm_node into the allocator, meaning that start, size and color must be set by the caller. This is useful to initialize the allocator with preallocated objects which must be set-up before the range allocator can be set-up, e.g. when taking over a firmware framebuffer.

Return

0 on success, -ENOSPC if there’s no hole where node is.

int drm_mm_insert_node_generic(struct drm_mm * mm, struct drm_mm_node * node, u64 size, unsigned alignment, unsigned long color, enum drm_mm_search_flags sflags, enum drm_mm_allocator_flags aflags)¶

search for space and insert node

Parameters

struct drm_mm * mm

drm_mm to allocate from

struct drm_mm_node * node

preallocate node to insert

u64 size

size of the allocation

unsigned alignment

alignment of the allocation

unsigned long color

opaque tag value to use for this node

enum drm_mm_search_flags sflags

flags to fine-tune the allocation search

enum drm_mm_allocator_flags aflags

flags to fine-tune the allocation behavior

Description

The preallocated node must be cleared to 0.

Return

0 on success, -ENOSPC if there’s no suitable hole.

int drm_mm_insert_node_in_range_generic(struct drm_mm * mm, struct drm_mm_node * node, u64 size, unsigned alignment, unsigned long color, u64 start, u64 end, enum drm_mm_search_flags sflags, enum drm_mm_allocator_flags aflags)¶

ranged search for space and insert node

Parameters

struct drm_mm * mm

drm_mm to allocate from

struct drm_mm_node * node

preallocate node to insert

u64 size

size of the allocation

unsigned alignment

alignment of the allocation

unsigned long color

opaque tag value to use for this node

u64 start

start of the allowed range for this node

u64 end

end of the allowed range for this node

enum drm_mm_search_flags sflags

flags to fine-tune the allocation search

enum drm_mm_allocator_flags aflags

flags to fine-tune the allocation behavior

Description

The preallocated node must be cleared to 0.

Return

0 on success, -ENOSPC if there’s no suitable hole.

void drm_mm_remove_node(struct drm_mm_node * node)¶

Remove a memory node from the allocator.

Parameters

struct drm_mm_node * node

drm_mm_node to remove

Description

This just removes a node from its drm_mm allocator. The node does not need to be cleared again before it can be re-inserted into this or any other drm_mm allocator. It is a bug to call this function on a un-allocated node.

void drm_mm_replace_node(struct drm_mm_node * old, struct drm_mm_node * new)¶

move an allocation from old to new

Parameters

struct drm_mm_node * old

drm_mm_node to remove from the allocator

struct drm_mm_node * new

drm_mm_node which should inherit old‘s allocation

Description

This is useful for when drivers embed the drm_mm_node structure and hence can’t move allocations by reassigning pointers. It’s a combination of remove and insert with the guarantee that the allocation start will match.

void drm_mm_init_scan(struct drm_mm * mm, u64 size, unsigned alignment, unsigned long color)¶

initialize lru scanning

Parameters

struct drm_mm * mm

drm_mm to scan

u64 size

size of the allocation

unsigned alignment

alignment of the allocation

unsigned long color

opaque tag value to use for the allocation

Description

This simply sets up the scanning routines with the parameters for the desired hole. Note that there’s no need to specify allocation flags, since they only change the place a node is allocated from within a suitable hole.

Warning: As long as the scan list is non-empty, no other operations than adding/removing nodes to/from the scan list are allowed.

void drm_mm_init_scan_with_range(struct drm_mm * mm, u64 size, unsigned alignment, unsigned long color, u64 start, u64 end)¶

initialize range-restricted lru scanning

Parameters

struct drm_mm * mm

drm_mm to scan

u64 size

size of the allocation

unsigned alignment

alignment of the allocation

unsigned long color

opaque tag value to use for the allocation

u64 start

start of the allowed range for the allocation

u64 end

end of the allowed range for the allocation

Description

This simply sets up the scanning routines with the parameters for the desired hole. Note that there’s no need to specify allocation flags, since they only change the place a node is allocated from within a suitable hole.

Warning: As long as the scan list is non-empty, no other operations than adding/removing nodes to/from the scan list are allowed.

bool drm_mm_scan_add_block(struct drm_mm_node * node)¶

add a node to the scan list

Parameters

struct drm_mm_node * node

drm_mm_node to add

Description

Add a node to the scan list that might be freed to make space for the desired hole.

Return

True if a hole has been found, false otherwise.

bool drm_mm_scan_remove_block(struct drm_mm_node * node)¶

remove a node from the scan list

Parameters

struct drm_mm_node * node

drm_mm_node to remove

Description

Nodes _must_ be removed in the exact same order from the scan list as they have been added, otherwise the internal state of the memory manager will be corrupted.

When the scan list is empty, the selected memory nodes can be freed. An immediately following drm_mm_search_free with !DRM_MM_SEARCH_BEST will then return the just freed block (because its at the top of the free_stack list).

Return

True if this block should be evicted, false otherwise. Will always return false when no hole has been found.

bool drm_mm_clean(struct drm_mm * mm)¶

checks whether an allocator is clean

Parameters

struct drm_mm * mm

drm_mm allocator to check

Return

True if the allocator is completely free, false if there’s still a node allocated in it.

void drm_mm_init(struct drm_mm * mm, u64 start, u64 size)¶

initialize a drm-mm allocator

Parameters

struct drm_mm * mm

the drm_mm structure to initialize

u64 start

start of the range managed by mm

u64 size

end of the range managed by mm

Description

Note that mm must be cleared to 0 before calling this function.

void drm_mm_takedown(struct drm_mm * mm)¶

clean up a drm_mm allocator

Parameters

struct drm_mm * mm

drm_mm allocator to clean up

Description

Note that it is a bug to call this function on an allocator which is not clean.

void drm_mm_debug_table(struct drm_mm * mm, const char * prefix)¶

dump allocator state to dmesg

Parameters

struct drm_mm * mm

drm_mm allocator to dump

const char * prefix

prefix to use for dumping to dmesg

int drm_mm_dump_table(struct seq_file * m, struct drm_mm * mm)¶

dump allocator state to a seq_file

Parameters

struct seq_file * m

seq_file to dump to

struct drm_mm * mm

drm_mm allocator to dump

bool drm_mm_node_allocated(struct drm_mm_node * node)¶

checks whether a node is allocated

Parameters

struct drm_mm_node * node

drm_mm_node to check

Description

Drivers should use this helpers for proper encapusulation of drm_mm internals.

Return

True if the node is allocated.

bool drm_mm_initialized(struct drm_mm * mm)¶

checks whether an allocator is initialized

Parameters

struct drm_mm * mm

drm_mm to check

Description

Drivers should use this helpers for proper encapusulation of drm_mm internals.

Return

True if the mm is initialized.

u64 drm_mm_hole_node_start(struct drm_mm_node * hole_node)¶

computes the start of the hole following node

Parameters

struct drm_mm_node * hole_node

drm_mm_node which implicitly tracks the following hole

Description

This is useful for driver-sepific debug dumpers. Otherwise drivers should not inspect holes themselves. Drivers must check first whether a hole indeed follows by looking at node->hole_follows.

Return

Start of the subsequent hole.

u64 drm_mm_hole_node_end(struct drm_mm_node * hole_node)¶

computes the end of the hole following node

Parameters

struct drm_mm_node * hole_node

drm_mm_node which implicitly tracks the following hole

Description

This is useful for driver-sepific debug dumpers. Otherwise drivers should not inspect holes themselves. Drivers must check first whether a hole indeed follows by looking at node->hole_follows.

Return

End of the subsequent hole.

drm_mm_for_each_node(entry, mm)¶

iterator to walk over all allocated nodes

Parameters

entry

drm_mm_node structure to assign to in each iteration step

mm

drm_mm allocator to walk

Description

This iterator walks over all nodes in the range allocator. It is implemented with list_for_each, so not save against removal of elements.

drm_mm_for_each_hole(entry, mm, hole_start, hole_end)¶

iterator to walk over all holes

Parameters

entry

drm_mm_node used internally to track progress

mm

drm_mm allocator to walk

hole_start

ulong variable to assign the hole start to on each iteration

hole_end

ulong variable to assign the hole end to on each iteration

Description

This iterator walks over all holes in the range allocator. It is implemented with list_for_each, so not save against removal of elements. entry is used internally and will not reflect a real drm_mm_node for the very first hole. Hence users of this iterator may not access it.

Implementation Note: We need to inline list_for_each_entry in order to be able to set hole_start and hole_end on each iteration while keeping the macro sane.

The __drm_mm_for_each_hole version is similar, but with added support for going backwards.

int drm_mm_insert_node(struct drm_mm * mm, struct drm_mm_node * node, u64 size, unsigned alignment, enum drm_mm_search_flags flags)¶

search for space and insert node

Parameters

struct drm_mm * mm

drm_mm to allocate from

struct drm_mm_node * node

preallocate node to insert

u64 size

size of the allocation

unsigned alignment

alignment of the allocation

enum drm_mm_search_flags flags

flags to fine-tune the allocation

Description

This is a simplified version of drm_mm_insert_node_generic() with color set to 0.

The preallocated node must be cleared to 0.

Return

0 on success, -ENOSPC if there’s no suitable hole.

int drm_mm_insert_node_in_range(struct drm_mm * mm, struct drm_mm_node * node, u64 size, unsigned alignment, u64 start, u64 end, enum drm_mm_search_flags flags)¶

ranged search for space and insert node

Parameters

struct drm_mm * mm

drm_mm to allocate from

struct drm_mm_node * node

preallocate node to insert

u64 size

size of the allocation

unsigned alignment

alignment of the allocation

u64 start

start of the allowed range for this node

u64 end

end of the allowed range for this node

enum drm_mm_search_flags flags

flags to fine-tune the allocation

Description

This is a simplified version of drm_mm_insert_node_in_range_generic() with color set to 0.

The preallocated node must be cleared to 0.

Return

0 on success, -ENOSPC if there’s no suitable hole.

CMA Helper Functions Reference¶

The Contiguous Memory Allocator reserves a pool of memory at early boot that is used to service requests for large blocks of contiguous memory.

The DRM GEM/CMA helpers use this allocator as a means to provide buffer objects that are physically contiguous in memory. This is useful for display drivers that are unable to map scattered buffers via an IOMMU.

struct drm_gem_cma_object * drm_gem_cma_create(struct drm_device * drm, size_t size)¶

allocate an object with the given size

Parameters

struct drm_device * drm

DRM device

size_t size

size of the object to allocate

Description

This function creates a CMA GEM object and allocates a contiguous chunk of memory as backing store. The backing memory has the writecombine attribute set.

Return

A struct drm_gem_cma_object * on success or an ERR_PTR()-encoded negative error code on failure.

void drm_gem_cma_free_object(struct drm_gem_object * gem_obj)¶

free resources associated with a CMA GEM object

Parameters

struct drm_gem_object * gem_obj

GEM object to free

Description

This function frees the backing memory of the CMA GEM object, cleans up the GEM object state and frees the memory used to store the object itself. Drivers using the CMA helpers should set this as their DRM driver’s ->:c:func:gem_free_object() callback.

int drm_gem_cma_dumb_create_internal(struct drm_file * file_priv, struct drm_device * drm, struct drm_mode_create_dumb * args)¶

create a dumb buffer object

Parameters

struct drm_file * file_priv

DRM file-private structure to create the dumb buffer for

struct drm_device * drm

DRM device

struct drm_mode_create_dumb * args

IOCTL data

Description

This aligns the pitch and size arguments to the minimum required. This is an internal helper that can be wrapped by a driver to account for hardware with more specific alignment requirements. It should not be used directly as the ->:c:func:dumb_create() callback in a DRM driver.

Return

0 on success or a negative error code on failure.

int drm_gem_cma_dumb_create(struct drm_file * file_priv, struct drm_device * drm, struct drm_mode_create_dumb * args)¶

create a dumb buffer object

Parameters

struct drm_file * file_priv

DRM file-private structure to create the dumb buffer for

struct drm_device * drm

DRM device

struct drm_mode_create_dumb * args

IOCTL data

Description

This function computes the pitch of the dumb buffer and rounds it up to an integer number of bytes per pixel. Drivers for hardware that doesn’t have any additional restrictions on the pitch can directly use this function as their ->:c:func:dumb_create() callback.

For hardware with additional restrictions, drivers can adjust the fields set up by userspace and pass the IOCTL data along to the drm_gem_cma_dumb_create_internal() function.

Return

0 on success or a negative error code on failure.

int drm_gem_cma_dumb_map_offset(struct drm_file * file_priv, struct drm_device * drm, u32 handle, u64 * offset)¶

return the fake mmap offset for a CMA GEM object

Parameters

struct drm_file * file_priv

DRM file-private structure containing the GEM object

struct drm_device * drm

DRM device

u32 handle

GEM object handle

u64 * offset

return location for the fake mmap offset

Description

This function look up an object by its handle and returns the fake mmap offset associated with it. Drivers using the CMA helpers should set this as their DRM driver’s ->:c:func:dumb_map_offset() callback.

Return

0 on success or a negative error code on failure.

int drm_gem_cma_mmap(struct file * filp, struct vm_area_struct * vma)¶

memory-map a CMA GEM object

Parameters

struct file * filp

file object

struct vm_area_struct * vma

VMA for the area to be mapped

Description

This function implements an augmented version of the GEM DRM file mmap operation for CMA objects: In addition to the usual GEM VMA setup it immediately faults in the entire object instead of using on-demaind faulting. Drivers which employ the CMA helpers should use this function as their ->:c:func:mmap() handler in the DRM device file’s file_operations structure.

Return

0 on success or a negative error code on failure.

void drm_gem_cma_describe(struct drm_gem_cma_object * cma_obj, struct seq_file * m)¶

describe a CMA GEM object for debugfs

Parameters

struct drm_gem_cma_object * cma_obj

CMA GEM object

struct seq_file * m

debugfs file handle

Description

This function can be used to dump a human-readable representation of the CMA GEM object into a synthetic file.

struct sg_table * drm_gem_cma_prime_get_sg_table(struct drm_gem_object * obj)¶

provide a scatter/gather table of pinned pages for a CMA GEM object

Parameters

struct drm_gem_object * obj

GEM object

Description

This function exports a scatter/gather table suitable for PRIME usage by calling the standard DMA mapping API. Drivers using the CMA helpers should set this as their DRM driver’s ->:c:func:gem_prime_get_sg_table() callback.

Return

A pointer to the scatter/gather table of pinned pages or NULL on failure.

struct drm_gem_object * drm_gem_cma_prime_import_sg_table(struct drm_device * dev, struct dma_buf_attachment * attach, struct sg_table * sgt)¶

produce a CMA GEM object from another driver’s scatter/gather table of pinned pages

Parameters

struct drm_device * dev

device to import into

struct dma_buf_attachment * attach

DMA-BUF attachment

struct sg_table * sgt

scatter/gather table of pinned pages

Description

This function imports a scatter/gather table exported via DMA-BUF by another driver. Imported buffers must be physically contiguous in memory (i.e. the scatter/gather table must contain a single entry). Drivers that use the CMA helpers should set this as their DRM driver’s ->:c:func:gem_prime_import_sg_table() callback.

Return

A pointer to a newly created GEM object or an ERR_PTR-encoded negative error code on failure.

int drm_gem_cma_prime_mmap(struct drm_gem_object * obj, struct vm_area_struct * vma)¶

memory-map an exported CMA GEM object

Parameters

struct drm_gem_object * obj

GEM object

struct vm_area_struct * vma

VMA for the area to be mapped

Description

This function maps a buffer imported via DRM PRIME into a userspace process’s address space. Drivers that use the CMA helpers should set this as their DRM driver’s ->:c:func:gem_prime_mmap() callback.

Return

0 on success or a negative error code on failure.

void * drm_gem_cma_prime_vmap(struct drm_gem_object * obj)¶

map a CMA GEM object into the kernel’s virtual address space

Parameters

struct drm_gem_object * obj

GEM object

Description

This function maps a buffer exported via DRM PRIME into the kernel’s virtual address space. Since the CMA buffers are already mapped into the kernel virtual address space this simply returns the cached virtual address. Drivers using the CMA helpers should set this as their DRM driver’s ->:c:func:gem_prime_vmap() callback.

Return

The kernel virtual address of the CMA GEM object’s backing store.

void drm_gem_cma_prime_vunmap(struct drm_gem_object * obj, void * vaddr)¶

unmap a CMA GEM object from the kernel’s virtual address space

Parameters

struct drm_gem_object * obj

GEM object

void * vaddr

kernel virtual address where the CMA GEM object was mapped

Description

This function removes a buffer exported via DRM PRIME from the kernel’s virtual address space. This is a no-op because CMA buffers cannot be unmapped from kernel space. Drivers using the CMA helpers should set this as their DRM driver’s ->:c:func:gem_prime_vunmap() callback.

struct drm_gem_cma_object¶

GEM object backed by CMA memory allocations

Definition

struct drm_gem_cma_object {
  struct drm_gem_object base;
  dma_addr_t paddr;
  struct sg_table * sgt;
  void * vaddr;
};

Members

struct drm_gem_object base

base GEM object

dma_addr_t paddr

physical address of the backing memory

struct sg_table * sgt

scatter/gather table for imported PRIME buffers

void * vaddr

kernel virtual address of the backing memory

Display Modes Function Reference¶

enum drm_mode_status¶

hardware support status of a mode

Constants

MODE_OK

Mode OK

MODE_HSYNC

hsync out of range

MODE_VSYNC

vsync out of range

MODE_H_ILLEGAL

mode has illegal horizontal timings

MODE_V_ILLEGAL

mode has illegal horizontal timings

MODE_BAD_WIDTH

requires an unsupported linepitch

MODE_NOMODE

no mode with a matching name

MODE_NO_INTERLACE

interlaced mode not supported

MODE_NO_DBLESCAN

doublescan mode not supported

MODE_NO_VSCAN

multiscan mode not supported

MODE_MEM

insufficient video memory

MODE_VIRTUAL_X

mode width too large for specified virtual size

MODE_VIRTUAL_Y

mode height too large for specified virtual size

MODE_MEM_VIRT

insufficient video memory given virtual size

MODE_NOCLOCK

no fixed clock available

MODE_CLOCK_HIGH

clock required is too high

MODE_CLOCK_LOW

clock required is too low

MODE_CLOCK_RANGE

clock/mode isn’t in a ClockRange

MODE_BAD_HVALUE

horizontal timing was out of range

MODE_BAD_VVALUE

vertical timing was out of range

MODE_BAD_VSCAN

VScan value out of range

MODE_HSYNC_NARROW

horizontal sync too narrow

MODE_HSYNC_WIDE

horizontal sync too wide

MODE_HBLANK_NARROW

horizontal blanking too narrow

MODE_HBLANK_WIDE

horizontal blanking too wide

MODE_VSYNC_NARROW

vertical sync too narrow

MODE_VSYNC_WIDE

vertical sync too wide

MODE_VBLANK_NARROW

vertical blanking too narrow

MODE_VBLANK_WIDE

vertical blanking too wide

MODE_PANEL

exceeds panel dimensions

MODE_INTERLACE_WIDTH

width too large for interlaced mode

MODE_ONE_WIDTH

only one width is supported

MODE_ONE_HEIGHT

only one height is supported

MODE_ONE_SIZE

only one resolution is supported

MODE_NO_REDUCED

monitor doesn’t accept reduced blanking

MODE_NO_STEREO

stereo modes not supported

MODE_STALE

mode has become stale

MODE_BAD

unspecified reason

MODE_ERROR

error condition

Description

This enum is used to filter out modes not supported by the driver/hardware combination.

struct drm_display_mode¶

DRM kernel-internal display mode structure

Definition

struct drm_display_mode {
  struct list_head head;
  struct drm_mode_object base;
  char name[DRM_DISPLAY_MODE_LEN];
  enum drm_mode_status status;
  unsigned int type;
  int clock;
  int hdisplay;
  int hsync_start;
  int hsync_end;
  int htotal;
  int hskew;
  int vdisplay;
  int vsync_start;
  int vsync_end;
  int vtotal;
  int vscan;
  unsigned int flags;
  int width_mm;
  int height_mm;
  int crtc_clock;
  int crtc_hdisplay;
  int crtc_hblank_start;
  int crtc_hblank_end;
  int crtc_hsync_start;
  int crtc_hsync_end;
  int crtc_htotal;
  int crtc_hskew;
  int crtc_vdisplay;
  int crtc_vblank_start;
  int crtc_vblank_end;
  int crtc_vsync_start;
  int crtc_vsync_end;
  int crtc_vtotal;
  int * private;
  int private_flags;
  int vrefresh;
  int hsync;
  enum hdmi_picture_aspect picture_aspect_ratio;
};

Members

struct list_head head

struct list_head for mode lists.

struct drm_mode_object base

A display mode is a normal modeset object, possibly including public userspace id.

FIXME:

This can probably be removed since the entire concept of userspace managing modes explicitly has never landed in upstream kernel mode setting support.

char name[DRM_DISPLAY_MODE_LEN]

Human-readable name of the mode, filled out with drm_mode_set_name().

enum drm_mode_status status

Status of the mode, used to filter out modes not supported by the hardware. See enum drm_mode_status.

unsigned int type

A bitmask of flags, mostly about the source of a mode. Possible flags are:

• DRM_MODE_TYPE_BUILTIN: Meant for hard-coded modes, effectively unused.
• DRM_MODE_TYPE_PREFERRED: Preferred mode, usually the native resolution of an LCD panel. There should only be one preferred mode per connector at any given time.
• DRM_MODE_TYPE_DRIVER: Mode created by the driver, which is all of them really. Drivers must set this bit for all modes they create and expose to userspace.

Plus a big list of flags which shouldn’t be used at all, but are still around since these flags are also used in the userspace ABI:

• DRM_MODE_TYPE_DEFAULT: Again a leftover, use DRM_MODE_TYPE_PREFERRED instead.
• DRM_MODE_TYPE_CLOCK_C and DRM_MODE_TYPE_CRTC_C: Define leftovers which are stuck around for hysterical raisins only. No one has an idea what they were meant for. Don’t use.
• DRM_MODE_TYPE_USERDEF: Mode defined by userspace, again a vestige from older kms designs where userspace had to first add a custom mode to the kernel’s mode list before it could use it. Don’t use.

int clock

Pixel clock in kHz.

int hdisplay

horizontal display size

int hsync_start

horizontal sync start

int hsync_end

horizontal sync end

int htotal

horizontal total size

int hskew

horizontal skew?!

int vdisplay

vertical display size

int vsync_start

vertical sync start

int vsync_end

vertical sync end

int vtotal

vertical total size

int vscan

vertical scan?!

unsigned int flags

Sync and timing flags:

• DRM_MODE_FLAG_PHSYNC: horizontal sync is active high.
• DRM_MODE_FLAG_NHSYNC: horizontal sync is active low.
• DRM_MODE_FLAG_PVSYNC: vertical sync is active high.
• DRM_MODE_FLAG_NVSYNC: vertical sync is active low.
• DRM_MODE_FLAG_INTERLACE: mode is interlaced.
• DRM_MODE_FLAG_DBLSCAN: mode uses doublescan.
• DRM_MODE_FLAG_CSYNC: mode uses composite sync.
• DRM_MODE_FLAG_PCSYNC: composite sync is active high.
• DRM_MODE_FLAG_NCSYNC: composite sync is active low.
• DRM_MODE_FLAG_HSKEW: hskew provided (not used?).
• DRM_MODE_FLAG_BCAST: not used?
• DRM_MODE_FLAG_PIXMUX: not used?
• DRM_MODE_FLAG_DBLCLK: double-clocked mode.
• DRM_MODE_FLAG_CLKDIV2: half-clocked mode.

Additionally there’s flags to specify how 3D modes are packed:

• DRM_MODE_FLAG_3D_NONE: normal, non-3D mode.
• DRM_MODE_FLAG_3D_FRAME_PACKING: 2 full frames for left and right.
• DRM_MODE_FLAG_3D_FIELD_ALTERNATIVE: interleaved like fields.
• DRM_MODE_FLAG_3D_LINE_ALTERNATIVE: interleaved lines.
• DRM_MODE_FLAG_3D_SIDE_BY_SIDE_FULL: side-by-side full frames.
• DRM_MODE_FLAG_3D_L_DEPTH: ?
• DRM_MODE_FLAG_3D_L_DEPTH_GFX_GFX_DEPTH: ?
• DRM_MODE_FLAG_3D_TOP_AND_BOTTOM: frame split into top and bottom parts.
• DRM_MODE_FLAG_3D_SIDE_BY_SIDE_HALF: frame split into left and right parts.

int width_mm

Addressable size of the output in mm, projectors should set this to 0.

int height_mm

Addressable size of the output in mm, projectors should set this to 0.

int crtc_clock

Actual pixel or dot clock in the hardware. This differs from the logical clock when e.g. using interlacing, double-clocking, stereo modes or other fancy stuff that changes the timings and signals actually sent over the wire.

This is again in kHz.

Note that with digital outputs like HDMI or DP there’s usually a massive confusion between the dot clock and the signal clock at the bit encoding level. Especially when a 8b/10b encoding is used and the difference is exactly a factor of 10.

int crtc_hdisplay

hardware mode horizontal display size

int crtc_hblank_start

hardware mode horizontal blank start

int crtc_hblank_end

hardware mode horizontal blank end

int crtc_hsync_start

hardware mode horizontal sync start

int crtc_hsync_end

hardware mode horizontal sync end

int crtc_htotal

hardware mode horizontal total size

int crtc_hskew

hardware mode horizontal skew?!

int crtc_vdisplay

hardware mode vertical display size

int crtc_vblank_start

hardware mode vertical blank start

int crtc_vblank_end

hardware mode vertical blank end

int crtc_vsync_start

hardware mode vertical sync start

int crtc_vsync_end

hardware mode vertical sync end

int crtc_vtotal

hardware mode vertical total size

int * private

Pointer for driver private data. This can only be used for mode objects passed to drivers in modeset operations. It shouldn’t be used by atomic drivers since they can store any additional data by subclassing state structures.

int private_flags

Similar to private, but just an integer.

int vrefresh

Vertical refresh rate, for debug output in human readable form. Not used in a functional way.

This value is in Hz.

int hsync

Horizontal refresh rate, for debug output in human readable form. Not used in a functional way.

This value is in kHz.

enum hdmi_picture_aspect picture_aspect_ratio

Field for setting the HDMI picture aspect ratio of a mode.

Description

The horizontal and vertical timings are defined per the following diagram.

          Active                 Front           Sync           Back
         Region                 Porch                          Porch
<-----------------------><----------------><-------------><-------------->
  //////////////////////|
 ////////////////////// |
//////////////////////  |..................               ................
                                           _______________
<----- [hv]display ----->
<------------- [hv]sync_start ------------>
<--------------------- [hv]sync_end --------------------->
<-------------------------------- [hv]total ----------------------------->*

This structure contains two copies of timings. First are the plain timings, which specify the logical mode, as it would be for a progressive 1:1 scanout at the refresh rate userspace can observe through vblank timestamps. Then there’s the hardware timings, which are corrected for interlacing, double-clocking and similar things. They are provided as a convenience, and can be appropriately computed using drm_mode_set_crtcinfo().

bool drm_mode_is_stereo(const struct drm_display_mode * mode)¶

check for stereo mode flags

Parameters

const struct drm_display_mode * mode

drm_display_mode to check

Return

True if the mode is one of the stereo modes (like side-by-side), false if not.

void drm_mode_debug_printmodeline(const struct drm_display_mode * mode)¶

print a mode to dmesg

Parameters

const struct drm_display_mode * mode

mode to print

Description

Describe mode using DRM_DEBUG.

struct drm_display_mode * drm_mode_create(struct drm_device * dev)¶

create a new display mode

Parameters

struct drm_device * dev

DRM device

Description

Create a new, cleared drm_display_mode with kzalloc, allocate an ID for it and return it.

Return

Pointer to new mode on success, NULL on error.

void drm_mode_destroy(struct drm_device * dev, struct drm_display_mode * mode)¶

remove a mode

Parameters

struct drm_device * dev

DRM device

struct drm_display_mode * mode

mode to remove

Description

Release mode‘s unique ID, then free it mode structure itself using kfree.

void drm_mode_probed_add(struct drm_connector * connector, struct drm_display_mode * mode)¶

add a mode to a connector’s probed_mode list

Parameters

struct drm_connector * connector

connector the new mode

struct drm_display_mode * mode

mode data

Description

Add mode to connector‘s probed_mode list for later use. This list should then in a second step get filtered and all the modes actually supported by the hardware moved to the connector‘s modes list.

struct drm_display_mode * drm_cvt_mode(struct drm_device * dev, int hdisplay, int vdisplay, int vrefresh, bool reduced, bool interlaced, bool margins)¶

create a modeline based on the CVT algorithm

Parameters

struct drm_device * dev

drm device

int hdisplay

hdisplay size

int vdisplay

vdisplay size

int vrefresh

vrefresh rate

bool reduced

whether to use reduced blanking

bool interlaced

whether to compute an interlaced mode

bool margins

whether to add margins (borders)

Description

This function is called to generate the modeline based on CVT algorithm according to the hdisplay, vdisplay, vrefresh. It is based from the VESA(TM) Coordinated Video Timing Generator by Graham Loveridge April 9, 2003 available at http://www.elo.utfsm.cl/~elo212/docs/CVTd6r1.xls

And it is copied from xf86CVTmode in xserver/hw/xfree86/modes/xf86cvt.c. What I have done is to translate it by using integer calculation.

Return

The modeline based on the CVT algorithm stored in a drm_display_mode object. The display mode object is allocated with drm_mode_create(). Returns NULL when no mode could be allocated.

struct drm_display_mode * drm_gtf_mode_complex(struct drm_device * dev, int hdisplay, int vdisplay, int vrefresh, bool interlaced, int margins, int GTF_M, int GTF_2C, int GTF_K, int GTF_2J)¶

create the modeline based on the full GTF algorithm

Parameters

struct drm_device * dev

drm device

int hdisplay

hdisplay size

int vdisplay

vdisplay size

int vrefresh

vrefresh rate.

bool interlaced

whether to compute an interlaced mode

int margins

desired margin (borders) size

int GTF_M

extended GTF formula parameters

int GTF_2C

extended GTF formula parameters

int GTF_K

extended GTF formula parameters

int GTF_2J

extended GTF formula parameters

Description

GTF feature blocks specify C and J in multiples of 0.5, so we pass them in here multiplied by two. For a C of 40, pass in 80.

Return

The modeline based on the full GTF algorithm stored in a drm_display_mode object. The display mode object is allocated with drm_mode_create(). Returns NULL when no mode could be allocated.

struct drm_display_mode * drm_gtf_mode(struct drm_device * dev, int hdisplay, int vdisplay, int vrefresh, bool interlaced, int margins)¶

create the modeline based on the GTF algorithm

Parameters

struct drm_device * dev

drm device

int hdisplay

hdisplay size

int vdisplay

vdisplay size

int vrefresh

vrefresh rate.

bool interlaced

whether to compute an interlaced mode

int margins

desired margin (borders) size

Description

return the modeline based on GTF algorithm

This function is to create the modeline based on the GTF algorithm. Generalized Timing Formula is derived from:

GTF Spreadsheet by Andy Morrish (1/5/97) available at http://www.vesa.org

And it is copied from the file of xserver/hw/xfree86/modes/xf86gtf.c. What I have done is to translate it by using integer calculation. I also refer to the function of fb_get_mode in the file of drivers/video/fbmon.c

Standard GTF parameters:

M = 600
C = 40
K = 128
J = 20

Return

The modeline based on the GTF algorithm stored in a drm_display_mode object. The display mode object is allocated with drm_mode_create(). Returns NULL when no mode could be allocated.

void drm_display_mode_from_videomode(const struct videomode * vm, struct drm_display_mode * dmode)¶

fill in dmode using vm,

Parameters

const struct videomode * vm

videomode structure to use as source

struct drm_display_mode * dmode

drm_display_mode structure to use as destination

Description

Fills out dmode using the display mode specified in vm.

void drm_display_mode_to_videomode(const struct drm_display_mode * dmode, struct videomode * vm)¶

fill in vm using dmode,

Parameters

const struct drm_display_mode * dmode

drm_display_mode structure to use as source

struct videomode * vm

videomode structure to use as destination

Description

Fills out vm using the display mode specified in dmode.

int of_get_drm_display_mode(struct device_node * np, struct drm_display_mode * dmode, int index)¶

get a drm_display_mode from devicetree

Parameters

struct device_node * np

device_node with the timing specification

struct drm_display_mode * dmode

will be set to the return value

int index

index into the list of display timings in devicetree

Description

This function is expensive and should only be used, if only one mode is to be read from DT. To get multiple modes start with of_get_display_timings and work with that instead.

Return

0 on success, a negative errno code when no of videomode node was found.

void drm_mode_set_name(struct drm_display_mode * mode)¶

set the name on a mode

Parameters

struct drm_display_mode * mode

name will be set in this mode

Description

Set the name of mode to a standard format which is <hdisplay>x<vdisplay> with an optional ‘i’ suffix for interlaced modes.

int drm_mode_hsync(const struct drm_display_mode * mode)¶

get the hsync of a mode

Parameters

const struct drm_display_mode * mode

mode

Return

modes‘s hsync rate in kHz, rounded to the nearest integer. Calculates the value first if it is not yet set.

int drm_mode_vrefresh(const struct drm_display_mode * mode)¶

get the vrefresh of a mode

Parameters

const struct drm_display_mode * mode

mode

Return

modes‘s vrefresh rate in Hz, rounded to the nearest integer. Calculates the value first if it is not yet set.

void drm_mode_set_crtcinfo(struct drm_display_mode * p, int adjust_flags)¶

set CRTC modesetting timing parameters

Parameters

struct drm_display_mode * p

mode

int adjust_flags

a combination of adjustment flags

Description

Setup the CRTC modesetting timing parameters for p, adjusting if necessary.

• The CRTC_INTERLACE_HALVE_V flag can be used to halve vertical timings of interlaced modes.
• The CRTC_STEREO_DOUBLE flag can be used to compute the timings for buffers containing two eyes (only adjust the timings when needed, eg. for “frame packing” or “side by side full”).
• The CRTC_NO_DBLSCAN and CRTC_NO_VSCAN flags request that adjustment not be performed for doublescan and vscan > 1 modes respectively.

void drm_mode_copy(struct drm_display_mode * dst, const struct drm_display_mode * src)¶

copy the mode

Parameters

struct drm_display_mode * dst

mode to overwrite

const struct drm_display_mode * src

mode to copy

Description

Copy an existing mode into another mode, preserving the object id and list head of the destination mode.

struct drm_display_mode * drm_mode_duplicate(struct drm_device * dev, const struct drm_display_mode * mode)¶

allocate and duplicate an existing mode

Parameters

struct drm_device * dev

drm_device to allocate the duplicated mode for

const struct drm_display_mode * mode

mode to duplicate

Description

Just allocate a new mode, copy the existing mode into it, and return a pointer to it. Used to create new instances of established modes.

Return

Pointer to duplicated mode on success, NULL on error.

bool drm_mode_equal(const struct drm_display_mode * mode1, const struct drm_display_mode * mode2)¶

test modes for equality

Parameters

const struct drm_display_mode * mode1

first mode

const struct drm_display_mode * mode2

second mode

Description

Check to see if mode1 and mode2 are equivalent.

Return

True if the modes are equal, false otherwise.

bool drm_mode_equal_no_clocks(const struct drm_display_mode * mode1, const struct drm_display_mode * mode2)¶

test modes for equality

Parameters

const struct drm_display_mode * mode1

first mode

const struct drm_display_mode * mode2

second mode

Description

Check to see if mode1 and mode2 are equivalent, but don’t check the pixel clocks.

Return

True if the modes are equal, false otherwise.

bool drm_mode_equal_no_clocks_no_stereo(const struct drm_display_mode * mode1, const struct drm_display_mode * mode2)¶

test modes for equality

Parameters

const struct drm_display_mode * mode1

first mode

const struct drm_display_mode * mode2

second mode

Description

Check to see if mode1 and mode2 are equivalent, but don’t check the pixel clocks nor the stereo layout.

Return

True if the modes are equal, false otherwise.

enum drm_mode_status drm_mode_validate_basic(const struct drm_display_mode * mode)¶

make sure the mode is somewhat sane

Parameters

const struct drm_display_mode * mode

mode to check

Description

Check that the mode timings are at least somewhat reasonable. Any hardware specific limits are left up for each driver to check.

Return

The mode status

enum drm_mode_status drm_mode_validate_size(const struct drm_display_mode * mode, int maxX, int maxY)¶

make sure modes adhere to size constraints

Parameters

const struct drm_display_mode * mode

mode to check

int maxX

maximum width

int maxY

maximum height

Description

This function is a helper which can be used to validate modes against size limitations of the DRM device/connector. If a mode is too big its status member is updated with the appropriate validation failure code. The list itself is not changed.

Return

The mode status

void drm_mode_prune_invalid(struct drm_device * dev, struct list_head * mode_list, bool verbose)¶

remove invalid modes from mode list

Parameters

struct drm_device * dev

DRM device

struct list_head * mode_list

list of modes to check

bool verbose

be verbose about it

Description

This helper function can be used to prune a display mode list after validation has been completed. All modes who’s status is not MODE_OK will be removed from the list, and if verbose the status code and mode name is also printed to dmesg.

void drm_mode_sort(struct list_head * mode_list)¶

sort mode list

Parameters

struct list_head * mode_list

list of drm_display_mode structures to sort

Description

Sort mode_list by favorability, moving good modes to the head of the list.

void drm_mode_connector_list_update(struct drm_connector * connector)¶

update the mode list for the connector

Parameters

struct drm_connector * connector

the connector to update

Description

This moves the modes from the connector probed_modes list to the actual mode list. It compares the probed mode against the current list and only adds different/new modes.

This is just a helper functions doesn’t validate any modes itself and also doesn’t prune any invalid modes. Callers need to do that themselves.

bool drm_mode_parse_command_line_for_connector(const char * mode_option, struct drm_connector * connector, struct drm_cmdline_mode * mode)¶

parse command line modeline for connector

Parameters

const char * mode_option

optional per connector mode option

struct drm_connector * connector

connector to parse modeline for

struct drm_cmdline_mode * mode

preallocated drm_cmdline_mode structure to fill out

Description

This parses mode_option command line modeline for modes and options to configure the connector. If mode_option is NULL the default command line modeline in fb_mode_option will be parsed instead.

This uses the same parameters as the fb modedb.c, except for an extra force-enable, force-enable-digital and force-disable bit at the end:

<xres>x<yres>[M][R][-<bpp>][@<refresh>][i][m][eDd]

The intermediate drm_cmdline_mode structure is required to store additional options from the command line modline like the force-enable/disable flag.

Return

True if a valid modeline has been parsed, false otherwise.

struct drm_display_mode * drm_mode_create_from_cmdline_mode(struct drm_device * dev, struct drm_cmdline_mode * cmd)¶

convert a command line modeline into a DRM display mode

Parameters

struct drm_device * dev

DRM device to create the new mode for

struct drm_cmdline_mode * cmd

input command line modeline

Return

Pointer to converted mode on success, NULL on error.

Atomic Mode Setting Function Reference¶

void drm_atomic_state_default_release(struct drm_atomic_state * state)¶

release memory initialized by drm_atomic_state_init

Parameters

struct drm_atomic_state * state

atomic state

Description

Free all the memory allocated by drm_atomic_state_init. This is useful for drivers that subclass the atomic state.

int drm_atomic_state_init(struct drm_device * dev, struct drm_atomic_state * state)¶

init new atomic state

Parameters

struct drm_device * dev

DRM device

struct drm_atomic_state * state

atomic state

Description

Default implementation for filling in a new atomic state. This is useful for drivers that subclass the atomic state.

struct drm_atomic_state * drm_atomic_state_alloc(struct drm_device * dev)¶

allocate atomic state

Parameters

struct drm_device * dev

DRM device

Description

This allocates an empty atomic state to track updates.

void drm_atomic_state_default_clear(struct drm_atomic_state * state)¶

clear base atomic state

Parameters

struct drm_atomic_state * state

atomic state

Description

Default implementation for clearing atomic state. This is useful for drivers that subclass the atomic state.

void drm_atomic_state_clear(struct drm_atomic_state * state)¶

clear state object

Parameters

struct drm_atomic_state * state

atomic state

Description

When the w/w mutex algorithm detects a deadlock we need to back off and drop all locks. So someone else could sneak in and change the current modeset configuration. Which means that all the state assembled in state is no longer an atomic update to the current state, but to some arbitrary earlier state. Which could break assumptions the driver’s ->atomic_check likely relies on.

Hence we must clear all cached state and completely start over, using this function.

void drm_atomic_state_free(struct drm_atomic_state * state)¶

free all memory for an atomic state

Parameters

struct drm_atomic_state * state

atomic state to deallocate

Description

This frees all memory associated with an atomic state, including all the per-object state for planes, crtcs and connectors.

struct drm_crtc_state * drm_atomic_get_crtc_state(struct drm_atomic_state * state, struct drm_crtc * crtc)¶

get crtc state

Parameters

struct drm_atomic_state * state

global atomic state object

struct drm_crtc * crtc

crtc to get state object for

Description

This function returns the crtc state for the given crtc, allocating it if needed. It will also grab the relevant crtc lock to make sure that the state is consistent.

Return

Either the allocated state or the error code encoded into the pointer. When the error is EDEADLK then the w/w mutex code has detected a deadlock and the entire atomic sequence must be restarted. All other errors are fatal.

int drm_atomic_set_mode_for_crtc(struct drm_crtc_state * state, struct drm_display_mode * mode)¶

set mode for CRTC

Parameters

struct drm_crtc_state * state

the CRTC whose incoming state to update

struct drm_display_mode * mode

kernel-internal mode to use for the CRTC, or NULL to disable

Description

Set a mode (originating from the kernel) on the desired CRTC state. Does not change any other state properties, including enable, active, or mode_changed.

Return

Zero on success, error code on failure. Cannot return -EDEADLK.

int drm_atomic_set_mode_prop_for_crtc(struct drm_crtc_state * state, struct drm_property_blob * blob)¶

set mode for CRTC

Parameters

struct drm_crtc_state * state

the CRTC whose incoming state to update

struct drm_property_blob * blob

pointer to blob property to use for mode

Description

Set a mode (originating from a blob property) on the desired CRTC state. This function will take a reference on the blob property for the CRTC state, and release the reference held on the state’s existing mode property, if any was set.

Return

Zero on success, error code on failure. Cannot return -EDEADLK.

int drm_atomic_crtc_set_property(struct drm_crtc * crtc, struct drm_crtc_state * state, struct drm_property * property, uint64_t val)¶

set property on CRTC

Parameters

struct drm_crtc * crtc

the drm CRTC to set a property on

struct drm_crtc_state * state

the state object to update with the new property value

struct drm_property * property

the property to set

uint64_t val

the new property value

Description

Use this instead of calling crtc->atomic_set_property directly. This function handles generic/core properties and calls out to driver’s ->:c:func:atomic_set_property() for driver properties. To ensure consistent behavior you must call this function rather than the driver hook directly.

Return

Zero on success, error code on failure

struct drm_plane_state * drm_atomic_get_plane_state(struct drm_atomic_state * state, struct drm_plane * plane)¶

get plane state

Parameters

struct drm_atomic_state * state

global atomic state object

struct drm_plane * plane

plane to get state object for

Description

This function returns the plane state for the given plane, allocating it if needed. It will also grab the relevant plane lock to make sure that the state is consistent.

Return

Either the allocated state or the error code encoded into the pointer. When the error is EDEADLK then the w/w mutex code has detected a deadlock and the entire atomic sequence must be restarted. All other errors are fatal.

int drm_atomic_plane_set_property(struct drm_plane * plane, struct drm_plane_state * state, struct drm_property * property, uint64_t val)¶

set property on plane

Parameters

struct drm_plane * plane

the drm plane to set a property on

struct drm_plane_state * state

the state object to update with the new property value

struct drm_property * property

the property to set

uint64_t val

the new property value

Description

Use this instead of calling plane->atomic_set_property directly. This function handles generic/core properties and calls out to driver’s ->:c:func:atomic_set_property() for driver properties. To ensure consistent behavior you must call this function rather than the driver hook directly.

Return

Zero on success, error code on failure

struct drm_connector_state * drm_atomic_get_connector_state(struct drm_atomic_state * state, struct drm_connector * connector)¶

get connector state

Parameters

struct drm_atomic_state * state

global atomic state object

struct drm_connector * connector

connector to get state object for

Description

This function returns the connector state for the given connector, allocating it if needed. It will also grab the relevant connector lock to make sure that the state is consistent.

Return

Either the allocated state or the error code encoded into the pointer. When the error is EDEADLK then the w/w mutex code has detected a deadlock and the entire atomic sequence must be restarted. All other errors are fatal.

int drm_atomic_connector_set_property(struct drm_connector * connector, struct drm_connector_state * state, struct drm_property * property, uint64_t val)¶

set property on connector.

Parameters

struct drm_connector * connector

the drm connector to set a property on

struct drm_connector_state * state

the state object to update with the new property value

struct drm_property * property

the property to set

uint64_t val

the new property value

Description

Use this instead of calling connector->atomic_set_property directly. This function handles generic/core properties and calls out to driver’s ->:c:func:atomic_set_property() for driver properties. To ensure consistent behavior you must call this function rather than the driver hook directly.

Return

Zero on success, error code on failure

int drm_atomic_set_crtc_for_plane(struct drm_plane_state * plane_state, struct drm_crtc * crtc)¶

set crtc for plane

Parameters

struct drm_plane_state * plane_state

the plane whose incoming state to update

struct drm_crtc * crtc

crtc to use for the plane

Description

Changing the assigned crtc for a plane requires us to grab the lock and state for the new crtc, as needed. This function takes care of all these details besides updating the pointer in the state object itself.

Return

0 on success or can fail with -EDEADLK or -ENOMEM. When the error is EDEADLK then the w/w mutex code has detected a deadlock and the entire atomic sequence must be restarted. All other errors are fatal.

void drm_atomic_set_fb_for_plane(struct drm_plane_state * plane_state, struct drm_framebuffer * fb)¶

set framebuffer for plane

Parameters

struct drm_plane_state * plane_state

atomic state object for the plane

struct drm_framebuffer * fb

fb to use for the plane

Description

Changing the assigned framebuffer for a plane requires us to grab a reference to the new fb and drop the reference to the old fb, if there is one. This function takes care of all these details besides updating the pointer in the state object itself.

int drm_atomic_set_crtc_for_connector(struct drm_connector_state * conn_state, struct drm_crtc * crtc)¶

set crtc for connector

Parameters

struct drm_connector_state * conn_state

atomic state object for the connector

struct drm_crtc * crtc

crtc to use for the connector

Description

Changing the assigned crtc for a connector requires us to grab the lock and state for the new crtc, as needed. This function takes care of all these details besides updating the pointer in the state object itself.

Return

0 on success or can fail with -EDEADLK or -ENOMEM. When the error is EDEADLK then the w/w mutex code has detected a deadlock and the entire atomic sequence must be restarted. All other errors are fatal.

int drm_atomic_add_affected_connectors(struct drm_atomic_state * state, struct drm_crtc * crtc)¶

add connectors for crtc

Parameters

struct drm_atomic_state * state

atomic state

struct drm_crtc * crtc

DRM crtc

Description

This function walks the current configuration and adds all connectors currently using crtc to the atomic configuration state. Note that this function must acquire the connection mutex. This can potentially cause unneeded seralization if the update is just for the planes on one crtc. Hence drivers and helpers should only call this when really needed (e.g. when a full modeset needs to happen due to some change).

Return

0 on success or can fail with -EDEADLK or -ENOMEM. When the error is EDEADLK then the w/w mutex code has detected a deadlock and the entire atomic sequence must be restarted. All other errors are fatal.

int drm_atomic_add_affected_planes(struct drm_atomic_state * state, struct drm_crtc * crtc)¶

add planes for crtc

Parameters

struct drm_atomic_state * state

atomic state

struct drm_crtc * crtc

DRM crtc

Description

This function walks the current configuration and adds all planes currently used by crtc to the atomic configuration state. This is useful when an atomic commit also needs to check all currently enabled plane on crtc, e.g. when changing the mode. It’s also useful when re-enabling a CRTC to avoid special code to force-enable all planes.

Since acquiring a plane state will always also acquire the w/w mutex of the current CRTC for that plane (if there is any) adding all the plane states for a CRTC will not reduce parallism of atomic updates.

Return

0 on success or can fail with -EDEADLK or -ENOMEM. When the error is EDEADLK then the w/w mutex code has detected a deadlock and the entire atomic sequence must be restarted. All other errors are fatal.

void drm_atomic_legacy_backoff(struct drm_atomic_state * state)¶

locking backoff for legacy ioctls

Parameters

struct drm_atomic_state * state

atomic state

Description

This function should be used by legacy entry points which don’t understand -EDEADLK semantics. For simplicity this one will grab all modeset locks after the slowpath completed.

int drm_atomic_check_only(struct drm_atomic_state * state)¶

check whether a given config would work

Parameters

struct drm_atomic_state * state

atomic configuration to check

Description

Note that this function can return -EDEADLK if the driver needed to acquire more locks but encountered a deadlock. The caller must then do the usual w/w backoff dance and restart. All other errors are fatal.

Return

0 on success, negative error code on failure.

int drm_atomic_commit(struct drm_atomic_state * state)¶

commit configuration atomically

Parameters

struct drm_atomic_state * state

atomic configuration to check

Description

Note that this function can return -EDEADLK if the driver needed to acquire more locks but encountered a deadlock. The caller must then do the usual w/w backoff dance and restart. All other errors are fatal.

Also note that on successful execution ownership of state is transferred from the caller of this function to the function itself. The caller must not free or in any other way access state. If the function fails then the caller must clean up state itself.

Return

0 on success, negative error code on failure.

int drm_atomic_nonblocking_commit(struct drm_atomic_state * state)¶

atomic:c:type:nonblocking configuration commit

Parameters

struct drm_atomic_state * state

atomic configuration to check

Description

Note that this function can return -EDEADLK if the driver needed to acquire more locks but encountered a deadlock. The caller must then do the usual w/w backoff dance and restart. All other errors are fatal.

Also note that on successful execution ownership of state is transferred from the caller of this function to the function itself. The caller must not free or in any other way access state. If the function fails then the caller must clean up state itself.

Return

0 on success, negative error code on failure.

void drm_atomic_clean_old_fb(struct drm_device * dev, unsigned plane_mask, int ret)¶

• Unset old_fb pointers and set plane->fb pointers.

Parameters

struct drm_device * dev

drm device to check.

unsigned plane_mask

plane mask for planes that were updated.

int ret

return value, can be -EDEADLK for a retry.

Description

Before doing an update plane->old_fb is set to plane->fb, but before dropping the locks old_fb needs to be set to NULL and plane->fb updated. This is a common operation for each atomic update, so this call is split off as a helper.

void drm_atomic_replace_property_blob(struct drm_property_blob ** blob, struct drm_property_blob * new_blob, bool * replaced)¶

replace a blob property

Parameters

struct drm_property_blob ** blob

a pointer to the member blob to be replaced

struct drm_property_blob * new_blob

the new blob to replace with

bool * replaced

whether the blob has been replaced

Return

Zero on success, error code on failure

int drm_atomic_crtc_get_property(struct drm_crtc * crtc, const struct drm_crtc_state * state, struct drm_property * property, uint64_t * val)¶

get property value from CRTC state

Parameters

struct drm_crtc * crtc

the drm CRTC to set a property on

const struct drm_crtc_state * state

the state object to get the property value from

struct drm_property * property

the property to set

uint64_t * val

return location for the property value

Description

This function handles generic/core properties and calls out to driver’s ->:c:func:atomic_get_property() for driver properties. To ensure consistent behavior you must call this function rather than the driver hook directly.

Return

Zero on success, error code on failure

int drm_atomic_crtc_check(struct drm_crtc * crtc, struct drm_crtc_state * state)¶

check crtc state

Parameters

struct drm_crtc * crtc

crtc to check

struct drm_crtc_state * state

crtc state to check

Description

Provides core sanity checks for crtc state.

Return

Zero on success, error code on failure

int drm_atomic_plane_get_property(struct drm_plane * plane, const struct drm_plane_state * state, struct drm_property * property, uint64_t * val)¶

get property value from plane state

Parameters

struct drm_plane * plane

the drm plane to set a property on

const struct drm_plane_state * state

the state object to get the property value from

struct drm_property * property

the property to set

uint64_t * val

return location for the property value

Description

This function handles generic/core properties and calls out to driver’s ->:c:func:atomic_get_property() for driver properties. To ensure consistent behavior you must call this function rather than the driver hook directly.

Return

Zero on success, error code on failure

int drm_atomic_plane_check(struct drm_plane * plane, struct drm_plane_state * state)¶

check plane state

Parameters

struct drm_plane * plane

plane to check

struct drm_plane_state * state

plane state to check

Description

Provides core sanity checks for plane state.

Return

Zero on success, error code on failure

int drm_atomic_connector_get_property(struct drm_connector * connector, const struct drm_connector_state * state, struct drm_property * property, uint64_t * val)¶

get property value from connector state

Parameters

struct drm_connector * connector

the drm connector to set a property on

const struct drm_connector_state * state

the state object to get the property value from

struct drm_property * property

the property to set

uint64_t * val

return location for the property value

Description

This function handles generic/core properties and calls out to driver’s ->:c:func:atomic_get_property() for driver properties. To ensure consistent behavior you must call this function rather than the driver hook directly.

Return

Zero on success, error code on failure

Frame Buffer Abstraction¶

Frame buffers are abstract memory objects that provide a source of pixels to scanout to a CRTC. Applications explicitly request the creation of frame buffers through the DRM_IOCTL_MODE_ADDFB(2) ioctls and receive an opaque handle that can be passed to the KMS CRTC control, plane configuration and page flip functions.

Frame buffers rely on the underneath memory manager for low-level memory operations. When creating a frame buffer applications pass a memory handle (or a list of memory handles for multi-planar formats) through the drm_mode_fb_cmd2 argument. For drivers using GEM as their userspace buffer management interface this would be a GEM handle. Drivers are however free to use their own backing storage object handles, e.g. vmwgfx directly exposes special TTM handles to userspace and so expects TTM handles in the create ioctl and not GEM handles.

The lifetime of a drm framebuffer is controlled with a reference count, drivers can grab additional references with drm_framebuffer_reference()`and drop them again with :c:func:`drm_framebuffer_unreference(). For driver-private framebuffers for which the last reference is never dropped (e.g. for the fbdev framebuffer when the struct struct drm_framebuffer is embedded into the fbdev helper struct) drivers can manually clean up a framebuffer at module unload time with drm_framebuffer_unregister_private().

DRM Format Handling¶

const char * drm_get_format_name(uint32_t format)¶

return a string for drm fourcc format

Parameters

uint32_t format

format to compute name of

Description

Note that the buffer used by this function is globally shared and owned by the function itself.

FIXME: This isn’t really multithreading safe.

void drm_fb_get_bpp_depth(uint32_t format, unsigned int * depth, int * bpp)¶

get the bpp/depth values for format

Parameters

uint32_t format

pixel format (DRM_FORMAT_*)

unsigned int * depth

storage for the depth value

int * bpp

storage for the bpp value

Description

This only supports RGB formats here for compat with code that doesn’t use pixel formats directly yet.

int drm_format_num_planes(uint32_t format)¶

get the number of planes for format

Parameters

uint32_t format

pixel format (DRM_FORMAT_*)

Return

The number of planes used by the specified pixel format.

int drm_format_plane_cpp(uint32_t format, int plane)¶

determine the bytes per pixel value

Parameters

uint32_t format

pixel format (DRM_FORMAT_*)

int plane

plane index

Return

The bytes per pixel value for the specified plane.

int drm_format_horz_chroma_subsampling(uint32_t format)¶

get the horizontal chroma subsampling factor

Parameters

uint32_t format

pixel format (DRM_FORMAT_*)

Return

The horizontal chroma subsampling factor for the specified pixel format.

int drm_format_vert_chroma_subsampling(uint32_t format)¶

get the vertical chroma subsampling factor

Parameters

uint32_t format

pixel format (DRM_FORMAT_*)

Return

The vertical chroma subsampling factor for the specified pixel format.

int drm_format_plane_width(int width, uint32_t format, int plane)¶

width of the plane given the first plane

Parameters

int width

width of the first plane

uint32_t format

pixel format

int plane

plane index

Return

The width of plane, given that the width of the first plane is width.

int drm_format_plane_height(int height, uint32_t format, int plane)¶

height of the plane given the first plane

Parameters

int height

height of the first plane

uint32_t format

pixel format

int plane

plane index

Return

The height of plane, given that the height of the first plane is height.

Dumb Buffer Objects¶

The KMS API doesn’t standardize backing storage object creation and leaves it to driver-specific ioctls. Furthermore actually creating a buffer object even for GEM-based drivers is done through a driver-specific ioctl - GEM only has a common userspace interface for sharing and destroying objects. While not an issue for full-fledged graphics stacks that include device-specific userspace components (in libdrm for instance), this limit makes DRM-based early boot graphics unnecessarily complex.

Dumb objects partly alleviate the problem by providing a standard API to create dumb buffers suitable for scanout, which can then be used to create KMS frame buffers.

To support dumb objects drivers must implement the dumb_create, dumb_destroy and dumb_map_offset operations.

• int (*dumb_create)(struct drm_file *file_priv, struct drm_device *dev, struct drm_mode_create_dumb *args); The dumb_create operation creates a driver object (GEM or TTM handle) suitable for scanout based on the width, height and depth from the struct struct drm_mode_create_dumb argument. It fills the argument’s handle, pitch and size fields with a handle for the newly created object and its line pitch and size in bytes.
• int (*dumb_destroy)(struct drm_file *file_priv, struct drm_device *dev, uint32_t handle); The dumb_destroy operation destroys a dumb object created by dumb_create.
• int (*dumb_map_offset)(struct drm_file *file_priv, struct drm_device *dev, uint32_t handle, uint64_t *offset); The dumb_map_offset operation associates an mmap fake offset with the object given by the handle and returns it. Drivers must use the drm_gem_create_mmap_offset() function to associate the fake offset as described in ?.

Note that dumb objects may not be used for gpu acceleration, as has been attempted on some ARM embedded platforms. Such drivers really must have a hardware-specific ioctl to allocate suitable buffer objects.

Output Polling¶

void (*output_poll_changed)(struct drm_device *dev); This operation notifies the driver that the status of one or more connectors has changed. Drivers that use the fb helper can just call the drm_fb_helper_hotplug_event() function to handle this operation.

CRTCs (struct drm_crtc)¶

A CRTC is an abstraction representing a part of the chip that contains a pointer to a scanout buffer. Therefore, the number of CRTCs available determines how many independent scanout buffers can be active at any given time. The CRTC structure contains several fields to support this: a pointer to some video memory (abstracted as a frame buffer object), a display mode, and an (x, y) offset into the video memory to support panning or configurations where one piece of video memory spans multiple CRTCs.

Planes (struct drm_plane)¶

A plane represents an image source that can be blended with or overlayed on top of a CRTC during the scanout process. Planes are associated with a frame buffer to crop a portion of the image memory (source) and optionally scale it to a destination size. The result is then blended with or overlayed on top of a CRTC.

The DRM core recognizes three types of planes:

• DRM_PLANE_TYPE_PRIMARY represents a “main” plane for a CRTC. Primary planes are the planes operated upon by CRTC modesetting and flipping operations described in the page_flip hook in struct drm_crtc_funcs.
• DRM_PLANE_TYPE_CURSOR represents a “cursor” plane for a CRTC. Cursor planes are the planes operated upon by the DRM_IOCTL_MODE_CURSOR and DRM_IOCTL_MODE_CURSOR2 ioctls.
• DRM_PLANE_TYPE_OVERLAY represents all non-primary, non-cursor planes. Some drivers refer to these types of planes as “sprites” internally.

For compatibility with legacy userspace, only overlay planes are made available to userspace by default. Userspace clients may set the DRM_CLIENT_CAP_UNIVERSAL_PLANES client capability bit to indicate that they wish to receive a universal plane list containing all plane types.

Encoders (struct drm_encoder)¶

An encoder takes pixel data from a CRTC and converts it to a format suitable for any attached connectors. On some devices, it may be possible to have a CRTC send data to more than one encoder. In that case, both encoders would receive data from the same scanout buffer, resulting in a “cloned” display configuration across the connectors attached to each encoder.

Connectors (struct drm_connector)¶

A connector is the final destination for pixel data on a device, and usually connects directly to an external display device like a monitor or laptop panel. A connector can only be attached to one encoder at a time. The connector is also the structure where information about the attached display is kept, so it contains fields for display data, EDID data, DPMS & connection status, and information about modes supported on the attached displays.

Cleanup¶

The DRM core manages its objects’ lifetime. When an object is not needed anymore the core calls its destroy function, which must clean up and free every resource allocated for the object. Every drm_*_init() call must be matched with a corresponding drm_*_cleanup() call to cleanup CRTCs (drm_crtc_cleanup()), planes (drm_plane_cleanup()), encoders (drm_encoder_cleanup()) and connectors (drm_connector_cleanup()). Furthermore, connectors that have been added to sysfs must be removed by a call to drm_connector_unregister() before calling drm_connector_cleanup().

Connectors state change detection must be cleanup up with a call to drm_kms_helper_poll_fini().

Output discovery and initialization example¶

void intel_crt_init(struct drm_device *dev)
{
    struct drm_connector *connector;
    struct intel_output *intel_output;

    intel_output = kzalloc(sizeof(struct intel_output), GFP_KERNEL);
    if (!intel_output)
        return;

    connector = &intel_output->base;
    drm_connector_init(dev, &intel_output->base,
               &intel_crt_connector_funcs, DRM_MODE_CONNECTOR_VGA);

    drm_encoder_init(dev, &intel_output->enc, &intel_crt_enc_funcs,
             DRM_MODE_ENCODER_DAC);

    drm_mode_connector_attach_encoder(&intel_output->base,
                      &intel_output->enc);

    /* Set up the DDC bus. */
    intel_output->ddc_bus = intel_i2c_create(dev, GPIOA, "CRTDDC_A");
    if (!intel_output->ddc_bus) {
        dev_printk(KERN_ERR, &dev->pdev->dev, "DDC bus registration "
               "failed.\n");
        return;
    }

    intel_output->type = INTEL_OUTPUT_ANALOG;
    connector->interlace_allowed = 0;
    connector->doublescan_allowed = 0;

    drm_encoder_helper_add(&intel_output->enc, &intel_crt_helper_funcs);
    drm_connector_helper_add(connector, &intel_crt_connector_helper_funcs);

    drm_connector_register(connector);
}

In the example above (taken from the i915 driver), a CRTC, connector and encoder combination is created. A device-specific i2c bus is also created for fetching EDID data and performing monitor detection. Once the process is complete, the new connector is registered with sysfs to make its properties available to applications.

KMS API Functions¶

const char * drm_get_connector_status_name(enum drm_connector_status status)¶

return a string for connector status

Parameters

enum drm_connector_status status

connector status to compute name of

Description

In contrast to the other drm_get_*_name functions this one here returns a const pointer and hence is threadsafe.

const char * drm_get_subpixel_order_name(enum subpixel_order order)¶

return a string for a given subpixel enum

Parameters

enum subpixel_order order

enum of subpixel_order

Description

Note you could abuse this and return something out of bounds, but that would be a caller error. No unscrubbed user data should make it here.

struct drm_mode_object * drm_mode_object_find(struct drm_device * dev, uint32_t id, uint32_t type)¶

look up a drm object with static lifetime

Parameters

struct drm_device * dev

drm device

uint32_t id

id of the mode object

uint32_t type

type of the mode object

Description

This function is used to look up a modeset object. It will acquire a reference for reference counted objects. This reference must be dropped again by callind drm_mode_object_unreference().

void drm_mode_object_unreference(struct drm_mode_object * obj)¶

decr the object refcnt

Parameters

struct drm_mode_object * obj

mode_object

Description

This functions decrements the object’s refcount if it is a refcounted modeset object. It is a no-op on any other object. This is used to drop references acquired with drm_mode_object_reference().

void drm_mode_object_reference(struct drm_mode_object * obj)¶

incr the object refcnt

Parameters

struct drm_mode_object * obj

mode_object

Description

This functions increments the object’s refcount if it is a refcounted modeset object. It is a no-op on any other object. References should be dropped again by calling drm_mode_object_unreference().

int drm_framebuffer_init(struct drm_device * dev, struct drm_framebuffer * fb, const struct drm_framebuffer_funcs * funcs)¶

initialize a framebuffer

Parameters

struct drm_device * dev

DRM device

struct drm_framebuffer * fb

framebuffer to be initialized

const struct drm_framebuffer_funcs * funcs

... with these functions

Description

Allocates an ID for the framebuffer’s parent mode object, sets its mode functions & device file and adds it to the master fd list.

IMPORTANT: This functions publishes the fb and makes it available for concurrent access by other users. Which means by this point the fb _must_ be fully set up - since all the fb attributes are invariant over its lifetime, no further locking but only correct reference counting is required.

Return

Zero on success, error code on failure.

struct drm_framebuffer * drm_framebuffer_lookup(struct drm_device * dev, uint32_t id)¶

look up a drm framebuffer and grab a reference

Parameters

struct drm_device * dev

drm device

uint32_t id

id of the fb object

Description

If successful, this grabs an additional reference to the framebuffer - callers need to make sure to eventually unreference the returned framebuffer again, using drm_framebuffer_unreference.

void drm_framebuffer_unregister_private(struct drm_framebuffer * fb)¶

unregister a private fb from the lookup idr

Parameters

struct drm_framebuffer * fb

fb to unregister

Description

Drivers need to call this when cleaning up driver-private framebuffers, e.g. those used for fbdev. Note that the caller must hold a reference of it’s own, i.e. the object may not be destroyed through this call (since it’ll lead to a locking inversion).

void drm_framebuffer_cleanup(struct drm_framebuffer * fb)¶

remove a framebuffer object

Parameters

struct drm_framebuffer * fb

framebuffer to remove

Description

Cleanup framebuffer. This function is intended to be used from the drivers ->destroy callback. It can also be used to clean up driver private framebuffers embedded into a larger structure.

Note that this function does not remove the fb from active usuage - if it is still used anywhere, hilarity can ensue since userspace could call getfb on the id and get back -EINVAL. Obviously no concern at driver unload time.

Also, the framebuffer will not be removed from the lookup idr - for user-created framebuffers this will happen in in the rmfb ioctl. For driver-private objects (e.g. for fbdev) drivers need to explicitly call drm_framebuffer_unregister_private.

void drm_framebuffer_remove(struct drm_framebuffer * fb)¶

remove and unreference a framebuffer object

Parameters

struct drm_framebuffer * fb

framebuffer to remove

Description

Scans all the CRTCs and planes in dev‘s mode_config. If they’re using fb, removes it, setting it to NULL. Then drops the reference to the passed-in framebuffer. Might take the modeset locks.

Note that this function optimizes the cleanup away if the caller holds the last reference to the framebuffer. It is also guaranteed to not take the modeset locks in this case.

int drm_crtc_init_with_planes(struct drm_device * dev, struct drm_crtc * crtc, struct drm_plane * primary, struct drm_plane * cursor, const struct drm_crtc_funcs * funcs, const char * name, ...)¶

Initialise a new CRTC object with specified primary and cursor planes.

Parameters

struct drm_device * dev

DRM device

struct drm_crtc * crtc

CRTC object to init

struct drm_plane * primary

Primary plane for CRTC

struct drm_plane * cursor

Cursor plane for CRTC

const struct drm_crtc_funcs * funcs

callbacks for the new CRTC

const char * name

printf style format string for the CRTC name, or NULL for default name

...

variable arguments

Description

Inits a new object created as base part of a driver crtc object.

Return

Zero on success, error code on failure.

void drm_crtc_cleanup(struct drm_crtc * crtc)¶

Clean up the core crtc usage

Parameters

struct drm_crtc * crtc

CRTC to cleanup

Description

This function cleans up crtc and removes it from the DRM mode setting core. Note that the function does not free the crtc structure itself, this is the responsibility of the caller.

int drm_display_info_set_bus_formats(struct drm_display_info * info, const u32 * formats, unsigned int num_formats)¶

set the supported bus formats

Parameters

struct drm_display_info * info

display info to store bus formats in

const u32 * formats

array containing the supported bus formats

unsigned int num_formats

the number of entries in the fmts array

Description

Store the supported bus formats in display info structure. See MEDIA_BUS_FMT_* definitions in include/uapi/linux/media-bus-format.h for a full list of available formats.

int drm_connector_init(struct drm_device * dev, struct drm_connector * connector, const struct drm_connector_funcs * funcs, int connector_type)¶

Init a preallocated connector

Parameters

struct drm_device * dev

DRM device

struct drm_connector * connector

the connector to init

const struct drm_connector_funcs * funcs

callbacks for this connector

int connector_type

user visible type of the connector

Description

Initialises a preallocated connector. Connectors should be subclassed as part of driver connector objects.

Return

Zero on success, error code on failure.

void drm_connector_cleanup(struct drm_connector * connector)¶

cleans up an initialised connector