github.com/SagerNet/gvisor@v0.0.0-20210707092255-7731c139d75c/pkg/usermem/README.md (about)

     1  This package defines primitives for sentry access to application memory.
     2  
     3  Major types:
     4  
     5  -   The `IO` interface represents a virtual address space and provides I/O
     6      methods on that address space. `IO` is the lowest-level primitive. The
     7      primary implementation of the `IO` interface is `mm.MemoryManager`.
     8  
     9  -   `IOSequence` represents a collection of individually-contiguous address
    10      ranges in a `IO` that is operated on sequentially, analogous to Linux's
    11      `struct iov_iter`.
    12  
    13  Major usage patterns:
    14  
    15  -   Access to a task's virtual memory, subject to the application's memory
    16      protections and while running on that task's goroutine, from a context that
    17      is at or above the level of the `kernel` package (e.g. most syscall
    18      implementations in `syscalls/linux`); use the `kernel.Task.Copy*` wrappers
    19      defined in `kernel/task_usermem.go`.
    20  
    21  -   Access to a task's virtual memory, from a context that is at or above the
    22      level of the `kernel` package, but where any of the above constraints does
    23      not hold (e.g. `PTRACE_POKEDATA`, which ignores application memory
    24      protections); obtain the task's `mm.MemoryManager` by calling
    25      `kernel.Task.MemoryManager`, and call its `IO` methods directly.
    26  
    27  -   Access to a task's virtual memory, from a context that is below the level of
    28      the `kernel` package (e.g. filesystem I/O); clients must pass I/O arguments
    29      from higher layers, usually in the form of an `IOSequence`. The
    30      `kernel.Task.SingleIOSequence` and `kernel.Task.IovecsIOSequence` functions
    31      in `kernel/task_usermem.go` are convenience functions for doing so.