NVIDIA Tegra
NVIDIA DRIVE OS 5.1 Linux

Developer Guide
5.1.0.2 Release


 
Wayland Window System
 
EGLOutput/EGLDevice Specifications
Building Weston from Source
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 clients. It is also a C library implementation of that protocol. Weston is the reference implementation of the Wayland compositor. The DRIVE AGX platform supports Wayland and Weston. Consult the Release Notes for specific versions supported.
Consult the Wayland website for more information :
http://wayland.freedesktop.org/
http://wayland.freedesktop.org/docs/html/
EGLOutput/EGLDevice Specifications
To direct output to display screens in the absence of a full window system, for example X, NVIDIA defines extensions to enumerate and control devices and screens through EGL screens. These are collectively referred to as EGLOutput.
The EGLOutput/EGLDevice specifications used by Weston are as follows:
Extension
Link
EGL_EXT_device_base—Allows the initialization of EGL displays and surfaces directory on top of native GPU or device objects rather than native window system objects.
EGL_EXT_device_drm—Allows mapping of device between EGL and DRM/KMS.
EGL_EXT_output_base—Creates demand for a method to initialize EGL displays and surfaces directly on top of native GPU or device objects rather than native window system objects.
EGL_EXT_output_drm—Listens to the specified socket name.
Usage: --socket=<socket name>for applications.
EGL_EXT_stream_consumer_egloutput—Allows mapping of output handles between EGL and DRM/KMS.
EGL_KHR_stream_consumer_gltexture—Allows the binding of EGLOutputLayerEXTs as stream consumers.
The Weston compositor uses EGLOutput/EGLDevice to display the composited Weston desktop or individual Wayland applications on a physical display device.
Building Weston from Source
This topic applies to the Ubuntu root filesystem. Yocto includes other recipe scripts for building Weston.
Before building Weston from source, ensure the prerequisites are met.
Prerequisites
Install the dependent packages, which include:
Ensuring the host system is connected to the Internet.
On the host, enter the command:
sudo apt-get install autoconf libtool cmake
To build Weston
1. Navigate to the Weston sample directory at:
cd <top>/drive-t186ref-linux/samples/wayland/weston
2. Execute the build script:
./drive-SDK-build-weston.sh
If the output directory is not specified, a Weston binary and all Weston modules libraries are created at:
<top>/weston_sysroot_aarch64/weston_install
To specify another output directory, use the WESTON_INSTALL_DIR environment variable:
WESTON_INSTALL_DIR=<desired_directory> ./drive-SDK-build-weston.sh
Complete usage message of the build script can be printed by running:
./drive-SDK-build-weston.sh help
To install Weston
To install custom-built Weston onto the target, copy all resulting files and folders under WESTON_INSTALL_DIR onto the root folder of the target filesystem.
If the target filesystem is NFS-mounted:
cp -r <top>/weston_sysroot_aarch64/weston_install/* <rootfs_mountpoint_on_host>/
If target filesystem is not NFS-mounted:
scp <top>/weston_sysroot_aarch64/weston_install/* nvidia@<target_ip_addr>:/
By default, the build script creates the files under the /usr directory on the target filesystem. To use another destination directory, the WESTON_PREFIX_DIR environment variable must be set accordingly when running the build script:
WESTON_PREFIX_DIR=/home/nvidia/custom_weston ./drive-SDK-build-weston.sh
Runtime Configuration
The SDK provides utilities for changing the configuration and run-time parameters.
Note:
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:
drive-t186ref-linux/samples/wayland/weston
The NVIDIA implementation of Weston uses the Direct Rendering Manager (DRM) backend, found in the target filesystem at:
/usr/local/lib/weston/drm-backend.so
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.
The first mode, called GL-Composition, 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 OpenGL texture. This texture is then managed by the Weston compositor as any other client. Buffers are sent through EGL Streams from the Wayland client application to Weston. Weston can then composite the buffers from multiple clients into OpenGL ES texture. The final composited texture is sent to EGLOutput Consumer, to which Weston is already bound to during Weston start, which displays the composited texture onto the display. This is the default mode.
Before running Weston, ensure the Prerequisites are met.
weston &
The second mode, called 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, which corresponds 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:
/weston --overlay-compositing &
Note:
Weston itself is always bound to an EGLOutput layer consumer.
Overlay planes are a limited hardware resource. If, for example, a connector supports 3 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".
libdrm Support
The libdrm.so library is used to set display modes and to attach framebuffer images to display overlays. The AGX 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:
/usr/lib/arm64-linux-gnu/libdrm.so*
The SDK installation deletes those libraries and replaces them with libdrm.so at:
/usr/lib/libdrm.so
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:
/usr/lib/arm64-linux-gnu/
Weston Common Options
Weston supports multiple backends. The core options that all Weston backends support are as follows.
 
Command
Parameter(s)
Description
--version
N/A
Prints the Weston version.
-B, --backend
drm-backend.so
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.
--shell
desktop-shell.so
ivi-shell.so
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
<seconds>
Specifies the idle time in seconds.
--log
<file name>
Displays the log for the given file.
Usage: --log=<file name>
-h, --help
N/A
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
This topic provides a list of supported drm-backend.so options and the values they consume.
Command
Parameter(s)
Description
--connector
<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.
--no-input
N/A
Specifies to not create input devices.
--current-mode
N/A
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.
--overlay-compositing
N/A
Assigns EGL clients to individual overlays, allowing for hardware composition. The number of apps started is limited to the number of overlays available.
--preferred-plane
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 1 (primary plane).
Index value 1 starts Weston on overlay 2.
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, first and second launched applications are assigned overlays of first display and third and fourth ones will be assigned overlays of 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:
Value
Description
Default
Assigns the first free overlay found, regardless of what output the overlay belongs to. This is the same as leaving the variable unset.
Roundrobin
Assigns the first free overlay found, but uses an overlay from a different output each time, following a round-robin algorithm.
<num>:<num>
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:
$XDG_CONFIG_HOME/weston.ini
If $HOME is set, Weston searches in:
$HOME/.config/weston.ini
If $XDG_CONFIG_DIRS is set, Weston searches in:
$XDG_CONFIG_DIR/weston/weston.ini
If $XDG_CONFIG_DIRS is not set, Weston searches in:
/etc/xdg/weston/weston.ini
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 not sufficient, 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:
[output]
name=<output_name>
mode=<mode>
transform=<transformation>
Where name=<output_name> sets a name for the output string. The backend uses the name to identify the output.
Output
Description
LVDS1
Laptop internal panel number 1.
VGA1
VGA connector number.
X1
X window number 1.
The mode=<mode> assignment sets the output mode string. The mode parameter is handled differently depending on the backend. The DRAM backend accepts different modes:
Mode
Description
WIDTHxHEIGHT
Resolution size width and height in pixels.
preferred
Uses the preferred mode.
current
Uses the current CRT controller mode.
off
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
Description
normal
Normal output.
90
90 degrees clockwise.
180
Upside down.
270
90 degrees counter clockwise.
flipped
Horizontally flipped.
flipped-90
Flipped and rotated 90 degrees clockwise.
flipped-180
Flipped upside down.
flipped-270
Flipped and 90 degrees counter clockwise.
The following is a weston.ini configuration example:
[output]
name=LVDS1
mode=1680x1050
transform=90
icc_profile=/usr/share/color/icc/colord/Bluish.icc
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. The $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 are stored.
This functionality is provided using systemd by some distributions (Fedora, Arch since June 2012, or Exherbo). Ubuntu began providing it in Quantal. It is not provided by Gentoo. If you are using a distribution that sets $XDG_RUNTIME_DIR for you, you can skip the rest of this section. Otherwise, you must set it using your shell profile capability.
For best practices, create a /tmp directory as the base to put the $XDG_RUNTIME_DIR variable for filesystems other than QNX.
Ensure these prerequisites are met:
You are the owner of the temporary directory and you are the only person who has read and write access.
The lifetime of the directory is bound to you being logged in. It is created when you first log in and deleted when you fully log out.
If you log in more than once, the directory exists from your first login to your last logout on the system; it remains until your last logout.
Files in the directory do not survive reboot or a full login/logout cycle.
If you share your computer among multiple users, you use a unique $XDG_RUNTIME_DIR for each user.
You have set $XDG_RUNTIME_DIR.
For root filesystems other than QNX, 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 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]
ivi-module=hmi-controller.so
ivi-shell-user-interface=absolute path to “weston-ivi-shell-user-interface”
 
 
Note:
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:
[ivi-shell]
ivi-module=ivi-controller.so
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.
Running Weston Samples
Use these procedures to run the Weston samples.
For best practices, use the root user when running Weston.
To become root user
Execute the following command to switch to superuser:
sudo su
The default password is nvidia.
If Weston is running without superuser, use the sudo -E option to start Weston and Wayland client applications.
Beginning with Ubuntu 16.04, sudo -E must be used for the sudo environment to select the XDG_RUNTIME_DIR value.
The instructions provided assume Weston and Wayland is 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 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