KMS Initialization and Cleanup

CRTCs (struct drm_crtc)
Planes (struct drm_plane)
Encoders (struct drm_encoder)
Connectors (struct drm_connector)
Cleanup
Output discovery and initialization example

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 after initializing mode setting.

CRTCs (struct drm_crtc)

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

CRTC Initialization

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.

CRTC Operations

Set Configuration
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.

Note

FIXME: How should set_config interact with DPMS? If the CRTC is suspended, should it be resumed?

Page Flipping
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.

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);
            

Note

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

Miscellaneous
  • 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 section called “KMS Initialization and Cleanup”.

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.

Plane Initialization

Planes are optional. To create a plane, a KMS drivers allocates and zeroes an instances of struct drm_plane (possibly 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.

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, and the source rectangle size doesn't match the destination rectangle size, the driver must return a -EINVAL error.

  • 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 section called “KMS Initialization and Cleanup”.

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.

Encoder Initialization

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.

Encoder Operations

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.

Connector Initialization

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

Connector Operations

Note

Unless otherwise state, all operations are mandatory.

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

Modes
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).

Connection Status

The connection status is updated through polling or hotplug events when supported (see polled). 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.

enum drm_connector_status (*detect)(struct drm_connector *connector,
                                        bool force);

Check to see if anything is attached to the connector. The force parameter is set to false whilst polling or to 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.

Miscellaneous

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.

Output discovery and initialization example

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

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

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

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

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

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

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

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

	drm_sysfs_connector_add(connector);
}

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