Ubuntu Manpage: weston-drm - the DRM backend for Weston

NAME

       weston-drm - the DRM backend for Weston

SYNOPSIS

       weston --backend=drm

DESCRIPTION

The DRM backend is the native Weston backend for systems that support the Linux kernel DRM, kernel mode
setting (KMS), and evdev input devices. It is the recommended backend for desktop PCs, and aims to
provide the full Wayland experience with the "every frame is perfect" concept. It also relies on the
Mesa GBM interface.

With the DRM backend, weston runs without any underlying windowing system. The backend uses the Linux KMS
API to detect connected monitors. Monitor hot-plugging is supported. Input devices are found
automatically by udev(7). Compositing happens mainly in GL ES 2, initialized through EGL. It is also
possible to take advantage of hardware cursors and overlays, when they exist and are functional. Full-
screen surfaces will be scanned out directly without compositing, when possible. Hardware accelerated
clients are supported via EGL.

The backend chooses the DRM graphics device first based on seat id. If seat identifiers are not set, it
looks for the graphics device that was used in boot. If that is not found, it finally chooses the first
DRM device returned by udev(7). Combining multiple graphics devices is not supported yet.

The DRM backend also supports virtual outputs that are transmitted over an RTP session as a series of
JPEG images (RTP payload type 26) to a remote client. Virtual outputs are configured in the remote-output
section of weston.ini.

CONFIGURATION

The DRM backend uses the following entries from weston.ini.

Section core
gbm-format=format
Sets the default pixel format for DRM KMS framebuffers. Format can be xrgb8888, xrgb2101010,
rgb565 or others. Weston recognizes the names of most pixel formats defined by the kernel DRM
subsystem in drm_fourcc.h header without the DRM_FORMAT_ prefix. The actually supported pixel
formats depend on the DRM driver and hardware, and the renderer used. Using Pixman-renderer, DRM-
backend supports xrgb8888, xrgb2101010, rgb565 and some of their permutations. The formats
supported with GL-renderer depend on the EGL and OpenGL ES 2 or 3 implementations. The names are
case-insensitive. This setting applies only to outputs in SDR mode, see eotf-mode in
weston.ini(5).

If not specified, xrgb8888 is used. See also gbm-format in output section.

pageflip-timeout=milliseconds
sets Weston's pageflip timeout in milliseconds. This sets a timer to exit gracefully with a log
message and an exit code of 1 in case the DRM driver is non-responsive. Setting it to 0 disables
this feature.

Section output
name=connector
The KMS connector name identifying the output, for instance LVDS1.

mode=mode
Specify the video mode for the output. The argument mode can be one of the words off to turn the
output off, preferred to use the monitor's preferred video mode, or current to use the current
video mode and avoid a mode switch. It can also be a resolution as:

mode=widthxheight

mode=widthxheight@refresh_rate
Specify a mode with a given refresh-rate measured in Hz.

mode=widthxheight@refresh_rate ratio
Here ratio is Picture Aspect-Ratio which can have values as 4:3, 16:9, 64:27, and 256:135. This
resolution-format helps to select a CEA mode, if such a video mode is present in the mode-list of
the output.

CEA defines the timing of a video mode, which is considered as a standard for HDMI spcification
and compliance testing. It defines each and every parameter of a video mode, like hactive,
vactive, vfront, vback etc., including aspect-ratio information. For CEA modes, the drm layer,
stores this aspect-ratio information in user-mode (drmModeModeInfo) flag bits 19-22. For the non-
CEA modes a value of 0 is stored in the aspect-ratio flag bits.

Each CEA-mode is identified by a unique, Video Identification Code (VIC). For example, VIC=4 is
1280x720@60 aspect-ratio 16:9. This mode will be different than a non-CEA mode 1280x720@60 0:0.
When the video mode 1280x720@60 0:0 is applied, since its timing doesn't exactly match with the
CEA information for VIC=4, it would be treated as a non-CEA mode. Also, while setting the HDMI-
AVI-Inforframe, VIC parameter will be given as '0'. If video mode 1280x720@60 16:9 is applied, its
CEA timimgs matches with that of video mode with VIC=4, so the VIC parameter in HDMI-AVI-Infoframe
will be set to 4.

Many a times, an output may have both CEA and non-CEA modes, which are similar in all resepct,
differing only in the aspect-ratio. A user can select a CEA mode by giving the aspect-ratio, along
with the other arguments for the mode. By omitting the aspect-ratio, user can specify the non-CEA
modes. This helps when certification testing is done, in tests like 7-27, the HDMI-analyzer
applies a particular CEA mode, and expects the applied mode to be with exactly same timings,
including the aspect-ratio and VIC field.

The resolution can also be a detailed mode line as below.

mode=dotclock hdisp hsyncstart hsyncend htotal vdisp vsyncstart vsyncend vtotal hflag vflag
Use the given detailed mode line as the video mode for this output. The definition is the same as
in xorg.conf(5), and cvt(1) can generate detailed mode lines.

transform=transform
Transform for the output, which can be rotated in 90-degree steps and possibly flipped. Possible
values are normal, rotate-90, rotate-180, rotate-270, flipped, flipped-rotate-90, flipped-
rotate-180, and flipped-rotate-270.

gbm-format=format
Set the DRM KMS framebuffer format for this specific output. If not set, the value from gbm-format
option in core section is used for SDR mode outputs and xrgb2101010 for other modes. For the
possible values for format see gbm-format option in core section. For SDR mode, see eotf-mode in
weston.ini(7).

pixman-shadow=boolean
If using the Pixman-renderer, use shadow framebuffers. Defaults to true.

same-as=name
Make this output (connector) a clone of another. The argument name is the name value of another
output section. The referred to output section must exist. When this key is present in an output
section, all other keys have no effect on the configuration.

NOTE: cms-colord plugin does not work correctly with this option. The plugin chooses an arbitrary
monitor to load the color profile for, but the profile is applied equally to all cloned monitors
regardless of their properties.

force-on=true
Force the output to be enabled even if the connector is disconnected. Defaults to false. Note
that mode=off will override force-on=true. When a connector is disconnected, there is no EDID
information to provide a list of video modes. Therefore a forced output should also have a
detailed mode line specified.

max-bpc=N
Set "max bpc" KMS property to value N, silenty clamped to the hardware driver supported range.
This artificially limits the driver chosen link bits-per-channel which may be useful for working
around sink hardware (e.g. monitor) limitations. The default is 16 which is practically unlimited.
If you need to work around hardware issues, try a lower value like 8. A value of 0 means that the
current max bpc will be reprogrammed.

Section remote-output
name=name
Specify unique name for the output.

mode=mode
Specify the video mode for the output. The argument mode is a resolution setting, such as:

mode=widthxheight

mode=widthxheight@refresh_rate
If refresh_rate is not specified it will default to a 60Hz.

host=host
Specify the host name or IP Address that the remote output will be transmitted to.

port=port
Specify the port number to transmit the remote output to. Usable port range is 1-65533.

gst-pipeline=pipeline
Specify the gstreamer pipeline. It is necessary that source is appsrc, its name is "src", and sink
name is "sink" in pipeline. Ignore port and host configuration if the gst-pipeline is specified.

OPTIONS

       When the DRM backend is loaded, weston will understand the following additional command line options.

       --current-mode
              By  default,  use  the  current  video  mode  of  all outputs, instead of switching to the monitor
              preferred mode.

       --drm-device=cardN
              Use the DRM device cardN for rendering and output instead of the default heuristics based on  seat
              assignments and boot VGA status. For example, use card0.

       --additional-devices=cardN
              Comma  separated  list of secondary DRM devices cardM,cardN that will only be used as outputs, but
              not for rendering. For example, use card1,card2.

       --seat=seatid
              Use graphics and input devices designated for seat seatid instead  of  the  seat  defined  in  the
              environment variable XDG_SEAT. If neither is specified, seat0 will be assumed.

       --continue-without-input
              Allow Weston to start without input devices. Used for testing purposes.

ENVIRONMENT