SD Card

Create a Bootable SD Card

To create a bootable SD card, you’ll need to flash a BSP image onto it. “Flashing” refers to the process of burning software images onto a flash memory storage device. This guide section outlines three methods for flashing the complete .wic.xz image format to an SD Card. One method involves using balena-etcher, while the other two methods utilize Linux terminal commands: dd and bmaptool.

The .wic.xz image format is a compressed binary containing all the necessary binaries, as well as information about the required disk partitions needed for booting the phyCORE-AM64x into Linux. This includes the bootloader, kernel, and root filesystem.

In order to boot the phyCORE-AM64x development kit into Linux, it must load valid software from a memory storage device. It is typical for production systems to boot software from an onboard (non-removable) memory storage device such as eMMC memory but booting from an SD Card is more convenient during development. The phyCORE-AM64x development kit is configured to boot from an SD Card by default.

A pre-configured SD Card should have been included in the box with your development kit but this guide will walk through the creation of a bootable SD Card using Pre-Built Binaries or images you have generated on your own by following the Build the BSP guide.

Warning

The machine number for the BSP image can be impacted based on the processor you are developing with. Please refer to the table Part Number Summary in the BSP-Yocto-Ampliphy-AM64x-PD24.1.1 to assist in selecting the correct machine.

Layout of a SD Card

To generate bootable WIC image artifacts, we utilize the wic command, which is the OpenEmbedded Image Creator. The final unpacked phytec-container-image-phyboard-electra-am64xx-2.rootfs.wic.xz defines the SD Card layout as follows.

Using balenaEtcher

What you’ll need

SD Card Reader
4GB micro-SD Card or larger (Included in development kit)

Step-by-Step

Download the SD card flasher app BalenaEtcher
Download the prebuilt SD card image Pre-Built Binaries.
Now that your system is setup, use the BalenaEtcher SD card flasher to create a bootable SD card.
1. Open BalenaEthcher and select “Flash from file”.
2. Select the phytec-container-image-phyboard-electra-am64xx-2.rootfs.wic.xz SD card image file from your Downloads folder.
3. Then insert the micro-SD card into the SD card reader.
4. Click on “Select Target” and select the SD card.
5. Begin flashing the SD card by pressing “Flash!”
6. Once BalenaEtcher is done flashing the SD card image, eject the SD card from the Host PC and insert the SD card into the development kit.

See the section “Booting from SD Card” for more information.

Using bmaptool (Linux)

What you’ll need

Ubuntu 22.04 LTS, 64-bit Host Machine
- If using a virtual machine, VMWare Workstation, VMWare Player, and VirtualBox are all viable solutions.
SD Card Reader
4GB micro-SD Card or larger (Included in development kit)

Step-by-Step

Download the prebuilt SD card image (wic.xz) and bmap (.wic.bmap) from the Pre-Built Binaries.
Install bmaptool
```
host:~$ sudo apt install bmap-tools
```
Run the following command without the SD card connected to the host machine.
```
host:~$ ls /dev/sd*
```
Connect the SD card to the Ubuntu host machine.
Run the following command again with the SD card connected to the host machine.
```
host:~$ ls /dev/sd*
```
Unmount the SD card from the host machine. Do not remove the card from the machine.
```
host:~$ umount /dev/sdX*
```
Navigate to the directory containing the ‘.wic.xz’ file you wish to flash. This might be wherever you downloaded the pre-built image or it could be the deployment directory of your local BSP build at $BUILDDIR/deploy-ampliphy/images/phyboard-electra-am64xx-2/
```
host:~$ cd <image location>
```
Flash the .wic.xz image to the SD Card using bmaptool:
```
host:~$ sudo bmaptool copy phytec-container-image-phyboard-electra-am64xx-2.rootfs.wic.xz /dev/sdX
```
Note

Note that you have to flash the SD Card image to the entirety of the SD Card. This is done by specify the output location of the flashing command without a numbered partition specified. For example, if you try to flash the SD Card image to /dev/sda1 this will result in a improperly formatted SD Card.

Unmount the SD card from your Linux machine.

host:~$ umount /media/<user>/boot /media/<user>/root

Insert the micro-SD card into the development kit. For more information on how to boot from SD card, see the section “Booting from SD Card”.

Using dd (Linux)

What you’ll need

Ubuntu 22.04 LTS, 64-bit Host Machine
- If using a virtual machine, VMWare Workstation, VMWare Player, and VirtualBox are all viable solutions.
SD Card Reader
4GB micro-SD Card or larger (Included in development kit)

Step-by-Step

Download the prebuilt SD card image (wic.xz) from the BSP-Yocto-Ampliphy-AM64x-PD24.1.1.
Run the following command without the SD card connected to the host machine.
```
host:~$ ls /dev/sd*
```
Connect the SD card to the Ubuntu host machine.
Run the following command again with the SD card connected to the host machine.
```
host:~$ ls /dev/sd*
```
Unmount the SD card from the host machine. Do not remove the card from the machine.
```
host:~$ umount /dev/sdX*
```
Navigate to the directory containing the ‘.wic.xz’ file you wish to flash. This might be wherever you downloaded the pre-built image or it could be the deployment directory of your local BSP build at $BUILDDIR/deploy-ampliphy/images/phyboard-electra-am64xx-2/
```
host:~$ cd <image location>
```
Flash the .wic.xz image to the SD Card:
```
host:~$ sudo xz -dc phytec-container-image-phyboard-electra-am64xx-2.rootfs.wic.xz | sudo dd of=/dev/sdX bs=8192 conv=fsync
```
Note

Note that you have to flash the SD Card image to the entirety of the SD Card. This is done by specify the output location of the flashing command without a numbered partition specified. For example, if you try to flash the SD Card image to /dev/sda1 this will result in a improperly formatted SD Card.

Unmount the SD card from your Linux machine.

host:~$ umount /media/<user>/boot /media/<user>/root

Insert the micro-SD card into the development kit. For more information on how to boot from SD card, see the section “Booting from SD Card”.

Updating Individual Parts of the SD Card (Advanced, Linux Machine)

Once the SD card has been formatted the first time via flashing the complete .wic.xz image, you do not need to flash the entire contents of the SD Card image again to update the image components. The bootloader, kernel and root filesystem can be updated individually (depending on the changes being tested) to potentially save a lot of time during development. Find all the images and binaries for the phyCORE-AM64x development kit on the Pre-Built Binaries page.

Updating the Kernel

First, remove the existing kernel image and device tree files:

host:~$ sudo rm /media/<user>/boot/Image
host:~$ sudo rm /media/<user>/boot/oftree
host:~$ sudo rm /media/<user>/boot/k3-am642-phyboard-electra-rdk.dtb

Copy the new Linux kernel, device tree binaries and applicable device tree overlays to the SD card’s Boot partition:

host:~$ sudo cp Image /media/<user>/boot/
host:~$ sudo cp oftree /media/<user>/boot/
host:~$ sudo cp k3-am642-phyboard-electra-rdk.dtb /media/<user>/boot/
host:~$ sudo sync /media/<user>/boot/

Updating the Root Filesystem

Connect your SD card to the Host Machine and identify the root filesystem’s mount point. This can be down using the mount utility from above:

host:~$ mount
sysfs on /sys type sysfs (rw,nosuid,nodev,noexec,relatime)
proc on /proc type proc (rw,nosuid,nodev,noexec,relatime)
udev on /dev type devtmpfs (rw,nosuid,relatime,size=1975752k,nr_inodes=493938,mode=755)
devpts on /dev/pts type devpts (rw,nosuid,noexec,relatime,gid=5,mode=620,ptmxmode=000)
tmpfs on /run type tmpfs (rw,nosuid,noexec,relatime,size=400172k,mode=755)
/dev/sda1 on / type ext4 (rw,relatime,errors=remount-ro)
...
/dev/sde1 on /media/<user>/boot type vfat (rw,nosuid,nodev,relatime,uid=1000,gid=1000,fmask=0022,dmask=0022,codepage=437,iocharset=iso8859-1,shortname=mixed,showexec,utf8,flush,errors=remount-ro,uhelper=udisks2)
/dev/sde2 on /media/<user>/root type ext4 (rw,nosuid,nodev,relatime,uhelper=udisks2)

We can see in this example output the SD card’s two partitions are mounted on /media/<user>/boot and /media/<user>/root respectively.

Delete the contents of the SD card’s root filesystem partition:
```
host:~$ sudo rm -rf /media/<user>/root/*
```

Unpack the root filesystem tarball into the SD card’s existing root filesystem partition’s mount point:

host:~$ sudo tar -xf phytec-container-image-phyboard-electra-am64xx-2.tar.xz -C /media/<user>/root/
host:~$ sudo sync /media/<user>/root/

Updating the Bootloader

Delete the contents of the SD card’s boot partition:

host:~$ sudo rm /media/<user>/boot/tiboot3.bin
host:~$ sudo rm /media/<user>/boot/tispl.bin
host:~$ sudo rm /media/<user>/boot/u-boot.img

Copy the bootloader binaries to the SD card:

host:~$ sudo cp tiboot3.bin /media/<user>/boot/
host:~$ sudo cp tispl.bin /media/<user>/boot/
host:~$ sudo cp u-boot.img /media/<user>/boot/
host:~$ sudo sync /media/<user>/boot/

Booting from SD Card

The phyCORE-AM64x development kit is configured to boot from an SD Card slot by default and basic steps for performing this and establishing serial communication are outlined in the Quickstart. Boot switch (aka DIP switches) settings determine the location and method the boot ROM loads the first stage bootloader into memory before executing it.

Note

If you have saved the U-Boot environment using saveenv, those changes may persist even if you have reflashed the SD card. Bmaptool will persist the environment, while other programs like balena-etcher might reset the environment. You can manually reset the environment using:

uboot:~# env default -f -a
uboot:~# saveenv

Boot Switch Settings

S10 should be ON to override default boot settings.