Introduction

This Quickstart guide describes the tools and provides the know-how to install and work with the Linux Board Support Package (BSP) for the phyCORE-i.MX 91/93 Alpha Kit. This guide shows you how to install the appropriate tools and sources, build custom kernels, and deploy the OS to operate the software and hardware.

This kit is currently in Alpha Status. There are several topics to keep in mind while working with this kit and guide:

• The phyCORE-i.MX 91/93 will undergo several functional changes during the Alpha Stage of development. Due to this, this Quickstart guide may change without any prior notice.
• The phyCORE-i.MX 91/93 has some functionality that is not currently operational. Please be aware of this when working with the Alpha Kit.
• This Quickstart guide is only for booting and starting the basic functionality of the phyCORE-i.MX 91/93.
• Hardware manual for the phyCORE-i.MX 91/93 can be found here: L-1058e.A0 phyCORE-i.MX 93/phyBOARD-Segin (1607.0/1472.4) Hardware Manual
• The following manuals will be available in future releases of the phyCORE-i.MX 91/93:

* Yocto Reference Manual - provides information on Yocto, which is used with most PHYTEC products
* Board Support Package (BSP) Manual - provides detailed instructions on running the tools which are used to build various software
* Development Environment Guide - provides instructions to prepare and start the programs Eclipse and QT Creator, as well as setting up a Linux host system
* Pin Muxing Table - a complete list of all signal chains from processor to carrier board output. Signal level, signal type, and other useful information is also included.

For more information or details regarding the phyCORE-i.MX 91/93, please contact the PHYTEC Sales department. For information about all our supported i.MX 9 variants, visit our web page athttps://www.phytec.de/produkte/system-on-modules/phycore-imx-91-93/

Requirements

The following components and system requirements are necessary to successfully complete this Quickstart. Deviations from these requirements are possible but may require workarounds.

Hardware

Included in Kit

1. phyCORE-i.MX 91/93 SOM (PCL-077)
2. phyBOARD-Segin Alpha carrier board (PB-02029-010I.A0)
3. Power adapter supplying 24 V / 1 A (SV055)
   
4. Ethernet cable (WK114)
   
5. USB-A to USB Micro Cable (WK345)
   
6. SD Card with prepared prebuilt images
   
7. Serial Cable (WK548)
8. Evaluation Adapter (PEB-EVAL-01-1413-1)
9. Power Module (PEB-POW-01)

Components

Connecting thephyBOARD-Segin

There are a few manual connections that you will need to make before using the phyBOARD-Segin.

• Evaluation Module (PEB-EVAL-01) connected via the Expansion Connector (X16) on the phyBOARD-Segin (phyBOARD-Segin with Evaluation and Power Modules)
• Power Module (PEB-POW-01) connected via the Power Connector (X2) on the phyBOARD-Segin (phyBOARD-Segin with Evaluation and Power Modules)

Connecting the Debug Interface

For the following steps, a console connection via RS232 is required. You can use the included COM cable.

1. Connect your PC's COM port with the COM port (X4) of the Evaluation Module (PEB-EVAL-01).
2. Your device manager will show new COM ports. On the processor side, UART1 is the default debug UART of the SoM.
3. Setup your Terminal with the following parameters:
   • Speed: 115200 baud
   • Data bits: 8
   • Stop bits: 1
   • Parity: None
   • Flow control: None

On Linux, a simple serial device tool like tio can be used:

host$ sudo apt update
host$ sudo apt install tio
host$ tio /dev/ttyUSB1

Linux Host PC

Before you can work with the phyCORE-i.MX 91/93 Board Support Package (BSP), you will need a host PC with the following minimum requirements:

• A modern Linux operating host system either natively or via a virtual machine.
• The underlying NXP-BSP is using Ubuntu 20.04 LTS 64-bit. Other distributions will likely work but note that some setup information, as well as OS-specific commands and paths, may differ. See Yocto Mickledore compatible distributions
• VMWare Workstation, VMWare Player, and VirtualBox are possible solutions if you want to use a virtual machine.
• Root access to your Linux host PC. Some commands in this guide will not work if you do not have sudo access (e.g. package installation, formatting an SD card).
• At least 40 GB to 50 GB of free space on the build partition of the host PC.
• An SD card reader, operational under Linux.
• An active internet connection.

Getting Started with the Included SD Card

This section is designed to get the board up and running with the SD card included in the kit, which has been prepared with pre-built images.

Booting from the SD Card

This section describes how to boot thephyBOARD-Segin with the pre-built images on the included SD card.

• Insert the micro SD card into the SD card slot of the board.
• Start your favorite terminal software (e.g. Minicom or Tera Term) on your host PC and configure it for 115200 baud, 8 data bits, no parity, and 1 stop bit (8n1) with no handshake.
• Connect the power supply to the power connector (please note the polarity shown in the picture Power Schematic).
• Set the correct boot option

The console output can be viewed in your terminal window. If everything has been done correctly, the login prompt will be shown at the end of the booting process:

phyboard-segin-imx93-1 login:

The default login is:

• User: root
• Password: root

Powering the Board

We recommend powering the phyBOARD-Segin Alpha with the power supply (SV055) included in the kit. Connect the power supply to the Power-In connector (X1) of PEB-POW-01.

Prebuild Images

PHYTEC provides prebuild images and release notes for the phyBOARD-Segin-i.MX 91/93. They can be downloaded here: BSP-Yocto-NXP-i.MX93-ALPHA1/images/

Git Repositories

You can find all PHYTEC Git repositories on:

git://git.phytec.de

or

https://github.com/phytec/

Used u-boot repository:

https://git.phytec.de/u-boot-imx/

Our u-boot version is based on the Ti u-boot.

Used Linux kernel repository:

https://git.phytec.de/linux-imx/ 

Our i.MX 91/93 kernel is based on the NXP Linux kernel.

Building the BSP

This section will guide you through the general build process of the NXP i.MX 93 BSP using Yocto and the phyLinux script

Basic Set-Up

Basic Set-Up

There are a few important steps that have to be done before the main build process.

• Setting up the host, see Setting up the Host
• Setting up the Git configuration, see Git Configuration

Get the BSP

There are two ways to get the BSP sources. You can download the complete BSP sources from our download page:BSP-Yocto-i.MX93; or you can build it yourself with Yocto. This is particularly useful if you want to make customizations. 

The phyLinux script is a basic management tool for PHYTEC Yocto BSP releases written in Python. It is mainly a helper to get started with the BSP structure. 

• Create a fresh project folder, get phyLinux, and make the script executable:

host$ mkdir ~/yocto
host$ cd yocto/
host$ wget https://download.phytec.de/Software/Linux/Yocto/Tools/phyLinux
host$ chmod +x phyLinux

• Run phyLinux

host$ ./phyLinux init

• During the execution of the init command, you need to choose your processor platform (SoC), PHYTEC's BSP release number, and the hardware you are working on.
  

  15 # imx93
  1 # BSP-Yocto-NXP-i.MX93-ALPHA1

  The BSP provides two different builds: One generic build without display support, called "headless"; and another one with display support, called "qt6-demo". In the next step, you need to choose which one to use.
  

  for a headless build use:
  1 # phyboard-segin-imx93-1     PHYTEC phyBOARD-Segin i.MX93   (..."target: phytec-headless-image") 
  
  
  for a build with display support use:
  2 # phyboard-segin-imx93-1     PHYTEC phyBOARD-Segin i.MX93   (..."target: phytec-qt6demo-image")

• It is also possible to pass this information directly using command line parameters:

  host$ DISTRO=ampliphy-vendor-wayland MACHINE=phyboard-segin-imx93-1 ./phyLinux init -p imx93 -r BSP-Yocto-NXP-i.MX93-ALPHA1

After the execution of the init command, phyLinux will print a few important notes as well as information for the next steps in the build process.

Starting the Build Process

• Set up the shell environment variables:

host$ source sources/oe-core/oe-init-build-env

• The current working directory of the shell should change to build/.
• Open the main configuration file and accept the GPU and VPU binary license agreements. You have to uncomment the corresponding line.
  

host$ vim conf/local.conf
# Uncomment to accept NXP EULA                                                  
# EULA can be found under ../sources/meta-freescale/EULA                        
ACCEPT_FSL_EULA = "1"

• Build your image:

# for an image without display support:
host$ bitbake phytec-qt6demo-image

# or with display support:
host$ bitbake phytec-qt6demo-image

BSP Images

All images generated by Bitbake are deployed to ~/yocto/build/deploy/images/<machine>. The following list shows for example all files generated for the i.MX 93 phyBOARD-Segin-imx93-* machine:

• u-boot-spl.bin: The first bootloader image (2nd program loader from u-boot), loaded by the boot ROM, initializes the DDR-RAM and loads the u-boot.img.
• u-boot.img:Bootloader for the i.MX 93 phyBOARD-Segin-imx93.
  
• Image: Linux kernel image
• imx93-phyboard-segin-rdk.dtb: Kernel device tree file
• phytec-headless-image-phyboard-segin-imx93-1.tar.gz
  orphytec-qt6demo-image-phyboard-segin-imx93-1.tar.gz:Root file system
  
• phytec-headless-image-phyboard-segin-imx93-1.wic.xz:
  orphytec-qt6demo-image-phyboard-segin-imx93-1.wic.xz: SD card image

Update and Device Management

This section of the product wiki contains guides for common development tasks associated with updating the software on the phyCORE-i.MX 91/93 SOM.

Create a Bootable SD Card

In order to boot the phyCORE-i.MX 91/93 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-i.MX 91/93 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.

Requirements

• Ubuntu 20.04 LTS, 64-bit Host Machine

  • If using a virtual machine, VMWare Workstation, VMWare Player, and VirtualBox are all viable solutions.

• SD Card Reader operational under the Ubuntu Host Machine

• 4GB SD Card or larger

Flashing a Complete Image

Flashing is a term used to describe the process of burning software images to a flash memory storage device, hence flashing. This section of the guide will outline the steps for flashing the complete .wic.xz image format to an SD Card. The .wic.xz image format is a compressed binary consisting of all the necessary binaries, as well as information about the required disk partitions needed for booting the phyCORE-i.MX 91/93 into Linux. This includes the bootloader, kernel, and root filesystem.

• Install bmap-tools on your host Machine:

host$ sudo apt-get update
host$ sudo apt install bmap-tools

• Run the following command without the SD Card connected to the Host Machine.

host$ ls /dev/disk/by-id/*

• 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/disk/by-id/*

• Navigate to the directory containing the .wic.xz and .wic.bmap files 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/images/phyboard-segin-imx93-1/

host$ cd <image location>

• Flash the .wic.xz image to the SD Card:

# for an image without display support:
host$ sudo bmaptool copy phytec-headless-image-phyboard-segin-imx93-1.wic.xz /dev/disk/by-id/<your device>      

# or with display support:
host$ sudo bmaptool copy phytec-qt6demo-image-phyboard-segin-imx93-1.wic.xz /dev/disk/by-id/<your device>

Updating Individual Parts

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.

Updating the Kernel

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

host$ rm /media/<user>/boot/Image
host$ rm /media/<user>/boot/*.dtb
host$ rm /media/<user>/boot/oftree
host$ rm /media/<user>/boot/tee.bin 

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

host$ cp Image /media/<user>/boot/
host$ cp oftree /media/<user>/boot/
host$ cp imx93-peb-av-02.dtb /media/<user>/boot/  # only for a build with display support
host$ cp tee.bin /media/<user>/boot/ 
host$ sudo sync /media/<user>/root/

Updating the Root Filesystem

• Connect your SD Card to the Host Machine and identify the root filesystem’s mount point. This can be done 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-headless-image-phyboard-segin-imx93-1.tar.gz -C /media/<user>/root/
or 
host$ sudo tar -xf phytec-qt6demo-image-phyboard-segin-imx93-1.tar.gz -C /media/<user>/root/


host$ sudo sync /media/<user>/root/

Device Tree Settings

Change the Device Tree

By default, U-Boot loads the dtb file named oftree as the active device tree during boot. This portion of the guide will instruct how to change U-boot to load a different device tree by a different name.

• Power on the board and press any key to stop autoboot and enter U-boot.
• Change the default device tree.

=> setenv default_device_tree <dtb name>
=> saveenv
Saving Environment to FAT... OK

U-Boot will now load the dtb file named ‘<dtb name>’ automatically during subsequent boots (just replace it with the appropriate file name when you run the command).

Copying Files to the Device

There are several ways of transferring files to and from your target device. Please reference the following for some possible methods.

Secure Copy Protocol

Secure Copy Protocol (SCP) is built around a Secure Shell connection (SSH) and offers all the same security features. One advantage of using this method for transferring single files is that it is generally pretty fast but you won’t get interactive functionality when pulling multiple files from a remote server. For example, you won’t be able to list out directory contents and see what other files are available. SCP also has no file size limitations.

• Use the following command to transfer your file:

host$ scp <insert-path-to-file> root@<insert-IP-address>:~

• Your copied file will appear in the root directory on the target device.
• To go the other direction and retrieve files from the Target Hardware, just flip the source and destination arguments:

host$ scp root@<insert-IP-address>:<insert-name-of-file> <insert-path-to-destination>

USB Storage Device

USB storage devices should mount automatically, the mount utility can help show where:

target$ mount | grep sda
/dev/sda1 on /run/media/sda1 type vfat (rw,relatime,gid=6,fmask=0007,dmask=0007,allow_utime=0020,codepage=437,iocharset=iso8859-1,shortname=mixed,errors=remount-ro)

In the above example output we can see that the device sda (located at /dev/sda) has a single partition /dev/sda1 mounted on /run/media/sda1.

• Generate a random 10 MB file to test transferring data from the storage device.

target$ dd if=/dev/urandom of=test.file count=10 bs=1M

• Copy the file to your storage device.

target$ cp test.file /run/media/sda1 && sync

• Copy the test file we previously created during the write process back to the host:

target$ cp /run/media/sda1/test.file readback-usb.file && sync

• We can double-check that the file was successfully copied to and from the USB device by checking the md5sum of the file:

root@phyboard-segin-imx93-1:~# md5sum test.file readback-usb.file
eab3b13f7ffa7f5c22e8b0c9c061c874  test.file
eab3b13f7ffa7f5c22e8b0c9c061c874  readback-usb.file

• Make sure the drive is unmounted prior to physically disconnecting the device. Failure to do so may result in loss of data and corruption of files

target$ umount /run/media/sda1/

The Bootable SD Card (Root Partition)

Since our Host Machines have access to the SD Card readers, we can use the bootable SD Card itself to transfer files to and from the development kit too, the only downside for this is that you will want to poweroff the development kit before removing the primary boot media.

• Remove the SD Card and connect it to your Host Machine. You will not be able to place files on the SD Card using Windows because the SD Card is formatted for Linux and Windows won't recognize it.

• In order to copy files to the SD Card using the Terminal, this can be done with the standard cp (copy) command. See the above section utilizing a USB storage device for more information.

Accessing Peripherals

Network

All interfaces offer a standard Linux network port that can be programmed using the BSD socket interface. The whole network configuration is handled by the systemd-networkd daemon. The relevant configuration files can be found on the target in /lib/systemd/network/ as well as the BSP in meta-yogurt/recipes-core/systemd/system-machine-units.

IP addresses can be configured within *.network files. The default IP address and netmask for eth0 and eth1 are:

SSH into the phyCORE-i.MX 91/93

This section of the guide will walk through establishing an SSH connection with the hardware which can be a handy way to quickly get a second terminal session up and running. This might be useful if you are doing development directly on the target and need to process a second task in parallel with something running in the standard hardware UART console. In order to most easily follow this section of the guide, both the phyCORE-i.MX 91/93 and your Host Machine must be connected to the same local area network (LAN).

Using your Ubuntu Host Machine, start a new Terminal session and use the following command to ensure that ssh is installed:

host$ sudo apt update
host$ sudo apt install ssh

The phyCORE-i.MX 91/93 Linux BSP has an SSH server installed and enabled by default so it is already pre-configured to accept SSH connections. Establish a connection with the development kit using the Host Machine:

host$ ssh root@192.168.3.11 

GPIOs

The phyBOARD-Segin has a set of pins especially dedicated as a user I/Os. Those pins are connected directly to i.MX 93 pins and are muxed as GPIOs. They are directly usable in Linux userspace. The processor has organized its GPIOs into four instances: GPIO1, GPIO2, GPIO3, and GPIO14, each of 32 pins. But due to muxing, not all can be used.

In the schematic GPIOs are identified as X_GPIO<a>_<b> (e.g. X_GPIO1_10). <a> identifies the GPIO instance, while <b> stands for the GPIO within the instance.

The Linux kernel organizes all GPIOs in so-called gpiochips, where each chip contains 32 GPIOs. Note that the gpiochips mapped to the i.MX 93 GPIO instances as below:

GPIO1 instance maps to gpiochip0 [43810080.gpio]
GPIO2 instance maps to gpiochip1 [43820080.gpio]
GPIO3 instance maps to gpiochip2 [43830080.gpio]
GPIO4 instance maps to gpiochip3 [47400080.gpio]

Accessing GPIOs from userspace will be done using the libgpiod. It provides a library and tools for interacting with the Linux GPIO character device. The used pins have to be configured as GPIO in the kernel before usage. Examples of the usage for some of the tools:

• Detecting the gpiochips on the chip:

target$ gpiodetect 
gpiochip0 [43810080.gpio] (32 lines)
gpiochip1 [43820080.gpio] (32 lines)
gpiochip2 [43830080.gpio] (32 lines)
gpiochip3 [47400080.gpio] (32 lines)  

• Show detailed information about the gpiochips. Like their names, consumers, direction, active state, and additional flags:

target$ gpioinfo gpiochip0

• Read the value of a GPIO (e.g GPIO 20 from chip0):

target$ gpioget gpiochip0 20

• Set the value of GPIO 20 on chip0 to 0 and exit tool:

target$ gpioset --mode=exit gpiochip0 20=0

RS232

The i.MX 93 SoC provides up to 4 UART units. On the phyBOARD-Segin, they are configured as follows:

RS232

Configuration of the UART interface can be done with stty. For example:

target$ stty -F /dev/ttyS3 115200 raw -echo

CAN FD

The phyBOARD-Segin provides one CAN interface supporting CAN FD. It is supported by the Linux standard CAN framework which builds upon the Linux network layer. Using this framework, the CAN interfaces behave like ordinary Linux network devices, with some additional features special to CAN. More information can be found in the Linux Kernel documentation:

https://www.kernel.org/doc/html/latest/networking/can.html

• To get information on can0, such as bit rate and error counters, type:

target$ ip -d -s link show can0

The information for can0 will look like this:

4: can0: <NOARP,UP,LOWER_UP,ECHO> mtu 16 qdisc pfifo_fast state UP mode DEFAULT group default qlen 10
    link/can  promiscuity 0  allmulti 0 minmtu 0 maxmtu 0 
    can state ERROR-ACTIVE (berr-counter tx 0 rx 0) restart-ms 0 
          bitrate 500000 sample-point 0.875
          tq 25 prop-seg 37 phase-seg1 32 phase-seg2 10 sjw 1 brp 1
          flexcan: tseg1 2..96 tseg2 2..32 sjw 1..16 brp 1..1024 brp_inc 1
          flexcan: dtseg1 2..39 dtseg2 2..8 dsjw 1..4 dbrp 1..1024 dbrp_inc 1
          clock 40000000 
          re-started bus-errors arbit-lost error-warn error-pass bus-off
          0          0          0          0          0          0         numtxqueues 1 numrxqueues 1 gso_max_size 65536 gso_max_segs 65535 tso_max_size 65536 tso_max_segs 65535 gro_max_size 65536 parentbus platform parentdev 443a0000.can 
    RX:  bytes packets errors dropped  missed   mcast           
             0       0      0       0       0       0 
    TX:  bytes packets errors dropped carrier collsns           
             0       0      0       0       0       0

The CAN configuration is done in the systemd configuration file/lib/systemd/network/can0.network. For a persistent change of (as an example, the default bitrates), change the configuration in the BSP under ./meta-ampliphy/recipes-core/systemd/systemd-conf/can0.networkin the root filesystem and rebuild the root filesystem. In this ALPHA1 release so far the configuration over systemd is only done for the can0 and the can1 interface.

[Match]
Name=can0

[CAN]
BitRate=500000

The bitrate can also be changed manually, for example, to make use of the flexible bitrate:

target$ ip link set can0 down
target$ ip link set can0 txqueuelen 10 up type can bitrate 500000 sample-point 0.75 dbitrate 4000000 dsample-point 0.8 fd on

You can send messages with cansend or receive messages with candump:

target$ cansend can0 123#45.67
target$ candump can0

To generate random CAN traffic for testing purposes, use cangen:

target$ cangen

cansend --help and candump --help provide help messages for further information on options and usage.

I²C Bus

The i.MX 93 contains two Multimaster fast-mode I²C modules. PHYTEC boards provide plenty of different I²C devices connected to the I²C modules of the i.MX 93. This chapter will describe the basic device usage of some of the I²C devices integrated into our phyBOARD-Segin.

RTC

RTCs can be accessed via /dev/rtc*. Because PHYTEC boards have often more than one RTC, there might be more than one RTC device file.

• To find the name of the RTC device, you can read its sysfs entry with:

target$ cat /sys/class/rtc/rtc*/name

• You will get, for example:

bbnsm_rtc 44440000.bbnsm:rtc
rtc-m41t80 1-0068

Date and time can be manipulated with the hwclock tool, using the -w (systohc) and -s (hctosys) options. To set the date, first, use the date mmddhhMMyyyy.sec and then run hwclock -w to store the new date into the RTC. For more information about this tool, refer to the manpage of hwclock.

target$ date 061513482023.26
target$ hwclock -w -f /dev/rtc0