View source for Yocto Debian Build Release

<!-- Set release according to "release" parameter in URL and use mx93-debian-bookworm-6.1.36_2.1.0-v1.0 as default
--> {{INIT_RELEASE_PARAM|mx93-debian-bookworm-6.1.36_2.1.0-v1.0}}<!--
--> {{#lst:Debian_Platform_Customization|{{#var:RELEASE_PARAM}}}} <!--
--> {{PageHeader|{{#var:HARDWARE_NAME}} - Debian {{#var:DEBIAN_NAME}} {{#var:DEBIAN_VERSION}} based on Yocto {{#var:YOCTO_NAME}} {{#var:YOCTO_VERSION}} with {{#varexists:FSLC_BSP_VERSION|FSL Community BSP {{#var:FSLC_BSP_VERSION}}|NXP BSP {{#var:FSL_BSP_VERSION}}}} {{DocImage|category1=Debian|category2={{#var:HARDWARE_NAME}}}} }}__toc__

<!-- Set local variables
Include common yocto variables
--> {{COMMON_YOCTO_VARS}} 

{{Note|'''Note'''<br>
Since Debian Bookworm with NXP BSP L6.1.36_2.1.0, the build system has transitioned to Yocto. If you previously used an older Debian release, please note that setting up a new development environment may be necessary. Therefore, it is recommended to familiarize yourself with the following guides first:
* [[Yocto_Development_Environment|Setting a Development Environment]]
* [[Yocto Common Errors|Yocto common build errors]]
|info}}

<!-- Section: Installing required packages --> 
{{YOCTO_INSTALL_REQUIRED_PACKAGES}}

= Reference documentation =
  {{#lst:Yocto_Platform_Customization|YOCTO_DOC_{{#var:YOCTO_VERSION}}}} <!--
-->{{#if:{{#var:FSLC_BSP_VERSION}}|{{#lst:Yocto_Platform_Customization|YOCTO_DOC_FSLC_BSP_{{#var:FSLC_BSP_VERSION}}}}|}} <!--
-->{{#lst:Yocto_Platform_Customization|YOCTO_DOC_FSL_BSP_{{#var:FSL_BSP_VERSION}}}}

= Setting Up Yocto Build Environment =
{{GIT_INITIAL_SETUP}}

{{REPO_INITIAL_SETUP}}

Create a build directory:
 $ mkdir {{#var:BUILD_FOLDER}}
 $ cd {{#var:BUILD_FOLDER}}

Now, choose between downloading a release tag, and downloading the latest revision (recommended) and '''follow only one of the next two bullet sections''', accordingly:<br>
<br>
* '''Download the latest revision (recommended)'''<br>
 {{#varexists: YOCTO_MANIFEST |
 $ repo init -u {{#var:YOCTO_GIT}} -b {{#var:YOCTO_BRANCH}} -m {{#var:YOCTO_MANIFEST}}
 $ repo sync -j$(nproc)
|
 $ repo init -u {{#var:YOCTO_GIT}} -b {{#var:YOCTO_BRANCH}}
 $ repo sync -j$(nproc)
 }}
<br>
or<br>
<br>
* '''Download a release tag'''<br>
Each release in https://github.com/varigit/variscite-bsp-platform/releases corresponds to a tag.<br>
The tags are also listed in https://github.com/varigit/variscite-bsp-platform/tags<br>
To specify a specific release/tag, run the following:
 $ repo init -u https://github.com/varigit/variscite-bsp-platform.git -b refs/tags/TAG_NAME
 
 For example:
 {{#varexists: YOCTO_MANIFEST |
 $ repo init -u https://github.com/varigit/variscite-bsp-platform.git -b refs/tags/{{#var:RELEASE_NAME}} -m {{#var:YOCTO_MANIFEST}}
 $ repo sync -j$(nproc)
|
 $ repo init -u https://github.com/varigit/variscite-bsp-platform.git -b refs/tags/{{#var:RELEASE_NAME}}
 $ repo sync -j$(nproc)
}}

= Building the Image =

== Supported images ==
Variscite provides the following images for evaluation purposes:
* '''var-image-debian''': Default Variscite demo image for Debian build with Yocto. This image recipe works currently only with Xwayland

== Supported distros ==
The following distros can be used:
* '''var-debian-xwayland''': Distro for Wayland with X11. This distro includes both Wayland and X11 emulation features.

== Build Debian Xwayland GUI demo image ==
After the Yocto environment is set up, you need to configure the build environment for your target device: <!-- TODO: Use template YOCTO_ENV_SETUP_X and YOCTO_ENV_SETUP_X_SHORT -->
 $ cd {{#var:BUILD_FOLDER}}
 $ MACHINE={{#var:MACHINE_NAME}} DISTRO=var-debian-xwayland . var-setup-debian.sh build_debian_xwayland

The above command is only mandatory for the very first build setup. Whenever restarting a newer build session (from a different terminal or in a different time), you can skip the full setup and just run:
 $ cd {{#var:BUILD_FOLDER}}
 $ source setup-environment build_debian_xwayland

Then, the image can be created by running the following bitbake command:

 $ bitbake var-image-debian

The target rootfs image is located at:

{{#var:BUILD_FOLDER}}/build_debian_xwayland/tmp/deploy/images/{{#var:MACHINE_NAME}}/var-image-debian-{{#var:MACHINE_NAME}}.wic.gz

{{#varexists:DEBIAN_BUILD_RESULTS_SECTION |
== Build Results ==
The resulting images are located in {{#var:BUILD_FOLDER}}/build_debian_xwayland/tmp/deploy/images/{{#var:MACHINE_NAME}}.

{{#lst:Debian_Platform_Customization|{{#var:DEBIAN_BUILD_RESULTS_SECTION}}}}
|}}

= Linux console access =
== Default users and passwords ==
{| class="wikitable"
|-
! scope="col" | User name
! scope="col" | User password
! scope="col" | User descriptor
|-
| root
| root
| system administrator
|-
| user
| user
| local user
|-
|}

You can customize the users during runtime with the common known methods in Debian. Please follow up with the next section if you'd like to customize them during the build.

== Customize users during the build ==
The Variscite Debian image is pre-configured to include the user's 'user' and 'root'. While the user 'root' is mandatory, the user 'user' is optional and can be configured or dropped according to your needs (it's also possible to add additional users).

The related statements in the Yocto tree are in 'dynamic-layers/var-debian/recipes-var/images/var-image-common.inc' within the meta layer [https://github.com/varigit/meta-variscite-sdk-imx meta-variscite-sdk-imx].

'''var-image-common.inc'''
 ...
 # Default password: root
 USER_PASSWD_ROOT ?= "POYe5TylsuKjU"

 # Add user with password user and default shell bash
 USER_SHELL_BASH ?= "/bin/bash"
 # Default password: user
 USER_PASSWD_USER ?= "zHipsIr46vtZk"
 APTGET_ADD_USERS ?= "user:${USER_PASSWD_USER}:${USER_SHELL_BASH}"
 ...

This makes use of the API APTGET_ADD_USERS variable of the bitbake class nativeaptinstall.bbclass (can be found in 'classes/nativeaptinstall.bbclass' in the meta layer [https://github.com/varigit/meta-variscite-debian meta-variscite-debian]).

The syntax of the variable APTGET_ADD_USERS is <code><name:pass:shell></code>, with the following meaning:<br>
* name: The user name
* pass: An encrypted password (if empty or missing, an empty password will be assigned)
* shell: The default shell (if empty, default is /bin/sh)

For multiple definitions, a space can be used as a separator.

The encrypted password (DES hash) can be created using the tool 'mkpasswd', provided by the package 'whois'.

For instance:
 $ sudo apt-get update; sudo apt-get install -y whois
 $ mkpasswd --method=DES user
 $ lAeYt2gLbjniw

This will generate a hash with a random salt. To double-check, we can pass the salt (the first 2 characters of the output), like:
 $ mkpasswd --method=DES --salt lA user
 $ lAeYt2gLbjniw

One can either change the variables in 'var-image-common.inc' directly or overwrite the default values, e.g., in the local.conf ('{{#var:BUILD_FOLDER}}/build_debian_xwayland/conf/local.conf').

For instance, to configure 2 users, 'user' and 'user2', with the password being the same as the user name:<br>
'''local.conf'''
 ...
 APTGET_ADD_USERS = " \
     user:lAeYt2gLbjniw:/bin/bash \
     user2:FuOvd4U8o1Y4.:/bin/bash \
 "
 ...

Or to add an additional user to the one already present:<br>
 ...
 APTGET_ADD_USERS += " \
     user2:FuOvd4U8o1Y4.:/bin/bash \
 "
 ...

Or drop all additional users (only user 'root'):<br>
 ...
 APTGET_ADD_USERS = ""
 ...

{{note|'''Note:''' If you only want to change the password of the default user 'user', overwrite the variable USER_PASSWD_USER to your needs. The same applies to the user 'root' with the associated variable USER_PASSWD_ROOT.|info}}

<!-- Create a Bootable SD card -->
{{Yocto_Create_Bootable_SD}}

= Boot the board with a bootable SD card =
{{#ifeq: {{#var:HARDWARE_NAME}} | DART-6UL |
Note: <span style="color:red">The WiFi is not operational when booting from SD card</span>, as the WiFi and SD card are using the same SDIO interface.<br>
A typical use-case is to boot from an SD card, flash the eMMC/NAND flash, and re-boot from the eMMC/NAND flash to have the WiFi operational.
|}}
{{#ifeq: {{#var:HARDWARE_NAME}} | DART-MX8M |
Note: <span style="color:red">The WiFi is not operational when booting from SD card</span>, as the WiFi and SD card are using the same SDIO interface.<br>
A typical use-case is to boot from an SD card, flash the eMMC, and re-boot from the eMMC to have the WiFi operational.
|}}
== Setting the Boot Mode ==
{{#lst:Yocto_Platform_Customization|{{#var:YOCTO_BOOT_BOARD_SECTION}}}}

{{#ifeq: {{#var:HARDWARE_NAME}} | VAR-SOM-MX8X|
|
== Automatic device tree selection in U-Boot ==
As shown in the [[#Build_Results| Build Results]] table above, we have different kernel device trees, corresponding to our different H/W configurations.<br>
{{#ifeq: {{#var:HARDWARE_NAME}} | DART-MX8M |
We implemented a script in U-Boot's environment, which sets the fdt_file environment variable based on the detected version of the carrier board revision.<br>
This file is actually a symbolic link, pointing to the real dtb file. The symbolic link can be set manually and defaults to the LVDS display configuration<br>
(when using the install_yocto.sh script with a display parameter, this script automatically sets this symbolic link to the appropriate dtb file).<br>
|
We implemented a script in U-Boot's environment, which sets the fdt_file environment variable based on the detected hardware.
}}
=== Enable/Disable automatic device tree selection ===
To enable the automatic device tree selection in U-Boot (already enabled by default):
<pre>
$ setenv fdt_file undefined
$ saveenv
</pre>
To disable the automatic device tree selection in U-Boot, set the device tree file manually:
<pre>
$ setenv fdt_file YOUR_DTB_FILE
$ saveenv
</pre>

{{#switch: {{#var:SOC_SERIES}} | imx8 | imx9=
Useful example: To list all files in the /boot directory (where the dtb files are by default) of an SD card:
 $ ls mmc {{#var:U-BOOT_SD_DEV}}:1 /boot
|
Useful example: To list all files in the boot partition (where the dtb files are by default) of an SD card:
<pre>
$ ls mmc 0:1
</pre>
}}
<!-- Make NOTE for DART-6UL only -->
{{#ifeq: {{#var:HARDWARE_NAME}} | DART-6UL |
{{note|Comment:<br>Make sure you don't set an inappropriate dtb file, like a dtb with nand on a SOM that has eMMC, or a dtb for mx6ull on a SOM with an mx6ul SOC.|info}}
|}}
}}
= Flash images to NAND/eMMC =
Please refer to {{Varlink|Yocto NAND Flash Burning|{{#var:RELEASE_LINK}}|Debian NAND Flash Burning}} guide.