Developer Guide
5.1.15 Release

Wayland Window System
EGLOutput/EGLDevice Specifications
Runtime Configuration
libdrm Support
Weston Common Options
Weston Backend Options
Multimonitor Considerations in Overlay-Compositing Mode
Weston Configuration File Location
Weston Display Configuration
Prerequisites to Starting Weston
Starting Weston
Running Weston Samples
Wayland is a protocol that a backend compositor uses to communicate with its clients. It is also a C library implementation of that protocol. Weston is the reference implementation of the Wayland compositor. The platform supports Wayland and Weston. Check the Release Notes for specific versions supported.
For more information about Wayland, see the Wayland home page and documentation page at:
EGLOutput/EGLDevice Specifications
NVIDIA defines extensions to enumerate and control devices and screens through EGL. These are collectively referred to as EGLOutput/EGLDevice.
The EGLOutput/EGLDevice specifications used by Weston are as follows:
EGL_EXT_device_base—Allows the initialization of EGL displays directly on top of native GPU or device objects.
EGL_EXT_device_drm—Allows mapping of device between EGL and DRM/KMS.
EGL_EXT_output_base—Allows rendering to be directed to a screens or display outputs.
EGL_EXT_output_drm— Allows mapping of output handles between EGL and DRM/KMS.
EGL_EXT_stream_consumer_egloutput— Allows the binding of EGLOutputLayerEXTs as stream consumers.
EGL_KHR_stream_consumer_gltexture— Allows an OpenGL(ES) texture to be connected to an EGLStream as its consumer.
The Weston compositor uses EGLOutput/EGLDevice to display the composited Weston desktop or individual Wayland applications on a physical display device.
Runtime Configuration
The platform provides utilities for changing the configuration and runtime parameters.
For binary and library paths, Ubuntu root filesystem is assumed in the following sections. Other root filesystems (e.g., Yocto) may have different binary and library paths.
The full source code to the NVIDIA implementation of Weston is in:
The NVIDIA implementation of Weston uses the Direct Rendering Manager (DRM) backend, found in the target filesystem at:
The DRM backend is implemented on top of the EGLOutput family of extensions. See EGLOutput specifications.
During the Weston startup, Weston creates an OpenGL ES EGLStream producer and an EGLOutput EGLStream consumer that passes all the output frames from Weston to the display.
Wayland buffer sharing between EGL clients and Weston is implemented using EGLStreams. The EGL client creates an EGLStream producer and binds the EGLStream file descriptor to wl_buffer through the Wayland protocol. Weston queries the EGLStream file descriptor from wl_buffer through a query of EGL_WAYLAND_BUFFER_WL to eglQueryWaylandBufferWL(). This functionality is provided by the EGL_WL_bind_wayland_display extension.
The NVIDIA Weston implementation can operate in two modes: GL-Composition and Overlay-Compositing
GL-Composition, the default mode relies on the EGL_KHR_stream_consumer_gltexture and EGL_EXT_stream_consumer_egloutput extensions, where Weston gets the file descriptor from the above eglQueryWaylandBufferWL() and creates an EGLStream consumer by binding it to an OpenGL texture. This texture is then managed by the Weston compositor as any other client. Buffers are sent through EGLStreams from the Wayland client application to Weston. Weston can then composite the buffers from multiple clients into an OpenGL ES texture. The final composited texture is sent to an EGLOutput Consumer, to which Weston is already bound to during Weston start, which displays the composited texture onto the display.
Overlay-Composting relies on the EGL_EXT_stream_consumer_egloutput extension, where Weston gets the file descriptor from the above eglQueryWaylandBufferWL() and creates an EGLStream consumer by binding it to an EGLOutput layer consumer, corresponding to an overlay plane. Buffers are sent through EGLStreams from the Wayland client application to Weston and bound to an EGLOutput layer corresponding to a hardware display overlay plane.
This mode is enabled by starting Weston as follows:
/usr/local/bin/weston --overlay-compositing &
Weston itself is always bound to an EGLOutput layer consumer.
Overlay planes are a limited hardware resource. As the base overlay is used by the Weston, only the remaining overlays can be used by the EGL applications. If, for example, a connector supports 2 overlay planes, it is possible to run a maximum of 2 EGL applications simultaneously in the second mode. There is no such limitation in the first mode.
The NVIDIA EGL implementation tries to detect what platform it is running on at runtime (e.g., Wayland, etc.). It is possible to bypass this detection by setting the EGL_PLATFORM environment variable. For Wayland, this variable must be set to "wayland". And do not set the environment variable DISPLAY in case of the wayland platform. If DISPLAY is set, you are assumed to be running X11.
libdrm Support
The libdrm.so library is used to set display modes and to attach framebuffer images to display overlays. The platform custom implementation of libdrm.so is not implemented on top of the DRM-KMS display driver. Instead, it is implemented on top of the NVIDIA NVDC display driver.
Weston requires the NVIDIA custom libdrm.so and is not compatible with the default Ubuntu libdrm.so.
The default Ubuntu libdrm libraries are located at:
The sdk installation deletes those libraries and replaces them with libdrm.so at:
When installing 3rd party packages or new software with apt-get, you must make sure that libdrm.so* shared objects are not recreated. If they exist, remove them from:
Weston Common Options
Weston supports multiple backends. This section describes the core options that all Weston backends support.
Prints the Weston version.
-B, --backend
eglstream-backend.so (for cross partition use cases)
Specifies the backend module. Defaults to drm-backend.so.
Usage: --backend=<module>, where module is one of the parameters.
Specifies the shell module. Defaults to desktop-sheel.so.
Usage: --shell=<module>, where module is one of the parameters.
-S, --socket
<socket name>
Listens to the specified socket name.
Usage: --socket=<socket name>for applications.
-i, --idle-time
Specifies the idle time in seconds.
<file name>
Displays the log for the given file.
Usage: --log=<file name>
-h, --help
Displays the help message.
Weston Backend Options
Weston supports multiple backends and, depending on the backend used, accepts different options. NVIDIA supports drm-backend.so, which allows Weston to support NVIDIA graphics.
drm-backend.so options
The supported drm-backend.so options and the values they consume are as follows.
<connector ID>
Brings up the specified connector.
Usage: --connector=<connector ID>
For HDMI monitor, the connector ID is 1001.
For mini DP, the connector ID is 1000.
The connector ID is displayed in the Weston start log.
Specifies to not create input devices.
Specifies that current DRM mode is preferred over EDID mode. If the display is already turned on by any DRM application other than Weston, Weston uses the current DRM mode instead of a new display mode from the monitor EDID.
Assigns EGL clients to individual overlays, allowing for hardware composition. The number of apps started is limited to the number of overlays available.
Plane Index
Composite EGL clients to plane identified by index IDX rather than primary plane. This option is incompatible with -overlay-compositing.
Depending on the number of overlays, this index value changes.
By default, each connector (HDMI, mini DP) has 3 overlays.
Index value 0 starts Weston on overlay 0 (primary plane).
Index value 1 starts Weston on overlay 1.
Index value 2 starts Weston on overlay 2.
Multimonitor Considerations in Overlay-Compositing Mode
When starting Weston in overlay-compositing mode, every application is assigned a different hardware layer. By default, an application will be assigned the first available (not yet assigned) overlay, no matter what display/output that overlay belongs to. That means, in a two-monitor setup, the first and second launched applications are assigned overlays of the first display; the third and fourth applications will be assigned overlays of the second display.
Change how overlays are assigned and start applications on specific displays by setting the WESTON_EGLOUTPUT_OVERLAY_POLICY environment variable before starting Weston. The WESTON_EGLOUTPUT_OVERLAY_POLICY environment variable accepts the following values:
Assigns the first free overlay found, regardless of what output the overlay belongs to. This is the same as leaving the variable unset.
Assigns the first free overlay found, but uses an overlay from a different output each time, following a round-robin algorithm.
Colon-delimited custom list of output indexes. The nth index of the list indicates the output for the nth created surface.
A value of 0 indicates no preference, e.g.,
WESTON_EGLOUTPUT_OVERLAY_POLICY=1:3:2:0:4 specifies the following:
The first created surface must go to the first output (output id = 0),the second created surface must go to third output (output id = 2), the third created surface must go to 2nd output (output id = 1), the fourth created surface can go to any available output, and the fifth created surface must go to the fourth output (output id = 3).
Weston Configuration File Location
Weston uses a configuration file called weston.ini for its setup. When Weston starts, it will search for the weston.ini configuration file in one of the following places:
If $XDG_CONFIG_HOME is set, Weston searches in:
If $HOME is set, Weston searches in:
If $XDG_CONFIG_DIRS is set, Weston searches in:
If $XDG_CONFIG_DIRS is not set, Weston searches in:
If no variables are set, Weston searches in:
<current dir>/weston.ini
Where the environment variable:
$HOME is your home directory.
$XDG_CONFIG_HOME is your specific configuration directory.
$XDG_CONFIG_DIRS is a colon ':' delimited list of configuration base directories, such as /etc/xdg-foo:/etc/xdg.
Weston Display Configuration
Weston picks the default settings for display by itself. If the default settings are insufficient, the display settings can be defined in weston.ini.
To configure the display, add the following to weston.ini with the appropriate values for output name, mode, and transform:
Where name=<output_name> sets a name for the output string. The backend uses the name to identify the output.
Output Name
Laptop internal panel number 1.
VGA connector number.
The mode=<mode> assignment sets the output mode string. The mode parameter is handled differently depending on the backend. The DRM backend accepts different modes:
Resolution size width and height in pixels.
Uses the preferred mode.
Uses the current CRT controller mode.
Disables the output.
Optionally, you can specify a modeline, for example:
173.00 1920 2048 2248 2576 1080 1083 1088 1120 -hsync +vsync
A modeline consists of the refresh rate in Hz, the horizontal and vertical resolution, and options for horizontal and vertical synchronization. The cvt(1) program provides a suitable modeline string.
The transform=<transformation> assignment applies the transformation to the screen output string. The transform key must be one of the following 8 strings:
Transform string
Normal output.
90 degrees clockwise.
Upside down.
90 degrees counter clockwise.
Horizontally flipped.
Flipped and rotated 90 degrees clockwise.
Flipped upside down.
Flipped and 90 degrees counter clockwise.
The following is a weston.ini configuration example:
Prerequisites to Starting Weston
Weston creates its Unix socket file, for example wayland-0, in the directory specified by the required environment variable $XDG_RUNTIME_DIR. $XDG_RUNTIME_DIR defines the base directory relative to which user-specific non-essential runtime files and other file objects (such as sockets, named pipes, etc.) are stored.
Check whether the $XDG_RUNTIME_DIR environment variable is set, if it is not set please set it as follows.
Setting the $XDG_RUNTIME_DIR Directory
Use either of the following two methods to set the $XDG_RUNTIME_DIR directory before running Weston:
Set $XDG_RUNTIME_DIR manually
Set $XDG_RUNTIME_DIR using your shell profile
To set the $XDG_RUNTIME_DIR directory manually
Execute the following:
mkdir /tmp/xdgruntime
chmod 700 /tmp/xdgruntime
export XDG_RUNTIME_DIR=/tmp/xdgruntime
At runtime, /tmp/xdgruntime looks like:
root@nvidia:/# ls -lt /tmp/xdgruntime
total 0
srwxr-xr-x 1 root root 0 May 12 11:31 wayland-0
-rw-r----- 1 root root 0 May 12 11:31 wayland-0.lock
To set the $XDG_RUNTIME_DIR directory using your shell profile
Modify your shell profile to perform the manual steps described above. For information on modifying your shell, see the manual for your shell. Also see these important tips for when modifying your shell profile to set up $XDG_RUNTIME_DIR:
Determine the correct shell profile to modify.
Some shells read multiple files (Zshell). Others pick the first available file, ignoring the others (Bash). ~/.profile is generally a good guess for most Bourne-shell compatible shells; ~/.zprofile is the Zshell equivalent. Use the profile file if there is one; otherwise, use the login file. The software automatically uses the variable once it is set. This is useful if you want to use your profile file on different systems.
Put the following code in your shell profile and adapt it to your shell’s internals. This code is Bourne-shell compatible.
if test -z "${XDG_RUNTIME_DIR}"; then export XDG_RUNTIME_DIR=/tmp/${UID}-runtime-dir
if ! test -d "${XDG_RUNTIME_DIR}"; then mkdir "${XDG_RUNTIME_DIR}"
chmod 0700 "${XDG_RUNTIME_DIR}"
Starting Weston
Weston, the Wayland reference compositor, expects a keyboard and mouse to be connected when it starts. If you are starting Weston without a mouse and keyboard connected, use the --no-input option.
To start Weston with root privileges
Execute the following command to switch to superuser:
sudo su
The default password is nvidia.
Then launch weston as in the following sections
To start Weston on desktop-shell
Execute the following command:
weston &
By default, Weston runs using desktop-shell.
To start Weston with ivi-shell and hmi-controller
Execute the following command:
weston --shell=ivi-shell.so &
ivi-shell can pull different controllers that effectively take care of the window management.
By default, weston.ini is configured so that ivi-shell loads hmi-controller:
ivi-shell-user-interface=absolute path to “weston-ivi-shell-user-interface”
By default, weston.ini sets the background-color to 0x00000000 (ARGB color). Therefore, a plain black background is expected.
To start Weston with ivi-shell and ivi-controller
Modify weston.ini to load ivi-controller:
Execute the following command:
weston --shell=ivi-shell.so &
This starts Weston with IVI shell using the corresponding controller module. The display should remain black. The ivi-controller does not provide any desktop decorations, by default.
To start Weston without root privileges
Weston can be launched as non-root with the weston-launch binary. It is present in /usr/local/bin for Ubuntu rootfs. Follow the steps below to launch weston as non-root.
1. Add the non root user to weston-launch group:
sudo su
usermod -a -G weston-launch <non_root_user_name>
chown root /usr/local/bin/weston-launch
chmod +s /usr/local/bin/weston-launch
2. Launch weston with weston-launch binary as non-root:
su <non_root_user_name>
weston-launch [args...] [-- [weston args..]]
For example:
Run weston-launch with desktop-shell:
weston-launch -- --shell=desktop-shell.so
Run weston-launch with ivi-shell:
weston-launch -- --shell=ivi-shell.so
Running Weston Samples
Use these procedures to run the Weston samples.
The instructions provided assume Weston and Wayland are running as superuser.
To start Weston-simple-egl with ivi-shell and hmi-controller
Execute the command:
weston-simple-egl &
To start Weston-simple-egl with ivi-shell and ivi-controller
1. Execute the command:
weston-simple-egl -width 1920 -height 1080 -surface 10 &
2. Manually configuring the client surface:
LayerManagerControl set surface 10 source region 0 0 1920 1080
LayerManagerControl set surface 10 destination region 0 0 1920 1080
LayerManagerControl set surface 10 visibility 1
Nothing appears on the screen because the application surface is not linked to a layer.
3. Create a layer and attach the client surface to it:
LayerManagerControl create layer 1000 1920 1080
LayerManagerControl set layer 1000 render order 10
LayerManagerControl set layer 1000 visibility 1
4. Link your layer to a screen:
LayerManagerControl set screen 0 render order 1000