From 8af20068d13986c7f66a595b89d4ef251b9d9e34 Mon Sep 17 00:00:00 2001 From: Anup Patel Date: Tue, 29 Jan 2019 17:59:02 +0530 Subject: [PATCH] docs: Add library usage guide This patch adds static library usage guide (i.e. docs/library_usage.md). Signed-off-by: Anup Patel --- docs/library_usage.md | 57 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) create mode 100644 docs/library_usage.md 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 + */lib/libsbi.a* +2. *libplatsbi.a* - A platform specific OpenSBI static library, that is, + libsbi.a plus platform specific hooks installed at + */platform//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