+ Architecture of a DRM driver
+i ----------------------------
+
+Written by Laurent Pinchart <[email protected]>
+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.
--
