A process can request specific memory ranges to be allocated. For example, a `uart_server` might request the UART memory region be allocated so that it can handle that device and provide a service. This region cannot be re-mapped to another process until it is freed.
A process can request more memory for its heap. This will pull memory from the global pool and add it to that process' `heap_size`. Processes start out with a `heap_size` of 0, which does not include the contents of the `.text` or `.data` sections.
If a process intends to spawn multiple threads, then it must malloc that memory prior to creating the thread.
These addresses are statically mapped in virtual memory. They are only visible in "Supervisor" mode. However, they are globally mapped, and are available in every process.
Memory is kept in a whitelist. That is, when calling `sys_memory_allocate()`, the address is first validated against a list of known ranges. This has two major benefits:
1. It prevents attacks where memory mirrors can be reused to access another process' memory. For example, on Litex, the peripheral space is mirrored at both `0x70000000` and `0xe0000000`. Without special handling, two different processes could map these two spaces and share memory.
2. We can limit the amount of memory that is needed to keep track of memory. For example, if we had generic tables that expanded every time an invalid region was accessed, then a process could use up the kernel's memory by simply requesting every possible address. In having a whitelist, we can statically allocate memory blocks to track memory usage.
## Memory Tables
Each valid memory page has an associated table entry. This entry simply contains a `XousPid`, to indicate which process the memory block belongs to. A `XousPid` of `0` is invalid, and indicates the region is free. A `XousPid` of `1` indicates the page belongs to the kernel.
In a system with ample amounts of memory, all valid memory page would get its own memory table. However, in resource-constrained systems, a simple array is not suitable, and so a programmatic lookup table is used instead.
There are several arguments that specify where kernel structures should go.
### Memory Blocks
The kernel needs to know the range of pages. This is passed to the kernel
as a list in the following form:
```
MBLK,$count,
$start1,$len1,$name
$start2,$len2,$name
...
```
The first memory range that is listed is always RAM, which is the range that will be used for dealing with `sbrk` and unspecified memory allocations. The name should be printable ASCII, and is primarily used for debugging.
### Kernel Memory
This structure specifies how kernel memory is laid out.
## Allocation Tables
Each page of memory has an entry in the allocation tables. When allocating
a new page, Xous ensures that page is not currently allocated to another
process. This ensures that each page of memory is only assigned to one
process at a time, unless that page is handed out as shared.
Allocation tables have the following layout:
```rust
struct AllocationEntry {
/// PID that owns this page. `0` if this
/// page is unallocated.
pid: XousPid,
}
struct PageRange {
/// A slice of all allocations within this range.
entries: &[AllocationEntry],
}
struct PageAllocations {
/// Each range of memory gets its own allocation table.
/// ranges[0] is always defined as RAM,
/// and is where memory comes from when
/// no physical address is specified.
ranges: &[PageRange],
}
```
## Page Tables
Each process requires its own page table. The kernel will be mapped to a fixed offset in each process, in order to save some RAM and make
