Commit 39b629ad authored by Kunshan Wang's avatar Kunshan Wang

Clarification.

Not changing semantics, but changed the wording to make it clearer.

- Provided an object hierarchy of objects in a Mu IR bundle. This
  describes the "has many" and "refers to" relations between things in a
  bundle.

- Clarify what are "top-level entities". Specifically, "functions" are,
  but "function versions" are not. Stopped using "top-level definitions"
  because "definition" is too text-oriented. The API functions create
  entities.

- Stopped using the term "declaring a function", but use "creating a
  function" and "creating a function version" instead. Now "undefined
  function" and "defined function" simply refers to functions with 0
  versions and functions with 1+ versions, respectively.

- Explicitly state the "function version lookup" when a function is
  executed.
parent b96142cf
......@@ -33,8 +33,8 @@ How to start a Mu micro VM instance or a client is implementation-specific.
The Mu specification defines some types for using with common instructions, such
as ``@uvm.meta.byteref``. These types are always available. Whether other types,
signatures, constants, global cells or functions are already defined, declared
or exposed, or whether any Mu objects, stacks or Mu threads already created is
signatures, constants, global cells, functions or exposed functions already
exist, or whether any Mu objects, stacks or Mu threads already created is
implementation-specific. When boot images are used to initialise the micro VM,
the micro VM will contain the contents of the boot image, but may still contain
implementation-specific extra entities.
......
......@@ -101,7 +101,7 @@ The stack-bottom frame is in the state **READY<Ts>**, where *Ts* are the
parameter types of ``%func``.
This instruction continues exceptionally if Mu failed to create the stack. The
exception parameter receives NULL.
exceptional parameter receives NULL.
::
......
......@@ -92,6 +92,8 @@ SSA variable may hold different values in different contexts at different times.
* Parameter
* Instruction result
.. _global-variable:
A **global SSA variable** is valid in the whole Mu instance after it is defined.
Their values never change.
......@@ -2117,7 +2119,7 @@ instruction continues normally. Specifically, ``WATCHPOINT`` branches to the
When rebinding with an exception, the ``TRAP`` or ``WATCHPOINT`` continues
exceptionally. Specifically, ``WATCHPOINT`` branches to the *exc* destination
where the exception is received by the exception parameter. When the exception
where the exception is received by the exceptional parameter. When the exception
clause of ``TRAP`` or the *exc* destination of ``WATCHPOINT`` is absent, the
exception is thrown out of the current frame.
......@@ -2525,7 +2527,7 @@ the newly created thread. If it is omitted, the thread-local object reference
will be ``NULL``.
This instruction continues exceptionally if Mu cannot create the new thread. The
exception parameter receives NULL.
exceptional parameter receives NULL.
..
......
This diff is collapsed.
......@@ -213,7 +213,7 @@ function version::
b->new_func_ver(b, funcver, func, basicblocks, num_of_basicblocks);
If only the function node is defined but not any function versions, it will
*declare* a function without defining it.
create an undefined function.
Constructing a *function version* node needs a list of **basic blocks**, and
constructing each *basic block* needs a list of **instructions**. This requires
......@@ -274,7 +274,7 @@ programmer manually creates the CFG in C::
Note the ``MU_NO_ID`` in ``new_bb``. Each basic block has an optional `exception
parameter <ir.rst#exception-parameter>`__ which receives caught exceptions. The
``MU_NO_ID`` macro is just 0, which means "there is no exception parameter for
``MU_NO_ID`` macro is just 0, which means "there is no exceptional parameter for
this basic block".
Some parameters are **arrays**. Arrays are represented as the pointer to its
......@@ -475,6 +475,8 @@ the constant.
``ty`` is the type. ``symbol`` is the symbolic name, which can include ASCII
characters 33-126 but not 34.
.. _new-func:
Creating Other Top-level Nodes
------------------------------
......@@ -488,9 +490,10 @@ In all cases, ``id`` is the ID of the top-level definition.
- ``new_global_cell`` creates a global cell node. ``ty`` is its type.
- ``new_func`` creates a function node. ``sig`` is its signature. If a function
node is created but the function version node is not, it declares a function
without definition.
- ``new_func`` creates a function node. ``sig`` is its signature. Function
*versions* are created separately using ``new_func_ver``. It is allowed to
create functions without function versions, in which case the function is said
to be undefined.
- ``new_exp_func`` creates an exposed function node. ``func`` is the function to
expose; ``callconv`` is the calling convention; ``cookie`` is the cookie.
......@@ -534,7 +537,7 @@ the length of the two arrays before it.
``exc_param_id`` is **optional**. When not ``MU_NO_ID``, it is the ID of the
`excepton parameter <ir.rst#exception-parameter>` of the basic block.
The ``new_bb`` function defines its normal parameters and exception parameter
The ``new_bb`` function defines its normal parameters and exceptional parameter
nodes. These parameter nodes are not constructed separately, and can be used
directly inside the basic block as local variables.
......
......@@ -543,7 +543,7 @@ struct MuIRBuilder {
// Create global cell
void (*new_global_cell )(MuIRBuilder *b, MuID id, MuTypeNode ty);
// Create function (declaring function, not defining)
// Create function (versions are created separately)
void (*new_func )(MuIRBuilder *b, MuID id, MuFuncSigNode sig);
// Create exposed function
......
......@@ -243,13 +243,44 @@ the callee, or 0 if called directly from Mu.
context by merely the exposed function pointer.
One way to work around this problem is to generate a trampoline function
which sets the cookie and jumps to the real callee. Many different
trampolines can be made for a single Mu function, each of which supplies a
different cookie. In this case, the cookie can identify the context for the
closure.
which sets the cookie and jumps to the real callee. For example::
The simplest kind of cookie is an integer, but an object reference may also
be a candidate.
actual_mu_function:
// rax holds the cookie now
push rbp
mov rbp, rsp
...
trampoline1:
mov rax, 0x123456789abcdef0 // COOKIE1
jmp actual_mu_function
trampoline2:
mov rax, 0xfedcba9876543210 // COOKIE2
jmp actual_mu_function
Many different trampolines can be made for a single Mu function, each of
which supplies a different cookie. In this case, the cookie can identify the
context for the closure.
Each trampoline has the same size, so they can be allocated and deallocated
quite efficiently using a free-list allocator.
The simplest data type for cookie is integer. In theory, object reference
could be supported, but is difficult. On some architectures, it is
impossible to load a pointer-sized word into a register in one instruction.
Take ARMv7 as example::
trampoline3:
// Assume the object address is 0x12345678
movw r1, 0x5678
movt r1, 0x1234
br actual_mu_function
The GC must update both instructions atomically. It is easy to do with
respect to a cooperative mutator, but it is hard for uncooperative native
programs. Since the "exposed functions" are called by native programs,
"mutable" cookies (with respect to machine code) are undesirable.
Since Mu programs need special contexts to execute (such as the thread-local
memory allocation pool for the garbage collector, and the notion of the "current
......
......@@ -650,9 +650,9 @@ of the function it refers to.
A ``NULL`` value of a ``funcref`` type does not refer to any function.
NOTE: The value of a ``funcref`` may refer to a function that is declared
but not defined. The value of a ``funcref`` type does not change even the
function it refers to becomes defined or redefined.
NOTE: The value of a ``funcref`` may refer to an undefined function. The
value of a ``funcref`` type does not change even the function it refers to
becomes defined or redefined.
..
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment