Hey, thanks Laurent, this was quite needed!

I apologize in advance for the html mail.. but reviewing this on the flight home from connect and can't figure out how to do plain text email w/ google's offline mail client :-(

On Wednesday, May 30, 2012, Laurent Pinchart wrote:

Signed-off-by: Laurent Pinchart laurent.pinchart@ideasonboard.com

Documentation/drm.txt | 1265 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 files changed, 1265 insertions(+), 0 deletions(-) create mode 100644 Documentation/drm.txt

Hi everybody,

Here's the DRM kernel framework documentation I wrote while developing the Renesas SH Mobile DRM driver. It hopefully covers most of what's needed to write a simple DRM driver (although some areas are not documented, such as properties or the fbdev compatibility layer).

I can convert the documentation to DocBook if needed and integrate it with the existing "documentation stub". In that case I'm thinking of splitting the DocBook documentation in two parts, userspace API documentation (that someone would have to fill, any volunteer ? ;-)) and kernel API documentation. Would that be fine ?

Last but not least, now that documentation exists (albeit in an incomplete state), we need to make sure it won't get outdated too quickly. As nobody will volunteer to maintain it (feel free to prove me wrong though), I'd like to propose the same rule that we already follow in V4L: any patch that touches the API won't get merged if it doesn't update the documentation. Do you think this could work out ?

seems like a pretty reasonable idea

As usual, review will be appreciated.

diff --git a/Documentation/drm.txt b/Documentation/drm.txt new file mode 100644 index 0000000..4d8843d --- /dev/null +++ b/Documentation/drm.txt @@ -0,0 +1,1265 @@

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

AFAIK lastclose() should also be drm_fb_helper_restore_fbdev_mode() to restore fbcon mode. I'm also restoring crtc and plane properties to default values here, so a subsequent open of the device isn't inheriting some state from the previous user.

(maybe some of this could be handled instead in core, rather than each driver.. could be an idea for a cleanup?)

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

oh, heh, I completely missed that in omapdrm, so looks like I need to do some cleanup around here.. I wonder if there is any sane way to make this simpler for the driver writer, since basically all drivers would need to do the same thing here.. Ie. keep track of pending page_flip events, sort of analogous to how the core keeps track of pending vblank events..

Are there any drivers that can queue up more than one page flip per crtc at a time? If no, we could track pending page flip event in 'struct drm_crtc' and then have a drm_crtc_handle_page_flip_events(crtc), similar to drm_handle_vblank_events()..

• 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

s/methos/methods/

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

not sure if that is a spurious 'and' or you somehow lost part of that sentence?

+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

s/allocate/allocates/

Also, maybe worth mentioning that actual 'struct page's are allocated when drm_gem_get_pages() is called..

(I suppose you could say that only the storage but not the memory is allocated when the object is created, but maybe that confuses things more.)

• 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

s/no/not/

• 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().

I suppose it is easy enough seen from the code, but might be worth mentioning that drm_gem_handle_create() increment's the refcnt of the gem obj, rather than taking ownership of the gem obj.. so in some cases the driver writer would want to drop that reference to the obj

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

editorial nag: maybe move the notes about dma-buf / cross-device / cross-subsystem stuff above the prime_x_to_y fxn ptrs.. the real purpose of drm_gem_prime_x_to_y() was to allow dma-buf/prime to be used by drivers that do not use GEM. Any driver using GEM in some form or another, either by itself or in combination w/ TTM, probably wants to use drm_gem_prime_x_to_y() for these two fxn ptrs and instead provide the .gem_prime_{import,export} fxn ptr hooks which are used by drm_gem_prime_x_to_y().

But if your buffer object handle is not a GEM handle, then you instead need to implement .prime_x_to_y() fxn ptrs.. I think this applies only just to one driver (vmwgfx? I don't remember for sure, airlied mentioned it at one point). This was the reason for the split into two sets of fxn ptrs, so that non GEM drivers don't get left out.

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

only mandatory when using GEM+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?)

DPMS calls from userspace are made on the connector, and internally propagated to encoder/crtc/etc via drm_helper_connector_dpms(). When it is resumed, it should (IIRC) keep it's old settings.

• 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

s/Anothe/Another/

• 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?)

Queuing could be done in userspace (which gets a page_flip event when flip completes).. this at least simplifies the driver somewhat. And in cases where UI interactivity is required you really don't want to let rendering get too far ahead of scanout or the user will see this as laggy display. So I don't see a particularly good reason to support queuing.

(Also, makes it easier to move page_flip event handling to the core if you can have only at most one outstanding page flip.)

• 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?)

Or just drm_crtc_handle_page_flip_event() which would also let us simplify some of the cleanup when userspace closes the device, as mentioned earlier ;-) I think when I have a few spare minutes I'll try this.

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

hmm, ignored seems bad.. maybe driver should -EINVAL?

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

cool, thx.. I may have missed some things since I was trying to hurry up and finish reviewing before my battery died ;-)

BR, -R

-- Regards,

Laurent Pinchart

---

dri-devel mailing list dri-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/dri-devel