KMS Initialization and Cleanup
Prev | Chapter 2. DRM Internals | Next

## KMS Initialization and Cleanup

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 targeting 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 can be successfully scheduled the driver must set the `drm_crtc-<fb` field to the new framebuffer pointed to by `fb`. This is important so that the reference counting on framebuffers stays balanced.

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 call `drm_send_vblank_event` to fill in the event and send to wake up any waiting processes. This can be performed with

                spin_lock_irqsave(&dev->event_lock, flags);
                ...
                drm_send_vblank_event(dev, pipe, event);
                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 (*set_property)(struct drm_crtc *crtc,
                           struct drm_property *property, uint64_t value);

  Set the value of the given CRTC property to `value`. See the section called “KMS Properties” for more information about properties.

-     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

-     void (*destroy)(struct drm_encoder *encoder);

  Called to destroy the encoder when not needed anymore. See the section called “KMS Initialization and Cleanup”.

-     void (*set_property)(struct drm_plane *plane,
                           struct drm_property *property, uint64_t value);

  Set the value of the given plane property to `value`. See the section called “KMS Properties” for more information about properties.

### 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

-     void (*set_property)(struct drm_connector *connector,
                           struct drm_property *property, uint64_t value);

  Set the value of the given connector property to `value`. See the section called “KMS Properties” for more information about properties.

-     void (*destroy)(struct drm_connector *connector);

  Destroy the connector when not needed anymore. See the section called “KMS Initialization and Cleanup”.

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

### KMS API Functions

Prev | Up | Next
Mode Setting | Home | drm_modeset_lock_all