Commit 2cb622b6 authored by Kunshan Wang's avatar Kunshan Wang

Renamed files to make them more GitLab-friendly

As we migrated to GitLab, GitLab expects the .rst suffix instead of
.rest which GitHub expects. I also renamed some files using this
opportunity.
parent 979b4eb2
================
Mu Specification
================
This document aims to provide a detailed description of Mu, a micro virtual
machine, including its architecture, instruction set and type system.
NOTE: This branch uses the goto-with-values form. The previous branch using
SSA form with PHI nodes is in the `phi
<https://github.com/microvm/microvm-spec/tree/phi>`__ branch.
Main specification:
- `Overview <overview.rest>`__
- `Intermediate Representation <uvm-ir.rest>`__
- `Intermediate Representation Binary Form (deprecated) <uvm-ir-binary.rest>`__
- `Type System <type-system.rest>`__
- `Instruction Set <instruction-set.rest>`__
- `Common Instructions <common-insts.rest>`__
- `Client Interface (a.k.a. The API) <uvm-client-interface.rest>`__
- `Call-based IR Building API (work in progress) <irbuilder.rest>`__
- `Threads and Stacks <threads-stacks.rest>`__
- `Memory and Garbage Collection <uvm-memory.rest>`__
- `Memory Model <memory-model.rest>`__
- `(Unsafe) Native Interface <native-interface.rest>`__
- `Heap Allocation and Initialisation Language (HAIL) <hail.rest>`__
- `Portability and Implementation Advices <portability.rest>`__
Platform-specific parts: These extends the main specification. The main
specification considers these parts as implementation-specific.
- `AMD64 Unix Native Interface <native-interface-x64-unix.rest>`__
.. vim: tw=80
================
Mu Specification
================
This document aims to provide a detailed description of Mu, a micro virtual
machine, including its architecture, instruction set and type system.
Main specification:
- `Overview <overview.rst>`__
- `Intermediate Representation <ir.rst>`__
- `Intermediate Representation Binary Form (deprecated) <ir-binary.rst>`__
- `Type System <type-system.rst>`__
- `Instruction Set <instruction-set.rst>`__
- `Common Instructions <common-insts.rst>`__
- `Client Interface (a.k.a. The API) <api.rst>`__
- `Call-based IR Building API (work in progress) <irbuilder.rst>`__
- `Threads and Stacks <threads-stacks.rst>`__
- `Memory and Garbage Collection <memory.rst>`__
- `Memory Model <memory-model.rst>`__
- `(Unsafe) Native Interface <native-interface.rst>`__
- `Heap Allocation and Initialisation Language (HAIL) <hail.rst>`__
- `Portability and Implementation Advices <portability.rst>`__
Platform-specific parts: These extends the main specification. The main
specification considers these parts as implementation-specific.
- `AMD64 Unix Native Interface <native-interface-x64-unix.rst>`__
.. vim: tw=80
......@@ -22,8 +22,8 @@ bindings, which is beyond this specification.
script to automatically generate interfaces to higher-level languages.
Most API functions are also available in the form of `instructions
<instruction-set.rest>`__ (such as ``refcast`` and ``REFCAST``) or `common
instructions <common-insts.rest>`__ (such as ``new_stack`` and
<instruction-set.rst>`__ (such as ``refcast`` and ``REFCAST``) or `common
instructions <common-insts.rst>`__ (such as ``new_stack`` and
``@uvm.new_stack``). See their respective chapters.
Starting Up and Shutting Down
......@@ -181,7 +181,7 @@ location or other entities. This means a handle can keep Mu heap objects alive.
Lua 4.0, introduced a stack-based API to pass values to/from the C program.
That stack is unnecessary for Mu because Mu is not a stack-based VM. The API
is also not designed to frequently exchange data frequently with the client
(see the (unsafe) `Native Interface <native-interface.rest>`__ for a more
(see the (unsafe) `Native Interface <native-interface.rst>`__ for a more
efficient (and less safe) interface).
..
......@@ -604,7 +604,7 @@ Memory addressing
* ``shift_iref`` assumes ``opnd`` refers to an element in a memory array
(including arrays, vectors and the variable part of hybrids in the memory, see
`Mu and the Memory <uvm-memory.rest>`__). It returns the iref of ``opnd`` moved by
`Mu and the Memory <memory.rst>`__). It returns the iref of ``opnd`` moved by
``offset`` (forward if positive, backward if negative).
* ``get_var_part_iref`` gets an iref to the 0-th element of the variable part of
......@@ -946,7 +946,7 @@ where::
``@uvm.native.expose`` instruction or the ``expose`` API function with calling
convention ``call_conv``.
See the `Native Interface <native-interface.rest>`__ chapter for details of expose
See the `Native Interface <native-interface.rst>`__ chapter for details of expose
and unexpose. See the platform-specific native interface for the return value
type.
......@@ -963,7 +963,7 @@ It is unspecified on which stack the trap handler is run.
Mu is allowed to call these handlers concurrently. Mu does not guarantee the
order in which these handlers are called, but guarantees the happen-before
relation between the trap and the handler. See `Memory Model <memory-model.rest>`__.
relation between the trap and the handler. See `Memory Model <memory-model.rst>`__.
The Mu thread that triggers the trap is temporarily unbound from the stack.
......@@ -1038,7 +1038,7 @@ are used, they must be set and must be held by ``ctx``.
Building Mu IR Bundles
======================
See `IR Builder <irbuilder.rest>`__ for this part of the API.
See `IR Builder <irbuilder.rst>`__ for this part of the API.
Signal Handling
===============
......
......@@ -7,7 +7,7 @@ This document specifies Common Instructions.
**Common Instructions** are instructions that have a common format and are
used with the ``COMMINST`` super instruction. They have:
1. An ID and a name. (This means, they are *identified*. See `<uvm-ir.rest>`__.)
1. An ID and a name. (This means, they are *identified*. See `<ir.rst>`__.)
2. A flag list.
3. A type parameter list.
4. A value parameter list.
......@@ -195,7 +195,7 @@ Math Instructions
Futex Instructions
==================
See `<threads-stacks.rest>`__ for high-level descriptions about Futex.
See `<threads-stacks.rst>`__ for high-level descriptions about Futex.
Wait
----
......
......@@ -56,7 +56,7 @@ evaluated. Storing them to global cells is one way to keep references to the
allocated objects.
**Global name**, **integer literal**, **floating point literal** and **null
literal** are defined the same way as in `Mu IR <uvm-ir.rest>`__. They are
literal** are defined the same way as in `Mu IR <ir.rst>`__. They are
denoted as ``globalName``, ``intLit``, ``floatLit``, ``'NULL'``, respectively.
Expressions
......@@ -342,7 +342,7 @@ refer to different things even if their values are equal. HAIL IDs only refer to
heap-allocated objects in the current HAIL script.
In the following paragraphs, binary types defined in `Mu IR Binary Form
<uvm-ir-binary.rest>`__ are used. For convenience, we use "hID" for HAIL ID and "mID"
<ir-binary.rst>`__ are used. For convenience, we use "hID" for HAIL ID and "mID"
for Mu ID.
A *fixed object allocation* definition has the form:
......
......@@ -147,7 +147,7 @@ Otherwise it is dead.
The execution of an instruction is called **an evaluation**. An evaluation
determines its results, and this process is called **value computation**.
Accessing the memory (see `Memory Model <uvm-memory.rest>`__) or changing the
Accessing the memory (see `Memory Model <memory.rst>`__) or changing the
state of the execution environment is called **side effect**. An evaluation may
have side effects.
......@@ -223,7 +223,7 @@ diverging control flows. *nor* and *exc* are the **normal destination** and the
**exceptional destination**, respectively.
The exception clause can be omitted. Any instruction that may have exception
clauses is not a *terminator* (see `Mu IR <uvm-ir.rest>`__) if the exception
clauses is not a *terminator* (see `Mu IR <ir.rst>`__) if the exception
clause is omitted. Otherwise it is a *terminator*.
Any instruction that may have exception clause may **continue normally** or
......@@ -548,7 +548,7 @@ result:
In all comparison operations, both *op1* and *op2* must have type *T*.
For EQ and NE, *T* must be a EQ-comparable type (see `<type-system.rest>`__) or a
For EQ and NE, *T* must be a EQ-comparable type (see `<type-system.rst>`__) or a
vector of EQ-comparable types.
For SGE, SGT, SLE, SLT, UGE, UGT, ULE and ULT, *T* must be ``int`` or a vector
......@@ -1137,7 +1137,7 @@ exceptionally, catching the exception received.
NOTE: This can be the result of OSR: Upper frames are popped and the current
``CALL`` instruction receives values provided by the client, or by other
means of stack binding. See `Threads and Stacks <threads-stacks.rest>`__.
means of stack binding. See `Threads and Stacks <threads-stacks.rst>`__.
The ``TAILCALL`` instruction replaces the caller's stack frame with a new stack
frame for the callee. If the frame below the current frame has state
......@@ -1158,7 +1158,7 @@ point. After ``TAILCALL``, the new frame is in the **ACTIVE** state.
which version to call.)
Calling an undefined function is allowed. Such functions will trigger a trap
when executed so that the client can handle it. See `Mu IR <uvm-ir.rest>`__ for
when executed so that the client can handle it. See `Mu IR <ir.rst>`__ for
the behaviour of undefined functions.
..
......@@ -1646,7 +1646,7 @@ result:
..
NOTE: The cryptic description of the return value means the referent type
``T`` may be a prefix (see `Mu and the Memory <uvm-memory.rest>`__) of the
``T`` may be a prefix (see `Mu and the Memory <memory.rst>`__) of the
actual type represented in the object. In this case, this instruction only
provides access to the prefix part.
......@@ -1716,7 +1716,7 @@ The ``GETELEMIREF`` instruction gets an internal reference/pointer to the
The ``SHIFTIREF`` instruction assumes the *opnd* already refers to an element of
a *memory array* (including arrays, vectors and the variable part of hybrids,
see `Mu and the Memory <uvm-memory.rest>`__). It moves *opnd* internal
see `Mu and the Memory <memory.rst>`__). It moves *opnd* internal
reference/pointer forward by *offset* elements. If *offset* is negative, it
moves the reference/pointer backwards by the absolute value of *offset*.
......@@ -1797,8 +1797,8 @@ Memory Order
~~~~~~~~~~~~
A **memory order** is one in the following table. Their semantics are described
in `<memory-model.rest>`__. Different instructions have different requirements for
their *memory orders*. See `<memory-model.rest>`__.
in `<memory-model.rst>`__. Different instructions have different requirements for
their *memory orders*. See `<memory-model.rst>`__.
=========== ====== =======================
Keyword Binary Semantic
......@@ -1835,7 +1835,7 @@ result
Type is the strong variant of *T*: The result of the load operation.
The ``LOAD`` instruction performs a *load* operation with argument (*ord*, *T*,
*loc*) as defined in `Mu and the Memory <uvm-memory.rest>`__.
*loc*) as defined in `Mu and the Memory <memory.rst>`__.
In the text form, *ord* can be omitted and defaults to ``NOT_ATOMIC``.
......@@ -1875,7 +1875,7 @@ newVal
Type is the strong variant of *T*: The new value to store.
The ``STORE`` instruction performs a *store* operation with argument (*ord*,
*T*, *loc*, *newVal*) as defined in `Mu and the Memory <uvm-memory.rest>`__.
*T*, *loc*, *newVal*) as defined in `Mu and the Memory <memory.rst>`__.
In the text form, *ord* can be omitted and defaults to ``NOT_ATOMIC``.
......@@ -1929,10 +1929,10 @@ results:
The ``CMPXCHG`` instruction performs a *compare exchange* operation with
argument (*isWeak*, *ordSucc*, *ordFail*, *T*, *loc*, *expected*, *desired*),
where *isWeak* is true if ``WEAK`` is present, otherwise false. The operation
is defined in `Mu and the Memory <uvm-memory.rest>`__.
is defined in `Mu and the Memory <memory.rst>`__.
This instruction produces two results which represent the *v* and *s* value as
defined in `Mu and the Memory <uvm-memory.rest>`__. The second result is 1 for
defined in `Mu and the Memory <memory.rst>`__. The second result is 1 for
true and 0 for false.
For LLVM users: This is the counterpart of the ``cmpxchg`` instruction.
......@@ -2020,7 +2020,7 @@ UMIN 0x0A int unsigned min
The ``ATOMICRMW`` instruction performs an *atomic-x* operation with argument
(*ord*, *T*, *loc*, *opnd*), where the *x* in *atomic-x* is *op*. The operation
is defined in `Mu and the Memory <uvm-memory.rest>`__.
is defined in `Mu and the Memory <memory.rst>`__.
..
......@@ -2044,7 +2044,7 @@ ord
*memory order*: The memory order.
The ``FENCE`` is a fence of memory order *ord*. Its semantics is specified in
`<memory-model.rest>`__.
`<memory-model.rst>`__.
For LLVM users: This is the counterpart of the ``fence`` instruction.
......@@ -2097,7 +2097,7 @@ A ``TRAP`` instruction is always enabled. A ``WATCHPOINT`` can be enabled or
disabled by its watch point ID *wpid*. A disabled ``WATCHPOINT`` does not
produce any results and unconditionally branches to the destination *dis*.
`The API <uvm-client-interface.rest>`__ provides functions to enable or disable
`The API <api.rst>`__ provides functions to enable or disable
watchpoints.
A ``TRAP`` or an enabled ``WATCHPOINT`` temporarily unbinds the current thread
......@@ -2133,7 +2133,7 @@ it is enabled.
If the client disabled watch point 42 when handling this watchpoint and
rebinds the current stack (see `Threads and Stacks
<threads-stacks.rest>`__ for stack/thread rebinding), then it will branch to
<threads-stacks.rst>`__ for stack/thread rebinding), then it will branch to
``%ena``. The ``%wp`` instruction will branch to ``%dis`` if and only if
watch point 42 is disabled when it is executed.
......@@ -2339,7 +2339,7 @@ The ``CCALL`` instruction calls a native function.
The *callee* must have type *T*. The allowed type of ``T``, and the number of
return values, are implementation-dependent and calling convention-dependent.
See `<native-interface.rest>`__ for a detailed description of the native interface.
See `<native-interface.rst>`__ for a detailed description of the native interface.
The return values of ``CCALL`` are the return values of the native callee.
......@@ -2445,11 +2445,11 @@ or it receives the exception provided by the rebinding process.
Thread and Stack
================
See `Thread and Stack <threads-stacks.rest>`__ for more information of stack
See `Thread and Stack <threads-stacks.rst>`__ for more information of stack
creation and the swap-stack operation.
NOTE: New stacks can be created by the ``@uvm.new_stack`` `common instruction
<common-insts.rest>`__ or the ``new_stack`` `API <uvm-client-interface.rest>`__
<common-insts.rst>`__ or the ``new_stack`` `API <api.rst>`__
function.
Common Structures
......@@ -2567,7 +2567,7 @@ In the *curStackClause*:
According to the *newStackClause*, values or an exception can be passed to the
*swappee* stack.
See `Thread and Stack <threads-stacks.rest>`__ for more details about the
See `Thread and Stack <threads-stacks.rst>`__ for more details about the
SWAP-STACK operation.
When a stack is rebound and the top frame pauses on a ``SWAPSTACK`` instruction
......@@ -2690,7 +2690,7 @@ instruction must not have an exception clause unless the common instruction can
continue exceptionally. A ``COMMINST`` instruction must have an empty keep-alive
clause unless the common instruction is an OSR point.
See `<common-insts.rest>`__ for a complete list of common instructions.
See `<common-insts.rst>`__ for a complete list of common instructions.
..
......
......@@ -3,7 +3,7 @@ Intermediate Representation (Binary Form)
=========================================
This document describes the binary form of the Mu intermediate representation.
For the text form, see `<uvm-ir.rest>`__.
For the text form, see `<ir.rst>`__.
**DEPRECATED**: The binary format is deprecated. As mentioned in `this ticket
<https://github.com/microvm/microvm-meta/issues/55>`__, we have come to the
......@@ -16,7 +16,7 @@ compiled implementations.
Overview
========
The Mu IR Binary Form is similar to the `Text Form <uvm-ir.rest>`__ in structure,
The Mu IR Binary Form is similar to the `Text Form <ir.rst>`__ in structure,
but has notable differences.
Numerical IDs are used exclusively instead of textual names. The binary form
......@@ -76,11 +76,11 @@ ID List
An ID list, denoted as **idList**, is a list of IDs. It has the general form:
+------+-----+-----+-----+
| lent | idt | idt | ... |
+======+=====+=====+=====+
| nIDs | id1 | id2 | ... |
+------+-----+-----+-----+
+------+-----+-----+----------------+
| lent | idt | idt | . . . |
+======+=====+=====+================+
| nIDs | id1 | id2 | . . . |
+------+-----+-----+----------------+
``nIDs`` specifies the number of IDs and there are ``nIDs`` IDs following it.
......@@ -102,7 +102,7 @@ Type definition has the following form:
+------+-----+------------------+
``id`` is the identifier of the defined type. A type constructor follows the
opcode 0x01 and the ID. See `<type-system.rest>`__ for a complete list of type
opcode 0x01 and the ID. See `<type-system.rst>`__ for a complete list of type
constructors.
NOTE: this is equivalent to: ``.typedef id = cons``.
......@@ -267,21 +267,21 @@ Function Body
A **function body** has the following form:
+------+-------------+-------------+-----+
| lent | basic block | basic block | ... |
+======+=============+=============+=====+
| nbbs | bb1 | bb2 | ... |
+------+-------------+-------------+-----+
+------+-------------+-------------+-------+
| lent | basic block | basic block | . . . |
+======+=============+=============+=======+
| nbbs | bb1 | bb2 | . . . |
+------+-------------+-------------+-------+
``nbbs`` is the number of basic blocks. ``bbx`` are basic blocks.
A **basic block** has the following form:
+-----+---------+---------+-----+--------+-------------+-------------+-----+
| idt | lent | idPairs | idt | lent | instruction | instruction | ... |
+=====+=========+=========+=====+========+=============+=============+=====+
| id | nparams | params | exc | ninsts | inst1 | inst2 | ... |
+-----+---------+---------+-----+--------+-------------+-------------+-----+
+-----+---------+---------+-----+--------+-------------+-------------+-------+
| idt | lent | idPairs | idt | lent | instruction | instruction | . . . |
+=====+=========+=========+=====+========+=============+=============+=======+
| id | nparams | params | exc | ninsts | inst1 | inst2 | . . . |
+-----+---------+---------+-----+--------+-------------+-------------+-------+
``id`` is the ID of the basic block. Every basic block must have an ID, *even
the entry block*. ``nparams`` is the number of parameters in ``params``, which a
......@@ -311,7 +311,7 @@ An **instruction** has the following form:
``resIDs`` is a list of IDS for the results. ``id`` is the ID of the
instruction. ``instbody`` is instruction body which is specific to each
instruction. See `<instruction-set.rest>`__ for an exhaustive list.
instruction. See `<instruction-set.rst>`__ for an exhaustive list.
Function Exposing Definition
============================
......@@ -337,16 +337,16 @@ valid textual global identifier (including the prefix '@').
A name binding has the following form:
+------+-----+--------+-------+-------+-----+
| opct | idt | lent | i8 | i8 | ... |
+======+=====+========+=======+=======+=====+
| 0x08 | id | nbytes | byte1 | byte2 | ... |
+------+-----+--------+-------+-------+-----+
+------+-----+--------+-------+-------+-------+
| opct | idt | lent | i8 | i8 | . . . |
+======+=====+========+=======+=======+=======+
| 0x08 | id | nbytes | byte1 | byte2 | . . . |
+------+-----+--------+-------+-------+-------+
``id`` is the ID to bind. ``nbytes`` is the number of bytes in the name and
``bytex`` is the value of each byte.
The name is encoded in ASCII and must follow the rules of global names, local
names and allowed characters as defined in `<uvm-ir.rest>`__.
names and allowed characters as defined in `<ir.rst>`__.
.. vim: textwidth=80
......@@ -13,15 +13,15 @@ Mu IR is a tree-shaped structure that consists of nodes, including top-level
definitions and their children. It also has a human-readable text form.
This document describes the top-level of the Mu IR using the text form. There is
also the `IR Builder API <irbuilder.rest>`__, a programmatic interface to build
also the `IR Builder API <irbuilder.rst>`__, a programmatic interface to build
Mu IR inside a running micro VM.
There was a binary form, but is now deprecated. See `<uvm-ir-binary.rest>`__.
There was a binary form, but is now deprecated. See `<ir-binary.rst>`__.
For the documents of the type system and the instruction set, see:
- `<type-system.rest>`__
- `<instruction-set.rest>`__
- `<type-system.rst>`__
- `<instruction-set.rst>`__
Example
=======
......@@ -262,7 +262,7 @@ conflict if two local names have the same global name.
The call site can be globally identified by ``@foo.v1.entry.the_call_site``.
The trap can be identified by ``@foo.v1.entry.my_trap``. The name is
globally unique and can be used to identify individual traps and call sites
in *trap handlers* (see `the API <uvm-client-interface.rest>`__).
in *trap handlers* (see `the API <api.rst>`__).
Identifiers
~~~~~~~~~~~
......@@ -277,7 +277,7 @@ implementation for extension purposes.
Type Definition
===============
Types and the **type constructor** syntax are documented in `<type-system.rest>`__.
Types and the **type constructor** syntax are documented in `<type-system.rst>`__.
A **type definition** gives a name to a type. It has the following form::
......@@ -443,7 +443,7 @@ A **constant constructor** can be the following:
A constant must not be recursive.
- A **null constructor** create a null value of *general reference types* except
``weakref`` (defined in `<type-system.rest>`__). It is written as the **null
``weakref`` (defined in `<type-system.rst>`__). It is written as the **null
literal**: ``NULL``.
..
......@@ -454,7 +454,7 @@ A **constant constructor** can be the following:
..
NOTE: ``weakref`` cannot be the type of an SSA variable, but all constants
are SSA variables. (See `<type-system.rest>`__ and `<instruction-set.rest>`__).
are SSA variables. (See `<type-system.rst>`__ and `<instruction-set.rst>`__).
..
......@@ -568,7 +568,7 @@ Global Cell Definition
======================
A **global cell definition** defines a **global cell**. A global cell is the
memory allocation unit in the *global memory*. See `<uvm-memory.rest>`__ for more
memory allocation unit in the *global memory*. See `<memory.rst>`__ for more
information about the global memory.
NOTE: The global memory is the counterpart of static or global variables in
......@@ -609,7 +609,7 @@ A global cell definition has the form::
For C programmers: Unlike C, global cells cannot be initialised as C global
variables. Mu global cells (as any Mu memory locations) are initialised to 0
or NULL. Writing to global cells can only be done via memory accessing
(load, store, ...), or indirectly via the `HAIL <hail.rest>`__ language.
(load, store, ...), or indirectly via the `HAIL <hail.rst>`__ language.
Beware that concurrent non-atomic access (even as a result of careless
initialisation) may result in data race, which has undefined behaviour.
......@@ -795,7 +795,7 @@ absent, the instruction does not have a name.
The grammar of the ``InstBody`` part for each instruction is defined separately
in `<instruction-set.rest>`__.
in `<instruction-set.rst>`__.
Full example::
......@@ -828,7 +828,7 @@ which is one of the following:
- ``RET``
- ``THROW``
- ``SWAPSTACK`` if the "current stack clause" is ``KILL_OLD``
- Some `Common Instructions <common-insts.rest>`__ are always terminators:
- Some `Common Instructions <common-insts.rst>`__ are always terminators:
- ``@uvm.thread_exit``
......@@ -841,7 +841,7 @@ which is one of the following:
- ``LOAD``, ``STORE``, ``CMPXCHG``, ``ATOMICRMW``
- ``TRAP``, ``WATCHPOINT``
- ``NEWTHREAD``, ``SWAPSTACK``
- Some `Common Instructions <common-insts.rest>`__ when having exception
- Some `Common Instructions <common-insts.rst>`__ when having exception
clause
- ``@uvm.new_stack``
......@@ -882,7 +882,7 @@ Bundle Loading
TODO: The spec should describe the call-based API, too.
The API provides a ``load_bundle`` function. See `the API
<uvm-client-interface.rest>`__. This function can be called by multiple client
<api.rst>`__. This function can be called by multiple client
threads on their client contexts, and the result is always equivalent to as if
they were loaded in a specific sequence.
......@@ -904,7 +904,7 @@ defined version of the function. Defines of functions (bundle loading) and uses
of functions (including function calls and the creation of stacks, i.e. the
``@uvm.new_stack`` instruction or the ``new_stack`` API) obey the memory model
of the ``RELAXED`` order as if the definition is a store and the use is a load.
See `Memory Model <memory-model.rest>`__.
See `Memory Model <memory-model.rst>`__.
All existing activations of any functions remain unchanged, that is, they remain
to be the old versions of the functions.
......
......@@ -3,7 +3,7 @@ Function Call-based Mu IR Building API
======================================
This chapter describes the function call-based Mu IR building API. It is part of
the `Mu Client Interface <uvm-client-interface.rest>`__.
the `Mu Client Interface <api.rst>`__.
The C functions and types are also defined in `<muapi.h>`__.
......@@ -27,7 +27,7 @@ finished building, the client calls another API function
to the client.
All API functions are also available as `common instructions
<common-insts.rest>`__.
<common-insts.rst>`__.
This API is minimal, just like other parts of the Mu Client API. For example,
the AST is only mutable in certain ways (such as appending instructions in the
......@@ -111,7 +111,7 @@ are only supposed to refer to nodes of their specified type in the comments::
typedef MuChildNode MuInstNode; // Instruction (itself, not result)
All ``MuChildNode`` subtypes are "identified entities" (see `Mu IR
<uvm-ir.rest>`__). They have IDs and optionally names. The ID of each
<ir.rst>`__). They have IDs and optionally names. The ID of each
``MuChildNode`` is generated automatically. The ID can be obtained by the
``get_id`` function. The names are assigned by the client by the ``set_name``
function.
......@@ -412,16 +412,16 @@ These functions create constant nodes and add them to the bundle ``b``.
multiple of 64 bits.
- ``new_const_float`` and ``new_const_double`` create constants of the
``float`` type and the ``double`` type, respectively. ``ty`` must be
``float`` or ``double``. ``value`` is the value.
``float`` type and the ``double`` type, respectively. ``ty`` must be
``float`` or ``double``. ``value`` is the value.
- ``new_const_null`` creates a ``NULL`` constant of general reference types.
``ty`` is the type and must be a general reference type.
``ty`` is the type and must be a general reference type.
- ``new_const_seq`` can create constants of ``struct``, ``array`` or
``vector`` types. ``ty`` is the type. ``elems`` points to an array of other
constants which are the fields or elements. ``nelems`` is the length of the
array, and must match the actual number of fields or elements of the type.
``vector`` types. ``ty`` is the type. ``elems`` points to an array of other
constants which are the fields or elements. ``nelems`` is the length of the
array, and must match the actual number of fields or elements of the type.
All constants are created in one step, because constants cannot be recursive.
......
......@@ -67,24 +67,24 @@ Concepts
========
data value
See `Type System <type-system.rest>`__
See `Type System <type-system.rst>`__
SSA variable, instruction and evaluation
See `Instruction Set <instruction-set.rest>`__
See `Instruction Set <instruction-set.rst>`__
memory, initial value, load, store, access and conflict
See `Mu and the Memory <uvm-memory.rest>`__
See `Mu and the Memory <memory.rst>`__
thread
A thread is the unit of CPU scheduling. In this memory model, threads
include but are not limited to Mu threads. See `Threads and Stacks <threads-stacks.rest>`__ for the
include but are not limited to Mu threads. See `Threads and Stacks <threads-stacks.rst>`__ for the
definition of Mu threads.
stack, stack binding, stack unbinding, swap-stack
See `Threads and Stacks <threads-stacks.rest>`__
See `Threads and Stacks <threads-stacks.rst>`__
futex, futex_wait, futex_wake
See `Threads and Stacks <threads-stacks.rest>`__
See `Threads and Stacks <threads-stacks.rst>`__
Comparison of Terminology
-------------------------
......
......@@ -116,7 +116,7 @@ overlapping regions in the address space.
* Mu forces the 2's complement representation, though the byte order and
alignment requirement are implementation-defined.
See `Native Interface <native-interface.rest>`__ for details about the pinning and
See `Native Interface <native-interface.rst>`__ for details about the pinning and
unpinning operations.
Memory Allocation and Deallocation
......@@ -190,8 +190,8 @@ have both a load and a store operation, but may have special atomic properties.
abstract operations are in lower case: load, store and access.
Memory access operations can be performed by some Mu instructions (see
`Instruction Set <instruction-set.rest>`__, API functions (see `Client Interface
<uvm-client-interface.rest>`__), native programs which accesses the pinned Mu memory,
`Instruction Set <instruction-set.rst>`__, API functions (see `Client Interface
<api.rst>`__), native programs which accesses the pinned Mu memory,
or in other implementation-specific ways.
Two memory accesses **conflict** if one stores to a memory location and the
......@@ -202,7 +202,7 @@ Parameters and Semantics of Memory Operations
Generally speaking, load operations copy values from the memory and store
operations copy values into the memory. The exact results are determined by the
memory model. See `Memory Model <memory-model.rest>`__.
memory model. See `Memory Model <memory-model.rst>`__.
A **load** operation has parameters ``(ord, T, loc)``. *ord* is the memory order
of the operation. *T* is the type of *loc*, a memory location. The result is a
......@@ -282,7 +282,7 @@ operation.
All operators other than ``XCHG`` are only applicable for integer types.
``XCHG`` is allowed for any type. However, a Mu implementation may only
implement some combinations of operators and operand types according to the
requirements specified in `Portability <portability.rest>`__
requirements specified in `Portability <portability.rst>`__
Memory Operations on Pointers
-----------------------------
......@@ -296,7 +296,7 @@ represented as ``uptr<T>``) rather than memory locations (usually represented as
Only *native-safe* types can be accessed via pointers.
When accessing the memory via pointers, if the bytes are mapped to a Mu memory
location via pinning (see `Native Interface <native-interface.rest>`__), then if the
location via pinning (see `Native Interface <native-interface.rst>`__), then if the
referent type of the pointer is the same as the Mu memory location, it has the
same effect as accessing the corresponding Mu memory location.
......@@ -420,7 +420,7 @@ All prefixes of a memory location have the same beginning.
The ``REFCAST`` instruction or the ``refcast`` API function preserves the
beginning of the operand. If it casts ``iref<T1>`` to ``iref<T2>``, the result
is an internal reference to the memory location of type ``T2`` at the same
beginning. (see `Instruction Set <instruction-set.rest>`__)
beginning. (see `Instruction Set <instruction-set.rst>`__)
Array Rule
----------
......
......@@ -297,13 +297,13 @@ Changes in the Mu IR and the API introduced by the native interface
* ``uptr < T >``
* ``ufuncptr < sig >``
See `Type System <type-system.rest>`__
See `Type System <type-system.rst>`__
**New top-level definitions**:
* function exposing definition
See `Mu IR <uvm-ir.rest>`__.
See `Mu IR <ir.rst>`__.
**New instructions**:
......@@ -314,8 +314,8 @@ See `Mu IR <uvm-ir.rest>`__.
* ``@uvm.native.unexpose``
* ``@uvm.native.get_cookie``
See `Instruction Set <instruction-set.rest>`__ and `Common Instructions
<common-insts.rest>`__.
See `Instruction Set <instruction-set.rst>`__ and `Common Instructions
<common-insts.rst>`__.
**Modified instructions**:
......@@ -345,7 +345,7 @@ example:
* ``%result = CMPXCHG PTR ACQ_REL ACQUIRE <@T> %ptr_to_T %expected %desired``
* ``%old_val = ATOMICRMW ADD PTR SEQ_CST <@T> %ptr_to_T %rhs``
See `Instruction Set <instruction-set.rest>`__.
See `Instruction Set <instruction-set.rst>`__.
**New API functions**:
......
......@@ -133,7 +133,7 @@ Mu is agnostic of the type hierarchy in high-level languages, but the client can
implement its language-specific type system and run-time type information on top
of the Mu type system.
See `Type System <type-system.rest>`__ for more details.
See `Type System <type-system.rst>`__ for more details.
The Mu Instruction Set
-----------------------
......@@ -157,8 +157,8 @@ cannot handle.
There are also instructions for handling stack and threads.
See `Instruction Set <instruction-set.rest>`__ and `Common Instructions
<common-insts.rest>`__ for more details.
See `Instruction Set <instruction-set.rst>`__ and `Common Instructions
<common-insts.rst>`__ for more details.
The Mu Client Interface
------------------------
......@@ -181,7 +181,7 @@ The client also handles trap events generated by the Mu IR code. The client can
introspect the selected local variables on the stack and perform on-stack
replacement (i.e. OSR. Discussed later.)
See `Client Interface <uvm-client-interface.rest>`__ for more details.
See `Client Interface <api.rst>`__ for more details.
Unsafe Native Interface
-----------------------
......@@ -198,7 +198,7 @@ This interface is different from the client API. The main purpose is to
implement the system-interfacing part of the high-level language, such as the IO
and the networking library.
See `Native Interface <native-interface.rest>`__ for more details.
See `Native Interface <native-interface.rst>`__ for more details.
Multi-Threading
---------------
......@@ -216,8 +216,8 @@ Linux kernel. It is the client's responsibility to implement mutex locks,
semaphores, conditions, barriers and so on using atomic memory accesses and the
futex.
See `Threads and Stacks <threads-stacks.rest>`__ for details about threads and
`Memory Model <memory-model.rest>`__ for the Mu memory model.
See `Threads and Stacks <threads-stacks.rst>`__ for details about threads and
`Memory Model <memory-model.rst>`__ for the Mu memory model.
The Swap-stack Operation
------------------------
......@@ -243,7 +243,7 @@ It also allows the client to implement its own light-weight
thread. This is particularly useful for languages with massively many threads
(e.g. Erlang).
See `Threads and Stacks <threads-stacks.rest>`__ for details.
See `Threads and Stacks <threads-stacks.rst>`__ for details.
Function Redefinition
---------------------
......@@ -265,8 +265,8 @@ If a function has zero versions, it is "undefined". Calling such a function will
"trap" to the client. Such functions behave like "stubs" and this gives the
client a chance to implement lazy code/class loading.
See `Intermediate Representation <uvm-ir.rest.rest>`__ for the definition of
functions and versions, and see `Client Interface <uvm-client-interface.rest>`__ for
See `Intermediate Representation <ir.rst>`__ for the definition of
functions and versions, and see `Client Interface <api.rst>`__ for