diff --git a/docs/source/Getting-Started/Running-Keystone-on-Unmatched.rst b/docs/source/Getting-Started/Running-Keystone-on-Unmatched.rst new file mode 100644 index 000000000..f7adf4087 --- /dev/null +++ b/docs/source/Getting-Started/Running-Keystone-on-Unmatched.rst @@ -0,0 +1,153 @@ +SiFive HiFive Unmatched Hardware Deployment +=========================================== + +.. warning:: + Building for the HiFive Unmatched using this approach is experimental. + +Preparing freedom-u-sdk +----------------------- + +First, obtain the `freedom-u-sdk `_. It is recommended to use the ``2022.12.00`` release since it uses Linux ``5.19.14``, which is close to the default Linux version of the *Keystone* project. Attempts at using Linux ``6.5-rc3`` resulted in a *User space access Oops*. + +To create a Kernel Configuration we merge the *freedom-u-sdk* defconfig under ``recipes-kernel/linux/linux-sifive/unmatched/defconfig`` with the *Keystone* sifive defconfig under ``conf/linux64-sifive-defconfig``, giving precedence to *freedom-u-sdk* where necessary. We copy the new defconfig to the aforementioned location inside the *freedom-u-sdk* and in *Keystone* to ``conf/linux64-defconfig``. Note, for *Keystone*, we add ``HAVE_STACKPROTECTOR=n`` (or comment ``select HAVE_STACKPROTECTOR`` out in ``linux/arch/riscv/Kconfig``), as there will be unknown symbols in ``keystone-driver.ko`` otherwise. + +Build the image (this will take a while): + +:: + + kas build freedom-u-sdk/scripts/kas/unmatched.yml --target demo-coreip-cli + +and flash the SD Card + +:: + + xzcat demo-coreip-cli-unmatched.wic.xz | sudo dd of=/dev/mmcblk0 bs=512K iflag=fullblock oflag=direct conv=fsync status=progress + + +Building Keystone +----------------- + +On the build system, run ``./fast_setup.sh``. + +Once completed, replace Linux with version `5.19.14 `_ such that the kernel and kernel driver match. + +Furthermore, update ``OpenSBI`` inside ``sm/`` to the newest available version. + +Use the platform configuration files in ``opensbi/platform/generic`` to update the platform configuration files in ``sm/plat/generic`` (at the time of this writing a PR is pending). + +In ``sm/plat/generic/platform.c``, in function ``generic_final_init``, add ``sm_init(cold_boot)`` such that: + +:: + + static int generic_final_init(bool cold_boot) + { + void *fdt; + int rc; + + if (generic_plat && generic_plat->final_init) { + rc = generic_plat->final_init(cold_boot, generic_plat_match); + if (rc) + return rc; + } + + sm_init(cold_boot); + + if (!cold_boot) + return 0; + + fdt = fdt_get_address(); + + fdt_cpu_fixup(fdt); + fdt_fixups(fdt); + fdt_domain_fixup(fdt); + + if (generic_plat && generic_plat->fdt_fixup) { + rc = generic_plat->fdt_fixup(fdt, generic_plat_match); + if (rc) + return rc; + } + + return 0; + } + + +After, you can run the following commands to build *Keystone*. + +:: + + mkdir + cd + cmake .. + make + make image + make tests + +This will automatically build a generic SM. + +Once you have built the image, you will see ``sm.build/platform/generic/firmware/`` under your +build directory. + +Separately, ``make image`` will also generate ``sm.build/platform/generic/firmware/fw_dynamic.bin`` under your build directory. +This is the file that you want to reflash the SD card with. + +Setting up the HiFive +--------------------- + +Setup Bootloader +################ + +First, you will need to get a working custom first-stage bootloader +(FSBL) working on your board. This will require creating a new +partition on your SD card as well as setting the MSEL2 dipswitch. See the `Getting Started Guide `_ +for details. + +For the bootloader itself, you'll need to use ``u-boot``: + +https://github.com/u-boot/u-boot. + +Build according to the `u-boot build instructions `_ using the *Keystone* custom *OpenSBI*: + +:: + + export OPENSBI= + cd + make sifive_unmatched_defconfig + make FW_PAYLOAD= + +Program the SPL and *u-boot* on the card where the pre-built image is already flashed. + +:: + + sudo dd if=spl/u-boot-spl.bin of=/dev/mmcblk0 seek=34 + sudo dd if=u-boot.itb of=/dev/mmcblk0 seek=2082 + +Running on the HiFive +--------------------- + +Attach to the serial console on the HiFive board. + +Boot the HiFive with the custom FSBL/Linux as described above. + +Copy Keystone driver and examples +################################# + +Copy the *Keystone* driver from ``sm.build/linux-keystone-driver.build/keystone-driver.ko`` and the examples from ``sm.build/examples`` to the board. +Since we used the *freedom-u-sdk*, you have to copy the files manually. + +Run binaries +######################### + +Insert the *Keystone* driver, and run whatever test binaries you wish. + +Example + +:: + + insmod keystone-driver.ko + ./tests/tests.ke + + + + +The ``fib-bench`` test causes the system to hang since it uses the `rdcycle` instruction which is now illegal from `u-mode`, hence, should be replaced by `rdtime`, and ``attestation`` fails as the required values are absent during the SM initialization. +