executing in VS-mode.
The *RISC-V SBI specification* is maintained as an independent project by the
-RISC-V Foundation on [Github] (https://github.com/riscv/riscv-sbi-doc).
+RISC-V Foundation on [Github].
The goal of the OpenSBI project is to provide an open-source reference
implementation of the RISC-V SBI specifications for platform-specific firmwares
OpenSBI also provides several runtime firmware examples built using the platform
*libplatsbi.a*. These example firmwares can be used to replace the legacy
*riscv-pk* bootloader (aka BBL) and enable the use of well-known bootloaders
-such as [U-Boot] (https://git.denx.de/u-boot.git).
+such as [U-Boot].
Supported SBI version
---------------------
as it doesn't need to boot all the harts. The operating system should be
capable enough to bring up all other non-booting harts using HSM extension.
-Required Toolchain
-------------------
+Required Toolchain and Packages
+-------------------------------
OpenSBI can be compiled natively or cross-compiled on a x86 host. For
-cross-compilation, you can build your own toolchain or just download
-a prebuilt one from the
-[Bootlin toolchain repository] (https://toolchains.bootlin.com/).
+cross-compilation, you can build your own toolchain, download a prebuilt one
+from the [Bootlin toolchain repository] or install a distribution-provided
+toolchain; if you opt to use LLVM/Clang, most distribution toolchains will
+support cross-compiling for RISC-V using the same toolchain as your native
+LLVM/Clang toolchain due to LLVM's ability to support multiple backends in the
+same binary, so is often an easy way to obtain a working cross-compilation
+toolchain.
+
+Basically, we prefer toolchains with Position Independent Executable (PIE)
+support like *riscv64-linux-gnu-gcc*, *riscv64-unknown-freebsd-gcc*, or
+*Clang/LLVM* as they generate PIE firmware images that can run at arbitrary
+address with appropriate alignment. If a bare-metal GNU toolchain (e.g.
+*riscv64-unknown-elf-gcc*) is used, static linked firmware images are
+generated instead. *Clang/LLVM* can still generate PIE images if a bare-metal
+triple is used (e.g. *-target riscv64-unknown-elf*).
Please note that only a 64-bit version of the toolchain is available in
the Bootlin toolchain repository for now.
+In addition to a toolchain, OpenSBI also requires the following packages on
+the host:
+
+1. device-tree-compiler: The device tree compiler for compiling device
+ tree sources (DTS files).
+2. python3: The python 3.0 (or compatible) language support for various
+ scripts.
+
Building and Installing the OpenSBI Platform-Independent Library
----------------------------------------------------------------
For cross-compiling, the environment variable *CROSS_COMPILE* must be defined
to specify the name prefix of the RISC-V compiler toolchain executables, e.g.
-*riscv64-unknown-elf-* if the gcc executable used is *riscv64-unknown-elf-gcc*.
+*riscv64-linux-gnu-* if the gcc executable used is *riscv64-linux-gnu-gcc*.
To build *libsbi.a* simply execute:
```
*docs/platform/<platform_name>.md* files and
*docs/firmware/<firmware_name>.md* files.
+All OpenSBI platforms support Kconfig style build-time configuration. Users
+can change the build-time configuration of a platform using a graphical
+interface as follows:
+```
+make PLATFORM=<platform_subdir> menuconfig
+```
+
+Alternately, an OpenSBI platform can have multiple default configurations
+and users can select a custom default configuration as follows:
+```
+make PLATFORM=<platform_subdir> PLATFORM_DEFCONFIG=<platform_custom_defconfig>
+```
+
Building 32-bit / 64-bit OpenSBI Images
---------------------------------------
By default, building OpenSBI generates 32-bit or 64-bit images based on the
supplied RISC-V cross-compile toolchain. For example if *CROSS_COMPILE* is set
-to *riscv64-unknown-elf-*, 64-bit OpenSBI images will be generated. If building
+to *riscv64-linux-gnu-*, 64-bit OpenSBI images will be generated. If building
32-bit OpenSBI images, *CROSS_COMPILE* should be set to a toolchain that is
-pre-configured to generate 32-bit RISC-V codes, like *riscv32-unknown-elf-*.
+pre-configured to generate 32-bit RISC-V codes, like *riscv32-linux-gnu-*.
However it's possible to explicitly specify the image bits we want to build with
a given RISC-V toolchain. This can be done by setting the environment variable
*PLATFORM_RISCV_XLEN* to the desired width, for example:
```
-export CROSS_COMPILE=riscv64-unknown-elf-
+export CROSS_COMPILE=riscv64-linux-gnu-
export PLATFORM_RISCV_XLEN=32
```
will generate 32-bit OpenSBI images. And vice vesa.
+Building with Clang/LLVM
+------------------------
+
+OpenSBI can also be built with Clang/LLVM. To build with just Clang but keep
+the default binutils (which will still use the *CROSS_COMPILE* prefix if
+defined), override the *CC* make variable with:
+```
+make CC=clang
+```
+
+To build with a full LLVM-based toolchain, not just Clang, enable the *LLVM*
+option with:
+```
+make LLVM=1
+```
+
+When using Clang, *CROSS_COMPILE* often does not need to be defined unless
+using GNU binutils with prefixed binary names. *PLATFORM_RISCV_XLEN* will be
+used to infer a default triple to pass to Clang, so if *PLATFORM_RISCV_XLEN*
+itself defaults to an undesired value then prefer setting that rather than the
+full triple via *CROSS_COMPILE*. If *CROSS_COMPILE* is nonetheless defined,
+rather than being used as a prefix for the executable name, it will instead be
+passed via the `--target` option with the trailing `-` removed, so must be a
+valid triple.
+
+These can also be mixed; for example using a GCC cross-compiler but LLVM
+binutils would be:
+```
+make CC=riscv64-linux-gnu-gcc LLVM=1
+```
+
+These variables must be passed for all the make invocations described in this
+document.
+
+NOTE: Using Clang with a `riscv*-linux-gnu` GNU binutils linker has been seen
+to produce broken binaries with missing relocations; it is therefore currently
+recommended that this combination be avoided or *FW_PIC=n* be used to disable
+building OpenSBI as a position-independent binary.
+
+Building with timestamp and compiler info
+-----------------------------------------
+
+When doing development, we may want to know the build time and compiler info
+for debug purpose. OpenSBI can also be built with timestamp and compiler info.
+To build with those info and print it out at boot time, we can just simply add
+`BUILD_INFO=y`, like:
+```
+make BUILD_INFO=y
+```
+
+But if you have used `BUILD_INFO=y`, and want to switch back to `BUILD_INFO=n`,
+you must do
+```
+make clean
+```
+before the next build.
+
+NOTE: Using `BUILD_INFO=y` without specifying SOURCE_DATE_EPOCH will violate
+[reproducible builds]. This definition is ONLY for development and debug
+purpose, and should NOT be used in a product which follows "reproducible
+builds".
+
+Building with optimization off for debugging
+--------------------------------------------
+
+When debugging OpenSBI, we may want to turn off the compiler optimization and
+make debugging produce the expected results for a better debugging experience.
+To build with optimization off we can just simply add `DEBUG=1`, like:
+```
+make DEBUG=1
+```
+
+This definition is ONLY for development and debug purpose, and should NOT be
+used in a product build.
+
Contributing to OpenSBI
-----------------------
* [Platform Documentation]: Documentation of the platforms currently supported.
* [Firmware Documentation]: Documentation for the different types of firmware
examples build supported by OpenSBI.
+* [Domain Support]: Documentation for the OpenSBI domain support which helps
+ users achieve system-level partitioning using OpenSBI.
OpenSBI source code is also well documented. For source level documentation,
doxygen style is used. Please refer to the [Doxygen manual] for details on this
[Github]: https://github.com/riscv/riscv-sbi-doc
[U-Boot]: https://www.denx.de/wiki/U-Boot/SourceCode
+[Bootlin toolchain repository]: https://toolchains.bootlin.com/
[COPYING.BSD]: COPYING.BSD
[SPDX]: http://spdx.org/licenses/
[Contribution Guideline]: docs/contributing.md
[Platform Support Guide]: docs/platform_guide.md
[Platform Documentation]: docs/platform/platform.md
[Firmware Documentation]: docs/firmware/fw.md
+[Domain Support]: docs/domain_support.md
[Doxygen manual]: http://www.doxygen.nl/manual/index.html
[Kendryte standalone SDK]: https://github.com/kendryte/kendryte-standalone-sdk
[third party notices]: ThirdPartyNotices.md
+[reproducible builds]: https://reproducible-builds.org
projects / platform / kernel / opensbi.git / blobdiff