Skip to content

Reprogramming & Booting the RZ V2L through eMMC, micro SD, and NFS mount

Jump to bottom
Lucas Keller edited this page Oct 11, 2023 · 13 revisions

Mastering RZBoardV2L Deployment: Understanding eMMC, Micro SD, and Network Boot!

Optimize your RZ/V2L deployment process while learning best practices

rzboard_v2l

Difficulty: Intermediate

Tutorial Time

  • Hands-on Estimate: 30 minutes per boot target

Table of Contents

Prerequisites

Before you begin, make sure you have the following hardware and software in place:

Hardware Requirements

Primary Components

  • RzBoard V2L
  • Deployment/Build Host
    • 64-bit Ubuntu 20.04 LTS

Peripherals

  • Common Peripherals
    • USB Mouse
    • USB Keyboard
    • USB-Serial adapter cable (I'm using PL2303TA)
    • 1x Ethernet cable
  • For Micro-SD Boot
    • 1x Micro-SD 32 GB
    • 1x micro-SD-USB adapter
  • For eMMC and/or NFS Boot
    • 1x Ethernet Cable

Repository Dependencies

We will be cloning the following repository later in the blog

Introduction

The RZ/V2L is a flexible AI on the edge device with several viable embedded linux boot configurations. It is an engineering decision to decide what boot configuration is most appropriate; this project covers general embedded linux booting details, boot configuration tradeoffs and considerations, and lastly, how to deploy and boot through eMMC, micro SD, and the network.

boot-configurations

The embedded linux boot process has gathered complexities over the years; but, this project will touch on the primary components relevant to RZBoard V2L. You may also find this project writeup generic enough to help with other embedded linux devices. Thankfully, building embedded linux for arm targets is heavily documented, and you may find resources like the yocto project or Arm Trusted Firmware documentation helpful.

In terms of engineering tradeoffs, there are many reasons why developers may favor one boot configuration over the others. This project will touch on the primary factors supporting and opposing eMMC, SD, and network boot configurations. Anecdotally, I've used all three boot configurations on embedded linux devices. As a hobbyist, I found myself often using SD cards (and replacing them as needed), but as a professional developer, I much preferred network boot for iterative development & eMMC for production.

Once the reader has an understanding of embedded linux booting and decides upon a boot configuration, the final sections of the project will cover how to use each configuration in practice.

Understanding Embedded Linux Booting

Pressing the power switch on the RZBoard V2L is activating an event sequence similar to other linux devices. boot-sequence

The boot process involves: bootloader startup, launching the kernel, and parsing the device tree binary (DTB) and root filesystem (rootfs). RZBoard V2L specifically uses UBoot, and the kernel/dtb/rootfs components of the build are managed by the various yocto layers present in the build process- read more here or here (src).

To summarize, the following table describes the role(s) and possible locations of the primary components of the RZBoard V2L boot process.

Name Description Location
Bootloader The lowest level hardware initializer. Reads and executes storage offsets to find components (like kernel for example), loads the kernel into RAM, and yields device control to the kernel. eMMC or QSPI flash
Kernel The core component of the linux operating system. Initializes and manages hardware resources like CPU, memory, drivers. Must be loaded into RAM before full system capabilities are unlocked. eMMC, micro SD, or TFTP server
DTB Hardware abstracted into a datastructure. This binary describes the system hardware in a generic manner for the kernel to consume. eMMC, micro SD, or TFTP server
Rootfs The operating system files and directories. Mounted by the kernel during the boot process. eMMC, micro SD, or NFS server

Now, review the boot configurations diagram below. boot-configurations

You can see the RzV2L Linux bootloader is common to the 3 boot configurations. To elaborate, the 3 bootloader files: image writer, Bl2 image, and FIP image are required to be flashed to RZBoard V2L before using any specific boot configuration. For micro SD and network booting, the bootloader must be flashed to QSPI; for eMMC booting, the bootloader must be flashed to eMMC. This is as simple as specifying a parameter in your RzBoard V2L flashing utility.

Now, you should understand the core difference between the three boot configurations is where the kernel, DTB, and rootfs are located. Next, I will cover some tradeoffs and considerations of the RZBoard V2L boot methods.

Tradeoffs and Considerations

Understanding the core difference between boot configurations, practical tradeoffs and considerations can be discussed. Specifically, I will speak to eMMC, micro SD, and network booting the RZBoard V2L; but, the details covered here will often be applicable to other embedded linux devices.

Topic eMMC micro SD Network
Biggest Pro(s) Sturdy, simple, and hard to tamper with Replacable, scalable, & mobile data storage Centralized storage, updates, & maintenance (can even automate)
Biggest Cons(s) Low flexibility/scaling Degradation over time (can be mitigated) Latency or network loss -> degraded performance
Longevity Heavy writing and reading will degrade performance & health Heavy writing and reading will degrade performance & health As robust as network & server(s) are (generally robust)
Boot Time Mostly constant, will degrade over time Mostly constant, will degrade over time Limited by network bandwidth
Deployment Ease Very easy, use FlashUtility Easy, use sd-card writer tool Moderately difficult setup & maintenance required
Dev. or Prod. Generally, prod. Either Either (makes dev iteration faster)
Maintenance Replace board Replace SD card Centralized maintenance, but have to maintain network health

In summary: eMMC and SD cards have similar pros/cons derived from hardware specs, while network boot tradeoffs are mostly determined by network capabilities.

So, when should you pick one boot configuration over the other? Here are some examples/use cases.

  • eMMC is strong for embedded devices that require little maintenance- think self checkout monitoring device.
  • Micro SD card booting might be more applicable if you plan to replace or swap SD cards often- think trail cam.
  • Network booting is very strong for development iteration & centralized maintenance, but maintaining the network comes with its own challenges. Think distributed camera system in a building/warehouse, or application development.

How do you use these methds in practice? Later sections of this project will cover the shared bootloader process and configuration-specific processes for eMMC, micro SD, and network booting.

The shared bootloader process

Common to eMMC, micro SD, and network booting, this section covers how to flash your RZBoard V2L with the three bootloader images:

Image File Name Description
Flash Image Writer Flash_Writer_SCIF_rzboard.mot Application loaded in to received bootloader images over serial and write to eMMC
BL2 Image bl2_bp-rzboard.srec Bootloader
FIP Image fip-rzboard.srec Bootloader, ARM TFA (Trusted Firmware-A) BL31, and u-boot in a combined image

Hardware Configuration

Firstly, the RZBoard hardware must be in a SCIF flash configuration.

  1. Power off the RZBoard
  2. Place the RZBoard into "SCIF download boot-mode" by setting:
    1. BOOT2=1 by strapping J19-pin1 J1-pin2
    2. BOOT1=0 by strapping SW1.1 = ON
    3. BOOT0=1 by removing the SD card from MicroSD slot
  3. Connect RZBoard & build host such that they can be on the same subnet. For this demonstration, I connected RZBoard directly to build host via ethernet. This is only technically needed for flashing the system image, but assuming this configuration now will make later steps easier.
  4. Connect the RZBoard with the build host via the USB-Serial cable. The fly leads will connect with the 4-pin debug UART header.

SCIF_setup

Software & Ubuntu Configuration

Additionally, you will need the flash-writer utility to send the data over the USB-serial cable. To download the flash writer and its related dependencies, run the following:

$ mkdir ~/rz_qt5 && cd ~/rz_qt5
$ git clone https://github.com/Avnet/rzboard_flash_util.git
$ cd rzboard_flash_util
$ pip3 install -r requirements.txt

The flash-writer tool makes a few assumptions (README):

  1. The images to be flashed are located in the directory of the flash writer rzboard_flash-util (with the original names output by bitbake). This can also be bypassed with parameters (see README)
  2. /dev/ttyUSB0 is used (check out the flash writer docs for overriding the default serial port)

Before running the flash-writer, you can verify your USB-Serial device is protected. I'm using a Prolific PL2303TA which shows up in lsusb like:

$ lsusb
...
Bus 001 Device 007: ID 067b:2303 Prolific Technology, Inc. PL2303 Serial Port
...

Gather the Files

Copy the bootloader files over to the target directory ~/rz_qt5/rzboard_flash_util. These commands assume you built according to the RZBoard V2L QT project. Otherwise, just manually drag the 3 bootloader files into ~/rz_qt5/rzboard_flash_util

$ cd ~/rz_qt5/yocto_rzboard/build/
$ cp tmp/deploy/images/rzboard/Flash_Writer_SCIF_rzboard.mot ~/rz_qt5/rzboard_flash_util/
$ cp tmp/deploy/images/rzboard/bl2_bp-rzboard.srec ~/rz_qt5/rzboard_flash_util/
$ cp tmp/deploy/images/rzboard/fip-rzboard.srec ~/rz_qt5/rzboard_flash_util/

Flashing

Before flashing, you must know if you want a eMMC, micro SD, or network boot configuration! If you plan to use micro SD or network booting, make sure to include the --qspi in your flash_rzboard.py command; but, If you want an eMMC boot, simply use the --bootloader parameter and eMMC flashing is assumed!

The next steps require power cycling, here is a reminder of where the power button is: power_button

When performing a --bootloader flash, follow the flash writer output. The general order of operations will be:

  1. Power down RZBoard, configure for SCIF download boot mode
  2. On build host, run $ python flash_util.py --bootloader from ~/rz_qt5/rzboard_flash_util (for eMMC)
  3. Power up RZBoard (Still in SCIF download boot mode)
  4. Let the flash_util.py script flash the flash writer, bl2, and FIP image.
  5. Wait for the Done flashing bootloader! flash log
  6. Power down the RZBoard, removing the BOOT2 flywire strapping J19-pin1 J1-pin2
  7. Power on the RZBoard

Because I just implemented the --qspi feature for the rzboard_flash_util, I'll showcase my usage of the utility in preparation for a micro SD boot.

$ python flash_rzboard.py --qspi --bootloader
Please power on board. Make sure boot2 is strapped.
Writing Flash Writer application.
Done writing Flash Writer application.
Clearing QSPI flash
Done clearing QSPI flash
Flashing bl2 image to QSPI
Done flashing bl2 image to QSPI
Flashing FIP image to QSPI
Done flashing FIP image to QSPI
Done flashing bootloader!

eMMC Deployment & Booting

This section will detail the final step of flashing the linux system image, assuming you've already completed the steps of The shared bootloader process section above.

Click to expand/collapse eMMC Deployment & Booting

Gather the File

This section depends upon one image file:

Image File Name Description
System Image avnet-core-image-rzboard.wic Contains the linux kernel, device tree (dtb), and root filesystem (rootfs) in a minimized format.

Copy the system image file over to the target directory ~/rz_qt5/rzboard_flash_util. These commands assume you built according to the RZBoard V2L QT project. Otherwise, just manually drag the system image file into ~/rz_qt5/rzboard_flash_util

$ cd ~/rz_qt5/yocto_rzboard/build/
$ cp tmp/deploy/images/rzboard/avnet-core-image-rzboard.wic ~/rz_qt5/rzboard_flash_util/

Lastly, flash the system image using --rootfs flash writer parameter. For --full or --rootfs, flash_util.py will try to automatically find the RZBoard IP address, unless you specify a static IP. For this demonstration, I preferred to use a static IP.

The next steps require power cycling, here is a reminder of where the power button is: power_button

When performing a --rootfs flash, follow the flash writer output. The general order of operations will be:

  1. Power down RZBoard, configure for SCIF download boot mode
  2. Exit SCIF download mode by removing the BOOT2 flywire strapping J19-pin1 J1-pin2. Leave BOOT1 and BOOT0 untouched.
  3. Give build host 192.168.1.X IP so it can share same subnet with RZBoard. Personally, I ran $ ifconfig eno1 192.168.1.88, as eno1 was the ethernet port connected directly to the RzBoard.
  4. On build host, run $ python flash_util.py --rootfs --static_ip 192.168.1.99 from ~/rz_qt5/rzboard_flash_util
  5. Wait for the Power on Board. Make sure boot2 strap is NOT on flash log
  6. Power on the RZBoard
  7. Wait for the Finished. Total time: X.Ys log before rebooting the RZBoard

NOTE: Use your prefered parameters/method, but know the RZBoard & build host must be on the same subnet. More information on the flashing utility can be found in the README

$ cd ~/rz_qt5/rzboard_flash_util/
$ python flash_rzboard.py --rootfs --static_ip 192.168.1.99
Power on board. Make sure boot2 strap is NOT on.
Waiting for device...
Setting static IP: 192.168.1.99
Putting device into fastboot mode
Device in fastboot mode
error: no response from target
< waiting for udp:192.168.1.99>
fastboot: verbose: Do flash rawimg /home/ljkeller/code/rzv2l/rzboard_flash_util/avnet-core-image-rzboard.wic
fastboot: verbose: target reported max-download-size of 117440512 bytes
Sending sparse 'rawimg' 1/27 (102256 KB)           OKAY [ 11.173s]
Writing 'rawimg'                                   OKAY [ 20.617s]
Sending sparse 'rawimg' 2/27 (114684 KB)           OKAY [ 12.525s]
Writing 'rawimg'                                   (bootloader) writing
OKAY [  9.997s]
Sending sparse 'rawimg' 3/27 (114684 KB)           OKAY [ 12.511s]
Writing 'rawimg'                                   (bootloader) writing
OKAY [  9.965s]
Sending sparse 'rawimg' 4/27 (114684 KB)           OKAY [ 12.522s]
Writing 'rawimg'                                   OKAY [ 10.126s]
Sending sparse 'rawimg' 5/27 (114684 KB)           OKAY [ 12.532s]
Writing 'rawimg'                                   (bootloader) writing
OKAY [  9.935s]
Sending sparse 'rawimg' 6/27 (114684 KB)           OKAY [ 13.524s]
Writing 'rawimg'                                   (bootloader) writing
OKAY [ 10.106s]
Sending sparse 'rawimg' 7/27 (114684 KB)           OKAY [ 12.520s]
Writing 'rawimg'                                   OKAY [  9.933s]
Sending sparse 'rawimg' 8/27 (114684 KB)           OKAY [ 12.543s]
Writing 'rawimg'                                   (bootloader) writing
OKAY [ 10.112s]
Sending sparse 'rawimg' 9/27 (114684 KB)           OKAY [ 13.457s]
Writing 'rawimg'                                   (bootloader) writing
OKAY [  9.931s]
Sending sparse 'rawimg' 10/27 (114684 KB)          OKAY [ 12.519s]
Writing 'rawimg'                                   OKAY [  9.924s]
Sending sparse 'rawimg' 11/27 (114684 KB)          OKAY [ 12.536s]
Writing 'rawimg'                                   (bootloader) writing
OKAY [ 10.106s]
Sending sparse 'rawimg' 12/27 (114684 KB)          OKAY [ 13.537s]
Writing 'rawimg'                                   (bootloader) writing
OKAY [  9.940s]
Sending sparse 'rawimg' 13/27 (114684 KB)          OKAY [ 12.527s]
Writing 'rawimg'                                   OKAY [  9.937s]
Sending sparse 'rawimg' 14/27 (114684 KB)          OKAY [ 12.523s]
Writing 'rawimg'                                   (bootloader) writing
OKAY [  9.925s]
Sending sparse 'rawimg' 15/27 (114684 KB)          OKAY [ 12.609s]
Writing 'rawimg'                                   (bootloader) writing
OKAY [  9.942s]
Sending sparse 'rawimg' 16/27 (114684 KB)          OKAY [ 12.524s]
Writing 'rawimg'                                   OKAY [ 15.702s]
Sending sparse 'rawimg' 17/27 (114684 KB)          OKAY [ 12.527s]
Writing 'rawimg'                                   (bootloader) writing
OKAY [  9.972s]
Sending sparse 'rawimg' 18/27 (113788 KB)          OKAY [ 12.409s]
Writing 'rawimg'                                   (bootloader) writing
OKAY [ 15.134s]
Sending sparse 'rawimg' 19/27 (114684 KB)          OKAY [ 12.531s]
Writing 'rawimg'                                   OKAY [  9.985s]
Sending sparse 'rawimg' 20/27 (114684 KB)          OKAY [ 12.529s]
Writing 'rawimg'                                   (bootloader) writing
OKAY [  9.960s]
Sending sparse 'rawimg' 21/27 (113976 KB)          OKAY [ 12.466s]
Writing 'rawimg'                                   (bootloader) writing
OKAY [  9.885s]
Sending sparse 'rawimg' 22/27 (114684 KB)          OKAY [ 12.532s]
Writing 'rawimg'                                   OKAY [  9.975s]
Sending sparse 'rawimg' 23/27 (114684 KB)          OKAY [ 12.525s]
Writing 'rawimg'                                   (bootloader) writing
OKAY [  9.932s]
Sending sparse 'rawimg' 24/27 (114684 KB)          OKAY [ 12.515s]
Writing 'rawimg'                                   (bootloader) writing
OKAY [  9.948s]
Sending sparse 'rawimg' 25/27 (114684 KB)          OKAY [ 12.514s]
Writing 'rawimg'                                   OKAY [  9.932s]
Sending sparse 'rawimg' 26/27 (114684 KB)          OKAY [ 12.172s]
Writing 'rawimg'                                   (bootloader) writing
OKAY [  9.925s]
Sending sparse 'rawimg' 27/27 (104524 KB)          OKAY [ 11.985s]
Writing 'rawimg'                                   (bootloader) writing
(bootloader) writing
(bootloader) writing
OKAY [ 73.463s]
Finished. Total time: 693.934s

Once this process has complete, you should be ready to launch!

Launching

Upon rebooting your rzboard, you should see the following U-Boot logs from your serial connection:

...
Importing environment from mmc0 ...
switch to partitions #0, OK
mmc0(part 0) is current device
... (kernel launch, etc...)

Enjoy!

micro SD Deployment & Booting

Booting from SD card requires a QSPI boot configuration, which looks like:

QSPI Configuration

This configuration will launch the QSPI bootloader, which should have been flashed according to the flashing the bootloader section.

Click to expand/collapse Network Deployment & Booting

TODO: UPDATE BELOW

...
Importing environment from mmc0 ...
switch to partitions #0, OK
mmc0(part 0) is current device
...

Network Deployment & Booting

Click to expand/collapse Network Deployment & Booting ## TODO: UPDATE BELOW ## Deploying to RzBoard V2L

Feedback and Contributions

We welcome feedback, bug reports, and contributions. If you encounter any issues or have suggestions for improvements, please feel free to open an issue or submit a pull request. Our support will be focused on the meta-rzboard repository.

Clone this wiki locally