# Wayland Linux BSP

# Wayland Linux BSP: Prerequisites

#### **Hardware: Raspberry Pi 5 Board** 

CGI Studio has been tested on the <span style="background-color: rgb(0, 0, 0);">**<span style="background-color: rgb(255, 255, 255);">Raspberry Pi 5</span>**<span style="background-color: rgb(255, 255, 255);"> </span></span><span style="background-color: rgb(255, 255, 255);">B</span>oard.

##### <a class="anchor" id="bkmrk--0"></a>CMake

In order to build Candera, the Meta build system CMake needs to be installed with at least version mentioned <span style="color: rgb(230, 126, 35);">[here.](https://doc316en.candera.eu/books/build-system-setup/page/prerequisites)</span>   
CMake is able to create the cross compilation make files that can be used with GCC (cross-compile) compiler.

##### <a class="anchor" id="bkmrk--1"></a>Linux Toolchain (BSP)

<div class="contents" id="bkmrk-linux-version-5.4.3-"><div class="contents"><div class="textblock">- SD card image was prepared with <span style="color: rgb(230, 126, 35);">[Raspberry Pi Imager](https://www.raspberrypi.com/software/)</span>.
- Raspberry Pi OS based on Debian Trixie was tested with a Debian Trixie build machine. 
    - Install crossbuild-essential-arm64   
        ```
        su
        apt-get -y update && \
        apt-get -y install crossbuild-essential-arm64
        
        
        
        ```
    - Make the SD card accessible in your build machine.  
        Copy the /usr/lib and /usr/Include folders from the SD card to your build machine. This can also be done with e.g. scp. ```
        #find the mount point of the SD card created with Raspberry Pi Imager
        su
        mkdir /opt/raspberry
        mkdir /opt/raspberry/sysroot64
        mkdir /opt/raspberry/sysroot64/usr
        cd /opt/raspberry/sysroot64/usr
        
        cp -ar <mount point of the sd card>/usr/lib  <mount point of the sd card>/usr/include .
        
        
        
        ```

</div></div><div class="contents"><div class="textblock"><dl class="note"><dd><p class="callout info">SD Card image, SDK and cross-compiler/s are not part of the delivery and have to be provided by the customer.</p>

</dd></dl></div></div></div>#### **Hardware: NXP i.MX8QMMEK Board** 

CGI Studio has been tested on **NXP i.MX8QMMEK** board.

##### <a class="anchor" id="bkmrk-"></a>CMake

In order to build Candera, the Meta build system CMake needs to be installed with at least version mentioned <span style="color: rgb(230, 126, 35);">[here.](https://doc316en.candera.eu/books/build-system-setup/page/prerequisites)</span>   
CMake is able to create the cross compilation make files that can be used with GCC (cross-compile) compiler.

##### <a class="anchor" id="bkmrk--2"></a>Linux Toolchain (BSP)

<div class="contents" id="bkmrk-linux-version-5.4.3--1"><div class="contents"><div class="textblock">- Linux version 5.4.3-lts-lf-5.4 (GCC version 9.2.0), Poky 5.4.3 (Zeus) was used to test this release with Weston 7.0.0 (Wayland 1.17.0).
- SD card image and SDK was prepared following the NXP’s Linux user guide.
- Graphic driver: Vivante (OpenGL ES 2.0)

</div></div><div class="contents"><div class="textblock"><dl class="note"><dd><p class="callout info">SD Card image, SDK and cross-compiler/s are not part of the delivery and have to be provided by the customer.</p>

</dd></dl></div></div></div>#### <a class="anchor" id="bkmrk--3"></a>Known Limitations

In case open source graphic driver is used (e.g. Etnaviv) following limitations could occur due to driver limitations:

<div class="contents" id="bkmrk-issue-with-shader%2Fs-"><div class="textblock">- issue with shader/s due to limited number of vectors
- MSAA was not supported

</div></div>####   
**Hardware: STM32MP157C-DK2 board** 

CGI Studio has been tested on STM32MP157C-DK2 board.

##### <a class="anchor" id="bkmrk--4"></a>CMake

In order to build Candera, the Meta build system CMake needs to be installed with at least version mentioned <span style="color: rgb(230, 126, 35);">[here.](https://doc316en.candera.eu/books/build-system-setup/page/prerequisites)</span>   
CMake is able to create the cross compilation make files that can be used with GCC (cross-compile) compiler.

##### <a class="anchor" id="bkmrk--5"></a>Linux Toolchain (BSP)

<div class="contents" id="bkmrk-linux-version-5.10.1"><div class="contents"><div class="textblock">- Linux version 5.10.10 (GCC version 9.3.0), ST OpenSTLinux - Weston - (A Yocto Project Based Distro) 3.1-openstlinux-5.10-dunfell-mp1-21-03-31 (dunfell) was used to test this release with Weston 8.0.0 (Wayland 1.18.0).
- SD card image and SDK was prepared following the STM’s Linux user guide.
- Graphic driver: Vivante (OpenGL ES 2.0)

</div><div class="textblock"><dl class="note"><dd><p class="callout info">SD Card image, SDK and cross-compiler/s are not part of the delivery and have to be provided by the customer.</p>

</dd></dl></div></div></div>##### <a class="anchor" id="bkmrk--6"></a>Known Limitations

In case open source graphic driver is used (e.g. Etnaviv) following limitations could occur due to driver limitations:

<div class="contents" id="bkmrk-issue-with-shader%2Fs--0"><div class="textblock">- issue with shader/s due to limited number of vectors
- MSAA was not supported

</div></div>#### **Hardware: NXP i.MX 8MN board** 

CGI Studio has been tested on NXP i.MX 8MN board.

##### <a class="anchor" id="bkmrk--7"></a>CMake

In order to build Candera, the Meta build system CMake needs to be installed with at least version mentioned <span style="color: rgb(230, 126, 35);">[here.](https://doc316en.candera.eu/books/build-system-setup/page/prerequisites)</span>   
CMake is able to create the cross compilation make files that can be used with GCC (cross-compile) compiler.

##### <a class="anchor" id="bkmrk--8"></a>Linux Toolchain (BSP)

<div class="contents" id="bkmrk-linux-version-5.4.70"><div class="contents"><div class="textblock">- Linux version 5.4.70 (GCC version 9.2.0), Poky 5.4 (Zeus) was used to test this release with Weston 9.0.0 (Wayland 1.18.0).
- SD card image and SDK was prepared following the boards user guide.
- Graphic driver: Etnaviv (OpenGL ES 3.0)

</div><div class="textblock"><dl class="note"><dd><p class="callout info">SD Card image, SDK and cross-compiler/s are not part of the delivery and have to be provided by the customer.</p>

</dd></dl></div></div></div>##### <a class="anchor" id="bkmrk--9"></a>Known Limitations

In case open source graphic driver is used (e.g. Etnaviv) following limitations could occur due to driver limitations:

<div class="contents" id="bkmrk-issue-with-shader%2Fs--1"><div class="textblock">- issue with shader/s due to limited number of vectors
- MSAA was not supported

</div></div>####   
**Hardware: NXP i.MX 8MM board** 

CGI Studio has been tested on NXP i.MX 8MM board.

##### <a class="anchor" id="bkmrk--10"></a>CMake

In order to build Candera, the Meta build system CMake needs to be installed with at least version mentioned <span style="color: rgb(230, 126, 35);">[here.](https://doc316en.candera.eu/books/build-system-setup/page/prerequisites)</span>   
CMake is able to create the cross compilation make files that can be used with GCC (cross-compile) compiler.

##### <a class="anchor" id="bkmrk--11"></a>Linux Toolchain (BSP)

<div class="contents" id="bkmrk-linux-version-5.4.70-0"><div class="contents"><div class="textblock">- Linux version 5.4.70 (GCC version 9.2.0), Poky 5.4 (Zeus) was used to test this release with Weston 9.0.0 (Wayland 1.18.0).
- SD card image and SDK was prepared following the boards user guide.
- Graphic driver: Etnaviv (OpenGL ES 2.0)

</div><div class="textblock"><dl class="note"><dd><p class="callout info">SD Card image, SDK and cross-compiler/s are not part of the delivery and have to be provided by the customer.</p>

</dd></dl></div></div></div>##### <a class="anchor" id="bkmrk--12"></a>Known Limitations

In case open source graphic driver is used (e.g. Etnaviv) following limitations could occur due to driver limitations:

<div class="contents" id="bkmrk-issue-with-shader%2Fs--2"><div class="textblock">- issue with shader/s due to limited number of vectors
- MSAA was not supported

</div></div>

# Running the CGI Player Demo Application on Linux with a Wayland Display Server

Copy the application and the asset to the target in /home/root folder. This can be done by copying the filed to the SD card containing the file system or via ssh (scp).

#### Logging Output and Key Input

Use TeraTerm or another terminal software to connect to the target via micro-USB (debugger) to receive logging output and use key input.   
BaudRate needs to be setup to 115200 8/n/1/n.

#### Loading and Running the Application

On target via TeraTerm, navigate (change directory) into the /home/root folder and run the applications with following command:

```
./<app-name> <asset-name>.bin



```

# Building Own Application for Linux with a Wayland Display Server

#### Generate Makefiles with CMake

For general information about CGI Studio Build System and CMake properties available to configure Candera applications refer to <span style="color: rgb(230, 126, 35);">[CGI Studio Build System](https://doc316en.candera.eu/books/build-system-setup/chapter/build-system-overview)</span>

To configure and generate makefiles for compiling the CGI Player, follow below steps:   
  
The first step for cross compiling is to make sure all the environment variables for the Yocto SDK are set!

<div class="contents" id="bkmrk-open-a-terminal.-set"><div class="contents"><div class="textblock">1. Open a terminal.
2. Set the environment. This step is mandatory. Omitting this step will cause building with the host systems compiler instead of cross compiling. ```
    $source /<path to the Yocto SDK installation>/environment-setup-<platform specific suffix e.g. aarch64-poky-linux> 
    
    
    
    ```
3. Important! From the same console with the set environment start the CMake GUI or run the CMake commandline. We will continue with the CMake GUI in this guide.
4. Point CMake to source directory 
    - Folder containing top-level "CMakeLists.txt", e.g. /cmake/Candera/Player <div class="image"><div drawio-diagram="2938"><img src="https://doc316en.candera.eu/uploads/images/drawio/2023-02/drawing-4-1677567539.png" alt=""/></div>
        
          
        </div>
5. Point CMake to binary directory 
    - May not exist, create folder with CMake if necessary
    - Root directory for generated makefiles / solutions
    - Root directory for build artifacts <div class="image"><div drawio-diagram="2939"><img src="https://doc316en.candera.eu/uploads/images/drawio/2023-02/drawing-4-1677567561.png" alt=""/></div>
        
          
        </div>
6. Configure 
    - Specify Unix Makefiles as generator for the project.
    - Specify tool-chain file for cross-compiling. <div class="image"><div drawio-diagram="2940"><img src="https://doc316en.candera.eu/uploads/images/drawio/2023-02/drawing-4-1677567581.png" alt=""/></div>
        
          
        </div>
7. Select the toolchain-file from the delivery (adapt for your toolchain installation and application specific needs)  
    ```
    /cgi_studio_devices/src/Wayland/ToolchainFiles/GCC-toolchain-Wayland-Linux.txt
    
    
    
    ```
    
    If Vulkan support is required, use the Vulkan-specific toolchain file.
    
    ```
    /cgi_studio_devices/src/Wayland/ToolchainFiles/GCC-toolchain-Wayland-Vulkan-Linux.txt
    
    
    
    ```
8. Adapt the CMake settings, if necessary, e.g.: 
    - CMAKE\_BUILD\_TYPE-&gt; Debug or Release.
    - Enable/disable features.
    - Press Configure.
9. Press Generate.

</div></div></div>#### Building Application

<div class="contents" id="bkmrk-make-sure-that-the-e"><div class="textblock"><dl class="note"><dd><p class="callout info">Make sure that the environment variables for the Yocto SDK are set in the terminal! Either reuse the terminal used to start CMake for building the Player or call the environment setup script again.</p>

</dd></dl></div></div>```
$source /<path to the Yocto SDK installation>/environment-setup-<platform specific suffix e.g. aarch64-poky-linux> 



```

<div class="contents" id="bkmrk-open-cmake-gui-and-c"><div class="textblock">1. Open CMake GUI and configure the project (e.g Player, CourierSampleApp, CitDemoApp) according to Generate Makefiles with CMake.
2. After generating your cmake files, navigate to the specified build directory (binary directory created in CMake GUI) and type "make" to start the build or “make -j” to build with multithreading.   
    With some hypervisors, the Linux VM may get unresponsive when using the –j option. Reducing the number of used threads to the number of available cores improves the responsiveness of the VM during the build.

</div></div><div class="contents" id="bkmrk-for-couriersampleapp"><div class="textblock"><dl class="note"><dd><p class="callout info">For CourierSampleApp and CitDemoApp asset file must be created with a matching SCHost.dll as the SCHost.dll for the CourierSampleApp and CitDemoApp contain specialized Widgets.</p>

</dd></dl></div><div class="textblock"><dl class="note"><dd>#### Vulkan Packaging Workflow

After a successful Vulkan build:

</dd></dl></div></div>1. Build and copy ANGLE Vulkan Libraries:  
    Build your own ANGLE Vulkan libraries for your target platform:  
    \- libEGL.so   
    \- libGLESv2.so   
      
    These libraries must match your target architecture.
    
    Copy into the same directory where the Player executable is located (the build output directory).
2. Run Packaging Script  
    From the build directory, execute the `package_player.sh` script. After execution, a folder named **vulkan** will be created.   
    Inside this folder you will find **Player.run** this is the only required output package.
3. Run the packaged Player using `./Player.run Your_Asset.bin`

<div class="contents" id="bkmrk-"><div class="textblock"><dl class="note"></dl>  
</div></div>