Weston (Wayland) Windowing System

L4T supports the Weston implementation of the Wayland windowing system. The current release of L4T supports Weston 6.0.

Running Weston 6.0

The current release of Jetpack supports Weston 6.0. You can launch it by entering these commands:
# Stop X xerver
sudo service gdm stop; sudo pkill -9 Xorg
 
# Use Tegra DRM driver
sudo modprobe tegra-udrm modeset=1
sudo ln -sf /usr/lib/aarch64-linux-gnu/tegra/libnvgbm.so /usr/lib/aarch64-linux-gnu/libgbm.so.1
 
# Environment and directory setup
unset DISPLAY
mkdir /tmp/xdg
chmod 700 /tmp/xdg
 
# Choose a valid tty
export WESTON_TTY=1
 
# Launch Weston
sudo XDG_RUNTIME_DIR=/tmp/xdg weston --tty="$WESTON_TTY" --idle-time=0 &
# Optional: WAYLAND_DEBUG=server
# Optional: use --use-egldevice to disable gbm swapchains and use EGLStreams at weston output
 
# Run a client (can we do this without root? => No)
sudo XDG_RUNTIME_DIR=/tmp/xdg weston-simple-egl
# Optional: WAYLAND_DEBUG=1
 
# For running Weston tests, the weston-test.so module needs to be loaded by a parameter, or in weston.ini.
# E.g. --modules=/usr/lib/aarch64-linux-gnu/tegra/weston/weston-test.so

Multiple Display Heads

NVIDIA® Jetson™ Nano series and Jetson TX2 series devices support multiple display heads with multiple overlays as described in the Display Configuration and Bring-Up topic of the Jetson Linux Driver Package Development Guide.
Weston 6.0 supports multiple heads on L4T as well. Use weston.ini to set the expected resolution and orientation of the monitors.
If multiple displays are connected, applications are launched on the one that contains the mouse pointer at the time of launch. Once an application is launched, you can drag it across a boundary between displays.
If multiple displays are connected and they have different resolutions, Weston reports the frame rate of the display on which more than 50% of its window is displayed.
If a monitor is removed while Weston is running (hot removal), running applications dynamically shift to the remaining active monitor.

Example of weston.ini Display Options

Use this example as a model for setting your own display options in weston.ini.
name=HDMI-A-1
mode=1920 x 1080
transform=90 (0,90,180,270)

Hot-Plugging

Weston monitors events sent by the Direct Rendering Manager (DRM) subsystem using udev. When the display configuration changes, udev receives a HOTPLUG event. It calls drmModeGetResources() to identify connectors that have been added or removed, and takes actions accordingly.
On T210 there is no real kernel mode DRM driver; instead there is a user mode DRM driver, drm-nvdc, and a dummy kernel mode DRM driver, tegra-udrm. These drivers work together to provide a real DRM driver-like interface to Weston. The tegra-udrm driver signals a HOTPLUG event when the display connection state changes.

Verified Use Cases

Disconnect and connect the HDMI™ display after launching Weston.
Disconnect and connect the HDMI display while the application nvgldemo is running, and verify that application drawing is visible after connection.
Launch Weston without an HDMI display connected and then connect an HDMI display.
Launch Weston without an HDMI display connected, launch the nvgldemo application, and then connect an HDMI display.
All of the use cases above are also verified with DisplayPort displays.

Issues Fixed in Weston

Application window disappears when display is re-connected.
A fix for this issue has been backported to the downstream Weston 6 codeline from the upstream Weston main codeline. See the freedesktop.org GitLab for more information.

Compositing Mode in Weston

Weston supports mixed mode compositing using dma-buf. The T210 has three display windows per head. Weston assigns one window to the GFX plane. The other two are available to be renamed as secondary overlay planes. On every frame Weston evaluates all surfaces and views and chooses one of these strategies to composite them:
DRM_OUTPUT_PROPOSE_STATE_MIXED (Overlay + GL)
DRM_OUTPUT_PROPOSE_STATE_RENDERER_ONLY (GL)
DRM_OUTPUT_PROPOSE_STATE_PLANES_ONLY (Overlay only)
The demo application weston-simple-dmabuf-egldevice demonstrates mixed-mode compositing path in weston, where some surfaces are assigned overlay planes and others are composited with GL.
You can use the application weston-debug to verify that overlay plans are being assigned. Use the following procedure.
1. Stop X if it is running and prepare the device for launching Weston:
$ sudo service gdm stop; sudo pkill -9 Xorg
$ unset DISPLAY
$ mkdir /tmp/xdg
$ chmod 700 /tmp/xdg
$ export WESTON_TTY=1
$ sudo modprobe tegra-udrm modeset=1
$ sudo ln -sf /usr/lib/aarch64-linux-gnu/tegra/libnvgbm.so /usr/lib/aarch64-linux-gnu/libgbm.so.1
2. Launch Weston with the --debug switch:
$ sudo XDG_RUNTIME_DIR=/tmp/xdg weston --tty="$WESTON_TTY" --idle-time=0 --debug &
3. Launch a few Weston client applications:
$ sudo XDG_RUNTIME_DIR=/tmp/xdg weston-simple-egl &
$ sudo XDG_RUNTIME_DIR=/tmp/xdg weston-simple-dmabuf-egldevice &
$ sudo XDG_RUNTIME_DIR=/tmp/xdg weston-simple-dmabuf-egldevice &
$ sudo XDG_RUNTIME_DIR=/tmp/xdg weston-simple-dmabuf-egldevice &
4. Run the weston-debug application:
$ sudo XDG_RUNTIME_DIR=/tmp/xdg ./weston-debug -a
5. Look for information like that shown below in the weston-debug output. Blue colored surfaces are overlay-composited and green-colored surfaces are GL-composited.
Layer 5 (pos 0x50000000):
View 0 (role xdg_toplevel, PID 8080, surface ID 3, top-level window 'simple-dmabuf-egldevice', 0x33c798b0):
position: (714, 860) -> (970, 1116)
[not opaque]
outputs: 0 (HDMI-A-1) (primary)
dmabuf buffer
format: 0x34325258 XRGB8888
modifier: 0x3800000000fe014
View 1 (role xdg_toplevel, PID 8073, surface ID 3, top-level window 'simple-dmabuf-egldevice', 0x33bb9500):
position: (209, 591) -> (465, 847)
[not opaque]
outputs: 0 (HDMI-A-1) (primary)
dmabuf buffer
format: 0x34325258 XRGB8888
modifier: 0x3800000000fe014
 
View 2 (role xdg_toplevel, PID 8066, surface ID 3, top-level window 'simple-dmabuf-egldevice', 0x31769110):
position: (1129, 339) -> (1385, 595)
[not opaque]
outputs: 0 (HDMI-A-1) (primary)
dmabuf buffer
format: 0x34325258 XRGB8888
modifier: 0x3800000000fe014
 
View 3 (role xdg_toplevel, PID 8051, surface ID 9, top-level window 'simple-egl', 0x314c6430):
position: (1343, 642) -> (1593, 892)
[not opaque]
outputs: 0 (HDMI-A-1) (primary)
EGL buffer
 
Layer 6 (pos 0x2):
...
[view] evaluating view 0x33c798b0 for output HDMI-A-1 (0)
[view] view 0x33c798b0 format: XRGB8888
[overlay] provisionally placing view 0x33c798b0 on overlay 4002 in mixed mode
[view] evaluating view 0x33bb9500 for output HDMI-A-1 (0)
[view] view 0x33bb9500 format: XRGB8888
[overlay] provisionally placing view 0x33bb9500 on overlay 4001 in mixed mode
[view] evaluating view 0x31769110 for output HDMI-A-1 (0)
[view] view 0x31769110 format: XRGB8888
[overlay] not placing view 0x31769110 on overlay: no free overlay planes
[view] evaluating view 0x314c6430 for output HDMI-A-1 (0)
[overlay] not placing view 0x314c6430 on overlay: couldn't get fb
[repaint] Using mixed state composition
[repaint] view 0x33c798b0 on Overlay plane 4002
[repaint] view 0x33bb9500 on Overlay plane 4001
[repaint] view 0x31769110 using renderer composition
[repaint] view 0x314c6430 using renderer composition

NV16/NV24 in Weston

The Weston GL compositor adds support for NV16 and NV24 content via shared memory buffers.
NV24 is not part of any released version of Wayland (the latest is 1.18 as of this writing), but it was added to the Wayland main branch on September 2, 2019, and will likely be included in the next official release. Applications that need to use the WL_SHM_FORMAT_NV24 enumerant can substitute DRM_FORMAT_NV24, as by convention both enumerations use symbols defined in drm_fourcc.h to identify most formats, including other NVxx formats.
The experimental Weston VIC compositor does not yet support NV16 and NV24.

Shared-Memory Rendering

The Weston test color-format.weston exercises shared-memory rendering for all formats that Weston currently supports. Though implemented as a test case, it is intended for visual verification, and it must be manually terminated.
To run the test case
1. Start Weston with the weston-test.so module, for example:
$ sudo XDG_RUNTIME_DIR=/tmp/xdg weston --tty="$WESTON_TTY" --idle-time=0 --modules=weston-test.so &
2. Enter this command to execute the test application:
$ sudo XDG_RUNTIME_DIR=/tmp/xdg color-format.weston
The application displays eight color test patterns, each rendered using a different color format. All should appear substantially identical, with minor variations caused by the limitations of the formats.
3. To terminate the test, enter Ctrl-C.

DMA Buffer Rendering

DRM now supports NV16 and NV24 color formats. To use these formats, construct an EGLImage from the DMA buffer via the exposed EXT_image_dma_buf_import and EXT_image_dma_buf_import_modifiers extensions.
Currently only block-linear DMA buffer layouts are supported. DRM_FORMAT_NV21, DRM_FORMAT_NV16, and DRM_FORMAT_NV24 have been added to supported_drm_formats.
To run a verified use case (video playback test)
Enter this command:
$ gst-launch-1.0 filesrc location=<mp4_src_file> ! qtdemux ! h264parse ! nvv4l2decoder ! nvvidconv ! 'video/x-raw(memory:NVMM), width=(int)1280, height=(int)720, format=(string)<format>' ! nvdrmvideosink
Where:
<mp4_src_file> is the pathname of the apt source file
<format> is NV16 or NV24.
The gst-launch-1.0 command is a GStreamer pipeline to display video. It uses the nvvidconv plugin to convert other formats in the stream to NV16/NV24. The video is displayed with the nvdrmvideosink plugin, which internally uses DRM.

VPR Memory

You can allocate VPR memory using nbuf_utils, GBM and eglStream.
With nvbuf_utils: Add the NvBufferTag_PROTECTED tag via NvBufferCreateParams() and pass to NvBufferCreate().
With GBM: Specify the GBM_BO_USE_PROTECTED usage flag for gbm_bo_create().
With EglStreams: Add the EGL_PROTECTED_CONTENT_EXT attribute when creating eglSurface objects. Specify the texture parameter GL_TEXTURE_PROTECTED_EXT for protected textures.
To write to protected textures with GL you must also use a protected context, which you may create by specifying the EGL_PROTECTED_CONTENT_EXT attribute. Note that you must also specify this attribute when you import dmabuf into EGL, in the case where the dmabuf is created in VPR memory.
To run a sample case
Run the weston-simple-dmabuf-egldevice app with the -p switch.
To verify the correctness of the result, examine it on the screen. It should be the same as when you run the app without using VPR memory.
Current Limitations
The VPR content can only be rendered on the screen with overlay GLcomposition. GL does not support protected content yet. Such support will be added in later releases.
Thus, if there are several windows on the screen exceeding the limit for overlay composition, protected content is not rendered for the excess windows.
HDCP support is not available yet. It will be supported in a future release. For Jetson Nano series, though, you can display VPR content onscreen even without establishing an HDCP link.

Weston dma-buf Support

Clients can post dma-buf buffers to Weston using the Linux DMA-BUF Unstable V1 Protocol of Wayland. Dma-buf support with Weston has following components.

Buffer Allocation

GBM is commonly used to allocate buffers, which are backed by the dma-buf file descriptor.
This code snippet shows how to allocate a buffer using GBM:
drm_fd = open("/dev/dri/card0", O_RDWR);
device = gbm_create_device(drm_fd);
bo = gbm_bo_create_with_modifiers(device, width, height,
format, modifiers, modifiers_count);
Weston supports the formats DRM_FORMAT_XRGB8888 and DRM_FORMAT_ARGB8888.
A modifier is an encoding of vendor-specific buffer layout parameters. Weston supports modifiers are supported by DRM (read the IN_FORMATS plane property blob) and by EGL (call eglQueryDmaBufModifiersEXT() ).

Buffer Write/read from CPU

You can use this API function to write data directly into a GBM buffer:
gbm_bo_write(bo, user_buffer, sizeof user_buffer);
You also can memory map a GBM buffer and get a CPU-accessible address to the data written to or read from it. The following code snippet shows how:
uint32_t dst_stride = 0;
void *gbo_mapping = NULL;
// Map bo to CPU accessible address.
char *dst_ptr = gbm_bo_map(bo,
0, 0,
width,
height,
GBM_BO_TRANSFER_READ_WRITE,
&dst_stride,
&gbo_mapping);
 
// Write data to or read data from dst_ptr.
. . .
 
// Unmap bo.
gbm_bo_unmap(bo, gbo_mapping);

Wayland Protocol to Post dma-buf Buffers to Weston

Weston uses the Generic Buffer Management (GBM) library to allocate buffers, which are backed by dma-buf file descriptors. Client applications must call the following GBM functions to get the dma-buf file descriptor and associated parameters from the GBM buffer object. To post the dma-buf to a Wayland surface, the file descriptor and parameters must be provided via Linux DMA-BUF Unstable V1 Protocol.
The following code snippet shows the main calls involved.
stride = gbm_bo_get_stride_for_plane(bo, 0);
offset = gbm_bo_get_offset(bo, 0);
handle = gbm_bo_get_handle_for_plane(bo, 0);
modifier = gbm_bo_get_modifier(bo);
drmPrimeHandleToFD(drm_fd, handle, 0, &dmabuf_fd);
 
zwp_linux_buffer_params_v1_add(params, dmabuf_fds, 0, offset,
stride, modifier >> 32,
modifier & 0xffffffff);
zwp_linux_buffer_params_v1_create(params, width, height,
format, flags);

GL Renderer in Weston

The GL renderer in Weston creates an eglImage from a dma-buf object that it receives with Linux DMA-BUF Unstable V1 Protocol using the EGL_EXT_image_dma_buf_import and EGL_EXT_image_dma_buf_import_modifiers extensions. Weston obtains the GL texture target to be used with this eglImage by calling eglQueryDmaBufModifiersEXT(), and binds the eglImage to the texture.

Display Hardware Compositing in Weston

The DRM compositor in Weston calls drmModeAddFB2WithModifiers() to associate a DRM framebuffer ID with the dma-buf it receives via Linux DMA-BUF Unstable V1 Protocol. It then uses the framebuffer ID to present the dma-buf to one of the available display hardware planes using drmModeSetPlane(), in the legacy path, or drmModeAtomicCommit(), in the atomic modeset path. This takes the form of a flip, where the reference to the new buffer is swapped in during vblank.

Constraints on the VIC Renderer

Weston dma-buf support is subject to these constraints:
libgbm.so from the Mesa package is not supported. Instead; libnvgbm.so provides a partial GBM API that supports Weston's DRM compositor and is compatible with NVIDIA drivers.
libnvgbm.so is still considered experimental. Install the following soft-link to enable GBM support with Weston:
$ sudo ln -sf /usr/lib/aarch64-linux-gnu/tegra/libnvgbm.so \
/usr/lib/aarch64-linux-gnu/libgbm.so.1
libnvgbm.so does not support multi-planar dma-buf formats. DRM and EGL support for them has not been verified using Weston.
For multi-planar dma-buf formats, all planes must be from a single memory allocation. The offsets specified in EGL_EXT_image_dma_buf_import attributes must be defined relative to the start of the allocation.
All planes for multi-planar dma-buf formats must have same memory layout.
nvbuf_utils is another dma-buf allocator available in L4T. Interoperability between nvbuf_utils and dma-buf has not been tested.

weston-debug

The client application weston-debug receives and prints debug messages using the weston-debug protocol. For example, when Weston is recompositing it prints all surface views and descriptions of the decision process regarding their assignment to overlays and GL compositing.
For weston-debug to work, you must run Weston with the ‑‑debug switch. Do not use this switch in production.
You can pass weston-debug additional parameters to choose categories of debug output to display:1
$ sudo XDG_RUNTIME_DIR=/tmp/xdg weston –debug
$ sudo XDG_RUNTIME_DIR=/tmp/xdg ./weston-debug -a
Alternatively, you can enable Weston debug output by setting the environment variable WAYLAND_DEBUG=server, and Weston client debug by setting WAYLAND_DEBUG=1.