sdcard.mk

# SPDX-License-Identifier: Apache-2.0
#
################################################################################
##
## Copyright 2024 Missing Link Electronics, Inc.
##
## Licensed under the Apache License, Version 2.0 (the "License");
## you may not use this file except in compliance with the License.
## You may obtain a copy of the License at
##
##     http://www.apache.org/licenses/LICENSE-2.0
##
## Unless required by applicable law or agreed to in writing, software
## distributed under the License is distributed on an "AS IS" BASIS,
## WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
## See the License for the specific language governing permissions and
## limitations under the License.
##
################################################################################
##
##  File Name      : sdcard.mk
##  Initial Author : Joachim Foerster
##                   <joachim.foerster@missinglinkelectronics.com>
##
################################################################################
##
##  File Summary   : SDCard related targets for petalinux.mk
##
################################################################################


# user arguments, mandatory, override needed (via local.mk or command line)

# arguments depending on Petalinux Project settings and hardware

# path to SDcard block device node on target board
BOARD_SD_DEV ?= /dev/unknown-sdcard
# password of sudo-capable non-root user, to login into target board; for
# username see BOARD_SSH_USER below
BOARD_SSH_PW ?= unknown-password

# arguments depending on Lab Environment settings

# DNS name or IP address of target board in lab environment
BOARD_NAME ?= unknown-board-dns-name

# DNS name or IP address of TFTP server in lab environment, to login via SSH
TFTPD_SSH_HOST ?= unknown-tftpd-dns-name
# directory on TFTP server in lab environment, to put boot files into
TFTPD_SSH_DIR ?= /unknown-tftpd-dir
# IP address of TFTP server in lab environment, for U-Boot script
TFTPD_ADDR ?= $(shell nslookup $(TFTPD_SSH_HOST) | grep -A 2 -e answer | grep -e ^Address: | cut -d " " -f 2)


# user arguments, optional, override possible (via local.mk or command line)

# SDCard partition sizes
SDCARD_PART1_SZ ?= 1G
SDCARD_PART2_SZ ?= 6G

# MAC address to set U-Boot environment variable "ethaddr" to before doing DHCP
# and TFTP, target "boot-rescue"
BOOT_RESCUE_UBOOT_FORCE_ETHADDR ?=
# U-Boot script snippet to run before doing DHCP and TFTP, target "boot-rescue"
BOOT_RESCUE_UBOOT_SCR_PRE ?=

# arguments depending on Petalinux Project settings and hardware

# sudo-capable non-root user name, to login into target board
BOARD_SSH_USER ?= petalinux
# ssh (client) options, for login into target board
BOARD_SSH_OPT ?= -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null

# path to compressed root filesystem archive
ROOTFS_TAR ?= $(IMAGE_DIR)/rootfs.tar.gz
# path to uncompressed output of "petalinux-package --wic"
SDCARD_IMG_UNCOMPR ?= $(IMAGE_DIR)/petalinux-sdimage.wic
# compression type as file extension and path to compressed output of
# "petalinux-package --wic"
SDCARD_IMG_COMPR_EXT ?= xz
SDCARD_IMG ?= $(SDCARD_IMG_UNCOMPR).$(SDCARD_IMG_COMPR_EXT)


################################################################################


CONFIG_SUBSYSTEM_ROOTFS_INITRD = \
	$(shell sed -n -e 's/CONFIG_SUBSYSTEM_ROOTFS_INITRD=y/y/p' \
		project-spec/configs/config)
CONFIG_SUBSYSTEM_ROOTFS_EXT4 = \
	$(shell sed -n -e 's/CONFIG_SUBSYSTEM_ROOTFS_EXT4=y/y/p' \
		project-spec/configs/config)
CONFIG_SYSTEM_VERSAL = \
	$(shell sed -n -e 's/CONFIG_SYSTEM_VERSAL=y/y/p' \
		project-spec/configs/config)
CONFIG_SYSTEM_ZYNQMP = \
	$(shell sed -n -e 's/CONFIG_SYSTEM_ZYNQMP=y/y/p' \
		project-spec/configs/config)


# package-sdcard: generate SDCard image using "petalinux-package --wic"

ifneq ($(CONFIG_SUBSYSTEM_ROOTFS_INITRD),)
# NOTE: (PetaLinux v2024.1)
#       Using option -w / --wks <wks_file> with "petalinux-package --wic" does
#       NOT seem to _always_ work. It may fail with some Python problem "list
#       index out of range". Thus we cannot specify a custom partitioning scheme
#       (.wks file) and have to let the tool create a 2nd partition, ext4
#       formatted, labeled "root". However we can handover an empty .tar.gz file
#       to be extracted into that 2nd partition - instead of the default
#       (images/linux/rootfs.tar.gz).

EMPTY_TAR ?= build/psmake/empty.tar.gz

$(EMPTY_TAR):
	tmpdir=$$(mktemp -d) && currentdir=$$(pwd) && \
		env -C $$tmpdir/ tar czvf $$currentdir/$@ . >/dev/null && \
		rmdir $$tmpdir

_ROOTFS_TAR := $(EMPTY_TAR)
else
ifneq ($(CONFIG_SUBSYSTEM_ROOTFS_EXT4),)
_ROOTFS_TAR := $(ROOTFS_TAR)
else
$(error Not generating an SDcard image due to unknown rootfs mode)
endif
endif

BOOT_FILES_LOADER ?= $(BOOT_BIN) $(IMAGE_DIR)/boot.scr
BOOT_FILES_SYSTEM ?= $(IMAGE)
BOOT_FILES_EXTRA ?=

BOOT_FILES ?= \
	$(BOOT_FILES_LOADER) \
	$(BOOT_FILES_SYSTEM) \
	$(BOOT_FILES_EXTRA)

build/boot_files:
	# make selected boot files "reside" in images/linux/ by symlink'ing if
	# necessary; "petalinux-package --wic" expects to find them there
	boot_files=; \
	for bootfile in $(BOOT_FILES); do \
		if [ "$$(realpath $$bootfile)" != "$$(realpath images/linux)/$$(basename $$bootfile)" ]; then \
			ln -sf $$(realpath $$bootfile) images/linux/; \
		fi; \
		boot_files="$$boot_files $$(basename $$bootfile)"; \
	done; \
	@echo "info: boot files for 1st partition: $$boot_files"; \
	echo "$$boot_files" >$@
.PHONY: build/boot_files

# for PetaLinux <= v2023.1, only
build/rootfs.wks:
	echo "part /boot --source bootimg-partition --ondisk mmcblk0 --fstype=vfat --label boot --active --align 4 --fixed-size $(SDCARD_PART1_SZ)" >$@
	echo "part /     --source rootfs            --ondisk mmcblk0 --fstype=ext4 --label root          --align 4 --fixed-size $(SDCARD_PART2_SZ)" >>$@
.PHONY: build/rootfs.wks

# arguments for "petalinux-package --wic" call
PACKAGE_SDCARD_WIC_ARGS_PRE =
PACKAGE_SDCARD_WIC_ARGS_POST =
ifeq ($(shell expr $(subst .,,$(PETALINUX_VER)) "<=" 20231),1)
# --size is not available in PetaLinux <= v2023.1
PACKAGE_SDCARD_WIC_ARGS_PRE += --wks build/rootfs.wks
else
# --size is available in PetaLinux >= v2023.2
PACKAGE_SDCARD_WIC_ARGS_POST += --size $(SDCARD_PART1_SZ),$(SDCARD_PART2_SZ)
endif

$(SDCARD_IMG_UNCOMPR): $(_ROOTFS_TAR) build/boot_files build/rootfs.wks
	petalinux-package --wic \
		$(PACKAGE_SDCARD_WIC_ARGS_PRE) \
		--bootfiles "$(shell cat build/boot_files)" \
		--rootfs-file $(_ROOTFS_TAR) \
		$(PACKAGE_SDCARD_WIC_ARGS_POST)

	# WORKAROUND: revert unnecessary modification by "petalinx-package --wic"
	sed -i -e '/^\s*IMAGE_BOOT_FILES/d' project-spec/meta-user/conf/petalinuxbsp.conf

	@echo ""
	@echo "info: Generated build/rootfs.wks:"
	@cat build/rootfs.wks

	@echo ""
	@echo "info: Generated SDcard image:"
	@echo "info:   Size: $$(($$(stat -c %s $@) / 1024 / 1024)) MiB"
	@echo "info:   Partition table:"
	@if which fdisk >/dev/null; then \
		fdisk -l $@ | sed -e 's/^/\t/'; \
	else \
		file $@ | sed -e 's/^\([^:]*\): /\t/' -e 's/;/\n\t/g'; \
	fi
.PHONY: $(SDCARD_IMG_UNCOMPR)

PACKAGE_SDCARD_COMPR_CMDLINE = build/psmake/package-sdcard-zip-cmdline
$(PACKAGE_SDCARD_COMPR_CMDLINE):
	@case "$(SDCARD_IMG_COMPR_EXT)" in \
	gz) cmdline="gzip -c -9" ;; \
	bz2) cmdline="bzip2 -c -9" ;; \
	xz) cmdline="xz -c -3" ;; \
	zstd) cmdline="zstd -c -3" ;; \
	*) echo "error: unsupported file extension \"$(SDCARD_IMG_COMPR_EXT)\" for compression" >&2; exit 1; \
	esac; \
	echo "$$cmdline" >$@
.PHONY: $(PACKAGE_SDCARD_COMPR_CMDLINE)

$(SDCARD_IMG): $(SDCARD_IMG_UNCOMPR) $(PACKAGE_SDCARD_COMPR_CMDLINE)
	@echo ""
	@echo "info: Compressing generated SDcard image"
	$$(cat $(PACKAGE_SDCARD_COMPR_CMDLINE)) $< >$@

package-sdcard: $(SDCARD_IMG)


ifeq ($(CONFIG_SUBSYSTEM_ROOTFS_INITRD),y)

# boot-rescue: boot board via JTAG (BOOT.BIN) and TFTP (Image,
#              rootfs.cpio.gz.u-boot, boot.scr)
#
# NOTE: Works for Petalinux projects with initramfs-based rootfs, only!
#
# steps:
#
# - Generate a custom boot.scr, which uses U-Boot's TFTP client to fetch boot
#   files (see above) and (re-)invoke U-Boot "boot" command
#
# - Generate XSDB script to download that generated custom boot.scr to
#   0x20000000, which is U-Boot's built-in default to check for a U-Boot script -
#   especially as a first step when in JTAG boot mode.
#
# - Invoking U-Boot's "boot" command (again) from the custom boot.scr after
#   having loaded images/linux/{Image,rootfs.cpio.gz.u-boot,boot.scr} via TFTP
#   re-enters the JTAG mode boot process, which again checks 0x20000000 for a
#   U-Boot script and finds the images/linux/boot.scr this time.
#
# - PetaLinux's images/linux/boot.scr assumes Image and rootfs.cpio.gz.u-boot
#   are at addresses 0x00200000 and 0x04000000 by default. And it assume
#   system.dtb to be at 0x00001000, which is placed there by loading
#   images/linux/BOOT.BIN (Yes, BOOT.BIN by default comprises the device tree).

BOOT_RESCUE_UBOOT_SRC = build/psmake/boot-rescue.txt
BOOT_RESCUE_UBOOT_UIMAGE = build/psmake/boot-rescue.scr
BOOT_RESCUE_UBOOT_SCR_LOAD = \
	dhcp 0x00200000 $(TFTPD_ADDR):$(USER)/$(BOARD_NAME)/Image; \
	tftpboot 0x04000000 $(TFTPD_ADDR):$(USER)/$(BOARD_NAME)/rootfs.cpio.gz.u-boot; \
	tftpboot 0x20000000 $(TFTPD_ADDR):$(USER)/$(BOARD_NAME)/boot.scr
$(BOOT_RESCUE_UBOOT_SRC):
	truncate -s 0 $@
ifneq ($(BOOT_RESCUE_UBOOT_FORCE_ETHADDR),)
	echo "echo \"Force setting ethaddr=$(BOOT_RESCUE_UBOOT_FORCE_ETHADDR)\"" >>$@
	echo "env delete -f ethaddr" >>$@
	echo "setenv ethaddr $(BOOT_RESCUE_UBOOT_FORCE_ETHADDR)" >>$@
endif
ifneq ($(BOOT_RESCUE_UBOOT_SCR_PRE),)
	echo "$(BOOT_RESCUE_UBOOT_SCR_PRE)" >>$@
endif
	echo "$(BOOT_RESCUE_UBOOT_SCR_LOAD)" >>$@
ifneq ($(BOOT_RESCUE_UBOOT_SCR_LOAD_POST),)
	echo "$(BOOT_RESCUE_UBOOT_SCR_POST)" >>$@
endif
	echo "boot" >>$@
$(BOOT_RESCUE_UBOOT_UIMAGE): $(BOOT_RESCUE_UBOOT_SRC)
	mkimage -A arm -T script -C none -n "Boot script" -d $< $@
.PHONY: $(BOOT_RESCUE_UBOOT_SRC) $(BOOT_RESCUE_UBOOT_UIMAGE)

BOOT_RESCUE_XSDB = build/psmake/boot-rescue.tcl
BOOT_RESCUE_XSDB_SCR = \
	connect -url $(HW_SERVER_URL);
ifeq ($(CONFIG_SYSTEM_VERSAL),y)
BOOT_RESCUE_XSDB_SCR += \
	puts \"info: Load PL/PS BOOT.BIN: $(IMAGE_DIR)/BOOT.BIN\"; \
	targets -set -filter {name =~ \"Versal *\"}; \
	device program $(IMAGE_DIR)/BOOT.BIN; \
	stop;
else
ifeq ($(CONFIG_SYSTEM_ZYNQMP),y)
# NOTE: The following TCL script has been derived from the verbose output of
#       PetaLinux' command "petalinux-boot jtag" (v2024.1).
BOOT_RESCUE_XSDB_SCR += \
	\
	puts \"info: Load PL bitstream: $(BIT)\"; \
	fpga \"$(BIT)\"; \
	\
	puts \"info: Load and run PS PMU firmware: $(PMUFW)\"; \
	targets -set -nocase -filter {name =~ \"*PSU*\"}; \
	mask_write 0xffca0038 0x1c0 0x1c0; \
	targets -set -nocase -filter {name =~ \"*MicroBlaze PMU*\"}; \
	if { [string first \"Stopped\" [state]] != 0 } { \
		stop; \
	}; \
	dow \"$(PMUFW)\"; \
	con; \
	\
	puts \"info: Load and run PS FSBL: $(FSBL)\"; \
	targets -set -nocase -filter {name =~ \"*A53*\#0\"}; \
	rst -processor -clear-registers; \
	source project-spec/hw-description/psu_init.tcl; \
	dow \"$(FSBL)\"; \
	puts \"info: Run PS A53\#0 for 3 sec\"; \
	con; \
	after 3000; \
	stop; \
	puts \"info: Stopped PS A53\#0 after running for 3 sec\"; \
	psu_ps_pl_isolation_removal; psu_ps_pl_reset_config; \
	\
	puts \"info: Load PS devicetree: $(SYSTEM_DTB)\"; \
	dow -data \"$(SYSTEM_DTB)\" 0x100000; \
	puts \"info: Load PS U-Boot: $(UBOOT)\"; \
	dow \"$(UBOOT)\"; \
	puts \"info: Load PS ARM Trusted Firmware: $(ATF)\"; \
	dow \"$(ATF)\";
else
BOOT_RESCUE_XSDB_SCR += \
	puts stderr "error: Type of system not supported!"; \
	exit;
endif
endif
BOOT_RESCUE_XSDB_SCR += \
	puts \"info: Load PS rescue boot.scr: $(BOOT_RESCUE_UBOOT_UIMAGE)\"; \
	dow -data -force $(BOOT_RESCUE_UBOOT_UIMAGE) 0x20000000; \
	puts \"info: Run PS\"; \
	con; \
	disconnect; \
	exit;
$(BOOT_RESCUE_XSDB): $(BOOT_RESCUE_UBOOT_UIMAGE)
	echo "$(BOOT_RESCUE_XSDB_SCR)" >$@
.PHONY: $(BOOT_RESCUE_XSDB)

boot-rescue: reset-jtag $(BOOT_RESCUE_XSDB)
	ssh $(TFTPD_SSH_HOST) "mkdir -p $(TFTPD_SSH_DIR)/$(USER)/$(BOARD_NAME)"
	scp -rp $(IMAGE_DIR)/{BOOT.BIN,Image,rootfs.cpio.gz.u-boot,boot.scr} \
		$(TFTPD_SSH_HOST):$(TFTPD_SSH_DIR)/$(USER)/$(BOARD_NAME)/
	$(XSDB) $(BOOT_RESCUE_XSDB)

endif


# flash-sdcard-rescue: flash SDCard via initramfs-based system (==
#                             "rescue" system, rootfs not on SDCard), which has
#                             already been booted before calling this target
#
# NOTE: For now, this is using SSH to connect to the target board. Further
#       methods might be added later (labgrid).
#
# NOTE: Assumes a initramfs-based system is running on the target board, which
#       has sudo installed and a sudo-capable user ($(BOARD_SSH_OPT)).
#
# steps:
#
# - (optional) Use ssh-copy-id to copy the user's SSH public key to the board to
#   avoid having to enter the password for every command.
#
# - Umount any SDcard partition on the board and grant write-access to SDcard to
#   any user.
#
# - Pipe SDcard image over SSH onto SDcard.
#
# - Umount any SDcard partition in case systemd/udev did mount it again automatically.
#
# - (optional) Mount first partition (assume it exists and is mountable!) and
#   show MD5SUM of all (boot) files

# shell scripts executed on target board
FLASH_SDCARD_RESCUE_SCR_UMOUNT = \
	for dev in \$$(mount | grep -e '^$(BOARD_SD_DEV)' | awk '{ print \$$1 }'); do \
		echo \"info: \$$dev is mounted, trying to unmount ...\"; \
		echo \"$(BOARD_SSH_PW)\" | sudo -S umount \$$dev; \
		echo -e \"\ninfo: \$$dev unmounted\"; \
	done; \
	sync; sync; sync;
FLASH_SDCARD_RESCUE_SCR_PRE = \
	$(FLASH_SDCARD_RESCUE_SCR_UMOUNT) \
	echo \"$(BOARD_SSH_PW)\" | sudo -S chmod a+w $(BOARD_SD_DEV);
FLASH_SDCARD_RESCUE_SCR_POST = \
	$(FLASH_SDCARD_RESCUE_SCR_UMOUNT)
FLASH_SDCARD_RESCUE_SCR_P1SHOWMD5 = \
	echo \"$(BOARD_SSH_PW)\" | sudo -S mount $(BOARD_SD_DEV)p1 /mnt; \
	echo \"Modification Timestamp:\"; \
	echo \"$(BOARD_SSH_PW)\" | sudo -S find /mnt/ -mindepth 1 -maxdepth 1 -type f -exec stat -c \"%y  %n\" \"{}\" \";\"; \
	echo \"MD5SUMs:\"; \
	echo \"$(BOARD_SSH_PW)\" | sudo -S find /mnt/ -mindepth 1 -maxdepth 1 -type f -exec md5sum \"{}\" \";\"; \
	echo \"$(BOARD_SSH_PW)\" | sudo -S umount /mnt;

# shell scripts executed on host
# to remove certain output strings (sudo) lines (ssh) to make output better
# readable
FLASH_SDCARD_RESCUE_SCR_PRETTIFY = \
	sed \
		-e 's/^Password: //' \
		-e '/^Warning: Permanently added/d'

FLASH_SDCARD_RESCUE_UNCOMPR_CMDLINE = build/psmake/flash-sdcard-rescue-uncompr-cmdline
$(FLASH_SDCARD_RESCUE_UNCOMPR_CMDLINE):
	@mime_type="$$(file -L -b --mime-type $(SDCARD_IMG))"; \
	case "$$mime_type" in \
	"application/gzip") cmdline="gunzip -c" ;; \
	"application/x-bzip2") cmdline="bunzip2 -c" ;; \
	"application/x-xz") cmdline="unxz -c" ;; \
	"application/zstd") cmdline="unzstd -c" ;; \
	*) cmdline="cat" ;; \
	esac; \
	echo "$$cmdline -c" >$@
.PHONY: $(FLASH_SDCARD_RESCUE_UNCOMPR_CMDLINE)

flash-sdcard-rescue: $(FLASH_SDCARD_RESCUE_UNCOMPR_CMDLINE)
	-sshpass -p$(BOARD_SSH_PW) ssh-copy-id $(BOARD_SSH_OPT) $(BOARD_SSH_USER)@$(BOARD_NAME)

	@echo ""
	@echo "info: prepare target board's $(BOARD_SD_DEV) for writing:"
	@echo ""
	ssh $(BOARD_SSH_OPT) $(BOARD_SSH_USER)@$(BOARD_NAME) "$(FLASH_SDCARD_RESCUE_SCR_PRE)" 2>&1 | \
		$(FLASH_SDCARD_RESCUE_SCR_PRETTIFY)

	@echo ""
	@echo "info: writing $(SDCARD_IMG) image to target board's $(BOARD_SD_DEV):"
	@echo ""
	time $$(cat $(FLASH_SDCARD_RESCUE_UNCOMPR_CMDLINE)) $(SDCARD_IMG) | dd status=progress | gzip -9 | \
		ssh $(BOARD_SSH_OPT) $(BOARD_SSH_USER)@$(BOARD_NAME) "gunzip -c >$(BOARD_SD_DEV)"
	ssh $(BOARD_SSH_OPT) $(BOARD_SSH_USER)@$(BOARD_NAME) "$(FLASH_SDCARD_RESCUE_SCR_POST)" 2>&1 | \
		$(FLASH_SDCARD_RESCUE_SCR_PRETTIFY)

	@echo ""
	@echo ""
	@echo ""
	@echo "info: boot files on first partition on target board's SDcard after flashing:"
	@echo ""
	-@ssh $(BOARD_SSH_OPT) $(BOARD_SSH_USER)@$(BOARD_NAME) "$(FLASH_SDCARD_RESCUE_SCR_P1SHOWMD5)" 2>&1 | \
		$(FLASH_SDCARD_RESCUE_SCR_PRETTIFY)

	@echo ""
	@echo ""
	@echo "info: boot files on in $(IMAGE_DIR) to compare with the output above:"
	@echo ""
	@echo -e "Modification Timestamp\t\t\tMD5SUM\t\t\t\t  Filename:"
	@find $(IMAGE_DIR) -mindepth 1 -maxdepth 1 -type f -exec sh -c 'echo -e "$$(stat -c %y "{}")\t$$(md5sum "{}")"' ";"
.PHONY: flash-sdcard-rescue