Add initial readme, license and CI

.gitignore

@@ -0,0 +1 @@
+/target

Cargo.toml

@@ -1,8 +1,8 @@
 [package]
-name = "crate-template"
+name = "vmm-reference"
 version = "0.1.0"
-authors = [TODO]
-license = "Apache-2.0 OR BSD-3-Clause"
+authors = ["rust-vmm AWS maintainers <rust-vmm-maintainers@amazon.com>"]
 edition = "2018"
+license = "Apache-2.0 OR BSD-3-Clause"
 
 [dependencies]

LICENSE-BSD-3-CLAUSE

@@ -0,0 +1,26 @@
+Copyright 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+this list of conditions and the following disclaimer in the documentation
+and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+may be used to endorse or promote products derived from this software without
+specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -1,41 +1,57 @@
-# Crate Name
+# `vmm-reference`
 
 ## Design
 
-TODO: This section should have a high-level design of the crate.
+The purpose of the reference VMM is twofold:
 
-Some questions that might help in writing this section:
-- What is the purpose of this crate?
-- What are the main components of the crate? How do they interact which each
-  other?
+1. To serve as a starting point in the creation of tailor-made VMMs that users
+   build according to their needs. Users can fork the reference VMM, mix and
+   match its components and UI to create a functional VMM with a minimal attack
+   surface and resource footprint, custom-made to suit their isolation
+   requirements.
+1. To validate the `rust-vmm` crates that compose it and demonstrate their
+   functionality in a use-case-agnostic, end-to-end VMM.
 
-## Usage
+The reference VMM consists of `rust-vmm crates` and minimal glue code that
+sticks them together. The crate exposes several `pub fn`s that serve as entry
+points for pluggable UIs. A basic command line parser demonstrates how a
+frontend can be stitched to the VMM. Any external component that binds to the
+reference VMM's public Rust API can replace it.
 
-TODO: This section describes how the crate is used.
+The reference VMM is also a vehicle for end-to-end testing of `rust-vmm`
+crates. Each crate must contain individual functional and performance tests
+that exercise as wide a range of use cases as possible; the reference VMM is
+not meant to reiterate on that, but to validate all the pieces put together.
+The public Rust API facilitates Rust integration tests that exercise it.
 
-Some questions that might help in writing this section:
-- What traits do users need to implement?
-- Does the crate have any default/optional features? What is each feature
-  doing?
-- Is this crate used by other rust-vmm components? If yes, how?
+## Usage
 
-## Examples
+The reference VMM can be used out of the box as a `hello-world` example of a
+fully functional VMM built with `rust-vmm` crates.
+
+```bash
+cargo run                       \
+    --guest-memory=1024         \
+    --vcpus=1                   \
+    --kernel=/path/to/vmlinux   \
+    --cmdline="cmdline"
+    [--blk=<blkdev_config> - TBD]
+    [--net=<netdev_config> - TBD]
+```
 
-TODO: Usage examples.
+The crate's [`Cargo.toml`](Cargo.toml) controls which VMM functionalities are
+available. By default, all rust-vmm crates are listed as dependencies and
+therefore included. Users can play freely with the building blocks by modifying
+the TOML, and the prepackaged CLI can quickly validate the altered
+configurations. Advanced users can, of course, plug in their own front-end.
 
-```rust
-use my_crate;
+## CLI reference
 
-...
-```
+**TODO**
 
 ## License
 
-**!!!NOTICE**: The BSD-3-Clause license is not included in this template.
-The license needs to be manually added because the text of the license file
-also includes the copyright. The copyright can be different for different
-crates. If the crate contains code from CrosVM, the crate must add the
-CrosVM copyright which can be found
-[here](https://chromium.googlesource.com/chromiumos/platform/crosvm/+/master/LICENSE).
-For crates developed from scratch, the copyright is different and depends on
-the contributors.
+This project is licensed under either of:
+
+- [Apache License](LICENSE-APACHE), Version 2.0
+- [BSD-3-Clause License](LICENSE-BSD-3-CLAUSE)

main.rs

@@ -0,0 +1,3 @@
+fn main() {
+    println!("Hello, world, from the rust-vmm reference VMM!");
+}