diff options
| author | Damien Le Moal <damien.lemoal@wdc.com> | 2019-02-07 18:41:50 +0900 |
|---|---|---|
| committer | Anup Patel <anup@brainfault.org> | 2019-02-08 09:36:06 +0530 |
| commit | 01fe77911382ac61dd15e604e35660222c314a5d (patch) | |
| tree | 326388dee3d5bc3b686c485b74d5f11f18bd743a /docs/library_usage.md | |
| parent | b1b7e49c6372839a4ba37252e742f3f4769d8c46 (diff) | |
docs: improve library usage document
Clarify the libraries descriptions.
Signed-off-by: Damien Le Moal <damien.lemoal@wdc.com>
Diffstat (limited to 'docs/library_usage.md')
| -rw-r--r-- | docs/library_usage.md | 52 |
1 files changed, 30 insertions, 22 deletions
diff --git a/docs/library_usage.md b/docs/library_usage.md index 0eb74ef..579411f 100644 --- a/docs/library_usage.md +++ b/docs/library_usage.md @@ -1,30 +1,36 @@ -OpenSBI Library Usage Guideline -=============================== +OpenSBI Library Usage +===================== 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* -2. *libplatsbi.a* - A platform specific OpenSBI static library, that is, - libsbi.a plus platform specific hooks installed at +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* -The platform specific firmwares provided by OpenSBI are not mandatory. Users -can always link OpenSBI as static library to their favorite M-mode firmware -or bootloader provided that it has a license compatible with OpenSBI license. +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. -Users can choose either *libsbi.a* or *libplatsbi.a* to link with their -firmware or bootloader but with *libsbi.a* platform specific hooks (i.e. -*struct sbi_platform* instance) will have 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. Constraints on OpenSBI usage from external firmware --------------------------------------------------- -Users have to ensure that external firmware or bootloader and OpenSBI static -library (*libsbi.a* or *libplatsbi.a*) are compiled with the same GCC target -options *-mabi*, *-march*, and *-mcmodel*. +Users have to ensure that an external firmware or bootloader linking against +OpenSBI static libraries (*libsbi.a* or *libplatsbi.a*) are compiled with the +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: 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 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 -*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 -when a HART is powered-up at boot-time or in response to a CPU hotplug event. +The *sbi_init()* function should be called by the external firmware or +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 -bootloader for the following interrupts and traps: +The *sbi_trap_handler()* function should be called by the external firmware or +bootloader to service the following interrupts and traps: 1. M-mode timer interrupt 2. M-mode software interrupt @@ -54,4 +61,5 @@ bootloader for the following interrupts and traps: 7. Hypervisor ecall trap **Note:** external firmwares or bootloaders can be more conservative by -forwarding all traps and interrupts to *sbi_trap_handler()*
\ No newline at end of file +forwarding all traps and interrupts to *sbi_trap_handler()*. + |