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>

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