region 0.3.0

A library for manipulating memory regions
Documentation 
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

use error::*;
use {os, page};

/// Locks one or more memory regions to RAM.
///
/// The memory pages within the address range is guaranteed to stay in RAM
/// except for specials cases such as hibernation and memory starvation.
///
/// - The range is `[address, address + size)`
/// - The address is rounded down to the closest page boundary.
/// - The size is rounded up to the closest page boundary, relative to the
///   address.
///
/// # Examples
///
/// ```
/// let data = [0; 100];
/// let _guard = region::lock(data.as_ptr(), data.len()).unwrap();
/// ```
pub fn lock(address: *const u8, size: usize) -> Result<LockGuard> {
  os::lock(
    page::floor(address as usize) as *const u8,
    page::size_from_range(address, size),
  )?;
  Ok(LockGuard::new(address, size))
}

/// Unlocks one or more memory regions from RAM.
///
/// This function is unsafe since it cannot be known whether it is called on a
/// locked region or not. In normal uses cases, the `LockGuard` is recommended
/// for safe code.
///
/// - The range is `[address, address + size)`
/// - The address is rounded down to the closest page boundary.
/// - The size is rounded up to the closest page boundary, relative to the
///   address.
pub unsafe fn unlock(address: *const u8, size: usize) -> Result<()> {
  os::unlock(
    page::floor(address as usize) as *const u8,
    page::size_from_range(address, size),
  )
}

/// An RAII implementation of a "scoped lock". When this structure is dropped
/// (falls out of scope), the virtual lock will be unlocked.
#[must_use]
pub struct LockGuard {
  address: *const u8,
  size: usize,
}

impl LockGuard {
  fn new(address: *const u8, size: usize) -> Self {
    LockGuard { address, size }
  }

  /// Releases the guards ownership of the virtual lock.
  pub unsafe fn release(self) {
    ::std::mem::forget(self);
  }
}

impl Drop for LockGuard {
  fn drop(&mut self) {
    assert!(
      unsafe { ::unlock(self.address, self.size).is_ok() },
      "unlocking region"
    );
  }
}

#[cfg(test)]
mod tests {
  use super::*;
  use Protection;
  use os::page_size;
  use tests::alloc_pages;

  #[test]
  fn lock_page() {
    let map = alloc_pages(&[Protection::ReadWrite]);
    let _guard = lock(map.as_ptr(), page_size()).unwrap();
  }

  #[test]
  fn lock_page_release() {
    let map = alloc_pages(&[Protection::ReadWrite]);

    unsafe {
      lock(map.as_ptr(), page_size()).unwrap().release();
      unlock(map.as_ptr(), page_size()).unwrap();
    }
  }

}