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.
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.
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 that the drm core has no notion of restoring the mode setting
state after resume, since all resume handling is in the full
responsibility of the driver. The common mode setting helper library
though provides a helper which can be used for this:
drm_helper_resume_force_mode.
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);
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).
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”.
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.
The DRM core recognizes three types of planes:
For compatibility with legacy userspace, only overlay planes are made available to userspace by default. Userspace clients may set the DRM_CLIENT_CAP_UNIVERSAL_PLANES client capability bit to indicate that they wish to receive a universal plane list containing all plane types.
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_universal_plane_init. The function takes a bitmask
of the CRTCs that can be associated with the plane, a pointer to the
plane functions, a list of format supported formats, and the type of
plane (primary, cursor, or overlay) being initialized.
Cursor and overlay planes are optional. All drivers should provide one primary plane per CRTC (although this requirement may change in the future); drivers that do not wish to provide special handling for primary planes may make use of the helper functions described in the section called “Plane Helper Reference” to create and register a primary plane with standard capabilities.
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”.
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
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.
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.
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_allowedWhether the connector can handle interlaced modes.
doublescan_allowedWhether 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.
polledConnector polling mode, a combination of
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.
Periodically poll the connector for connection.
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_connector_register.
Supported connector types are
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.
Unless otherwise state, all operations are mandatory.
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.
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 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.
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”.
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_connector_unregister before calling
drm_connector_cleanup.
Connectors state change detection must be cleanup up with a call to
drm_kms_helper_poll_fini.
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_connector_register(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.
mutex_is_locked
As KMS moves toward more fine grained locking, and atomic ioctl where userspace can indirectly control locking order, it becomes necessary to use ww_mutex and acquire-contexts to avoid deadlocks. But because the locking is more distributed around the driver code, we want a bit of extra utility/tracking out of our acquire-ctx. This is provided by drm_modeset_lock / drm_modeset_acquire_ctx.
For basic principles of ww_mutex, see: Documentation/locking/ww-mutex-design.txt
The basic usage pattern is to:
drm_modeset_acquire_init(ctx) retry: foreach (lock in random_ordered_set_of_locks) { ret = drm_modeset_lock(lock, ctx) if (ret == -EDEADLK) { drm_modeset_backoff(ctx); goto retry; } }
... do stuff ...
drm_modeset_drop_locks(ctx); drm_modeset_acquire_fini(ctx);