portability.rest 10.3 KB
Newer Older
1 2 3 4 5
==============
Portability
==============

As both a thin layer over the hardware and an abstraction over concurrency, JIT
Kunshan Wang's avatar
Kunshan Wang committed
6 7
compiling and GC, Mu must strike a balance between portability and the ability
to exploit platform-specific features. Thus Mu is designed in such a way that
8 9 10

1. There is a basic set of types and instructions that have common and defined
   behaviours and reasonably good performance on all platforms.
Kunshan Wang's avatar
Kunshan Wang committed
11 12
2. Mu also includes platform-specific instructions. These instructions are
   either defined by this Mu specification or extended by Mu implementations.
13

Kunshan Wang's avatar
Kunshan Wang committed
14
In this chapter, **required** features must be implemented by Mu
15 16 17 18 19
implementation and **optional** features may or may not be implemented. However,
if an optional feature is implemented, it must behave as specified.

    NOTE: Although "behaving as specified", the implementation can still reject
    some inputs in a compliant way. For example, if an array type is too large,
Kunshan Wang's avatar
Kunshan Wang committed
20 21
    Mu still needs to accept the Mu IR that contains such a type, but may always
    refuse to allocate such a type in the memory.
22

23 24 25 26 27 28
The platform-independent part of the native interface is a required component of
the Mu spec, but the platform-dependent parts are not. There will be things
which are "required but has implementation-defined behaviours". In this case, Mu
must not reject IR programs that contain such constructs, but each
implementation may do different things.

29 30 31 32
Type System
===========

The ``int`` type of lengths 1, 8, 16, 32, and 64 are required. ``int`` of 6 and
Kunshan Wang's avatar
Kunshan Wang committed
33 34
52 bits are required if Mu also implements the ``tagref64`` type. Other lengths
are optional.
35 36 37 38 39 40

Both ``float`` and ``double`` are required.

The vector types ``vector<int<32> 4>``, ``vector<float 4>`` and ``vector<double
2>`` are required. Other vector types are optional.

Kunshan Wang's avatar
Kunshan Wang committed
41 42 43 44 45
    NOTE: Even though required to be accepted by Mu, they are not required to be
    implemented using hardware-provided vector instructions or vector registers
    of the exact same length. They can be implemented totally with scalar
    operations and general-purpose registers or memory, or implemented using
    different hardware vector sizes, larger or smaller.
46 47 48 49 50 51 52

Reference types ``ref<T>``, ``iref<T>`` and ``weakref<T>`` are required if ``T``
is implemented. Otherwise optional.

A struct type ``struct<...>`` are required if it has at most 256 fields and all
of its field types are implemented. Otherwise optional.

Kunshan Wang's avatar
Kunshan Wang committed
53 54
An array type ``array<T n>`` is required if T is implemented and n is less than
2^64. Otherwise optional.
55

Kunshan Wang's avatar
Kunshan Wang committed
56
    NOTE: This implies Mu must accept array types of up to 2^64-1 elements.
57 58 59
    However, arrays must be in the memory. Whether such an array can be
    successfully allocated is a different story.

60
A hybrid type ``hybrid<Fs V>`` is required if all fields in ``Fs`` and ``V`` are
61 62 63 64
implemented.

The void type ``void`` is required.

Kunshan Wang's avatar
Kunshan Wang committed
65
A function type ``funcref<Sig>`` is required if ``Sig`` is implemented.
66

Kunshan Wang's avatar
Kunshan Wang committed
67
The opaque types ``threadref`` and ``stackref`` are both required.
68 69 70 71 72 73 74

The tagged reference type ``tagref64`` is optional.

A function signature ``R (P0 P1 ...)`` is required if all of its parameter types
and its return type are implemented and there are at most 256 parameters.
Otherwise optional.

Kunshan Wang's avatar
Kunshan Wang committed
75
Pointer types ``uptr<T>`` and ``ufuncptr<sig>`` are required for required and
76 77 78
native-safe types ``T`` and signatures ``sig``. Both are represented as
integers, but their lengths are implementation-defined.

79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94
Constants
=========

An integer constant of type ``T = int<n>`` is required if T is implemented and n
is at most 64.

    NOTE: The binary representation currently only defines 64-bit literals. This
    is subject to extension.

Float and double constants are required.

A struct constant is required if constants for all of its fields are
implemented.

All NULL constants are required.

95 96 97
Pointer constants are required, but the implementation defines the length of
them.

98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116
Instructions
============

All integer binary operations and comparisons are required for ``int`` of length
8, 16, 32, 64 and required integer vector types, and optional for other integer
lengths or integer vector types. All floating-point binary operations and
comparisons are required for all floating point types and required floating
point vector types, and optional for other floating point vector types.

In the event of signed and unsigned integer overflow in binary operations, the
result is truncated to the length of the operand type.

Divide-by-zero caused by ``UDIV`` and ``SDIV`` results in exceptional control
flows. The result of signed overflow by ``SDIV`` is the left-hand-side.

    NOTE: -0x80000000 / -1 == -0x80000000 for signed 32-bit int.

For shifting instructions ``SHL``, ``LSHR`` and ``ASHR`` for integer type
``int<n>``, only the lowest ``m`` bits of the right-hand-side are used, where
Michael Norrish's avatar
Michael Norrish committed
117
``m`` is the smallest integer that ``2^m`` >= ``n``.
118

119 120 121
Conversions instructions are required between any two implemented types that can
be converted. Specifically, given two types T1 and T2 and a conversion operation
CONVOP, if both T1 and T2 are implemented and they satisfied the requirement of
Kunshan Wang's avatar
Kunshan Wang committed
122
the ``T1`` and ``T2`` parameters of CONVOP (see `<instruction-set.rest>`__), then the
123
CONVOP operation converting from T1 to T2 is required.
124

Kunshan Wang's avatar
Kunshan Wang committed
125 126 127 128 129
Binary floating point operations round to nearest and round ties to even.
Conversions involving floating point numbers round towards zero except
converting from floating point to integer, in which case, round towards zero and
the range is clamped to that of the result type and NaN is converted to 0.
Binary operations, comparisons and conversions involving floating point numbers
130
never raise exceptions or hardware traps.  *[JVM behaviour]*
131 132 133 134

Switch is required for the operand type of ``int`` of length 8, 16, 32 and 64.
Otherwise optional.

Kunshan Wang's avatar
Kunshan Wang committed
135
Calling a function whose value is ``NULL`` is undefined behaviour.
136

137 138
Throwing exceptions across native frames has implementation-defined behaviour.

Kunshan Wang's avatar
Kunshan Wang committed
139
Stack overflow when calling a function results in taking the exceptional control
140
flow and the exceptional parameter instruction receives ``NULL``.
141

142 143 144 145
``EXTRACTELEMENT`` and ``INSERTELEMENT`` is required for all implemented vector
types and integer types. ``SHUFFLEELEMENT`` is required if the source vector
type, the mask vector type and the result vector type are all implemented.

146 147 148 149 150 151 152
All memory allocation instructions ``NEW``, ``NEWHYBRID``, ``ALLOCA`` and
``ALLOCAHYBRID`` are allowed to result in error, in which case the exceptional
control flow is taken.

    NOTE: This is for out-of-memory error and other errors.

The ``GETELEMIREF`` and ``SHIFTIREF`` instructions accept any integer type as
Kunshan Wang's avatar
Kunshan Wang committed
153 154 155 156
the index or offset type. The index and the offset are treated as signed. When
these two instructions result in a reference beyond the size of the actual array
in the memory, they have undefined behaviours.

157 158 159
``GETVARPARTIREF`` has undefined behaviour if the hybrid has zero elements in
its variable part.

Kunshan Wang's avatar
Kunshan Wang committed
160
All memory addressing instructions ``GETIREF``, ``GETFIELDIREF``,
161
``GETELEMIREF``, ``SHIFTIREF`` and ``GETVARPARTIREF`` give
162 163 164
undefined behaviour when applied to ``NULL`` references. But when applied to
pointers, these instructions calculates the result by calculating the offset
according to the memory layout, which is implementation-defined.
165 166

All memory access instructions ``LOAD``, ``STORE``, ``CMPXCHG`` and
167 168 169 170 171
``ATOMICRMW`` that access the ``NULL`` references take the exceptional control
flow. If they access an invalid memory location (this include the case when the
stack frame that contains a stack cell created by ``ALLOCA`` is popped and a
reference to it becomes a dangling reference), then they have undefined
behaviours.
Kunshan Wang's avatar
Kunshan Wang committed
172

173 174
Accessing a memory location which represents a type different from the type
expected by the instruction gives undefined behaviour.
175

176 177 178 179 180 181 182
Accessing the memory via a pointer behaves as if accessing via an ``iref`` if
the byte region represented by the pointer overlaps with the mapped (pinned)
memory region of the Mu memory location. It behaves as if updating the memory
byte-by-byte (not atomically) when all bytes in the byte region pointed by the
pointer are part of some Mu memory locations. Otherwise such memory access has
implementation-defined behaviours.

183 184 185
The following types are required for both non-atomic and atomic ``LOAD`` and
``STORE`` for all implemented ``T`` and ``Sig``: ``int<8>``, ``int<16>``,
``int<32>``, ``int<64>``, ``float``, ``double``, ``ref<T>``, ``iref<T>``,
Kunshan Wang's avatar
Kunshan Wang committed
186 187
``weakref<T>``, ``funcref<Sig>``, ``threadref``, ``stackref``, ``uptr<T>`` and
``ufuncptr<Sig>``.
188 189 190

The following types are required for non-atomic ``LOAD`` and ``STORE``:
``vector<int<32> 4>``, ``vector<float 4>`` and ``vector<double 2>``.
191

Kunshan Wang's avatar
Kunshan Wang committed
192 193 194
``int<32>``, ``int<64>``, ``ref``, ``iref``, ``weakref``, ``funcref``,
``threadref``, ``stackref``, ``uptr`` and ``ufuncptr`` are required for
``CMPXCHG`` and the ``XCHG`` operation of the ``ATOMICRMW`` instruction. 
195 196 197

``int<32>`` and ``int<64>`` are required for all ``ATOMICRMW`` operations.

198 199 200
If ``tagref64`` is implemented, it is required for both atomic and non-atomic
``LOAD`` and ``STORE``, and the ``XCHG`` operation of the ``ATOMICRMW``
instruction.
201 202 203

Other types are optional for ``CMPXCHG`` and any subset of ``ATOMICRMW``
operations.
204

Kunshan Wang's avatar
Kunshan Wang committed
205
One atomic Mu instruction does not necessarily correspond to exactly one
206 207
machine instruction. So some atomic read-modify-write operations can be
implemented using ``CMPXCHG`` or load-link store-conditional constructs.
208

209 210
``CCALL`` is required, but the behaviour is implementation-defined. The
available calling conventions are implementation-defined.
211

212 213
``@uvm.new_stack`` and ``NEWTHREAD`` is allowed to result in error, in which
case the exceptional control flow is taken.
214 215 216

The availability of ``COMMINST`` is specified in the next section.

Kunshan Wang's avatar
Kunshan Wang committed
217 218
In any cases when an error occurs and the control flow is expected to transfer
to the exceptional control flow, but the exception clause is not supplied, then
219
it gives undefined behaviours.
220 221 222 223 224 225 226

All instructions whose availability is not explicitly specified above are
required for all types and signatures that are implemented and suitable.

Common Instructions
===================

227
Required only when ``tagref64`` is implemented:
228 229 230 231 232 233 234 235 236 237 238 239

* @uvm.tr64.is_fp
* @uvm.tr64.is_int
* @uvm.tr64.is_ref
* @uvm.tr64.to_fp
* @uvm.tr64.to_int
* @uvm.tr64.to_ref
* @uvm.tr64.to_tag
* @uvm.tr64.from_fp
* @uvm.tr64.from_int
* @uvm.tr64.from_ref

240 241
All other common instructions are always required.

Kunshan Wang's avatar
Kunshan Wang committed
242
The Mu implementation may add common instructions.
243 244

.. vim: tw=80