Firmware/opensbi
8
0
Fork 0
forked from Mirrors/opensbi
Code Pull Requests Activity

docs: improve library usage document

Browse Source 
Clarify the libraries descriptions.

Signed-off-by: Damien Le Moal <damien.lemoal@wdc.com>
This commit is contained in:
Damien Le Moal
2019-02-07 18:41:50 +09:00
committed by Anup Patel
parent b1b7e49c63
commit 01fe779113
1 changed files with 30 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files

52
docs/library_usage.md
View File

@@ -1,30 +1,36 @@
OpenSBI Library Usage Guideline OpenSBI Library Usage
=============================== =====================
OpenSBI provides two types of static libraries: OpenSBI provides two types of static libraries:
1. *libsbi.a* - A generic OpenSBI static library installed at 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* *<install_directory>/lib/libsbi.a*
2. *libplatsbi.a* - A platform specific OpenSBI static library, that is, 2. *libplatsbi.a* - An example platform specific static library integrating
libsbi.a plus platform specific hooks installed at *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* *<install_directory>/platform/<platform_subdir>/lib/libplatsbi.a*
The platform specific firmwares provided by OpenSBI are not mandatory. Users Implementations may choose either *libsbi.a* or *libplatsbi.a* to link with
can always link OpenSBI as static library to their favorite M-mode firmware their firmware or bootloader. In the case of *libsbi.a*, platform specific
or bootloader provided that it has a license compatible with OpenSBI license. hooks in the form of a *struct sbi_platform* instance needs to be provided.
Users can choose either *libsbi.a* or *libplatsbi.a* to link with their The platform specific example firmwares provided by OpenSBI are not mandatory.
firmware or bootloader but with *libsbi.a* platform specific hooks (i.e. An implementation may choose to link OpenSBI generic static library together
*struct sbi_platform* instance) will have to be provided. 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.
Constraints on OpenSBI usage from external firmware Constraints on OpenSBI usage from external firmware
--------------------------------------------------- ---------------------------------------------------
Users have to ensure that external firmware or bootloader and OpenSBI static Users have to ensure that an external firmware or bootloader linking against
library (*libsbi.a* or *libplatsbi.a*) are compiled with the same GCC target OpenSBI static libraries (*libsbi.a* or *libplatsbi.a*) are compiled with the
options *-mabi*, *-march*, and *-mcmodel*. same GCC target options *-mabi*, *-march*, and *-mcmodel*.
There are only two constraints on calling any OpenSBI function from an There are only two constraints on calling any OpenSBI library function from an
external M-mode firmware or bootloader: external M-mode firmware or bootloader:
1. The RISC-V *MSCRATCH* CSR must point to a valid OpenSBI scratch space 1. The RISC-V *MSCRATCH* CSR must point to a valid OpenSBI scratch space
@@ -35,15 +41,16 @@ external M-mode firmware or bootloader:
The most important functions from an external firmware or bootloader The most important functions from an external firmware or bootloader
perspective are *sbi_init()* and *sbi_trap_handler()*. perspective are *sbi_init()* and *sbi_trap_handler()*.
In addition to above constraints, the external firmware or bootloader must 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 *MSTATUS* and *MIE* CSRs when calling
*sbi_init()* and *sbi_trap_handler()* functions. the functions *sbi_init()* and *sbi_trap_handler()*.
The *sbi_init()* should be called by the external firmware or bootloader The *sbi_init()* function should be called by the external firmware or
when a HART is powered-up at boot-time or in response to a CPU hotplug event. bootloader for each HART that is powered-up at boot-time or in response to a
CPU hotplug event.
The *sbi_trap_handler()* should be called by the external firmware or The *sbi_trap_handler()* function should be called by the external firmware or
bootloader for the following interrupts and traps: bootloader to service the following interrupts and traps:
1. M-mode timer interrupt 1. M-mode timer interrupt
2. M-mode software interrupt 2. M-mode software interrupt
@@ -54,4 +61,5 @@ bootloader for the following interrupts and traps:
7. Hypervisor ecall trap 7. Hypervisor ecall trap
**Note:** external firmwares or bootloaders can be more conservative by **Note:** external firmwares or bootloaders can be more conservative by
forwarding all traps and interrupts to *sbi_trap_handler()* forwarding all traps and interrupts to *sbi_trap_handler()*.