Update documentations; Release v0.5.0

Evian-Zhang · Aug 10, 2024 · 5baeb83 · 5baeb83
1 parent 8f5a684
commit 5baeb83
Show file tree

Hide file tree

Showing 8 changed files with 27 additions and 7 deletions.
diff --git a/CHANGELOG/v0.5.0.md b/CHANGELOG/v0.5.0.md
@@ -0,0 +1,9 @@
+# static-keys v0.5.0
+
+Add `loongarch64-unknown-linux-gnu` target.
+
+For x86-64 and x86 target, use strictly 5-byte JMP when generating initial static branches.
+
+For Linux target, use copy-then-remap to modify instructions. This may be slower than the previous `mprotect`-based way, but is more general for those targets with W^X on. Moreover, this is beneficial to the future multi-threaded version.
+
+Add additional cache clear mechanism. This is done by platform-specific instructions in [Evian-Zhang/clear-cache](https://github.com/Evian-Zhang/clear-cache).
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "static-keys"
-version = "0.4.0"
+version = "0.5.0"
 edition = "2021"
 authors = ["Evian-Zhang <evianzhang1999@163.com>"]
 license = "MIT OR Apache-2.0"

diff --git a/README.md b/README.md
@@ -15,6 +15,7 @@ Currently CI-tested platforms:
     * `i686-unknown-linux-gnu`
     * `aarch64-unknown-linux-gnu`
     * `riscv64gc-unknown-linux-gnu`
+    * `loongarch64-unknown-linux-gnu`
 * macOS
 
     * `aarch64-apple-darwin`
@@ -23,6 +24,8 @@ Currently CI-tested platforms:
     * `x86_64-pc-windows-msvc`
     * `i686-pc-windows-msvc`
 
+Note that when using cross-rs to build `loongarch64-unknown-linux-gnu` target, you should use latest cross-rs avaiable on GitHub. See [Evian-Zhang/static-keys#4](https://github.com/Evian-Zhang/static-keys/pull/4) for more details.
+
 For more comprehensive explanations and FAQs, you can refer to [GitHub Pages](https://evian-zhang.github.io/static-keys/en/) ([中文版文档](https://evian-zhang.github.io/static-keys/zh-Hans/)).
 
 ## Motivation
@@ -95,7 +98,7 @@ First, add this crate to your `Cargo.toml`:
 
 ```toml
 [dependencies]
-static-keys = "0.4"
+static-keys = "0.5"
 ```
 
 At the beginning of `main` function, you should invoke [`static_keys::global_init`](https://docs.rs/static-keys/latest/static_keys/fn.global_init.html) to initialize.

diff --git a/docs/en/src/FAQs.md b/docs/en/src/FAQs.md
@@ -11,7 +11,7 @@ Two reasons:
 
 In userland, it is very complicated to modify an instruction which may be executed by another thread. Linux kernel community once proposed a [`text_poke` syscall](https://lwn.net/Articles/574309/), but is still not available nowadays. BTW, [Linus doesn't seem to like it](https://lore.kernel.org/lkml/CA+55aFzr9ZKcGfT_Q31T9_vuCcmWxGCh0wixuZqt7VhjxxYU9g@mail.gmail.com/), and his reasons do make sense.
 
-Another reason is that we need to manipulate memory protection to bypass DEP, which may involves race condition on the protection itself in multi-thread environment.
+Another reason is that we need to manipulate memory protection to bypass DEP, which may involves race condition on the protection itself in multi-thread environment. Mutex may be used to avoid data race, while if cargo resolves multi-version static-key crates dependencies, the mutexes would be duplicated for each version, and this approach is thus useless. This shall be resolved when [RFC 1977: public & private dependencies](https://github.com/rust-lang/rust/issues/44663) is stabilized. [rust-lang/cargo#2363](https://github.com/rust-lang/cargo/issues/2363) is also a reference.
 
 ## Why is nightly Rust required?
 
@@ -34,6 +34,7 @@ Because when passing a static variable to inline assembly as `sym` argument, it
 ## What arch-specific features are required to extend to new architectures?
 
 * A `nop` instruction with same length as `jmp` (or can divide the length, e.g. 2-byte `nop` and 4-byte `jmp`)
+* Approaches to clear instruction cache in Linux. (Should be added to [Evian-Zhang/clear-cache](https://github.com/Evian-Zhang/clear-cache))
 * Inline assembly supported by Rust
 
 ## Can I use this crate in `no_std`?

diff --git a/docs/en/src/README.md b/docs/en/src/README.md
@@ -15,6 +15,7 @@ Currently CI-tested platforms:
     * `i686-unknown-linux-gnu`
     * `aarch64-unknown-linux-gnu`
     * `riscv64gc-unknown-linux-gnu`
+    * `loongarch64-unknown-linux-gnu`
 * macOS
 
     * `aarch64-apple-darwin`
@@ -23,6 +24,8 @@ Currently CI-tested platforms:
     * `x86_64-pc-windows-msvc`
     * `i686-pc-windows-msvc`
 
+Note that when using cross-rs to build `loongarch64-unknown-linux-gnu` target, you should use latest cross-rs avaiable on GitHub. See [Evian-Zhang/static-keys#4](https://github.com/Evian-Zhang/static-keys/pull/4) for more details.
+
 For more comprehensive explanations and FAQs, you can refer to [GitHub Pages](https://evian-zhang.github.io/static-keys/en/) ([中文版文档](https://evian-zhang.github.io/static-keys/zh-Hans/)).
 
 ## Motivation
@@ -95,7 +98,7 @@ First, add this crate to your `Cargo.toml`:
 
 ```toml
 [dependencies]
-static-keys = "0.4"
+static-keys = "0.5"
 ```
 
 At the beginning of `main` function, you should invoke [`static_keys::global_init`](https://docs.rs/static-keys/latest/static_keys/fn.global_init.html) to initialize.

diff --git a/docs/zh-Hans/src/FAQs.md b/docs/zh-Hans/src/FAQs.md
@@ -11,7 +11,7 @@
 
 在用户态，如果要修改别的线程可能会执行到的指令会非常复杂。Linux内核社区曾经提出过[`text_poke`系统调用](https://lwn.net/Articles/574309/)，但是如今仍不可用。顺带一提，[Linus好像不太喜欢这个](https://lore.kernel.org/lkml/CA+55aFzr9ZKcGfT_Q31T9_vuCcmWxGCh0wixuZqt7VhjxxYU9g@mail.gmail.com/)，并且他说的很有道理。
 
-另一个原因是我们需要操作内存保护权限来绕过DEP，但是在多线程环境下，这会引发保护权限本身的race condition。
+另一个原因是我们需要操作内存保护权限来绕过DEP，但是在多线程环境下，这会引发保护权限本身的race condition。尽管可以用mutex来解决数据竞争的问题，但是如果cargo解析出多版本的static-keys依赖，那么每个版本中都会有一个全局mutex实例，这种方法就失效了。这个可以被[RFC 1977: public & private dependencies](https://github.com/rust-lang/rust/issues/44663)解决。[rust-lang/cargo#2363](https://github.com/rust-lang/cargo/issues/2363)亦可供参考。
 
 ## 为什么需要nightly Rust？
 
@@ -33,6 +33,7 @@
 ## 如果要扩展到新的指令集架构，需要实现哪些架构特性？
 
 * 与`jmp`等长的`nop`指令（或者可以整除，如2字节`nop`与4字节`jmp`）
+* 在Linux上清除指令缓存的方式（需加入到[Evian-Zhang/clear-cache](https://github.com/Evian-Zhang/clear-cache)）
 * Rust支持的内联汇编
 
 ## 我可以在`no_std`环境中使用吗？

diff --git a/docs/zh-Hans/src/README.md b/docs/zh-Hans/src/README.md
@@ -15,6 +15,7 @@
     * `i686-unknown-linux-gnu`
     * `aarch64-unknown-linux-gnu`
     * `riscv64gc-unknown-linux-gnu`
+    * `loongarch64-unknown-linux-gnu`
 * macOS
 
     * `aarch64-apple-darwin`
@@ -23,6 +24,8 @@
     * `x86_64-pc-windows-msvc`
     * `i686-pc-windows-msvc`
 
+需要注意，如果使用cross-rs交叉编译`loongarch64-unknown-linux-gnu`平台，需要使用GitHub上的最新版cross-rs。更多细节可参见[Evian-Zhang/static-keys#4](https://github.com/Evian-Zhang/static-keys/pull/4)。
+
 更详细的解释和FAQ可参见[GitHub Pages](https://evian-zhang.github.io/static-keys/zh-Hans/)([English version](https://evian-zhang.github.io/static-keys/en/)).
 
 ## 出发点
@@ -95,7 +98,7 @@ do_something:
 
 ```toml
 [dependencies]
-static-keys = "0.4"
+static-keys = "0.5"
 ```
 
 在`main`函数开头，需要调用[`static_keys::global_init`](https://docs.rs/static-keys/latest/static_keys/fn.global_init.html)进行初始化。