lib: rename MachineInfo to EnvInfo to shorten trait name

Signed-off-by: Zhouqi Jiang <luojia@hust.edu.cn>

CHANGELOG.md

@@ -18,7 +18,7 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Modified
 
-- run on provided `MachineInfo` by default; bare metal M-mode environment should gate `machine`
+- run on provided `EnvInfo` by default; bare metal M-mode environment should gate `machine`
 - doc: grammar tweaks in hsm module
 - update dependency `sbi-spec` to v0.0.6, use `Physical` struct from `sbi-spec` crate.
 

examples/derive/commons.rs

@@ -1,7 +1,7 @@
 // Mock implementaion module. Actual SBI implementaion should implement
 // those SBI extensions with machine environment specific hardware features.
 
-use rustsbi::{HartMask, MachineInfo};
+use rustsbi::{HartMask, EnvInfo};
 use sbi_spec::binary::SbiRet;
 
 pub struct MyFence;
@@ -21,9 +21,9 @@ impl rustsbi::Fence for MyFence {
     }
 }
 
-pub struct MyMachineInfo;
+pub struct MyEnvInfo;
 
-impl MachineInfo for MyMachineInfo {
+impl EnvInfo for MyEnvInfo {
     fn mvendorid(&self) -> usize {
         0x100
     }

examples/derive/main.rs

@@ -24,7 +24,7 @@ struct MySBI {
     // CSR accesses; developers should enable RustSBI feature `machine` in this case.
     // The name `info` is also special, like the name `fence` we have mentioned;
     // RustSBI identifies machine information from the field name `info`.
-    info: MyMachineInfo,
+    info: MyEnvInfo,
 }
 
 // We have a properly defined RustSBI implementation called `MySBI`. Now `MySBI`
@@ -38,7 +38,7 @@ fn main() {
     // as a stack variable for now.
     let sbi = MySBI {
         fence: MyFence,
-        info: MyMachineInfo,
+        info: MyEnvInfo,
     };
 
     // In S-mode environment call handler, call the `handle_ecall` of the SBI instance.

macros/src/lib.rs

@@ -15,7 +15,7 @@ struct RustSBIImp<'a> {
     cppc: Option<&'a Ident>,
     nacl: Option<&'a Ident>,
     sta: Option<&'a Ident>,
-    machine_info: Option<&'a Ident>,
+    env_info: Option<&'a Ident>,
 }
 
 /// This macro should be used in `rustsbi` crate as `rustsbi::RustSBI`.
@@ -56,7 +56,7 @@ pub fn derive_rustsbi(input: TokenStream) -> TokenStream {
                 "cppc" => imp.cppc = Some(name),
                 "nacl" => imp.nacl = Some(name),
                 "sta" => imp.sta = Some(name),
-                "info" | "machine_info" => imp.machine_info = Some(name),
+                "info" | "env_info" => imp.env_info = Some(name),
                 _ => {}
             }
         }
@@ -96,17 +96,18 @@ fn impl_derive_rustsbi(name: &Ident, imp: RustSBIImp) -> TokenStream {
             sta: #sta_probe,
         }
     };
-    let base_procedure = if let Some(machine_info) = imp.machine_info {
+    let base_procedure = if let Some(env_info) = imp.env_info {
         quote! {
-            ::rustsbi::spec::base::EID_BASE => ::rustsbi::_rustsbi_base_machine_info(param, function, &self.#machine_info, #probe),
+            ::rustsbi::spec::base::EID_BASE => ::rustsbi::_rustsbi_base_env_info(param, function, &self.#env_info, #probe),
         }
     } else {
         match () {
             #[cfg(not(feature = "machine"))]
             () => quote! {
                 ::rustsbi::spec::base::EID_BASE => compile_error!(
-                    "can't derive RustSBI: #[cfg(feature = \"machine\")] is needed to derive RustSBI with no extra MachineInfo provided; \
-            consider adding an `info` parameter to provide machine information if RustSBI is not run on machine mode."
+                    "can't derive RustSBI: #[cfg(feature = \"machine\")] is needed to derive RustSBI with no extra `EnvInfo` provided; \
+            consider adding an `info` parameter to provide machine information implementing `rustsbi::EnvInfo`\
+            if RustSBI is not run on machine mode."
                 ),
             },
             #[cfg(feature = "machine")]

src/lib.rs

@@ -362,12 +362,12 @@
 //! or provide another set of information to override the current environment. Notably,
 //! RISC-V hypervisors do not have direct access to machine mode (M-mode) registers.
 //!
-//! RustSBI supports both by providing a `MachineInfo` structure in instance based interface.
+//! RustSBI supports both by providing a `EnvInfo` structure in instance based interface.
 //! If RISC-V hypervisors choose to use existing information on current machine, it may require
-//! to call underlying M-mode environment using SBI calls and fill in information into `MachineInfo`.
+//! to call underlying M-mode environment using SBI calls and fill in information into `EnvInfo`.
 //! If hypervisors use customized information other than taking the same one from the
-//! environment they reside in, they may fill in custom one into `MachineInfo` structures.
-//! When creating RustSBI instance, `MachineInfo` structure is required as an input of constructor.
+//! environment they reside in, they may fill in custom one into `EnvInfo` structures.
+//! When creating RustSBI instance, `EnvInfo` structure is required as an input of constructor.
 //!
 //! To begin with, include RustSBI library in file `Cargo.toml`:
 //!
@@ -550,7 +550,7 @@ pub extern crate sbi_spec as spec;
 ///
 /// # Usage
 ///
-/// The `#[derive(RustSBI)]` macro provides a convenient way of building `RustSBI` trait implementation.
+/// The `#[derive(RustSBI)]` macro provides a convenient way of building `RustSBI` trait implementations.
 /// To use this macro, say that we have a struct `MyFence` with RISC-V SBI Remote Fence extension
 /// implemented using `rustsbi::Fence` trait. Then, we build a struct around it, representing a
 /// whole SBI implementation including one `Fence` extension only; we can name it `MySBI`:
@@ -572,10 +572,10 @@ pub extern crate sbi_spec as spec;
 /// }
 /// ```
 ///
-/// Here, we declared the field named `fence` with type `MyFence`. The name `fence` is special, it tells
-/// RustSBI derive macro that this field implements SBI Remote Fence instead of other SBI extensions.
+/// Here, we declared the field named `fence` with type `MyFence`. The variable name `fence` is special,
+/// it tells RustSBI derive macro that this field implements SBI Remote Fence instead of other SBI extensions.
 /// We can continue to adding more fields into `MySBI`. For example, if we have RISC-V SBI Time extension
-/// implementation `MyTimer`, we can add it to `MySBI`:
+/// implementation with type `MyTimer`, we can add it to `MySBI`:
 ///
 /// ```rust
 /// struct MySBI {
@@ -615,7 +615,7 @@ pub extern crate sbi_spec as spec;
 /// Oops! Compile failed. We'd check what happened here:
 ///
 /// ```text
-/// error: can't derive RustSBI: #[cfg(feature = "machine")] is needed to derive RustSBI with no extra MachineInfo provided; consider adding an `info` parameter to provide machine information if RustSBI is not run on machine mode.
+/// error: can't derive RustSBI: #[cfg(feature = "machine")] is needed to derive RustSBI with no extra `EnvInfo` provided; consider adding an `info` parameter to provide machine information implementing `rustsbi::EnvInfo` if RustSBI is not run on machine mode.
 ///  --> example.rs:LL:10
 ///    |
 /// LL | #[derive(RustSBI)]
@@ -626,12 +626,12 @@ pub extern crate sbi_spec as spec;
 /// error: aborting due to previous error
 /// ```
 ///
-/// The error message hints that we don't have machine information implementing trait `MachineInfo`
-/// provided. By default, RustSBI is targeted to provide RISC-V supervisor environment on any hardware,
+/// The error message hints that we didn't provide any SBI environment information implementing trait
+/// `EnvInfo`. By default, RustSBI is targeted to provide RISC-V supervisor environment on any hardware,
 /// targeting hypervisor, emulator and binary translation applications. In this case, the virtualized
-/// environment should provide the supervisor with machine information like `mvendorid`, `marchid` and
-/// `mimpid` values. RustSBI could also be used on bare-metal RISC-V machines where such values would
-/// be directly accessible through CSR read operations.
+/// environment should provide the supervisor with machine environment information like `mvendorid`,
+/// `marchid` and `mimpid` values. RustSBI could also be used on bare-metal RISC-V machines where such
+/// values would be directly accessible through CSR read operations.
 ///
 /// If we are targeting bare-metal, we can use the RustSBI library with `#[cfg(feature = "machine")]`
 /// enabled by changing `dependencies` section in `Cargo.toml` file (if we are using Cargo):
@@ -642,7 +642,7 @@ pub extern crate sbi_spec as spec;
 /// ```
 ///
 /// If that's not the case and we are writing a virtualization targeted application, we should add a
-/// `MachineInfo` implementation into the structure like `MySBI` mentioned above, with a special field
+/// `EnvInfo` implementation into the structure like `MySBI` mentioned above, with a special field
 /// name `info`. We can do it like:
 ///
 /// ```rust
@@ -651,12 +651,12 @@ pub extern crate sbi_spec as spec;
 ///     fence: MyFence,
 ///     timer: MyTimer,
 /// #   #[cfg(not(feature = "machine"))]
-///     info: MyMachineInfo,
+///     info: MyEnvInfo,
 /// }
 ///
-/// struct MyMachineInfo;
+/// struct MyEnvInfo;
 ///
-/// impl rustsbi::MachineInfo for MyMachineInfo {
+/// impl rustsbi::EnvInfo for MyEnvInfo {
 ///     #[inline]
 ///     fn mvendorid(&self) -> usize { todo!("add real value here") }
 ///     #[inline]
@@ -690,14 +690,14 @@ pub extern crate sbi_spec as spec;
 /// #[derive(RustSBI)]
 /// struct MySBI {
 ///     /* we omit the extension fields by now */
-/// #   info: MyMachineInfo,
+/// #   info: MyEnvInfo,
 /// }
 ///
 /// fn main() {
 ///     // Create a MySBI instance.
 ///     let sbi = MySBI {
 ///         /* include initial values for fields */
-/// #       info: MyMachineInfo
+/// #       info: MyEnvInfo
 ///     };
 ///     // Make the call. Read SBI implementation ID resides in extension Base (0x10),
 ///     // with function id 1, and it doesn't have any parameters.
@@ -706,8 +706,8 @@ pub extern crate sbi_spec as spec;
 ///     println!("SBI implementation ID for MySBI: {}", ret.value);
 ///     assert_eq!(ret.value, 4);
 /// }
-/// # struct MyMachineInfo;
-/// # impl rustsbi::MachineInfo for MyMachineInfo {
+/// # struct MyEnvInfo;
+/// # impl rustsbi::EnvInfo for MyEnvInfo {
 /// #     fn mvendorid(&self) -> usize { unimplemented!() }
 /// #     fn marchid(&self) -> usize { unimplemented!() }
 /// #     fn mimpid(&self) -> usize { unimplemented!() }
@@ -720,8 +720,9 @@ pub extern crate sbi_spec as spec;
 /// SBI implementation ID for MySBI: 4
 /// ```
 ///
-/// The SBI call returns the number 4 as SBI call result. By looking up the RISC-V SBI Specification,
-/// we acknowledge that RustSBI have the implementation ID of 4. You have successfully made your first
+/// The SBI call returns the number 4 as SBI call result. By looking up
+/// [the RISC-V SBI Specification](https://github.com/riscv-non-isa/riscv-sbi-doc/blob/cf86bda6f57afb8e0e7011b61504d4e8664b9b1d/src/ext-base.adoc#sbi-implementation-ids),
+/// we can know that RustSBI have the implementation ID of 4. You have successfully made your first
 /// SBI call from a derived `RustSBI` implementation!
 ///
 /// If we learn further from the RISC-V privileged software architecture, we may know more about how
@@ -757,17 +758,17 @@ pub extern crate sbi_spec as spec;
 /// | `nacl` | [`Nacl`](trait.Nacl.html) | Nested Acceleration extension |
 /// | `sta` | [`Sta`](trait.Sta.html) | Steal Time Accounting extension |
 ///
-/// The `MachineInfo` parameter is used by RISC-V SBI Base extension which is always supported on all
-/// RISC-V SBI implementations. RustSBI provides Base extension with additional `MachineInfo` by default.
+/// The `EnvInfo` parameter is used by RISC-V SBI Base extension which is always supported on all
+/// RISC-V SBI implementations. RustSBI provides Base extension with additional `EnvInfo` by default.
 ///
 /// | Field names | RustSBI trait | Description |
 /// |:------------|:----------|:--------------|
-/// | `info` or `machine_info` | [`MachineInfo`](trait.MachineInfo.html) | Machine information used by Base extension |
+/// | `info` or `env_info` | [`EnvInfo`](trait.EnvInfo.html) | Machine environment information used by Base extension |
 ///
 /// Or, if `#[cfg(feature = "machine")]` is enabled, RustSBI derive macro does not require additional
-/// machine information but reads them by RISC-V CSR operation when we don't have any `MachineInfo`
+/// machine environment information but reads them by RISC-V CSR operation when we don't have any `EnvInfo`s
 /// in the structure. This feature would only work if RustSBI runs directly on machine mode hardware.
-/// If we are targeting other environments (virtualization etc.) we should provide `MachineInfo` instead
+/// If we are targeting other environments (virtualization etc.) we should provide `EnvInfo` instead
 /// of using the machine feature.
 ///
 /// # Examples
@@ -779,11 +780,11 @@ pub extern crate sbi_spec as spec;
 /// #[derive(RustSBI)]
 /// struct MySBI {
 ///     fence: MyFence,
-///     info: MyMachineInfo,
+///     info: MyEnvInfo,
 /// }
 ///
 /// // we assume that `MyFence` implements `rustsbi::Fence`
-/// // and `MyMachineInfo` implements `rustsbi::MachineInfo`.
+/// // and `MyEnvInfo` implements `rustsbi::EnvInfo`.
 /// # use rustsbi::{RustSBI, HartMask};
 /// # use sbi_spec::binary::SbiRet;
 /// # struct MyFence;
@@ -792,8 +793,8 @@ pub extern crate sbi_spec as spec;
 /// #     fn remote_sfence_vma(&self, _: HartMask, _: usize, _: usize) -> SbiRet { unimplemented!() }
 /// #     fn remote_sfence_vma_asid(&self, _: HartMask, _: usize, _: usize, _: usize) -> SbiRet { unimplemented!() }
 /// # }
-/// # struct MyMachineInfo;
-/// # impl rustsbi::MachineInfo for MyMachineInfo {
+/// # struct MyEnvInfo;
+/// # impl rustsbi::EnvInfo for MyEnvInfo {
 /// #     fn mvendorid(&self) -> usize { 1 }
 /// #     fn marchid(&self) -> usize { 2 }
 /// #     fn mimpid(&self) -> usize { 3 }
@@ -817,7 +818,7 @@ pub use rfence::Rfence as Fence;
 pub use sta::Sta;
 pub use susp::Susp;
 pub use timer::Timer;
-pub use traits::{MachineInfo, RustSBI};
+pub use traits::{EnvInfo, RustSBI};
 
 // Macro internal functions and structures
 
@@ -826,7 +827,7 @@ pub use traits::{MachineInfo, RustSBI};
 pub use traits::_rustsbi_base_bare;
 #[doc(hidden)]
 pub use traits::{
-    _StandardExtensionProbe, _rustsbi_base_machine_info, _rustsbi_console, _rustsbi_cppc,
+    _StandardExtensionProbe, _rustsbi_base_env_info, _rustsbi_console, _rustsbi_cppc,
     _rustsbi_fence, _rustsbi_hsm, _rustsbi_ipi, _rustsbi_nacl, _rustsbi_pmu, _rustsbi_reset,
     _rustsbi_sta, _rustsbi_susp, _rustsbi_timer,
 };

src/traits.rs

@@ -9,10 +9,10 @@ pub trait RustSBI {
     fn handle_ecall(&self, extension: usize, function: usize, param: [usize; 6]) -> SbiRet;
 }
 
-/// Machine information for SBI environment.
+/// Machine environment information for an SBI environment.
 ///
 /// This trait is useful to build an SBI environment when RustSBI is not run directly on RISC-V machine mode.
-pub trait MachineInfo {
+pub trait EnvInfo {
     /// Vendor ID for the supervisor environment.
     ///
     /// Provides JEDEC manufacturer ID of the provider of the core.
@@ -74,7 +74,7 @@ pub fn _rustsbi_base_bare(
 
 #[doc(hidden)]
 #[inline(always)]
-pub fn _rustsbi_base_machine_info<T: MachineInfo>(
+pub fn _rustsbi_base_env_info<T: EnvInfo>(
     param: [usize; 6],
     function: usize,
     machine_info: &T,

tests/build-full.rs

@@ -19,7 +19,7 @@ struct FullyImplemented {
     sta: DummySta,
     susp: DummySusp,
     timer: DummyTimer,
-    info: DummyMachineInfo,
+    info: DummyEnvInfo,
 }
 
 #[derive(RustSBI)]
@@ -35,7 +35,7 @@ struct AlternateName {
     sta: DummySta,
     susp: DummySusp,
     time: DummyTimer,
-    info: DummyMachineInfo,
+    info: DummyEnvInfo,
 }
 
 struct DummyConsole;
@@ -197,9 +197,9 @@ impl rustsbi::Timer for DummyTimer {
     }
 }
 
-struct DummyMachineInfo;
+struct DummyEnvInfo;
 
-impl rustsbi::MachineInfo for DummyMachineInfo {
+impl rustsbi::EnvInfo for DummyEnvInfo {
     fn mvendorid(&self) -> usize {
         unimplemented!()
     }
@@ -227,7 +227,7 @@ fn rustsbi_impl_id() {
         sta: DummySta,
         susp: DummySusp,
         timer: DummyTimer,
-        info: DummyMachineInfo,
+        info: DummyEnvInfo,
     };
     assert_eq!(sbi.handle_ecall(0x10, 0x1, [0; 6]).value, 4);
     let sbi = AlternateName {
@@ -242,7 +242,7 @@ fn rustsbi_impl_id() {
         sta: DummySta,
         susp: DummySusp,
         time: DummyTimer,
-        info: DummyMachineInfo,
+        info: DummyEnvInfo,
     };
     assert_eq!(sbi.handle_ecall(0x10, 0x1, [0; 6]).value, 4);
 }