summaryrefslogtreecommitdiffhomepage
path: root/pkg/sentry/mm/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'pkg/sentry/mm/README.md')
-rw-r--r--pkg/sentry/mm/README.md161
1 files changed, 81 insertions, 80 deletions
diff --git a/pkg/sentry/mm/README.md b/pkg/sentry/mm/README.md
index 067733475..e485a5ca5 100644
--- a/pkg/sentry/mm/README.md
+++ b/pkg/sentry/mm/README.md
@@ -38,50 +38,50 @@ forces the kernel to create such a mapping to service the read.
For a file, doing so consists of several logical phases:
-1. The kernel allocates physical memory to store the contents of the required
- part of the file, and copies file contents to the allocated memory. Supposing
- that the kernel chooses the physical memory at physical address (PA)
- 0x2fb000, the resulting state of the system is:
+1. The kernel allocates physical memory to store the contents of the required
+ part of the file, and copies file contents to the allocated memory.
+ Supposing that the kernel chooses the physical memory at physical address
+ (PA) 0x2fb000, the resulting state of the system is:
VMA: VA:0x400000 -> /tmp/foo:0x0
Filemap: /tmp/foo:0x0 -> PA:0x2fb000
- (In Linux the state of the mapping from file offset to physical memory is
- stored in `struct address_space`, but to avoid confusion with other notions
- of address space we will refer to this system as filemap, named after Linux
- kernel source file `mm/filemap.c`.)
+ (In Linux the state of the mapping from file offset to physical memory is
+ stored in `struct address_space`, but to avoid confusion with other notions
+ of address space we will refer to this system as filemap, named after Linux
+ kernel source file `mm/filemap.c`.)
-2. The kernel stores the effective mapping from virtual to physical address in a
- *page table entry* (PTE) in the application's *page tables*, which are used
- by the CPU's virtual memory hardware to perform address translation. The
- resulting state of the system is:
+2. The kernel stores the effective mapping from virtual to physical address in
+ a *page table entry* (PTE) in the application's *page tables*, which are
+ used by the CPU's virtual memory hardware to perform address translation.
+ The resulting state of the system is:
VMA: VA:0x400000 -> /tmp/foo:0x0
Filemap: /tmp/foo:0x0 -> PA:0x2fb000
PTE: VA:0x400000 -----------------> PA:0x2fb000
- The PTE is required for the application to actually use the contents of the
- mapped file as virtual memory. However, the PTE is derived from the VMA and
- filemap state, both of which are independently mutable, such that mutations
- to either will affect the PTE. For example:
-
- - The application may remove the VMA using the `munmap` system call. This
- breaks the mapping from VA:0x400000 to /tmp/foo:0x0, and consequently the
- mapping from VA:0x400000 to PA:0x2fb000. However, it does not necessarily
- break the mapping from /tmp/foo:0x0 to PA:0x2fb000, so a future mapping of
- the same file offset may reuse this physical memory.
-
- - The application may invalidate the file's contents by passing a length of 0
- to the `ftruncate` system call. This breaks the mapping from /tmp/foo:0x0
- to PA:0x2fb000, and consequently the mapping from VA:0x400000 to
- PA:0x2fb000. However, it does not break the mapping from VA:0x400000 to
- /tmp/foo:0x0, so future changes to the file's contents may again be made
- visible at VA:0x400000 after another page fault results in the allocation
- of a new physical address.
-
- Note that, in order to correctly break the mapping from VA:0x400000 to
- PA:0x2fb000 in the latter case, filemap must also store a *reverse mapping*
- from /tmp/foo:0x0 to VA:0x400000 so that it can locate and remove the PTE.
+ The PTE is required for the application to actually use the contents of the
+ mapped file as virtual memory. However, the PTE is derived from the VMA and
+ filemap state, both of which are independently mutable, such that mutations
+ to either will affect the PTE. For example:
+
+ - The application may remove the VMA using the `munmap` system call. This
+ breaks the mapping from VA:0x400000 to /tmp/foo:0x0, and consequently
+ the mapping from VA:0x400000 to PA:0x2fb000. However, it does not
+ necessarily break the mapping from /tmp/foo:0x0 to PA:0x2fb000, so a
+ future mapping of the same file offset may reuse this physical memory.
+
+ - The application may invalidate the file's contents by passing a length
+ of 0 to the `ftruncate` system call. This breaks the mapping from
+ /tmp/foo:0x0 to PA:0x2fb000, and consequently the mapping from
+ VA:0x400000 to PA:0x2fb000. However, it does not break the mapping from
+ VA:0x400000 to /tmp/foo:0x0, so future changes to the file's contents
+ may again be made visible at VA:0x400000 after another page fault
+ results in the allocation of a new physical address.
+
+ Note that, in order to correctly break the mapping from VA:0x400000 to
+ PA:0x2fb000 in the latter case, filemap must also store a *reverse mapping*
+ from /tmp/foo:0x0 to VA:0x400000 so that it can locate and remove the PTE.
[^mmap-anon]: Memory mappings to non-files are discussed in later sections.
@@ -146,30 +146,30 @@ When the application first incurs a page fault on this address, the host kernel
delivers information about the page fault to the sentry in a platform-dependent
manner, and the sentry handles the fault:
-1. The sentry allocates memory to store the contents of the required part of the
- file, and copies file contents to the allocated memory. However, since the
- sentry is implemented atop a host kernel, it does not configure mappings to
- physical memory directly. Instead, mappable "memory" in the sentry is
- represented by a host file descriptor and offset, since (as noted in
- "Background") this is the memory mapping primitive provided by the host
- kernel. In general, memory is allocated from a temporary host file using the
- `filemem` package. Supposing that the sentry allocates offset 0x3000 from
- host file "memory-file", the resulting state is:
+1. The sentry allocates memory to store the contents of the required part of
+ the file, and copies file contents to the allocated memory. However, since
+ the sentry is implemented atop a host kernel, it does not configure mappings
+ to physical memory directly. Instead, mappable "memory" in the sentry is
+ represented by a host file descriptor and offset, since (as noted in
+ "Background") this is the memory mapping primitive provided by the host
+ kernel. In general, memory is allocated from a temporary host file using the
+ `filemem` package. Supposing that the sentry allocates offset 0x3000 from
+ host file "memory-file", the resulting state is:
Sentry VMA: VA:0x400000 -> /tmp/foo:0x0
Sentry filemap: /tmp/foo:0x0 -> host:memory-file:0x3000
-2. The sentry stores the effective mapping from virtual address to host file in
- a host VMA by invoking the `mmap` system call:
+2. The sentry stores the effective mapping from virtual address to host file in
+ a host VMA by invoking the `mmap` system call:
Sentry VMA: VA:0x400000 -> /tmp/foo:0x0
Sentry filemap: /tmp/foo:0x0 -> host:memory-file:0x3000
Host VMA: VA:0x400000 -----------------> host:memory-file:0x3000
-3. The sentry returns control to the application, which immediately incurs the
- page fault again.[^mmap-populate] However, since a host VMA now exists for
- the faulting virtual address, the host kernel now handles the page fault as
- described in "Background":
+3. The sentry returns control to the application, which immediately incurs the
+ page fault again.[^mmap-populate] However, since a host VMA now exists for
+ the faulting virtual address, the host kernel now handles the page fault as
+ described in "Background":
Sentry VMA: VA:0x400000 -> /tmp/foo:0x0
Sentry filemap: /tmp/foo:0x0 -> host:memory-file:0x3000
@@ -183,12 +183,12 @@ independently mutable, and the desired state of host VMAs is derived from that
state.
[^mmap-populate]: The sentry could force the host kernel to establish PTEs when
- it creates the host VMA by passing the `MAP_POPULATE` flag to
- the `mmap` system call, but usually does not. This is because,
- to reduce the number of page faults that require handling by
- the sentry and (correspondingly) the number of host `mmap`
- system calls, the sentry usually creates host VMAs that are
- much larger than the single faulting page.
+ it creates the host VMA by passing the `MAP_POPULATE` flag to
+ the `mmap` system call, but usually does not. This is because,
+ to reduce the number of page faults that require handling by
+ the sentry and (correspondingly) the number of host `mmap`
+ system calls, the sentry usually creates host VMAs that are
+ much larger than the single faulting page.
## Private Mappings
@@ -233,45 +233,46 @@ there is no shared zero page.
In Linux:
-- A virtual address space is represented by `struct mm_struct`.
+- A virtual address space is represented by `struct mm_struct`.
-- VMAs are represented by `struct vm_area_struct`, stored in `struct
- mm_struct::mmap`.
+- VMAs are represented by `struct vm_area_struct`, stored in `struct
+ mm_struct::mmap`.
-- Mappings from file offsets to physical memory are stored in `struct
- address_space`.
+- Mappings from file offsets to physical memory are stored in `struct
+ address_space`.
-- Reverse mappings from file offsets to virtual mappings are stored in `struct
- address_space::i_mmap`.
+- Reverse mappings from file offsets to virtual mappings are stored in `struct
+ address_space::i_mmap`.
-- Physical memory pages are represented by a pointer to `struct page` or an
- index called a *page frame number* (PFN), represented by `pfn_t`.
+- Physical memory pages are represented by a pointer to `struct page` or an
+ index called a *page frame number* (PFN), represented by `pfn_t`.
-- PTEs are represented by architecture-dependent type `pte_t`, stored in a table
- hierarchy rooted at `struct mm_struct::pgd`.
+- PTEs are represented by architecture-dependent type `pte_t`, stored in a
+ table hierarchy rooted at `struct mm_struct::pgd`.
In the sentry:
-- A virtual address space is represented by type [`mm.MemoryManager`][mm].
+- A virtual address space is represented by type [`mm.MemoryManager`][mm].
-- Sentry VMAs are represented by type [`mm.vma`][mm], stored in
- `mm.MemoryManager.vmas`.
+- Sentry VMAs are represented by type [`mm.vma`][mm], stored in
+ `mm.MemoryManager.vmas`.
-- Mappings from sentry file offsets to host file offsets are abstracted through
- interface method [`memmap.Mappable.Translate`][memmap].
+- Mappings from sentry file offsets to host file offsets are abstracted
+ through interface method [`memmap.Mappable.Translate`][memmap].
-- Reverse mappings from sentry file offsets to virtual mappings are abstracted
- through interface methods [`memmap.Mappable.AddMapping` and
- `memmap.Mappable.RemoveMapping`][memmap].
+- Reverse mappings from sentry file offsets to virtual mappings are abstracted
+ through interface methods
+ [`memmap.Mappable.AddMapping` and `memmap.Mappable.RemoveMapping`][memmap].
-- Host files that may be mapped into host VMAs are represented by type
- [`platform.File`][platform].
+- Host files that may be mapped into host VMAs are represented by type
+ [`platform.File`][platform].
-- Host VMAs are represented in the sentry by type [`mm.pma`][mm] ("platform
- mapping area"), stored in `mm.MemoryManager.pmas`.
+- Host VMAs are represented in the sentry by type [`mm.pma`][mm] ("platform
+ mapping area"), stored in `mm.MemoryManager.pmas`.
-- Creation and destruction of host VMAs is abstracted through interface methods
- [`platform.AddressSpace.MapFile` and `platform.AddressSpace.Unmap`][platform].
+- Creation and destruction of host VMAs is abstracted through interface
+ methods
+ [`platform.AddressSpace.MapFile` and `platform.AddressSpace.Unmap`][platform].
[filemem]: https://gvisor.googlesource.com/gvisor/+/master/pkg/sentry/platform/filemem/filemem.go
[memmap]: https://gvisor.googlesource.com/gvisor/+/master/pkg/sentry/memmap/memmap.go