diff options
| author | Anup Patel <anup.patel@wdc.com> | 2019-01-29 17:59:02 +0530 |
|---|---|---|
| committer | Anup Patel <anup@brainfault.org> | 2019-01-30 12:14:30 +0530 |
| commit | 8af20068d13986c7f66a595b89d4ef251b9d9e34 (patch) | |
| tree | 8313509d907e69082ca5e08dcef275f61e831ede /docs | |
| parent | 27b55bb4da7321137693de7e6e73609e1271dce3 (diff) | |
docs: Add library usage guide
This patch adds static library usage guide (i.e.
docs/library_usage.md).
Signed-off-by: Anup Patel <anup.patel@wdc.com>
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/library_usage.md | 57 |
1 files changed, 57 insertions, 0 deletions
diff --git a/docs/library_usage.md b/docs/library_usage.md new file mode 100644 index 0000000..0eb74ef --- /dev/null +++ b/docs/library_usage.md @@ -0,0 +1,57 @@ +OpenSBI Library Usage Guideline +=============================== + +OpenSBI provides two types of static libraries: + +1. *libsbi.a* - A generic OpenSBI static library installed at + *<install_directory>/lib/libsbi.a* +2. *libplatsbi.a* - A platform specific OpenSBI static library, that is, + libsbi.a plus platform specific hooks installed at + *<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. + +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. + +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*. + +There are only two constraints on calling any OpenSBI 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 + +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 +ensure that interrupts are disabled in *MSTATUS* and *MIE* CSRs when calling +*sbi_init()* and *sbi_trap_handler()* functions. + +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_trap_handler()* should be called by the external firmware or +bootloader for the following interrupts and traps: + +1. M-mode timer interrupt +2. M-mode software interrupt +3. Illegal instruction trap +4. Misaligned load trap +5. Misaligned store trap +6. Supervisor ecall trap +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 |