1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006
// Copyright (C) 2019 Alibaba Cloud Computing. All rights reserved. // // Portions Copyright 2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. // // Portions Copyright 2017 The Chromium OS Authors. All rights reserved. // Use of this source code is governed by a BSD-style license that can be // found in the LICENSE-BSD-3-Clause file. // // SPDX-License-Identifier: Apache-2.0 OR BSD-3-Clause //! Traits to track and access the physical memory of the guest. //! //! To make the abstraction as generic as possible, all the core traits declared here only define //! methods to access guest's memory, and never define methods to manage (create, delete, insert, //! remove etc) guest's memory. This way, the guest memory consumers (virtio device drivers, //! vhost drivers and boot loaders etc) may be decoupled from the guest memory provider (typically //! a hypervisor). //! //! Traits and Structs //! - [GuestAddress](struct.GuestAddress.html): represents a guest physical address (GPA). //! - [MemoryRegionAddress](struct.MemoryRegionAddress.html): represents an offset inside a region. //! - [GuestMemoryRegion](trait.GuestMemoryRegion.html): represent a continuous region of guest's //! physical memory. //! - [GuestMemory](trait.GuestMemory.html): represent a collection of GuestMemoryRegion objects. //! The main responsibilities of the GuestMemory trait are: //! - hide the detail of accessing guest's physical address. //! - map a request address to a GuestMemoryRegion object and relay the request to it. //! - handle cases where an access request spanning two or more GuestMemoryRegion objects. //! //! Whenever a collection of GuestMemoryRegion objects is mutable, //! [GuestAddressSpace](trait.GuestAddressSpace.html) should be implemented //! for clients to obtain a [GuestMemory] reference or smart pointer. use std::convert::From; use std::fmt::{self, Display}; use std::fs::File; use std::io::{self, Read, Write}; use std::ops::{BitAnd, BitOr, Deref}; use std::rc::Rc; use std::sync::Arc; use crate::address::{Address, AddressValue}; use crate::bytes::Bytes; use crate::volatile_memory; static MAX_ACCESS_CHUNK: usize = 4096; /// Errors associated with handling guest memory accesses. #[allow(missing_docs)] #[derive(Debug)] pub enum Error { /// Failure in finding a guest address in any memory regions mapped by this guest. InvalidGuestAddress(GuestAddress), /// Couldn't read/write from the given source. IOError(io::Error), /// Incomplete read or write. PartialBuffer { expected: usize, completed: usize }, /// Requested backend address is out of range. InvalidBackendAddress, /// Host virtual address not available. HostAddressNotAvailable, } impl From<volatile_memory::Error> for Error { fn from(e: volatile_memory::Error) -> Self { match e { volatile_memory::Error::OutOfBounds { .. } => Error::InvalidBackendAddress, volatile_memory::Error::Overflow { .. } => Error::InvalidBackendAddress, volatile_memory::Error::TooBig { .. } => Error::InvalidBackendAddress, volatile_memory::Error::Misaligned { .. } => Error::InvalidBackendAddress, volatile_memory::Error::IOError(e) => Error::IOError(e), volatile_memory::Error::PartialBuffer { expected, completed, } => Error::PartialBuffer { expected, completed, }, } } } /// Result of guest memory operations. pub type Result<T> = std::result::Result<T, Error>; impl std::error::Error for Error {} impl Display for Error { fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { write!(f, "Guest memory error: ")?; match self { Error::InvalidGuestAddress(addr) => { write!(f, "invalid guest address {}", addr.raw_value()) } Error::IOError(error) => write!(f, "{}", error), Error::PartialBuffer { expected, completed, } => write!( f, "only used {} bytes in {} long buffer", completed, expected, ), Error::InvalidBackendAddress => write!(f, "invalid backend address"), Error::HostAddressNotAvailable => write!(f, "host virtual address not available"), } } } /// Represents a guest physical address (GPA). /// /// # Notes: /// On ARM64, a 32-bit hypervisor may be used to support a 64-bit guest. For simplicity, /// `u64` is used to store the the raw value no matter if the guest a 32-bit or 64-bit virtual /// machine. #[derive(Clone, Copy, Debug, Eq, PartialEq, Ord, PartialOrd)] pub struct GuestAddress(pub u64); impl_address_ops!(GuestAddress, u64); /// Represents an offset inside a region. #[derive(Clone, Copy, Debug, Eq, PartialEq, Ord, PartialOrd)] pub struct MemoryRegionAddress(pub u64); impl_address_ops!(MemoryRegionAddress, u64); /// Type of the raw value stored in a GuestAddress object. pub type GuestUsize = <GuestAddress as AddressValue>::V; /// Represents the start point within a `File` that backs a `GuestMemoryRegion`. #[derive(Clone, Debug)] pub struct FileOffset { file: Arc<File>, start: u64, } impl FileOffset { /// Creates a new `FileOffset` object. pub fn new(file: File, start: u64) -> Self { FileOffset::from_arc(Arc::new(file), start) } /// Creates a new `FileOffset` object based on an exiting `Arc<File>`. pub fn from_arc(file: Arc<File>, start: u64) -> Self { FileOffset { file, start } } /// Returns a reference to the inner `File` object. pub fn file(&self) -> &File { &self.file.as_ref() } /// Return a reference to the inner `Arc<File>` object. pub fn arc(&self) -> &Arc<File> { &self.file } /// Returns the start offset within the file. pub fn start(&self) -> u64 { self.start } } /// Represents a continuous region of guest physical memory. #[allow(clippy::len_without_is_empty)] pub trait GuestMemoryRegion: Bytes<MemoryRegionAddress, E = Error> { /// Returns the size of the region. fn len(&self) -> GuestUsize; /// Returns the minimum (inclusive) address managed by the region. fn start_addr(&self) -> GuestAddress; /// Returns the maximum (inclusive) address managed by the region. fn last_addr(&self) -> GuestAddress { // unchecked_add is safe as the region bounds were checked when it was created. self.start_addr().unchecked_add(self.len() - 1) } /// Returns the given address if it is within this region. fn check_address(&self, addr: MemoryRegionAddress) -> Option<MemoryRegionAddress> { if self.address_in_range(addr) { Some(addr) } else { None } } /// Returns `true` if the given address is within this region. fn address_in_range(&self, addr: MemoryRegionAddress) -> bool { addr.raw_value() < self.len() } /// Returns the address plus the offset if it is in this region. fn checked_offset( &self, base: MemoryRegionAddress, offset: usize, ) -> Option<MemoryRegionAddress> { base.checked_add(offset as u64) .and_then(|addr| self.check_address(addr)) } /// Tries to convert an absolute address to a relative address within this region. /// /// Returns `None` if `addr` is out of the bounds of this region. fn to_region_addr(&self, addr: GuestAddress) -> Option<MemoryRegionAddress> { addr.checked_offset_from(self.start_addr()) .and_then(|offset| self.check_address(MemoryRegionAddress(offset))) } /// Returns the host virtual address corresponding to the region address. /// /// Some [`GuestMemory`](trait.GuestMemory.html) implementations, like `GuestMemoryMmap`, /// have the capability to mmap guest address range into host virtual address space for /// direct access, so the corresponding host virtual address may be passed to other subsystems. /// /// # Note /// The underlying guest memory is not protected from memory aliasing, which breaks the /// Rust memory safety model. It's the caller's responsibility to ensure that there's no /// concurrent accesses to the underlying guest memory. fn get_host_address(&self, _addr: MemoryRegionAddress) -> Result<*mut u8> { Err(Error::HostAddressNotAvailable) } /// Returns information regarding the file and offset backing this memory region. fn file_offset(&self) -> Option<&FileOffset> { None } /// Returns a slice corresponding to the data in the region. /// /// Returns `None` if the region does not support slice-based access. /// /// # Safety /// /// Unsafe because of possible aliasing. unsafe fn as_slice(&self) -> Option<&[u8]> { None } /// Returns a mutable slice corresponding to the data in the region. /// /// Returns `None` if the region does not support slice-based access. /// /// # Safety /// /// Unsafe because of possible aliasing. unsafe fn as_mut_slice(&self) -> Option<&mut [u8]> { None } } /// GuestAddressSpace provides a way to retrieve a GuestMemory object. /// The vm-memory crate already provides trivial implementation for /// references to GuestMemory or reference-counted GuestMemory objects, /// but the trait can also be implemented by any other struct in order /// to provide temporary access to a snapshot of the memory map. /// /// In order to support generic mutable memory maps, devices (or other things /// that access memory) should store the memory as a GuestAddressSpace<M>. /// This example shows that references can also be used as the GuestAddressSpace /// implementation, providing a zero-cost abstraction whenever immutable memory /// maps are sufficient. /// /// ``` /// # use std::sync::Arc; /// # #[cfg(feature = "backend-mmap")] /// # use vm_memory::GuestMemoryMmap; /// # #[cfg(feature = "backend-atomic")] /// # use vm_memory::GuestMemoryAtomic; /// # use vm_memory::{GuestAddress, GuestMemory, GuestAddressSpace}; /// /// pub struct VirtioDevice<AS: GuestAddressSpace> { /// mem: Option<AS>, /// } /// /// impl<AS: GuestAddressSpace> VirtioDevice<AS> { /// fn new() -> Self { /// VirtioDevice { mem: None } /// } /// fn activate(&mut self, mem: AS) { /// self.mem = Some(mem) /// } /// } /// /// # #[cfg(feature = "backend-mmap")] /// # fn get_mmap() -> GuestMemoryMmap { /// # GuestMemoryMmap::from_ranges(&[(GuestAddress(0),0)]).unwrap() /// # } /// /// # #[cfg(feature = "backend-mmap")] /// # fn test_1() { /// // Using `VirtioDevice` with an immutable GuestMemoryMmap: /// let mut for_immutable_mmap: VirtioDevice<&GuestMemoryMmap> = /// VirtioDevice::new(); /// let mmap = get_mmap(); /// for_immutable_mmap.activate(&mmap); /// let mut another: VirtioDevice<&GuestMemoryMmap> = /// VirtioDevice::new(); /// another.activate(&mmap); /// # } /// /// # #[cfg(all(feature = "backend-mmap", feature = "backend-atomic"))] /// # fn test_2() { /// // Using `VirtioDevice` with a mutable GuestMemoryMmap: /// let mut for_mutable_mmap: VirtioDevice<GuestMemoryAtomic<GuestMemoryMmap>> = /// VirtioDevice::new(); /// let atomic = GuestMemoryAtomic::new(get_mmap()); /// for_mutable_mmap.activate(atomic.clone()); /// let mut another: VirtioDevice<GuestMemoryAtomic<GuestMemoryMmap>> = /// VirtioDevice::new(); /// another.activate(atomic.clone()); /// // atomic can be modified here... /// # } /// ``` pub trait GuestAddressSpace { /// The type that will be used to access guest memory. type M: GuestMemory; /// A type that provides access to the memory. type T: Deref<Target = Self::M>; /// Return an object (e.g. a reference or guard) that can be used /// to access memory through this address space. The object provides /// a consistent snapshot of the memory map. fn memory(&self) -> Self::T; } impl<M: GuestMemory> GuestAddressSpace for &M { type T = Self; type M = M; fn memory(&self) -> Self { self } } impl<M: GuestMemory> GuestAddressSpace for Rc<M> { type T = Self; type M = M; fn memory(&self) -> Self { self.clone() } } impl<M: GuestMemory> GuestAddressSpace for Arc<M> { type T = Self; type M = M; fn memory(&self) -> Self { self.clone() } } /// GuestMemory represents a container for an *immutable* collection of /// GuestMemoryRegion objects. GuestMemory provides the `Bytes<GuestAddress>` /// trait to hide the details of accessing guest memory by physical address. /// Interior mutability is not allowed for implementations of GuestMemory so /// that they always provide a consistent view of the memory map. /// /// The task of the GuestMemory trait are: /// - map a request address to a GuestMemoryRegion object and relay the request to it. /// - handle cases where an access request spanning two or more GuestMemoryRegion objects. pub trait GuestMemory { /// Type of objects hosted by the address space. type R: GuestMemoryRegion; /// Returns the number of regions in the collection. fn num_regions(&self) -> usize; /// Returns the region containing the specified address or `None`. fn find_region(&self, addr: GuestAddress) -> Option<&Self::R>; /// Perform the specified action on each region. /// /// It only walks children of current region and does not step into sub regions. fn with_regions<F, E>(&self, cb: F) -> std::result::Result<(), E> where F: Fn(usize, &Self::R) -> std::result::Result<(), E>; /// Perform the specified action on each region mutably. /// /// It only walks children of current region and does not step into sub regions. fn with_regions_mut<F, E>(&self, cb: F) -> std::result::Result<(), E> where F: FnMut(usize, &Self::R) -> std::result::Result<(), E>; /// Applies two functions, specified as callbacks, on the inner memory regions. /// /// # Arguments /// * `init` - Starting value of the accumulator for the `foldf` function. /// * `mapf` - "Map" function, applied to all the inner memory regions. It returns an array of /// the same size as the memory regions array, containing the function's results /// for each region. /// * `foldf` - "Fold" function, applied to the array returned by `mapf`. It acts as an /// operator, applying itself to the `init` value and to each subsequent elemnent /// in the array returned by `mapf`. /// /// # Examples /// /// * Compute the total size of all memory mappings in KB by iterating over the memory regions /// and dividing their sizes to 1024, then summing up the values in an accumulator. /// /// ``` /// # #[cfg(feature = "backend-mmap")] /// # use vm_memory::{GuestAddress, GuestMemory, GuestMemoryRegion, GuestMemoryMmap}; /// /// # #[cfg(feature = "backend-mmap")] /// # fn test_map_fold() -> Result<(), ()> { /// let start_addr1 = GuestAddress(0x0); /// let start_addr2 = GuestAddress(0x400); /// let mem = GuestMemoryMmap::from_ranges(&vec![(start_addr1, 1024), (start_addr2, 2048)]) /// .unwrap(); /// let total_size = mem.map_and_fold( /// 0, /// |(_, region)| region.len() / 1024, /// |acc, size| acc + size /// ); /// println!("Total memory size = {} KB", total_size); /// Ok(()) /// # } /// /// # #[cfg(feature = "backend-mmap")] /// # test_map_fold(); /// ``` fn map_and_fold<F, G, T>(&self, init: T, mapf: F, foldf: G) -> T where F: Fn((usize, &Self::R)) -> T, G: Fn(T, T) -> T; /// Returns the maximum (inclusive) address managed by the /// [`GuestMemory`](trait.GuestMemory.html). /// /// # Examples /// /// ``` /// # #[cfg(feature = "backend-mmap")] /// # use vm_memory::{Address, GuestAddress, GuestMemory, GuestMemoryMmap}; /// /// # #[cfg(feature = "backend-mmap")] /// # fn test_last_addr() -> Result<(), ()> { /// let start_addr = GuestAddress(0x1000); /// let mut gm = GuestMemoryMmap::from_ranges(&vec![(start_addr, 0x400)]).map_err(|_| ())?; /// assert_eq!(start_addr.checked_add(0x3ff), Some(gm.last_addr())); /// Ok(()) /// # } /// /// # #[cfg(feature = "backend-mmap")] /// # test_last_addr(); /// ``` fn last_addr(&self) -> GuestAddress { self.map_and_fold( GuestAddress(0), |(_, region)| region.last_addr(), std::cmp::max, ) } /// Tries to convert an absolute address to a relative address within the corresponding region. /// /// Returns `None` if `addr` isn't present within the memory of the guest. fn to_region_addr(&self, addr: GuestAddress) -> Option<(&Self::R, MemoryRegionAddress)> { self.find_region(addr) .map(|r| (r, r.to_region_addr(addr).unwrap())) } /// Returns `true` if the given address is present within the memory of the guest. fn address_in_range(&self, addr: GuestAddress) -> bool { self.find_region(addr).is_some() } /// Returns the given address if it is present within the memory of the guest. fn check_address(&self, addr: GuestAddress) -> Option<GuestAddress> { self.find_region(addr).map(|_| addr) } /// Returns the address plus the offset if it is present within the memory of the guest. fn checked_offset(&self, base: GuestAddress, offset: usize) -> Option<GuestAddress> { base.checked_add(offset as u64) .and_then(|addr| self.check_address(addr)) } /// Invokes callback `f` to handle data in the address range `[addr, addr + count)`. /// /// /// The address range `[addr, addr + count)` may span more than one /// [`GuestMemoryRegion`](trait.GuestMemoryRegion.html) objects, or even have holes in it. /// So [`try_access()`](trait.GuestMemory.html#method.try_access) invokes the callback 'f' /// for each [`GuestMemoryRegion`](trait.GuestMemoryRegion.html) object involved and returns: /// - the error code returned by the callback 'f' /// - the size of the already handled data when encountering the first hole /// - the size of the already handled data when the whole range has been handled fn try_access<F>(&self, count: usize, addr: GuestAddress, mut f: F) -> Result<usize> where F: FnMut(usize, usize, MemoryRegionAddress, &Self::R) -> Result<usize>, { let mut cur = addr; let mut total = 0; while let Some(region) = self.find_region(cur) { let start = region.to_region_addr(cur).unwrap(); let cap = region.len() - start.raw_value(); let len = std::cmp::min(cap, (count - total) as GuestUsize); match f(total, len as usize, start, region) { // no more data Ok(0) => return Ok(total), // made some progress Ok(len) => { total += len; if total == count { break; } cur = match cur.overflowing_add(len as GuestUsize) { (GuestAddress(0), _) => GuestAddress(0), (result, false) => result, (_, true) => panic!("guest address overflow"), } } // error happened e => return e, } } if total == 0 { Err(Error::InvalidGuestAddress(addr)) } else { Ok(total) } } /// Get the host virtual address corresponding to the guest address. /// /// Some [`GuestMemory`](trait.GuestMemory.html) implementations, like `GuestMemoryMmap`, /// have the capability to mmap the guest address range into virtual address space of the host /// for direct access, so the corresponding host virtual address may be passed to other /// subsystems. /// /// # Note /// The underlying guest memory is not protected from memory aliasing, which breaks the /// Rust memory safety model. It's the caller's responsibility to ensure that there's no /// concurrent accesses to the underlying guest memory. /// /// # Arguments /// * `guest_addr` - Guest address to convert. /// /// # Examples /// /// ``` /// # #[cfg(feature = "backend-mmap")] /// # use vm_memory::{GuestAddress, GuestMemory, GuestMemoryMmap}; /// /// # #[cfg(feature = "backend-mmap")] /// # fn test_get_host_address() -> Result<(), ()> { /// let start_addr = GuestAddress(0x1000); /// let mut gm = GuestMemoryMmap::from_ranges(&vec![(start_addr, 0x500)]).map_err(|_| ())?; /// let addr = gm.get_host_address(GuestAddress(0x1200)).unwrap(); /// println!("Host address is {:p}", addr); /// Ok(()) /// # } /// /// # #[cfg(feature = "backend-mmap")] /// test_get_host_address(); /// ``` fn get_host_address(&self, addr: GuestAddress) -> Result<*mut u8> { self.to_region_addr(addr) .ok_or_else(|| Error::InvalidGuestAddress(addr)) .and_then(|(r, addr)| r.get_host_address(addr)) } } impl<T: GuestMemory> Bytes<GuestAddress> for T { type E = Error; fn write(&self, buf: &[u8], addr: GuestAddress) -> Result<usize> { self.try_access( buf.len(), addr, |offset, _count, caddr, region| -> Result<usize> { region.write(&buf[offset as usize..], caddr) }, ) } fn read(&self, buf: &mut [u8], addr: GuestAddress) -> Result<usize> { self.try_access( buf.len(), addr, |offset, _count, caddr, region| -> Result<usize> { region.read(&mut buf[offset as usize..], caddr) }, ) } /// # Examples /// * Write a slice at guestaddress 0x200. /// /// ``` /// # #[cfg(feature = "backend-mmap")] /// # use vm_memory::{Bytes, GuestAddress, mmap::GuestMemoryMmap}; /// /// # #[cfg(feature = "backend-mmap")] /// # fn test_write_u64() { /// let start_addr = GuestAddress(0x1000); /// let mut gm = /// GuestMemoryMmap::from_ranges(&vec![(start_addr, 0x400)]) /// .expect("Could not create guest memory"); /// let res = gm.write_slice(&[1, 2, 3, 4, 5], start_addr); /// assert!(res.is_ok()); /// # } /// /// # #[cfg(feature = "backend-mmap")] /// # test_write_u64(); /// ``` fn write_slice(&self, buf: &[u8], addr: GuestAddress) -> Result<()> { let res = self.write(buf, addr)?; if res != buf.len() { return Err(Error::PartialBuffer { expected: buf.len(), completed: res, }); } Ok(()) } /// # Examples /// * Read a slice of length 16 at guestaddress 0x200. /// /// ``` /// # #[cfg(feature = "backend-mmap")] /// # use vm_memory::{Bytes, GuestAddress, mmap::GuestMemoryMmap}; /// /// # #[cfg(feature = "backend-mmap")] /// # fn test_write_u64() { /// let start_addr = GuestAddress(0x1000); /// let mut gm = /// GuestMemoryMmap::from_ranges(&vec![(start_addr, 0x400)]) /// .expect("Could not create guest memory"); /// let buf = &mut [0u8; 16]; /// let res = gm.read_slice(buf, start_addr); /// assert!(res.is_ok()); /// # } /// /// # #[cfg(feature = "backend-mmap")] /// # test_write_u64() /// ``` fn read_slice(&self, buf: &mut [u8], addr: GuestAddress) -> Result<()> { let res = self.read(buf, addr)?; if res != buf.len() { return Err(Error::PartialBuffer { expected: buf.len(), completed: res, }); } Ok(()) } /// # Examples /// /// * Read bytes from /dev/urandom /// /// ``` /// # #[cfg(feature = "backend-mmap")] /// # use vm_memory::{Address, Bytes, GuestAddress, mmap::GuestMemoryMmap}; /// # use std::fs::File; /// # use std::path::Path; /// /// # #[cfg(all(unix, feature = "backend-mmap"))] /// # fn test_read_random() { /// let start_addr = GuestAddress(0x1000); /// let gm = /// GuestMemoryMmap::from_ranges(&vec![(start_addr, 0x400)]) /// .expect("Could not create guest memory"); /// let mut file = File::open(Path::new("/dev/urandom")) /// .expect("could not open /dev/urandom"); /// let addr = GuestAddress(0x1010); /// gm.read_from(addr, &mut file, 128) /// .expect("Could not read from /dev/urandom into guest memory"); /// let read_addr = addr.checked_add(8).expect("Could not compute read address"); /// let rand_val: u32 = gm /// .read_obj(read_addr) /// .expect("Could not read u32 val from /dev/urandom"); /// # } /// /// # #[cfg(all(unix, feature = "backend-mmap"))] /// # test_read_random(); /// ``` fn read_from<F>(&self, addr: GuestAddress, src: &mut F, count: usize) -> Result<usize> where F: Read, { self.try_access(count, addr, |offset, len, caddr, region| -> Result<usize> { // Check if something bad happened before doing unsafe things. assert!(offset <= count); if let Some(dst) = unsafe { region.as_mut_slice() } { // This is safe cause `start` and `len` are within the `region`. let start = caddr.raw_value() as usize; let end = start + len; let bytes_read = src.read(&mut dst[start..end]).map_err(Error::IOError)?; Ok(bytes_read) } else { let len = std::cmp::min(len, MAX_ACCESS_CHUNK); let mut buf = vec![0u8; len].into_boxed_slice(); let bytes_read = src.read(&mut buf[..]).map_err(Error::IOError)?; let bytes_written = region.write(&buf[0..bytes_read], caddr)?; assert_eq!(bytes_written, bytes_read); Ok(bytes_read) } }) } fn read_exact_from<F>(&self, addr: GuestAddress, src: &mut F, count: usize) -> Result<()> where F: Read, { let res = self.read_from(addr, src, count)?; if res != count { return Err(Error::PartialBuffer { expected: count, completed: res, }); } Ok(()) } /// # Examples /// /// * Write 128 bytes to /dev/null /// /// ``` /// # #[cfg(feature = "backend-mmap")] /// # use vm_memory::{Bytes, GuestAddress, mmap::GuestMemoryMmap}; /// # use std::fs::OpenOptions; /// # use std::path::Path; /// /// # #[cfg(all(unix, feature = "backend-mmap"))] /// # fn test_write_null() { /// let start_addr = GuestAddress(0x1000); /// let gm = /// GuestMemoryMmap::from_ranges(&vec![(start_addr, 1024)]) /// .expect("Could not create guest memory"); /// let mut file = OpenOptions::new() /// .write(true) /// .open("/dev/null") /// .expect("Could not open /dev/null"); /// /// gm.write_to(start_addr, &mut file, 128) /// .expect("Could not write 128 bytes to the provided address"); /// # } /// /// # #[cfg(all(unix, feature = "backend-mmap"))] /// # test_write_null(); /// ``` fn write_to<F>(&self, addr: GuestAddress, dst: &mut F, count: usize) -> Result<usize> where F: Write, { self.try_access(count, addr, |offset, len, caddr, region| -> Result<usize> { // Check if something bad happened before doing unsafe things. assert!(offset <= count); if let Some(src) = unsafe { region.as_slice() } { // This is safe cause `start` and `len` are within the `region`. let start = caddr.raw_value() as usize; let end = start + len; // It is safe to read from volatile memory. Accessing the guest // memory as a slice should be OK as long as nothing assumes another // thread won't change what is loaded; however, we may want to introduce // VolatileRead and VolatileWrite traits in the future. let bytes_written = dst.write(&src[start..end]).map_err(Error::IOError)?; Ok(bytes_written) } else { let len = std::cmp::min(len, MAX_ACCESS_CHUNK); let mut buf = vec![0u8; len].into_boxed_slice(); let bytes_read = region.read(&mut buf, caddr)?; assert_eq!(bytes_read, len); // For a non-RAM region, reading could have side effects, so we // must use write_all(). dst.write_all(&buf).map_err(Error::IOError)?; Ok(len) } }) } fn write_all_to<F>(&self, addr: GuestAddress, dst: &mut F, count: usize) -> Result<()> where F: Write, { let res = self.write_to(addr, dst, count)?; if res != count { return Err(Error::PartialBuffer { expected: count, completed: res, }); } Ok(()) } } #[cfg(test)] mod tests { use super::*; #[cfg(feature = "backend-mmap")] use crate::bytes::ByteValued; #[cfg(feature = "backend-mmap")] use crate::{GuestAddress, GuestMemoryMmap}; #[cfg(feature = "backend-mmap")] use std::io::Cursor; #[cfg(feature = "backend-mmap")] use std::time::{Duration, Instant}; use vmm_sys_util::tempfile::TempFile; #[cfg(feature = "backend-mmap")] fn make_image(size: u8) -> Vec<u8> { let mut image: Vec<u8> = Vec::with_capacity(size as usize); for i in 0..size { image.push(i); } image } #[test] fn test_file_offset() { let file = TempFile::new().unwrap().into_file(); let start = 1234; let file_offset = FileOffset::new(file, start); assert_eq!(file_offset.start(), start); assert_eq!( file_offset.file() as *const File, file_offset.arc().as_ref() as *const File ); } #[cfg(feature = "backend-mmap")] #[test] fn checked_read_from() { let start_addr1 = GuestAddress(0x0); let start_addr2 = GuestAddress(0x40); let mem = GuestMemoryMmap::from_ranges(&[(start_addr1, 64), (start_addr2, 64)]).unwrap(); let image = make_image(0x80); let offset = GuestAddress(0x30); let count: usize = 0x20; assert_eq!( 0x20 as usize, mem.read_from(offset, &mut Cursor::new(&image), count) .unwrap() ); } // Runs the provided closure in a loop, until at least `duration` time units have elapsed. #[cfg(feature = "backend-mmap")] fn loop_timed<F>(duration: Duration, mut f: F) where F: FnMut() -> (), { // We check the time every `CHECK_PERIOD` iterations. const CHECK_PERIOD: u64 = 1_000_000; let start_time = Instant::now(); loop { for _ in 0..CHECK_PERIOD { f(); } if start_time.elapsed() >= duration { break; } } } // Helper method for the following test. It spawns a writer and a reader thread, which // simultaneously try to access an object that is placed at the junction of two memory regions. // The part of the object that's continuously accessed is a member of type T. The writer // flips all the bits of the member with every write, while the reader checks that every byte // has the same value (and thus it did not do a non-atomic access). The test succeeds if // no mismatch is detected after performing accesses for a pre-determined amount of time. #[cfg(feature = "backend-mmap")] fn non_atomic_access_helper<T>() where T: ByteValued + std::fmt::Debug + From<u8> + Into<u128> + std::ops::Not<Output = T> + PartialEq, { use std::mem; use std::thread; // A dummy type that's always going to have the same alignment as the first member, // and then adds some bytes at the end. #[derive(Clone, Copy, Debug, Default, PartialEq)] struct Data<T> { val: T, some_bytes: [u8; 7], } // Some sanity checks. assert_eq!(mem::align_of::<T>(), mem::align_of::<Data<T>>()); assert_eq!(mem::size_of::<T>(), mem::align_of::<T>()); unsafe impl<T: ByteValued> ByteValued for Data<T> {} // Start of first guest memory region. let start = GuestAddress(0); let region_len = 1 << 12; // The address where we start writing/reading a Data<T> value. let data_start = GuestAddress((region_len - mem::size_of::<T>()) as u64); let mem = GuestMemoryMmap::from_ranges(&[ (start, region_len), (start.unchecked_add(region_len as u64), region_len), ]) .unwrap(); // Need to clone this and move it into the new thread we create. let mem2 = mem.clone(); // Just some bytes. let some_bytes = [1u8, 2, 4, 16, 32, 64, 128]; let mut data = Data { val: T::from(0u8), some_bytes, }; // Simple check that cross-region write/read is ok. mem.write_obj(data, data_start).unwrap(); let read_data = mem.read_obj::<Data<T>>(data_start).unwrap(); assert_eq!(read_data, data); let t = thread::spawn(move || { let mut count: u64 = 0; loop_timed(Duration::from_secs(3), || { let data = mem2.read_obj::<Data<T>>(data_start).unwrap(); // Every time data is written to memory by the other thread, the value of // data.val alternates between 0 and T::MAX, so the inner bytes should always // have the same value. If they don't match, it means we read a partial value, // so the access was not atomic. let bytes = data.val.into().to_le_bytes(); for i in 1..mem::size_of::<T>() { if bytes[0] != bytes[i] { panic!( "val bytes don't match {:?} after {} iterations", &bytes[..mem::size_of::<T>()], count ); } } count += 1; }); }); // Write the object while flipping the bits of data.val over and over again. loop_timed(Duration::from_secs(3), || { mem.write_obj(data, data_start).unwrap(); data.val = !data.val; }); t.join().unwrap() } #[cfg(feature = "backend-mmap")] #[test] fn test_non_atomic_access() { non_atomic_access_helper::<u16>() } #[cfg(feature = "backend-mmap")] #[test] fn test_zero_length_accesses() { #[derive(Default, Clone, Copy)] #[repr(C)] struct ZeroSizedStruct { dummy: [u32; 0], } unsafe impl ByteValued for ZeroSizedStruct {} let addr = GuestAddress(0x1000); let mem = GuestMemoryMmap::from_ranges(&[(addr, 0x1000)]).unwrap(); let obj = ZeroSizedStruct::default(); let mut image = make_image(0x80); assert_eq!(mem.write(&[], addr).unwrap(), 0); assert_eq!(mem.read(&mut [], addr).unwrap(), 0); assert!(mem.write_slice(&[], addr).is_ok()); assert!(mem.read_slice(&mut [], addr).is_ok()); assert!(mem.write_obj(obj, addr).is_ok()); assert!(mem.read_obj::<ZeroSizedStruct>(addr).is_ok()); assert_eq!(mem.read_from(addr, &mut Cursor::new(&image), 0).unwrap(), 0); assert!(mem .read_exact_from(addr, &mut Cursor::new(&image), 0) .is_ok()); assert_eq!( mem.write_to(addr, &mut Cursor::new(&mut image), 0).unwrap(), 0 ); assert!(mem .write_all_to(addr, &mut Cursor::new(&mut image), 0) .is_ok()); } }