= Data replication & distribution policy =

[[PageOutline]]

The replication / distribution policy has two goals: enforce locality (as much as possible), and avoid contention (it is the main goal).
 * The read-only segments (type CODE) are replicated in all clusters where they are used.
 * The private  segments (type STACK) are placed in the same cluster as the thread using it.
 * The shared segments (types DATA, HEAP, etc ) are distributed on all clusters as regularly as possible to avoid contention.
 * The pinned segments (type REMOTE) are placed in the user-specified cluster.

To actually control data placement on the physical memory banks, the kernel uses the paged virtual memory MMU.

This policy is implemented by the Virtual Memory Manager (vmm.h / vmm.c files).

A '''vseg''' is a contiguous memory zone in the process virtual space. It is always an integer number of pages. Depending on its type, a '''vseg''' has some specific attributes regarding access rights, replication policy, and distribution policy. The vseg descriptor is defined by the structure vseg_t (in vseg.h file).

For each process P, the process descriptor is replicated in all clusters containing at least one thread of P (called active clusters). In each cluster K, the virtual memory manager VMM(P,K) is stored in the local process descriptor, and contains two main structures: VSL(P,K) is the list of all vsegs registered for process P in cluster K, and GPT(P,K) is the generic page table, defining the actual physical mapping of those vsegs on the distributed physical memory banks.

== 1)  User segments types and attributes  ==

 * A vseg is '''public''' when it can be accessed by any thread of the process, whatever the cluster where the thread is running.  It is '''private''' when it can only be accessed by the threads running in the cluster containing the physical memory bank where this vseg is mapped. A '''private''' vseg is entirely mapped in one single cluster K. It is registered in the VMM(P,K) segment list, but not in the other VMM(P,X) segment lists.

 * A vseg can be '''localised''' (all vseg pages are mapped in the same cluster), or '''distributed''' (different pages are mapped on different clusters, using the virtual page number (VPN) least significant bits as distribution key). A '''private''' vseg is always '''localised'''.

ALMOS-MK defines seven vseg types:
|| type        ||               ||                  ||                                                                                                     ||
|| CODE     ||  private   || localised   || one per active cluster / same virtual addresses / same content    ||
|| DATA       ||  public   || distributed || one per process / replicated in all active clusters                         ||
|| STACK    ||  private  || localised    || one per thread / in same cluster as the thread                              || 
|| MMAP     ||  public   || distributed || one per mmap(anon)                                                                    ||
|| FILE        ||  public   || localised    || one per mmap(file) / in same cluster as the file                             ||
|| MALLOC ||  public   || distributed || used by the malloc() library / dynamically extensible                    ||
|| REMOTE ||  public   || localised    || one per remote_malloc() / in cluster specified by user                  ||

The replication of the VSL(P,K) and GPT(P,K) structures creates a coherence problem for non private vsegs.

 * A VSL(P,K) contains all private vsegs in cluster K, but contains only the public vsegs that have been actually accessed by a thread of P running in cluster K. Only the '''reference''' process descriptor stored in the reference cluster Z contains the complete list VSL(P,Z) of all public vsegs for the P process.
 * A GPT(P,K) contains all contains all entries corresponding to private vsegs. For public vsegs, it contains only the entries corresponding to pages that have been accessed by a thread running in cluster K. Only the reference cluster Z contains the complete  GPT(P,Z) page table of all mapped pages in all clusters for process P.

Therefore, the process descriptors - other than the reference one - are used as read-only caches.

For a process P, the CODE and DATA vsegs are registered in the VSL(P,Z) when the process main thread is created in reference cluster Z. The STACK vsegs are registered in the VSL(P,K) when a thread of process P is created in cluster K. The HEAP, REMOTE, or FILE threads are registered in the VSL(P,Z) of the reference cluster Z, when any thread, running in any cluster X, makes a mmap(), malloc() or remote malloc() system call, because only the reference cluster can dynamically create a public vseg. The new vseg is then copied in the VSL(P,X) of the cluster X running the client thread. It is only registered in the VSL of other clusters in case of page-fault (on-demand registration).

The GPT(P,K) page tables are progressively updated by the kernel as a response to a page-fault (on-demand paging). But a page fault detected in any cluster K must always be reported to the reference cluster Z, and the new mapping should be introduced in the reference GPT(P,Z), before to be copied in the client GPT(P,X).

Finally, when a given vseg or a given entry in the page table must be removed by the kernel, this modification must be done first in the reference cluster, and broadcasted to all other clusters for update.

== 2) User process virtual space organisation ==

The virtual space of an user process P in a given cluster K is split in four zones called ''vzone''.  Each vzone contains one or several vsegs.

 1. The '''utils''' vzone has a fixed size, and is located in the lower part of the virtual space. It contains the three vsegs ''kentry'', ''args'', ''envs'', whose sizes are defined by configuration parameters. These vsegs are set by the kernel each time a new process is created. The ''kentry'' vseg has CODE type and contains the code that must be executed to enter the kernel from user space. The ''args'' vseg has DATA type, and contains the process main() thread arguments. The ''envs'' vseg has DATA type and contains the process environment variables.

 1. The '''elf''' vzone has a variable size, and contains the ''text'' and and ''data'' vsegs containing the process binary code and global data. The size is defined in the .elf file and reported in the boot_info structure by the boot loader. It is located on top of the '''utils''' vzone

 1. The '''stack''' vzone has a fixed size, and is located in the upper part of the virtual space. It contains as many vsegs of type STACK as the max number of threads for a process in a single cluster. The total size is defined as CONFIG_VSPACE_STACK_SIZE * CONFIG_PTHREAD_MAX_NR. 

 1. The '''heap''' vzone has a variable size, and occupies all space between the top of the '''elf''' vzone and the base of the '''stack''' zone. It contains all vsegs of type MMAP, FILE, MALLOC, or REMOTE that are dynamically allocated by the reference VMM manager.