[PATCH] doc: board: starfive: Fix paths in the bash block

[PATCH] doc: board: starfive: Fix paths in the bash block

[Ivan Orlov]

From the current documentation it is not entirely obvious where to take
some of the u-boot build artifacts in order to flash them to the sd
card. Extend the "Program the SD card" block by providing relative paths
to the jh7110-starfive-visionfive-2.dtb and u-boot-spl.bin.normal.out
files.

Add "$(linux_image_dir)/" prefix to the Image.gz and initramfs.cpio.gz
files in order to provide some information about where they could be
taken from.

Signed-off-by: Ivan Orlov <ivan.orlov0322@gmail.com>
---
 doc/board/starfive/visionfive2.rst | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/doc/board/starfive/visionfive2.rst b/doc/board/starfive/visionfive2.rst
index abda8ac21b..031d66fbfb 100644
--- a/doc/board/starfive/visionfive2.rst
+++ b/doc/board/starfive/visionfive2.rst
@@ -103,15 +103,15 @@ Program the SD card
 
 .. code-block:: bash
 
-	sudo dd if=u-boot-spl.bin.normal.out of=/dev/sdb1
+	sudo dd if=spl/u-boot-spl.bin.normal.out of=/dev/sdb1
 	sudo dd if=u-boot.itb of=/dev/sdb2
 
 	sudo mount /dev/sdb3 /mnt/
-	sudo cp u-boot-spl.bin.normal.out /mnt/
+	sudo cp spl/u-boot-spl.bin.normal.out /mnt/
 	sudo cp u-boot.itb /mnt/
-	sudo cp Image.gz /mnt/
-	sudo cp initramfs.cpio.gz /mnt/
-	sudo cp jh7110-starfive-visionfive-2.dtb /mnt/
+	sudo cp $(linux_image_dir)/Image.gz /mnt/
+	sudo cp $(linux_image_dir)/initramfs.cpio.gz /mnt/
+	sudo cp arch/riscv/dts/jh7110-starfive-visionfive-2.dtb /mnt/
 	sudo umount /mnt
 
 Booting
-- 
2.34.1

Re: [PATCH] doc: board: starfive: Fix paths in the bash block

[Heinrich Schuchardt]

On 3/4/24 23:15, Ivan Orlov wrote:
>  From the current documentation it is not entirely obvious where to take
> some of the u-boot build artifacts in order to flash them to the sd
> card. Extend the "Program the SD card" block by providing relative paths
> to the jh7110-starfive-visionfive-2.dtb and u-boot-spl.bin.normal.out
> files.
>
> Add "$(linux_image_dir)/" prefix to the Image.gz and initramfs.cpio.gz
> files in order to provide some information about where they could be
> taken from.
>
> Signed-off-by: Ivan Orlov <ivan.orlov0322@gmail.com>
> ---
>   doc/board/starfive/visionfive2.rst | 10 +++++-----
>   1 file changed, 5 insertions(+), 5 deletions(-)
>
> diff --git a/doc/board/starfive/visionfive2.rst b/doc/board/starfive/visionfive2.rst
> index abda8ac21b..031d66fbfb 100644
> --- a/doc/board/starfive/visionfive2.rst
> +++ b/doc/board/starfive/visionfive2.rst
> @@ -103,15 +103,15 @@ Program the SD card
>

>   .. code-block:: bash
>
> -	sudo dd if=u-boot-spl.bin.normal.out of=/dev/sdb1
> +	sudo dd if=spl/u-boot-spl.bin.normal.out of=/dev/sdb1
>   	sudo dd if=u-boot.itb of=/dev/sdb2
>
>   	sudo mount /dev/sdb3 /mnt/

Following the instructions the partition in not formatted.
You won't be able to mount it anywhere.

Looking at the boot log the author FAT formatted the drive which is not
recommendable.

> -	sudo cp u-boot-spl.bin.normal.out /mnt/
> +	sudo cp spl/u-boot-spl.bin.normal.out /mnt/
>   	sudo cp u-boot.itb /mnt/
> -	sudo cp Image.gz /mnt/
> -	sudo cp initramfs.cpio.gz /mnt/
> -	sudo cp jh7110-starfive-visionfive-2.dtb /mnt/
> +	sudo cp $(linux_image_dir)/Image.gz /mnt/
> +	sudo cp $(linux_image_dir)/initramfs.cpio.gz /mnt/

I have no clue why all users should copy the kernel to the root
partition on the SD card.

If you have a Linux installation on the SD-card, you want the kernel in
boot/. But this board boots fine without any SD-card from NVMe, USB, or
eMMC.

> +	sudo cp arch/riscv/dts/jh7110-starfive-visionfive-2.dtb /mnt/

Copying the U-Boot device-tree makes no sense it is already available at
$fdtcontroladdr. If you ever wanted to copy a device-tree, it should be
the one provided with the kernel.

This whole section is rather misleading for inexperienced users who just
want to boot a Linux distro on the board.

Best regards

Heinrich

>   	sudo umount /mnt
>
>   Booting

Re: [PATCH] doc: board: starfive: Fix paths in the bash block

[Ivan Orlov]

On 3/5/24 19:52, Heinrich Schuchardt wrote:
> On 3/4/24 23:15, Ivan Orlov wrote:
>>  From the current documentation it is not entirely obvious where to take
>> some of the u-boot build artifacts in order to flash them to the sd
>> card. Extend the "Program the SD card" block by providing relative paths
>> to the jh7110-starfive-visionfive-2.dtb and u-boot-spl.bin.normal.out
>> files.
>>
>> Add "$(linux_image_dir)/" prefix to the Image.gz and initramfs.cpio.gz
>> files in order to provide some information about where they could be
>> taken from.
>>
>> Signed-off-by: Ivan Orlov <ivan.orlov0322@gmail.com>
>> ---
>>   doc/board/starfive/visionfive2.rst | 10 +++++-----
>>   1 file changed, 5 insertions(+), 5 deletions(-)
>>
>> diff --git a/doc/board/starfive/visionfive2.rst 
>> b/doc/board/starfive/visionfive2.rst
>> index abda8ac21b..031d66fbfb 100644
>> --- a/doc/board/starfive/visionfive2.rst
>> +++ b/doc/board/starfive/visionfive2.rst
>> @@ -103,15 +103,15 @@ Program the SD card
>>
> 
>>   .. code-block:: bash
>>
>> -    sudo dd if=u-boot-spl.bin.normal.out of=/dev/sdb1
>> +    sudo dd if=spl/u-boot-spl.bin.normal.out of=/dev/sdb1
>>       sudo dd if=u-boot.itb of=/dev/sdb2
>>
>>       sudo mount /dev/sdb3 /mnt/
> 
> Following the instructions the partition in not formatted.
> You won't be able to mount it anywhere.
> 
> Looking at the boot log the author FAT formatted the drive which is not
> recommendable.
> 
>> -    sudo cp u-boot-spl.bin.normal.out /mnt/
>> +    sudo cp spl/u-boot-spl.bin.normal.out /mnt/
>>       sudo cp u-boot.itb /mnt/
>> -    sudo cp Image.gz /mnt/
>> -    sudo cp initramfs.cpio.gz /mnt/
>> -    sudo cp jh7110-starfive-visionfive-2.dtb /mnt/
>> +    sudo cp $(linux_image_dir)/Image.gz /mnt/
>> +    sudo cp $(linux_image_dir)/initramfs.cpio.gz /mnt/
> 
> I have no clue why all users should copy the kernel to the root
> partition on the SD card.
> 
> If you have a Linux installation on the SD-card, you want the kernel in
> boot/. But this board boots fine without any SD-card from NVMe, USB, or
> eMMC.
> 
>> +    sudo cp arch/riscv/dts/jh7110-starfive-visionfive-2.dtb /mnt/
> 
> Copying the U-Boot device-tree makes no sense it is already available at
> $fdtcontroladdr. If you ever wanted to copy a device-tree, it should be
> the one provided with the kernel.
> 
> This whole section is rather misleading for inexperienced users who just
> want to boot a Linux distro on the board.
> 

Hi Heinrich,

Thank you very much for the review. I agree that this documentation is 
far from being perfect, so I will try to improve it and fix all the 
flaws in the V2 of this patch :)

-- 
Kind regards,
Ivan Orlov