Add crate README files

Signed-off-by: Maksym Pavlenko <pavlenko.maksym@gmail.com>

Author: mxpv

README.md

@@ -6,10 +6,21 @@
 
 Build virtualization solutions on top of a lightweight hypervisor using Rust:
 - Full Hypervisor Framework support.
-- Rusty API.
 - Supports Apple Silicon.
+- Rusty API.
+
+This repository contains the following crates:
+| Name | Description |
+| --- | --- |
+| [hv-sys](./hv-sys) | Unsafe bindings generated with bindgen |
+| [hv](./hv) | High level API to access Hypervisor Framework |
+
+[Apple Documentation](https://developer.apple.com/documentation/hypervisor)
 
-[Documentation](https://developer.apple.com/documentation/hypervisor)
+### Current list of things to do:
+- Make high level API safer.
+- Expand documentation.
+- Add more examples.
 
 ## Requirements
 

hv-sys/Cargo.toml

@@ -5,10 +5,10 @@ edition = "2018"
 description = "Unsafe bindings for Hypervisor Framework generated with bindgen"
 authors = ["Maksym Pavlenko <pavlenko.maksym@gmail.com>"]
 repository = "https://github.com/mxpv/hv"
-license-file = "../LICENSE"
-readme = "../README.md"
-
-[dependencies]
+license = "Apache-2.0"
+readme = "README.md"
+keywords = ["hypervisor", "virtualization", "microvm", "macos", "apple"]
+categories = ["os::macos-apis", "api-bindings", "hardware-support"]
 
 [build-dependencies]
 bindgen = "0.58"

hv-sys/README.md

@@ -0,0 +1,18 @@
+# hv-sys
+
+[![CI](https://github.com/mxpv/hv/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/mxpv/hv/actions/workflows/ci.yml)
+
+Unsafe `-sys` crate with raw, unsafe bindings for [Hypervisor Framework](https://developer.apple.com/documentation/hypervisor), automatically generated with `bindgen`.
+
+Please don't use this crate directly, have a look on [hv](https://crates.io/crates/hv) crate instead.
+It offers high level safer Rust API to access Hypervisor Framework.
+
+Also please see the [repository](https://github.com/mxpv/hv) for ongoing work, questions, submit bugs, etc.
+
+## Usage
+
+Add the following to your `Cargo.toml`:
+```toml
+[dependencies]
+hv-sys = "0.1"
+```

hv/Cargo.toml

@@ -5,8 +5,10 @@ edition = "2018"
 description = "High level Rust bidings to Hypervisor Framework"
 authors = ["Maksym Pavlenko <pavlenko.maksym@gmail.com>"]
 repository = "https://github.com/mxpv/hv"
-license-file = "../LICENSE"
-readme = "../README.md"
+license = "Apache-2.0"
+readme = "README.md"
+keywords = ["hypervisor", "virtualization", "microvm", "macos", "apple"]
+categories = ["os::macos-apis", "api-bindings", "hardware-support"]
 
 [dependencies]
 bitflags = "1.2"
@@ -18,3 +20,11 @@ libc = "0.2"
 [features]
 hv_10_15 = []
 default = ["hv_10_15"]
+
+# Query basic caps
+[[example]]
+name = "caps"
+
+# Apple Silicon
+[[example]]
+name = "as"

hv/README.md

@@ -0,0 +1,71 @@
+# hv
+
+[![CI](https://github.com/mxpv/hv/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/mxpv/hv/actions/workflows/ci.yml)
+
+`hv` is a high level Rust bindings for Hypervisor Framework.
+
+Build virtualization solutions on top of a lightweight hypervisor using Rust:
+- Full Hypervisor Framework support.
+- Supports Apple Silicon.
+- Rusty API.
+
+Please also see the [repository](https://github.com/mxpv/hv) for latest changes and updates.
+
+## Requirements
+
+### Hypervisor Framework
+
+At runtime, determine whether the Hypervisor APIs are available on a particular machine with the `sysctl`:
+
+```bash
+$ sysctl kern.hv_support
+kern.hv_support: 1
+```
+
+In order to use Hypervisor API your app must have `com.apple.security.hypervisor` entitlement.
+Refer to [example.entitlements](example.entitlements) for example of how entitlement file might look like.
+
+Use the following command to self sign your binary for local development:
+
+```bash
+$ codesign --sign - --force --entitlements=example.entitlements ./binary
+```
+
+### Rust
+
+Developed and tested on latest stable Rust (1.53.0+).
+
+Be sure to have [Xcode](https://developer.apple.com/xcode/) installed and don't forget to `xcode-select --install`,
+otherwise `bindgen` may fail to find Hypervisor headers.
+
+## Usage
+
+This crate uses [hv-sys]()
+
+## Example
+
+Here is basic "Hello world" example on Apple Silicon:
+```rust
+// Init VM
+hv::Vm::create_vm(ptr::null_mut())?;
+
+// Initialize guest memory
+hv::Vm::map(load_addr, GUEST_ADDR as _, MEM_SIZE as _, hv::Memory::READ)?;
+
+// Create VCPU
+let cpu = hv::Vm::create_cpu()?;
+
+// Set regs
+cpu.set_reg(Reg::PC, GUEST_ADDR)?;
+cpu.set_reg(Reg::X1, GUEST_RESULT_ADDR)?;
+
+// Run CPU
+loop {
+    cpu.run()?;
+
+    let info = cpu.exit_info();
+    println!("{:?}", info);
+
+    break;
+}
+```