Architecture of a DRM driver

+		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.
--