diff options
Diffstat (limited to 'mem/docs/vmap.9.scd')
| -rw-r--r-- | mem/docs/vmap.9.scd | 80 |
1 files changed, 80 insertions, 0 deletions
diff --git a/mem/docs/vmap.9.scd b/mem/docs/vmap.9.scd new file mode 100644 index 0000000..89faca7 --- /dev/null +++ b/mem/docs/vmap.9.scd @@ -0,0 +1,80 @@ +MEM_VMAP(9) + +# NAME + +*mem_vmap_translate*, *mem_vmap_map*, *mem_vmap_unmap* - manage virtual address spaces + +# SYNOPSIS + +``` +#include <mem/vmap.h> + +typedef struct mem_vmap MemVmap; + +usize mem_vmap_translate(MemVmap *inner, usize virt); +int mem_vmap_map(MemVmap *inner, usize phys, usize virt, usize len, int flags); +void mem_vmap_unmap(MemVmap *inner, usize virt, usize len); +``` + +# DESCRIPTION + +Many CPUs offer the ability to specify mappings between what the CPU regular memory accesses can see, and the physical memory as laid by the machine. A set of mappings enabled at once at the same time is said to constitute a *virtual address space*, in that it is the space of addresses that are meaningful to the current execution environment of the CPU. + +*MemVmap* and its related utility methods are an abstraction over the hardware's memory mapping facilities to allow managing an address space and switch from an address space to another. + +## Translation + +Translation is the action of taking a virtual address and obtaining its physical address. A CPU supporting memory mapping can do this relatively efficiently compared with simulating it in software. + +The *mem_vmap_translate()* function translates a virtual address into its physical one in software. This can be useful for a few reasons and this mechanism is used internally by MemVmap implementation themselves. *mem_vmap_translate()* takes the following arguments: + + _inner_ The *MemVmap* to use + _virt_ The virtual address to translate + +If the translation lands on an unmapped region of the virtual address space, the miss flag is set. + +## Mapping + +The *mem_vmap_map()* function maps a region of physical memory into the specified virtual address space, around a specified virtual address, with some flags. *mem_vmap_map()* takes the following arguments: + + _inner_ The *MemVmap* to use + _phys_ The beginning of the physical memory region that will back the map + _virt_ The beginning of the virtual memory region to which the physical memory shall be mapped + _len_ The length of the region in char-sized units + _flags_ The flags with which the region must be mapped + +The mapping operation may fail for reasons, such as: + - The requested mapping overlaps with a pre-existing mapping + +## Unmapping + +Unmapping is the inverse operation of mapping, it removes a particular map from the set of mappings. + +The *mem_vmap_unmap()* function is used to perform the unmap operation on a particular address space at a specified virtual address. *mem_vmap_unmap()* takes the following arguments: + + _inner_ The *MemVmap* to use + _virt_ The beginning of the virtual memory region that must be unmapped + _len_ The length of the virtual memory region that must be unmapped + +Note: it is not an error to unmap a region of virtual memory that is not already mapped. The unmap operation, if properly implemented, should not fail. + +# Switching + +The *mem_vmap_switch_to()* functions is used to enable a particular address space. It takes only one argument, _inner_ the address space to switch to. + +Note: the caller should naturally make sure that the current code being executed, along with the required data, is correctly mapped at the according places in the target address space. + +# FLAGS + +XXX todo, unimplemented yet + +# RETURN VALUES + +*mem_vmap_translate()* returns a physical address on success, 0 in case of error or miss +*mem_vmap_map()* returns 0 in case of success, or a non-zero value in case of error + +Refer to mem/errors.h for the list of error codes pertaining to the _mem_ module + +# CODE REFERENCES + +*MemVmap* and its related functions are defined in _mem/vmap.c_. Also refer to its particular implementations.
\ No newline at end of file |