Skip to main content
Version: Torizon OS 7.x.y

Customizing Kernel Arguments in Torizon

Introduction​

The Linux Kernel of Torizon OS accepts certain boot-time arguments (parameters) that configure aspects of the kernel itself or its modules. This article briefly describes the method provided by the TorizonCore Builder tool (which is part of the Torizon Cloud) to perform such configuration.

To learn which Linux Kernel version corresponds to the latest Torizon OS versions, check the Embedded Linux Release Matrix.

To find out more about Linux Kernel Arguments, see The kernel’s command-line parameters.

This article complies with the Typographic Conventions for Torizon Documentation.

Pre-requisites​

The pre-requisite to complete these instructions are:

To install TorizonCore Builder, read our statements on OS and shell compatibility, then follow the instructions below, in order.

  1. Download the setup script into some writable directory in your system (here we use ~/tcbdir/):

    $ mkdir -p ~/tcbdir/ && cd ~/tcbdir/
    $ wget https://raw.githubusercontent.com/toradex/tcb-env-setup/master/tcb-env-setup.sh
    note

    If you did this before then you can skip this step unless you want to update the setup script. When you source the script (next step) it will show you a warning message if it determines an update is advisable.

  2. Source the script:

    $ cd ~/tcbdir/
    $ source tcb-env-setup.sh

    Make sure to do this from every shell instance that you intend to use with TorizonCore Builder. For advanced usage, run source tcb-env-setup.sh -h, or see the project README. The latter has information about using the early-access version of the tool for those interested.

    tip
    • Remember to source the setup script every time you start a new terminal (or shell instance).
    • The setup script installs a Bash completion script for TorizonCore Builder, making it possible to autocomplete commands and parameters by just pressing the TAB key.

    Beware that under Windows, you must pass extra parameters to the script when the use of the following commands is intended:

  3. Verify that the command torizoncore-builder is available:

    $ torizoncore-builder --help

Applying Kernel Arguments to a Custom Image​

There are two possible approaches to apply the customization and generate a custom Toradex Easy Installer image, described in the next two sections Approach 1 and Approach 2. These approaches in some cases are interchangeable and in some not as described in the next sections.

To learn about TorizonCore Builder workflow and the different approaches to use the tool, with explanatory diagrams, please refer to the TorizonCore Builder - Workflow article.

danger

Both approaches generate a custom Toradex Easy Installer image as output, so the approaches should be followed alternatively and not in sequence.

Approach 1: Applying Custom Kernel Arguments to a Custom Image Using the Build Command​

TorizonCore Builder build command generates a custom Torizon OS image with the custom kernel arguments applied, ready to be installed with Toradex Easy Installer, named torizon-core-docker-colibri-imx6-Tezi_5.3.0.CUSTOM in the example below. This is achieved using a configuration YAML file, tcbuild.yaml as default.

This is the recommended approach on production programming and on CI/CD (continuous integration / continuous development) pipelines.

To learn about TorizonCore Builder workflow and the different approaches to use the tool, with explanatory diagrams, please refer to the TorizonCore Builder - Workflow article.

It requires a Toradex Easy Installer image of Torizon OS (preferably without containers), torizon-core-docker-colibri-imx6-Tezi_5.3.0+build.7.tar in this case, as input. The directory with the kernel arguments are passed as customization: kernel: arguments.

tcbuild.yaml
# Sample configuration file:
input:
  easy-installer:
    local: images/torizon-core-docker-colibri-imx6-Tezi_5.3.0+build.7.tar
# Sample customization: include or change (if already exists) key1 and key2 kernel arguments
customization:
  kernel:
    arguments:
      - key1=val1
      - key2=val2
output:
  easy-installer:
    local: torizon-core-docker-colibri-imx6-Tezi_5.3.0.CUSTOM

Build the Custom Image​

To generate the Torizon OS image, run the command below, in the same directory where the tcbuild.yaml file is:

$ torizoncore-builder build

...
1091 metadata, 12741 content objects imported; 412.2 MB content written                                                                                                                                   
Pulling done.
Deploying OSTree with checksum 58629613a342197c31c5911d0874aac1b0fcb46b68a63f59760c03bacc4df08a
Deploying done.
Copy files not under OSTree control from original deployment.
Packing rootfs...
Packing rootfs done.

=>> Build command successfully executed!

In case of using a configuration file with a different name than tcbuild.yaml, run the command specifying the configuration file name:

$ torizoncore-builder build --file <configuration_file_name>

Deploy the Custom Toradex Easy Installer Image​

To deploy the custom Toradex Easy Installer image to the board, click on the link below and choose between the available options.

Deploy The Custom Toradex Easy Installer Image

The output image can be deployed in three ways to the board:

  • Using Toradex Easy Installer, the recommended method for production programming.
  • Directly on the board through SSH, the recommended method during development.
  • Through Torizon Cloud server, the recommended method to perform updates on a device already deployed to the field.
info

Despite the recommendations, it is also possible to use a different method, using the Torizon Cloud method during development for example.

To learn more about when to use each method, please refer to the Deployment Methods Comparison section of the TorizonCore Builder - Workflow article.

Toradex Easy Installer​

Toradex Easy Installer Tool allows users to install an image into the internal flash memory of Toradex modules in an extremely simple way.

Copy the output image into a USB stick and follow the steps in the Toradex Easy Installer article linked above. The copy of the output image can be done with the command below:

$ cp -a torizon-core-docker-colibri-imx6-Tezi_5.3.0.CUSTOM /media/user/myUSBstick

Where, in my case, /media/user/myUSBstick is the path to USB stick mount point and torizon-core-docker-colibri-imx6-Tezi_5.3.0.CUSTOM is the directory containing the custom Toradex Easy Installer image.

Directly, through SSH​

In this case, before deployment the output image needs to be unpacked, using the command below:

$ torizoncore-builder images unpack torizon-core-docker-colibri-imx6-Tezi_5.3.0.CUSTOM

Change the argument torizon-core-docker-colibri-imx6-Tezi_5.3.0.CUSTOM to the directory containing your custom Toradex Easy Installer image.

For more details on how this command works, please check the images unpack command in the commands manual.

To deploy it directly to the board, through SSH, use the command below:

$ torizoncore-builder deploy --remote-host 192.168.1.117 --remote-username torizon --remote-password torizon --reboot

For more details on how this command works, please check the deploy command in the commands manual.

Change the arguments --remote-host,--remote-username and --remote-password to your board IP Address, username and password, respectively.

tip

From TorizonCore Builder 3.1.0 after, the default value of --remote-username and --remote-password is torizon, so if the username or the password is torizon the argument can be omitted.

caution

This way does not support the deployment of the pre-provisioned containers.

Torizon Cloud​

In this case, before deployment the output image needs to be unpacked, using the command below:

$ torizoncore-builder images unpack torizon-core-docker-colibri-imx6-Tezi_5.3.0.CUSTOM

Change the argument torizon-core-docker-colibri-imx6-Tezi_5.3.0.CUSTOM to the directory containing your custom Toradex Easy Installer image.

For more details on how this command works, please check the images unpack command in the commands manual.

To deploy it to the Torizon Cloud Update Service, use the command below:

$ torizoncore-builder platform push --credentials credentials.zip --package-name base-package --package-version base-package-1.0 base

For more details on how this command works, please check the platform push command documentation in the Commands Manual.

caution

This way does not support the deployment of the pre-provisioned containers, so their Docker Compose file will need to be deployed separately in the server.

To deploy the image from the Torizon Cloud Remote Update Service to the board, please follow the steps in the OTA Web Interface article.

To obtain credentials (credentials.zip file) and to obtain more information on how to sign and securely deploy a custom image using Torizon Cloud Updates, check the Signing and pushing the image to Torizon Cloud article.

Approach 2: Applying Custom Kernel Arguments to a Custom Image: Using Standalone Commands​

In this second approach, instead of using a configuration YAML file and a one-step command, the generation of the custom Torizon OS with the custom kernel arguments is done using standalone commands, each performing one step towards this generation.

This approach is especially useful when making incremental changes, generating multiple images with different custom kernel arguments (or other customizations like different device tree overlays). As you will see, applying custom kernel arguments on an image of Torizon OS that has other customizations is just a matter of performing the apply, merge and deploy stages.

To learn about TorizonCore Builder workflow and the different approaches to use the tool, with explanatory diagrams, please refer to the TorizonCore Builder - Workflow article.

To generate a custom Toradex Easy Installer image with the desired custom kernel arguments follow the sequence of steps below.

Unpack an Input Image​

You just need to execute this once. Then, you are ready to apply multiple changes to the image. For example, in addition to applying custom kernel arguments, you can also apply a custom splash screen, a new device tree, among other possibilities.

If you have not unpacked an image yet, download a base Torizon OS image (preferably without containers) inside the TorizonCore Builder working directory, then run the command below to unpack it. In the example below the torizon-core-docker-colibri-imx6-Tezi_5.3.0+build.7.tar image is used as a reference:

$ torizoncore-builder images unpack torizon-core-docker-colibri-imx6-Tezi_5.3.0+build.7.tar

If you want to change the Torizon OS base image, download the new image and run the images unpack command again, passing the new image as the argument.

For more details about the images unpack command, please check the images unpack command in the commands manual.

Instead of using the images unpack you can use the images download command. This command checks which is the connected Toradex SoM, downloads the compatible latest quarterly release of a Torizon OS image without containers, and unpacks this image.

$ torizoncore-builder images download --remote-host 192.168.1.117 --remote-username torizon --remote-password torizon

Change the arguments --remote-host,--remote-username and --remote-password to your board IP Address, username and password, respectively.

For more details on how the images download command works, please check the images download command in the commands manual.

Set a Custom Kernel Argument​

For setting the custom kernel arguments, one would simply run:

$ torizoncore-builder kernel set_custom_args "key1=val1" "key2=val2"
'custom-kargs_overlay.dts' compiles successfully.
Overlay custom-kargs_overlay.dtbo successfully applied.
Kernel custom arguments successfully configured with "key1=val1 key2=val2".
caution

Every time you execute the kernel set_custom_args command the custom-kargs_overlay.dts is overwritten, so you should pass all the kernel arguments in a single set_custom_args command.

For more details about the kernel set_custom_args command, please check the kernel set_custom_args command in the commands manual.

As shown in the above message, a device tree overlay will be applied to the image to set the custom arguments. This fact can be verified by using the dto status command, which will display the custom-kargs_overlay.dtbo amongst any other applied overlays, like so:

$ torizoncore-builder dto status
Enabled overlays over device tree imx6dl-colibri-eval-v3.dtb:
- colibri-imx6_parallel-rgb_overlay.dtbo
- colibri-imx6_stmpe-ts_overlay.dtbo
- display-vga_overlay.dtbo
- custom-kargs_overlay.dtbo
caution

Since the arguments are kept in a device-tree overlay, the user should be careful not to remove that overlay (especially by using dto remove --all) or the arguments will not be present on the deployed image.

For more details about the dto status command, please check the dto status command in the commands manual.

Check the Current Set of Custom Kernel Arguments​

To determine what the current custom kernel arguments are (that is, what configuration would take effect upon the execution of a union command) use:

$ torizoncore-builder kernel get_custom_args
Currently configured custom kernel arguments: "key1=val1" "key2=val2".

For more details about the kernel get_custom_args command, please check the kernel get_custom_args command in the commands manual.

Finally, it is also possible to clear any applied custom kernel arguments by doing:

$ torizoncore-builder kernel clear_custom_args
Custom kernel arguments successfully cleared.

This will remove the corresponding device-tree overlay (custom-kargs_overlay.dtbo) as done by dto remove.

For more details about the kernel clear_custom_args command, please check the kernel clear_custom_args command in the commands manual.

Merge Changes​

Merge the kernel arguments (as well as other customizations like a splash screen or a new device tree) into the base Toradex Easy Installer image of Torizon - use whatever branch name you want.

As an example, to commit changes into a branch named custom-branch use the command below, accordingly with the TorizonCore Builder version:

$ torizoncore-builder union custom-branch

Applying changes from STORAGE/dt.
Commit 58629613a342197c31c5911d0874aac1b0fcb46b68a63f59760c03bacc4df08a has been generated for changes and is ready to be deployed.
caution

We recommend that you switch to the latest version of TorizonCore Builder to enjoy its simpler and more consistent user interface besides other improvements and bug fixes.

For more details about the union command, please check the union command in the commands manual.

Deploy the Custom Toradex Easy Installer Image​

To deploy the custom Toradex Easy Installer image to the board, click on the link below and choose between the available options.

Deploy The Custom Toradex Easy Installer Image

The output image can be deployed in three ways to the board:

  • Using Toradex Easy Installer, the recommended method for production programming.
  • Directly on the board through SSH, the recommended method during development.
  • Through Torizon Cloud server, the recommended method to perform updates on a device already deployed to the field.
info

Despite the recommendations, it is also possible to use a different method, using the Torizon Cloud method during development for example.

To learn more about when to use each method, please refer to the Deployment Methods Comparison section of the TorizonCore Builder - Workflow article.

However, the commands have differences in comparison to the deploy in Approach 1.

Toradex Easy Installer​

Toradex Easy Installer Tool allows users to install an image into the internal flash memory of Toradex modules in an extremely simple way.

First, to generate a Toradex Easy Installer image, into the output directory torizon-core-docker-colibri-imx6-Tezi_5.3.0.CUSTOM, use the command below:

$ torizoncore-builder deploy custom-branch --output-directory torizon-core-docker-colibri-imx6-Tezi_5.3.0.CUSTOM

Change the arguments custom-branch to the branch where you merged the changes (with the union command).

Copy the output image into a USB stick and follow the steps in the Toradex Easy Installer Tool article linked above. The copy of the output image can be done with the command below:

$ cp -a torizon-core-docker-colibri-imx6-Tezi_5.3.0.CUSTOM /media/user/myUSBstick

Where /media/user/myUSBstick is, in my case, the path to USB stick mount point.

Directly, through SSH​

To deploy it directly to the board, through SSH, use the command below:

$ torizoncore-builder deploy custom-branch --remote-host 192.168.1.117 --remote-username torizon --remote-password torizon --reboot

Change the arguments custom-branch, --remote-host,--remote-username and --remote-password to the branch where you merged the changes (with the union command), your board IP Address, username and password, respectively.

tip

From TorizonCore Builder 3.1.0 after, the default value of --remote-username and --remote-password is torizon, so if the username or the password is torizon the argument can be omitted.

For more details on how this command works, please check the deploy command in the commands manual.

caution

This way does not support the deployment of the pre-provisioned containers.

Torizon Cloud Remote Update Service​

To deploy it to the Torizon Cloud Remote Update Service, use the command below:

$ torizoncore-builder push --credentials credentials.zip custom-branch

Change the argument custom-branch to the branch where you merged the changes (with the union command).

caution

This way does not support the deployment of the pre-provisioned containers, so their Docker Compose file will need to be deployed separately in the server.

To deploy the image from the Torizon Cloud Remote Update Service to the board, please follow the steps in the OTA Web Interface article.

To obtain credentials (credentials.zip file) and to obtain more information on how to sign and securely deploy a custom image using Over-the-Air (OTA) updates, check the Signing and pushing the image to Torizon Cloud article.

For more details on how this command works, please check the push command in the commands manual.

Deploying Through the Torizon Cloud​

The images with customized Kernel Arguments can be deployed using the Torizon Updates Features.

You can sign and push the custom OS image to the Torizon Cloud as an OS Package. After pushing the new custom OS image, your device can be updated with it.

This is only possible from Torizon OS 6 onward.

Verifying the New Custom Image on the Device​

After rebooting, in your target device's terminal, verify that your new custom image of Torizon OS is active on the device with the command below:

# sudo ostree admin status

Password: 
* torizon 58629613a342197c31c5911d0874aac1b0fcb46b68a63f59760c03bacc4df08a.0
    Version: 5.3.0+build.7-tcbuilder.20211008140217
    origin refspec: tcbuilder:58629613a342197c31c5911d0874aac1b0fcb46b68a63f59760c03bacc4df08a
  torizon 36ad904617b170339b6ded7b9dce87ed8cf0f76473b897fdd832d91e82eb1ddc.0 (rollback)
    Version: 5.3.0+build.7
    origin refspec: tcbuilder:36ad904617b170339b6ded7b9dce87ed8cf0f76473b897fdd832d91e82eb1ddc

Where 58629613a342197c31c5911d0874aac1b0fcb46b68a63f59760c03bacc4df08a is the OSTree commit hash and should be the same as:

  • The one in the output of the union command in the case of the standalone commands
  • The one in the "Deploying OSTree with checksum ..." part of the output of the build command.

Check the Custom Kernel Arguments​

After deploying the image, you should be able to see your custom kernel arguments in the kernel arguments list. To do it, you can use the command below:

# cat /proc/cmdline

enable_wait_mode=off galcore.contiguousSize=50331648 root=LABEL=otaroot rootfstype=ext4 quiet logo.nologo vt.global_cursor_default=0 plymouth.ignore-serial-consoles splash ostree=/ostree/boot.1/torizon/248c1906ffb097b9d5dd4d48f0a942a23cfd82378649edbc24ce5743291c53b0/0 key1=val1 key2=val2


Send Feedback!