Merge pull request #292 from TimePrinciple/monorepo

monorepo: Merge `kvm-bindings` into `kvm-ioctls`

Author: roypat

.buildkite/custom-tests.json

@@ -0,0 +1,38 @@
+{
+    "tests": [
+        {
+            "test_name": "build-fam-gnu",
+            "command": "cargo build --release --features=fam-wrappers",
+            "platform": [
+                "x86_64",
+                "aarch64",
+                "riscv64"
+            ]
+        },
+        {
+            "test_name": "build-fam-musl",
+            "command": "cargo build --release --features=fam-wrappers --target {target_platform}-unknown-linux-musl",
+            "platform": [
+                "x86_64",
+                "aarch64"
+            ]
+        },
+        {
+            "test_name": "build-serde-gnu",
+            "command": "cargo build --release --features=serde",
+            "platform": [
+                "x86_64",
+                "aarch64",
+                "riscv64"
+            ]
+        },
+        {
+            "test_name": "build-serde-musl",
+            "command": "cargo build --release --features=serde --target {target_platform}-unknown-linux-musl",
+            "platform": [
+                "x86_64",
+                "aarch64"
+            ]
+        }
+    ]
+}

.cargo/config.toml

@@ -1,2 +1,5 @@
+# This workaround is needed because the linker is unable to find __addtf3,
+# __multf3 and __subtf3.
+# Related issue: https://github.com/rust-lang/compiler-builtins/issues/201
 [target.aarch64-unknown-linux-musl]
-rustflags = [ "-C", "target-feature=+crt-static", "-C", "link-arg=-lgcc" ]
+rustflags = [ "-C", "target-feature=+crt-static", "-C", "link-arg=-lgcc"]

.gitignore

@@ -1,5 +1,5 @@
 Cargo.lock
-/target
+target
 .idea
 **/*.rs.bk
 **/.pytest_cache/

Cargo.toml

@@ -1,19 +1,6 @@
-[package]
-name = "kvm-ioctls"
-version = "0.19.0"
-authors = ["Amazon Firecracker Team <[email protected]>"]
-description = "Safe wrappers over KVM ioctls"
-repository = "https://github.com/rust-vmm/kvm-ioctls"
-readme = "README.md"
-keywords = ["kvm"]
-license = "Apache-2.0 OR MIT"
-edition = "2021"
-
-[dependencies]
-libc = "0.2.39"
-kvm-bindings = { version = "0.10.0", features = ["fam-wrappers"] }
-vmm-sys-util = "0.12.1"
-bitflags = "2.4.1"
-
-[dev-dependencies]
-byteorder = "1.2.1"
+[workspace]
+resolver = "2"
+members = [
+    "kvm-bindings",
+    "kvm-ioctls",
+]

coverage_config_aarch64.json

@@ -1,5 +1,5 @@
 {
-  "coverage_score": 77.1,
+  "coverage_score": 60.9,
   "exclude_path": "",
-  "crate_features": ""
+  "crate_features": "fam-wrappers,serde"
 }

coverage_config_x86_64.json

@@ -1,5 +1,5 @@
 {
-  "coverage_score": 92.61,
-  "exclude_path": "",
-  "crate_features": ""
+  "coverage_score": 91.46,
+  "exclude_path": ".*bindings\\.rs",
+  "crate_features": "fam-wrappers,serde"
 }

kvm-bindings/CHANGELOG.md

@@ -0,0 +1,122 @@
+# Changelog
+## [Unreleased]
+
+### Added
+
+### Changed
+
+### Removed
+
+## [0.10.0]
+
+### Added
+
+- RISC-V KVM bindings for Linux kernel v6.9, including serialization support.
+
+## [0.9.1]
+
+### Changed
+
+- Fixed and validated manual (De)Serialize implementations to work with
+  `serde_json` crate.
+
+## [0.9.0]
+
+### Changed
+
+- Replaced the v6.2 bindings of arm64, x86\_64 with the v6.9 ones.
+
+### Removed
+
+- Removed v6.2 bindings.
+
+## [0.8.2]
+
+### Changed 
+
+- Improve performance of bindings deserialization by \~5% by avoiding
+  a temporary allocation.
+
+## [0.8.1]
+
+### Fixed
+
+- Implement `Default` for `kvm_xsave2`, which fixes usage of `Xsave`
+  unconditionally causing compile errors in downstream crates.
+
+## [0.8.0]
+
+### Added
+
+- An opt-in feature `serde` that enables [`serde`](https://serde.rs)-based
+  (de)serialization of various bindings. 
+
+## [0.7.0]
+
+### Changed
+- API change in the bindings from upstream kernel changes:
+  * system\_event has been made into a new union
+- The x86 module has been renamed to x86\_64 for consistency (matches the kernel
+  architecture directory name)
+- Added all features to the generated docs.rs documentation.
+
+### Removed
+
+- Dropped "x86" (32-bit) x86 support
+
+## [0.6.0]
+
+### Changed
+
+- Updated vmm-sys-utils dependency to 0.11.0
+- Switched to specifying dependencies using caret requirements
+  instead of comparision requirements
+
+### Added
+
+- Implement `PartialEq` for fam\_wrappers 
+
+## [0.5.0]
+
+### Changed
+
+- Replaced the v4.20 bindings with the v5.13 ones.
+
+### Removed
+
+- Removed v4.14 bindings.
+
+## [0.4.0]
+
+- vmm-sys-utils dependency bumped to match kvm-ioctls.
+
+## [0.3.0]
+
+### Added
+
+- Enabled `fam-wrappers` support on arm and arm64.
+- Added fam-wrapper for the arm specific `kvm_reg_list` struct.
+
+## [0.2.0]
+
+### Added
+
+- Added opt-in feature `fam-wrappers` that enables exporting
+  safe wrappers over generated structs with flexible array
+  members. This optional feature has an external dependency
+  on `vmm-sys-util`.
+- Added safe fam-wrappers for `kvm_msr_list`, `kvm_msrs`,
+  and `kvm_cpuid2`.
+
+## [0.1.1]
+
+### Changed
+
+- Do not enforce rust Edition 2018.
+
+## [0.1.0]
+
+### Added
+
+- KVM bindings for Linux kernel version 4.14 and 4.20 with
+  support for arm, arm64, x86 and x86_64.

kvm-bindings/CONTRIBUTING.md

@@ -0,0 +1,109 @@
+# Contributing to kvm-bindings
+
+## Dependencies
+
+### Bindgen
+The bindings are currently generated using
+[bindgen](https://crates.io/crates/bindgen) version 0.70.1:
+```bash
+cargo install bindgen-cli --vers 0.70.1
+```
+
+### Linux Kernel
+Generating bindings depends on the Linux kernel, so you need to have the
+repository on your machine:
+
+```bash
+git clone https://github.com/torvalds/linux.git
+```
+
+## Updating bindings / adding a new architecture
+
+When adding a new architecture, the bindings must be generated for all existing
+versions for consistency reasons.
+
+### Example for arm64 and kernel version 6.9
+
+For this example we assume that you have both linux and kvm-bindings
+repositories in your root.
+
+```bash
+# Step 1 (if adding a new architecture): Create a new module using the name of the architecture in src/
+pushd kvm-bindings
+mkdir src/arm64
+popd
+
+# linux is the repository that you cloned at the previous step.
+pushd linux
+# Step 2: Checkout the version you want to generate the bindings for.
+git checkout v6.9
+
+# Step 3: Generate the bindings.
+# This will generate the headers for the targeted architecture and place them
+# in the user specified directory
+
+export ARCH=arm64
+make headers_install ARCH=$ARCH INSTALL_HDR_PATH="$ARCH"_headers
+pushd "$ARCH"_headers
+bindgen include/linux/kvm.h -o bindings.rs  \
+     --impl-debug --with-derive-default  \
+     --with-derive-partialeq  --impl-partialeq \
+     -- -Iinclude
+popd
+
+# Step 4: Copy the generated file to the arm64 module.
+popd
+cp linux/"$ARCH"_headers/bindings.rs kvm-bindings/src/arm64
+
+```
+
+Steps 2, 3 and 4 must be repeated for all existing architectures.
+
+Now that we have the bindings generated, for a new architecture we can copy the
+module file from one of the existing modules.
+
+```bash
+cp arm/mod.rs arm64/
+```
+
+Also, you will need to add the new architecture to `kvm-bindings/lib.rs`.
+
+When regenerating bindings, care must be taken to re-add various `zerocopy`
+derives under the `serde` feature. All items that require derives are
+listed in the `x86_64/serialize.rs` and `arm64/serialize.rs` inside the
+`serde_impls!` macro invocation, and missing derives will cause these
+modules to fail compilation. For all items listed here, the following
+derive should be present:
+
+```rs
+#[cfg_attr(
+    feature = "serde",
+    derive(zerocopy::AsBytes, zerocopy::FromBytes, zerocopy::FromZeroes)
+)]
+```
+
+Any types whose name contains a suffix akin to `__bindgen_ty_<number>` and
+which is contained in any struct listed in `serialize.rs` will also need
+to have this derive added (otherwise compilation will fail). Note that
+these types are not explicitly listed in `serialize.rs`, as their names
+can change across `bindgen.rs` versions.
+
+Lastly, in `x86_64/bindings.rs`, the derives also need to be added to
+`struct __BindgenBitfieldUnit<Storage>` and `struct __IncompleteArrayField<T>`.
+Additionally, these structs need to have their layout changed from `#[repr(C)]`
+to `#[repr(transparent)]`. This is needed because `zerocopy` traits can only be
+derived on generic structures that are `repr(transparent)` or `repr(packed)`.
+
+### Future Improvements
+All the above steps are scriptable, so in the next iteration I will add a
+script to generate the bindings.
+
+# Testing
+
+This crate is tested using
+[rust-vmm-ci](https://github.com/rust-vmm/rust-vmm-ci) and
+[Buildkite](https://buildkite.com/) pipelines. Each new feature added to this crate must be
+accompanied by Buildkite steps for testing the following:
+- Release builds (using musl/gnu) with the new feature on arm and x86
+- Coverage test as specified in the
+[rust-vmm-ci readme](https://github.com/rust-vmm/rust-vmm-ci#getting-started-with-rust-vmm-ci).

kvm-bindings/Cargo.toml

@@ -0,0 +1,29 @@
+[package]
+name = "kvm-bindings"
+version = "0.10.0"
+authors = ["Amazon firecracker team <[email protected]>"]
+description = "Rust FFI bindings to KVM generated using bindgen."
+repository = "https://github.com/rust-vmm/kvm-bindings"
+readme = "README.md"
+keywords = ["kvm"]
+license = "Apache-2.0"
+
+[package.metadata.docs.rs]
+all-features = true
+rustdoc-args = ["--cfg", "docsrs"]
+
+[features]
+fam-wrappers = ["vmm-sys-util"]
+# It is not needed to enable the `serde` feature of `vmm-sys-util` here, because due to how cargo merges features,
+# if a downstream crate enables vmm-sys-util in its Cargo.toml, it will get enabled globally.
+serde = ["dep:serde", "serde/derive", "dep:zerocopy"]
+
+
+[dependencies]
+vmm-sys-util = { version = "0.12.1", optional = true }
+serde = { version = "1.0.0", optional = true, features = ["derive"] }
+zerocopy = { version = "0.7.32", optional = true, features = ["derive"] }
+
+[dev-dependencies]
+bincode = "1.3.3"
+serde_json = "1.0.125"