README.md

   1 # Linux kernel for StarFive's JH7100 RISC-V SoC
   2
   3 ## What is this?
   4
   5 The [JH7100][soc] is a Linux-capable dual-core 64bit RISC-V SoC and this tree
   6 is meant to collect all the in-development patches for running Linux on boards
   7 using this. So far there are two such boards and both are supported by this tree:
   8
   9 1) [StarFive VisionFive][visionfive]
  10 2) [BeagleV Starlight Beta][starlight]
  11
  12 The VisionFive boards aren't quite shipping yet, but you can already
  13 [register interest][interest] and ask questions on the [forum][].
  14
  15 About 300 BeagleV Starlight Beta boards were sent out to developers in
  16 April 2021 in preparation for an eventual BeagleV branded board using the
  17 updated JH7110 chip. The BeagleBoard organization has since [cancelled that
  18 project][beaglev] though.
  19
  20
  21 [visionfive]: https://github.com/starfive-tech/VisionFive
  22 [interest]: http://starfive.mikecrm.com/doQXj99
  23 [forum]: https://forum.rvspace.org/c/visionfive/6
  24 [starlight]: https://github.com/beagleboard/beaglev-starlight
  25 [soc]: https://github.com/starfive-tech/JH7100_Docs
  26 [beaglev]: https://beaglev.org/blog/2021-07-30-the-future-of-beaglev-community
  27
  28 ## Cross-compiling
  29
  30 Cross-compiling the Linux kernel is surprisingly easy since it doesn't depend
  31 on any (target) libraries and most distributions already have packages with a
  32 working cross-compiler. We'll also need a few other tools to build everything:
  33 ```shell
  34 # Debian/Ubuntu
  35 sudo apt-get install libncurses-dev libssl-dev bc flex bison make gcc gcc-riscv64-linux-gnu
  36 # Fedora
  37 sudo dnf install ncurses-devel openssl openssl-devel bc flex bison make gcc gcc-riscv64-linux-gnu
  38 # Archlinux
  39 sudo pacman -S --needed ncurses openssl bc flex bison make gcc riscv64-linux-gnu-gcc
  40 ```
  41
  42 The build system needs to know that we want to cross-compile a kernel for
  43 RISC-V by setting `ARCH=riscv`. It also needs to know the prefix of our
  44 cross-compiler using `CROSS_COMPILE=riscv64-linux-gnu-`. Also let's assume
  45 we're building on an 8-core machine so compilation can be greatly sped up by
  46 telling make to use all 8 cores with `-j8`.
  47
  48 First we need to configure the kernel though. Linux has a *very* extensive
  49 configuration system, but you can get a good baseline configuration for the
  50 boards using:
  51 ```shell
  52 make -j8 ARCH=riscv CROSS_COMPILE=riscv64-linux-gnu- visionfive_defconfig
  53 ```
  54
  55 There is nothing magic about this configuration other than it has all the
  56 drivers enabled that are working for the hardware on the boards. In fact it has
  57 very little extra features enabled which is great for compile times, but you
  58 are very much encouraged to add additional drivers and configure your kernel
  59 further using
  60 ```shell
  61 make -j8 ARCH=riscv CROSS_COMPILE=riscv64-linux-gnu- nconfig
  62 ```
  63
  64 Now compile the whole thing with
  65 ```
  66 make -j8 ARCH=riscv CROSS_COMPILE=riscv64-linux-gnu-
  67 ```
  68
  69
  70 ## Installing
  71
  72 Once the build has finished the resulting kernel can be found at
  73 ```shell
  74 arch/riscv/boot/Image
  75 ```
  76 You'll also need the matching device tree at
  77 ```shell
  78 arch/riscv/boot/dts/starfive/jh7100-starfive-visionfive-v1.dtb
  79 ```
  80 (If you have a Starlight board you should instead be using `jh7100-beaglev-starlight.dtb`.)
  81
  82 These two files should be copied to the boot partition on the SD card. In the
  83 default [Fedora image][fedora] this is `/dev/mmcblk0p3` and is mounted at `/boot`.
  84
  85 Now add the following entry to the `grub.cfg` file:
  86 ```
  87 menuentry 'My New Kernel' {
  88     linux /Image earlycon console=ttyS0,115200n8 root=/dev/mmcblk0p4 rootwait
  89     devicetree /jh7100-starfive-visionfive-v1.dtb
  90 }
  91 ```
  92
  93 This assumes your root file system is at `/dev/mmcblk0p4` which it is in the
  94 default [Fedora image][fedora].
  95
  96 The `visionfive_defconfig` doesn't enable modules, but if you enabled them in
  97 your build you'll also need to install them in `/lib/modules/` on the root file
  98 system. How to do that best is out of scope for this README though.
  99
 100 [fedora]: https://github.com/starfive-tech/Fedora_on_StarFive/
 101
 102 ## Status
 103
 104 #### SoC
 105
 106 - [x] Clock tree
 107 - [x] Resets
 108 - [x] Pinctrl/Pinmux
 109 - [x] GPIO
 110 - [x] Serial port
 111 - [x] I2C
 112 - [x] SPI
 113 - [x] MMC / SDIO / SD card
 114 - [x] Random number generator
 115 - [x] Temperature sensor
 116 - [x] Ethernet
 117 - [x] USB, USB 3.0 is broken with `CONFIG_PM=y`
 118 - [x] DRM driver
 119 - [x] NVDLA
 120 - [x] Watchdog
 121 - [x] PWM DAC for sound through the minijack, only 16kHz samplerate for now
 122 - [ ] I2S [WIP]
 123 - [ ] TDM [WIP]
 124 - [ ] MIPI-DSI [WIP]
 125 - [ ] MIPI-CSI [WIP]
 126 - [ ] ISP [WIP]
 127 - [ ] Video Decode [WIP]
 128 - [ ] Video Encode [WIP]
 129 - [ ] QSPI
 130 - [ ] Security Engine
 131 - [ ] NNE50
 132 - [ ] Vision DSP
 133
 134 #### Board
 135
 136 - [x] LED
 137 - [x] PMIC / Reboot
 138 - [x] Ethernet PHY
 139 - [x] HDMI
 140 - [x] AP6236 Wifi
 141 - [x] AP6236 Bluetooth, with a [userspace tool][patchram]
 142 - [x] I2C EEPROM (VisionFive only)
 143 - [ ] GD25LQ128DWIG (VisionFive) / GD25LQ256D (Starlight) flash
 144
 145 [patchram]: https://github.com/AsteroidOS/brcm-patchram-plus
 146
 147 ## Contributing
 148
 149 If you're working on cleaning up or upstreaming some of this or adding support
 150 for more of the SoC I'd very much like to incorporate it into this tree. Either
 151 send a pull request, mail or contact Esmil on IRC/Slack.
 152
 153 Also think of this tree mostly as a collection of patches that will hopefully
 154 mature enough to be submitted upstream eventually. So expect regular rebases.