Mirrors/opensbi
1
0
Fork 1
mirror of https://github.com/riscv-software-src/opensbi.git synced 2025-08-24 15:31:22 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs: miscellaneous documentation fixes and updates

Browse Source 
- fix some broken hyperlinks
- add additional hyperlinks to references to external documents
- reformat some paragraphs to keep lines under 80 characters
- unify the enumeration style between different parts of the
  documentation
- fix spelling/grammar mistakes
- extend the copyright notice in README.md to be the same as the
  one in COPYING.BSD

Signed-off-by: Karsten Merker <merker@debian.org>
Reviewed-by: Atish Patra <atish.patra@wdc.com>
This commit is contained in:
Karsten Merker
2019-05-05 12:33:25 +02:00
committed by Anup Patel
parent 3bb2d25f44
commit 0d33a981ec
10 changed files with 146 additions and 141 deletions
Download Patch File Download Diff File Expand all files Collapse all files

103
README.md
View File

@@ -1,4 +1,5 @@
Copyright (c) 2019 Western Digital Corporation or its affiliates.
Copyright (c) 2019 Western Digital Corporation or its affiliates
and other contributors.
RISC-V Open Source Supervisor Binary Interface (OpenSBI)
========================================================
@@ -6,53 +7,55 @@ RISC-V Open Source Supervisor Binary Interface (OpenSBI)
The **RISC-V Supervisor Binary Interface (SBI)** is the recommended interface
between:
1. A platform specific firmware running in M-mode and bootloader, hypervisor or
a general purpose OS executing in S-mode or HS-mode.
2. A hypervisor running in HS-mode and a bootloader or a general purpose OS
1. A platform-specific firmware running in M-mode and a bootloader, a
hypervisor or a general-purpose OS executing in S-mode or HS-mode.
2. A hypervisor running in HS-mode and a bootloader or a general-purpose OS
executing in VS-mode.
The *RISC-V SBI specification* is maintained as an independent project by the
RISC-V Foundation in [Github].
RISC-V Foundation on [Github] (https://github.com/riscv/riscv-sbi-doc).
The goal of the OpenSBI project is to provide an open-source reference
implementation of the RISC-V SBI specifications for platform specific firmwares
executing in M-mode (case 1 mentioned above). OpenSBI implementation can be
implementation of the RISC-V SBI specifications for platform-specific firmwares
executing in M-mode (case 1 mentioned above). An OpenSBI implementation can be
easily extended by RISC-V platform and system-on-chip vendors to fit a
particular hardware configuration.
The main component of OpenSBI is provided in the form of a platform independent
The main component of OpenSBI is provided in the form of a platform-independent
static library **libsbi.a** implementing the SBI interface. A firmware or
bootloader implementation can link against this library to ensure conformance
with the SBI interface specifications. *libsbi.a* also defines an interface for
integrating with platform specific operations provided by the platform firmware
implementation (e.g. console access functions, inter-processor interrupts
integrating with platform-specific operations provided by the platform firmware
implementation (e.g. console access functions, inter-processor interrupt
control, etc).
To illustrate the use of *libsbi.a* library, OpenSBI also provides a set of
platform specific support examples. For each example, a platform
specific static library *libplatsbi.a* can be compiled. This library implements
SBI calls processing by integrating *libsbi.a* with necessary platform dependent
hardware manipulation functions. For all supported platforms, OpenSBI also
provides several runtime firmware examples built using the platform
To illustrate the use of the *libsbi.a* library, OpenSBI also provides a set of
platform-specific support examples. For each example, a platform-specific
static library *libplatsbi.a* can be compiled. This library implements
SBI call processing by integrating *libsbi.a* with the necessary
platform-dependent hardware manipulation functions. For all supported platforms,
OpenSBI also provides several runtime firmware examples built using the platform
*libplatsbi.a*. These example firmwares can be used to replace the legacy
*riskv-pk* bootloader (aka BBL) and enable the use of well known bootloaders
such as [U-Boot].
*riscv-pk* bootloader (aka BBL) and enable the use of well-known bootloaders
such as [U-Boot] (https://git.denx.de/u-boot.git).
Required Toolchain
------------------
OpenSBI can be compiled natively or cross-compiled on a x86 host. For
cross-compilation, you can build your tool chain or just download from
the [bootlin] (https://toolchains.bootlin.com/).
cross-compilation, you can build your own toolchain or just download
a prebuilt one from the
[Bootlin toolchain repository] (https://toolchains.bootlin.com/).
Please note that only 64bit version of toolchain is available in bootlin
for now.
Please note that only a 64bit version of the toolchain is available in
the Bootlin toolchain repository for now.
Building and Installing OpenSBI Platform Independent Library
------------------------------------------------------------
Building and Installing the OpenSBI Platform-Independent Library
----------------------------------------------------------------
OpenSBI platform independent static library *libsbi.a* can be natively compiled
or cross-compiled on a host with a different base architecture than RISC-V.
The OpenSBI platform-independent static library *libsbi.a* can be compiled
natively or it can be cross-compiled on a host with a different base
architecture than RISC-V.
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.
@@ -63,8 +66,8 @@ To build *libsbi.a* simply execute:
make
```
All compiled binaries as well as the result *libsbi.a* static library file will
be placed in the *build/lib* directory. To specify an alternate build root
All compiled binaries as well as the resulting *libsbi.a* static library file
will be placed in the *build/lib* directory. To specify an alternate build root
directory path, run:
```
make O=<build_directory>
@@ -76,38 +79,38 @@ make install
```
This will create the *install* directory with all necessary include files
copied under the *install/include* directory and library file copied in the
*install/lib* directory. To specify an alternate installation root directory
path, run:
copied under the *install/include* directory and the library file copied into
the *install/lib* directory. To specify an alternate installation root
directory path, run:
```
make I=<install_directory> install
```
Building and Installing a Reference Platform Static Library and Firmwares
-------------------------------------------------------------------------
Building and Installing a Reference Platform Static Library and Firmware
------------------------------------------------------------------------
When the *PLATFORM=<platform_subdir>* argument is specified on the make command
line, the platform specific static library *libplatsbi.a* and firmware examples
line, the platform-specific static library *libplatsbi.a* and firmware examples
are built for the platform *<platform_subdir>* present in the directory
*platform* in OpenSBI top directory. For example, to compile the platform
library and firmware examples for QEMU RISC-V *virt* machine,
*platform* in the OpenSBI top directory. For example, to compile the platform
library and the firmware examples for the QEMU RISC-V *virt* machine,
*<platform_subdir>* should be *qemu/virt*.
To build *libsbi.a*, *libplatsbi.a* and the firmwares for one of the supported
platform, run:
To build *libsbi.a*, *libplatsbi.a* and the firmware for one of the supported
platforms, run:
```
make PLATFORM=<platform_subdir>
```
An alternate build directory path can also be specified.
An alternate build directory path can also be specified:
```
make PLATFORM=<platform_subdir> O=<build_directory>
```
The platform specific library *libplatsbi.a* will be generated in the
The platform-specific library *libplatsbi.a* will be generated in the
*build/platform/<platform_subdir>/lib* directory. The platform firmware files
will be under the *build/platform/<platform_subdir>/firmware* directory.
The compiled firmwares will be available in two different format: an ELF file
The compiled firmwares will be available in two different formats: an ELF file
and an expanded image file.
To install *libsbi.a*, *libplatsbi.a*, and the compiled firmwares, run:
@@ -115,16 +118,16 @@ To install *libsbi.a*, *libplatsbi.a*, and the compiled firmwares, run:
make PLATFORM=<platform_subdir> install
```
This will copy the compiled platform specific libraries and firmware files
This will copy the compiled platform-specific libraries and firmware files
under the *install/platform/<platform_subdir>/* directory. An alternate
install root directory path can be specified as follows.
install root directory path can be specified as follows:
```
make PLATFORM=<platform_subdir> I=<install_directory> install
```
In addition, platform specific configuration options can be specified with the
In addition, platform-specific configuration options can be specified with the
top-level make command line. These options, such as *PLATFORM_<xyz>* or
*FW_<abc>*, are platform specific and described in more details in the
*FW_<abc>*, are platform-specific and described in more details in the
*docs/platform/<platform_name>.md* files and
*docs/firmware/<firmware_name>.md* files.
@@ -155,7 +158,7 @@ files where the reused code is present.
under the terms of the BSD 2-Clause license. Any contributions to this
code must be made under the terms of both licenses.
2. Some source file for the Kendryte/k210 platform code are based on code from
the Kendryte [standalone SDK] available on github. These files retain the
the [Kendryte standalone SDK] available on github. These files retain the
original copyright and license of the Kendryte standalone SDK project and
are licensed under the terms of the Apache License, Version 2.0.
@@ -165,7 +168,7 @@ Contributing to OpenSBI
-----------------------
The OpenSBI project encourages and welcomes contributions. Contributions should
follow the rules described in OpenSBI [Contribution Guideline] document.
follow the rules described in the OpenSBI [Contribution Guideline] document.
In particular, all patches sent should contain a Signed-off-by tag.
The [Contributors List] document provides a list of individuals and
@@ -185,7 +188,7 @@ Detailed documentation of various aspects of OpenSBI can be found under the
examples build supported by OpenSBI.
OpenSBI source code is also well documented. For source level documentation,
doxygen style is used. Please refer to [Doxygen manual] for details on this
doxygen style is used. Please refer to the [Doxygen manual] for details on this
format.
Doxygen can be installed on Linux distributions using *.deb* packages using
@@ -234,6 +237,6 @@ make I=<install_directory> install_docs
[Platform Support Guide]: docs/platform_guide.md
[Platform Documentation]: docs/platform/platform.md
[Firmware Documentation]: docs/firmware/fw.md
[Doxygen manual]: http://www.stack.nl/~dimitri/doxygen/manual.html
[standalone SDK]: https://github.com/kendryte/kendryte-standalone-sdk
[Doxygen manual]: http://www.doxygen.nl/manual/index.html
[Kendryte standalone SDK]: https://github.com/kendryte/kendryte-standalone-sdk
[third party notices]: ThirdPartyNotices.md

23
docs/contributing.md
View File

@@ -1,19 +1,20 @@
OpenSBI Contribution Guideline
==============================
All contributions to OpenSBI can be sent in following ways:
1. Email patches to OpenSBI mailing list `opensbi@lists.infradead.org`
2. GitHub Pull Requests (PRs) to [OpenSBI main repository]
All contributions to OpenSBI can be sent in the following ways:
1. Email patches to the OpenSBI mailing list at `opensbi@lists.infradead.org`
2. GitHub Pull Requests (PRs) to the [OpenSBI main repository]
To join OpenSBI mailing list, please visit [OpenSBI infradead page].
To join the OpenSBI mailing list, please visit the [OpenSBI infradead page].
OpenSBI maintainers prefer patches via OpenSBI mailing list (option1 above)
so that they are visible to wider audience. All accepted patches on the
OpenSBI mailing list will be taken by any of the OpenSBI maintainers and
merged into [OpenSBI main repository] using GitHub PRs.
The OpenSBI maintainers prefer patches via the OpenSBI mailing list
(option 1 above) so that they are visible to a wider audience. All
accepted patches on the OpenSBI mailing list will be taken by any of
the OpenSBI maintainers and merged into the [OpenSBI main repository]
using GitHub PRs.
All contributed work must follow the following rules:
1. OpenSBI code should be written in accordance to [Linux coding style].
1. OpenSBI code should be written in accordance to the [Linux coding style].
2. This project embraces the [Developer Certificate of Origin (DCO)] for
contributions. This means that you must agree to the following prior to
submitting patches: if you agree with this developer certificate you
@@ -27,9 +28,9 @@ prefixes are for example "lib:", "platform:", "firmware:", "docs:" and "top:".
5. Maintainers should use "Rebase and Merge" when using GitHub to merge pull
requests to avoid creating unnecessary merge commits.
6. Maintainers should avoid creating branches directly in the main
riscv/opensbi repository. Instead prefer using a fork of riscv/opensbi main
riscv/opensbi repository. Instead prefer using a fork of the riscv/opensbi main
repository and branches within that fork to create pull requests.
7. A maintainer cannot merge his own pull requests in riscv/opensbi main
7. A maintainer cannot merge his own pull requests in the riscv/opensbi main
repository.
8. A pull request must get at least one review from a maintainer.
9. A pull request must spend at least 24 hours in review to allow for other

2
docs/doxygen.cfg
View File

@@ -44,7 +44,7 @@ PROJECT_NUMBER = "v@@OPENSBI_MAJOR@@.@@OPENSBI_MINOR@@"
# for a project that appears at the top of each page and should give viewer a
# quick idea about the purpose of the project. Keep the description short.
PROJECT_BRIEF = "Open source implemenation of supervisor binary interface"
PROJECT_BRIEF = "Open source implemenation of the supervisor binary interface"
# With the PROJECT_LOGO tag one can specify a logo or an icon that is included
# in the documentation. The maximum height of the logo should not exceed 55

22
docs/firmware/fw_jump.md
View File

@@ -6,19 +6,19 @@ handles the address of the next booting stage entry, e.g. a bootloader or an OS
kernel, without directly including the binary code for this next stage.
A *FW_JUMP* firmware is particularly useful when the booting stage executed
prior to OpenSBI firmware is capable of loading both the OpenSBI firmware and
the booting stage binary to follow OpenSBI firmware.
prior to the OpenSBI firmware is capable of loading both the OpenSBI firmware
and the booting stage binary to follow the OpenSBI firmware.
*FW_JUMP* Compilation
---------------------
A platform *FW_JUMP* firmware can be enabled by any of the following methods.
A platform *FW_JUMP* firmware can be enabled by any of the following methods:
1. Specifying `FW_JUMP=y` on the top level `make` command line.
2. Specifying `FW_JUMP=y` in the target platform *config.mk* configuration file.
The compiled *FW_JUMP* firmware ELF file is named *fw_jump.elf*. Its expanded
image file is *fw_jump.bin*. Both files are created in the platform specific
image file is *fw_jump.bin*. Both files are created in the platform-specific
build directory under the *build/platform/<platform_subdir>/firmware* directory.
*FW_JUMP* Firmware Configuration Options
@@ -27,26 +27,26 @@ build directory under the *build/platform/<platform_subdir>/firmware* directory.
To operate correctly, a *FW_JUMP* firmware requires some configuration
parameters to be defined using either the top level `make` command line or the
target platform *config.mk* configuration file. The possible parameters are as
follows.
follows:
* **FW_JUMP_ADDR** - Address of the entry point of the booting stage to be
executed following OpenSBI firmware. This address generally correspond
executed following OpenSBI firmware. This address generally corresponds
exactly to the address where this next booting stage was loaded. This is a
mandatory parameter. Compilation errors will result from not defining this
address.
* **FW_JUMP_FDT_ADDR** - Address where the *flattened device tree (FDT file)*
passed by the prior booting stage will be placed in memory before executing
the booting stage following OpenSBI firmware. If this option is not provided,
then OpenSBI firmware will pass zero as the FDT address to the following
booting stage.
the booting stage following the OpenSBI firmware. If this option is not
provided, then the OpenSBI firmware will pass zero as the FDT address to the
following booting stage.
*FW_JUMP* Example
-----------------
The *[qemu/virt]* and *[qemu/sifive_u]* platforms illustrates how to configure
The *[qemu/virt]* and *[qemu/sifive_u]* platforms illustrate how to configure
and use a *FW_JUMP* firmware. Detailed information regarding these platforms
can be found in the platforms documentation files.
can be found in the platform documentation files.
[qemu/virt]: ../platform/qemu_virt.md
[qemu/sifive_u]: ../platform/qemu_sifive_u.md

31
docs/firmware/fw_payload.md
View File

@@ -2,22 +2,22 @@ OpenSBI Firmware with Payload *FW_PAYLOAD*
==========================================
OpenSBI **firmware with Payload (FW_PAYLOAD)** is a firmware which directly
includes the binary for the booting stage to follow OpenSBI firmware execution.
Typically, this payload will be a bootloader or an OS kernel.
includes the binary for the booting stage to follow the OpenSBI firmware
execution. Typically, this payload will be a bootloader or an OS kernel.
A *FW_PAYLOAD* firmware is particularly useful when the booting stage executed
prior to OpenSBI firmware is not capable of loading both OpenSBI firmware and
the booting stage to follow OpenSBI firmware.
prior to the OpenSBI firmware is not capable of loading both the OpenSBI
firmware and the booting stage to follow OpenSBI firmware.
A *FW_PAYLOAD* firmware is also useful for cases where the booting stage prior
to OpenSBI firmware does not pass a *flattened device tree (FDT file)*. In such
case, a *FW_PAYLOAD* firmware allows embedding a flattened device tree in the
.text section of the final firmware.
to the OpenSBI firmware does not pass a *flattened device tree (FDT file)*. In
such a case, a *FW_PAYLOAD* firmware allows embedding a flattened device tree
in the .text section of the final firmware.
Enabling *FW_PAYLOAD* compilation
---------------------------------
The *FW_PAYLOAD* firmware can be enabled by any of the following methods.
The *FW_PAYLOAD* firmware can be enabled by any of the following methods:
1. Specifying `FW_PAYLOAD=y` on the top level `make` command line.
2. Specifying `FW_PAYLOAD=y` in the target platform *config.mk* configuration
@@ -25,7 +25,7 @@ The *FW_PAYLOAD* firmware can be enabled by any of the following methods.
The compiled *FW_PAYLOAD* firmware ELF file is named *fw_jump.elf*. Its
expanded image file is *fw_payload.bin*. Both files are created in the
platform specific build directory under the
platform-specific build directory under the
*build/platform/<platform_subdir>/firmware* directory.
Configuration Options
@@ -34,7 +34,7 @@ Configuration Options
A *FW_PAYLOAD* firmware is built according to configuration parameters and
options. These configuration parameters can be defined using either the top
level `make` command line or the target platform *config.mk* configuration
file. The parameters currently defined are as follows.
file. The parameters currently defined are as follows:
* **FW_PAYLOAD_OFFSET** - Offset from *FW_TEXT_BASE* where the payload binary
will be linked in the final *FW_PAYLOAD* firmware binary image. This
@@ -47,8 +47,8 @@ file. The parameters currently defined are as follows.
will be linked after the end of the base firmware binary in the final
*FW_PAYLOAD* firmware binary image. This configuration parameter is mandatory
if *FW_PAYLOAD_OFFSET* is not defined. If both *FW_PAYLOAD_OFFSET* and
*FW_PAYLOAD_ALIGN* are defined, *FW_PAYLOAD_OFFSET* is used and
*FW_PAYLOAD_ALIGN* ignored.
*FW_PAYLOAD_ALIGN* are defined, *FW_PAYLOAD_OFFSET* is used and
*FW_PAYLOAD_ALIGN* is ignored.
* **FW_PAYLOAD_PATH** - Path to the image file of the next booting stage
binary. If this option is not provided then a simple test payload is
@@ -78,13 +78,12 @@ file. The parameters currently defined are as follows.
*FW_PAYLOAD* Example
--------------------
The *[qemu/virt]* and *[qemu/sifive_u]* platforms illustrates how to configure
The *[qemu/virt]* and *[qemu/sifive_u]* platforms illustrate how to configure
and use a *FW_PAYLOAD* firmware. Detailed information regarding these platforms
can be found in the platforms documentation files.
can be found in the platform documentation files.
The *kendryte/k210* platform also enables build of a *FW_PAYLOAD* using an
The *kendryte/k210* platform also enables a build of a *FW_PAYLOAD* using an
internally defined device tree file (*FW_PAYLOAD_FDT*).
[qemu/virt]: ../platform/qemu_virt.md
[qemu/sifive_u]: ../platform/qemu_sifive_u.md

9
docs/firmware/payload_linux.md
View File

@@ -1,11 +1,10 @@
Linux as a direct payload to OpenSBI
====================================
OpenSBI has the capability to load Linux kernel image directly in supervisor
OpenSBI has the capability to load a Linux kernel image directly in supervisor
mode. The flattened image generated by the Linux kernel build process can be
provided as payload to OpenSBI.
provided as a payload to OpenSBI.
Detailed examples and platform guides can be found in both [QEMU](
../platform/qemu_virt.md) and [HiFive Unleashed](../platform/sifive_fu540.md)
platform guide respectively.
Detailed examples can be found in both the [QEMU](../platform/qemu_virt.md)
and the [HiFive Unleashed](../platform/sifive_fu540.md) platform guides.

16
docs/firmware/payload_uboot.md
View File

@@ -4,30 +4,32 @@ U-Boot as a payload to OpenSBI
[U-Boot](https://www.denx.de/wiki/U-Boot) is an open-source primary boot loader.
It can be used as first and/or second stage boot loader in an embedded
environment. In the context of OpenSBI, U-Boot can be specified as a payload to
OpenSBI firmware, becoming the boot stage following OpenSBI firmware
the OpenSBI firmware, becoming the boot stage following the OpenSBI firmware
execution.
The current stable upstream code of U-Boot does not yet include all patches
necessary to fully support OpenSBI. To use U-Boot as an OpenSBI payload, the
following out-of-tree patch series must be applied to the upstream U-Boot source
code.
code:
HiFive Unleashed support for U-Boot
https://lists.denx.de/pipermail/u-boot/2019-February/358058.html
This patch series enables a single CPU to execute U-Boot. As a result, the next
stage boot code such as Linux kernel can also only execute a single CPU. U-Boot
SMP support for RISC-V can be enabled with the following additional patches.
stage boot code such as a Linux kernel can also only execute on a single CPU.
U-Boot SMP support for RISC-V can be enabled with the following additional
patches:
https://lists.denx.de/pipermail/u-boot/2019-February/358393.html
Building and Generating U-Boot images
=====================================
Please refer to U-Boot build documentation for detailed instructions on how to build U-Boot images.
Please refer to the U-Boot build documentation for detailed instructions on
how to build U-Boot images.
Once U-Boot images are built, Linux kernel image need to be converted to a format
that U-Boot understands.
Once U-Boot images are built, the Linux kernel image needs to be converted
into a format that U-Boot understands:
```
<uboot-dir>/tools/mkimage -A riscv -O linux -T kernel -C none -a 0x80200000 -e 0x80200000 -n Linux -d \

33
docs/library_usage.md
View File

@@ -3,46 +3,46 @@ OpenSBI Library Usage
OpenSBI provides two types of static libraries:
1. *libsbi.a* - A platform independent generic static library implementing the
interface defined by the SBI specifications. Platform specific processing
1. *libsbi.a* - A platform-independent generic static library implementing the
interface defined by the SBI specifications. Platform-specific processing
hooks for the execution of this interface must be provided by the firmware or
bootloader linking with this library. This library is installed as
*<install_directory>/lib/libsbi.a*
2. *libplatsbi.a* - An example platform specific static library integrating
*libsbi.a* with platform specific hooks. This library is available only for
2. *libplatsbi.a* - An example platform-specific static library integrating
*libsbi.a* with platform-specific hooks. This library is available only for
the platforms supported by OpenSBI. This library is installed as
*<install_directory>/platform/<platform_subdir>/lib/libplatsbi.a*
Implementations may choose either *libsbi.a* or *libplatsbi.a* to link with
their firmware or bootloader. In the case of *libsbi.a*, platform specific
hooks in the form of a *struct sbi_platform* instance needs to be provided.
their firmware or bootloader. In the case of *libsbi.a*, platform-specific
hooks in the form of a *struct sbi_platform* instance need to be provided.
The platform specific example firmwares provided by OpenSBI are not mandatory.
An implementation may choose to link OpenSBI generic static library together
with an M-mode firmware or bootloader providing hardware specific hooks. Since
OpenSBI is a statically linked library, users must ensure that the license of
these external components is compatible with OpenSBI license.
The platform-specific example firmwares provided by OpenSBI are not mandatory.
An implementation may choose to link the OpenSBI generic static library together
with an M-mode firmware or bootloader providing the hardware-specific hooks.
Since OpenSBI is a statically linked library, users must ensure that the
license of these external components is compatible with the OpenSBI license.
Constraints on OpenSBI usage from external firmware
---------------------------------------------------
Users have to ensure that an external firmware or bootloader linking against
OpenSBI static libraries (*libsbi.a* or *libplatsbi.a*) are compiled with the
OpenSBI static libraries (*libsbi.a* or *libplatsbi.a*) is compiled with the
same GCC target options *-mabi*, *-march*, and *-mcmodel*.
There are only two constraints on calling any OpenSBI library function from an
external M-mode firmware or bootloader:
1. The RISC-V *MSCRATCH* CSR must point to a valid OpenSBI scratch space
(i.e. *struct sbi_scratch* instance)
2. The RISC-V *SP* register (i.e. stack pointer) must be set per-HART
pointing to distinct non-overlapping stacks
(i.e. a *struct sbi_scratch* instance).
2. The RISC-V *SP* register (i.e. the stack pointer) must be set per-HART
pointing to distinct non-overlapping stacks.
The most important functions from an external firmware or bootloader
perspective are *sbi_init()* and *sbi_trap_handler()*.
In addition to the above constraints, the external firmware or bootloader must
ensure that interrupts are disabled in *MSTATUS* and *MIE* CSRs when calling
ensure that interrupts are disabled in the *MSTATUS* and *MIE* CSRs when calling
the functions *sbi_init()* and *sbi_trap_handler()*.
The *sbi_init()* function should be called by the external firmware or
@@ -62,4 +62,3 @@ bootloader to service the following interrupts and traps:
**Note:** external firmwares or bootloaders can be more conservative by
forwarding all traps and interrupts to *sbi_trap_handler()*.

16
docs/platform/platform.md
View File

@@ -1,11 +1,12 @@
OpenSBI Supported Platforms
===========================
OpenSBI currently supports the following virtual and hardware platforms.
OpenSBI currently supports the following virtual and hardware platforms:
* **QEMU RISC-V Virt Machine**: Platform support for QEMU *virt* virtual RISC-V
machine. This virtual machine is intended for RISC-V software development and
test. More details on this platform can be found in the file *[qemu_virt.md]*.
* **QEMU RISC-V Virt Machine**: Platform support for the QEMU *virt* virtual
RISC-V machine. This virtual machine is intended for RISC-V software
development and tests. More details on this platform can be found in the
file *[qemu_virt.md]*.
* **QEMU SiFive Unleashed Machine**: Platform support for the *sifive_u* QEMU
virtual RISC-V machine. This is an emulation machine of the HiFive Unleashed
@@ -18,13 +19,14 @@ OpenSBI currently supports the following virtual and hardware platforms.
*[sifive_fu540.md]*.
* **Kendryte K210 SoC**: Platform support for the Kendryte K210 SoC used on
boards such as the Kendryte KD233 and Sipeed MAIX Dock boards.
boards such as the Kendryte KD233 or the Sipeed MAIX Dock.
The code for these supported platforms can be used as example to implement
support for other platforms. The *platform/template* directory also provides
template files for implementing support for a new platform. The *object.mk*,
*config.mk* and *platform.c* template files provides enough comments to facilitate
the implementation.
*config.mk* and *platform.c* template files provides enough comments to
facilitate the implementation.
[qemu_virt.md]: qemu_virt.md
[qemu_sifive_u.md]: qemu_sifive_u.md
[sifive_fu540.md]: sifive_fu540.md

32
docs/platform_guide.md
View File

@@ -1,15 +1,15 @@
OpenSBI Platform Support Guideline
==================================
OpenSBI platform support allows an implementation to define a set of platform
specific hooks (hardware manipulation functions) in the form of a
The OpenSBI platform support allows an implementation to define a set of
platform-specific hooks (hardware manipulation functions) in the form of a
*struct sbi_platform* data structure instance. This instance is required by
platform independent *libsbi.a* to execute platform specific operations.
the platform-independent *libsbi.a* to execute platform-specific operations.
Each of the reference platform support provided by OpenSBI define an instance
Each of the reference platform supports provided by OpenSBI defines an instance
of the *struct sbi_platform* data structure. For each supported platform,
*libplatsbi.a* integrates this instance with *libsbi.a* to create a platform
specific OpenSBI static library. This library is installed
*libplatsbi.a* integrates this instance with *libsbi.a* to create a
platform-specific OpenSBI static library. This library is installed
in *<install_directory>/platform/<platform_subdir>/lib/libplatsbi.a*
OpenSBI also provides implementation examples of bootable runtime firmwares for
@@ -22,21 +22,21 @@ for the legacy *riskv-pk* boot loader (BBL).
A complete doxygen-style documentation of *struct sbi_platform* and related
APIs is available in the file *include/sbi/sbi_platform.h*.
Adding a new platform support
-----------------------------
Adding support for a new platform
---------------------------------
Support for a new platform named *<xyz>* can be added as follows:
1. Create a directory named *<xyz>* under *platform/* directory
2. Create a platform configuration file named *config.mk* under
1. Create a directory named *<xyz>* under the *platform/* directory.
2. Create a platform configuration file named *config.mk* under the
*platform/<xyz>/* directory. This configuration file will provide
compiler flags, select common drivers, and select firmware options
3. Create *platform/<xyz>/objects.mk* file for listing the platform
specific object files to be compiled
4. Create *platform/<xyz>/platform.c* file providing a *struct sbi_platform*
instance
compiler flags, select common drivers, and select firmware options.
3. Create a *platform/<xyz>/objects.mk* file for listing the
platform-specific object files to be compiled.
4. Create a *platform/<xyz>/platform.c* file providing a *struct sbi_platform*
instance.
A template platform support code is available under the *platform/template*
A platform support code template is available under the *platform/template*
directory. Copying this directory and its content as a new directory named
*<xyz>* under the *platform/* directory will create all the files mentioned
above.