Mode Setting Helper Functions

Atomic Modeset Helper Functions Reference
Modeset Helper Reference for Common Vtables
Legacy CRTC/Modeset Helper Functions Reference
Output Probing Helper Functions Reference
fbdev Helper Functions Reference
Framebuffer CMA Helper Functions Reference
Display Port Helper Functions Reference
Display Port Dual Mode Adaptor Helper Functions Reference
Display Port MST Helper Functions Reference
MIPI DSI Helper Functions Reference
EDID Helper Functions Reference
Rectangle Utilities Reference
Flip-work Helper Reference
HDMI Infoframes Helper Reference
Plane Helper Reference
Tile group
Bridges
Panel Helper Reference

The plane, 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 plane, 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.

Atomic Modeset Helper Functions Reference

Overview
Implementing Asynchronous Atomic Commit
Atomic State Reset and Initialization
drm_atomic_crtc_for_each_plane — iterate over planes currently attached to CRTC
drm_atomic_crtc_state_for_each_plane — iterate over attached planes in new state
drm_atomic_helper_check_modeset — validate state object for modeset changes
drm_atomic_helper_check_planes — validate state object for planes changes
drm_atomic_helper_check — validate state object
drm_atomic_helper_update_legacy_modeset_state — update legacy modeset state
drm_atomic_helper_commit_modeset_disables — modeset commit to disable outputs
drm_atomic_helper_commit_modeset_enables — modeset commit to enable outputs
drm_atomic_helper_wait_for_fences — wait for fences stashed in plane state
drm_atomic_helper_framebuffer_changed — check if framebuffer has changed
drm_atomic_helper_wait_for_vblanks — wait for vblank on crtcs
drm_atomic_helper_commit — commit validated state object
drm_atomic_helper_prepare_planes — prepare plane resources before commit
drm_atomic_helper_commit_planes — commit plane state
drm_atomic_helper_commit_planes_on_crtc — commit plane state for a crtc
drm_atomic_helper_disable_planes_on_crtc — helper to disable CRTC's planes
drm_atomic_helper_cleanup_planes — cleanup plane resources after commit
drm_atomic_helper_swap_state — store atomic state into current sw state
drm_atomic_helper_update_plane — Helper for primary plane update using atomic
drm_atomic_helper_disable_plane — Helper for primary plane disable using * atomic
drm_atomic_helper_set_config — set a new config from userspace
drm_atomic_helper_disable_all — disable all currently active outputs
drm_atomic_helper_suspend — subsystem-level suspend helper
drm_atomic_helper_resume — subsystem-level resume helper
drm_atomic_helper_crtc_set_property — helper for crtc properties
drm_atomic_helper_plane_set_property — helper for plane properties
drm_atomic_helper_connector_set_property — helper for connector properties
drm_atomic_helper_page_flip — execute a legacy page flip
drm_atomic_helper_connector_dpms — connector dpms helper implementation
drm_atomic_helper_best_encoder Helper for drm_connector_helper_funcs ->best_encoder callback
drm_atomic_helper_crtc_reset — default ->reset hook for CRTCs
__drm_atomic_helper_crtc_duplicate_state — copy atomic CRTC state
drm_atomic_helper_crtc_duplicate_state — default state duplicate hook
__drm_atomic_helper_crtc_destroy_state — release CRTC state
drm_atomic_helper_crtc_destroy_state — default state destroy hook
drm_atomic_helper_plane_reset — default ->reset hook for planes
__drm_atomic_helper_plane_duplicate_state — copy atomic plane state
drm_atomic_helper_plane_duplicate_state — default state duplicate hook
__drm_atomic_helper_plane_destroy_state — release plane state
drm_atomic_helper_plane_destroy_state — default state destroy hook
__drm_atomic_helper_connector_reset — reset state on connector
drm_atomic_helper_connector_reset — default ->reset hook for connectors
__drm_atomic_helper_connector_duplicate_state — copy atomic connector state
drm_atomic_helper_connector_duplicate_state — default state duplicate hook
drm_atomic_helper_duplicate_state — duplicate an atomic state object
__drm_atomic_helper_connector_destroy_state — release connector state
drm_atomic_helper_connector_destroy_state — default state destroy hook
drm_atomic_helper_legacy_gamma_set — set the legacy gamma correction table

Overview

This helper library provides implementations of check and commit functions on top of the CRTC modeset helper callbacks and the plane helper callbacks. It also provides convenience implementations for the atomic state handling callbacks for drivers which don't need to subclass the drm core structures to add their own additional internal state.

This library also provides default implementations for the check callback in drm_atomic_helper_check and for the commit callback with drm_atomic_helper_commit. But the individual stages and callbacks are exposed to allow drivers to mix and match and e.g. use the plane helpers only together with a driver private modeset implementation.

This library also provides implementations for all the legacy driver interfaces on top of the atomic interface. See drm_atomic_helper_set_config, drm_atomic_helper_disable_plane, drm_atomic_helper_disable_plane and the various functions to implement set_property callbacks. New drivers must not implement these functions themselves but must use the provided helpers.

The atomic helper uses the same function table structures as all other modesetting helpers. See the documentation for struct drm_crtc_helper_funcs, struct drm_encoder_helper_funcs and struct drm_connector_helper_funcs. It also shares the struct drm_plane_helper_funcs function table with the plane helpers.

Implementing Asynchronous Atomic Commit

Atomic State Reset and Initialization

Both the drm core and the atomic helpers assume that there is always the full and correct atomic software state for all connectors, CRTCs and planes available. Which is a bit a problem on driver load and also after system suspend. One way to solve this is to have a hardware state read-out infrastructure which reconstructs the full software state (e.g. the i915 driver).

The simpler solution is to just reset the software state to everything off, which is easiest to do by calling drm_mode_config_reset. To facilitate this the atomic helpers provide default reset implementations for all hooks.

On the upside the precise state tracking of atomic simplifies system suspend and resume a lot. For drivers using drm_mode_config_reset a complete recipe is implemented in drm_atomic_helper_suspend and drm_atomic_helper_resume. For other drivers the building blocks are split out, see the documentation for these functions.

Modeset Helper Reference for Common Vtables

struct drm_crtc_helper_funcs — helper operations for CRTCs
drm_crtc_helper_add — sets the helper vtable for a crtc
struct drm_encoder_helper_funcs — helper operations for encoders
drm_encoder_helper_add — sets the helper vtable for an encoder
struct drm_connector_helper_funcs — helper operations for connectors
drm_connector_helper_add — sets the helper vtable for a connector
struct drm_plane_helper_funcs — helper operations for planes
drm_plane_helper_add — sets the helper vtable for a plane

The DRM mode setting helper functions are common code for drivers to use if they wish. Drivers are not forced to use this code in their implementations but it would be useful if the code they do use at least provides a consistent interface and operation to userspace. Therefore it is highly recommended to use the provided helpers as much as possible.

Because there is only one pointer per modeset object to hold a vfunc table for helper libraries they are by necessity shared among the different helpers.

To make this clear all the helper vtables are pulled together in this location here.

Legacy CRTC/Modeset Helper Functions Reference

drm_helper_move_panel_connectors_to_head — move panels to the front in the connector list
drm_helper_encoder_in_use — check if a given encoder is in use
drm_helper_crtc_in_use — check if a given CRTC is in a mode_config
drm_helper_disable_unused_functions — disable unused objects
drm_crtc_helper_set_mode — internal helper to set a mode
drm_crtc_helper_set_config — set a new config from userspace
drm_helper_connector_dpms — connector dpms helper implementation
drm_helper_mode_fill_fb_struct — fill out framebuffer metadata
drm_helper_resume_force_mode — force-restore mode setting configuration
drm_helper_crtc_mode_set — mode_set implementation for atomic plane helpers
drm_helper_crtc_mode_set_base — mode_set_base implementation for atomic plane helpers
drm_helper_crtc_enable_color_mgmt — enable color management properties

The CRTC modeset helper library provides a default set_config implementation in drm_crtc_helper_set_config. Plus a few other convenience functions using the same callbacks which drivers can use to e.g. restore the modeset configuration on resume with drm_helper_resume_force_mode.

Note that this helper library doesn't track the current power state of CRTCs and encoders. It can call callbacks like ->dpms even though the hardware is already in the desired state. This deficiency has been fixed in the atomic helpers.

The driver callbacks are mostly compatible with the atomic modeset helpers, except for the handling of the primary plane: Atomic helpers require that the primary plane is implemented as a real standalone plane and not directly tied to the CRTC state. For easier transition this library provides functions to implement the old semantics required by the CRTC helpers using the new plane and atomic helper callbacks.

Drivers are strongly urged to convert to the atomic helpers (by way of first converting to the plane helpers). New drivers must not use these functions but need to implement the atomic interface instead, potentially using the atomic helpers for that.

These legacy modeset helpers use the same function table structures as all other modesetting helpers. See the documentation for struct drm_crtc_helper_funcs, struct drm_encoder_helper_funcs and struct drm_connector_helper_funcs.

Output Probing Helper Functions Reference

drm_kms_helper_poll_enable_locked — re-enable output polling.
drm_helper_probe_single_connector_modes — get complete set of display modes
drm_kms_helper_hotplug_event — fire off KMS hotplug events
drm_kms_helper_poll_disable — disable output polling
drm_kms_helper_poll_enable — re-enable output polling.
drm_kms_helper_poll_init — initialize and enable output polling
drm_kms_helper_poll_fini — disable output polling and clean it up
drm_helper_hpd_irq_event — hotplug processing

This library provides some helper code for output probing. It provides an implementation of the core connector->fill_modes interface with drm_helper_probe_single_connector_modes.

It also provides support for polling connectors with a work item and for generic hotplug interrupt handling where the driver doesn't or cannot keep track of a per-connector hpd interrupt.

This helper library can be used independently of the modeset helper library. Drivers can also overwrite different parts e.g. use their own hotplug handling code to avoid probing unrelated outputs.

The probe helpers share the function table structures with other display helper libraries. See struct drm_connector_helper_funcs for the details.

fbdev Helper Functions Reference

drm_fb_helper_single_add_all_connectors — add all connectors to fbdev emulation helper
drm_fb_helper_debug_enter — implementation for ->fb_debug_enter
drm_fb_helper_debug_leave — implementation for ->fb_debug_leave
drm_fb_helper_restore_fbdev_mode_unlocked — restore fbdev configuration
drm_fb_helper_blank — implementation for ->fb_blank
drm_fb_helper_prepare — setup a drm_fb_helper structure
drm_fb_helper_init — initialize a drm_fb_helper structure
drm_fb_helper_alloc_fbi — allocate fb_info and some of its members
drm_fb_helper_unregister_fbi — unregister fb_info framebuffer device
drm_fb_helper_release_fbi — dealloc fb_info and its members
drm_fb_helper_unlink_fbi — wrapper around unlink_framebuffer
drm_fb_helper_deferred_io — fbdev deferred_io callback function
drm_fb_helper_sys_read — wrapper around fb_sys_read
drm_fb_helper_sys_write — wrapper around fb_sys_write
drm_fb_helper_sys_fillrect — wrapper around sys_fillrect
drm_fb_helper_sys_copyarea — wrapper around sys_copyarea
drm_fb_helper_sys_imageblit — wrapper around sys_imageblit
drm_fb_helper_cfb_fillrect — wrapper around cfb_fillrect
drm_fb_helper_cfb_copyarea — wrapper around cfb_copyarea
drm_fb_helper_cfb_imageblit — wrapper around cfb_imageblit
drm_fb_helper_set_suspend — wrapper around fb_set_suspend
drm_fb_helper_setcmap — implementation for ->fb_setcmap
drm_fb_helper_check_var — implementation for ->fb_check_var
drm_fb_helper_set_par — implementation for ->fb_set_par
drm_fb_helper_pan_display — implementation for ->fb_pan_display
drm_fb_helper_fill_fix — initializes fixed fbdev information
drm_fb_helper_fill_var — initalizes variable fbdev information
drm_fb_helper_initial_config — setup a sane initial connector configuration
drm_fb_helper_hotplug_event — respond to a hotplug notification by probing all the outputs attached to the fb
struct drm_fb_helper_surface_size — describes fbdev size and scanout surface size
struct drm_fb_helper_funcs — driver callbacks for the fbdev emulation library
struct drm_fb_helper — main structure to emulate fbdev on top of KMS

The fb helper functions are useful to provide an fbdev on top of a drm kernel mode setting driver. They can be used mostly independently from the crtc helper functions used by many drivers to implement the kernel mode setting interfaces.

Initialization is done as a four-step process with drm_fb_helper_prepare, drm_fb_helper_init, drm_fb_helper_single_add_all_connectors and drm_fb_helper_initial_config. Drivers with fancier requirements than the default behaviour can override the third step with their own code. Teardown is done with drm_fb_helper_fini.

At runtime drivers should restore the fbdev console by calling drm_fb_helper_restore_fbdev_mode_unlocked from their ->lastclose callback. They should also notify the fb helper code from updates to the output configuration by calling drm_fb_helper_hotplug_event. For easier integration with the output polling code in drm_crtc_helper.c the modeset code provides a ->output_poll_changed callback.

All other functions exported by the fb helper library can be used to implement the fbdev driver interface by the driver.

It is possible, though perhaps somewhat tricky, to implement race-free hotplug detection using the fbdev helpers. The drm_fb_helper_prepare helper must be called first to initialize the minimum required to make hotplug detection work. Drivers also need to make sure to properly set up the dev->mode_config.funcs member. After calling drm_kms_helper_poll_init it is safe to enable interrupts and start processing hotplug events. At the same time, drivers should initialize all modeset objects such as CRTCs, encoders and connectors. To finish up the fbdev helper initialization, the drm_fb_helper_init function is called. To probe for all attached displays and set up an initial configuration using the detected hardware, drivers should call drm_fb_helper_single_add_all_connectors followed by drm_fb_helper_initial_config.

If drm_framebuffer_funcs ->dirty is set, the drm_fb_helper_{cfb,sys}_{write,fillrect,copyarea,imageblit} functions will accumulate changes and schedule drm_fb_helper ->dirty_work to run right away. This worker then calls the dirty function ensuring that it will always run in process context since the fb_*() function could be running in atomic context. If drm_fb_helper_deferred_io is used as the deferred_io callback it will also schedule dirty_work with the damage collected from the mmap page writes.

Framebuffer CMA Helper Functions Reference

drm_fb_cma_create_with_funcs helper function for the drm_mode_config_funcs ->fb_create callback function
drm_fb_cma_create drm_mode_config_funcs ->fb_create callback function
drm_fb_cma_get_gem_obj — Get CMA GEM object for framebuffer
drm_fb_cma_debugfs_show — Helper to list CMA framebuffer objects in debugfs.
drm_fbdev_cma_init_with_funcs — Allocate and initializes a drm_fbdev_cma struct
drm_fbdev_cma_init — Allocate and initializes a drm_fbdev_cma struct
drm_fbdev_cma_fini — Free drm_fbdev_cma struct
drm_fbdev_cma_restore_mode — Restores initial framebuffer mode
drm_fbdev_cma_hotplug_event — Poll for hotpulug events

Provides helper functions for creating a cma (contiguous memory allocator) backed framebuffer.

drm_fb_cma_create is used in the drm_mode_config_funcs ->fb_create callback function to create a cma backed framebuffer.

An fbdev framebuffer backed by cma is also available by calling drm_fbdev_cma_init. drm_fbdev_cma_fini tears it down. If the drm_framebuffer_funcs ->dirty callback is set, fb_deferred_io will be set up automatically. dirty is called by drm_fb_helper_deferred_io in process context (struct delayed_work).

Example fbdev deferred io code:

static int driver_fbdev_fb_dirty(struct drm_framebuffer *fb, struct drm_file *file_priv, unsigned flags, unsigned color, struct drm_clip_rect *clips, unsigned num_clips) { struct drm_gem_cma_object *cma = drm_fb_cma_get_gem_obj(fb, 0); ... push changes ... return 0; }

static struct drm_framebuffer_funcs driver_fbdev_fb_funcs = { .destroy = drm_fb_cma_destroy, .create_handle = drm_fb_cma_create_handle, .dirty = driver_fbdev_fb_dirty, };

static int driver_fbdev_create(struct drm_fb_helper *helper, struct drm_fb_helper_surface_size *sizes) { return drm_fbdev_cma_create_with_funcs(helper, sizes, driver_fbdev_fb_funcs); }

static const struct drm_fb_helper_funcs driver_fb_helper_funcs = { .fb_probe = driver_fbdev_create, };

Initialize: fbdev = drm_fbdev_cma_init_with_funcs(dev, 16, dev->mode_config.num_crtc, dev->mode_config.num_connector, driver_fb_helper_funcs);

Display Port Helper Functions Reference

struct drm_dp_aux_msg — DisplayPort AUX channel transaction
struct drm_dp_aux — DisplayPort AUX channel
drm_dp_dpcd_readb — read a single byte from the DPCD
drm_dp_dpcd_writeb — write a single byte to the DPCD
drm_dp_dpcd_read — read a series of bytes from the DPCD
drm_dp_dpcd_write — write a series of bytes to the DPCD
drm_dp_dpcd_read_link_status — read DPCD link status (bytes 0x202-0x207)
drm_dp_link_probe — probe a DisplayPort link for capabilities
drm_dp_link_power_up — power up a DisplayPort link
drm_dp_link_power_down — power down a DisplayPort link
drm_dp_link_configure — configure a DisplayPort link
drm_dp_aux_register — initialise and register aux channel
drm_dp_aux_unregister — unregister an AUX adapter

These functions contain some common logic and helpers at various abstraction levels to deal with Display Port sink devices and related things like DP aux channel transfers, EDID reading over DP aux channels, decoding certain DPCD blocks, ...

The DisplayPort AUX channel is an abstraction to allow generic, driver- independent access to AUX functionality. Drivers can take advantage of this by filling in the fields of the drm_dp_aux structure.

Transactions are described using a hardware-independent drm_dp_aux_msg structure, which is passed into a driver's .transfer implementation. Both native and I2C-over-AUX transactions are supported.

Display Port Dual Mode Adaptor Helper Functions Reference

enum drm_dp_dual_mode_type — Type of the DP dual mode adaptor
drm_dp_dual_mode_read — Read from the DP dual mode adaptor register(s)
drm_dp_dual_mode_write — Write to the DP dual mode adaptor register(s)
drm_dp_dual_mode_detect — Identify the DP dual mode adaptor
drm_dp_dual_mode_max_tmds_clock — Max TMDS clock for DP dual mode adaptor
drm_dp_dual_mode_get_tmds_output — Get the state of the TMDS output buffers in the DP dual mode adaptor
drm_dp_dual_mode_set_tmds_output — Enable/disable TMDS output buffers in the DP dual mode adaptor
drm_dp_get_dual_mode_type_name — Get the name of the DP dual mode adaptor type as a string

Helper functions to deal with DP dual mode (aka. DP++) adaptors.

Type 1: Adaptor registers (if any) and the sink DDC bus may be accessed via I2C.

Type 2: Adaptor registers and sink DDC bus can be accessed either via I2C or I2C-over-AUX. Source devices may choose to implement either of these access methods.

Display Port MST Helper Functions Reference

struct drm_dp_vcpi — Virtual Channel Payload Identifier
struct drm_dp_mst_port — MST port
struct drm_dp_mst_branch — MST branch device.
struct drm_dp_mst_topology_mgr — DisplayPort MST manager
drm_dp_update_payload_part1 — Execute payload update part 1
drm_dp_update_payload_part2 — Execute payload update part 2
drm_dp_mst_topology_mgr_set_mst — Set the MST state for a topology manager
drm_dp_mst_topology_mgr_suspend — suspend the MST manager
drm_dp_mst_topology_mgr_resume — resume the MST manager
drm_dp_mst_hpd_irq — MST hotplug IRQ notify
drm_dp_mst_detect_port — get connection status for an MST port
drm_dp_mst_port_has_audio — Check whether port has audio capability or not
drm_dp_mst_get_edid — get EDID for an MST port
drm_dp_find_vcpi_slots — find slots for this PBN value
drm_dp_mst_allocate_vcpi — Allocate a virtual channel
drm_dp_mst_reset_vcpi_slots — Reset number of slots to 0 for VCPI
drm_dp_mst_deallocate_vcpi — deallocate a VCPI
drm_dp_check_act_status — Check ACT handled status.
drm_dp_calc_pbn_mode — Calculate the PBN for a mode.
drm_dp_mst_dump_topology
drm_dp_mst_topology_mgr_init — initialise a topology manager
drm_dp_mst_topology_mgr_destroy — destroy topology manager.

These functions contain parts of the DisplayPort 1.2a MultiStream Transport protocol. The helpers contain a topology manager and bandwidth manager. The helpers encapsulate the sending and received of sideband msgs.

MIPI DSI Helper Functions Reference

struct mipi_dsi_msg — read/write DSI buffer
struct mipi_dsi_packet — represents a MIPI DSI packet in protocol format
struct mipi_dsi_host_ops — DSI bus operations
struct mipi_dsi_host — DSI host device
struct mipi_dsi_device_info — template for creating a mipi_dsi_device
struct mipi_dsi_device — DSI peripheral device
mipi_dsi_pixel_format_to_bpp — obtain the number of bits per pixel for any given pixel format defined by the MIPI DSI specification
enum mipi_dsi_dcs_tear_mode — Tearing Effect Output Line mode
struct mipi_dsi_driver — DSI driver
of_find_mipi_dsi_device_by_node — find the MIPI DSI device matching a device tree node
mipi_dsi_device_register_full — create a MIPI DSI device
mipi_dsi_device_unregister — unregister MIPI DSI device
of_find_mipi_dsi_host_by_node — find the MIPI DSI host matching a device tree node
mipi_dsi_attach — attach a DSI device to its DSI host
mipi_dsi_detach — detach a DSI device from its DSI host
mipi_dsi_packet_format_is_short — check if a packet is of the short format
mipi_dsi_packet_format_is_long — check if a packet is of the long format
mipi_dsi_create_packet — create a packet from a message according to the DSI protocol
mipi_dsi_shutdown_peripheral — sends a Shutdown Peripheral command
mipi_dsi_turn_on_peripheral — sends a Turn On Peripheral command
mipi_dsi_generic_write — transmit data using a generic write packet
mipi_dsi_generic_read — receive data using a generic read packet
mipi_dsi_dcs_write_buffer — transmit a DCS command with payload
mipi_dsi_dcs_write — send DCS write command
mipi_dsi_dcs_read — send DCS read request command
mipi_dsi_dcs_nop — send DCS nop packet
mipi_dsi_dcs_soft_reset — perform a software reset of the display module
mipi_dsi_dcs_get_power_mode — query the display module's current power mode
mipi_dsi_dcs_get_pixel_format — gets the pixel format for the RGB image data used by the interface
mipi_dsi_dcs_enter_sleep_mode — disable all unnecessary blocks inside the display module except interface communication
mipi_dsi_dcs_exit_sleep_mode — enable all blocks inside the display module
mipi_dsi_dcs_set_display_off — stop displaying the image data on the display device
mipi_dsi_dcs_set_display_on — start displaying the image data on the display device
mipi_dsi_dcs_set_column_address — define the column extent of the frame memory accessed by the host processor
mipi_dsi_dcs_set_page_address — define the page extent of the frame memory accessed by the host processor
mipi_dsi_dcs_set_tear_off — turn off the display module's Tearing Effect output signal on the TE signal line
mipi_dsi_dcs_set_tear_on — turn on the display module's Tearing Effect output signal on the TE signal line.
mipi_dsi_dcs_set_pixel_format — sets the pixel format for the RGB image data used by the interface
mipi_dsi_driver_register_full — register a driver for DSI devices
mipi_dsi_driver_unregister — unregister a driver for DSI devices

These functions contain some common logic and helpers to deal with MIPI DSI peripherals.

Helpers are provided for a number of standard MIPI DSI command as well as a subset of the MIPI DCS command set.

EDID Helper Functions Reference

drm_edid_header_is_valid — sanity check the header of the base EDID block
drm_edid_block_valid — Sanity check the EDID block (base or extension)
drm_edid_is_valid — sanity check EDID data
drm_do_get_edid — get EDID data using a custom EDID block read function
drm_probe_ddc — probe DDC presence
drm_get_edid — get EDID data, if available
drm_get_edid_switcheroo — get EDID data for a vga_switcheroo output
drm_edid_duplicate — duplicate an EDID and the extensions
drm_match_cea_mode — look for a CEA mode matching given mode
drm_get_cea_aspect_ratio — get the picture aspect ratio corresponding to the input VIC from the CEA mode list
drm_edid_get_monitor_name — fetch the monitor name from the edid
drm_edid_to_eld — build ELD from EDID
drm_edid_to_sad — extracts SADs from EDID
drm_edid_to_speaker_allocation — extracts Speaker Allocation Data Blocks from EDID
drm_av_sync_delay — compute the HDMI/DP sink audio-video sync delay
drm_select_eld — select one ELD from multiple HDMI/DP sinks
drm_detect_hdmi_monitor — detect whether monitor is HDMI
drm_detect_monitor_audio — check monitor audio capability
drm_rgb_quant_range_selectable — is RGB quantization range selectable?
drm_add_edid_modes — add modes from EDID data, if available
drm_add_modes_noedid — add modes for the connectors without EDID
drm_set_preferred_mode — Sets the preferred mode of a connector
drm_hdmi_avi_infoframe_from_display_mode — fill an HDMI AVI infoframe with data from a DRM display mode
drm_hdmi_vendor_infoframe_from_display_mode — fill an HDMI infoframe with data from a DRM display mode

Rectangle Utilities Reference

struct drm_rect — two dimensional rectangle
drm_rect_adjust_size — adjust the size of the rectangle
drm_rect_translate — translate the rectangle
drm_rect_downscale — downscale a rectangle
drm_rect_width — determine the rectangle width
drm_rect_height — determine the rectangle height
drm_rect_visible — determine if the the rectangle is visible
drm_rect_equals — determine if two rectangles are equal
drm_rect_intersect — intersect two rectangles
drm_rect_clip_scaled — perform a scaled clip operation
drm_rect_calc_hscale — calculate the horizontal scaling factor
drm_rect_calc_vscale — calculate the vertical scaling factor
drm_rect_calc_hscale_relaxed — calculate the horizontal scaling factor
drm_rect_calc_vscale_relaxed — calculate the vertical scaling factor
drm_rect_debug_print — print the rectangle information
drm_rect_rotate — Rotate the rectangle
drm_rect_rotate_inv — Inverse rotate the rectangle

Utility functions to help manage rectangular areas for clipping, scaling, etc. calculations.

Flip-work Helper Reference

struct drm_flip_task — flip work task
struct drm_flip_work — flip work queue
drm_flip_work_allocate_task — allocate a flip-work task
drm_flip_work_queue_task — queue a specific task
drm_flip_work_queue — queue work
drm_flip_work_commit — commit queued work
drm_flip_work_init — initialize flip-work
drm_flip_work_cleanup — cleans up flip-work

Util to queue up work to run from work-queue context after flip/vblank. Typically this can be used to defer unref of framebuffer's, cursor bo's, etc until after vblank. The APIs are all thread-safe. Moreover, drm_flip_work_queue_task and drm_flip_work_queue can be called in atomic context.

HDMI Infoframes Helper Reference

union hdmi_infoframe — overall union of all abstract infoframe representations
hdmi_avi_infoframe_init — initialize an HDMI AVI infoframe
hdmi_avi_infoframe_pack — write HDMI AVI infoframe to binary buffer
hdmi_spd_infoframe_init — initialize an HDMI SPD infoframe
hdmi_spd_infoframe_pack — write HDMI SPD infoframe to binary buffer
hdmi_audio_infoframe_init — initialize an HDMI audio infoframe
hdmi_audio_infoframe_pack — write HDMI audio infoframe to binary buffer
hdmi_vendor_infoframe_init — initialize an HDMI vendor infoframe
hdmi_vendor_infoframe_pack — write a HDMI vendor infoframe to binary buffer
hdmi_infoframe_pack — write a HDMI infoframe to binary buffer
hdmi_infoframe_log — log info of HDMI infoframe
hdmi_infoframe_unpack — unpack binary buffer to a HDMI infoframe

Strictly speaking this is not a DRM helper library but generally useable by any driver interfacing with HDMI outputs like v4l or alsa drivers. But it nicely fits into the overall topic of mode setting helper libraries and hence is also included here.

Plane Helper Reference

drm_plane_helper_check_update — Check plane update for validity
drm_primary_helper_update — Helper for primary plane update
drm_primary_helper_disable — Helper for primary plane disable
drm_primary_helper_destroy — Helper for primary plane destruction
drm_crtc_init — Legacy CRTC initialization function
drm_plane_helper_update — Transitional helper for plane update
drm_plane_helper_disable — Transitional helper for plane disable

This helper library has two parts. The first part has support to implement primary plane support on top of the normal CRTC configuration interface. Since the legacy ->set_config interface ties the primary plane together with the CRTC state this does not allow userspace to disable the primary plane itself. To avoid too much duplicated code use drm_plane_helper_check_update which can be used to enforce the same restrictions as primary planes had thus. The default primary plane only expose XRBG8888 and ARGB8888 as valid pixel formats for the attached framebuffer.

Drivers are highly recommended to implement proper support for primary planes, and newly merged drivers must not rely upon these transitional helpers.

The second part also implements transitional helpers which allow drivers to gradually switch to the atomic helper infrastructure for plane updates. Once that switch is complete drivers shouldn't use these any longer, instead using the proper legacy implementations for update and disable plane hooks provided by the atomic helpers.

Again drivers are strongly urged to switch to the new interfaces.

The plane helpers share the function table structures with other helpers, specifically also the atomic helpers. See struct drm_plane_helper_funcs for the details.

Tile group

Tile groups are used to represent tiled monitors with a unique integer identifier. Tiled monitors using DisplayID v1.3 have a unique 8-byte handle, we store this in a tile group, so we have a common identifier for all tiles in a monitor group.

Bridges

Overview
Default bridge callback sequence
drm_bridge_add — add the given bridge to the global bridge list
drm_bridge_remove — remove the given bridge from the global bridge list
drm_bridge_attach — associate given bridge to our DRM device
drm_bridge_mode_fixup — fixup proposed mode for all bridges in the encoder chain
drm_bridge_disable calls ->disable drm_bridge_funcs op for all bridges in the encoder chain.
drm_bridge_post_disable calls ->post_disable drm_bridge_funcs op for all bridges in the encoder chain.
drm_bridge_mode_set — set proposed mode for all bridges in the encoder chain
drm_bridge_pre_enable calls ->pre_enable drm_bridge_funcs op for all bridges in the encoder chain.
drm_bridge_enable calls ->enable drm_bridge_funcs op for all bridges in the encoder chain.
of_drm_find_bridge — find the bridge corresponding to the device node in the global bridge list

Overview

struct drm_bridge represents a device that hangs on to an encoder. These are handy when a regular drm_encoder entity isn't enough to represent the entire encoder chain.

A bridge is always attached to a single drm_encoder at a time, but can be either connected to it directly, or through an intermediate bridge:

encoder ---> bridge B ---> bridge A

Here, the output of the encoder feeds to bridge B, and that furthers feeds to bridge A.

The driver using the bridge is responsible to make the associations between the encoder and bridges. Once these links are made, the bridges will participate along with encoder functions to perform mode_set/enable/disable through the ops provided in drm_bridge_funcs.

drm_bridge, like drm_panel, aren't drm_mode_object entities like planes, CRTCs, encoders or connectors and hence are not visible to userspace. They just provide additional hooks to get the desired output at the end of the encoder chain.

Bridges can also be chained up using the next pointer in struct drm_bridge.

Both legacy CRTC helpers and the new atomic modeset helpers support bridges.

Default bridge callback sequence

The drm_bridge_funcs ops are populated by the bridge driver. The DRM internals (atomic and CRTC helpers) use the helpers defined in drm_bridge.c These helpers call a specific drm_bridge_funcs op for all the bridges during encoder configuration.

For detailed specification of the bridge callbacks see drm_bridge_funcs.

Panel Helper Reference

struct drm_panel_funcs — perform operations on a given panel
struct drm_panel — DRM panel object
drm_panel_unprepare — power off a panel
drm_panel_disable — disable a panel
drm_panel_prepare — power on a panel
drm_panel_enable — enable a panel
drm_panel_get_modes — probe the available display modes of a panel
drm_panel_init — initialize a panel
drm_panel_add — add a panel to the global registry
drm_panel_remove — remove a panel from the global registry
drm_panel_attach — attach a panel to a connector
drm_panel_detach — detach a panel from a connector
of_drm_find_panel — look up a panel using a device tree node

The DRM panel helpers allow drivers to register panel objects with a central registry and provide functions to retrieve those panels in display drivers.