library_usage.md 2.4 KB

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()