Merge branch 'next'

Merge the outstanding changes from the 'next' branch to master.
author: Tom Rini <[email protected]> 2025-10-06 13:20:24 -0600
committer: Tom Rini <[email protected]> 2025-10-06 13:20:24 -0600
commit: 0eaa4b337336dbbe93395d1f2ccc18937eaafea2 (patch)
tree: c01e661d69181dceca68f56a4849a9bd04608521 /doc
parent: e50b1e8715011def8aff1588081a2649a2c6cd47 (diff)
parent: 4e4a9de31de2a5f395ee25c59e4026422fbcb27e (diff)
22 files changed, 1390 insertions, 969 deletions
diff --git a/doc/README.commands.spl b/doc/README.commands.spl
index ecfd3ca9ee5..54cc5b1ec42 100644
--- a/doc/README.commands.spl
+++ b/doc/README.commands.spl
@@ -5,24 +5,16 @@ SUBCOMMAND EXPORT
 To execute the command everything has to be in place as if bootm should be
 used. (kernel image, initrd-image, fdt-image etc.)
 
-export has two subcommands:
-	atags: exports the ATAGS
+export has one subcommand:
 	fdt: exports the FDT
 
 Call is:
-spl export <fdt|atags> [kernel_addr] [initrd_addr] [fdt_addr if fdt]
+spl export fdt [kernel_addr] [initrd_addr] [fdt_addr if fdt]
 
 
 TYPICAL CALL
 
-on OMAP3:
-nandecc hw
-nand read 0x82000000 0x280000 0x400000	/* Read kernel image from NAND*/
-spl export atags			/* export ATAGS */
-nand erase 0x680000 0x20000		/* erase - one page */
-nand write 0x80000100 0x680000 0x20000	/* write the image - one page */
-
-call with FDT:
+on OMAP3 with FDT:
 nandecc hw
 nand read 0x82000000 0x280000 0x400000	/* Read kernel image from NAND*/
 tftpboot 0x80000100 devkit8000.dtb /* Read fdt */
diff --git a/doc/README.ext4 b/doc/README.ext4
deleted file mode 100644
index 8ecd21eee3b..00000000000
--- a/doc/README.ext4
+++ /dev/null
@@ -1,83 +0,0 @@
-U-Boot supports access of both ext2 and ext4 filesystems, either in read-only
-mode or in read-write mode.
-
-First, to enable support for both ext4 (and, automatically, ext2 as well),
-but without selecting the corresponding commands, enable one of the following:
-
-  CONFIG_FS_EXT4	(for read-only)
-  CONFIG_EXT4_WRITE	(for read-write)
-
-Next, to select the ext2-related commands:
-
-  * ext2ls
-  * ext2load
-
-or ext4-related commands:
-
-  * ext4size
-  * ext4ls
-  * ext4load
-
-use one or both of:
-
-  CONFIG_CMD_EXT2
-  CONFIG_CMD_EXT4
-
-Selecting either of the above automatically selects CONFIG_FS_EXT4 if it
-wasn't enabled already.
-
-In addition, to get the write access command "ext4write", enable:
-
-  CONFIG_CMD_EXT4_WRITE
-
-which automatically selects CONFIG_EXT4_WRITE if it wasn't defined
-already.
-
-Also relevant are the generic filesystem commands, selected by:
-
-  CONFIG_CMD_FS_GENERIC
-
-This does not automatically enable EXT4 support for you, you still need
-to do that yourself.
-
-Some sample commands to test ext4 support:
-
-1. Check that the commands can be seen in the output of U-Boot help:
-
-	UBOOT #help
-	...
-	ext4load- load binary file from a Ext4 file system
-	ext4ls  - list files in a directory (default /)
-	ext4size - determine a file's size
-	ext4write- create a file in ext4 formatted partition
-	...
-
-2. To list the files in an ext4-formatted partition, run:
-
-	ext4ls <interface> <dev[:part]> [directory]
-
-	For example:
-	UBOOT #ext4ls mmc 0:5 /usr/lib
-
-3. To read and load a file from an ext4-formatted partition to RAM, run:
-
-	ext4load <interface> <dev[:part]> [addr] [filename] [bytes]
-
-	For example:
-	UBOOT #ext4load mmc 2:2 0x30007fc0 uImage
-
-4. To write a file to an ext4-formatted partition.
-
-	a) First load a file to RAM at a particular address for example 0x30007fc0.
-	Now execute ext4write command:
-	ext4write <interface> <dev[:part]> [filename] [Address] [sizebytes]
-
-	For example:
-	UBOOT #ext4write mmc 2:2 /boot/uImage 0x30007fc0 6183120
-	(here 6183120 is the size of the file to be written)
-	Note: Absolute path is required for the file to be written
-
-References :
-	-- ext4 implementation in Linux Kernel
-	-- Uboot existing ext2 load and ls implementation
-	-- Journaling block device JBD2 implementation in linux Kernel
diff --git a/doc/board/microchip/index.rst b/doc/board/microchip/index.rst
index affc5a9e014..571b8877f08 100644
--- a/doc/board/microchip/index.rst
+++ b/doc/board/microchip/index.rst
@@ -7,3 +7,4 @@ Microchip
    :maxdepth: 2
 
    mpfs_icicle
+   mpfs_video
diff --git a/doc/board/microchip/mpfs_build_boot.rst b/doc/board/microchip/mpfs_build_boot.rst
new file mode 100644
index 00000000000..1239f675ec8
--- /dev/null
+++ b/doc/board/microchip/mpfs_build_boot.rst
@@ -0,0 +1,29 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+Booting from eMMC using HSS
+---------------------------
+
+Building U-Boot
+~~~~~~~~~~~~~~~
+
+1. Add the RISC-V toolchain to your PATH.
+2. Setup ARCH & cross compilation environment variable:
+
+.. code-block:: none
+
+   export CROSS_COMPILE=<riscv64 toolchain prefix>
+
+3. make microchip_mpfs_generic_defconfig
+4. make
+
+Flashing
+~~~~~~~~
+
+The current U-Boot port is supported in S-mode only and loaded from DRAM.
+
+A prior stage M-mode firmware/bootloader (e.g HSS with OpenSBI) is required to
+boot the u-boot.bin in S-mode.
+
+Currently, the u-boot.bin is used as a payload of the HSS firmware (Microchip
+boot-flow) and OpenSBI generic platform fw_payload.bin (with u-boot.bin embedded)
+as HSS payload (Custom boot-flow)
diff --git a/doc/board/microchip/mpfs_common.rst b/doc/board/microchip/mpfs_common.rst
new file mode 100644
index 00000000000..edbaf043966
--- /dev/null
+++ b/doc/board/microchip/mpfs_common.rst
@@ -0,0 +1,666 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+Creating the HSS payload - Custom boot-flow
+'''''''''''''''''''''''''''''''''''''''''''
+
+1. You will be creating a payload from `fw_payload.bin`.
+   Copy this file to the HSS/tools/hss-payload-generator/test directory.
+2. Go to hss-payload-generator source directory.
+
+.. code-block:: none
+
+   cd hart-software-services/tools/hss-payload-generator
+
+3. Edit test/uboot.yaml file for hart entry points and correct name of the binary file.
+
+	hart-entry-points: {u54_1: '0x80000000', u54_2: '0x80000000', u54_3: '0x80000000', u54_4: '0x80000000'}
+
+	payloads:
+	test/fw_payload.bin: {exec-addr: '0x80000000', owner-hart: u54_1, secondary-hart: u54_2, secondary-hart: u54_3, secondary-hart: u54_4, priv-mode: prv_m}
+
+4. Generate payload
+
+.. code-block:: none
+
+   ./hss-payload-generator -c test/uboot.yaml payload.bin
+
+Once the payload binary is generated, it should be copied to the eMMC.
+
+Please refer to HSS documenation to build the HSS firmware for payload.
+(Note: HSS git repo is at https://github.com/polarfire-soc/hart-software-services/blob/master/tools/hss-payload-generator/README.md
+and also refer the HSS payload generator at https://github.com/polarfire-soc/polarfire-soc-documentation/blob/master/software-development/hss-payloads.md)
+
+Program eMMC with HSS Payload
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Program eMMC with payload binary is explained in the PolarFire SoC documentation.
+(Note: PolarFire SoC Documentation git repo is at https://github.com/polarfire-soc/polarfire-soc-documentation/blob/master/boards/mpfs-icicle-kit-es/updating-icicle-kit/updating-icicle-kit-design-and-linux.md#eMMC)
+
+Once the payload image is copied to the eMMC, press CTRL+C in the HSS command
+line interface, then type 'boot' and enter to boot the newly copied image.
+
+.. code-block:: none
+
+    sudo dd if=<payload_binary> of=/dev/sdX bs=512
+
+GUID type with HSS Payload
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The HSS always picks up HSS payload from a GPT partition with
+GUID type "21686148-6449-6E6F-744E-656564454649" or sector '0' of the eMMC if no
+GPT partition.
+
+Booting with HSS Payload
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+You should see the U-Boot prompt on UART1.
+(Note: UART0 is reserved for HSS)
+
+Sample boot log from MPFS Icicle Kit
+''''''''''''''''''''''''''''''''''''
+
+.. code-block:: none
+
+   U-Boot 2021.01-00314-g7303332537-dirty (Jan 14 2021 - 10:09:43 +0530)
+
+   CPU:   rv64imafdc
+   Model: Microchip MPFS Icicle Kit
+   DRAM:  1 GiB
+   MMC:   sdhc@20008000: 0
+   In:    serial@20100000
+   Out:   serial@20100000
+   Err:   serial@20100000
+   Net:   eth0: ethernet@20112000
+   Hit any key to stop autoboot:  0
+
+Now you can configure your networking, tftp server and use tftp boot method to
+load uImage (with initramfs).
+
+.. code-block:: none
+
+   RISC-V # setenv kernel_addr_r 0x80200000
+   RISC-V # setenv fdt_addr_r 0x82200000
+
+   RISC-V # setenv ipaddr 192.168.1.5
+   RISC-V # setenv netmask 255.255.255.0
+   RISC-V # setenv serverip 192.168.1.3
+   RISC-V # setenv gateway 192.168.1.1
+
+   RISC-V # tftpboot ${kernel_addr_r} uImage
+   ethernet@20112000: PHY present at 9
+   ethernet@20112000: Starting autonegotiation...
+   ethernet@20112000: Autonegotiation complete
+   ethernet@20112000: link up, 1000Mbps full-duplex (lpa: 0x7800)
+   Using ethernet@20112000 device
+   TFTP from server 192.168.1.3; our IP address is 192.168.1.5
+   Filename 'uImage'.
+   Load address: 0x80200000
+   Loading: #################################################################
+	    #################################################################
+	    #################################################################
+	    #################################################################
+	    #################################################################
+	    #################################################################
+	    #################################################################
+	    #################################################################
+	    #################################################################
+	    #################################################################
+	    #################################################################
+	    #################################################################
+	    #################################################################
+	    #################################################################
+	    #################################################################
+	    ############
+	    6.4 MiB/s
+   done
+   Bytes transferred = 14482480 (dcfc30 hex)
+
+   RISC-V # tftpboot ${fdt_addr_r} mpfs-icicle-kit.dtb
+   ethernet@20112000: PHY present at 9
+   ethernet@20112000: Starting autonegotiation...
+   ethernet@20112000: Autonegotiation complete
+   ethernet@20112000: link up, 1000Mbps full-duplex (lpa: 0x7800)
+   Using ethernet@20112000 device
+   TFTP from server 192.168.1.3; our IP address is 192.168.1.5
+   Filename 'mpfs-icicle-kit.dtb'.
+   Load address: 0x82200000
+   Loading: #
+			2.5 MiB/s
+   done
+   Bytes transferred = 10282 (282a hex)
+
+   RISC-V # bootm ${kernel_addr_r} - ${fdt_addr_r}
+   ## Booting kernel from Legacy Image at 80200000 ...
+		Image Name:   Linux
+		Image Type:   RISC-V Linux Kernel Image (uncompressed)
+		Data Size:    14482416 Bytes = 13.8 MiB
+		Load Address: 80200000
+		Entry Point:  80200000
+		Verifying Checksum ... OK
+   ## Flattened Device Tree blob at 82200000
+		Booting using the fdt blob at 0x82200000
+		Loading Kernel Image
+		Using Device Tree in place at 000000008fffa000, end 000000008ffff829 ... OK
+
+   Starting kernel ...
+
+   [    0.000000] OF: fdt: Ignoring memory range 0x80000000 - 0x80200000
+   [    0.000000] Linux version 5.6.17 (padmarao@padmarao-VirtualBox) (gcc version 7.2.0 (GCC)) #2 SMP Tue Jun 16 21:27:50 IST 2020
+   [    0.000000] initrd not found or empty - disabling initrd
+   [    0.000000] Zone ranges:
+   [    0.000000]   DMA32    [mem 0x0000000080200000-0x00000000bfffffff]
+   [    0.000000]   Normal   empty
+   [    0.000000] Movable zone start for each node
+   [    0.000000] Early memory node ranges
+   [    0.000000]   node   0: [mem 0x0000000080200000-0x00000000bfffffff]
+   [    0.000000] Initmem setup node 0 [mem 0x0000000080200000-0x00000000bfffffff]
+   [    0.000000] software IO TLB: mapped [mem 0xbb1f5000-0xbf1f5000] (64MB)
+   [    0.000000] elf_hwcap is 0x112d
+   [    0.000000] percpu: Embedded 14 pages/cpu s24856 r0 d32488 u57344
+   [    0.000000] Built 1 zonelists, mobility grouping on.  Total pages: 258055
+   [    0.000000] Kernel command line: console=ttyS0,115200n8
+   [    0.000000] Dentry cache hash table entries: 131072 (order: 8, 1048576 bytes, linear)
+   [    0.000000] Inode-cache hash table entries: 65536 (order: 7, 524288 bytes, linear)
+   [    0.000000] Sorting __ex_table...
+   [    0.000000] mem auto-init: stack:off, heap alloc:off, heap free:off
+   [    0.000000] Memory: 950308K/1046528K available (3289K kernel code, 212K rwdata, 900K rodata, 9476K init, 250K bss, 96220K reserved, 0K cma-reserved)
+   [    0.000000] SLUB: HWalign=64, Order=0-3, MinObjects=0, CPUs=4, Nodes=1
+   [    0.000000] rcu: Hierarchical RCU implementation.
+   [    0.000000] rcu: 	RCU event tracing is enabled.
+   [    0.000000] rcu: 	RCU restricting CPUs from NR_CPUS=8 to nr_cpu_ids=4.
+   [    0.000000] rcu: RCU calculated value of scheduler-enlistment delay is 10 jiffies.
+   [    0.000000] rcu: Adjusting geometry for rcu_fanout_leaf=16, nr_cpu_ids=4
+   [    0.000000] NR_IRQS: 0, nr_irqs: 0, preallocated irqs: 0
+   [    0.000000] plic: mapped 186 interrupts with 4 handlers for 9 contexts.
+   [    0.000000] riscv_timer_init_dt: Registering clocksource cpuid [0] hartid [1]
+   [    0.000000] clocksource: riscv_clocksource: mask: 0xffffffffffffffff max_cycles: 0x1d854df40, max_idle_ns: 3526361616960 ns
+   [    0.000015] sched_clock: 64 bits at 1000kHz, resolution 1000ns, wraps every 2199023255500ns
+   [    0.000311] Calibrating delay loop (skipped), value calculated using timer frequency.. 2.00 BogoMIPS (lpj=10000)
+   [    0.000349] pid_max: default: 32768 minimum: 301
+   [    0.000846] Mount-cache hash table entries: 2048 (order: 2, 16384 bytes, linear)
+   [    0.000964] Mountpoint-cache hash table entries: 2048 (order: 2, 16384 bytes, linear)
+   [    0.005630] rcu: Hierarchical SRCU implementation.
+   [    0.006901] smp: Bringing up secondary CPUs ...
+   [    0.012545] smp: Brought up 1 node, 4 CPUs
+   [    0.014431] devtmpfs: initialized
+   [    0.020526] random: get_random_bytes called from setup_net+0x36/0x192 with crng_init=0
+   [    0.020928] clocksource: jiffies: mask: 0xffffffff max_cycles: 0xffffffff, max_idle_ns: 19112604462750000 ns
+   [    0.020999] futex hash table entries: 1024 (order: 4, 65536 bytes, linear)
+   [    0.022768] NET: Registered protocol family 16
+   [    0.035478] microchip-pfsoc-clkcfg 20002000.clkcfg: Registered PFSOC core clocks
+   [    0.048429] SCSI subsystem initialized
+   [    0.049694] pps_core: LinuxPPS API ver. 1 registered
+   [    0.049719] pps_core: Software ver. 5.3.6 - Copyright 2005-2007 Rodolfo Giometti <[email protected]>
+   [    0.049780] PTP clock support registered
+   [    0.051781] clocksource: Switched to clocksource riscv_clocksource
+   [    0.055326] NET: Registered protocol family 2
+   [    0.056922] tcp_listen_portaddr_hash hash table entries: 512 (order: 1, 8192 bytes, linear)
+   [    0.057053] TCP established hash table entries: 8192 (order: 4, 65536 bytes, linear)
+   [    0.057648] TCP bind hash table entries: 8192 (order: 5, 131072 bytes, linear)
+   [    0.058579] TCP: Hash tables configured (established 8192 bind 8192)
+   [    0.059648] UDP hash table entries: 512 (order: 2, 16384 bytes, linear)
+   [    0.059837] UDP-Lite hash table entries: 512 (order: 2, 16384 bytes, linear)
+   [    0.060707] NET: Registered protocol family 1
+   [    0.266229] workingset: timestamp_bits=62 max_order=18 bucket_order=0
+   [    0.287107] io scheduler mq-deadline registered
+   [    0.287140] io scheduler kyber registered
+   [    0.429601] Serial: 8250/16550 driver, 4 ports, IRQ sharing disabled
+   [    0.433979] printk: console [ttyS0] disabled
+   [    0.434154] 20000000.serial: ttyS0 at MMIO 0x20000000 (irq = 18, base_baud = 9375000) is a 16550A
+   [    0.928039] printk: console [ttyS0] enabled
+   [    0.939804] libphy: Fixed MDIO Bus: probed
+   [    0.948702] libphy: MACB_mii_bus: probed
+   [    0.993698] macb 20112000.ethernet eth0: Cadence GEM rev 0x0107010c at 0x20112000 irq 21 (56:34:12:00:fc:00)
+   [    1.006751] mousedev: PS/2 mouse device common for all mice
+   [    1.013803] i2c /dev entries driver
+   [    1.019451] sdhci: Secure Digital Host Controller Interface driver
+   [    1.027242] sdhci: Copyright(c) Pierre Ossman
+   [    1.032731] sdhci-pltfm: SDHCI platform and OF driver helper
+   [    1.091826] mmc0: SDHCI controller on 20008000.sdhc [20008000.sdhc] using ADMA 64-bit
+   [    1.102738] NET: Registered protocol family 17
+   [    1.170326] Freeing unused kernel memory: 9476K
+   [    1.176067] This architecture does not have kernel memory protection.
+   [    1.184157] Run /init as init process
+   Starting logging: OK
+   Starting mdev...
+   /etc/init.d/S10mdev: line 21: can't create /proc/sys/kernel/hotplug: nonexiste[    1.331981] mmc0: mmc_select_hs200 failed, error -74
+   nt directory
+   [    1.355011] mmc0: new MMC card at address 0001
+   [    1.363981] mmcblk0: mmc0:0001 DG4008 7.28 GiB
+   [    1.372248] mmcblk0boot0: mmc0:0001 DG4008 partition 1 4.00 MiB
+   [    1.382292] mmcblk0boot1: mmc0:0001 DG4008 partition 2 4.00 MiB
+   [    1.390265] mmcblk0rpmb: mmc0:0001 DG4008 partition 3 4.00 MiB, chardev (251:0)
+   [    1.425234] GPT:Primary header thinks Alt. header is not at the end of the disk.
+   [    1.434656] GPT:2255809 != 15273599
+   [    1.439038] GPT:Alternate GPT header not at the end of the disk.
+   [    1.446671] GPT:2255809 != 15273599
+   [    1.451048] GPT: Use GNU Parted to correct GPT errors.
+   [    1.457755]  mmcblk0: p1 p2 p3
+   sort: /sys/devices/platform/Fixed: No such file or directory
+   modprobe: can't change directory to '/lib/modules': No such file or directory
+   Initializing random number generator... [    2.830198] random: dd: uninitialized urandom read (512 bytes read)
+   done.
+   Starting network...
+   [    3.061867] macb 20112000.ethernet eth0: PHY [20112000.ethernet-ffffffff:09] driver [Vitesse VSC8662] (irq=POLL)
+   [    3.074674] macb 20112000.ethernet eth0: configuring for phy/sgmii link mode
+   [    3.084263] pps pps0: new PPS source ptp0
+   [    3.089710] macb 20112000.ethernet: gem-ptp-timer ptp clock registered.
+   udhcpc (v1.24.2) started
+   Sending discover...
+   Sending discover...
+   [    6.380169] macb 20112000.ethernet eth0: Link is Up - 1Gbps/Full - flow control tx
+   Sending discover...
+   Sending select for 192.168.1.2...
+   Lease of 192.168.1.2 obtained, lease time 86400
+   deleting routers
+   adding dns 192.168.1.1
+   Starting dropbear sshd: [   11.385619] random: dropbear: uninitialized urandom read (32 bytes read)
+   OK
+
+   Welcome to Buildroot
+   buildroot login: root
+   Password:
+   #
+
+Booting U-Boot and Linux from eMMC
+''''''''''''''''''''''''''''''''''
+
+FPGA design with HSS programming file and Linux Image
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+https://github.com/polarfire-soc/polarfire-soc-documentation/blob/master/boards/mpfs-icicle-kit-es/updating-icicle-kit/updating-icicle-kit-design-and-linux.md
+
+The HSS firmware runs from the PolarFire SoC eNVM on reset.
+
+Program eMMC with Payload Binary and Linux Image
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Program eMMC with payload binary and Linux image is explained in the
+PolarFire SoC documentation.
+The payload binary should be copied to partition 2 of the eMMC.
+
+(Note: PolarFire SoC Documentation git repo is at https://github.com/polarfire-soc/polarfire-soc-documentation/blob/master/boards/mpfs-icicle-kit-es/updating-icicle-kit/updating-icicle-kit-design-and-linux.md#eMMC)
+
+Once the Linux image and payload binary is copied to the eMMC, press CTRL+C
+in the HSS command line interface, then type 'boot' and enter to boot the newly
+copied payload and Linux image.
+
+.. code-block:: none
+
+    zcat <linux-image>.wic.gz | sudo dd of=/dev/sdX bs=4096 iflag=fullblock oflag=direct conv=fsync status=progress
+
+    sudo dd if=<payload_binary> of=/dev/sdX2 bs=512
+
+You should see the U-Boot prompt on UART1.
+(Note: UART0 is reserved for HSS)
+
+GUID type with Payload Binary and Linux Image
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The HSS always picks up the HSS payload from a GPT partition with
+GUID type "21686148-6449-6E6F-744E-656564454649" or sector '0' of the eMMC if no
+GPT partition.
+
+Sample boot log from MPFS Icicle Kit 2
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: none
+
+   U-Boot 2021.01-00314-g7303332537-dirty (Jan 14 2021 - 10:09:43 +0530)
+
+   CPU:   rv64imafdc
+   Model: Microchip MPFS Icicle Kit
+   DRAM:  1 GiB
+   MMC:   sdhc@20008000: 0
+   In:    serial@20100000
+   Out:   serial@20100000
+   Err:   serial@20100000
+   Net:   eth0: ethernet@20112000
+   Hit any key to stop autoboot:  0
+
+   RISC-V # mmc info
+   Device: sdhc@20008000
+   Manufacturer ID: 45
+   OEM: 100
+   Name: DG400
+   Bus Speed: 52000000
+   Mode: MMC High Speed (52MHz)
+   Rd Block Len: 512
+   MMC version 5.1
+   High Capacity: Yes
+   Capacity: 7.3 GiB
+   Bus Width: 4-bit
+   Erase Group Size: 512 KiB
+   HC WP Group Size: 8 MiB
+   User Capacity: 7.3 GiB WRREL
+   Boot Capacity: 4 MiB ENH
+   RPMB Capacity: 4 MiB ENH
+
+   RISC-V # mmc part
+   Partition Map for MMC device 0  --   Partition Type: EFI
+
+   Part	Start LBA	End LBA		Name
+		Attributes
+		Type GUID
+		Partition GUID
+	1	0x00002000	0x0000b031	"boot"
+		attrs:	0x0000000000000004
+		type:	ebd0a0a2-b9e5-4433-87c0-68b6b72699c7
+		guid:	99ff6a94-f2e7-44dd-a7df-f3a2da106ef9
+	2	0x0000b032	0x0000f031	"primary"
+		attrs:	0x0000000000000000
+		type:	21686148-6449-6e6f-744e-656564454649
+		guid:	12006052-e64b-4423-beb0-b956ea00f1ba
+	3	0x00010000	0x00226b9f	"root"
+		attrs:	0x0000000000000000
+		type:	0fc63daf-8483-4772-8e79-3d69d8477de4
+		guid:	dd2c5619-2272-4c3c-8dc2-e21942e17ce6
+
+   RISC-V # load mmc 0 ${ramdisk_addr_r} fitimage
+   RISC-V # bootm ${ramdisk_addr_r}
+   ## Loading kernel from FIT Image at 88300000 ...
+   Using 'conf@microchip_icicle-kit-es-a000-microchip.dtb' configuration
+   Trying 'kernel@1' kernel subimage
+     Description:  Linux kernel
+     Type:         Kernel Image
+     Compression:  gzip compressed
+     Data Start:   0x883000fc
+     Data Size:    3574555 Bytes = 3.4 MiB
+     Architecture: RISC-V
+     OS:           Linux
+     Load Address: 0x80200000
+     Entry Point:  0x80200000
+     Hash algo:    sha256
+     Hash value:   21f18d72cf2f0a7192220abb577ad25c77c26960052d779aa02bf55dbf0a6403
+   Verifying Hash Integrity ... sha256+ OK
+   ## Loading fdt from FIT Image at 88300000 ...
+   Using 'conf@microchip_icicle-kit-es-a000-microchip.dtb' configuration
+   Trying 'fdt@microchip_icicle-kit-es-a000-microchip.dtb' fdt subimage
+     Description:  Flattened Device Tree blob
+     Type:         Flat Device Tree
+     Compression:  uncompressed
+     Data Start:   0x88668d44
+     Data Size:    9760 Bytes = 9.5 KiB
+     Architecture: RISC-V
+     Load Address: 0x82200000
+     Hash algo:    sha256
+     Hash value:   5c3a9f30d41b6b8e53b47916e1f339b3a4d454006554d1f7e1f552ed62409f4b
+   Verifying Hash Integrity ... sha256+ OK
+   Loading fdt from 0x88668d48 to 0x82200000
+   Booting using the fdt blob at 0x82200000
+   Uncompressing Kernel Image
+   Loading Device Tree to 000000008fffa000, end 000000008ffff61f ... OK
+
+   Starting kernel ...
+
+   [    0.000000] OF: fdt: Ignoring memory range 0x80000000 - 0x80200000
+   [    0.000000] Linux version 5.6.16 (oe-user@oe-host) (gcc version 9.3.0 (GCC)) #1 SMP Fri Oct 9 11:49:47 UTC 2020
+   [    0.000000] earlycon: sbi0 at I/O port 0x0 (options '')
+   [    0.000000] printk: bootconsole [sbi0] enabled
+   [    0.000000] Zone ranges:
+   [    0.000000]   DMA32    [mem 0x0000000080200000-0x00000000bfffffff]
+   [    0.000000]   Normal   empty
+   [    0.000000] Movable zone start for each node
+   [    0.000000] Early memory node ranges
+   [    0.000000]   node   0: [mem 0x0000000080200000-0x00000000bfffffff]
+   [    0.000000] Zeroed struct page in unavailable ranges: 512 pages
+   [    0.000000] Initmem setup node 0 [mem 0x0000000080200000-0x00000000bfffffff]
+   [    0.000000] software IO TLB: mapped [mem 0xb9e00000-0xbde00000] (64MB)
+   [    0.000000] CPU with hartid=0 is not available
+   [    0.000000] CPU with hartid=0 is not available
+   [    0.000000] elf_hwcap is 0x112d
+   [    0.000000] percpu: Embedded 17 pages/cpu s29784 r8192 d31656 u69632
+   [    0.000000] Built 1 zonelists, mobility grouping on.  Total pages: 258055
+   [    0.000000] Kernel command line: earlycon=sbi root=/dev/mmcblk0p3 rootwait console=ttyS0,115200n8 uio_pdrv_genirq.of_id=generic-uio
+   [    0.000000] Dentry cache hash table entries: 131072 (order: 8, 1048576 bytes, linear)
+   [    0.000000] Inode-cache hash table entries: 65536 (order: 7, 524288 bytes, linear)
+   [    0.000000] Sorting __ex_table...
+   [    0.000000] mem auto-init: stack:off, heap alloc:off, heap free:off
+   [    0.000000] Memory: 941440K/1046528K available (4118K kernel code, 280K rwdata, 1687K rodata, 169K init, 273K bss, 105088K reserved, 0K cma-reserved)
+   [    0.000000] SLUB: HWalign=64, Order=0-3, MinObjects=0, CPUs=4, Nodes=1
+   [    0.000000] rcu: Hierarchical RCU implementation.
+   [    0.000000] rcu: 	RCU event tracing is enabled.
+   [    0.000000] rcu: 	RCU restricting CPUs from NR_CPUS=5 to nr_cpu_ids=4.
+   [    0.000000] rcu: RCU calculated value of scheduler-enlistment delay is 10 jiffies.
+   [    0.000000] rcu: Adjusting geometry for rcu_fanout_leaf=16, nr_cpu_ids=4
+   [    0.000000] NR_IRQS: 0, nr_irqs: 0, preallocated irqs: 0
+   [    0.000000] plic: mapped 53 interrupts with 4 handlers for 9 contexts.
+   [    0.000000] riscv_timer_init_dt: Registering clocksource cpuid [0] hartid [1]
+   [    0.000000] clocksource: riscv_clocksource: mask: 0xffffffffffffffff max_cycles: 0x1d854df40, max_idle_ns: 3526361616960 ns
+   [    0.000015] sched_clock: 64 bits at 1000kHz, resolution 1000ns, wraps every 2199023255500ns
+   [    0.008679] Console: colour dummy device 80x25
+   [    0.013112] Calibrating delay loop (skipped), value calculated using timer frequency.. 2.00 BogoMIPS (lpj=10000)
+   [    0.023368] pid_max: default: 32768 minimum: 301
+   [    0.028314] Mount-cache hash table entries: 2048 (order: 2, 16384 bytes, linear)
+   [    0.035766] Mountpoint-cache hash table entries: 2048 (order: 2, 16384 bytes, linear)
+   [    0.047099] rcu: Hierarchical SRCU implementation.
+   [    0.052813] smp: Bringing up secondary CPUs ...
+   [    0.061581] smp: Brought up 1 node, 4 CPUs
+   [    0.067069] devtmpfs: initialized
+   [    0.073621] random: get_random_u32 called from bucket_table_alloc.isra.0+0x4e/0x150 with crng_init=0
+   [    0.074409] clocksource: jiffies: mask: 0xffffffff max_cycles: 0xffffffff, max_idle_ns: 19112604462750000 ns
+   [    0.093399] futex hash table entries: 1024 (order: 4, 65536 bytes, linear)
+   [    0.101879] NET: Registered protocol family 16
+   [    0.110336] microchip-pfsoc-clkcfg 20002000.clkcfg: Registered PFSOC core clocks
+   [    0.132717] usbcore: registered new interface driver usbfs
+   [    0.138225] usbcore: registered new interface driver hub
+   [    0.143813] usbcore: registered new device driver usb
+   [    0.148939] pps_core: LinuxPPS API ver. 1 registered
+   [    0.153929] pps_core: Software ver. 5.3.6 - Copyright 2005-2007 Rodolfo Giometti <[email protected]>
+   [    0.163071] PTP clock support registered
+   [    0.168521] clocksource: Switched to clocksource riscv_clocksource
+   [    0.174927] VFS: Disk quotas dquot_6.6.0
+   [    0.179016] VFS: Dquot-cache hash table entries: 512 (order 0, 4096 bytes)
+   [    0.205536] NET: Registered protocol family 2
+   [    0.210944] tcp_listen_portaddr_hash hash table entries: 512 (order: 1, 8192 bytes, linear)
+   [    0.219393] TCP established hash table entries: 8192 (order: 4, 65536 bytes, linear)
+   [    0.227497] TCP bind hash table entries: 8192 (order: 5, 131072 bytes, linear)
+   [    0.235440] TCP: Hash tables configured (established 8192 bind 8192)
+   [    0.242537] UDP hash table entries: 512 (order: 2, 16384 bytes, linear)
+   [    0.249285] UDP-Lite hash table entries: 512 (order: 2, 16384 bytes, linear)
+   [    0.256690] NET: Registered protocol family 1
+   [    0.262585] workingset: timestamp_bits=62 max_order=18 bucket_order=0
+   [    0.281036] Block layer SCSI generic (bsg) driver version 0.4 loaded (major 249)
+   [    0.288481] io scheduler mq-deadline registered
+   [    0.292983] io scheduler kyber registered
+   [    0.298895] microsemi,mss-gpio 20122000.gpio: Microsemi MSS GPIO registered 32 GPIOs
+   [    0.453723] Serial: 8250/16550 driver, 4 ports, IRQ sharing disabled
+   [    0.462911] printk: console [ttyS0] disabled
+   [    0.467216] 20100000.serial: ttyS0 at MMIO 0x20100000 (irq = 12, base_baud = 9375000) is a 16550A
+   [    0.476201] printk: console [ttyS0] enabled
+   [    0.476201] printk: console [ttyS0] enabled
+   [    0.484576] printk: bootconsole [sbi0] disabled
+   [    0.484576] printk: bootconsole [sbi0] disabled
+   [    0.494920] 20102000.serial: ttyS1 at MMIO 0x20102000 (irq = 13, base_baud = 9375000) is a 16550A
+   [    0.505068] 20104000.serial: ttyS2 at MMIO 0x20104000 (irq = 14, base_baud = 9375000) is a 16550A
+   [    0.533336] loop: module loaded
+   [    0.572284] Rounding down aligned max_sectors from 4294967295 to 4294967288
+   [    0.580000] db_root: cannot open: /etc/target
+   [    0.585413] libphy: Fixed MDIO Bus: probed
+   [    0.591526] libphy: MACB_mii_bus: probed
+   [    0.598060] macb 20112000.ethernet eth0: Cadence GEM rev 0x0107010c at 0x20112000 irq 17 (56:34:12:00:fc:00)
+   [    0.608352] ehci_hcd: USB 2.0 'Enhanced' Host Controller (EHCI) Driver
+   [    0.615001] ehci-platform: EHCI generic platform driver
+   [    0.620446] ohci_hcd: USB 1.1 'Open' Host Controller (OHCI) Driver
+   [    0.626632] ohci-platform: OHCI generic platform driver
+   [    0.632326] usbcore: registered new interface driver cdc_acm
+   [    0.637996] cdc_acm: USB Abstract Control Model driver for USB modems and ISDN adapters
+   [    0.646459] i2c /dev entries driver
+   [    0.650852] microsemi-mss-i2c 2010b000.i2c: Microsemi I2C Probe Complete
+   [    0.658010] sdhci: Secure Digital Host Controller Interface driver
+   [    0.664326] sdhci: Copyright(c) Pierre Ossman
+   [    0.668754] sdhci-pltfm: SDHCI platform and OF driver helper
+   [    0.706845] mmc0: SDHCI controller on 20008000.sdhc [20008000.sdhc] using ADMA 64-bit
+   [    0.715052] usbcore: registered new interface driver usbhid
+   [    0.720722] usbhid: USB HID core driver
+   [    0.725174] pac193x 0-0010: Chip revision: 0x03
+   [    0.733339] pac193x 0-0010: :pac193x_prep_iio_channels: Channel 0 active
+   [    0.740127] pac193x 0-0010: :pac193x_prep_iio_channels: Channel 1 active
+   [    0.746881] pac193x 0-0010: :pac193x_prep_iio_channels: Channel 2 active
+   [    0.753686] pac193x 0-0010: :pac193x_prep_iio_channels: Channel 3 active
+   [    0.760495] pac193x 0-0010: :pac193x_prep_iio_channels: Active chip channels: 25
+   [    0.778006] NET: Registered protocol family 10
+   [    0.784929] Segment Routing with IPv6
+   [    0.788875] sit: IPv6, IPv4 and MPLS over IPv4 tunneling driver
+   [    0.795743] NET: Registered protocol family 17
+   [    0.801191] hctosys: unable to open rtc device (rtc0)
+   [    0.807774] Waiting for root device /dev/mmcblk0p3...
+   [    0.858506] mmc0: mmc_select_hs200 failed, error -74
+   [    0.865764] mmc0: new MMC card at address 0001
+   [    0.872564] mmcblk0: mmc0:0001 DG4008 7.28 GiB
+   [    0.878777] mmcblk0boot0: mmc0:0001 DG4008 partition 1 4.00 MiB
+   [    0.886182] mmcblk0boot1: mmc0:0001 DG4008 partition 2 4.00 MiB
+   [    0.892633] mmcblk0rpmb: mmc0:0001 DG4008 partition 3 4.00 MiB, chardev (247:0)
+   [    0.919029] GPT:Primary header thinks Alt. header is not at the end of the disk.
+   [    0.926448] GPT:2255841 != 15273599
+   [    0.930019] GPT:Alternate GPT header not at the end of the disk.
+   [    0.936029] GPT:2255841 != 15273599
+   [    0.939583] GPT: Use GNU Parted to correct GPT errors.
+   [    0.944800]  mmcblk0: p1 p2 p3
+   [    0.966696] EXT4-fs (mmcblk0p3): INFO: recovery required on readonly filesystem
+   [    0.974105] EXT4-fs (mmcblk0p3): write access will be enabled during recovery
+   [    1.052362] random: fast init done
+   [    1.057961] EXT4-fs (mmcblk0p3): recovery complete
+   [    1.065734] EXT4-fs (mmcblk0p3): mounted filesystem with ordered data mode. Opts: (null)
+   [    1.074002] VFS: Mounted root (ext4 filesystem) readonly on device 179:3.
+   [    1.081654] Freeing unused kernel memory: 168K
+   [    1.086108] This architecture does not have kernel memory protection.
+   [    1.092629] Run /sbin/init as init process
+   [    1.702217] systemd[1]: System time before build time, advancing clock.
+   [    1.754192] systemd[1]: systemd 244.3+ running in system mode. (+PAM -AUDIT -SELINUX +IMA -APPARMOR -SMACK +SYSVINIT +UTMP -LIBCRYPTSETUP -GCRYPT -GNUTLS +ACL +XZ -LZ4 -SECCOMP +BLKID -ELFUTILS +KMOD -IDN2 -IDN -PCRE2 default-hierarchy=hybrid)
+   [    1.776361] systemd[1]: Detected architecture riscv64.
+
+   Welcome to OpenEmbedded nodistro.0!
+
+   [    1.829651] systemd[1]: Set hostname to <icicle-kit-es>.
+   [    2.648597] random: systemd: uninitialized urandom read (16 bytes read)
+   [    2.657485] systemd[1]: Created slice system-getty.slice.
+   [  OK  ] Created slice system-getty.slice.
+   [    2.698779] random: systemd: uninitialized urandom read (16 bytes read)
+   [    2.706317] systemd[1]: Created slice system-serial\x2dgetty.slice.
+   [  OK  ] Created slice system-serial\x2dgetty.slice.
+   [    2.748716] random: systemd: uninitialized urandom read (16 bytes read)
+   [    2.756098] systemd[1]: Created slice User and Session Slice.
+   [  OK  ] Created slice User and Session Slice.
+   [    2.789065] systemd[1]: Started Dispatch Password Requests to Console Directory Watch.
+   [  OK  ] Started Dispatch Password …ts to Console Directory Watch.
+   [    2.828974] systemd[1]: Started Forward Password Requests to Wall Directory Watch.
+   [  OK  ] Started Forward Password R…uests to Wall Directory Watch.
+   [    2.869009] systemd[1]: Reached target Paths.
+   [  OK  ] Reached target Paths.
+   [    2.898808] systemd[1]: Reached target Remote File Systems.
+   [  OK  ] Reached target Remote File Systems.
+   [    2.938771] systemd[1]: Reached target Slices.
+   [  OK  ] Reached target Slices.
+   [    2.968754] systemd[1]: Reached target Swap.
+   [  OK  ] Reached target Swap.
+   [    2.999283] systemd[1]: Listening on initctl Compatibility Named Pipe.
+   [  OK  ] Listening on initctl Compatibility Named Pipe.
+   [    3.060458] systemd[1]: Condition check resulted in Journal Audit Socket being skipped.
+   [    3.069826] systemd[1]: Listening on Journal Socket (/dev/log).
+   [  OK  ] Listening on Journal Socket (/dev/log).
+   [    3.109601] systemd[1]: Listening on Journal Socket.
+   [  OK  ] Listening on Journal Socket.
+   [    3.149868] systemd[1]: Listening on Network Service Netlink Socket.
+   [  OK  ] Listening on Network Service Netlink Socket.
+   [    3.189419] systemd[1]: Listening on udev Control Socket.
+   [  OK  ] Listening on udev Control Socket.
+   [    3.229179] systemd[1]: Listening on udev Kernel Socket.
+   [  OK  ] Listening on udev Kernel Socket.
+   [    3.269520] systemd[1]: Condition check resulted in Huge Pages File System being skipped.
+   [    3.278477] systemd[1]: Condition check resulted in POSIX Message Queue File System being skipped.
+   [    3.288200] systemd[1]: Condition check resulted in Kernel Debug File System being skipped.
+   [    3.302570] systemd[1]: Mounting Temporary Directory (/tmp)...
+            Mounting Temporary Directory (/tmp)...
+   [    3.339226] systemd[1]: Condition check resulted in Create list of static device nodes for the current kernel being skipped.
+   [    3.355883] systemd[1]: Starting File System Check on Root Device...
+            Starting File System Check on Root Device...
+   [    3.407220] systemd[1]: Starting Journal Service...
+            Starting Journal Service...
+   [    3.422441] systemd[1]: Condition check resulted in Load Kernel Modules being skipped.
+   [    3.431770] systemd[1]: Condition check resulted in FUSE Control File System being skipped.
+   [    3.446415] systemd[1]: Mounting Kernel Configuration File System...
+            Mounting Kernel Configuration File System...
+   [    3.458983] systemd[1]: Starting Apply Kernel Variables...
+            Starting Apply Kernel Variables...
+   [    3.471368] systemd[1]: Starting udev Coldplug all Devices...
+            Starting udev Coldplug all Devices...
+   [    3.491071] systemd[1]: Mounted Temporary Directory (/tmp).
+   [  OK      3.498114] systemd[1]: Mounted Kernel Configuration File System.
+   0m] Mounted Temporary Directory (/tmp).
+   [  OK  ] Mounted Kernel Configuration File System.
+   [    3.550853] systemd[1]: Started Apply Kernel Variables.
+   [  OK      3.557535] systemd[1]: Started Journal Service.
+   0m] Started Apply Kernel Variables.
+   [  OK  ] Started Journal Service.
+   [  OK  ] Started udev Coldplug all Devices.
+   [  OK  ] Started File System Check on Root Device.
+            Starting Remount Root and Kernel File Systems...
+   [    8.133469] EXT4-fs (mmcblk0p3): re-mounted. Opts: (null)
+   [  OK  ] Started Remount Root and Kernel File Systems.
+            Starting Flush Journal to Persistent Storage...
+   [    8.215327] systemd-journald[77]: Received client request to flush runtime journal.
+            Starting Create Static Device Nodes in /dev...
+   [  OK  ] Started Flush Journal to Persistent Storage.
+   [  OK  ] Started Create Static Device Nodes in /dev.
+   [  OK  ] Reached target Local File Systems (Pre).
+            Mounting /var/volatile...
+            Starting udev Kernel Device Manager...
+   [  OK  ] Mounted /var/volatile.
+            Starting Load/Save Random Seed...
+   [  OK  ] Reached target Local File Systems.
+            Starting Create Volatile Files and Directories...
+   [  OK  ] Started udev Kernel Device Manager.
+   [  OK  ] Started Create Volatile Files and Directories.
+            Starting Network Time Synchronization...
+            Starting Update UTMP about System Boot/Shutdown...
+   [  OK  ] Started Update UTMP about System Boot/Shutdown.
+   [  OK  ] Started Network Time Synchronization.
+   [   11.618575] random: crng init done
+   [   11.622007] random: 7 urandom warning(s) missed due to ratelimiting
+   [  OK  ] Started Load/Save Random Seed.
+   [  OK  ] Reached target System Initialization.
+   [  OK  ] Started Daily Cleanup of Temporary Directories.
+   [  OK  ] Reached target System Time Set.
+   [  OK  ] Reached target System Time Synchronized.
+   [  OK  ] Reached target Timers.
+   [  OK  ] Listening on D-Bus System Message Bus Socket.
+   [  OK  ] Listening on dropbear.socket.
+   [  OK  ] Reached target Sockets.
+   [  OK  ] Reached target Basic System.
+   [  OK  ] Started D-Bus System Message Bus.
+            Starting IPv6 Packet Filtering Framework...
+            Starting IPv4 Packet Filtering Framework...
+            Starting Login Service...
+   [  OK  ] Started IPv6 Packet Filtering Framework.
+   [  OK  ] Started IPv4 Packet Filtering Framework.
+   [  OK  ] Reached target Network (Pre).
+            Starting Network Service...
+   [  OK  ] Started Login Service.
+   [   12.602455] macb 20112000.ethernet eth0: PHY [20112000.ethernet-ffffffff:09] driver [Vitesse VSC8662] (irq=POLL)
+   [   12.612795] macb 20112000.ethernet eth0: configuring for phy/sgmii link mode
+   [   12.622153] pps pps0: new PPS source ptp0
+   [  OK     12.626725] macb 20112000.ethernet: gem-ptp-timer ptp clock registered.
+   0m] Started Network Service.
+            Starting Network Name Resolution...
+   [  OK  ] Started Network Name Resolution.
+   [  OK  ] Reached target Network.
+   [  OK  ] Reached target Host and Network Name Lookups.
+   [  OK  ] Started Collectd.
+   [  OK  ] Started Collectd.
+            Starting Permit User Sessions...
+   [  OK  ] Started Permit User Sessions.
+   [  OK  ] Started Getty on tty1.
+   [  OK  ] Started Serial Getty on ttyS0.
+   [  OK  ] Reached target Login Prompts.
+   [  OK  ] Reached target Multi-User System.
+            Starting Update UTMP about System Runlevel Changes...
+   [  OK  ] Started Update UTMP about System Runlevel Changes.
+
+   OpenEmbedded nodistro.0 icicle-kit-es ttyS0
+
+   icicle-kit-es login: [   15.795564] macb 20112000.ethernet eth0: Link is Up - 1Gbps/Full - flow control tx
+   [   15.803306] IPv6: ADDRCONF(NETDEV_CHANGE): eth0: link becomes ready
+
+   icicle-kit-es login: root
+   root@icicle-kit-es:~#
diff --git a/doc/board/microchip/mpfs_design_hss.rst b/doc/board/microchip/mpfs_design_hss.rst
new file mode 100644
index 00000000000..d4100470758
--- /dev/null
+++ b/doc/board/microchip/mpfs_design_hss.rst
@@ -0,0 +1,37 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+FPGA design with HSS programming file
+'''''''''''''''''''''''''''''''''''''
+
+https://github.com/polarfire-soc/polarfire-soc-documentation/blob/master/reference-designs-fpga-and-development-kits/updating-linux-in-mpfs-kit.md
+
+The HSS firmware runs from the PolarFire SoC eNVM on reset.
+
+Creating the HSS payload - Microchip boot-flow
+''''''''''''''''''''''''''''''''''''''''''''''
+
+1. You will be creating a payload from `u-boot-dtb.bin`.
+   Copy this file to the HSS/tools/hss-payload-generator/test directory.
+2. Go to hss-payload-generator source directory.
+
+.. code-block:: none
+
+   cd hart-software-services/tools/hss-payload-generator
+
+3. Edit test/uboot.yaml file for hart entry points and correct name of the binary file.
+
+	hart-entry-points: {u54_1: '0x80200000', u54_2: '0x80200000', u54_3: '0x80200000', u54_4: '0x80200000'}
+
+	payloads:
+	test/u-boot-dtb.bin: {exec-addr: '0x80200000', owner-hart: u54_1, secondary-hart: u54_2, secondary-hart: u54_3, secondary-hart: u54_4, priv-mode: prv_s}
+
+4. Generate payload
+
+.. code-block:: none
+
+   ./hss-payload-generator -c test/uboot.yaml payload.bin
+
+Once the payload binary is generated, it should be copied to the eMMC.
+
+Please refer to HSS documenation to build the HSS firmware for payload.
+(Note: HSS git repo is at https://github.com/polarfire-soc/hart-software-services/blob/master/tools/hss-payload-generator/README.md)
+\ No newline at end of file
diff --git a/doc/board/microchip/mpfs_icicle.rst b/doc/board/microchip/mpfs_icicle.rst
index 1464e536e94..5af7125bde0 100644
--- a/doc/board/microchip/mpfs_icicle.rst
+++ b/doc/board/microchip/mpfs_icicle.rst
@@ -22,33 +22,7 @@ The support for following drivers are already enabled:
 4. Cadence MMC Driver for eMMC/SD support.
 5. Microchip I2C Driver.
 
-Booting from eMMC using HSS
----------------------------
-
-Building U-Boot
-~~~~~~~~~~~~~~~
-
-1. Add the RISC-V toolchain to your PATH.
-2. Setup ARCH & cross compilation environment variable:
-
-.. code-block:: none
-
-   export CROSS_COMPILE=<riscv64 toolchain prefix>
-
-3. make microchip_mpfs_icicle_defconfig
-4. make
-
-Flashing
-~~~~~~~~
-
-The current U-Boot port is supported in S-mode only and loaded from DRAM.
-
-A prior stage M-mode firmware/bootloader (e.g HSS with OpenSBI) is required to
-boot the u-boot.bin in S-mode.
-
-Currently, the u-boot.bin is used as a payload of the HSS firmware (Microchip
-boot-flow) and OpenSBI generic platform fw_payload.bin (with u-boot.bin embedded)
-as HSS payload (Custom boot-flow)
+.. include:: mpfs_build_boot.rst
 
 Microchip boot-flow
 ~~~~~~~~~~~~~~~~~~~
@@ -64,55 +38,21 @@ Build the HSS (Hart Software Services) - Microchip boot-flow
 
 .. code-block:: none
 
-   make BOARD=icicle-kit-es config
+   make BOARD=mpfs-icicle-kit-es config
 
 Alternatively, copy the default config for Microchip boot-flow.
 
 .. code-block:: none
 
-   cp boards/icicle-kit-es/def_config .config
+   cp boards/mpfs-icicle-kit-es/def_config .config
 
-2. make BOARD=icicle-kit-es
+2. make BOARD=mpfs-icicle-kit-es
 3. In the Default subdirectory, the standard build will create hss.elf and
    various binary formats (hss.hex and hss.bin).
 
 The FPGA design will use the hss.hex or hss.bin.
 
-FPGA design with HSS programming file
-'''''''''''''''''''''''''''''''''''''
-
-https://github.com/polarfire-soc/polarfire-soc-documentation/blob/master/boards/mpfs-icicle-kit-es/updating-icicle-kit/updating-icicle-kit-design-and-linux.md
-
-The HSS firmware runs from the PolarFire SoC eNVM on reset.
-
-Creating the HSS payload - Microchip boot-flow
-''''''''''''''''''''''''''''''''''''''''''''''
-
-1. You will be creating a payload from `u-boot-dtb.bin`.
-   Copy this file to the HSS/tools/hss-payload-generator/test directory.
-2. Go to hss-payload-generator source directory.
-
-.. code-block:: none
-
-   cd hart-software-services/tools/hss-payload-generator
-
-3. Edit test/uboot.yaml file for hart entry points and correct name of the binary file.
-
-	hart-entry-points: {u54_1: '0x80200000', u54_2: '0x80200000', u54_3: '0x80200000', u54_4: '0x80200000'}
-
-	payloads:
-	test/u-boot-dtb.bin: {exec-addr: '0x80200000', owner-hart: u54_1, secondary-hart: u54_2, secondary-hart: u54_3, secondary-hart: u54_4, priv-mode: prv_s}
-
-4. Generate payload
-
-.. code-block:: none
-
-   ./hss-payload-generator -c test/uboot.yaml payload.bin
-
-Once the payload binary is generated, it should be copied to the eMMC.
-
-Please refer to HSS documenation to build the HSS firmware for payload.
-(Note: HSS git repo is at https://github.com/polarfire-soc/hart-software-services/blob/master/tools/hss-payload-generator/README.md)
+.. include:: mpfs_design_hss.rst
 
 Custom boot-flow
 ~~~~~~~~~~~~~~~~
@@ -134,7 +74,7 @@ Build OpenSBI
 .. code-block:: none
 
    make PLATFORM=generic FW_PAYLOAD_PATH=<u-boot-directory>/u-boot.bin
-   FW_FDT_PATH=<u-boot-directory>/arch/riscv/dts/mpfs-icicle-kit-.dtb
+   FW_FDT_PATH=<u-boot-directory>/dts/upstream/src/riscv/microchip/mpfs-icicle-kit-.dtb
 
 3. Output "fw_payload.bin" file available at
    "<opensbi-directory>/build/platform/generic/firmware/fw_payload.bin"
@@ -148,681 +88,18 @@ Build the HSS (Hart Software Services)- Custom boot-flow
 
 .. code-block:: none
 
-   make BOARD=icicle-kit-es config
+   make BOARD=mpfs-icicle-kit-es config
 
 Alternatively, copy the default custom config for Custom boot-flow.
 
 .. code-block:: none
 
-   cp boards/icicle-kit-es/def_config_custom .config
+   cp boards/mpfs-icicle-kit-es/def_config_custom .config
 
-2. make BOARD=icicle-kit-es
+2. make BOARD=mpfs-icicle-kit-es
 3. In the Default subdirectory, the standard build will create hss.elf and
    various binary formats (hss.hex and hss.bin).
 
 The FPGA design will use the hss.hex or hss.bin.
 
-Creating the HSS payload - Custom boot-flow
-'''''''''''''''''''''''''''''''''''''''''''
-
-1. You will be creating a payload from `fw_payload.bin`.
-   Copy this file to the HSS/tools/hss-payload-generator/test directory.
-2. Go to hss-payload-generator source directory.
-
-.. code-block:: none
-
-   cd hart-software-services/tools/hss-payload-generator
-
-3. Edit test/uboot.yaml file for hart entry points and correct name of the binary file.
-
-	hart-entry-points: {u54_1: '0x80000000', u54_2: '0x80000000', u54_3: '0x80000000', u54_4: '0x80000000'}
-
-	payloads:
-	test/fw_payload.bin: {exec-addr: '0x80000000', owner-hart: u54_1, secondary-hart: u54_2, secondary-hart: u54_3, secondary-hart: u54_4, priv-mode: prv_m}
-
-4. Generate payload
-
-.. code-block:: none
-
-   ./hss-payload-generator -c test/uboot.yaml payload.bin
-
-Once the payload binary is generated, it should be copied to the eMMC.
-
-Please refer to HSS documenation to build the HSS firmware for payload.
-(Note: HSS git repo is at https://github.com/polarfire-soc/hart-software-services/blob/master/tools/hss-payload-generator/README.md
-and also refer the HSS payload generator at https://github.com/polarfire-soc/polarfire-soc-documentation/blob/master/software-development/hss-payloads.md)
-
-eMMC
-~~~~
-
-Program eMMC with payload binary is explained in the PolarFire SoC documentation.
-(Note: PolarFire SoC Documentation git repo is at https://github.com/polarfire-soc/polarfire-soc-documentation/blob/master/boards/mpfs-icicle-kit-es/updating-icicle-kit/updating-icicle-kit-design-and-linux.md#eMMC)
-
-Once the payload image is copied to the eMMC, press CTRL+C in the HSS command
-line interface, then type 'boot' and enter to boot the newly copied image.
-
-.. code-block:: none
-
-    sudo dd if=<payload_binary> of=/dev/sdX bs=512
-
-GUID type
-~~~~~~~~~
-
-The HSS always picks up HSS payload from a GPT partition with
-GUID type "21686148-6449-6E6F-744E-656564454649" or sector '0' of the eMMC if no
-GPT partition.
-
-Booting
-~~~~~~~
-
-You should see the U-Boot prompt on UART1.
-(Note: UART0 is reserved for HSS)
-
-Sample boot log from MPFS Icicle Kit
-''''''''''''''''''''''''''''''''''''
-
-.. code-block:: none
-
-   U-Boot 2021.01-00314-g7303332537-dirty (Jan 14 2021 - 10:09:43 +0530)
-
-   CPU:   rv64imafdc
-   Model: Microchip MPFS Icicle Kit
-   DRAM:  1 GiB
-   MMC:   sdhc@20008000: 0
-   In:    serial@20100000
-   Out:   serial@20100000
-   Err:   serial@20100000
-   Net:   eth0: ethernet@20112000
-   Hit any key to stop autoboot:  0
-
-Now you can configure your networking, tftp server and use tftp boot method to
-load uImage (with initramfs).
-
-.. code-block:: none
-
-   RISC-V # setenv kernel_addr_r 0x80200000
-   RISC-V # setenv fdt_addr_r 0x82200000
-
-   RISC-V # setenv ipaddr 192.168.1.5
-   RISC-V # setenv netmask 255.255.255.0
-   RISC-V # setenv serverip 192.168.1.3
-   RISC-V # setenv gateway 192.168.1.1
-
-   RISC-V # tftpboot ${kernel_addr_r} uImage
-   ethernet@20112000: PHY present at 9
-   ethernet@20112000: Starting autonegotiation...
-   ethernet@20112000: Autonegotiation complete
-   ethernet@20112000: link up, 1000Mbps full-duplex (lpa: 0x7800)
-   Using ethernet@20112000 device
-   TFTP from server 192.168.1.3; our IP address is 192.168.1.5
-   Filename 'uImage'.
-   Load address: 0x80200000
-   Loading: #################################################################
-	    #################################################################
-	    #################################################################
-	    #################################################################
-	    #################################################################
-	    #################################################################
-	    #################################################################
-	    #################################################################
-	    #################################################################
-	    #################################################################
-	    #################################################################
-	    #################################################################
-	    #################################################################
-	    #################################################################
-	    #################################################################
-	    ############
-	    6.4 MiB/s
-   done
-   Bytes transferred = 14482480 (dcfc30 hex)
-
-   RISC-V # tftpboot ${fdt_addr_r} mpfs-icicle-kit.dtb
-   ethernet@20112000: PHY present at 9
-   ethernet@20112000: Starting autonegotiation...
-   ethernet@20112000: Autonegotiation complete
-   ethernet@20112000: link up, 1000Mbps full-duplex (lpa: 0x7800)
-   Using ethernet@20112000 device
-   TFTP from server 192.168.1.3; our IP address is 192.168.1.5
-   Filename 'mpfs-icicle-kit.dtb'.
-   Load address: 0x82200000
-   Loading: #
-			2.5 MiB/s
-   done
-   Bytes transferred = 10282 (282a hex)
-
-   RISC-V # bootm ${kernel_addr_r} - ${fdt_addr_r}
-   ## Booting kernel from Legacy Image at 80200000 ...
-		Image Name:   Linux
-		Image Type:   RISC-V Linux Kernel Image (uncompressed)
-		Data Size:    14482416 Bytes = 13.8 MiB
-		Load Address: 80200000
-		Entry Point:  80200000
-		Verifying Checksum ... OK
-   ## Flattened Device Tree blob at 82200000
-		Booting using the fdt blob at 0x82200000
-		Loading Kernel Image
-		Using Device Tree in place at 000000008fffa000, end 000000008ffff829 ... OK
-
-   Starting kernel ...
-
-   [    0.000000] OF: fdt: Ignoring memory range 0x80000000 - 0x80200000
-   [    0.000000] Linux version 5.6.17 (padmarao@padmarao-VirtualBox) (gcc version 7.2.0 (GCC)) #2 SMP Tue Jun 16 21:27:50 IST 2020
-   [    0.000000] initrd not found or empty - disabling initrd
-   [    0.000000] Zone ranges:
-   [    0.000000]   DMA32    [mem 0x0000000080200000-0x00000000bfffffff]
-   [    0.000000]   Normal   empty
-   [    0.000000] Movable zone start for each node
-   [    0.000000] Early memory node ranges
-   [    0.000000]   node   0: [mem 0x0000000080200000-0x00000000bfffffff]
-   [    0.000000] Initmem setup node 0 [mem 0x0000000080200000-0x00000000bfffffff]
-   [    0.000000] software IO TLB: mapped [mem 0xbb1f5000-0xbf1f5000] (64MB)
-   [    0.000000] elf_hwcap is 0x112d
-   [    0.000000] percpu: Embedded 14 pages/cpu s24856 r0 d32488 u57344
-   [    0.000000] Built 1 zonelists, mobility grouping on.  Total pages: 258055
-   [    0.000000] Kernel command line: console=ttyS0,115200n8
-   [    0.000000] Dentry cache hash table entries: 131072 (order: 8, 1048576 bytes, linear)
-   [    0.000000] Inode-cache hash table entries: 65536 (order: 7, 524288 bytes, linear)
-   [    0.000000] Sorting __ex_table...
-   [    0.000000] mem auto-init: stack:off, heap alloc:off, heap free:off
-   [    0.000000] Memory: 950308K/1046528K available (3289K kernel code, 212K rwdata, 900K rodata, 9476K init, 250K bss, 96220K reserved, 0K cma-reserved)
-   [    0.000000] SLUB: HWalign=64, Order=0-3, MinObjects=0, CPUs=4, Nodes=1
-   [    0.000000] rcu: Hierarchical RCU implementation.
-   [    0.000000] rcu: 	RCU event tracing is enabled.
-   [    0.000000] rcu: 	RCU restricting CPUs from NR_CPUS=8 to nr_cpu_ids=4.
-   [    0.000000] rcu: RCU calculated value of scheduler-enlistment delay is 10 jiffies.
-   [    0.000000] rcu: Adjusting geometry for rcu_fanout_leaf=16, nr_cpu_ids=4
-   [    0.000000] NR_IRQS: 0, nr_irqs: 0, preallocated irqs: 0
-   [    0.000000] plic: mapped 186 interrupts with 4 handlers for 9 contexts.
-   [    0.000000] riscv_timer_init_dt: Registering clocksource cpuid [0] hartid [1]
-   [    0.000000] clocksource: riscv_clocksource: mask: 0xffffffffffffffff max_cycles: 0x1d854df40, max_idle_ns: 3526361616960 ns
-   [    0.000015] sched_clock: 64 bits at 1000kHz, resolution 1000ns, wraps every 2199023255500ns
-   [    0.000311] Calibrating delay loop (skipped), value calculated using timer frequency.. 2.00 BogoMIPS (lpj=10000)
-   [    0.000349] pid_max: default: 32768 minimum: 301
-   [    0.000846] Mount-cache hash table entries: 2048 (order: 2, 16384 bytes, linear)
-   [    0.000964] Mountpoint-cache hash table entries: 2048 (order: 2, 16384 bytes, linear)
-   [    0.005630] rcu: Hierarchical SRCU implementation.
-   [    0.006901] smp: Bringing up secondary CPUs ...
-   [    0.012545] smp: Brought up 1 node, 4 CPUs
-   [    0.014431] devtmpfs: initialized
-   [    0.020526] random: get_random_bytes called from setup_net+0x36/0x192 with crng_init=0
-   [    0.020928] clocksource: jiffies: mask: 0xffffffff max_cycles: 0xffffffff, max_idle_ns: 19112604462750000 ns
-   [    0.020999] futex hash table entries: 1024 (order: 4, 65536 bytes, linear)
-   [    0.022768] NET: Registered protocol family 16
-   [    0.035478] microchip-pfsoc-clkcfg 20002000.clkcfg: Registered PFSOC core clocks
-   [    0.048429] SCSI subsystem initialized
-   [    0.049694] pps_core: LinuxPPS API ver. 1 registered
-   [    0.049719] pps_core: Software ver. 5.3.6 - Copyright 2005-2007 Rodolfo Giometti <[email protected]>
-   [    0.049780] PTP clock support registered
-   [    0.051781] clocksource: Switched to clocksource riscv_clocksource
-   [    0.055326] NET: Registered protocol family 2
-   [    0.056922] tcp_listen_portaddr_hash hash table entries: 512 (order: 1, 8192 bytes, linear)
-   [    0.057053] TCP established hash table entries: 8192 (order: 4, 65536 bytes, linear)
-   [    0.057648] TCP bind hash table entries: 8192 (order: 5, 131072 bytes, linear)
-   [    0.058579] TCP: Hash tables configured (established 8192 bind 8192)
-   [    0.059648] UDP hash table entries: 512 (order: 2, 16384 bytes, linear)
-   [    0.059837] UDP-Lite hash table entries: 512 (order: 2, 16384 bytes, linear)
-   [    0.060707] NET: Registered protocol family 1
-   [    0.266229] workingset: timestamp_bits=62 max_order=18 bucket_order=0
-   [    0.287107] io scheduler mq-deadline registered
-   [    0.287140] io scheduler kyber registered
-   [    0.429601] Serial: 8250/16550 driver, 4 ports, IRQ sharing disabled
-   [    0.433979] printk: console [ttyS0] disabled
-   [    0.434154] 20000000.serial: ttyS0 at MMIO 0x20000000 (irq = 18, base_baud = 9375000) is a 16550A
-   [    0.928039] printk: console [ttyS0] enabled
-   [    0.939804] libphy: Fixed MDIO Bus: probed
-   [    0.948702] libphy: MACB_mii_bus: probed
-   [    0.993698] macb 20112000.ethernet eth0: Cadence GEM rev 0x0107010c at 0x20112000 irq 21 (56:34:12:00:fc:00)
-   [    1.006751] mousedev: PS/2 mouse device common for all mice
-   [    1.013803] i2c /dev entries driver
-   [    1.019451] sdhci: Secure Digital Host Controller Interface driver
-   [    1.027242] sdhci: Copyright(c) Pierre Ossman
-   [    1.032731] sdhci-pltfm: SDHCI platform and OF driver helper
-   [    1.091826] mmc0: SDHCI controller on 20008000.sdhc [20008000.sdhc] using ADMA 64-bit
-   [    1.102738] NET: Registered protocol family 17
-   [    1.170326] Freeing unused kernel memory: 9476K
-   [    1.176067] This architecture does not have kernel memory protection.
-   [    1.184157] Run /init as init process
-   Starting logging: OK
-   Starting mdev...
-   /etc/init.d/S10mdev: line 21: can't create /proc/sys/kernel/hotplug: nonexiste[    1.331981] mmc0: mmc_select_hs200 failed, error -74
-   nt directory
-   [    1.355011] mmc0: new MMC card at address 0001
-   [    1.363981] mmcblk0: mmc0:0001 DG4008 7.28 GiB
-   [    1.372248] mmcblk0boot0: mmc0:0001 DG4008 partition 1 4.00 MiB
-   [    1.382292] mmcblk0boot1: mmc0:0001 DG4008 partition 2 4.00 MiB
-   [    1.390265] mmcblk0rpmb: mmc0:0001 DG4008 partition 3 4.00 MiB, chardev (251:0)
-   [    1.425234] GPT:Primary header thinks Alt. header is not at the end of the disk.
-   [    1.434656] GPT:2255809 != 15273599
-   [    1.439038] GPT:Alternate GPT header not at the end of the disk.
-   [    1.446671] GPT:2255809 != 15273599
-   [    1.451048] GPT: Use GNU Parted to correct GPT errors.
-   [    1.457755]  mmcblk0: p1 p2 p3
-   sort: /sys/devices/platform/Fixed: No such file or directory
-   modprobe: can't change directory to '/lib/modules': No such file or directory
-   Initializing random number generator... [    2.830198] random: dd: uninitialized urandom read (512 bytes read)
-   done.
-   Starting network...
-   [    3.061867] macb 20112000.ethernet eth0: PHY [20112000.ethernet-ffffffff:09] driver [Vitesse VSC8662] (irq=POLL)
-   [    3.074674] macb 20112000.ethernet eth0: configuring for phy/sgmii link mode
-   [    3.084263] pps pps0: new PPS source ptp0
-   [    3.089710] macb 20112000.ethernet: gem-ptp-timer ptp clock registered.
-   udhcpc (v1.24.2) started
-   Sending discover...
-   Sending discover...
-   [    6.380169] macb 20112000.ethernet eth0: Link is Up - 1Gbps/Full - flow control tx
-   Sending discover...
-   Sending select for 192.168.1.2...
-   Lease of 192.168.1.2 obtained, lease time 86400
-   deleting routers
-   adding dns 192.168.1.1
-   Starting dropbear sshd: [   11.385619] random: dropbear: uninitialized urandom read (32 bytes read)
-   OK
-
-   Welcome to Buildroot
-   buildroot login: root
-   Password:
-   #
-
-Booting U-Boot and Linux from eMMC
-----------------------------------
-
-FPGA design with HSS programming file and Linux Image
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-https://github.com/polarfire-soc/polarfire-soc-documentation/blob/master/boards/mpfs-icicle-kit-es/updating-icicle-kit/updating-icicle-kit-design-and-linux.md
-
-The HSS firmware runs from the PolarFire SoC eNVM on reset.
-
-eMMC
-~~~~
-
-Program eMMC with payload binary and Linux image is explained in the
-PolarFire SoC documentation.
-The payload binary should be copied to partition 2 of the eMMC.
-
-(Note: PolarFire SoC Documentation git repo is at https://github.com/polarfire-soc/polarfire-soc-documentation/blob/master/boards/mpfs-icicle-kit-es/updating-icicle-kit/updating-icicle-kit-design-and-linux.md#eMMC)
-
-Once the Linux image and payload binary is copied to the eMMC, press CTRL+C
-in the HSS command line interface, then type 'boot' and enter to boot the newly
-copied payload and Linux image.
-
-.. code-block:: none
-
-    zcat <linux-image>.wic.gz | sudo dd of=/dev/sdX bs=4096 iflag=fullblock oflag=direct conv=fsync status=progress
-
-    sudo dd if=<payload_binary> of=/dev/sdX2 bs=512
-
-You should see the U-Boot prompt on UART1.
-(Note: UART0 is reserved for HSS)
-
-GUID type
-~~~~~~~~~
-
-The HSS always picks up the HSS payload from a GPT partition with
-GUID type "21686148-6449-6E6F-744E-656564454649" or sector '0' of the eMMC if no
-GPT partition.
-
-Sample boot log from MPFS Icicle Kit
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. code-block:: none
-
-   U-Boot 2021.01-00314-g7303332537-dirty (Jan 14 2021 - 10:09:43 +0530)
-
-   CPU:   rv64imafdc
-   Model: Microchip MPFS Icicle Kit
-   DRAM:  1 GiB
-   MMC:   sdhc@20008000: 0
-   In:    serial@20100000
-   Out:   serial@20100000
-   Err:   serial@20100000
-   Net:   eth0: ethernet@20112000
-   Hit any key to stop autoboot:  0
-
-   RISC-V # mmc info
-   Device: sdhc@20008000
-   Manufacturer ID: 45
-   OEM: 100
-   Name: DG400
-   Bus Speed: 52000000
-   Mode: MMC High Speed (52MHz)
-   Rd Block Len: 512
-   MMC version 5.1
-   High Capacity: Yes
-   Capacity: 7.3 GiB
-   Bus Width: 4-bit
-   Erase Group Size: 512 KiB
-   HC WP Group Size: 8 MiB
-   User Capacity: 7.3 GiB WRREL
-   Boot Capacity: 4 MiB ENH
-   RPMB Capacity: 4 MiB ENH
-
-   RISC-V # mmc part
-   Partition Map for MMC device 0  --   Partition Type: EFI
-
-   Part	Start LBA	End LBA		Name
-		Attributes
-		Type GUID
-		Partition GUID
-	1	0x00002000	0x0000b031	"boot"
-		attrs:	0x0000000000000004
-		type:	ebd0a0a2-b9e5-4433-87c0-68b6b72699c7
-		guid:	99ff6a94-f2e7-44dd-a7df-f3a2da106ef9
-	2	0x0000b032	0x0000f031	"primary"
-		attrs:	0x0000000000000000
-		type:	21686148-6449-6e6f-744e-656564454649
-		guid:	12006052-e64b-4423-beb0-b956ea00f1ba
-	3	0x00010000	0x00226b9f	"root"
-		attrs:	0x0000000000000000
-		type:	0fc63daf-8483-4772-8e79-3d69d8477de4
-		guid:	dd2c5619-2272-4c3c-8dc2-e21942e17ce6
-
-   RISC-V # load mmc 0 ${ramdisk_addr_r} fitimage
-   RISC-V # bootm ${ramdisk_addr_r}
-   ## Loading kernel from FIT Image at 88300000 ...
-   Using 'conf@microchip_icicle-kit-es-a000-microchip.dtb' configuration
-   Trying 'kernel@1' kernel subimage
-     Description:  Linux kernel
-     Type:         Kernel Image
-     Compression:  gzip compressed
-     Data Start:   0x883000fc
-     Data Size:    3574555 Bytes = 3.4 MiB
-     Architecture: RISC-V
-     OS:           Linux
-     Load Address: 0x80200000
-     Entry Point:  0x80200000
-     Hash algo:    sha256
-     Hash value:   21f18d72cf2f0a7192220abb577ad25c77c26960052d779aa02bf55dbf0a6403
-   Verifying Hash Integrity ... sha256+ OK
-   ## Loading fdt from FIT Image at 88300000 ...
-   Using 'conf@microchip_icicle-kit-es-a000-microchip.dtb' configuration
-   Trying 'fdt@microchip_icicle-kit-es-a000-microchip.dtb' fdt subimage
-     Description:  Flattened Device Tree blob
-     Type:         Flat Device Tree
-     Compression:  uncompressed
-     Data Start:   0x88668d44
-     Data Size:    9760 Bytes = 9.5 KiB
-     Architecture: RISC-V
-     Load Address: 0x82200000
-     Hash algo:    sha256
-     Hash value:   5c3a9f30d41b6b8e53b47916e1f339b3a4d454006554d1f7e1f552ed62409f4b
-   Verifying Hash Integrity ... sha256+ OK
-   Loading fdt from 0x88668d48 to 0x82200000
-   Booting using the fdt blob at 0x82200000
-   Uncompressing Kernel Image
-   Loading Device Tree to 000000008fffa000, end 000000008ffff61f ... OK
-
-   Starting kernel ...
-
-   [    0.000000] OF: fdt: Ignoring memory range 0x80000000 - 0x80200000
-   [    0.000000] Linux version 5.6.16 (oe-user@oe-host) (gcc version 9.3.0 (GCC)) #1 SMP Fri Oct 9 11:49:47 UTC 2020
-   [    0.000000] earlycon: sbi0 at I/O port 0x0 (options '')
-   [    0.000000] printk: bootconsole [sbi0] enabled
-   [    0.000000] Zone ranges:
-   [    0.000000]   DMA32    [mem 0x0000000080200000-0x00000000bfffffff]
-   [    0.000000]   Normal   empty
-   [    0.000000] Movable zone start for each node
-   [    0.000000] Early memory node ranges
-   [    0.000000]   node   0: [mem 0x0000000080200000-0x00000000bfffffff]
-   [    0.000000] Zeroed struct page in unavailable ranges: 512 pages
-   [    0.000000] Initmem setup node 0 [mem 0x0000000080200000-0x00000000bfffffff]
-   [    0.000000] software IO TLB: mapped [mem 0xb9e00000-0xbde00000] (64MB)
-   [    0.000000] CPU with hartid=0 is not available
-   [    0.000000] CPU with hartid=0 is not available
-   [    0.000000] elf_hwcap is 0x112d
-   [    0.000000] percpu: Embedded 17 pages/cpu s29784 r8192 d31656 u69632
-   [    0.000000] Built 1 zonelists, mobility grouping on.  Total pages: 258055
-   [    0.000000] Kernel command line: earlycon=sbi root=/dev/mmcblk0p3 rootwait console=ttyS0,115200n8 uio_pdrv_genirq.of_id=generic-uio
-   [    0.000000] Dentry cache hash table entries: 131072 (order: 8, 1048576 bytes, linear)
-   [    0.000000] Inode-cache hash table entries: 65536 (order: 7, 524288 bytes, linear)
-   [    0.000000] Sorting __ex_table...
-   [    0.000000] mem auto-init: stack:off, heap alloc:off, heap free:off
-   [    0.000000] Memory: 941440K/1046528K available (4118K kernel code, 280K rwdata, 1687K rodata, 169K init, 273K bss, 105088K reserved, 0K cma-reserved)
-   [    0.000000] SLUB: HWalign=64, Order=0-3, MinObjects=0, CPUs=4, Nodes=1
-   [    0.000000] rcu: Hierarchical RCU implementation.
-   [    0.000000] rcu: 	RCU event tracing is enabled.
-   [    0.000000] rcu: 	RCU restricting CPUs from NR_CPUS=5 to nr_cpu_ids=4.
-   [    0.000000] rcu: RCU calculated value of scheduler-enlistment delay is 10 jiffies.
-   [    0.000000] rcu: Adjusting geometry for rcu_fanout_leaf=16, nr_cpu_ids=4
-   [    0.000000] NR_IRQS: 0, nr_irqs: 0, preallocated irqs: 0
-   [    0.000000] plic: mapped 53 interrupts with 4 handlers for 9 contexts.
-   [    0.000000] riscv_timer_init_dt: Registering clocksource cpuid [0] hartid [1]
-   [    0.000000] clocksource: riscv_clocksource: mask: 0xffffffffffffffff max_cycles: 0x1d854df40, max_idle_ns: 3526361616960 ns
-   [    0.000015] sched_clock: 64 bits at 1000kHz, resolution 1000ns, wraps every 2199023255500ns
-   [    0.008679] Console: colour dummy device 80x25
-   [    0.013112] Calibrating delay loop (skipped), value calculated using timer frequency.. 2.00 BogoMIPS (lpj=10000)
-   [    0.023368] pid_max: default: 32768 minimum: 301
-   [    0.028314] Mount-cache hash table entries: 2048 (order: 2, 16384 bytes, linear)
-   [    0.035766] Mountpoint-cache hash table entries: 2048 (order: 2, 16384 bytes, linear)
-   [    0.047099] rcu: Hierarchical SRCU implementation.
-   [    0.052813] smp: Bringing up secondary CPUs ...
-   [    0.061581] smp: Brought up 1 node, 4 CPUs
-   [    0.067069] devtmpfs: initialized
-   [    0.073621] random: get_random_u32 called from bucket_table_alloc.isra.0+0x4e/0x150 with crng_init=0
-   [    0.074409] clocksource: jiffies: mask: 0xffffffff max_cycles: 0xffffffff, max_idle_ns: 19112604462750000 ns
-   [    0.093399] futex hash table entries: 1024 (order: 4, 65536 bytes, linear)
-   [    0.101879] NET: Registered protocol family 16
-   [    0.110336] microchip-pfsoc-clkcfg 20002000.clkcfg: Registered PFSOC core clocks
-   [    0.132717] usbcore: registered new interface driver usbfs
-   [    0.138225] usbcore: registered new interface driver hub
-   [    0.143813] usbcore: registered new device driver usb
-   [    0.148939] pps_core: LinuxPPS API ver. 1 registered
-   [    0.153929] pps_core: Software ver. 5.3.6 - Copyright 2005-2007 Rodolfo Giometti <[email protected]>
-   [    0.163071] PTP clock support registered
-   [    0.168521] clocksource: Switched to clocksource riscv_clocksource
-   [    0.174927] VFS: Disk quotas dquot_6.6.0
-   [    0.179016] VFS: Dquot-cache hash table entries: 512 (order 0, 4096 bytes)
-   [    0.205536] NET: Registered protocol family 2
-   [    0.210944] tcp_listen_portaddr_hash hash table entries: 512 (order: 1, 8192 bytes, linear)
-   [    0.219393] TCP established hash table entries: 8192 (order: 4, 65536 bytes, linear)
-   [    0.227497] TCP bind hash table entries: 8192 (order: 5, 131072 bytes, linear)
-   [    0.235440] TCP: Hash tables configured (established 8192 bind 8192)
-   [    0.242537] UDP hash table entries: 512 (order: 2, 16384 bytes, linear)
-   [    0.249285] UDP-Lite hash table entries: 512 (order: 2, 16384 bytes, linear)
-   [    0.256690] NET: Registered protocol family 1
-   [    0.262585] workingset: timestamp_bits=62 max_order=18 bucket_order=0
-   [    0.281036] Block layer SCSI generic (bsg) driver version 0.4 loaded (major 249)
-   [    0.288481] io scheduler mq-deadline registered
-   [    0.292983] io scheduler kyber registered
-   [    0.298895] microsemi,mss-gpio 20122000.gpio: Microsemi MSS GPIO registered 32 GPIOs
-   [    0.453723] Serial: 8250/16550 driver, 4 ports, IRQ sharing disabled
-   [    0.462911] printk: console [ttyS0] disabled
-   [    0.467216] 20100000.serial: ttyS0 at MMIO 0x20100000 (irq = 12, base_baud = 9375000) is a 16550A
-   [    0.476201] printk: console [ttyS0] enabled
-   [    0.476201] printk: console [ttyS0] enabled
-   [    0.484576] printk: bootconsole [sbi0] disabled
-   [    0.484576] printk: bootconsole [sbi0] disabled
-   [    0.494920] 20102000.serial: ttyS1 at MMIO 0x20102000 (irq = 13, base_baud = 9375000) is a 16550A
-   [    0.505068] 20104000.serial: ttyS2 at MMIO 0x20104000 (irq = 14, base_baud = 9375000) is a 16550A
-   [    0.533336] loop: module loaded
-   [    0.572284] Rounding down aligned max_sectors from 4294967295 to 4294967288
-   [    0.580000] db_root: cannot open: /etc/target
-   [    0.585413] libphy: Fixed MDIO Bus: probed
-   [    0.591526] libphy: MACB_mii_bus: probed
-   [    0.598060] macb 20112000.ethernet eth0: Cadence GEM rev 0x0107010c at 0x20112000 irq 17 (56:34:12:00:fc:00)
-   [    0.608352] ehci_hcd: USB 2.0 'Enhanced' Host Controller (EHCI) Driver
-   [    0.615001] ehci-platform: EHCI generic platform driver
-   [    0.620446] ohci_hcd: USB 1.1 'Open' Host Controller (OHCI) Driver
-   [    0.626632] ohci-platform: OHCI generic platform driver
-   [    0.632326] usbcore: registered new interface driver cdc_acm
-   [    0.637996] cdc_acm: USB Abstract Control Model driver for USB modems and ISDN adapters
-   [    0.646459] i2c /dev entries driver
-   [    0.650852] microsemi-mss-i2c 2010b000.i2c: Microsemi I2C Probe Complete
-   [    0.658010] sdhci: Secure Digital Host Controller Interface driver
-   [    0.664326] sdhci: Copyright(c) Pierre Ossman
-   [    0.668754] sdhci-pltfm: SDHCI platform and OF driver helper
-   [    0.706845] mmc0: SDHCI controller on 20008000.sdhc [20008000.sdhc] using ADMA 64-bit
-   [    0.715052] usbcore: registered new interface driver usbhid
-   [    0.720722] usbhid: USB HID core driver
-   [    0.725174] pac193x 0-0010: Chip revision: 0x03
-   [    0.733339] pac193x 0-0010: :pac193x_prep_iio_channels: Channel 0 active
-   [    0.740127] pac193x 0-0010: :pac193x_prep_iio_channels: Channel 1 active
-   [    0.746881] pac193x 0-0010: :pac193x_prep_iio_channels: Channel 2 active
-   [    0.753686] pac193x 0-0010: :pac193x_prep_iio_channels: Channel 3 active
-   [    0.760495] pac193x 0-0010: :pac193x_prep_iio_channels: Active chip channels: 25
-   [    0.778006] NET: Registered protocol family 10
-   [    0.784929] Segment Routing with IPv6
-   [    0.788875] sit: IPv6, IPv4 and MPLS over IPv4 tunneling driver
-   [    0.795743] NET: Registered protocol family 17
-   [    0.801191] hctosys: unable to open rtc device (rtc0)
-   [    0.807774] Waiting for root device /dev/mmcblk0p3...
-   [    0.858506] mmc0: mmc_select_hs200 failed, error -74
-   [    0.865764] mmc0: new MMC card at address 0001
-   [    0.872564] mmcblk0: mmc0:0001 DG4008 7.28 GiB
-   [    0.878777] mmcblk0boot0: mmc0:0001 DG4008 partition 1 4.00 MiB
-   [    0.886182] mmcblk0boot1: mmc0:0001 DG4008 partition 2 4.00 MiB
-   [    0.892633] mmcblk0rpmb: mmc0:0001 DG4008 partition 3 4.00 MiB, chardev (247:0)
-   [    0.919029] GPT:Primary header thinks Alt. header is not at the end of the disk.
-   [    0.926448] GPT:2255841 != 15273599
-   [    0.930019] GPT:Alternate GPT header not at the end of the disk.
-   [    0.936029] GPT:2255841 != 15273599
-   [    0.939583] GPT: Use GNU Parted to correct GPT errors.
-   [    0.944800]  mmcblk0: p1 p2 p3
-   [    0.966696] EXT4-fs (mmcblk0p3): INFO: recovery required on readonly filesystem
-   [    0.974105] EXT4-fs (mmcblk0p3): write access will be enabled during recovery
-   [    1.052362] random: fast init done
-   [    1.057961] EXT4-fs (mmcblk0p3): recovery complete
-   [    1.065734] EXT4-fs (mmcblk0p3): mounted filesystem with ordered data mode. Opts: (null)
-   [    1.074002] VFS: Mounted root (ext4 filesystem) readonly on device 179:3.
-   [    1.081654] Freeing unused kernel memory: 168K
-   [    1.086108] This architecture does not have kernel memory protection.
-   [    1.092629] Run /sbin/init as init process
-   [    1.702217] systemd[1]: System time before build time, advancing clock.
-   [    1.754192] systemd[1]: systemd 244.3+ running in system mode. (+PAM -AUDIT -SELINUX +IMA -APPARMOR -SMACK +SYSVINIT +UTMP -LIBCRYPTSETUP -GCRYPT -GNUTLS +ACL +XZ -LZ4 -SECCOMP +BLKID -ELFUTILS +KMOD -IDN2 -IDN -PCRE2 default-hierarchy=hybrid)
-   [    1.776361] systemd[1]: Detected architecture riscv64.
-
-   Welcome to OpenEmbedded nodistro.0!
-
-   [    1.829651] systemd[1]: Set hostname to <icicle-kit-es>.
-   [    2.648597] random: systemd: uninitialized urandom read (16 bytes read)
-   [    2.657485] systemd[1]: Created slice system-getty.slice.
-   [  OK  ] Created slice system-getty.slice.
-   [    2.698779] random: systemd: uninitialized urandom read (16 bytes read)
-   [    2.706317] systemd[1]: Created slice system-serial\x2dgetty.slice.
-   [  OK  ] Created slice system-serial\x2dgetty.slice.
-   [    2.748716] random: systemd: uninitialized urandom read (16 bytes read)
-   [    2.756098] systemd[1]: Created slice User and Session Slice.
-   [  OK  ] Created slice User and Session Slice.
-   [    2.789065] systemd[1]: Started Dispatch Password Requests to Console Directory Watch.
-   [  OK  ] Started Dispatch Password …ts to Console Directory Watch.
-   [    2.828974] systemd[1]: Started Forward Password Requests to Wall Directory Watch.
-   [  OK  ] Started Forward Password R…uests to Wall Directory Watch.
-   [    2.869009] systemd[1]: Reached target Paths.
-   [  OK  ] Reached target Paths.
-   [    2.898808] systemd[1]: Reached target Remote File Systems.
-   [  OK  ] Reached target Remote File Systems.
-   [    2.938771] systemd[1]: Reached target Slices.
-   [  OK  ] Reached target Slices.
-   [    2.968754] systemd[1]: Reached target Swap.
-   [  OK  ] Reached target Swap.
-   [    2.999283] systemd[1]: Listening on initctl Compatibility Named Pipe.
-   [  OK  ] Listening on initctl Compatibility Named Pipe.
-   [    3.060458] systemd[1]: Condition check resulted in Journal Audit Socket being skipped.
-   [    3.069826] systemd[1]: Listening on Journal Socket (/dev/log).
-   [  OK  ] Listening on Journal Socket (/dev/log).
-   [    3.109601] systemd[1]: Listening on Journal Socket.
-   [  OK  ] Listening on Journal Socket.
-   [    3.149868] systemd[1]: Listening on Network Service Netlink Socket.
-   [  OK  ] Listening on Network Service Netlink Socket.
-   [    3.189419] systemd[1]: Listening on udev Control Socket.
-   [  OK  ] Listening on udev Control Socket.
-   [    3.229179] systemd[1]: Listening on udev Kernel Socket.
-   [  OK  ] Listening on udev Kernel Socket.
-   [    3.269520] systemd[1]: Condition check resulted in Huge Pages File System being skipped.
-   [    3.278477] systemd[1]: Condition check resulted in POSIX Message Queue File System being skipped.
-   [    3.288200] systemd[1]: Condition check resulted in Kernel Debug File System being skipped.
-   [    3.302570] systemd[1]: Mounting Temporary Directory (/tmp)...
-            Mounting Temporary Directory (/tmp)...
-   [    3.339226] systemd[1]: Condition check resulted in Create list of static device nodes for the current kernel being skipped.
-   [    3.355883] systemd[1]: Starting File System Check on Root Device...
-            Starting File System Check on Root Device...
-   [    3.407220] systemd[1]: Starting Journal Service...
-            Starting Journal Service...
-   [    3.422441] systemd[1]: Condition check resulted in Load Kernel Modules being skipped.
-   [    3.431770] systemd[1]: Condition check resulted in FUSE Control File System being skipped.
-   [    3.446415] systemd[1]: Mounting Kernel Configuration File System...
-            Mounting Kernel Configuration File System...
-   [    3.458983] systemd[1]: Starting Apply Kernel Variables...
-            Starting Apply Kernel Variables...
-   [    3.471368] systemd[1]: Starting udev Coldplug all Devices...
-            Starting udev Coldplug all Devices...
-   [    3.491071] systemd[1]: Mounted Temporary Directory (/tmp).
-   [  OK      3.498114] systemd[1]: Mounted Kernel Configuration File System.
-   0m] Mounted Temporary Directory (/tmp).
-   [  OK  ] Mounted Kernel Configuration File System.
-   [    3.550853] systemd[1]: Started Apply Kernel Variables.
-   [  OK      3.557535] systemd[1]: Started Journal Service.
-   0m] Started Apply Kernel Variables.
-   [  OK  ] Started Journal Service.
-   [  OK  ] Started udev Coldplug all Devices.
-   [  OK  ] Started File System Check on Root Device.
-            Starting Remount Root and Kernel File Systems...
-   [    8.133469] EXT4-fs (mmcblk0p3): re-mounted. Opts: (null)
-   [  OK  ] Started Remount Root and Kernel File Systems.
-            Starting Flush Journal to Persistent Storage...
-   [    8.215327] systemd-journald[77]: Received client request to flush runtime journal.
-            Starting Create Static Device Nodes in /dev...
-   [  OK  ] Started Flush Journal to Persistent Storage.
-   [  OK  ] Started Create Static Device Nodes in /dev.
-   [  OK  ] Reached target Local File Systems (Pre).
-            Mounting /var/volatile...
-            Starting udev Kernel Device Manager...
-   [  OK  ] Mounted /var/volatile.
-            Starting Load/Save Random Seed...
-   [  OK  ] Reached target Local File Systems.
-            Starting Create Volatile Files and Directories...
-   [  OK  ] Started udev Kernel Device Manager.
-   [  OK  ] Started Create Volatile Files and Directories.
-            Starting Network Time Synchronization...
-            Starting Update UTMP about System Boot/Shutdown...
-   [  OK  ] Started Update UTMP about System Boot/Shutdown.
-   [  OK  ] Started Network Time Synchronization.
-   [   11.618575] random: crng init done
-   [   11.622007] random: 7 urandom warning(s) missed due to ratelimiting
-   [  OK  ] Started Load/Save Random Seed.
-   [  OK  ] Reached target System Initialization.
-   [  OK  ] Started Daily Cleanup of Temporary Directories.
-   [  OK  ] Reached target System Time Set.
-   [  OK  ] Reached target System Time Synchronized.
-   [  OK  ] Reached target Timers.
-   [  OK  ] Listening on D-Bus System Message Bus Socket.
-   [  OK  ] Listening on dropbear.socket.
-   [  OK  ] Reached target Sockets.
-   [  OK  ] Reached target Basic System.
-   [  OK  ] Started D-Bus System Message Bus.
-            Starting IPv6 Packet Filtering Framework...
-            Starting IPv4 Packet Filtering Framework...
-            Starting Login Service...
-   [  OK  ] Started IPv6 Packet Filtering Framework.
-   [  OK  ] Started IPv4 Packet Filtering Framework.
-   [  OK  ] Reached target Network (Pre).
-            Starting Network Service...
-   [  OK  ] Started Login Service.
-   [   12.602455] macb 20112000.ethernet eth0: PHY [20112000.ethernet-ffffffff:09] driver [Vitesse VSC8662] (irq=POLL)
-   [   12.612795] macb 20112000.ethernet eth0: configuring for phy/sgmii link mode
-   [   12.622153] pps pps0: new PPS source ptp0
-   [  OK     12.626725] macb 20112000.ethernet: gem-ptp-timer ptp clock registered.
-   0m] Started Network Service.
-            Starting Network Name Resolution...
-   [  OK  ] Started Network Name Resolution.
-   [  OK  ] Reached target Network.
-   [  OK  ] Reached target Host and Network Name Lookups.
-   [  OK  ] Started Collectd.
-   [  OK  ] Started Collectd.
-            Starting Permit User Sessions...
-   [  OK  ] Started Permit User Sessions.
-   [  OK  ] Started Getty on tty1.
-   [  OK  ] Started Serial Getty on ttyS0.
-   [  OK  ] Reached target Login Prompts.
-   [  OK  ] Reached target Multi-User System.
-            Starting Update UTMP about System Runlevel Changes...
-   [  OK  ] Started Update UTMP about System Runlevel Changes.
-
-   OpenEmbedded nodistro.0 icicle-kit-es ttyS0
-
-   icicle-kit-es login: [   15.795564] macb 20112000.ethernet eth0: Link is Up - 1Gbps/Full - flow control tx
-   [   15.803306] IPv6: ADDRCONF(NETDEV_CHANGE): eth0: link becomes ready
-
-   icicle-kit-es login: root
-   root@icicle-kit-es:~#
+.. include:: mpfs_common.rst
diff --git a/doc/board/microchip/mpfs_video.rst b/doc/board/microchip/mpfs_video.rst
new file mode 100644
index 00000000000..25df63ff14b
--- /dev/null
+++ b/doc/board/microchip/mpfs_video.rst
@@ -0,0 +1,105 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+Microchip PolarFire SoC Video Kit
+==================================
+
+RISC-V PolarFire SoC
+--------------------
+
+The PolarFire SoC is the 4+1 64-bit RISC-V SoC from Microchip.
+
+The Video Kit development platform is based on PolarFire SoC and capable
+of running Linux.
+
+Mainline support
+----------------
+
+The support for following drivers are already enabled:
+
+1. NS16550 UART Driver.
+2. Microchip Clock Driver.
+3. Cadence MACB ethernet driver for networking support.
+4. Cadence MMC Driver for eMMC/SD support.
+5. Microchip I2C Driver.
+
+.. include:: mpfs_build_boot.rst
+
+Microchip boot-flow
+~~~~~~~~~~~~~~~~~~~
+
+HSS with OpenSBI (M-Mode) -> U-Boot (S-Mode) -> Linux (S-Mode)
+
+Build the HSS (Hart Software Services) - Microchip boot-flow
+''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+(Note: HSS git repo is at https://github.com/polarfire-soc/hart-software-services)
+
+1. Configure
+
+.. code-block:: none
+
+   make BOARD=mpfs-video-kit config
+
+Alternatively, copy the default config for Microchip boot-flow.
+
+.. code-block:: none
+
+   cp boards/mpfs-video-kit/def_config .config
+
+2. make BOARD=mpfs-video-kit
+3. In the Default subdirectory, the standard build will create hss.elf and
+   various binary formats (hss.hex and hss.bin).
+
+The FPGA design will use the hss.hex or hss.bin.
+
+.. include:: mpfs_design_hss.rst
+
+Custom boot-flow
+~~~~~~~~~~~~~~~~
+
+HSS without OpenSBI (M-Mode) -> OpenSBI (M-Mode) -> U-Boot (S-Mode) -> Linux (S-Mode)
+
+Build OpenSBI
+'''''''''''''
+
+1. Get the OpenSBI source
+
+.. code-block:: none
+
+   git clone https://github.com/riscv/opensbi.git
+   cd opensbi
+
+2. Build
+
+.. code-block:: none
+
+   make PLATFORM=generic FW_PAYLOAD_PATH=<u-boot-directory>/u-boot.bin
+   FW_FDT_PATH=<u-boot-directory>/dts/upstream/src/riscv/microchip/mpfs-sev-kit-.dtb
+
+3. Output "fw_payload.bin" file available at
+   "<opensbi-directory>/build/platform/generic/firmware/fw_payload.bin"
+
+Build the HSS (Hart Software Services)- Custom boot-flow
+''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+(Note: HSS git repo is at https://github.com/polarfire-soc/hart-software-services)
+
+1. Configure
+
+.. code-block:: none
+
+   make BOARD=mpfs-video-kit config
+
+Alternatively, copy the default custom config for Custom boot-flow.
+
+.. code-block:: none
+
+   cp boards/mpfs-video-kit/def_config_custom .config
+
+2. make BOARD=mpfs-video-kit
+3. In the Default subdirectory, the standard build will create hss.elf and
+   various binary formats (hss.hex and hss.bin).
+
+The FPGA design will use the hss.hex or hss.bin.
+
+.. include:: mpfs_common.rst
diff --git a/doc/board/nxp/imx93_frdm.rst b/doc/board/nxp/imx93_frdm.rst
index a1f526fd4cc..3c3e5f49b04 100644
--- a/doc/board/nxp/imx93_frdm.rst
+++ b/doc/board/nxp/imx93_frdm.rst
@@ -13,6 +13,7 @@ Quick Start
 - Get ahab-container.img
 - Build U-Boot
 - Boot from the SD card
+- Boot using USB serial download (uuu)
 
 Get and Build the ARM Trusted firmware
 --------------------------------------
@@ -73,3 +74,24 @@ Boot from the SD card
   at /dev/ttyACM0.
 - Power on the board by connecting a USB Type-C cable into the P1
   Power USB Port.
+
+Boot using USB serial download (uuu)
+------------------------------------
+
+- Configure SW1 boot switches to serial download boot mode:
+  0001 SW1[3:0] - ("Serial downloader (USB)" Boot Mode)
+- Plug USB Type-C cable into the P2 device port.
+- Connect a USB Type-C cable into the P16 Debug USB Port and connect
+  using a terminal emulator at 115200 bps, 8n1. The console will show up
+  at /dev/ttyACM0.
+- Power on the board by connecting a USB Type-C cable into the P1
+  Power USB Port.
+- Use NXP Universal Update Utility `NXP Universal Update Utility`_ to boot or
+  flash the device. E.g. following command can be used to flash an image onto
+  the eMMC storage:
+
+.. code-block:: bash
+
+   $ uuu -V -b emmc_all <image file>
+
+.. _`NXP Universal Update Utility`: https://github.com/nxp-imx/mfgtools
diff --git a/doc/board/nxp/imx943_evk.rst b/doc/board/nxp/imx943_evk.rst
new file mode 100644
index 00000000000..651db08a0f7
--- /dev/null
+++ b/doc/board/nxp/imx943_evk.rst
@@ -0,0 +1,112 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+imx943_evk
+=======================
+
+U-Boot for the NXP i.MX943 19x19 EVK board
+
+Quick Start
+-----------
+
+- Get ahab-container.img
+- Get DDR PHY Firmware Images
+- Get and Build OEI Images
+- Get and Build System Manager Image
+- Get and Build the ARM Trusted Firmware
+- Build the Bootloader Image
+- Boot
+
+Get ahab-container.img
+--------------------------------------
+
+Note: srctree is U-Boot source directory
+
+.. code-block:: bash
+
+   $ wget https://www.nxp.com/lgfiles/NMG/MAD/YOCTO/firmware-ele-imx-2.0.2-89161a8.bin
+   $ sh firmware-ele-imx-2.0.2-89161a8.bin --auto-accept
+   $ cp firmware-ele-imx-2.0.2-89161a8/mx943a0-ahab-container.img $(srctree)
+
+Get DDR PHY Firmware Images
+--------------------------------------
+
+Note: srctree is U-Boot source directory
+
+.. code-block:: bash
+
+   $ wget https://www.nxp.com/lgfiles/NMG/MAD/YOCTO/firmware-imx-8.28-994fa14.bin
+   $ sh firmware-imx-8.28-994fa14.bin --auto-accept
+   $ cp firmware-imx-8.28-994fa14/firmware/ddr/synopsys/lpddr5*v202409.bin $(srctree)
+
+Get and Build OEI Images
+--------------------------------------
+
+Note: srctree is U-Boot source directory
+Get OEI from: https://github.com/nxp-imx/imx-oei
+branch: master
+
+.. code-block:: bash
+
+   $ sudo apt -y install make gcc g++-multilib srecord
+   $ wget https://developer.arm.com/-/media/Files/downloads/gnu/13.3.rel1/binrel/arm-gnu-toolchain-13.3.rel1-x86_64-arm-none-eabi.tar.xz
+   $ tar xvf arm-gnu-toolchain-13.3.rel1-x86_64-arm-none-eabi.tar.xz
+   $ export TOOLS=$PWD
+   $ git clone -b master https://github.com/nxp-imx/imx-oei.git
+   $ cd imx-oei
+   $ make board=mx943lp5-19 oei=ddr DEBUG=1 all
+   $ cp build/mx943lp5-19/ddr/oei-m33-ddr.bin $(srctree)
+
+Get and Build System Manager Image
+--------------------------------------
+
+Note: srctree is U-Boot source directory
+Get System Manager from: https://github.com/nxp-imx/imx-sm
+branch: master
+
+.. code-block:: bash
+
+   $ sudo apt -y install make gcc g++-multilib srecord
+   $ wget https://developer.arm.com/-/media/Files/downloads/gnu/13.3.rel1/binrel/arm-gnu-toolchain-13.3.rel1-x86_64-arm-none-eabi.tar.xz
+   $ tar xvf arm-gnu-toolchain-13.3.rel1-x86_64-arm-none-eabi.tar.xz
+   $ export TOOLS=$PWD
+   $ git clone -b master https://github.com/nxp-imx/imx-sm.git
+   $ cd imx-sm
+   $ make config=mx94evk all
+   $ cp build/mx94evk/m33_image.bin $(srctree)
+
+Get and Build the ARM Trusted Firmware
+--------------------------------------
+
+Note: srctree is U-Boot source directory
+Get ATF from: https://github.com/nxp-imx/imx-atf/
+branch: lf_v2.12
+
+.. code-block:: bash
+
+   $ export CROSS_COMPILE=aarch64-poky-linux-
+   $ unset LDFLAGS
+   $ unset AS
+   $ git clone -b lf_v2.12 https://github.com/nxp-imx/imx-atf.git
+   $ cd imx-atf
+   $ make PLAT=imx94 bl31
+   $ cp build/imx94/release/bl31.bin $(srctree)
+
+Build the Bootloader Image
+--------------------------
+
+.. code-block:: bash
+
+   $ export CROSS_COMPILE=aarch64-poky-linux-
+   $ make imx943_evk_defconfig
+   $ make
+
+Copy flash.bin to the MicroSD card:
+
+.. code-block:: bash
+
+   $ sudo dd if=flash.bin of=/dev/sd[x] bs=1k seek=32 conv=fsync
+
+Boot
+----
+
+Set i.MX943 boot device to MicroSD card
diff --git a/doc/board/nxp/index.rst b/doc/board/nxp/index.rst
index aa7d857346d..670501164b5 100644
--- a/doc/board/nxp/index.rst
+++ b/doc/board/nxp/index.rst
@@ -16,6 +16,7 @@ NXP Semiconductors
    imx93_9x9_qsb
    imx93_11x11_evk
    imx93_frdm
+   imx943_evk
    imx95_evk
    imxrt1020-evk
    imxrt1050-evk
diff --git a/doc/board/phytec/imx8mm-optee-build.rsti b/doc/board/phytec/imx8mm-optee-build.rsti
deleted file mode 100644
index c83de5cc7cf..00000000000
--- a/doc/board/phytec/imx8mm-optee-build.rsti
+++ /dev/null
@@ -1,14 +0,0 @@
-Build the OP-TEE binary (optional)
-----------------------------------
-
-.. code-block:: bash
-
-   $ git clone https://github.com/OP-TEE/optee_os.git
-   $ cd optee_os
-   $ make CFG_TEE_BENCHMARK=n \
-     CROSS_COMPILE=aarch64-linux-gnu- \
-     O=out/arm \
-     PLATFORM=imx-mx8mmevk \
-     CFG_TZDRAM_START=0x56000000 \
-     CFG_DDR_SIZE=0x80000000 \
-     CFG_UART_BASE=UART3_BASE
diff --git a/doc/board/phytec/imx8mm-phygate-tauri-l.rst b/doc/board/phytec/imx8mm-phygate-tauri-l.rst
index 0d9e1024f8c..3a09be7075a 100644
--- a/doc/board/phytec/imx8mm-phygate-tauri-l.rst
+++ b/doc/board/phytec/imx8mm-phygate-tauri-l.rst
@@ -9,7 +9,7 @@ Quick Start
 -----------
 
 - Build the ARM Trusted firmware binary
-- Build the OP-TEE binary (optional)
+- Build the OP-TEE binary
 - Get ddr firmware
 - Build U-Boot
 - Boot
@@ -21,23 +21,34 @@ Build the ARM Trusted firmware binary
 
    $ git clone https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git
    $ cd trusted-firmware-a
-   $ export CROSS_COMPILE=aarch64-linux-gnu-
-   $ export IMX_BOOT_UART_BASE=0x30880000
-   $ # with optee
-   $ make PLAT=imx8mm BL32_BASE=0x56000000 SPD=opteed bl31
-   $ # without optee
-   $ make PLAT=imx8mm bl31
+   $ make -j $(nproc) \
+          CROSS_COMPILE=aarch64-linux-gnu- \
+          PLAT=imx8mm \
+          IMX_BOOT_UART_BASE=0x30880000 \
+          BL32_BASE=0xbe000000 \
+          SPD=opteed \
+          bl31
 
-.. include:: imx8mm-optee-build.rsti
+Build the OP-TEE binary
+-----------------------
+
+.. code-block:: bash
+
+   $ git clone https://github.com/OP-TEE/optee_os.git
+   $ cd optee_os
+   $ make -j $(nproc) \
+          CROSS_COMPILE=aarch64-linux-gnu- \
+          O=out/arm \
+          PLATFORM=imx-mx8mm_phygate_tauri_l
 
 Get the ddr firmware
 --------------------
 
 .. code-block:: bash
 
-   $ wget https://www.nxp.com/lgfiles/NMG/MAD/YOCTO/firmware-imx-8.23.bin
-   $ chmod +x firmware-imx-8.23.bin
-   $ ./firmware-imx-8.23.bin
+   $ wget https://www.nxp.com/lgfiles/NMG/MAD/YOCTO/firmware-imx-8.28-994fa14.bin
+   $ chmod +x firmware-imx-8.28-994fa14.bin
+   $ ./firmware-imx-8.28-994fa14.bin
 
 Build U-Boot for SD card
 ------------------------
@@ -49,15 +60,17 @@ Copy binaries
 
    $ cp <TF-A dir>/build/imx8mm/release/bl31.bin .
    $ cp <OP-TEE dir>/out/arm/core/tee-raw.bin tee.bin
-   $ cp firmware-imx-8.23/firmware/ddr/synopsys/lpddr4*.bin .
+   $ cp firmware-imx-8.28-994fa14/firmware/ddr/synopsys/lpddr4*.bin .
 
 Build U-Boot
 ^^^^^^^^^^^^
 
 .. code-block:: bash
 
-   $ make imx8mm-phygate-tauri-l_defconfig
-   $ make flash.bin
+   $ make -j $(nproc)
+          CROSS_COMPILE=aarch64-linux-gnu- \
+          imx8mm-phygate-tauri-l_defconfig \
+          flash.bin
 
 Flash SD card
 ^^^^^^^^^^^^^
diff --git a/doc/board/phytec/imx8mp-libra-fpsc.rst b/doc/board/phytec/imx8mp-libra-fpsc.rst
new file mode 100644
index 00000000000..87b7a99ee71
--- /dev/null
+++ b/doc/board/phytec/imx8mp-libra-fpsc.rst
@@ -0,0 +1,82 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+Libra i.MX 8M Plus FPSC
+=======================
+
+The Libra i.MX 8M Plus FPSC is a SBC based with the phyCORE-i.MX 8M Plus FPSC
+SoM.
+The phyCORE-i.MX 8M Plus FPSC with 2GB of main memory is supported.
+
+Quick Start
+-----------
+
+- Build the ARM Trusted firmware binary
+- Build the OP-TEE binary
+- Get ddr firmware
+- Build U-Boot
+- Boot
+
+Build the ARM Trusted firmware binary
+-------------------------------------
+
+.. code-block:: bash
+
+   $ git clone https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git
+   $ cd trusted-firmware-a
+   $ make -j $(nproc) \
+          CROSS_COMPILE=aarch64-linux-gnu- \
+          PLAT=imx8mp \
+          IMX_BOOT_UART_BASE=0x30a60000 \
+          BL32_BASE=0x7e000000 \
+          SPD=opteed \
+          bl31
+
+Build the OP-TEE binary
+-----------------------
+
+.. code-block:: bash
+
+   $ git clone https://github.com/OP-TEE/optee_os.git
+   $ cd optee_os
+   $ make -j $(nproc) \
+          CROSS_COMPILE=aarch64-linux-gnu- \
+          O=out/arm \
+          PLATFORM=imx-mx8mp_libra_fpsc
+
+Get the ddr firmware
+--------------------
+
+.. code-block:: bash
+
+   $ wget https://www.nxp.com/lgfiles/NMG/MAD/YOCTO/firmware-imx-8.28-994fa14.bin
+   $ chmod +x firmware-imx-8.28-994fa14.bin
+   $ ./firmware-imx-8.28-994fa14.bin
+
+Build U-Boot for SD card
+------------------------
+
+Copy binaries
+^^^^^^^^^^^^^
+
+.. code-block:: bash
+
+   $ cp <TF-A dir>/build/imx8mp/release/bl31.bin .
+   $ cp <OP-TEE dir>/out/arm/core/tee-raw.bin tee.bin
+   $ cp firmware-imx-8.28-994fa14/firmware/ddr/synopsys/lpddr4*.bin .
+
+Build U-Boot
+^^^^^^^^^^^^
+
+.. code-block:: bash
+
+   $ make -j $(nproc) \
+          CROSS_COMPILE=aarch64-linux-gnu- \
+          imx8mp-libra-fpsc_defconfig \
+          flash.bin
+
+Flash SD card
+^^^^^^^^^^^^^
+
+.. code-block:: bash
+
+   $ sudo dd if=flash.bin of=/dev/sd[x] bs=1024 seek=32 conv=fsync
diff --git a/doc/board/phytec/index.rst b/doc/board/phytec/index.rst
index 1ae30c2dcd5..e24040a496e 100644
--- a/doc/board/phytec/index.rst
+++ b/doc/board/phytec/index.rst
@@ -6,6 +6,7 @@ PHYTEC
 .. toctree::
    :maxdepth: 2
 
+   imx8mp-libra-fpsc
    imx8mm-phygate-tauri-l
    imx93-phycore
    phycore-am62x
diff --git a/doc/board/phytec/phycore-imx8mm.rst b/doc/board/phytec/phycore-imx8mm.rst
index 08f5949e02d..0784154e710 100644
--- a/doc/board/phytec/phycore-imx8mm.rst
+++ b/doc/board/phytec/phycore-imx8mm.rst
@@ -9,7 +9,7 @@ Quick Start
 -----------
 
 - Build the ARM Trusted firmware binary
-- Build the OP-TEE binary (optional)
+- Build the OP-TEE binary
 - Get ddr firmware
 - Build U-Boot
 - Boot
@@ -21,23 +21,34 @@ Build the ARM Trusted firmware binary
 
    $ git clone https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git
    $ cd trusted-firmware-a
-   $ export CROSS_COMPILE=aarch64-linux-gnu-
-   $ export IMX_BOOT_UART_BASE=0x30880000
-   $ # with optee
-   $ make PLAT=imx8mm BL32_BASE=0x56000000 SPD=opteed bl31
-   $ # without optee
-   $ make PLAT=imx8mm bl31
+   $ make -j $(nproc) \
+          CROSS_COMPILE=aarch64-linux-gnu- \
+          PLAT=imx8mm \
+          IMX_BOOT_UART_BASE=0x30880000 \
+          BL32_BASE=0x7e000000 \
+          SPD=opteed \
+          bl31
 
-.. include:: imx8mm-optee-build.rsti
+Build the OP-TEE binary
+-----------------------
+
+.. code-block:: bash
+
+   $ git clone https://github.com/OP-TEE/optee_os.git
+   $ cd optee_os
+   $ make -j $(nproc) \
+          CROSS_COMPILE=aarch64-linux-gnu- \
+          O=out/arm \
+          PLATFORM=imx-mx8mm_phyboard_polis
 
 Get the ddr firmware
 --------------------
 
 .. code-block:: bash
 
-   $ wget https://www.nxp.com/lgfiles/NMG/MAD/YOCTO/firmware-imx-8.19.bin
-   $ chmod +x firmware-imx-8.19.bin
-   $ ./firmware-imx-8.19.bin
+   $ wget https://www.nxp.com/lgfiles/NMG/MAD/YOCTO/firmware-imx-8.28-994fa14.bin
+   $ chmod +x firmware-imx-8.28-994fa14.bin
+   $ ./firmware-imx-8.28-994fa14.bin
 
 Build U-Boot for SD card
 ------------------------
@@ -48,15 +59,18 @@ Copy binaries
 .. code-block:: bash
 
    $ cp <TF-A dir>/build/imx8mm/release/bl31.bin .
-   $ cp firmware-imx-8.19/firmware/ddr/synopsys/lpddr4*.bin .
+   $ cp <OP-TEE dir>/out/arm/core/tee-raw.bin tee.bin
+   $ cp firmware-imx-8.28-994fa14/firmware/ddr/synopsys/lpddr4*.bin .
 
 Build U-Boot
 ^^^^^^^^^^^^
 
 .. code-block:: bash
 
-   $ make phycore-imx8mm_defconfig
-   $ make flash.bin
+   $ make -j $(nproc) \
+          CROSS_COMPILE=aarch64-linux-gnu- \
+          phycore-imx8mm_defconfig \
+          flash.bin
 
 Flash SD card
 ^^^^^^^^^^^^^
diff --git a/doc/board/phytec/phycore-imx8mp.rst b/doc/board/phytec/phycore-imx8mp.rst
index 50be9912653..0252cbd0824 100644
--- a/doc/board/phytec/phycore-imx8mp.rst
+++ b/doc/board/phytec/phycore-imx8mp.rst
@@ -3,13 +3,13 @@
 phyCORE-i.MX 8M Plus
 ====================
 
-The phyCORE-i.MX 8M Plus with 2GB of main memory is supported.
+The phyCORE-i.MX 8M Plus with 1,2,4GB of main memory is supported.
 
 Quick Start
 -----------
 
 - Build the ARM Trusted firmware binary
-- Build the OP-TEE binary (optional)
+- Build the OP-TEE binary
 - Get ddr firmware
 - Build U-Boot
 - Boot
@@ -21,34 +21,34 @@ Build the ARM Trusted firmware binary
 
    $ git clone https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git
    $ cd trusted-firmware-a
-   $ export CROSS_COMPILE=aarch64-linux-gnu-
-   $ export IMX_BOOT_UART_BASE=0x30860000
-   $ # with optee
-   $ make PLAT=imx8mp SPD=opteed bl31
-   $ # without optee
-   $ make PLAT=imx8mp bl31
+   $ make -j $(nproc) \
+          CROSS_COMPILE=aarch64-linux-gnu- \
+          PLAT=imx8mp \
+          IMX_BOOT_UART_BASE=0x30860000 \
+          BL32_BASE=0x7e000000 \
+          SPD=opteed \
+          bl31
 
-Build the OP-TEE binary (optional)
-----------------------------------
+Build the OP-TEE binary
+-----------------------
 
 .. code-block:: bash
 
    $ git clone https://github.com/OP-TEE/optee_os.git
    $ cd optee_os
-   $ make CFG_TEE_BENCHMARK=n \
-     CROSS_COMPILE=aarch64-linux-gnu- \
-     O=out/arm \
-     PLATFORM=imx-mx8mp_phyboard_pollux \
-     CFG_TZDRAM_START=0x56000000
+   $ make -j $(nproc) \
+          CROSS_COMPILE=aarch64-linux-gnu- \
+          O=out/arm \
+          PLATFORM=imx-mx8mp_phyboard_pollux
 
 Get the ddr firmware
 --------------------
 
 .. code-block:: bash
 
-   $ wget https://www.nxp.com/lgfiles/NMG/MAD/YOCTO/firmware-imx-8.19.bin
-   $ chmod +x firmware-imx-8.19.bin
-   $ ./firmware-imx-8.19.bin
+   $ wget https://www.nxp.com/lgfiles/NMG/MAD/YOCTO/firmware-imx-8.28-994fa14.bin
+   $ chmod +x firmware-imx-8.28-994fa14.bin
+   $ ./firmware-imx-8.28-994fa14.bin
 
 Build U-Boot for SD card
 ------------------------
@@ -60,15 +60,17 @@ Copy binaries
 
    $ cp <TF-A dir>/build/imx8mp/release/bl31.bin .
    $ cp <OP-TEE dir>/out/arm/core/tee-raw.bin tee.bin
-   $ cp firmware-imx-8.19/firmware/ddr/synopsys/lpddr4*.bin .
+   $ cp firmware-imx-8.28-994fa14/firmware/ddr/synopsys/lpddr4*.bin .
 
 Build U-Boot
 ^^^^^^^^^^^^
 
 .. code-block:: bash
 
-   $ make phycore-imx8mp_defconfig
-   $ make flash.bin
+   $ make -j $(nproc) \
+          CROSS_COMPILE=aarch64-linux-gnu- \
+          phycore-imx8mp_defconfig \
+          flash.bin
 
 Flash SD card
 ^^^^^^^^^^^^^
diff --git a/doc/develop/codingstyle.rst b/doc/develop/codingstyle.rst
index 8ed6babe455..013bfebf7e4 100644
--- a/doc/develop/codingstyle.rst
+++ b/doc/develop/codingstyle.rst
@@ -12,8 +12,9 @@ or only minimal changes.
 The following rules apply:
 
 * All contributions to U-Boot should conform to the `Linux kernel
-  coding style <https://www.kernel.org/doc/html/latest/process/coding-style.html>`_
-  and the `Lindent script <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/scripts/Lindent>`_.
+  coding style <https://www.kernel.org/doc/html/latest/process/coding-style.html>`_.
+  U-Boot includes a `.clang-format` configuration file that can be used to
+  automatically format code according to these standards.
   * The exception for net files to the `multi-line comment
   <https://www.kernel.org/doc/html/latest/process/coding-style.html#commenting>`_
   applies only to Linux, not to U-Boot. Only large hunks which are copied
@@ -73,6 +74,82 @@ The following rules apply:
   issues are resolved *before* posting on the mailing list. For more information,
   read :doc:`checkpatch`.
 
+Code Formatting with clang-format
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+U-Boot provides a `.clang-format` configuration file that was copied directly
+from the Linux kernel without any modifications, ensuring complete compatibility
+with kernel coding standards. Here are common ways to use clang-format:
+
+**Basic usage for single files:**
+
+.. code-block:: bash
+
+   clang-format -style=file -i <file>
+
+**Format multiple files:**
+
+.. code-block:: bash
+
+   find . -name '*.c' -o -name '*.h' | xargs clang-format -style=file -i
+
+**Integration with git (format only staged changes):**
+
+.. code-block:: bash
+
+   git clang-format
+
+**Editor integration examples:**
+
+* **Vim/Neovim:** Install vim-clang-format plugin
+* **Emacs:** Use clang-format.el
+* **VSCode:** Install "Clang-Format" extension
+* **Most IDEs:** Have built-in or plugin support for clang-format
+
+The `.clang-format` file in the repository root ensures consistent formatting
+across the entire codebase and aligns with Linux kernel coding standards.
+
+**Disabling clang-format for specific code blocks:**
+
+In some cases, you may want to disable automatic formatting for specific code
+sections, such as carefully formatted tables, assembly code, or imported code
+from other projects. Use the following comments to control formatting:
+
+.. code-block:: c
+
+   // clang-format off
+   static const struct register_config regs[] = {
+       { 0x1000, 0x12345678 },  // Base address register
+       { 0x1004, 0xabcdef00 },  // Control register
+       { 0x1008, 0x00000001 },  // Status register
+   };
+   // clang-format on
+
+**Controversial aspects of coding style enforcement:**
+
+Coding style enforcement can be controversial, and it's difficult to have one
+configuration that satisfies everyone's personal preferences. The goal of using
+clang-format is consistency across the codebase rather than accommodating
+individual preferences. While some developers may disagree with specific
+formatting choices, maintaining a uniform style throughout the project makes
+code more readable and maintainable for the entire development community.
+
+**Best practices for formatting:**
+
+When using clang-format to format code, consider these best practices:
+
+* **Format only changed blocks:** It's preferred to format only the blocks of
+  code that have been modified rather than entire files. This keeps diffs
+  focused on actual changes and makes code reviews easier.
+
+* **Separate formatting commits:** If you need to format entire files, create
+  a separate commit containing only formatting changes. This allows reviewers
+  to easily distinguish between functional changes and pure formatting updates.
+
+* **Use git clang-format:** The ``git clang-format`` command is particularly
+  useful as it formats only the lines that have been modified in your current
+  changes, avoiding unnecessary formatting of unchanged code.
+
 * Source files originating from different projects (for example the MTD
   subsystem or the hush shell code from the BusyBox project) may, after
   careful consideration, be exempted from these rules. For such files, the
diff --git a/doc/develop/falcon.rst b/doc/develop/falcon.rst
index 244b4ccb5c2..5689d5b93a7 100644
--- a/doc/develop/falcon.rst
+++ b/doc/develop/falcon.rst
@@ -22,7 +22,7 @@ copies U-Boot image into the memory.
 
 The Falcon Mode extends this way allowing to start the Linux kernel directly
 from SPL. A new command is added to U-Boot to prepare the parameters that SPL
-must pass to the kernel, using ATAGS or Device Tree.
+must pass to the kernel using a Device Tree.
 
 In normal mode, these parameters are generated each time before
 loading the kernel, passing to Linux the address in memory where
@@ -117,10 +117,7 @@ spl - SPL configuration
 
 Usage::
 
-    spl export <img=atags|fdt> [kernel_addr] [initrd_addr] [fdt_addr ]
-
-img
-    "atags" or "fdt"
+    spl export fdt [kernel_addr] [initrd_addr] [fdt_addr ]
 
 kernel_addr
     kernel is loaded as part of the boot process, but it is not started.
@@ -134,11 +131,11 @@ fdt_addr
     in case of fdt, the address of the device tree.
 
 The *spl export* command does not write to a storage media. The user is
-responsible to transfer the gathered information (assembled ATAGS list
-or prepared FDT) from temporary storage in RAM into persistent storage
-after each run of *spl export*. Unfortunately the position of temporary
-storage can not be predicted nor provided at command line, it depends
-highly on your system setup and your provided data (ATAGS or FDT).
+responsible to transfer the gathered information (prepared FDT) from temporary
+storage in RAM into persistent storage after each run of *spl export*.
+Unfortunately the position of temporary storage can not be predicted nor
+provided at command line, it depends highly on your system setup and your
+provided device tree.
 However at the end of an successful *spl export* run it will print the
 RAM address of temporary storage. The RAM address of FDT will also be
 set in the environment variable *fdtargsaddr*, the new length of the
@@ -152,73 +149,6 @@ to the pre-defined address in persistent storage
 The following example shows how to prepare the data for Falcon Mode on
 twister board with ATAGS BLOB.
 
-The *spl export* command is prepared to work with ATAGS and FDT. However,
-using FDT is at the moment untested. The ppc port (see a3m071 example
-later) prepares the fdt blob with the fdt command instead.
-
-
-Usage on the twister board
---------------------------
-
-Using mtd names with the following (default) configuration
-for mtdparts::
-
-    device nand0 <omap2-nand.0>, # parts = 9
-     #: name        size        offset      mask_flags
-     0: MLO                 0x00080000      0x00000000      0
-     1: u-boot              0x00100000      0x00080000      0
-     2: env1                0x00040000      0x00180000      0
-     3: env2                0x00040000      0x001c0000      0
-     4: kernel              0x00600000      0x00200000      0
-     5: bootparms           0x00040000      0x00800000      0
-     6: splashimg           0x00200000      0x00840000      0
-     7: mini                0x02800000      0x00a40000      0
-     8: rootfs              0x1cdc0000      0x03240000      0
-
-::
-
-    twister => nand read 82000000 kernel
-
-    NAND read: device 0 offset 0x200000, size 0x600000
-    6291456 bytes read: OK
-
-Now the kernel is in RAM at address 0x82000000::
-
-    twister => spl export atags 0x82000000
-    ## Booting kernel from Legacy Image at 82000000 ...
-       Image Name:   Linux-3.5.0-rc4-14089-gda0b7f4
-       Image Type:   ARM Linux Kernel Image (uncompressed)
-       Data Size:    3654808 Bytes = 3.5 MiB
-       Load Address: 80008000
-       Entry Point:  80008000
-       Verifying Checksum ... OK
-       Loading Kernel Image ... OK
-    OK
-    cmdline subcommand not supported
-    bdt subcommand not supported
-    Argument image is now in RAM at: 0x80000100
-
-The result can be checked at address 0x80000100::
-
-    twister => md 0x80000100
-    80000100: 00000005 54410001 00000000 00000000    ......AT........
-    80000110: 00000000 00000067 54410009 746f6f72    ....g.....ATroot
-    80000120: 65642f3d 666e2f76 77722073 73666e20    =/dev/nfs rw nfs
-
-The parameters generated with this step can be saved into NAND at the offset
-0x800000 (value for twister for CONFIG_CMD_SPL_NAND_OFS)::
-
-    nand erase.part bootparms
-    nand write 0x80000100 bootparms 0x4000
-
-Now the parameters are stored into the NAND flash at the address
-CONFIG_CMD_SPL_NAND_OFS (=0x800000).
-
-Next time, the board can be started into Falcon Mode moving the
-setting the GPIO (on twister GPIO 55 is used) to kernel mode.
-
-The kernel is loaded directly by the SPL without passing through U-Boot.
-
 Example with FDT: a3m071 board
 ------------------------------
 
diff --git a/doc/mkimage.1 b/doc/mkimage.1
index d0a038a880a..75b6b48a0cf 100644
--- a/doc/mkimage.1
+++ b/doc/mkimage.1
@@ -239,6 +239,18 @@ Set the
 command will not load the image data, and instead will assume it is already
 accessible at the load address (such as via memory-mapped flash).
 .
+.TP
+.B \-y
+.TQ
+.B \-\-tfa-bl31-file
+Append TFA BL31 file to the image.
+.
+.TP
+.B \-Y
+.TQ
+.B \-\-tfa-bl31-addr
+Set TFA BL31 file load and entry point address.
+.
 .SS Options for creating FIT images
 .
 .TP
diff --git a/doc/usage/filesystems/ext4.rst b/doc/usage/filesystems/ext4.rst
new file mode 100644
index 00000000000..c6cdaf57fac
--- /dev/null
+++ b/doc/usage/filesystems/ext4.rst
@@ -0,0 +1,137 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+Ext4 File System
+================
+
+Overview
+--------
+
+U-Boot supports access of both ext2 and ext4 filesystems, either in read-only
+mode or in read-write mode.
+
+Configuration
+-------------
+
+First, to enable support for both ext4 (and, automatically, ext2 as well),
+but without selecting the corresponding commands, enable one of the following:
+
+::
+
+  CONFIG_FS_EXT4	(for read-only)
+  CONFIG_EXT4_WRITE	(for read-write)
+
+Next, to select the ext2-related commands:
+
+  * ext2ls
+  * ext2load
+
+or ext4-related commands:
+
+  * ext4size
+  * ext4ls
+  * ext4load
+
+use one or both of:
+
+::
+
+	CONFIG_CMD_EXT2
+	CONFIG_CMD_EXT4
+
+Selecting either of the above automatically selects CONFIG_FS_EXT4 if it
+wasn't enabled already.
+
+In addition, to get the write access command ``ext4write``, enable:
+
+::
+
+	CONFIG_CMD_EXT4_WRITE
+
+which automatically selects CONFIG_EXT4_WRITE if it wasn't defined
+already.
+
+Also relevant are the generic filesystem commands, selected by:
+
+::
+
+	CONFIG_CMD_FS_GENERIC
+
+This does not automatically enable EXT4 support for you, you still need
+to do that yourself.
+
+Lastly, the current u-boot implementation for Ext4 write requires a lot
+of memory to run successfully. The following enable support for
+large Ext4 partitions:
+
+::
+
+	CONFIG_EXT4_MAX_JOURNAL_ENTRIES
+	CONFIG_SYS_MALLOC_LEN
+
+The number of journal entries and dynamic memory allocation are proportional
+to the partition capacity. For example, an ext4 4TB HDD partition could
+require approximately 500 entries and more than 128 MB heap space.
+
+Examples
+--------
+
+Some sample commands to test ext4 support:
+
+1. Check that the ext4 commands can be seen in the output of U-Boot help:
+
+::
+
+	=> help
+	...
+	ext4load- load binary file from a Ext4 file system
+	ext4ls  - list files in a directory (default /)
+	ext4size - determine a file's size
+	ext4write- create a file in ext4 formatted partition
+	...
+
+2. The ``ext4ls`` command can be used to list the files in an ext4-formatted partition:
+
+::
+
+	ext4ls <interface> <dev[:part]> [directory]
+
+For example, to list files in ext4-formatted partition directory /usr/lib:
+
+::
+
+	=> ext4ls mmc 0:5 /usr/lib
+
+3. The ``ext4load`` command can be used to read and load a file from an
+ext4-formatted partition to RAM:
+
+::
+
+	ext4load <interface> [<dev[:part]> [addr [filename [bytes [pos]]]]]
+
+For example, to load file /uImage from an ext4-formatted partition:
+
+::
+
+	=> ext4load mmc 2:2 0x30007fc0 uImage
+
+4. The ``ext4write`` command can be used to write to an ext4 partition:
+
+::
+
+	ext4write <interface> <dev[:part]> <addr> <absolute filename path> [sizebytes] [file offset]
+
+For example, to write a file loaded at 0x8200000 of size 256 bytes to an
+ext4-formatted partition with the filename ``/boot/sample_file.hex``:
+
+::
+
+	=> ext4write mmc 2:2 0x82000000 /boot/sample_file.hex 0x100
+	256 bytes written in 138 ms (1000 Bytes/s)
+
+
+References
+----------
+
+	* ext4 implementation in Linux Kernel
+	* Uboot existing ext2 load and ls implementation
+	* Journaling block device JBD2 implementation in linux Kernel
diff --git a/doc/usage/index.rst b/doc/usage/index.rst
index 3a48521d5d5..4b0533c8e69 100644
--- a/doc/usage/index.rst
+++ b/doc/usage/index.rst
@@ -147,3 +147,11 @@ Booting OS
 
    os/plan9
    os/vxworks
+
+File Systems
+------------
+
+.. toctree::
+   :maxdepth: 1
+
+   filesystems/ext4
author	Tom Rini <[email protected]>	2025-10-06 13:20:24 -0600
committer	Tom Rini <[email protected]>	2025-10-06 13:20:24 -0600
commit	0eaa4b337336dbbe93395d1f2ccc18937eaafea2 (patch)
tree	c01e661d69181dceca68f56a4849a9bd04608521 /doc
parent	e50b1e8715011def8aff1588081a2649a2c6cd47 (diff)
parent	4e4a9de31de2a5f395ee25c59e4026422fbcb27e (diff)