Skip to content

# Booting an image on your hardware

## Boot chain overview

The Kontron yocto distribution for STM32MP boards implements the trusted bootchain which consists of

- trusted-firmware-a as first stage bootloader (fsbl)
- u-boot as second stage bootloader (ssbl)
- linux kernel

After powering up the device, the bootrom program located in SOC ROM searches for the boot device to use. The boot device is determined by boot strap pins BOOT0, BOOT1, BOOT2 and bits in OTP. This way it is possible to fetch the first stage boot loader from different storage media.

How to switch the boot source and what boot sources are available can be found in the Demo-Kit description. See there for more information what your board provides and how you can switch the boot source e.g. by dedicated boot switches on the board.

For the Kontron Demo-Kits the boot sources are SD-card and QSPI NOR. After fsbl and u-boot are loaded and started, u-boot loads the linux kernel and root filesystem from the media mentioned in `boot_targets` u-boot environment variable. See u-boot bootloader for more info.

For more information about the boot sequence see STM32MP trusted boot chain

Besides that, the Kontron BSP supports two different boot schemes

- extlinux boot scheme and
- AB boot scheme with SWUpdate.

They differ slightly how the boot procedure is executed and configured. Which boot scheme is used depends on the image you build for your board (see the available firmware images for further information)

### trusted-firmware loader (fsbl)

Upon supplying power to the hardware, the so called 'first stage bootloader' (fsbl) is loaded into internal SRAM and started from the STM32MP SOC.

The purpose of the fsbl is to do basic system initialisation tasks like DRAM and clock setup. Furthermore it assigns the peripherals to the secure and none secure area of the device. Secure parts can only used by fsbl. For all other software like u-boot and linux, secure periphals can't be used without notifying the secure software part, and requesting some action from the secure monitor.

    NOTICE:  CPU: STM32MP157AAD Rev.B
    NOTICE:  Model: stm32mp-t1000-k (tf-a)
    INFO:    Reset reason (0x4):
    INFO:      Pad Reset from NRST
    INFO:    Using NOR
    INFO:      Instance 1
    INFO:    Boot used partition fsbl1
    INFO:    NOR: Memory mapped mode
    INFO:    Product_below_2v5=1: HSLVEN update is
    INFO:      destructive, no update as VDD>2.7V
    NOTICE:  BL2: v2.0(debug):0.1.0.d-7-gd5e797c-dirty
    NOTICE:  BL2: Built : 15:39:08, Apr 12 2019
    INFO:    BL2: Doing platform setup
    INFO:    RAM: DDR3-DDR3L 16bits 528Mhz K4B4G1646E (v1,1066-7-7-7,cal)
    INFO:    Memory size = 0x20000000 (512 MB)
    INFO:    BL2 runs SP_MIN setup
    INFO:    BL2: Loading image id 4
    INFO:    Loading image id=4 at address 0x2fff0000
    INFO:    Image id=4 loaded: 0x2fff0000 - 0x30000000
    INFO:    BL2: Loading image id 5
    INFO:    Loading image id=5 at address 0xc0100000
    INFO:    STM32 Image size : 758445
    WARNING: Skip signature check (header option)
    INFO:    Image id=5 loaded: 0xc0100000 - 0xc01b92ad
    INFO:    read version 0 current version 0
    NOTICE:  BL2: Booting BL32
    INFO:    Entry point address = 0x2fff0000
    INFO:    SPSR = 0x1d3
    NOTICE:  SP_MIN: v2.0(debug):0.1.0.d-7-gd5e797c-dirty
    NOTICE:  SP_MIN: Built : 15:39:08, Apr 12 2019
    INFO:    ARM GICv2 driver initialized
    INFO:    stm32mp HSE (20): Secure only
    INFO:    stm32mp PLL2 (27): Secure only
    INFO:    stm32mp PLL2_R (30): Secure only
    INFO:    SP_MIN: Initializing runtime services
    INFO:    SP_MIN: Preparing exit to normal world

After fsbl has finished system setup, u-boot is started.

### u-boot bootloader (ssbl)

Upon supplying power to the hardware, the U-Boot bootloader stored in the NOR flash or SD card will be started (depending on the boot switch configuration).
The boot messages of the bootloader on the debug terminal will look something like this:

    U-Boot 2018.11-stm32mp-r2 (Apr 11 2019 - 18:56:44 +0000)

    CPU: STM32MP157AAD Rev.B
    Model: stm32mp-t1000-k (u-boot)
    Board: stm32mp1 in trusted mode (ex,stm32mp-t1000-k)
           Watchdog enabled
    DRAM:  512 MiB
    Clocks:
    - MPU : 648 MHz
    - MCU : 196 MHz
    - AXI : 264 MHz
    - PER : 24 MHz
    - DDR : 528 MHz
    NAND:  0 MiB
    MMC:   STM32 SDMMC2: 0, STM32 SDMMC2: 1
    Loading Environment from SPI Flash... SF: Detected mx25r1635f with page size 256 Bytes, erase size 64 KiB, total 2 MiB
    OK
    In:    serial
    Out:   serial
    Err:   serial
    Net:   Found Micrel KSZ8081 PHY, enable 50MHz RMII mode

    eth0: ethernet@5800a000
    Boot over nor0!
    Hit any key to stop autoboot:  2

After waiting some seconds, the bootloader tries to boot the linux kernel and mount the root filesystem. Which kernel, device-tree and linux kernel command line is used and where the root filesystem is located, is configured in the `extlinux.conf` file u-boot searches for in the boot partition (for extlinux boot scheme) or - if AB boot scheme is used, configured by u-boot environment variables.

This boot partition can be located on different storage media. For example 'mmc0' for SD-cards, 'mmc1' for eMMC and 'ubifs0' for QSPI NAND. But this depends on your board and what it provides. Besides this, 'pxe' is a special case for booting over network (see Boot from network for more info). Which boot medias are scanned for boot partitions is determined by the u-boot variable `boot_targets`, which contains a list of boot medias to be scanned. For example the Demo-Kits `boot_targets` variable is set to `mmc0 mmc1 ubifs0 pxe`. Please refer to the hardware documentation for information on what your board supports.

For extlinux boot scheme, u-boot searches the `extlinux.conf` file in a directory `${boot_device}${boot_instance}_${board_name}`. This results for example in the directory name `mmc0_stm32mp-t1000-k` for 'boot on SD-card' for the board 'stm32mp-t1000-k'. U-boot searches this directory with prefix '/' or '/boot/' on the boot partition.

For AB boot scheme the appropriate boot partition is selected by u-boot and the device tree file, and the linux kernel is loaded and started by u-boot.

To enter the bootloader command line hit a key before the bootloader starts booting. With this command line it it possible to change u-boot variables which influences the boot mode.

    STM32MP>

List of basic U-Boot commands:

Command | Description
--- | ---
printenv | print all variables and their values
printenv <variable> | print content of <variable>
setenv <variable> <value> | Set <variable> to <value>
setenv <variable> | Delete <variable>
editenv <variable> | Edit value of <variable>
saveenv | save all variables to flash
env default -a | restore default environment

Besides changing the boot variables u-boot provides commands for testing hardware, reading and writing storage media and much more. Use the u-boot command `help` to get a first impression what is possible.

The most important u-boot variables for booting are:

- boot_device
  Device string from where bootrom fetched tf-a and u-boot. For example `mmc` for SD-card and `nor` for QSPI NOR.
- boot_instance
  Instance of boot device, commonly '0'.
- boot_targets
  This is a list of boot devices which are scanned when u-boot searches the boot configuration. Available devices are `mmc0` for SD-card, `mmc1` for eMMC, `ubifs0` for QSPI NAND and `pxe` for network boot. Please have a look in the description for your Demo-Kit which boot devices are available for your board.
- board_name
  This variable is set from the device tree file for u-boot. It is extracted from the first compatible entry in the device tree file. This variable is used to build the search path of `extlinux.conf` on the boot partition or used to find the appropriate device tree file for the linux kernel.
- housing
  This variable is appended to the `board_name`. It can be changed by the user to enable some board variants. For example there is a board named 'stm32mp-t1000-k' which doesn't have a display. With the help of the `housing` variable some variants can be selected without the need to exchange u-boot and its device-tree configuration. For example setting the `housing` variable to '-50' selects the Demo-Kit variant with 5 inch display type ('stm32mp-t1000-k-50').
- fdtfile (AB boot scheme)
  This variable determines the linux kernel device tree file to be used for boot when AB boot scheme is used. The contents of this variable is calculated on each boot and made of `board_name` and `housing` variable contents and results in, e.g. `stm32mp-t1000-k-50.dtb`.
- bootargs_base (AB boot scheme)
  This variable contains the fixed linux kernel command line arguments. You can extend this variable to add your own specific boot arguments for the linux kernel.
- serverip
  Ip address of tftp server from where pxe tries to fetch the boot files.
- bootdelay
  Delay in seconds for which u-boot waits for user input to get into u-boot console. If set to zero you can't get into u-boot console while booting. If you want to have this possibility again, you have to modify the bootdelay variable in u-boot environment from a running linux.

Important

Setting `bootdelay` does not prevent starting u-boot console for all cases! If u-boot environment is not able to boot or detects a failure in boot processing it is possible that u-boot ends up in u-boot console.

Please note, that you can also modify the bootloader variables from within a running linux if the package u-boot-fw-utils is installed. Then you can use `fw_printenv` and `fw_setenv` the same way as you would use `printenv` and `setenv` in U-Boot.

## Partition layout structure

The linux userland uses different partitions to store the system and data.

For the extlinux boot scheme the following partitions are used:

- borootfs
  Mounted on /, storage for linux userland software and also for the boot files: linux kernel, device tree board descriptions and extlinux boot in /boot directory
- userfs
  Mounted on /usr/local, for user data storage

In case of the AB boot scheme the partitions are as following

- boot
  Storage for the boot files (linux kernel and device tree board descriptions) for A and B boot configuration in `root_A` and `root_B` directory. Mounted on /boot when linux is running
- root_A
  Root file system for boot configuration A. Mounted on / if configuration is active
- root_B
  Root file system for boot configuration B. Mounted on / if configuration is active
- userfs
  Mounted on /usr/local, for user data storage

Depending on the capabilities of the hardware and the setting of the boot switches, the SOM can boot directly either from QSPI NOR, SD card or USB boot.

## Image types

Depending on the configuration, Yocto creates different types of images. You can find the image files in your build directory in `tmp/deploy/images/<MACHINE>`. The variable `IMAGE_FSTYPES` can be used to set the types of images to be created.

The image files of the latest build can easily be accessed by using the links, that always point to the files most recently created.

After compilation, different filesystem images are available. The names of these filesystems are composed of the image name and the distribution and machine.

For a configuration with extlinux boot scheme

- image: `image-ktn`
- machine: `stm32mp-t1000-k-multi`

the image names will be

- borootfs: `image-ktn-stm32mp-t1000-k-multi.tar.gz`
- userfs: `image-ktn-userfs-stm32mp-t1000-k-multi-thud.tar.gz`

And for the AB boot scheme configuration

- image: `image-ktn-swu`
- machine: `stm32mp-t1000-k-multi`

the image names will be

- boot: `image-ktn-swu-bootfs-stm32mp-t1000-multi.tar.gz`
- boot_A: `image-ktn-swu-stm32mp-t1000-multi.tar.gz`
- boot_B: `image-ktn-swu-stm32mp-t1000-multi.tar.gz`
- userfs: `image-ktn-swu-userfs-stm32mp-t1000-multi.tar.gz`

Important

For all `*-swu` images, the `swu` package update files are also created on image build! For technical reasons, currently two different `swu` files are created. For example `image-ktn-stm32mp-t1000-multi.swu` and `image-ktn-swu-stm32mp-t1000-multi.swu`. Be aware that only the `image-*-swu-*` files contain a valid update package!

The Kontron Yocto BSP packages only generate compressed filesystems with tar.gz ending. These images are intended to be flashed by booting with SD card and flashing with the mptool Tool. If you wish to generate other images you have to enable them in `IMAGE_FSTYPES`.

- image-*.tar.gz This file contains the compressed filesystem and can be used to flash the contents with mptool tool or to load the filesystem via network after it was extracted

- *.sdcard This file has first to be created out of the image files in the image directory. See section create a bootable SD-card for this. It contains the borootfs and userfs partition besides the tf-a and u-boot bootloader. In default configuration it also contains the flash contents itself to flash them directly with mptool to the internal flashes.

- uImage or zImage This is the kernel image containing the linux kernel.

- u-boot-*-trusted.stm32 This is the u-boot bootloader for the STM32MP trusted boot chain. This can be directly flashed to NOR Flash, eMMC or SD card.

- tf-a-*-trusted.stm32 This is the first stage bootloader (fsbl) for the STM32MP trusted boot chain. This can be directly flashed to NOR Flash, eMMC or SD card.

## Booting your board

There are sevaral options to boot your software on the board:

1. boot your software from a SD-card to run your software for testing or to burn it into the internal flashes with mptool
2. boot your software from internal flash e.g. for productive envrionments
3. boot your software via network while developing
4. boot a u-boot via USB boot for flashing internal flashes with STM32CubeProgrammer on a totally blank device

Important

There are different SOM variants for the STM32MP1 platform. Especially the RAM configurations of 512MB and 256MB requires different boot loadders. All Kontron DKs configurations are based on the 512MB RAM configuration. If you want to boot the Kontron demo images, you have to generate these images with the appropriate bootloader configuration `stm32mp-t1000-k`. See the compatibility list for more information.

### Select a variant

Additionally it is possible to select different variants of your board in the boot loader. With this, it is possible to load the appropriate linux device tree file for your variant.

For the Kontron BL boards, this is used to select different display configurations. The basic device tree file for the board is named `stm32mp-t1000-k.dtb`. To enable the 5 inch DPI display variant, set the `housing` variable in u-boot to `-50`. This way u-boot loads the desired device tree file `stm32mp-t1000-k-50.dtb` for the selected variant alongside with the linux kernel.

## Booting from SD card

### Creation of a bootable SD card

Before you can boot from SD card, you have to create a bootable SD card. There are two ways to create one:

1. Download a already prepared SD card image for your board and write it to the SD card. This is the simplest way to update the firmware on your board, but is limited to the SD card images provided from Kontron.
2. Create your own SD card image with yocto which can be customized to your needs.

For both ways you have to provide an SD card reader which works in your environment!

#### Using prebuilt Kontron image

The simplest way to get a bootable SD card is to download prebuilt images from the Kontron file server. Search the *.sdcard image files for your board and the desired BSP version.

If you want to create the SD card with your PC and Windows os you have to use a suitable imager program for Windows to write the image contents to your SD card. One such easy to use program is 'Etcher'. You can download it from https://github.com/balena-io/etcher/releases

Danger

The usage of imager programs can be dangerous. If you select the wrong disk, it might cause severe loss of data on your hard disk or other drives!

If you want to write this prebuild *.sdcard file on a linux host, you can go on with Create image with yocto and simply skip the image creation procedure with 'create-sd-card.sh'.

#### Create image with yocto

To create a bootable SD card from your image tar.gz files you can use the script `create-sd-card.sh` from your Yocto tmp directory `tmp/deploy/images/<MACHINE>/script-mp` or you can download *.sdcard image files or the tar.gz files of a prebuilt image from the Kontron file server.

The layout and contents of the image is configured by a '*.layout' configuration file. Preconfigured files exist for different configurations of machine, distro and image.

To create the tar.gz files of your image, you have to build your images with bitbake. Then change into the images directory and run the 'create-sd-card.sh' script as root. Root is required for mounting and unmounting the image contents and unpack the contents with the right access rights.

    > bitbake image-ktn
    [...]
    > cd tmp/deploy/images/stm32mp-t1000-k-multi/script-mp
    > sudo ./create-sd-card.sh -c image-ktn-qt-ktn-stm32mp-t1000-k-multi.layout

Important

If you want to use this sd card to write your firmware to the internal flashes mit mptool, don't forget to use the `-p y` command line option or `PROD_IMG=y` configuration file option!

After this you find a file named `image-ktn-qt-ktn-stm32mp-t1000-k-multi.sdcard` in `tmp/deploy/images/stm32mp-t1000-k-multi` directory.

Now fill the SD card with the image contents:

Danger

The usage of the `dd` command in combination with `sudo` can be dangerous. If you use wrong parameters, this might cause severe loss of data on your hard disk or other drives!

    sudo dd if=../image-ktn-qt-ktn-stm32mp-t1000-k-multi.sdcard of=/dev/sdb bs=8M conv=fdatasync status=progress

### Boot into SD card

To boot from the SD-card,

- configure your boot switches for 'SD card boot' (for Kontron Demo-Kits this is not necessary, because the first boot source is the SD card),
- prepend the u-boot environment variable `boot_targets` with `mmc0` or set it to `setenv boot_targets mmc0 mmc1 ubifs0 pxe` (this is the default setting for Kontron Demo-Kits)
- optionally set the boot variant in `housing` for boards with display (e.g. `-50` for the `stm32mp-t1000-k-50` board and device tree). This requires saveenv and a reboot to take effect.

Hint

See your board documentation for information for your board about default boot devices

If you want your settings to be persistent, don't forget to run `saveenv`.
Then you are ready to boot by running `run bootcmd`.

## Booting from internal flash

### Update firmware in flash

Before the the device can boot from internal flash, you have to write your software to it.

Depending on your hardware it is possible that you have two locations where your filesystems can be stored: QSPI NAND or eMMC flash.

The simplest way to populate your flash with the new filesystem contents is to boot from sd card and use the mptool to flash the device with the new contents.

First create your SD card image with create-sd-card.sh tool and the `-p y` option to include your firmware files in the SD card image in `/usr/local` directory. See Creation of a bootable SD card for this.

After your device has booted into the linux system, login and start updating your device:

    mptool flash-bl-fs -m EMMC

mptool has different options to control what shall be updated. The most common are:

Option | Description
--- | ---
flash-tfa | Flash tf-a (first stage) bootloader
flash-u-boot | Flash u-boot (second stage) bootloader
flash-full-bl | Flash all bootloaders (tf-a and u-boot)
flash-full-fs | Flash all filesystem partitions
flash-bl-fs | Flash all bootloaders and all filesystem partitions
-m | Flash filesystem partitions to medium (e.g. NAND or EMMC)

See the mptool description or `mptool -h` for more options.

#### Export eMMC as USB flash drive

In case of eMMC memory it is also posible to publish the eMMC contents as USB flash drive when the OTG port of the device is connected thru USB cable to your development machine.

This way the internal eMMC flash can be handled like a normal USB attached flash device on your development machine. It is very handy if you only want to explore the file system on the board or if you want to exchange only a few files.

To activate USB flash mode in u-boot use the `ums` command, here internal eMMC (mmc 1) on a Kontron Demo-Kit:

    STM32MP> ums 0 mmc 1

Now you can mount the internal eMMC memory like an USB flash drive in your linux development environment. You can then use all the tools linux provides for partitionning, formatting and writing contents to USB flash drives.

### Boot into flash

After the flash is fully populated with your software (see Update firmware in flash), you can boot from flash:

- configure your boot switches for 'NOR boot', or remove the bootable SD card,
- prepend the u-boot environment variable `boot_targets` with `mmc1` for eMMC flash or `ubifs0` for QSPI NAND flash. Or set it to `setenv boot_targets mmc1` or `setenv boot_targets ubifs0`
- optionally set the boot variant in `housing` for boards with display (e.g. `-50` for the `stm32mp-t1000-k-50` board and device tree). This requires saveenv in u-boot and a reboot to take effect.

If you want your settings to be persistent, don't forget to run `saveenv` in u-boot.
Then you are ready to boot by running `run bootcmd`.

Hint

You can find in the appropriate board description, which boot_targets and and boot variants are supported for your board.

Here is an example for selecting NAND for boot, saving it to environment and reboot to take this setting into effect:

    STM32MP> printenv boot_targets
    boot_targets=mmc0 mmc1 ubifs0 pxe
    STM32MP> setenv boot_targets ubifs0
    STM32MP> setenv housing -50
    STM32MP> saveenv
    Saving Environment to SPI Flash... SF: Detected mx25r1635f with page size 256 Bytes, erase size 64 KiB, total 2 MiB
    Erasing SPI flash...Writing to SPI flash...done
    OK
    STM32MP> reset

## Booting via network adapter (TFTP/NFS)

In a development environment where you need to do a lot of testing while changing the kernel and rootfs, it is often helpful to have the system on your development machine and share the files via network with your target device. Please consult the hardware description of your board for the information which ethernet interfaces are supported in u-boot.

In combination with the Yocto build system you can export the `<builddir>/tmp/deploy/images` directory via TFTP to allow the target to fetch the kernel image, devicetrees, etc. To allow the target to use a rootfs over the network, you need to export the rootfs via NFS on your development machine.

The Kontron BSP uses PXE boot for booting over network. See STMicroelectronics Wiki for more information.

### Setup TFTP on the host

To install the TFTP-Server:

    > sudo apt-get install tftp-hpa

Change the TFTP-settings by changing the content of `/etc/default/tftp-hpa`:

    TFTP_USERNAME="tftp"
    TFTP_DIRECTORY="/tftproot"
    TFTP_ADDRESS="[::]:69"
    TFTP_OPTIONS="--secure"

After installation enable and restart the tftp server:

    > sudo systemctl enable tftpd-hpa
    > sudo systemctl restart tftpd-hpa

### Setup NFS on the host

To install the NFS server and create nfs directories:

    > sudo apt-get install nfs-kernel-server
    > sudo mkdir /nfsroot /nfs

Change the NFS settings by changing the content of `/etc/exports`:

    /nfsroot *(rw,no_root_squash,sync,no_subtree_check)
    /nfs *(rw,no_root_squash,sync,no_subtree_check)

After installation enable and restart the nfs server:

    > sudo systemctl enable nfs-kernel-server
    > sudo systemctl restart nfs-kernel-server

With `exportfs` you can check what your nfs server exports:

    > sudo exportfs
    /home/user      <world>
    /nfsroot        <world>
    /nfs            <world>

### Populate NFS and TFTP directories

To extract the rootfs and tftp contents, we suggest to use the `init-remote2` script in `yocto-ktn/scripts`:

    init-remote2 -f <configfile> [-t] [-n] [-o] [-c] [-h]

The most important configuration options are:

- f: use a configuration file
- t: generate TFTP contents
- n: generate NFS contents
- o: overwrite NFS contents if they already exist
- c: clean NFS directory if it already exists
- h: print out help text

You can get more inforation calling the script with the help (-h) option. Although all information can be given on the command line, we suggest to use config files to ease the use of this tool. Config options on the command line have a higher priority as options in the config file. This way the config file can contain default settings which can be overwritten by command line options.

Example configuration files can be found in `build-stm32mp/conf` directory. This is the example file `init-remote_t1000-k-multi_console.conf` for the console image:

    # this is a simple config file for init-remote2

    # name of builddir
    OPT_BUILDDIR=build-stm32mp

    # name of machine
    OPT_MACHINE=stm32mp-t1000-k-multi

    # name of used distro
    OPT_DISTRO=ktn-eglfs

    # name of rootfs image file
    OPT_IMAGE=image-stm32mp-console

    # compatibility option
    OPT_SINGLEBOARD=0

    # generate tftp directory in /tftproot/$OPT_TFTPNAME
    OPT_GEN_TFTP=0
    OPT_TFTPNAME=t1000-k-multi_console

    # generate nfs directory in /nfs/$OPT_NFSNAME
    OPT_GEN_NFS=0
    OPT_NFSNAME=t1000-k-multi_console
    # overwrite existing files
    OPT_OVERWRITE_NFS=0
    # clean nfs directory before deploying a new one
    OPT_CLEAN_NFS=0

    # generate debian packacke repos in $OPT_BUILDDIR/pkg-repos
    OPT_GEN_PKGREPOS=0

For example to generate the NFS and TFTP contents for the console image:

    init-remote2 -f conf/init-remote_t1000-k-multi_console.conf -t -n

The files in `/nfs/t1000-k-multi_console` and `/tftproot/t1000-k-multi_console` are populated. `init-remote2` uses `sudo` to populate some files for NFS. So it might be that you are being asked for the root password of your development machine.

To update the directoies with modified content use

    init-remote2 -f conf/init-remote_t1000-k-multi_console.conf -t -n -o

With the `-o` option all files out of the image are replaced with the new content. Files in the NFS directory which are not contained in the image stay untouched in their location.

If you want to wipe out an old NFS directory and get one brand-new use the `-c` option:

    init-remote2 -f conf/init-remote_t1000-k-multi_console.conf -n -c

Hint

`init-remote2` only deploys borootfs image. userfs and rescuefs images are not deployed!

### Create PXE configuration for your board

You have to create a PXE configuration for every board you want to boot over network. The PXE configuration is stored in the `pxelinux.cfg` subdirectory of your TFTP server directory. For every board you have to create a configuration file named similar to its MAC address.

First get the MAC address of your board from u-boot prompt:

    STM32MP> pri ethaddr
    ethaddr=70:82:0e:99:96:52

Create and edit the config file for this board. Prepend config file name with `01-` and replace all `:` by `-`. Here is an example:

    > gedit /tftproot/pxelinux.cfg/01-70-82-0e-99-96-52

These are the PXE config file contents for this example:

    #bootfile for t1000-k
    DEFAULT t1000-k-50_console
    TIMEOUT 20
    LABEL t1000-k-50_console
        KERNEL t1000-k-multi_console/uImage
        FDT t1000-k-multi_console/stm32mp-t1000-k-50.dtb
        APPEND root=/dev/nfs nfsroot=192.168.1.240:/nfs/t1000-k-multi_console,nfsvers=3 rootwait rw earlyprintk console=ttySTM0,115200 ip=192.168.1.11

For more information about booting over network see also STMicroelectronics Wiki

Important

- You have to adapt the NFS server ip and the board's ip address to your setup

### Boot from network

In the bootloader prepend or replace the list of `boot_targets` with the `pxe` entry (e.g. `boot_targets=pxe mmc0 mmc1 ubifs0`). Furthermore you should adapt the `serverip` environment variable to your host's ip address. If you want your settings to be persistent, don't forget to run `saveenv`.

Then you are ready to boot by running `run bootcmd`.

    STM32MP> setenv boot_targets pxe mmc0 mmc1 ubifs0
    STM32MP> setenv serverip 192.168.1.240
    STM32MP> saveenv
    STM32MP> run bootcmd

## Initial booting with USB boot

The STM32MP1 SOCs have the ability to load images and data from a host PC via USB to the internal SRAM. With the help of u-boot it is possible to write images to the connected storage devices. This is mostly used in development or production environment for board bring up. For Kontron SOCs flashing QSPI NOR, eMMC and SD card is currently supported.

Hint

For the Kontron BSPs the filesystem partions aren't generated with default settings. STM32CubeProgrammer is only used to flash the bootloaders 'tf-a' and 'u-boot' if booting from sd card is not recommended. Further flashing is done by booting from SD card and using 'mptool'.

To use this feature the SOC has to be USB boot mode, which means you set the boot switches to USB boot or the internal NOR flash must be empty.

Hint

Depending on the OTP-Fuses and if they were already burned, it might not be possible to put the SOC into USB boot mode anymore.

When the SOC is in USB boot mode and you connect a Micro-USB cable to the OTG-Port of the board, your host PC should detect a new USB device.

On Linux you can check for the device with `lsusb`:

    > lsusb | grep STM
    Bus 003 Device 039: ID 0483:df11 STMicroelectronics STM Device in DFU Mode

To download and flash content from your host PC on the device you have to use the STM32CubeProgrammer

### Flashing with STM32CubeProgrammer

To load a full system (tf-a, u-boot, borootfs, userfs) or only part of it into the QSPI NOR eMMC or SD card you can use the `*.tsv` programmer files from the yocto machine directory `meta-ktn-stm32mp/conf/machine`.

First check the connection to the board:

    > STM32_Programmer_CLI -c port=usb1
          -------------------------------------------------------------------
                            STM32CubeProgrammer v2.0.0
          -------------------------------------------------------------------

    USB speed   : High Speed (480MBit/s)
    Manuf. ID   : STMicroelectronics
    Product ID  : DFU in HS Mode @Device ID /0x500, @Revision ID /0x0000
    SN          : 002500413338510B34383330
    FW version  : 0x0110
    Device ID   : 0x0500
    Device name : STM32MPxxx
    Device type : MPU
    Device CPU  : Cortex-A7

If the programmer can't get the connection, you might adapt your UDEV rules to grant your user account to communicate with this device. In this case you have to create an appropriate UDEV rule for the programmer. This can be done for example by creating the file `/etc/udev/rules.d/50-usb-stmicro.rules` with the following content:

    # Grant permissions for all STMicro devices
    SUBSYSTEMS=="usb", ATTRS{idVendor}=="0483", GROUP="users", MODE="0666"

When connection is ok, you can now program the flash contents. In this example we'll program the QSPI NOR and eMMC flash of the board. For this you should have the tf-a, u-boot, bootfs, rootfs and userfs image files in your images directory (for example `tmp/deploy/images/stm32mp-t1000-k-multi`):

Info

Depending on the size of the filesystem images this programming requires a few minutes to finish.

    > cd build-stm32mp
    > cp ../layers/meta-ktn-stm32mp/conf/machine/FlashLayout_t1000-k-multi_qt_nor-emmc.tsv tmp/deploy/images/stm32mp-t1000-k-multi/
    > STM32_Programmer_CLI -c port=usb1 -tm 100000 -w tmp/deploy/images/stm32mp-t1000-k-multi/FlashLayout_t1000-k-multi_qt_nor-emmc.tsv
          -------------------------------------------------------------------
                            STM32CubeProgrammer v2.0.0
          -------------------------------------------------------------------

    Warning: Timeout is forced to 100000 ms

    USB speed   : High Speed (480MBit/s)
    Manuf. ID   : STMicroelectronics
    Product ID  : DFU in HS Mode @Device ID /0x500, @Revision ID /0x0000
    SN          : 002500413338510B34383330
    FW version  : 0x0110
    Device ID   : 0x0500
    Device name : STM32MPxxx
    Device type : MPU
    Device CPU  : Cortex-A7

    Start Embedded Flashing service

    Memory Programming ...
    Opening and parsing file: tf-a-stm32mp-t1000-k-trusted.stm32
      File          : tf-a-stm32mp-t1000-k-trusted.stm32
      Size          : 245360 Bytes
      Partition ID  : 0x01

    Download in Progress:
    [==================================================] 100%

    File download complete
    [...]

    Memory Programming ...
    Opening and parsing file: st-image-userfs-ktn-eglfs-stm32mp-t1000-k-multi.ext4
      File          : st-image-userfs-ktn-eglfs-stm32mp-t1000-k-multi.ext4
      Size          : 64 MBytes
      Partition ID  : 0x12

    Download in Progress:
    [==================================================] 100%

    File download complete
    Time elapsed during download operation: 00:00:53.085

    RUNNING Program ...
      PartID:      :0x12
    Start operation done successfully at partition 0x12
    Flashing service completed successfully

After successful flashing the device you can change the boot switches to eMMC boot and start your linux system.

Programming can also be done for other flash devices on the board. For more examples see the other tsv files in the yocto machine directory mentioned above.

It is also possible to flash only some parts of the device. For this the ID field of the tsv file can be modified:

- -: do nothing
- P: update the partition data, do not modify GPT partition table
- PE: (re)create GPU partition table, but do not update partition data
- PD: (re)create GPT partition table and update partition data
- PDE: (re)create GPT partition table and empty partition data

Hint

- The tsv file format is sensitive for tabs and whitespaces! So be sure to separate the fields in one row by one single tab. Else reading the file by STM32CubeProgrammer will fail!
- If only some flash parts of device shall be programmed, the complete partition layout in the tsv file has to fit to the real device even the partition is not touched. Else the programmer complains and refuses programming.

For further information how to install and use the tool and how to configure the contents to be flashed, read the documentation on STMicroelectronics website

Important

For the correct function of CubeProgrammer it is important that the u-boot launches the command `stm32prog usb` if it is started by USB boot. It is required for communication with CubeProgrammer. For the Kontron u-boot this is done in the preboot command. If you modify u-boot for your own requirements you should have this in mind!

Important

The Kontron u-boot loaded with CubeProgrammer reads the u-boot environment on start. This can lead to situations where these settings prevent the usage of CubeProgrammer because, for example it doesn't start `stm32prog usb` . In this case the u-boot environment has to be erased. This can be done on u-boot command line with the command `mtd erase env`

## Login

After a successful boot you will be greeted with a login prompt. The default (and only) user in an unmodified Konton image is the `root` user and it has no password.