portability.rst 10.2 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
Constants
=========

82
Integer constants of type ``int<n>`` is required for all implemented n.
83 84 85 86 87 88 89 90

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.

91 92 93
Pointer constants are required, but the implementation defines the length of
them.

94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112
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
113
``m`` is the smallest integer that ``2^m`` >= ``n``.
114

115 116 117
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
118
the ``T1`` and ``T2`` parameters of CONVOP (see `<instruction-set.rst>`__), then the
119
CONVOP operation converting from T1 to T2 is required.
120

Kunshan Wang's avatar
Kunshan Wang committed
121 122 123 124 125
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
126
never raise exceptions or hardware traps.  *[JVM behaviour]*
127 128 129 130

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
131
Calling a function whose value is ``NULL`` is undefined behaviour.
132

133 134
Throwing exceptions across native frames has implementation-defined behaviour.

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

138 139 140 141
``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.

142 143 144 145 146 147 148
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
149 150 151 152
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.

153 154 155
``GETVARPARTIREF`` has undefined behaviour if the hybrid has zero elements in
its variable part.

Kunshan Wang's avatar
Kunshan Wang committed
156
All memory addressing instructions ``GETIREF``, ``GETFIELDIREF``,
157
``GETELEMIREF``, ``SHIFTIREF`` and ``GETVARPARTIREF`` give
158 159 160
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.
161 162

All memory access instructions ``LOAD``, ``STORE``, ``CMPXCHG`` and
163 164 165 166 167
``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
168

169 170
Accessing a memory location which represents a type different from the type
expected by the instruction gives undefined behaviour.
171

172 173 174 175 176 177 178
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.

179 180 181
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
182 183
``weakref<T>``, ``funcref<Sig>``, ``threadref``, ``stackref``, ``uptr<T>`` and
``ufuncptr<Sig>``.
184 185 186

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

Kunshan Wang's avatar
Kunshan Wang committed
188 189 190
``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. 
191 192 193

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

194 195 196
If ``tagref64`` is implemented, it is required for both atomic and non-atomic
``LOAD`` and ``STORE``, and the ``XCHG`` operation of the ``ATOMICRMW``
instruction.
197 198 199

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

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

205 206
``CCALL`` is required, but the behaviour is implementation-defined. The
available calling conventions are implementation-defined.
207

208 209
``@uvm.new_stack`` and ``NEWTHREAD`` is allowed to result in error, in which
case the exceptional control flow is taken.
210 211 212

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

Kunshan Wang's avatar
Kunshan Wang committed
213 214
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
215
it gives undefined behaviours.
216 217 218 219 220 221 222

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

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

223
Required only when ``tagref64`` is implemented:
224 225 226 227 228 229 230 231 232 233 234 235

* @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

236 237
All other common instructions are always required.

Kunshan Wang's avatar
Kunshan Wang committed
238
The Mu implementation may add common instructions.
239 240

.. vim: tw=80