Browse Source

add notes on legacy feature gate

luojia65 2 years ago
parent
commit
01c0e43b3a
1 changed files with 31 additions and 1 deletions
  1. 31 1
      src/lib.rs

+ 31 - 1
src/lib.rs

@@ -142,8 +142,12 @@
 //! it's better to include minimal feature in core repository, and leave other features for downstream developers.
 //!
 //! # Notes for RustSBI developers
+//! 
+//! Following useful hints are for firmware and kernel developers when working with SBI and RustSBI.
+//! 
+//! ## RustSBI is a library for interfaces
 //!
-//! This library adapts to embedded Rust's `embedded-hal` crate to provide basic SBI features.
+//! This library adapts to individual Rust traits to provide basic SBI features.
 //! When building for own platform, implement traits in this library and pass them to the functions
 //! begin with `init`. After that, you may call `rustsbi::ecall` in your own exception handler
 //! which would dispatch parameters from supervisor to the traits to execute SBI functions.
@@ -155,6 +159,32 @@
 //! Note that this crate is a library which contains common building blocks in SBI implementation.
 //! It is not intended to be used directly; users should build own platforms with this library.
 //! RustSBI provides implementations on common platforms in separate platform crates.
+//! 
+//! ## Legacy SBI extension
+//! 
+//! Note: RustSBI legacy support is only designed for backward compability. It's disabled by default and it's not
+//! suggested to include legacy functions in newer firmware designs. Modules other than legacy console is replaced by
+//! individual modules in SBI. Legacy console is not suggested to use in kernels. 
+//! If you are a kernel developer, newer designs should consider relying on each SBI module other than
+//! legacy functions.
+//! 
+//! The SBI includes legacy extension which dated back to SBI 0.1 specification. Most of its features
+//! are replaced by individual SBI modules, thus the entire legacy extension is deprecated by
+//! SBI version 0.2. However, some users may find out SBI 0.1 legacy console useful in some situations
+//! even if it's deprecated.
+//! 
+//! RustSBI keeps SBI 0.1 legacy support under feature gate `legacy`. To use RustSBI with legacy feature,
+//! you may change dependency code to:
+//! 
+//! ```toml
+//! [dependencies]
+//! rustsbi = { version = "0.3.0", features = ["legacy"] }
+//! ```
+//! 
+//! By using the `legacy` feature, RustSBI will include `embedded-hal` compliant blocking serial interface.
+//! You may use any embedded-hal implementation to implement the legacy console.
+//! RustSBI legacy feature only supports blocking embedded-hal interface, as is defined in legacy
+//! SBI 0.1 specification.
 
 #![no_std]
 #![feature(ptr_metadata)]