Browse Source

dubhe: Added README file

Added a basic README file which includes introduction for meta-starfive
layer setup and simple usage guide.

Signed-off-by: Jun Yuan Tan <junyuan.tan@starfivetech.com>
Jun Yuan Tan 2 years ago
parent
commit
4fd31c3d76
1 changed files with 152 additions and 0 deletions
  1. 152 0
      README.md

+ 152 - 0
README.md

@@ -0,0 +1,152 @@
+# StarFive Linux Software Development Kit (SDK)
+
+The StarFive Dubhe Linux SDK is based on Yocto Project. It enables the creation of Linux distributions for any embedded project, as well as easy migration from a different architecture platform. 
+The meta-starfive layer is built on top of meta-riscv to provide additional modifications such as Linux Kernel, and toolchains like GCC and LLVM.
+
+
+## Supported Features
+* **FPGA Image Generation**
+  * Able to generate an image to boot up on FPGA directly
+
+<br>
+
+* **Yocto extensible-SDK (eSDK)**
+  * Shell-script installer
+  * Shrink-wrapped distro maintainer environment
+  * Updateable and Extensible
+
+# Setting up meta-starfive
+Guide to use meta-starfive using Yocto
+
+## Dependencies
+First, you need to download the essential Yocto dependencies, which can also be found on their [official Yocto Guide](https://docs.yoctoproject.org/brief-yoctoprojectqs/index.html#build-host-packages):
+```
+$ sudo apt install gawk wget git diffstat unzip texinfo gcc build-essential chrpath socat cpio python3 python3-pip python3-pexpect xz-utils debianutils iputils-ping python3-git python3-jinja2 libegl1-mesa libsdl1.2-dev pylint3 xterm python3-subunit mesa-common-dev zstd liblz4-tool
+```
+
+#### Installing Repo
+Next, you will need to install repo from https://source.android.com/setup/develop#installing-repo.
+
+Dependencies of repo include:
+```
+$ sudo apt install curl python python3-distutils
+```
+
+The steps to install repo are as below:
+```
+$ mkdir ~/bin
+$ PATH=~/bin:$PATH
+$ curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo
+$ chmod a+x ~/bin/repo
+```
+
+
+## Setup
+
+### Create a workspace
+Now, we will be creating a workspace and retrieve the latest layers needed for our image creation.
+
+```
+$ mkdir starfive-yocto && cd starfive-yocto
+$ repo init -u git://github.com/starfive-tech/meta-starfive -b starfive-honister -m tools/manifests/starfive.xml
+$ repo sync
+$ repo start work --all
+```
+
+
+### Setup Bitbake Environment 
+After having all the layers required,  you can now source into the build environment by running the `setup.sh` script in the meta-starfive layer. You should run the script in the starfive-yocto folder directory.
+
+```
+$ . ./meta-starfive/setup.sh
+```
+
+### Available Machines
+In meta-starfive, there is currently only one buildable machine that you can build for:
+
+* **starfive-dubhe**: The StarFive Dubhe machine
+
+### Build Images
+
+To build a initramfs image with QSPI-Image binary:
+```
+$ MACHINE=starfive-dubhe bitbake qspi-image
+```
+
+For the bitbake command, you can control the number of parallel tasks and the number of cores that Bitbake will use. You can either add the variables in the `<build_directory>/conf/local.conf` file, or add it in your shell environment command, for example:
+
+```
+$ PARALLEL_MAKE="-j 6" BB_NUMBER_THREADS=4 MACHINE=starfive-dubhe bitbake qspi-image
+```
+
+To populate the extensible eSDK shell script, you can use the `-c populate_sdk_ext` command:
+```
+$ MACHINE=starfive-dubhe bitbake qspi-image -c populate_sdk_ext
+```
+_NOTE: For your first build, it may take several hours to build the image._
+
+
+## Running in QEMU
+Run the 64-bit machine in QEMU using the following command:
+```
+MACHINE=starfive-dubhe runqemu nographic dubhe-image-initramfs
+```
+<br>
+
+_Tip: Once QEMU starts, in nographic mode, the terminal is 'controlled' by the Linux console. Thus, to kill QEMU and get back to the terminal, you can:_
+* ```CTRL-a x``` to kill QEMU and exit
+
+## Running on FPGA
+You will find image components such as openSBI (fw_payload.bin) and the Linux kernel in the bitbake build directory (_<SDK_path>/build/tmp-glibc/deploy/images/starfive-dubhe/_) after your bitbake process is done. You can also find the full QSPI binary image generated (QSPI-Image.bin), which includes the boot codes, openSBI and kernel in a single binary.
+
+You can flash the QSPI binary into the FPGA via openOCD or other FPGA flashing tools.
+
+<br>
+
+## Modifying the Kernel
+To modify the kernel, you can use the devtool command line:
+```
+$ MACHINE=starfive-dubhe devtool modify virtual/kernel
+```
+
+The devtool command will fetch the source code and unpack them in the _'build/workspace/sources/<kernel_name>'_ directory.
+
+Now you can make your changes in your source code in the workspace directory.
+
+### Building the Kernel
+After you had done your changes, you can build only the kernel by:
+```
+$ MACHINE=starfive-dubhe devtool build <kernel_name>
+
+or 
+
+$ MACHINE=starfive-dubhe bitbake virtual/kernel
+```
+
+You can obtain the image generated in the images folder _build/tmp-glibc/deploy/images/starfive-dubhe/<Image_name>_
+
+### Saving the Modification
+Once you are happy with the changes, you can go to the source folder and commit your changes:
+* Go to _workspace/sources/<kernel_name>_:
+  * ```$ git status```
+  * ```$ git add .```
+  * ```$ git commit -m "Changes added"```
+* Create a bbappend and patch file:
+  * ```$ devtool finish <kernel_name> <layer_path> ```
+
+### Rebuilding the Image
+To rebuild your image, the steps include:
+```
+$ MACHINE=starfive-dubhe bitbake qspi-image
+```
+Rebuilding will take less time as the sstate-cache is saved during your first build.
+
+
+## Extras
+In case you accidentally deleted files in the _build/tmp/deploy/images/_ directory and some of the files are not automatically re-created when you build the image again, you can rebuild and recreate the kernel files by:
+```
+$ MACHINE=starfive-dubhe bitbake -c clean virtual/kernel
+$ MACHINE=starfive-dubhe bitbake virtual/kernel
+```
+
+