This document specifies Common Instructions.
Common Instructions are instructions that have a common format and are
used with the COMMINST
super instruction. They have:
- An ID and a name. (This means, they are identified. See uvm-ir.rest.)
- A flag list.
- A type parameter list.
- A value parameter list.
- An optional exception clause.
- A possibly empty (which means optional) keep-alive clause.
Common instructions are a mechanism to extend the Mu IR without adding new instructions or changing the grammar.
NOTE: Common instructions were named "intrinsic function" in previous versions of this document. The name was borrowed from the LLVM. However, the common instructions in Mu are quite different from the usual concept of intrinsic functions.
Intrinsic functions usually mean a kind a function that is understood directly by the compiler. The C function
memcpy
is considered an intrinsic function by some compilers. In JikesRVM, methods of theMagic
class are a kind of intrinsic functions. They appear like ordinary functions in the language and bypass all front-end tools including the C parser and javac, but they are understood by the backend. Their purpose is to perform tasks that cannot be expressed by the high-level programming language, including direct raw memory access in Java.Common instructions only differ from ordinary Mu instructions in that they have a common format and are called by the
COMMINST
super instruction. The purpose is to add more instructions to the Mu IR without having to modify the parser.Common instructions are not Mu functions and cannot be called by the
CALL
instruction, nor can it be directly used from the high-level language that the client implements. The Mu client must understand common instructions because it is the only source of IR code of Mu. That is to say, there is no way any higher-level program can express anything which Mu knows but the client does not. For special high-level language functions that cannot be directly implemented in the high-level programming language, like the methods in thejava.lang.Thread
class, the client must implement those special high-level language functions in "ordinary" Mu IR code, which may or may not involve common instructions. For example, creating a thread is a "magic" in Java, but it is not more special than executing an instruction (NEWTHREAD
) in Mu. Some Java libraries require Mu to make aCCALL
to some C functions which are provided by the JVM, and they slip under the level of Mu. But Mu and the client always know the fact that "it call C function" and it is not magic.
This document uses the following notation:
[id]@name [F1 F2 ...] < T1 T2 ... > <[ sig1 sig2 ... ]> ( p1:t1, p2:t2, ... ) excClause KEEPALIVE -> RTs
id
is the ID and@name
is the name.[F1 F2 ...]
is a list of flag parameters.[T1 T2 ...]
is a list of type parameters. The users pass types into the common instruction via this list.<[ sig1 sig2 ... ]>
is a list of function signature parameters.(p1:t1, p2:t2, ...)
is a list of pairs of symbolic name and type. It is the value parameter list with the type of each parameter. The user only passes values via this list, and the types are only parts of the documentation.
If any of the above list is omitted in this document, it means the respective common instruction does not take that kind of parameters.
If excClause
or KEEPALIVE
are present, they mean that the common
instruction accepts exception clause or keepalive clause, respectively.
Otherwise the common instruction does not branch to exception destinations nor
support any keep-alive variables.
RTs
are the return types. If the return type is omitted, it means it
produces no results (equivalent to -> ()
).
The names of many common instructions are grouped by prefixes, such as
@uvm.tr64.
. In this document, their common prefixes may be omitted in their
descriptions when unambiguous.
[0x201]@uvm.new_stack <[sig]> (%func: funcref<sig>) -> stackref
Create a new stack with %func
as the stack-bottom function. %func
must
have signature sig
. Returns the stack reference to the new stack.
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.
[0x202]@uvm.kill_stack (%s: stackref)
Destroy the given stack %s
. The stack %s
must be in the READY state
and will enter the DEAD state.
[0x203]@uvm.thread_exit
Stop the current thread and kill the current stack. The current stack will enter the DEAD state. The current thread stops running.
[0x204]@uvm.current_stack -> stackref
Return the current stack.
[0x205]@uvm.set_threadlocal (%ref: ref<void>)
Set the thread-local object reference of the current thread to %ref
.
[0x206]@uvm.get_threadlocal -> ref<void>
Return the current thread-local object reference of the current thread.
[0x211]@uvm.tr64.is_fp (%tr: tagref64) -> int<1> [0x212]@uvm.tr64.is_int (%tr: tagref64) -> int<1> [0x213]@uvm.tr64.is_ref (%tr: tagref64) -> int<1>
is_fp
checks if%tr
holds an FP number.is_int
checks if%tr
holds an integer.is_ref
checks if%tr
holds a reference.
Return 1 or 0 for true or false.
[0x214]@uvm.tr64.from_fp (%val: double) -> tagref64 [0x215]@uvm.tr64.from_int (%val: int<52>) -> tagref64 [0x216]@uvm.tr64.from_ref (%ref: ref<void>, %tag: int<6>) -> tagref6
from_fp
creates atagref64
value from an FP number%val
.from_int
creates atagref64
value from an integer%val
.from_ref
creates atagref64
value from a reference%ref
and the integer tag%tag
.
Return the created tagref64
value.
[0x217]@uvm.tr64.to_fp (%tr: tagref64) -> double [0x218]@uvm.tr64.to_int (%tr: tagref64) -> int<52> [0x219]@uvm.tr64.to_ref (%tr: tagref64) -> ref<void> [0x21a]@uvm.tr64.to_tag (%tr: tagref64) -> int<6>
to_fp
returns the FP number held by%tr
.to_int
returns the integer held by%tr
.to_ref
returns the reference held by%tr
.to_tag
returns the integer tag held by%tr
that accompanies the reference.
They have undefined behaviours if %tr
does not hold the value of the
expected type.
TODO: Should provide enough math functions to support:
- Ordinary arithmetic and logical operations that throw exceptions when overflow. Example: C# in checked mode,
java.lang.Math.addOvf
added in Java 1.8.- Floating point math functions. Example: trigonometric functions, testing NaN, fused multiply-add, ...
It requires some work to decide a complete list of such functions. To work around the limitations for now, please call native functions in libc or libm using
CCALL
.
See threads-stacks.rest for high-level descriptions about Futex.
[0x220]@uvm.futex.wait <T> (%loc: iref<T>, %val: T) -> int<32> [0x221]@uvm.futex.wait_timeout <T> (%loc: iref<T>, %val: T, %timeout: int<64>) -> int<32>
T
must be an integer type.
wait
and wait_timeout
verify if the memory location %loc
still
contains the value %val
and then put the current thread to the waiting queue
of memory location %loc
. If %loc
does not contain %val
, return
immediately. These instructions are atomic.
wait
waits indefinitely.wait_timeout
has an extra%timeout
parameter which is a 64-bit unsigned integer that represents a time in nanoseconds. It specifies the duration of the wait.
Both instructions are allowed to spuriously wake up.
They return a signed integer which indicates the result of this call:
- 0: the current thread is woken.
- -1: the memory location
%loc
does not contain the value%val
. - -2: spurious wakeup.
- -3: timeout during waiting (
wait_timeout
only).
[0x222]@uvm.futex.wake <T> (%loc: iref<T>, %nthread: int<32>) -> int<32>
T
must be an integer type.
wake
wakes N threads in the waiting queue of the memory location %loc
.
This instruction is atomic.
N is the minimum value of %nthread
and the actual number of threads in the
waiting queue of %loc
. %nthread
is signed. Negative %nthread
has
undefined behaviour.
It returns the number of threads woken up.
[0x223]@uvm.futex.cmp_requeue <T> (%loc_src: iref<T>, %loc_dst: iref<T>, %expected: T, %nthread: int<32>) -> int<32>
T
must be an integer type.
cmp_requeue
verifies if the memory location %loc_src
still contains the
value %expected
and then wakes up N threads from the waiting queue of
%loc_src
and move all other threads in the waiting queue of %loc_src
to
the waiting queue of %loc_dst
. If %loc_src
does not contain the value
%expected
, return immediately. This instruction is atomic.
N is the minimum value of %nthread
and the actual number of threads in the
waiting queue of %loc
. %nthread
is signed. Negative %nthread
has
undefined behaviour.
It returns a signed integer. When the %loc_src
contains the value of
%expected
, return the number of threads woken up; otherwise return -1.
[0x230]@uvm.kill_dependency <T> (%val: T) -> T
Return the same value as %val
, but %val
does not carry a dependency to
the return value.
NOTE: This is supposed to free the compiler from keeping dependencies in some performance-critical cases.
[0x240]@uvm.native.pin <T> (%opnd: T) -> uptr<U> [0x241]@uvm.native.unpin <T> (%opnd: T)
T must be ref<U>
or iref<U>
for some U.
pin
adds one instance of the reference%opnd
to the pinning multiset of the current thread. Returns the mapped pointer to the bytes for the memory location. If T isref<U>
, it is equivalent to pinning the memory location of the whole object (as returned by theGETIREF
instruction). If opnd isNULL
, the result is a null pointer whose address is 0.unpin
removes one instance of the reference%opnd
from the pinning multiset of the current thread. It has undefined behaviour if no such an instance exists.
[0x242]@uvm.native.expose [callconv] <[sig]> (%func: funcref<sig>, %cookie: int<64>) -> U
callconv is a platform-specific calling convention flag. U is determined by the calling convention and sig.
expose
exposes a Mu function func as a value according to the calling
convention callConv with cookie cookie.
Example:
.funcdef @foo VERSION ... <@foo_sig> (...) { ... } %ev = COMMINST @uvm.native.expose [#DEFAULT] <[@foo_sig]>
[0x243]@uvm.native.unexpose [callconv] (%value: U)
callconv is a platform-specific calling convention flag. U is determined by the calling convention.
unexpose
removes the exposed value.
[0x244]@uvm.native.get_cookie () -> int<64>
If a Mu function is called via its exposed value, this instruction returns the attached cookie. Otherwise it returns an arbitrary value.
These are additional instructions that enables Mu IR programs to behave like a client.
Some types and signatures are pre-defined. They are always available. Note that the following are not strict text IR syntax because some types are defined in line:
.typedef @uvm.meta.bytes = hybrid <int<64> int<8>> // ID: 0x260 .typedef @uvm.meta.bytes.r = ref<@uvm.meta.bytes.r> // ID: 0x261 .typedef @uvm.meta.refs = hybrid <int<64> ref<void>> // ID: 0x262 .typedef @uvm.meta.refs.r = ref<@uvm.meta.refs.r> // ID: 0x263 .funcsig @uvm.meta.trap_handler.sig = (stackref int<32> ref<void>) -> () // ID: 0x264
In bytes
and refs
, the fixed part is the length of the variable part.
bytes
represents a byte array. ASCII strings are also represented this way.
[0x250]@uvm.meta.id_of (%name: @uvm.meta.bytes.r) -> int<32> [0x251]@uvm.meta.name_of (%id: int<32>) -> @uvm.meta.bytes.r
id_of
converts a textual Mu name%name
to the numerical ID. The name must be a global name.name_of
converts the ID%id
to its corresponding name. If the name does not exist, it returnsNULL
. The returned object must not be modified.
They have undefined behaviours if the name or the ID in the argument do not
exist, or %name
is NULL
.
[0x252]@uvm.meta.load_bundle (%buf: @uvm.meta.bytes.r) [0x253]@uvm.meta.load_hail (%buf: @uvm.meta.bytes.r)
load_bundle
and load_hail
loads Mu IR bundles and HAIL scripts,
respectively. %buf
is the content.
TODO: These comminsts should be made optional, and the IR Builder API should be provided as comminsts, too.
[0x254]@uvm.meta.new_cursor (%stack: stackref) -> framecursorref [0x255]@uvm.meta.next_frame (%cursor: framecursorref) [0x256]@uvm.meta.copy_cursor (%cursor: framecursorref) -> framecursorref [0x257]@uvm.meta.close_cursor (%cursor: framecursorref)
In all cases, cursor
and stack
cannot be NULL
.
new_cursor
allocates a frame cursor, referring to the top frame of%stack
. Returns the frame cursor reference.next_frame
moves the frame cursor so that it refers to the frame below its current frame.copy_cursor
allocates a frame cursor which refers to the same frame as%cursor
. Returns the frame cursor reference.close_cursor
deallocates the cursor.
[0x258]@uvm.meta.cur_func (%cursor: framecursorref) -> int<32> [0x259]@uvm.meta.cur_func_Ver (%cursor: framecursorref) -> int<32> [0x25a]@uvm.meta.cur_inst (%cursor: framecursorref) -> int<32> [0x25b]@uvm.meta.dump_keepalives (%cursor: framecursorref) -> @uvm.meta.refs.r
These functions operate on the frame referred by %cursor
. In all cases,
%cursor
cannot be NULL
.
cur_func
returns the ID of the frame. Returns 0 if the frame is native.cur_func_ver
returns the ID of the current function version of the frame. Returns 0 if the frame is native, or the function of the frame is undefined.cur_inst
returns the ID of the current instruction of the frame. Returns 0 if the frame is just created, its function is undefined, or the frame is native.dump_keepalives
dumps the values of the keep-alive variables of the current instruction in the frame. If the function is undefined, the arguments are the keep-alive variables. Cannot be used on native frames. The return value is a list of object references, each of which refers to an object which has type T and contains value v, where T and v are the type and the value of the corresponding keep-alive variable, respectively.
[0x25c]@uvm.meta.pop_frames_to (%cursor: framecursorref) [0x25d]@uvm.meta.push_frame <[sig]> (%stack: stackref, %func: funcref<sig>)
%cursor
, %stack
and %func
must not be NULL
.
pop_frames_to
pops all frames above%cursor
.push_frame
creates a new frame on top of the stack%stack
for the current version of the Mu function%func
.%func
must have the signaturesig
.
[0x25e]@uvm.meta.enable_watchpoint (%wpid: int<32>) [0x25f]@uvm.meta.disable_watchpoint (%wpid: int<32>)
enable_watchpoint
enables all watchpoints of watchpoint ID%wpid
.disenable_watchpoint
disables all watchpoints of watchpoint ID%wpid
.
[0x260]@uvm.meta.set_trap_handler (%handler: funcref<@uvm.meta.trap_handler.sig>, %userdata: ref<void>)
This instruction registers a trap handler. %handler
is the function to be
called and %userdata
will be their last argument when called.
This instruction overrides the trap handler registered via the C-based client API.
A trap handler takes three parameters:
- The stack where the trap takes place.
- The watchpoint ID, or 0 if triggered by the
TRAP
instruction. - The user data, which is provided when registering.
A trap handler is run by the same Mu thread that caused the trap and is executed on a new stack.
A trap handler usually terminates by either executing the @uvm.thread_exit
instruction (probably also kill the old stack before exiting), or SWAPSTACK
back to another stack while killing the stack the trap handler was running on.
These additional instructions are not dynamic. Unlike the C-based API, these
instructions do not use handles. Arguments, such as the additional arguments of
push_frame
are also statically typed. If the client needs dynamically typed
handles, it can always make its own. For example, push_frame
can be wrapped
by a Mu function which takes a dynamic argument list, checks the argument types,
and executes a static @uvm.meta.push_frame
instruction on the unboxed
values.
Some dynamic lookups, such as looking up constants by ID, are not available,
either. It can be worked around by maintaining a HashMap<id,value>
(in the
form of Mu IR programs) which is updated with each bundle loading. In other
words, if the client does not maintain such a map, Mu will have to maintain it
for the client.