+ Architecture of a DRM driver +i ---------------------------- + +Written by Laurent Pinchart <laurent.pinchart@ideasonboard.com> +Last revised: May 30, 2012 + + +1. Driver initialization +------------------------ + +- Create a static struct drm_driver instance and register it at probe() time + with drm_platform_init(). This will call the DRM driver load() method, if + provided (why would the method not be provided?). + + - int (*load) (struct drm_device *, unsigned long flags) + + The method takes two arguments, a pointer to the newly created drm_device + and flags. The flags are used to pass the driver_data field of the device id + corresponding to the device passed to drm_*_init(). Only PCI devices + currently use this, USB and platform DRM drivers have their load() method + called with flags to 0. + + The load method is responsible for performing resource allocation, hardware + initialization and DRM initialization. See the IRQ registration and KMS + initialization sections. + + - int (*firstopen) (struct drm_device *) + - void (*lastclose) (struct drm_device *) + - int (*open) (struct drm_device *, struct drm_file *) + - void (*preclose) (struct drm_device *, struct drm_file *) + - void (*postclose) (struct drm_device *, struct drm_file *) + + Open and close handlers. None of those methods are mandatory. + + The .firstopen() method is called by the DRM core when an application opens + a device that has no other opened file handle. Similarly the .lastclose() + method is called when the last application holding a file handle opened on + the device closes it. Both methods are mostly used for UMS (User Mode + Setting) drivers to acquire and release device resources which should be + done in the .load() and .unload() methods for KMS drivers. + + Note that the .lastclose() method is also called at module unload time or, + for hot-pluggable devices, when the device is unplugged. The .firstopen() + and .lastclose() calls can thus be unbalanced. + + The .open() method is called every time the device is opened by an + application. Drivers can allocate per-file private data in this method and + store them in the struct drm_file::driver_priv field. Note that the .open() + method is called before .firstopen(). + + The close operation is split into .preclose() and .postclose() methods. + Drivers must stop and cleanup all per-file operations in the .preclose() + method. For instance pending vertical blanking and page flip events must be + cancelled. No per-file operation is allowed on the file handle after + returning from the .preclose() method. + + Finally the .postclose() method is called as the last step of the close + operation, right before calling the .lastclose() method if no other open + file handle exists for the device. Drivers that have allocated per-file + private data in the .open() method should free it here. + + - int (*suspend) (struct drm_device *, pm_message_t state) + - int (*resume) (struct drm_device *) + + Legacy suspend and resume methos. New driver should use the power management + interface provided by their bus type (usually through the struct + device_driver dev_pm_ops) and set these methods to NULL. + + - int (*enable_vblank) (struct drm_device *dev, int crtc) + - void (*disable_vblank) (struct drm_device *dev, int crtc) + - u32 (*get_vblank_counter) (struct drm_device *dev, int crtc) + + Enable and disable vertical blanking interrupts and get the value of the + vblank counter for the given CRTC. See the Vertical Blanking and Page + Flipping section. + + - int (*gem_init_object) (struct drm_gem_object *obj) + - void (*gem_free_object) (struct drm_gem_object *obj) + + GEM object initialization and free handlers. The initialization handler is + only used in special cases and is optional. See the Memory Management + section. + + - int (*prime_handle_to_fd)(struct drm_device *dev, + struct drm_file *file_priv, uint32_t handle, + uint32_t flags, int *prime_fd) + - int (*prime_fd_to_handle)(struct drm_device *dev, + struct drm_file *file_priv, int prime_fd, + uint32_t *handle) + - struct dma_buf * (*gem_prime_export)(struct drm_device *dev, + struct drm_gem_object *obj, + int flags) + - struct drm_gem_object * (*gem_prime_import)(struct drm_device *dev, + struct dma_buf *dma_buf) + + DRM PRIME file descriptor management. See the Memory Management section. + + - int (*dumb_create)(struct drm_file *file_priv, struct drm_device *dev, + struct drm_mode_create_dumb *args) + - int (*dumb_map_offset)(struct drm_file *file_priv, struct drm_device *dev, + uint32_t handle, uint64_t *offset) + - int (*dumb_destroy)(struct drm_file *file_priv, struct drm_device *dev, + uint32_t handle) + + Dumb GEM frame buffers management. See the Memory Management section. + + - struct vm_operations_struct *gem_vm_ops + + VMA operations for GEM objects. See the Memory Management section. + + - major, minor, patchlevel + + The driver major, minor and patch level versions, printed to the kernel log + at initialization time and passed to userspace through DRM_IOCTL_VERSION. + + The major and minor numbers are also used to verify the requested driver API + version passed to DRM_IOCTL_SET_VERSION. When the driver API changes between + minor versions, applications can call DRM_IOCTL_SET_VERSION to select a + specific version of the API. If the requested major isn't equal to the + driver major, or the requested minor is larger than the driver minor, the + DRM_IOCTL_SET_VERSION call will return an error. Otherwise the driver's + set_version() method is called with the requested version. + + - name + + The driver name, printed to the kernel log at initialization time, used for + IRQ registration and passed to userspace through DRM_IOCTL_VERSION. + + - desc + + The driver description, passed to userspace through DRM_IOCTL_VERSION. + + - date + + The driver date as a string, printed to the kernel log at initialization time + and passed to userspace through DRM_IOCTL_VERSION. + + - features + + Bitfield of driver capabilities and requirements, used by the DRM core to + decide whether and how to implement parts of the DRM API. + + DRIVER_USE_AGP - The DRM core will manage AGP resources + DRIVER_REQUIRE_AGP - Make AGP initialization failure a fatal error + DRIVER_USE_MTRR - The DRM core will manage MTRR resources + DRIVER_PCI_DMA - Enable mapping of PCI DMA buffers to userspace + DRIVER_SG - Enable SG buffers allocation and mapping + DRIVER_HAVE_DMA - Enable userspace DMA API + DRIVER_HAVE_IRQ - Make the DRM core register an interrupt handler + DRIVER_IRQ_SHARED - Make the interrupt handler shared + DRIVER_IRQ_VBL - Unused + DRIVER_DMA_QUEUE - ??? + DRIVER_FB_DMA - Enable mapping of framebuffer DMA buffer to userspace + DRIVER_IRQ_VBL2 - Unused + DRIVER_GEM - Use the GEM memory manager + DRIVER_MODESET - The driver implements the KMS API + DRIVER_PRIME - The driver implements DRM PRIME buffer sharing + + - struct drm_ioctl_desc *ioctls + - int num_ioctls + + Driver-specific ioctls descriptors table. + + Driver-specific ioctls numbers start at DRM_COMMAND_BASE. The ioctls + descriptors table is indexed by the ioctl number offset from the base value. + Drivers can use the DRM_IOCTL_DEF_DRV() macro to initialize the table + entries. + + DRM_IOCTL_DEF_DRV(ioctl, func, flags) + + - ioctl is the ioctl name. Drivers must define the DRM_##ioctl and + DRM_IOCTL_##ioctl macros to the ioctl number offset from + DRM_COMMAND_BASE and the ioctl number respectively. The first macro is + private to the device while the second must be exposed to userspace in a + public header. + + - func is a pointer to the ioctl handler function compatible with the + drm_ioctl_t type. + + typedef int drm_ioctl_t(struct drm_device *dev, void *data, + struct drm_file *file_priv); + + - flags is a bitmask combination of the following values. It restricts how + the ioctl is allowed to be called. + + DRM_AUTH - Only authenticated callers allowed + DRM_MASTER - The ioctl can only be called on the master file handle + DRM_ROOT_ONLY - Only callers with the SYSADMIN capability allowed + DRM_CONTROL_ALLOW - The ioctl can only be called on a control device + DRM_UNLOCKED - The ioctl handler will be called without locking the DRM + global mutex. + + - const struct file_operations *fops + + File operations for the DRM device node. + + Drivers must define the file operations structure that forms the DRM + userspace API entry point, even though most of those operations are + implemented in the DRM core. The open, release and ioctl operations are + handled by + + .owner = THIS_MODULE, + .open = drm_open, + .release = drm_release, + .unlocked_ioctl = drm_ioctl, + #ifdef CONFIG_COMPAT + .compat_ioctl = drm_compat_ioctl, + #endif + + Drivers that implement private ioctls that requires 32/64bit compatibility + support must provide their own .compat_ioctl() handler that processes + private ioctls and calls drm_compat_ioctl() for core ioctls. + + The read and poll operations provide support for reading DRM events and + polling them. They are implemented by + + .poll = drm_poll, + .read = drm_read, + .fasync = drm_fasync, + .llseek = no_llseek, + + The memory mapping implementation varies depending on how the driver manages + memory. Pre-GEM drivers will use drm_mmap(), while GEM-aware drivers will + use drm_gem_mmap(). See the Memory Management section for more details. + + .mmap = drm_gem_mmap, + + No other file operation is supported by the DRM API. + + +2. IRQ registration +------------------- + +The DRM core tries to facilitate IRQ handler registration and unregistration +by providing drm_irq_install() and drm_irq_uninstall() methods. Those methods +only support a single interrupt per device. + +Both functions get the device IRQ by calling drm_dev_to_irq(). This inline +function will call a bus-specific operation to retrieve the IRQ number. For +platform devices, platform_get_irq(..., 0) is used to retrieve the IRQ number. + +drm_irq_install() starts by calling the irq_preinstall() driver operation. The +operation is optional and must make sure that the interrupt will not get fired +by clearing all pending interrupt flags or disabling the interrupt. + +The IRQ will then be requested by a call to request_irq(). If the +DRIVER_IRQ_SHARED driver feature flag is set, a shared (IRQF_SHARED) IRQ +handler will be requested. + +The IRQ handler function must be provided as the mandatory irq_handler driver +operation. It will get passed directly to request_irq() and thus has the same +prototype as all IRQ handlers. It will get called with a pointer to the DRM +device as the second argument. + +Finally the function calls the optional irq_postinstall() driver operation. +The operation usually enables interrupts (excluding the vblank interrupt, +which is enabled separately), but drivers may choose to enable/disable +interrupts at a different time. + +drm_irq_uninstall() is similarly used to uninstall an IRQ handler. It starts +by waking up all processes waiting on a vblank interrupt to make sure they +don't hang, and then calls the optional irq_uninstall() driver operation. The +operation must disable all hardware interrupts. Finally the function frees the +IRQ by calling free_irq(). + + +3. KMS initialization +--------------------- + +Drivers must first initialize the mode configuration core by calling +drm_mode_config_init() on the DRM device. The function initializes the +drm_device::mode_config field and never fails. Once done, mode configuration +must be setup by + + - int min_width, min_height + - int max_width, max_height + + Minimum and maximum width and height of the frame buffers in pixel units. + + - struct drm_mode_config_funcs *funcs + + Basic mode setting functions. See the Mode Setting Operations section for + details. + + +A KMS device is abstracted and exposed as a set of planes, CRTCs, encoders and +connectors. KMS drivers must thus create and initialize all those objects at +load time. + +- CRCTs (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." + +A KMS device must create and register at least one struct drm_crtc instance. +The instance is allocated and zeroed by the driver, possibly as part of a +larger structure, and registered with a call to drm_crtc_init() with a pointer +to CRTC functions. + +- 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. + +Planes are optional. To create a plane, a KMS drivers allocates and zeroes an +instances of struct drm_plane (possible as part of a larger structure) and +registers it with a call to drm_plane_init(). The function takes a bitmask of +the CRTCs that can be associated with the plane, a pointer to the plane +functions and a list of format supported formats. + +- 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." + +As for CRTCs, a KMS driver must create, initialize and register at least one +struct drm_encoder instance. The instance is allocated and zeroed by the +driver, possibly as part of a larger structure. + +Drivers must initialize the struct drm_encoder possible_crtcs and +possible_clones fields before registering the encoder. Both fields are +bitmasks of respectively the CRTCs that the encoder can be connected to, and +sibling encoders candidate for cloning. + +After being initialized, the encoder must be registered with a call to +drm_encoder_init(). The function takes a pointer to the encoder functions and +an encoder type. Supported types are + + DRM_MODE_ENCODER_DAC for VGA and analog on DVI-I/DVI-A + DRM_MODE_ENCODER_TMDS for DVI, HDMI and (embedded) DisplayPort + DRM_MODE_ENCODER_LVDS for display panels + DRM_MODE_ENCODER_TVDAC for TV output (Composite, S-Video, Component, SCART) + DRM_MODE_ENCODER_VIRTUAL for virtual machine displays + +Encoders must be attached to a CRTC to be used. DRM drivers leave encoders +unattached at initialization time. Applications (or the fbdev compatibility +layer when implemented) are responsible for attaching the encoders they want +to use to a CRTC. + +- 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." + +Finally a KMS driver must create, initialize, register and attach at least one +struct drm_connector instance. The instance is created as other KMS objects +and initialized by setting the following fields. + + interlace_allowed - whether the connector can handle interlaced modes + doublescan_allowed - whether the connector can handle doublescan + display_info - display information + + Display information is filled from EDID information when a display is + detected. For non hot-pluggable displays such as flat panels in embedded + systems, the driver should initialize the display_info.width_mm and + display_info.height_mm fields with the physical size of the display. + + polled - connector polling mode, a combination of + + DRM_CONNECTOR_POLL_HPD + The connector generates hotplug events and doesn't need to be + periodically polled. The CONNECT and DISCONNECT flags must not be set + together with the HPD flag. + DRM_CONNECTOR_POLL_CONNECT + Periodically poll the connector for connection. + DRM_CONNECTOR_POLL_DISCONNECT + Periodically poll the connector for disconnection. + + Set to 0 for connectors that don't support connection status discovery. + +The connector is then registered with a call to drm_connector_init() which +a pointer to the connector functions and a connector type, and exposed through +sysfs with a call to drm_sysfs_connector_add(). + +Supported connector types are + + DRM_MODE_CONNECTOR_VGA + DRM_MODE_CONNECTOR_DVII + DRM_MODE_CONNECTOR_DVID + DRM_MODE_CONNECTOR_DVIA + DRM_MODE_CONNECTOR_Composite + DRM_MODE_CONNECTOR_SVIDEO + DRM_MODE_CONNECTOR_LVDS + DRM_MODE_CONNECTOR_Component + DRM_MODE_CONNECTOR_9PinDIN + DRM_MODE_CONNECTOR_DisplayPort + DRM_MODE_CONNECTOR_HDMIA + DRM_MODE_CONNECTOR_HDMIB + DRM_MODE_CONNECTOR_TV + DRM_MODE_CONNECTOR_eDP + DRM_MODE_CONNECTOR_VIRTUAL + +Connectors must be attached to an encoder to be used. For devices that map +connectors to encoders 1:1, the connector should be attached at initialization +time with a call to drm_mode_connector_attach_encoder(). The driver must also +set the drm_connector::encoder field to point to the attached encoder. + + +Finally, drivers must initialize the connectors state change detection with a +call to drm_kms_helper_poll_init(). If at least one connector is pollable but +can't generate hotplug interrupts (indicated by the DRM_CONNECTOR_POLL_CONNECT +and DRM_CONNECTOR_POLL_DISCONNECT connector flags), a delayed work will +automatically be queued to periodically poll for changes. Connectors that can +generate hotplug interrupts must be marked with the DRM_CONNECTOR_POLL_HPD +flag instead, and their interrupt handler must call +drm_helper_hpd_irq_event(). The function will queue a delayed work to check +the state of all connectors, but no periodic polling will be done. + + +4. KMS 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_sysfs_connector_remove() +before calling drm_connector_cleanup(). + +Connectors state change detection must be cleanup up with a call to +drm_kms_helper_poll_fini(). + + +5. Vertical Blanking +-------------------- + +Vertical blanking plays a major role in graphics rendering. To achieve +tear-free display, users must synchronize page flips and/or rendering to +vertical blanking. The DRM API offers ioctls to perform page flips +synchronized to vertical blanking and wait for vertical blanking. + +The DRM core handles most of the vertical blanking management logic, which +involves filtering out spurious interrupts, keeping race-free blanking +counters, coping with counter wrap-around and resets and keeping use counts. +It relies on the driver to generate vertical blanking interrupts and +optionally provide a hardware vertical blanking counter. Drivers must +implement the following operations. + + - int (*enable_vblank) (struct drm_device *dev, int crtc) + - void (*disable_vblank) (struct drm_device *dev, int crtc) + + Enable or disable vertical blanking interrupts for the given CRTC. + + - u32 (*get_vblank_counter) (struct drm_device *dev, int crtc) + + Retrieve the value of the vertical blanking counter for the given CRTC. If + the hardware maintains a vertical blanking counter its value should be + returned. Otherwise drivers can use the drm_vblank_count() helper function + to handle this operation. + +Drivers must initialize the vertical blanking handling core with a call to +drm_vblank_init() in their .load() operation. The function will set the struct +drm_device vblank_disable_allowed field to 0. This will keep vertical blanking +interrupts enabled permanently until the first mode set operation, where +vblank_disable_allowed is set to 1. The reason behind this is not clear. +Drivers can set the field to 1 after calling drm_vblank_init() to make +vertical blanking interrupts dynamically managed from the beginning. + +Vertical blanking interrupts can be enabled by the DRM core or by drivers +themselves (for instance to handle page flipping operations). The DRM core +maintains a vertical blanking use count to ensure that the interrupts are not +disabled while a user still needs them. To increment the use count, drivers +call drm_vblank_get(). Upon return vertical blanking interrupts are guaranteed +to be enabled. + +To decrement the use count drivers call drm_vblank_put(). Only when the use +count drops to zero will the DRM core disable the vertical blanking +interrupts after a delay by scheduling a timer. The delay is accessible +through the vblankoffdelay module parameter or the drm_vblank_offdelay global +variable and expressed in milliseconds. Its default value is 5000 ms. + +When a vertical blanking interrupt occurs drivers only need to call the +drm_handle_vblank() function to account for the interrupt. + +Resources allocated by drm_vblank_init() must be freed with a call to +drm_vblank_cleanup() in the driver .unload() operation handler. + + +6. Memory Management +-------------------- + +Modern Linux systems require large amount of graphics memory to store frame +buffers, textures, vertices and other graphics-related data. Given the very +dynamic nature of many of that data, managing graphics memory efficiently is +thus crucial for the graphics stack and plays a central role in the DRM +infrastructure. + +The DRM core includes two memory managers, namely Translation Table Maps (TTM) +and Graphics Execution Manager (GEM). TTM was the first DRM memory manager to +be developed and tried to be a one-size-fits-them all solution. It provides a +single userspace API to accomodate the need of all hardware. This resulted in +a large, complex piece of code that turned out to be hard to use for driver +development and. + +GEM started as an Intel-sponsored project in reaction to TTM's complexity. Its +design philosophy is completely different: instead of providing a solution to +every graphics memory-related problems, GEM identified common code between +drivers and created a support library to share it. + +This document describes the use of the GEM memory manager only. + +The GEM design approach has resulted in a memory manager that doesn't provide +full coverage of all (or even all common) use cass 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 http://lwn.net/Articles/283798/. 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. + +- GEM Initialization + + Drivers that use GEM must set the DRIVER_GEM bit in the struct drm_driver + driver_features field. The DRM core will then automatically initialize the + GEM core before calling the .load() operation. + +- GEM Objects Creation + + GEM splits creation of GEM objects and allocation of the memory that backs + them in two distinct operations. + + GEM objects are represented by an instance of struct drm_gem_object. Drivers + usually need to extend GEM objects with private information and thus create + a driver-specific GEM object structure type that embeds an instance of + struct drm_gem_object. + + To create a GEM object, a driver allocates memory for an instance of its + specific GEM object type and initializes the embedded struct drm_gem_object + with a call to drm_gem_object_init(). The function takes a pointer to the + DRM device, a pointer to the GEM object and the buffer object size in bytes. + + GEM automatically allocate anonymous pageable memory through shmfs when an + object is initialized. drm_gem_object_init() will create an shmfs file of + the requested size and store it into the struct drm_gem_object filp field. + The memory is used as either main storage for the object when the graphics + hardware uses system memory directly or as a backing store otherwise. + + Anonymous pageable memory allocation is not always desired, for instance + when the hardware requires physically contiguous system memory as is often + the case in embedded devices. Drivers can create GEM objects with no shmfs + backing (called private GEM objects) by initializing them with a call to + drm_gem_private_object_init() instead of drm_gem_object_init(). Storage for + private GEM objects must be managed by drivers. + + Drivers that do no need to extend GEM objects with private information can + call the drm_gem_object_alloc() function to allocate and initialize a struct + drm_gem_object instance. The GEM core will call the optional driver + .gem_init_object() operation after initializing the GEM object with + drm_gem_object_init(). + + int (*gem_init_object) (struct drm_gem_object *obj) + + No alloc-and-init function exists for private GEM objects. + +- GEM Objects Lifetime + + All GEM objects are reference-counted by the GEM core. References can be + acquired and release by calling drm_gem_object_reference() and + drm_gem_object_unreference() respectively. The caller must hold the + drm_device struct_mutex lock. As a convenience, GEM provides the + drm_gem_object_reference_unlocked() and + drm_gem_object_unreference_unlocked() functions that can be called without + holding the lock. + + When the last reference to a GEM object is released the GEM core calls the + drm_driver .gem_free_object() operation. That operation is mandatory for + GEM-enabled drivers and must free the GEM object and all associated + resources. + + void (*gem_free_object) (struct drm_gem_object *obj) + + Drivers are responsible for freeing all GEM object resources, including the + resources created by the GEM core. If an mmap offset has been created for + the object (in which case drm_gem_object::map_list::map is not NULL) it must + be freed by a call to drm_gem_free_mmap_offset(). The shmfs backing store + must be released by calling drm_gem_object_release() (that function can + safely be called if no shmfs backing store has been created). + +- GEM Objects Naming + + Communication between userspace and the kernel refers to GEM objects using + local handles, global names or, more recently, file descriptors. All of + those are 32-bit integer values; the usual Linux kernel limits apply to the + file descriptors. + + GEM handles are local to a DRM file. Applications get a handle to a GEM + object through a driver-specific ioctl, and can use that handle to refer + to the GEM object in other standard or driver-specific ioctls. Closing a DRM + file handle frees all its GEM handles and dereferences the associated GEM + objects. + + To create a handle for a GEM object drivers call drm_gem_handle_create(). + The function takes a pointer to the DRM file and the GEM object and returns + a locally unique handle. When the handle is no longer needed drivers delete + it with a call to drm_gem_handle_delete(). Finally the GEM object associated + with a handle can be retrieved by a call to drm_gem_object_lookup(). + + GEM names are similar in purpose to handles but are not local to DRM files. + They can be passed between processes to reference a GEM object globally. + Names can't be used directly to refer to objects in the DRM API, + applications must convert handles to names and names to handles using the + DRM_IOCTL_GEM_FLINK and DRM_IOCTL_GEM_OPEN ioctls respectively. The + conversion is handled by the DRM core without any driver-specific support. + + Similar to global names, GEM file descriptors are also used to share GEM + objects across processes. They offer additional security: as file + descriptors must be explictly sent over UNIX domain sockets to be shared + between applications, they can't be guessed like the globally unique GEM + names. + + Drivers that support GEM file descriptors, also known as the DRM PRIME API, + must set the DRIVER_PRIME bit in the struct drm_driver driver_features field + and implement the .prime_handle_to_fd() and .prime_fd_to_handle() + operations. + + int (*prime_handle_to_fd)(struct drm_device *dev, + struct drm_file *file_priv, uint32_t handle, + uint32_t flags, int *prime_fd) + int (*prime_fd_to_handle)(struct drm_device *dev, + struct drm_file *file_priv, int prime_fd, + uint32_t *handle) + + Those two operations convert a GEM handle to a PRIME file descriptor and + vice versa. While the PRIME file descriptors can be specific to a device, + their true power come from making them shareable between multiple devices + using the cross-subsystem dma-buf buffer sharing framework. For that reason + drivers are advised to use the drm_gem_prime_handle_to_fd() and + drm_gem_prime_fd_to_handle() helper functions as their PRIME operations + handlers. + + The dma-buf PRIME helpers rely on the driver .gem_prime_export() and + .gem_prime_import() operations to create a dma-buf instance from a GEM + object (exporter role) and to create a GEM object from a dma-buf instance + (importer role). These two operations are mandatory when using dma-buf with + DRM PRIME. + +- GEM Objects Mapping + + Because mapping operations are fairly heavyweight GEM favours read/write- + like access to buffers, implemented through driver-specific ioctls, over + mapping buffers to userspace. However, when random access to the buffer is + needed (to perform software rendering for instance), direct access to the + object can be more efficient. + + The mmap system call can't be used directly to map GEM objects, as they + don't have their own file handle. Two alternative methods currently co-exist + to map GEM objects to userspace. The first method uses a driver-specific + ioctl to perform the mapping operation, calling do_mmap() under the hood. + This is often considered dubious, seems to be discouraged for new + GEM-enabled driver, and will thus not be described here. + + The second method uses the mmap system call on the DRM file handle. + + void *mmap(void *addr, size_t length, int prot, int flags, int fd, + off_t offset) + + DRM identifies the GEM object to be mapped by a fake offset passed through + the mmap offset argument. Prior to being mapped, a GEM object must thus be + associated with a fake offset. To do so, drivers must call + drm_gem_create_mmap_offset() on the object. The function allocates a fake + offset range from a pool and stores the offset divided by PAGE_SIZE in + obj->map_list.hash.key. Care must be taken not to call + drm_gem_create_mmap_offset() if a fake offset has already been allocated for + the object. This can be tested by obj->map_list.map being non-NULL. + + Once allocated, the fake offset value (obj->map_list.hash.key << PAGE_SHIFT) + must be passed to the application in a driver-specific way and can then be + used as the mmap offset argument. + + The GEM core provides a helper method drm_gem_mmap() to handle object + mapping. The method can be set directly as the mmap file operation handler. + It will look up the GEM object based on the offset value and set the VMA + operations to the drm_driver gem_vm_ops field. Note that drm_gem_mmap() + doesn't map memory to userspace, but relies on the driver-provided fault + handler to map pages individually. + + To use drm_gem_mmap(), drivers must fill the struct drm_driver gem_vm_ops + field with a pointer to VM operations. + + struct vm_operations_struct *gem_vm_ops + + struct vm_operations_struct { + void (*open)(struct vm_area_struct * area); + void (*close)(struct vm_area_struct * area); + int (*fault)(struct vm_area_struct *vma, struct vm_fault *vmf); + } + + The open and close operations must update the GEM object reference count. + Drivers can use the drm_gem_vm_open() and drm_gem_vm_close() helper + functions directly as open and close handlers. + + The fault operation handler is responsible for mapping individual pages to + userspace when a page fault occurs. Depending on the memory allocation + scheme, drivers can allocate pages at fault time, or can decide to allocate + memory for the GEM object at the time the object is created. + + Drivers that want to map the GEM object upfront instead of handling page + faults can implement their own mmap file operation handler. + +- Dumb GEM Objects + + The GEM API doesn't standardize GEM objects creation and leaves it to + driver-specific ioctls. 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 GEM 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 GEM 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 GEM object suitable for scanout based + on the width, height and depth from the struct drm_mode_create_dumb + argument. It fills the argument's handle, pitch and size fields with a + handle for the newly created GEM 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 GEM 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 GEM + 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 the GEM Objects Mapping section. + + +7. Mid-layer +------------ + +The CRTC, encoder and connector functions provided by the drivers implement +the DRM API. They're called by the DRM core and ioctl handlers to handle +device state changes and configuration request. As implementing those +functions often requires logic not specific to drivers, mid-layer helper +functions are available to avoid duplicating boilerplate code. + +The DRM core contains one mid-layer implementation. The mid-layer provides +implementations of several CRTC, encoder and connector functions (called from +the top of the mid-layer) that pre-process requests and call lower-level +functions provided by the driver (at the bottom of the mid-layer). For +instance, the drm_crtc_helper_set_config() function can be used to fill the +struct drm_crtc_funcs set_config field. When called, it will split the +set_config operation in smaller, simpler operations and call the driver to +handle them. + +To use the mid-layer, drivers call drm_crtc_helper_add(), +drm_encoder_helper_add() and drm_connector_helper_add() functions to install +their mid-layer bottom operations handlers, and fill the drm_crtc_funcs, +drm_encoder_funcs and drm_connector_funcs structures with pointers to the +mid-layer top API functions. Installing the mid-layer bottom operation +handlers is best done right after registering the corresponding KMS object. + +The mid-layer is not split between CRTC, encoder and connector operations. To +use it, a driver must provide bottom functions for all of the three KMS +entities. + + +8. Mode Setting Operations +-------------------------- + +- struct drm_framebuffer *(*fb_create)(struct drm_device *dev, + struct drm_file *file_priv, + struct drm_mode_fb_cmd2 *mode_cmd) + + Create a new frame buffer. + + 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. This document assumes that the driver uses GEM, + those handles thus reference GEM objects. + + Drivers must first validate the requested frame buffer parameters passed + through the mode_cmd argument. In particular this is where invalid sizes, + pixel formats or pitches can be caught. + + If the parameters are deemed valid, drivers then create, initialize and + return an instance of struct drm_framebuffer. If desired the instance can be + embedded in a larger driver-specific structure. The new instance is + initialized with a call to drm_framebuffer_init() which takes a pointer to + DRM frame buffer operations (struct drm_framebuffer_funcs). Frame buffer + operations are + + - int (*create_handle)(struct drm_framebuffer *fb, + struct drm_file *file_priv, unsigned int *handle) + + Create a handle to the frame buffer underlying memory object. If the frame + buffer uses a multi-plane format, the handle will reference the memory + object associated with the first plane. + + Drivers call drm_gem_handle_create() to create the handle. + + - void (*destroy)(struct drm_framebuffer *framebuffer) + + Destroy the frame buffer object and frees all associated resources. + Drivers must call drm_framebuffer_cleanup() to free resources allocated by + the DRM core for the frame buffer object, and must make sure to + unreference all memory objects associated with the frame buffer. Handles + created by the .create_handle() operation are released by the DRM core. + + - int (*dirty)(struct drm_framebuffer *framebuffer, + struct drm_file *file_priv, unsigned flags, unsigned color, + struct drm_clip_rect *clips, unsigned num_clips) + + This optional operation notifies the driver that a region of the frame + buffer has changed in response to a DRM_IOCTL_MODE_DIRTYFB ioctl call. + + After initializing the drm_framebuffer instance drivers must fill its width, + height, pitches, offsets, depth, bits_per_pixel and pixel_format fields from + the values passed through the drm_mode_fb_cmd2 argument. They should call + the drm_helper_mode_fill_fb_struct() helper function to do so. + +- 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 fbdev helper can just call the + drm_fb_helper_hotplug_event() function to handle this operation. + + +9. CRTC Operations +------------------- + +- void (*gamma_set)(struct drm_crtc *crtc, u16 *r, u16 *g, u16 *b, + uint32_t start, uint32_t size) + + Apply a gamma table to the device. The operation is optional. + +- void (*destroy)(struct drm_crtc *crtc) + + Destroy the CRTC when not needed anymore. See the KMS cleanup section. + +- int (*set_config)(struct drm_mode_set *set) + + Apply a new CRTC configuration to the device. The configuration specifies a + CRTC, a frame buffer to scan out from, a (x,y) position in the frame buffer, + a display mode and an array of connectors to drive with the CRTC if + possible. + + If the frame buffer specified in the configuration is NULL, the driver must + detach all encoders connected to the CRTC and all connectors attached to + those encoders and disable them. + + This operation is called with the mode config lock held. + + (FIXME: How should set_config interact with DPMS? If the CRTC is suspended, + should it be resumed?) + + The mid-layer provides a drm_crtc_helper_set_config() helper function. The + helper will try to locate the best encoder for each connector by calling the + connector .best_encoder helper operation. That operation is mandatory and + must return a pointer to the best encoder for the connector. For devices + that map connectors to encoders 1:1, the function simply returns the pointer + to the associated encoder. + + After locating the appropriate encoders, the helper function will call the + mandatory mode_fixup encoder and CRTC helper operations. + + - bool (*mode_fixup)(struct drm_encoder *encoder, + const struct drm_display_mode *mode, + struct drm_display_mode *adjusted_mode) + - bool (*mode_fixup)(struct drm_crtc *crtc, + const struct drm_display_mode *mode, + struct drm_display_mode *adjusted_mode) + + (FIXME: Should the mode argument be const? The i915 driver modifies + mode->clock in intel_dp_mode_fixup().) + + Let encoders and CRTC adjust the requested mode or reject it completely. + Those operations return true if the mode is accepted (possibly after being + adjusted) or false if it is rejected. + + The mode_fixup operation should reject the mode if it can't reasonably use + it. The definition of "reasonable" is currently fuzzy in this context. One + possible behaviour would be to set the adjusted mode to the panel timings + when a fixed-mode panel is used with hardware capable of scaling. Anothe + behaviour would be to accept any input mode and adjust it to the closest + mode supported by the hardware (FIXME: This needs to be clarified). + + If the new configuration after mode adjustment is identical to the current + configuration the helper function will return without performing any other + operation. + + If the adjusted mode is identical to the current mode but changes to the + frame buffer need to be applied, the drm_crtc_helper_set_config() function + will call the CRTC .mode_set_base() helper operation. + + - int (*mode_set_base)(struct drm_crtc *crtc, int x, int y, + struct drm_framebuffer *old_fb) + + Move the CRTC on the current frame buffer (stored in crtc->fb) to position + (x,y). Any of the frame buffer, x position or y position may have been + modified. + + This helper operation is optional. If not provided, the + drm_crtc_helper_set_config() function will fall back to the .mode_set() + helper operation. + + (FIXME: Why are x and y passed as arguments, as they can be accessed + through crtc->x and crtc->y?) + + If the adjusted mode differs from the current mode, or if the + .mode_set_base() helper operation is not provided, the helper function + performs a full mode set sequence by calling the following mandatory + CRTC and encoder operations in order. + + - void (*prepare)(struct drm_encoder *encoder) + - void (*prepare)(struct drm_crtc *crtc) + + Those operations are called after validating the requested mode. Drivers + use them to perform device-specific operations required before setting the + new mode. + + - int (*mode_set)(struct drm_crtc *crtc, struct drm_display_mode *mode, + struct drm_display_mode *adjusted_mode, int x, int y, + struct drm_framebuffer *old_fb) + - void (*mode_set)(struct drm_encoder *encoder, + struct drm_display_mode *mode, + struct drm_display_mode *adjusted_mode) + + Those operations set the new mode. Depending on the device requirements, + the mode can be stored internally by the driver and applied in the commit + operations, or programmed to the hardware here. + + The crtc::mode_set operation returns 0 on success or a negative error code + if an error occurs. The encoder::mode_set operation isn't allowed to fail. + + - void (*commit)(struct drm_crtc *crtc) + - void (*commit)(struct drm_encoder *encoder) + + Those operations are called after setting the new mode. Upon return the + device must use the new mode and be fully operational. + +- int (*page_flip)(struct drm_crtc *crtc, struct drm_framebuffer *fb, + struct drm_pending_vblank_event *event) + + Schedule a page flip to the given frame buffer for the CRTC. This operation + is called with the mode config mutex held. + + Page flipping is a synchronization mechanism that replaces the frame buffer + being scanned out by the CRTC with a new frame buffer during vertical + blanking, avoiding tearing. When an application requests a page flip the DRM + core verifies that the new frame buffer is large enough to be scanned out by + the CRTC in the currently configured mode and then calls the CRTC + .page_flip() operation with a pointer to the new frame buffer. + + The .page_flip() operation schedules a page flip. Once any pending rendering + targetting the new frame buffer has completed, the CRTC will be reprogrammed + to display that frame buffer after the next vertical refresh. The operation + must return immediately without waiting for rendering or page flip to + complete and must block any new rendering to the frame buffer until the page + flip completes. + + If a page flip is already pending, the .page_flip() operation must return + -EBUSY. + + (FIXME: Should DRM allow queueing multiple page flips?) + + To synchronize page flip to vertical blanking the driver will likely need to + enable vertical blanking interrupts. It should call drm_vblank_get() for + that purpose, and call drm_vblank_put() after the page flip completes. + + If the application has requested to be notified when page flip completes the + .page_flip() operation will be called with a non-NULL event argument + pointing to a drm_pending_vblank_event instance. Upon page flip completion + the driver must fill the event::event sequence, tv_sec and tv_usec fields + with the associated vertical blanking count and timestamp, add the event to + the drm_file list of events to be signaled, and wake up any waiting process. + This can be performed with + + struct timeval now; + + event->event.sequence = drm_vblank_count_and_time(..., &now); + event->event.tv_sec = now.tv_sec; + event->event.tv_usec = now.tv_usec; + + spin_lock_irqsave(&dev->event_lock, flags); + list_add_tail(&event->base.link, &event->base.file_priv->event_list); + wake_up_interruptible(&event->base.file_priv->event_wait); + spin_unlock_irqrestore(&dev->event_lock, flags); + + (FIXME: Could drivers that don't need to wait for rendering to complete just + add the event to dev->vblank_event_list and let the DRM core handle + everything, as for "normal" vertical blanking events?) + + While waiting for the page flip to complete, the event->base.link list head + can be used freely by the driver to store the pending event in a + driver-specific list. + + If the file handle is closed before the event is signaled, drivers must take + care to destroy the event in their .preclose() operation (and, if needed, + call drm_vblank_put()). + + +10. Plane Operations +------------------- + +- int (*update_plane)(struct drm_plane *plane, struct drm_crtc *crtc, + struct drm_framebuffer *fb, int crtc_x, int crtc_y, + unsigned int crtc_w, unsigned int crtc_h, + uint32_t src_x, uint32_t src_y, + uint32_t src_w, uint32_t src_h) + + Enable and configure the plane to use the given CRTC and frame buffer. + + The source rectangle in frame buffer memory coordinates is given by the + src_x, src_y, src_w and src_h parameters (as 16.16 fixed point values). + Devices that don't support subpixel plane coordinates can ignore the + fractional part. + + The destination rectangle in CRTC coordinates is given by the crtc_x, + crtc_y, crtc_w and crtc_h parameters (as integer values). Devices scale + the source rectangle to the destination rectangle. If scaling is not + supported, the src_w and src_h values can be ignored. + +- int (*disable_plane)(struct drm_plane *plane) + + Disable the plane. The DRM core calls this method in response to a + DRM_IOCTL_MODE_SETPLANE ioctl call with the frame buffer ID set to 0. + Disabled planes must not be processed by the CRTC. + +- void (*destroy)(struct drm_plane *plane) + + Destroy the plane when not needed anymore. See the KMS cleanup section. + + +11. Encoder Operations +---------------------- + +- void (*destroy)(struct drm_encoder *encoder) + + Called to destroy the encoder when not needed anymore. See the KMS cleanup + section. + + +12. Connector Operations +------------------------ + +Unless otherwise state, all operations are mandatory. + +- status - connection status (connected, disconnected, unknown) + + The connection status is updated through polling or hotplug events when + supported (see the polled field description). The status value is reported + to userspace through ioctls and must not be used inside the driver, as it + only gets initialized by a call to drm_mode_getconnector() from userspace. + +- void (*dpms)(struct drm_connector *connector, int mode) + + The DPMS operation sets the power state of a connector. The mode argument is + one of + + DRM_MODE_DPMS_ON + DRM_MODE_DPMS_STANDBY + DRM_MODE_DPMS_SUSPEND + DRM_MODE_DPMS_OFF + + In all but DPMS_ON mode the encoder to which the connector is attached + should put the display in low-power mode by driving its signals appropriately. + If more than one connector is attached to the encoder care should be taken + not to change the power state of other displays as a side effect. Low-power + mode should be propagated to the encoders and CRTCs when all related + connectors are put in low-power mode. + + The mid-layer offers a drm_helper_connector_dpms() helper function that + tracks power state of connectors. When using the helper function drivers + only need to provide .dpms helper operations for CRTCs and encoders to apply + the DPMS state to the device. + + The mid-layer doesn't track the power state of CRTCs and encoders. The .dpms + operations can thus be called with a mode identical to the currently active + mode. + +- enum drm_connector_status (*detect)(struct drm_connector *connector, + bool force) + + Check to see if anything is attached to the connector. @force is set to + false whilst polling, true when checking the connector due to user request. + @force can be used by the driver to avoid expensive, destructive operations + during automated probing. + + Return connector_status_connected if something is connected to the + connector, connector_status_disconnected if nothing is connected and + connector_status_unknown if the connection state isn't known. + + Drivers should only return connector_status_connected if the connection + status has really been probed as connected. Connectors that can't detect the + connection status, or failed connection status probes, should return + connector_status_unknown. + +- int (*fill_modes)(struct drm_connector *connector, uint32_t max_width, + uint32_t max_height) + + Fill the mode list with all supported modes for the connector. If the + max_width and max_height arguments are non-zero, the implementation must + ignore all modes wider than max_width or higher than max_height. + + The connector must also fill in this operation its display_info width_mm and + height_mm fields with the connected display physical size in millimeters. + The fields should be set to 0 if the value isn't known or is not applicable + (for instance for projector devices). + + The mid-layer provides a drm_helper_probe_single_connector_modes() helper + function. The helper updates the connection status for the connector and + then retrieves a list of modes by calling the connector .get_modes helper + operation. + + The .get_modes helper operation is mandatory. It must fill the connector's + probed_modes list by parsing EDID data with drm_add_edid_modes() or calling + drm_mode_probed_add() directly for every supported mode. The operation + returns the number of modes it has detected. + + When adding modes manually the driver creates each mode with a call to + drm_mode_create() and must fill the following fields. + + - type: Mode type bitmask, a combination of + + DRM_MODE_TYPE_BUILTIN - not used? + DRM_MODE_TYPE_CLOCK_C - not used? + DRM_MODE_TYPE_CRTC_C - not used? + DRM_MODE_TYPE_PREFERRED - The preferred mode for the connector + DRM_MODE_TYPE_DEFAULT - not used? + DRM_MODE_TYPE_USERDEF - not used? + DRM_MODE_TYPE_DRIVER - The mode has been created by the driver (as opposed + to user-created modes) + + Drivers must set the DRM_MODE_TYPE_DRIVER bit for all modes they create, + and set the DRM_MODE_TYPE_PREFERRED bit for the preferred mode. + + - clock: Pixel clock frequency in kHz unit + + - hdisplay, hsync_start, hsync_end, htotal: Horizontal timing information + - vdisplay, vsync_start, vsync_end, vtotal: Vertical timing information + + Active Front Sync Back + Region Porch Porch + <-----------------------><----------------><-------------><--------------> + + //////////////////////| + ////////////////////// | + ////////////////////// |.................. ................ + _______________ + + <----- [hv]display -----> + <------------- [hv]sync_start ------------> + <--------------------- [hv]sync_end ---------------------> + <-------------------------------- [hv]total -----------------------------> + + - hskew, vscan: ? + + - flags: Mode flags, a combination of + + 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 - not used? + DRM_MODE_FLAG_CLKDIV2 - ? + + Note that modes marked with the INTERLACE or DBLSCAN flags will be + filtered out by drm_helper_probe_single_connector_modes() if the + connector's interlace_allowed or doublescan_allowed field is set to 0. + + - name: Mode name + + The driver must call drm_mode_set_name() to fill the mode name from the + hdisplay, vdisplay and interlace flag after filling the corresponding + fields. + + The vrefresh value is computed by drm_helper_probe_single_connector_modes(). + + When parsing EDID data, drm_add_edid_modes() fill the connector display_info + width_mm and height_mm fields. When creating modes manually the .get_modes + helper operation must set the display_info width_mm and height_mm fields if + they haven't been set already (for instance at initilization time when a + fixed-size panel is attached to the connector). The mode width_mm and + height_mm fields are only used internally during EDID parsing and should not + be set when creating modes manually. + + The helper function filters out modes larger than max_width and max_height + if specified. It then calls the connector .mode_valid helper operation for + each mode in the probed list to check whether the mode is valid for the + connector. The helper is mandatory and returns MODE_OK for supported modes + and one of the enum drm_mode_status values (MODE_*) for unsupported modes. + As unsupported modes will be immediately removed an implementation can + return MODE_BAD regardless of the exact reason why the mode is not valid. + + Note that the .mode_valid helper operation is only called for modes detected + by the device, and *not* for modes set by the user through the CRTC + .set_config operation. + +- void (*destroy)(struct drm_connector *connector) + + Destroy the connector when not needed anymore. See the KMS cleanup section. + + +13. TODO +-------- + +- Document the struct_mutex catch-all lock +- Document connector properties + +- crtc and encoder dpms helper operations are only mandatory if the disable + operation isn't provided. +- crtc and connector .save and .restore operations are only used internally in + drivers, should they be removed from the core? +- encoder mid-layer .save and .restore operations are only used internally in + drivers, should they be removed from the core? +- encoder mid-layer .detect operation is only used internally in drivers, + should it be removed from the core? + +- KMS drivers must call drm_vblank_pre_modeset() and drm_vblank_post_modeset() + around mode setting. Should this be done in the DRM core? +- vblank_disable_allowed is set to 1 in the first drm_vblank_post_modeset() + call and never set back to 0. It seems to be safe to permanently set it to 1 + in drm_vblank_init() for KMS driver, and it might be safe for UMS drivers as + well. This should be investigated. --