[RFC 5/5] doc: describe Milk-V Mars board

[E Shattow]

Yes this reference to GPIO high/low states is clearer to understand. Have
you tested the DIP switch functionality to confirm?; It is not shown in the
MilkV documentation or outdated schematics and I don't have a Mars to test.
I did find function descriptions from what is likely cut-and-paste of
VisionFive2 board reference.

Ref:
https://github.com/milkv-mars/mars-files/blob/main/Mars_hardware_schematics/Mars_V1.11_20230821.pdf
Sheet 7 of 22 JH7110 GPIOs
There is a schematic for SW2 (bootloader button?) that lists an inset table:
* - GPIO_1
  - GPIO_0
  - Boot
* - 0
  - 0
  - Flash
* - 0
  - 1
  - SD
* - 1
  - 0
  - eMMC
* - 1
  - 1
  - UART

That circuit on SW2 appears to pull high both RGPIO_1 and RGPIO_0 with
transistors. Again, no DIP switch as this is an earlier revision.

Ref:
https://doc-en.rvspace.org/VisionFive2/Developer_Guide/JH7110_Boot_UG.pdf
page 9 table 1-4:
RGPIO1=0x0 RGPIO0=0x0 Boot Source: Quad SPI NOR flash memory, Read SPL from
Sector 0.
RGPIO1=0x1 RGPIO0=0x1 Boot Source: UART0, (description of UART Xmodem
function).

Following in the same document on page 13 figure 2-1 Boot Flow:
JH7110 supports the following boot devices.
QSPI Flash (For SPL + OpenSBI + U-Boot) + NVMe/SD Card/eMMC (For Kernel + Fi
le System and later)
Note: System will detect in sequence whether it can boot from the following
device sequence: NVMe > SD > eMMC. For example, if the boot program is found
on the SD, eMMC will be ignored.

Again in this document Figure 4-2 on page 17 is a visual listing of the DIP
switch positions for QSPI, SDIO, eMMC, and UART boot modes, of the
VisionFive2 board.

The only consistent physical interface over VisionFive2, Mars, Star64, Mars
CM all is RGPIO1=L RGPIO0=L SPI and RGPIO1=H RGPIO1=H UART; either by DIP
switch or pushbutton attached circuit. So, I question our assumptions about
what the actual behavior is for RGPIO1=H RGPIO0=L pairing and RGPIO1=L
RGPIO0=H, and in what circumstance would there be followed a device
sequence as suggested by the JH7110 reference. Why does the StarFive
documentation list a JH7110 boot device sequence if there is also these H+L
or L+H pairings to choose the device?

On Thu, Mar 7, 2024 at 6:37 PM Heinrich Schuchardt <
heinrich.schuchardt at canonical.com> wrote:

> On 3/8/24 00:20, E Shattow wrote:
> >
> > On Sun, Mar 3, 2024 at 5:02 AM Heinrich Schuchardt
> > <heinrich.schuchardt at canonical.com
> > <mailto:heinrich.schuchardt at canonical.com>> wrote:
> > ...
> >
> >     +The board provides the DIP switches MSEL[1:0] to select the boot
> >     device out of
> >     +SPI flash, eMMC, SD-card, UART. To select booting from SD-card set
> >     the DIP
> >     +switches MSEL[1:0] to 10.
> >
> >
> > This does not match the [Milk-V Mars vendor
> > documentation](https://milkv.io/docs/mars/getting-started/bootloader
> > <https://milkv.io/docs/mars/getting-started/bootloader>). Maybe you
> have
> > a different board revision?
>
> Thank you for reviewing.
>
> My board revision is V1.21 according to the silk screen.
>
> The Milk-V Mars has DIP switches for the boot selection as shown in
> https://gist.github.com/xypron/e28f95b1ed6911aeb9699ba63ae1a885
>
> If you look at the photo
>
> https://milkv.io/assets/images/mars-icon-04-e8814f18158a0e9d4387f4fa330693f1.webp
> in the https://milkv.io/mars page, it also shows DIP switches (in the
> SPI-Flash position) on a rev 1.2 board.
>
> Did you see a board without DIP switches being sold?
>
> The silk screen markings on the board and the switch don't match.
> The same confusion exists on the VisionFive2.
>
> So maybe I should better write in a table:
>
> SPI-Flash:
> GPIO0=L
> GPIO1=L
>
> SD-Card:
> GPIO0=H
> GPIO1=L
>
> eMMC:
> GPIO0=L
> GPIO1=H
>
> UART:
> GPIO0=H
> GPIO1=H
>
> Best regards
>
> Heinrich
>