diff --git a/docs/assets/header.png b/docs/assets/header.png new file mode 100644 index 000000000..c92ef42a3 Binary files /dev/null and b/docs/assets/header.png differ diff --git a/docs/assets/header.svg b/docs/assets/header.svg new file mode 100644 index 000000000..86b86408b --- /dev/null +++ b/docs/assets/header.svg @@ -0,0 +1,1507 @@ + + + +illustrations +\n + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + illustrations + + + + diff --git a/docs/index.md b/docs/index.md index 66444088f..d3ebdc735 100644 --- a/docs/index.md +++ b/docs/index.md @@ -5,4 +5,17 @@ layout: home --- -This site is in development. Come back soon to see more! \ No newline at end of file +MaPLe (MPL) is a functional language for provably efficient and safe multicore +parallelism, developed by researchers at Carnegie Mellon University, New York +University, and Rochester Institute of Technology. + +This site contains documentation for the MaPLe compiler and run-time system, +intended for anyone interested in contributing to the MaPLe project or learning +more about its implementation. + +To dive in, use the navigation links or search. + +{: .note} +This site is still under development. A few pages are available; see for +example [Heap Objects](rts/mm/object.html) and related pages. +More content will be added soon. \ No newline at end of file diff --git a/docs/rts/em/index.md b/docs/rts/em/index.md new file mode 100644 index 000000000..20df8760c --- /dev/null +++ b/docs/rts/em/index.md @@ -0,0 +1,9 @@ +--- +layout: page +title: Entanglement Detection and Management +parent: Runtime System +--- + +# Entanglement Detection and Management + +TODO... \ No newline at end of file diff --git a/docs/rts/mm/fwd-ptr.md b/docs/rts/mm/fwd-ptr.md new file mode 100644 index 000000000..e1f1afe61 --- /dev/null +++ b/docs/rts/mm/fwd-ptr.md @@ -0,0 +1,9 @@ +--- +layout: page +title: Forwarding Pointers +parent: Memory Management +--- + +# Forwarding Pointers + +TODO... \ No newline at end of file diff --git a/docs/rts/mm/header.md b/docs/rts/mm/header.md index 0a8f1f6ce..fb176ef0c 100644 --- a/docs/rts/mm/header.md +++ b/docs/rts/mm/header.md @@ -6,4 +6,36 @@ parent: Memory Management # Object Headers -TODO... \ No newline at end of file +Every [Heap Object](object.html) has an 8-byte **header** which contains +information about the object size, field layout, etc. This is implemented +with the type [`GC_header`](https://github.com/MPLLang/mpl/blob/6d7bb8588db713b87c515725bff3b5589fe8a9ad/runtime/gc/object.h#L53) in the run-time system. + +As of MaPLe v0.5, the header layout is as follows (in order of least-significant +to most-significant bit). + * Bit 0: indicates a **valid header**. It is set to 0 only if + the header has been overwritten with a [Forwarding Pointer](fwd-ptr.html). + * Bits 1-19: the **object type index**. The object type can be + retrieved by indexing into the [Object Type Table](obj-type-table.html). + * Bits 20-30 are used for [Entanglement Detection and Management](../em): + * Bits 20-27: the **object unpin depth**, used to track when a pinned object + can be safely unpinned. + * Bits 28-29: the **pin type** of the object, used to distinguish between + pinned and unpinned objects. + * Bit 30: indicates whether or not the object is an **entanglement suspect**. + * Bit 31: unused. + +![Header bit layout]({{site.baseurl}}/assets/header.png){:width="80%"} + +{: .note} +> Only the 4 lowest bytes of the header are currently used. This +> is a holdover from MLton, which supports both 32-bit and 64-bit execution +> modes. In 32-bit execution mode, headers and [Forwarding Pointers](fwd-ptr.html) +> are exactly the same size and therefore the header bytes can be reused to +> store a forwarding pointer during GC. In 64-bit execution mode, the forwarding +> pointers require 8 bytes, and therefore 4 bytes remain unused when storing +> a header. +> +> However, note that MaPLe currently only supports 64-bit execution mode, and +> it's unclear whether or not the 32-bit execution mode will be supported in the +> future. So, currently, we are stuck in a bit of a limbo, where the header is +> 8 bytes but we hesitate to use the upper 4 bytes... just in case. \ No newline at end of file diff --git a/docs/rts/mm/obj-type-table.md b/docs/rts/mm/obj-type-table.md new file mode 100644 index 000000000..32da6ab6e --- /dev/null +++ b/docs/rts/mm/obj-type-table.md @@ -0,0 +1,9 @@ +--- +layout: page +title: Object Type Table +parent: Memory Management +--- + +# The Object Type Table + +TODO... \ No newline at end of file