Install Ubuntu on the Milk-V Mars

The Milk-V Mars is a RISC-V based SBC.

Using the pre-installed server image

1. Download one of the supported images:

   • Ubuntu 24.10 (Oracular Oriole) images:

     • ubuntu-24.10-preinstalled-server-riscv64+milkvmars.img.xz

   • Ubuntu 24.04.1 LTS (Noble Numbat) images:

     • ubuntu-24.04.1-preinstalled-server-riscv64+milkvmars.img.xz

2. Flash the pre-installed server image to a microSD card (see Flash images to a microSD card)

3. Insert the microSD card into the board

4. Set the boot source to the microSD card (see Boot source selection)

5. Connect a USB UART adapter to the UART on the GPIO header (see UART console and Connect to a UART console)

6. Power on the board

7. When “Hit any key to stop autoboot” is displayed, press Enter

8. Reset the U-Boot environment with the following commands:

   env default -f -a
   env save
   

9. Power cycle the board

10. Wait for an output line confirming that cloud-init has finished running; this service is responsible for generating SSH keys, and creating the default user:

    [   35.682018] cloud-init[909]: Cloud-init v. 24.1.3-0ubuntu3 finished at Tue, 23 Apr 2024 07:44:59 +0000. Datasource DataSourceNoCloud [seed=/var/lib/cloud/seed/nocloud-net][dsmode=net].  Up 35.65 seconds
    

11. Login with the user ubuntu and the default password ubuntu; you will be asked to choose a new password

Using the live server image

The live installer image is used to install Ubuntu to an eMMC, USB, or NVMe drive. To boot the live image, U-Boot must be installed on the SPI flash.

Warning

The vendor U-Boot is not compatible with EBBR and cannot boot Ubuntu without manual changes.

Install U-Boot to the SPI flash

1. Download one of the supported images:

   • Ubuntu 24.10 (Oracular Oriole) images:

     • ubuntu-24.10-live-server-riscv64.img.gz

   • Ubuntu 24.04.1 LTS (Noble Numbat) images:

     • ubuntu-24.04.1-live-server-riscv64.img.gz

2. Flash the pre-installed server image to a microSD card (see Flash images to a microSD card)

3. Insert the microSD card into the board

4. Set the boot source to the microSD card (see Boot source selection)

5. Connect a USB UART adapter to the UART on the GPIO header (see UART console and Connect to a UART console)

6. Power on the board

7. When “Hit any key to stop autoboot” is displayed, press Enter

8. Enter the following commands to flash U-Boot to SPI:

   sf probe
   load mmc 1:1 $kernel_addr_r /usr/lib/u-boot/starfive_visionfive2/u-boot-spl.bin.normal.out
   sf update $kernel_addr_r 0 $filesize
   load mmc 1:1 $kernel_addr_r /usr/lib/u-boot/starfive_visionfive2/u-boot.itb
   sf update $kernel_addr_r 0x100000 $filesize
   

9. Switch the board off

10. Set the boot source to the SPI flash (see Boot source selection)

11. Power on the board

12. When “Hit any key to stop autoboot” is displayed, press Enter

13. Enter the following commands to reset the U-Boot environment:

    env default -f -a
    env save
    

14. Switch the board off

Boot the live server image

1. Flash the live server image to a microSD card (see Flash images to a microSD card)

2. Insert the microSD card into the board

3. Ensure the boot source is SPI flash (see Boot source selection), not microSD card

4. Connect a USB UART adapter to the UART on the GPIO header (see UART console and Connect to a UART console)

5. Power on the board

6. If no prior operating system installation exists, U-Boot will start up GRUB on the microSD card. Go to step 8

7. If a prior operating system exists, press Enter when “Hit any key to stop autoboot” is displayed, and enter:

   load mmc 1:1 $fdt_addr_r dtb/starfive/jh7110-milkv-mars.dtb
   load mmc 1:1 $kernel_addr_r EFI/boot/bootriscv64.efi
   bootefi $kernel_addr_r $fdt_addr_r
   

8. From the GRUB menu, select “Try or Install Ubuntu Server”

9. Loading the installer takes some time. Once it is loaded, follow the Ubuntu Server installation tutorial

10. Once the installation is complete, reboot the board without removing the microSD card

Note

U-Boot does not allow the operating system to write UEFI variables. You can do this manually using U-Boot’s eficonfig command.

Boot source selection

The Milk-V Mars board can boot firmware from SPI flash, microSD card, eMMC, or UART. The boot source is selected via DIP switches.

GPIO01	GPIO00	Boot Source
0	0	SPI flash
0	1	microSD card
1	0	eMMC
1	1	UART

For example, to boot from microSD card the DIP switches should be set as follows:

Alternatively, to boot from SPI flash, set the DIP switches like so:

Cloud-init seed

Sample files for a cloud-init seed are present on the FAT partition labeled “CIDATA”. See Configure your board for headless use for more information.

UART console

The UART is available via the GPIO connector. Assuming the typical coloring of USB to TTL serial adapters the following connections have to be made:

Board	Adapter
GND, pin 6	GND, black
TX, pin 8	RX, white
RX, pin 10	TX, green

Do not connect the red 3.3 V wire.

Connect with the following settings (see Connect to a UART console):

• 115200 baud

• 8 data bits

• no parity

• 1 stop bit

• no flow control

Limitations

• The on-board GPU is not supported

• PCIe support is incomplete: an NVMe drive can be used, but WiFi cards and external GPUs don’t work

• While the 3 USB 3.0 ports are working, the USB 2.0 port is not supported by the 6.8 kernel