1# vm-memory 2 3[](https://crates.io/crates/vm-memory) 4[](https://docs.rs/vm-memory/) 5 6## Design 7 8In a typical Virtual Machine Monitor (VMM) there are several components, such 9as boot loader, virtual device drivers, virtio backend drivers and vhost 10drivers, that need to access the VM physical memory. The `vm-memory` crate 11provides a set of traits to decouple VM memory consumers from VM memory 12providers. Based on these traits, VM memory consumers can access the physical 13memory of the VM without knowing the implementation details of the VM memory 14provider. Thus VMM components based on these traits can be shared and reused by 15multiple virtualization solutions. 16 17The detailed design of the `vm-memory` crate can be found [here](DESIGN.md). 18 19### Platform Support 20 21- Arch: x86, AMD64, ARM64 22- OS: Linux/Unix/Windows 23 24### Xen support 25 26Supporting Xen requires special handling while mapping the guest memory and 27hence a separate feature is provided in the crate: `xen`. Mapping the guest 28memory for Xen requires an `ioctl()` to be issued along with `mmap()` for the 29memory area. The arguments for the `ioctl()` are received via the `vhost-user` 30protocol's memory region area. 31 32Xen allows two different mapping models: `Foreign` and `Grant`. 33 34In `Foreign` mapping model, the entire guest address space is mapped at once, in 35advance. In `Grant` mapping model, the memory for few regions, like those 36representing the virtqueues, is mapped in advance. The rest of the memory 37regions are mapped (partially) only while accessing the buffers and the same is 38immediately deallocated after the buffer is accessed. Hence, special handling 39for the same in `VolatileMemory.rs`. 40 41In order to still support standard Unix memory regions, for special regions and 42testing, the Xen specific implementation here allows a third mapping type: 43`MmapXenFlags::UNIX`. This performs standard Unix memory mapping and the same is 44used for all tests in this crate. 45 46It was decided by the `rust-vmm` maintainers to keep the interface simple and 47build the crate for either standard Unix memory mapping or Xen, and not both. 48 49Xen is only supported for Unix platforms. 50 51## Usage 52 53Add `vm-memory` as a dependency in `Cargo.toml` 54 55```toml 56[dependencies] 57vm-memory = "*" 58``` 59 60Then add `extern crate vm-memory;` to your crate root. 61 62## Examples 63 64- Creating a VM physical memory object in hypervisor specific ways using the 65 `GuestMemoryMmap` implementation of the `GuestMemory` trait: 66 67```rust 68fn provide_mem_to_virt_dev() { 69 let gm = GuestMemoryMmap::from_ranges(&[ 70 (GuestAddress(0), 0x1000), 71 (GuestAddress(0x1000), 0x1000) 72 ]).unwrap(); 73 virt_device_io(&gm); 74} 75``` 76 77- Consumers accessing the VM's physical memory: 78 79```rust 80fn virt_device_io<T: GuestMemory>(mem: &T) { 81 let sample_buf = &[1, 2, 3, 4, 5]; 82 assert_eq!(mem.write(sample_buf, GuestAddress(0xffc)).unwrap(), 5); 83 let buf = &mut [0u8; 5]; 84 assert_eq!(mem.read(buf, GuestAddress(0xffc)).unwrap(), 5); 85 assert_eq!(buf, sample_buf); 86} 87``` 88 89## License 90 91This project is licensed under either of 92 93- [Apache License](http://www.apache.org/licenses/LICENSE-2.0), Version 2.0 94- [BSD-3-Clause License](https://opensource.org/licenses/BSD-3-Clause) 95