Setting Up Your Host PC

The build system is currently supported on host PCs running Ubuntu 20.04 LTS 64-bit. For setting up your host PC, please see the Setting Up Your Host PC page.

Fetching the Sources

The source is fully contained in the Analog Devices Linux for ADSP repositories.

To install the sources:

mkdir ~/adsp-sc584-ezkit-yocto-build
cd ~/adsp-sc584-ezkit-yocto-build
mkdir bin
curl http://commondatastorage.googleapis.com/git-repo-downloads/repo > ./bin/repo
chmod a+x ./bin/repo
./bin/repo init \
   -u https://github.com/analogdevicesinc/lnxdsp-repo-manifest.git \
   -b release/yocto-3.1.0 \
   -m release-yocto-3.1.0.xml
./bin/repo sync

Building the Image

Preparing the buildtool

Yocto requires the environment to be configured before building is possible. A setup-environment script in the adsp-sc584-ezkit-yocto-build folder contains all the required environment settings for your build target. Source the setup script for your board:

source setup-environment -m adsp-sc584-ezkit

Sourcing the script will configure your build environment and create a build folder along with a local build configuration file. See the Yocto Manual for further details.

Note

Note that the build environment needs to be sourced once only before building. If later working in a different terminal, the setup-environment script should be sourced again. If sourcing the setup-environment script is done without specifying the machine, Yocto will reuse the previous configuration settings and retain any changes made to the files in the conf folder

Building the example

You can build two different versions of the root file system; minimal and full. To build the example images invoke bitbake from within the build directory created previously.

bitbake adsp-sc5xx-minimal
bitbake adsp-sc5xx-full

When the build completes you will see a warning that the ELF binary has relocations in .text. It is OK to ignore this warning

Note

Building a Linux distribution with Yocto is a significantly demanding process, both in CPU and network usage. A full build from scratch is estimated to take around 170 minutes for an 11th Gen Intel Core i5-11500T with 16 GB of RAM and a stable, fast Internet connection. This estimate can go up significantly for a poorer Internet connection or CPU resources, so set aside plenty of time for a clean build.

Building the SDK

The SDK will provide you with the cross toolchain needed to develop application for the target board, alongside various miscellaneous tools. Notably, it will provide you with OpenOCD and GDB, which you can use to run and flash U-Boot on the board.

The SDK can be built for the adsp-sc5xx-minimal image or the adsp-sc5xx-full image. To build the SDK for the adsp-sc5xx-minimal image invoke bitbake from within the build directory created previously.

bitbake adsp-sc5xx-minimal -c populate_sdk

or for the adsp-sc5xx-full image

bitbake adsp-sc5xx-full -c populate_sdk

When the build has completed you will find a set of files in the <BUILD_DIR>/tmp/deploy/sdk directory. For example, the minimal image on ADSP-SC584:

ls tmp/deploy/sdk

adi-distro-glibc-glibc-x86_64-adsp-sc5xx-minimal-cortexa5t2hf-neon-adsp-sc584-ezkit-toolchain-3.1.0.host.manifest
adi-distro-glibc-glibc-x86_64-adsp-sc5xx-minimal-cortexa5t2hf-neon-adsp-sc584-ezkit-toolchain-3.1.0.sh
adi-distro-glibc-glibc-x86_64-adsp-sc5xx-minimal-cortexa5t2hf-neon-adsp-sc584-ezkit-toolchain-3.1.0.target.manifest
adi-distro-glibc-glibc-x86_64-adsp-sc5xx-minimal-cortexa5t2hf-neon-adsp-sc584-ezkit-toolchain-3.1.0.testdata.json

The adi-distro-glibc-glibc-x86_64-adsp-sc5xx-minimal-cortexa5t2hf-neon-adsp-sc584-ezkit-toolchain-3.1.0.sh is a self-extracting archive containing the SDK.

Installing the SDK

Invoke the self-extracting archive. It will default to installing to /opt/adi-distro-glibc/3.1.0 but gives you the option to select your own install folder during the installation. For the minimal image on ADSP-SC584

./adi-distro-glibc-glibc-x86_64-adsp-sc5xx-minimal-cortexa5t2hf-neon-adsp-sc584-ezkit-toolchain-3.1.0.sh
Analog Devices Inc Reference Distro (glibc) SDK installer version 3.1.0
=======================================================================
Enter target directory for SDK (default: /opt/adi-distro-glibc/3.1.0):
You are about to install the SDK to "/opt/adi-distro-glibc/3.1.0". Proceed [Y/n]?
Extracting SDK....................................................................................................................done
Setting it up...done
SDK has been successfully set up and is ready to be used.
Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g.
 $ . /opt/adi-distro-glibc/3.1.0/environment-setup-cortexa5t2hf-neon-adi_glibc-linux

Your SDK is now installed.

Setup the hardware

Before installing the software on to the development board, ensure that the following cables are connected:

https://github.com/analogdevicesinc/lnxdsp-adi-meta/assets/110021710/sc584-hardware.png

Board connected to network via ethernet cable using J13 connector.
Board connected to host PC using USB micro cable, connected to USB/UART port on the development board
Board connected to the ICE 1000 or ICE 2000 via the DEBUG port on the board
ICE is also connected to host PC via USB mini cable
The BOOT MODE selector should be turned to “0”.

Transfer, run and flash U-Boot on the board for the first time

Note

It’s always good practice to erase the contents of /tftpboot/ before running and/or flashing a new build of U-Boot or Linux. You can do so by executing rm /tftpboot/* on your host PC before proceeding

Transfer and run U-Boot on RAM

Copy the U-Boot binary & loader files to the tftp directory:

cp tmp/deploy/images/adsp-sc584-ezkit/u-boot-proper-sc584-ezkit.elf /tftpboot/
cp tmp/deploy/images/adsp-sc584-ezkit/u-boot-spl-sc584-ezkit.elf /tftpboot/
cp tmp/deploy/images/adsp-sc584-ezkit/stage1-boot.ldr /tftpboot/
cp tmp/deploy/images/adsp-sc584-ezkit/stage2-boot.ldr /tftpboot/

The console output from U-Boot and later on Linux will appear on the USB serial port configured in minicom earlier so open up minicom.

Terminal1: minicom

sudo minicom

In a separate console launch OpenOCD and connect to the development board.

Terminal2: OpenOCD

sdk_usr=/opt/adi-distro-glibc/3.1.0/sysroots/x86_64-adi_glibc_sdk-linux/usr/
$sdk_usr/bin/openocd -f $sdk_usr/share/openocd/scripts/interface/<ICE>.cfg -f $sdk_usr/share/openocd/scripts/target/adspsc58x.cfg

Where <ICE> should be replaced with ice1000 or ice2000 depending on your hardware. When successful you should see a message similar to the console output below

Terminal2: OpenOCD

Open On-Chip Debugger 0.10.0...

In a third console window launch GDB and type target extended-remote :3333. This will make GDB to connect to the gdbserver on the local host using port 3333. Then, load the U-Boot SPL into RAM by typing load. Hit Ctrl+C to interrupt thereafter.

Terminal3: GDB

cd /tftpboot
/opt/adi-distro-glibc/3.1.0/sysroots/x86_64-adi_glibc_sdk-linux/usr/bin/arm-adi_glibc-linux-gnueabi/arm-adi_glibc-linux-gnueabi-gdb u-boot-spl-sc584-ezkit.elf
...
(gdb) target extended-remote :3333
Remote debugging using :3333
0x000000000000352c in ?? ()
(gdb) load
Loading sections... Transfer rate: 29 KB/sec
(gdb) c
Continuing.
^C
Program received signal SIGINT, Interrupt.

You will see a message on Terminal 1 running minicom, informing you that you can now load U-Boot Proper

Terminal1: minicom

U-Boot SPL 2020.10
ADI Boot Mode: 0x0 (JTAG/BOOTROM)
SPL execution has completed.

Now, load U-Boot Proper into RAM.

Terminal3: GDB

(gdb) load u-boot-proper-sc584-ezkit.elf
Loading sections... Transfer rate: 28 KB/sec
(gdb) c
Continuing.

At this point U-Boot will now be running in RAM on your target board. You should see U-Boot booting in the minicom console (Terminal 1). Press a key to interrupt the boot process before the countdown terminates:

Terminal1: minicom

U-Boot 2020.10
CPU: ADSP ADSP-SC584
Hit any key to stop autoboot: 0
=>

Flash U-Boot to SPI Flash

In the U-Boot console, set the IP address of the Linux PC that hosts the U-Boot loader files (stage1-boot.ldr & stage2-boot.ldr) on TFTP.

Terminal1: minicom

=> setenv tftpserverip <SERVERIP>

Note

To find the IP address of your host Linux PC you can issue the ip addr command from the shell or console.

If your network supports DHCP, run:

=> dhcp

If your network does NOT support DHCP, in the U-Boot console configure the board IP address you want the board to be assigned with (<IPADDR>) and remove “dhcp;” from the “init_ethernet” command:

=> setenv ipaddr <IPADDR>
=> edit init_ethernet
=> edit: mii info; <remove "dhcp;" from here>; setenv serverip ${tftpserverip};
=> saveenv

i.e. init_ethernet should now be init_ethernet=mii info; setenv serverip ${tftpserverip};, where prior to this change it was init_ethernet=mii info; dhcp; setenv serverip ${tftpserverip};

Note

If flashing a board that had been previously programmed, it’s good to erase the whole flash before as sometimes previous U-Boot installations might leave remnants. You can do that by typing => run erase_spi on the U-Boot prompt before proceeding to the following instructions

Next, run the U-Boot update command to copy the U-Boot loader files from the host PC to the target board, and write it into flash:

=> run update_spi_uboot_only

You will see an output similar to the one below:

=> run update_spi_uboot_only
Speed: 1000, full duplex
TFTP from server...
Bytes transferred = 115008 (1c140 hex)
SF: 115008 bytes @ 0x0 Written: OK

In order to store the tftpserverip and the DHCP or otherwise assigned IP address of the board and have them available on next boot, you can run the following command:

=> saveenv
Saving Environment to SPIFlash... Erasing SPI flash...Writing to SPI flash...done
OK

At this point the U-Boot binary is stored in flash. You can now disconnect the ICE-1000 or ICE-2000 from the development board and make sure to switch the BMODE to position 1. You will only need to reconnect this if your board fails to boot and you need to re-follow these instructions.

Booting Linux

Network Booting

In order to boot Linux via the network, the TFTP server should be setup as indicated in the Setting Up Your Host PC page, and a copy of the fitImage should be copied into the /tftpboot directory.

cp tmp/deploy/images/adsp-sc584-ezkit/fitImage /tftpboot/

NFS Boot

In order to boot Linux via NFS, the NFS server should be setup as indicated in Setting Up Your Host PC: Configure NFS Server.

The root filesystem should then be copied to /romfs.

sudo tar -xf tmp/deploy/images/adsp-sc584-ezkit/adsp-sc5xx-full-adsp-sc584-ezkit.tar.xz -C /romfs

Next, on the target, from u-boot, run the following command:

=> run nfsboot
......
......
Starting services...
Analog Devices Yocto Distribution
login: root
Password: adi

Booting Linux Using SD Card

SD card boot instructions here…

Booting Linux from USB Mass Storage

Formatting the USB storage device

The first step is to format the USB stick to a format that U-Boot supports.

To do this, follow the commands below. The example code in this section assumes that the USB device is reported to be /dev/sdb. Ensure that you change these commands to use your device.

Note

You can use sudo fdisk -l to list the available devices and partitions, in order to locate the USB device.

sudo fdisk /dev/sdb
/* Create primary partition 1, 256M size*/
Command (m for help): n
Select (default p): p
Partition number (1-4, default 1): 1
First sector (2048-3887103, default 2048): PRESS ENTER
Last sector, +sectors or +size{K,M,G} (2048-3887103, default 3887103): PRESS ENTER

/* Save partition */
Command (m for help): w

Now that the storage device is partitioned, you need to format it to ext4:

sudo mkfs.ext4 /dev/sdb1

Writing the Kernel and rootFS to the USB storage device

Mount the device to a directory of your liking in your host machine (in the example, /mnt), and run the following commands which will uncompress the root file system and then store the kernel image under /boot inside it.

sudo mkdir /mnt
sudo mount -t ext4 /dev/sdb1 /mnt
sudo mkdir /mnt/boot
sudo tar -xf tmp/deploy/images/adsp-sc584-ezkit/adsp-sc5xx-minimal-adsp-sc584-ezkit.tar.xz -C /mnt
sudo cp tmp/deploy/images/adsp-sc584-ezkit/fitImage /mnt/boot/
sudo umount /mnt

Booting from the USB storage device

Now, on U-Boot, set the following environment variables:

=> setenv usbargs 'setenv bootargs root=/dev/sda1 rw rootfstype=ext4 rootwait earlycon=adi_uart,0x31003000 console=ttySC0,115200'
=> setenv usbload 'ext4load usb 0 ${loadaddr} /boot/${imagefile};'
=> setenv usbboot 'usb start; run usbload; run usbargs; bootm ${loadaddr};'

And type to boot

=> run usbboot

Now the rootfs is set to be your USB storage device, and the amount of space is the size of the partition created earlier on the device.