Research GitLab has introduced a user quota limitation. The new rule limits each user to have 50 Gb. The quota doesn't restrict group projects. If you have any concern with this, please talk to CECS Gitlab Admin at N110 (b) CSIT building.

ir.rst 36.6 KB
Newer Older
Kunshan Wang's avatar
Kunshan Wang committed
1 2 3
============================
Intermediate Representation
============================
Kunshan Wang's avatar
Kunshan Wang committed
4

Kunshan Wang's avatar
Kunshan Wang committed
5 6 7
Mu Intermediate Representation, or (Mu IR), is the language used by Mu to
represent a Mu program. It is the input from the client and can be executed on
Mu.
Kunshan Wang's avatar
Kunshan Wang committed
8

Kunshan Wang's avatar
Kunshan Wang committed
9 10
Mu can execute the program in any way, including interpretation, JIT compiling
or even Ahead-of-time compiling.
Kunshan Wang's avatar
Kunshan Wang committed
11

12 13
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.
14

15
This document describes the top-level of the Mu IR using the text form. There is
16
also the `IR Builder API <irbuilder.rst>`__, a programmatic interface to build
17 18
Mu IR inside a running micro VM.

19
There was a binary form, but is now deprecated. See `<ir-binary.rst>`__.
Kunshan Wang's avatar
Kunshan Wang committed
20 21 22

For the documents of the type system and the instruction set, see:

23 24
- `<type-system.rst>`__
- `<instruction-set.rst>`__
Kunshan Wang's avatar
Kunshan Wang committed
25 26 27 28

Example
=======

Kunshan Wang's avatar
Kunshan Wang committed
29
Here is an example of Mu IR in the text form::
Kunshan Wang's avatar
Kunshan Wang committed
30

Kunshan Wang's avatar
Kunshan Wang committed
31 32 33 34
    .typedef @i64 = int<64>
    .typedef @double = double
    .typedef @void = void
    .typedef @refvoid = ref<@void>
Kunshan Wang's avatar
Kunshan Wang committed
35

Kunshan Wang's avatar
Kunshan Wang committed
36 37
    .const @i64_0 <@i64> = 0
    .const @answer <@i64> = 42
Kunshan Wang's avatar
Kunshan Wang committed
38

Kunshan Wang's avatar
Kunshan Wang committed
39 40 41 42
    .typedef @some_global_data_t = struct <@i64 @double @refvoid>
    .global @some_global_data <@some_global_data_t>

    .typedef @Node = struct<@i64 @NodeRef>
Kunshan Wang's avatar
Kunshan Wang committed
43 44
    .typedef @NodeRef = ref<@Node>

45
    .funcsig @BinaryFunc = (@i64 @i64) -> (@i64)
Kunshan Wang's avatar
Kunshan Wang committed
46

Kunshan Wang's avatar
Kunshan Wang committed
47
    .funcdecl @square_sum <@BinaryFunc>
Kunshan Wang's avatar
Kunshan Wang committed
48

49 50 51
    .funcdef @gcd VERSION %v1 <@BinaryFunc> {
        %entry(<@i64> %a <@i64> %b):
            BRANCH %head(%a %b)
Kunshan Wang's avatar
Kunshan Wang committed
52

53
        %head(<@i64> %a <@i64> %b):
Kunshan Wang's avatar
Kunshan Wang committed
54
            %z = EQ <@i64> %b @i64_0
55
            BRANCH2 %z %exit(%a) %body(%a %b)
Kunshan Wang's avatar
Kunshan Wang committed
56

57
        %body(<@i64> %a <@i64> %b):
Kunshan Wang's avatar
Kunshan Wang committed
58
            %b1 = SREM <@i64> %a %b
59
            BRANCH %head(%b %b1)
Kunshan Wang's avatar
Kunshan Wang committed
60

61
        %exit(<@i64> %a):
62
            RET %a
Kunshan Wang's avatar
Kunshan Wang committed
63 64
    }

65 66
    .expose @gcd_native = @gcd < DEFAULT > @i64_0

67 68 69
Later the client can submit a function that defines a previously undefined
function or a new version of a function that replaces the old version::

70
    .funcdef @square_sum VERSION %v1 <@BinaryFunc> {
Kunshan Wang's avatar
Kunshan Wang committed
71
        // define the function (if not defined)
72 73
    }

74
    .funcdef @gcd VERSION %v2 <@BinaryFunc> {
Kunshan Wang's avatar
Kunshan Wang committed
75
        // or replace an existing version (if already defined)
76 77
    }

Kunshan Wang's avatar
Kunshan Wang committed
78 79 80
Top-level Structure
===================

Kunshan Wang's avatar
Kunshan Wang committed
81
A **bundle** is the unit of code the client sends to Mu. It contains many
82 83
**top-level definitions**. A top-level definition shall be a **type
definition**, **function signature definition**, **constant definition**,
84 85
**global cell definition**, **function definition**,  **function declaration**
or **function exposing definition**.
86 87 88

    NOTE: For Java users, a bundle is the counterpart of a Java class file.

89 90 91 92 93 94 95 96 97
Top-level definitions in a bundle can appear in any order. One top-level
definition can refer to itself or other top-level definitions that appear before
or after it, unless such cyclic reference breaks other rules.

    NOTE: For example, it is legal for a function to call itself. It is legal
    for two functions to call each other without having to declare any
    "prototype" as required by C.  But a struct type cannot contain itself as a
    field, which is explicitly forbidden.

Kunshan Wang's avatar
Kunshan Wang committed
98
Identifiers and Names
99 100
---------------------

Kunshan Wang's avatar
Kunshan Wang committed
101
Many entities in Mu are **identified**. An identified entity has an
Kunshan Wang's avatar
Kunshan Wang committed
102
identifiers (ID) and optionally a name. An identifier (ID) is a 32-bit integer.
Kunshan Wang's avatar
Kunshan Wang committed
103
A name is a string starting with a ``@`` or a ``%`` and followed by many
Kunshan Wang's avatar
Kunshan Wang committed
104
characters in the set: ``[0-9a-zA-Z_-.]``. An ID uniquely identifies an
105 106
*identified* entity. A name, if present, also uniquely identifies an
*identified* entity.
Kunshan Wang's avatar
Kunshan Wang committed
107 108 109 110

    NOTE: This specification does not define what is an "entity". An English
    dictionary would define "entity" as "a thing with distinct and independent
    existence".
111

112
IDs of entities are determined by the micro VM.
Kunshan Wang's avatar
Kunshan Wang committed
113

114 115 116 117
The text form Mu IR only refers to entities by names. When loaded into a micro
VM, the IDs of entities in a bundle is automatically generated.  When generating
IDs, Mu guarantees that there is a **mapping** from each name to its
corresponding ID, and **no two different names are mapped to the same ID**.
Kunshan Wang's avatar
Kunshan Wang committed
118

119 120
Names
~~~~~
Kunshan Wang's avatar
Kunshan Wang committed
121

Kunshan Wang's avatar
Kunshan Wang committed
122 123
A **global name** begins with ``@``. All identified entities can use global
names. Top-level definitions and the version name of functions must use global
Kunshan Wang's avatar
Kunshan Wang committed
124 125
names. Global names are valid in a whole Mu instance, not limited to a single
bundle.
Kunshan Wang's avatar
Kunshan Wang committed
126

127 128
    Example::

Kunshan Wang's avatar
Kunshan Wang committed
129 130
        .typedef    @i8 = int<8>
        .typedef    @i32 = int<32>
131
        .typedef    @i64 = int<64>
Kunshan Wang's avatar
Kunshan Wang committed
132 133 134
        .typedef    @ir_i8 = iref<@i8>
        .typedef    @ir_ir_i8 = iref<@ir_i8>

135 136
        .funcsig    @some_fun_sig = () -> ()
        .funcsig    @main_sig = (@i32 @ir_ir_i8) -> (@i32)
Kunshan Wang's avatar
Kunshan Wang committed
137 138 139 140 141 142 143

        .const      @i32_1 <@i32> = 1
        .const      @i64_0 <@i64> = 0

        .global     @errno <@i64>

        .funcdecl @some_fun <@some_fun_sig>
144

145
A **local name** begins with ``%``. Function versions, basic blocks, parameters
146
and instruction results may use local names in the IR.
147

148 149 150 151 152 153
Local names are a syntax sugar in the text-form IR. When parsed, they are
de-sugared into global names.

    NOTE: This implies that the client must use IDs or global names in the
    client API because there is no local name once a text-form bundle is loaded
    into the micro VM.
154 155 156 157 158

The global names are inferred from their syntactic parents:

- Within a function which has the global name ``@FuncGlobalName``, the function
  version ``%FV`` has global name ``@FuncGlobalName.FV``.
159

160 161 162
- Within a function version which has the global name ``@FuncVerGlobalName``, a
  basic block with local name ``%BB`` has global name ``@FuncVerGlobalName.BB``.

163 164 165
- Within a basic block which has the global name ``@BBGlobalName``, a parameter,
  an instruction or an instruction result with local name ``%LN`` has global
  name ``@BBGlobalName.LN``.
166 167

..
168 169 170

    Example::

Kunshan Wang's avatar
Kunshan Wang committed
171
        .funcsig @fac.sig = (... ...) -> (...)
172 173 174

        .funcdef @fac VERSION %v1 <@fac.sig> {
            %entry(<@i32> %n):
175
                [%first_br] BRANCH %head(%n @I32_1 @I32_1)
176 177 178

            %head(<@i32> %n <@i32> %p <@i32> %i):
                %lt = SLT <@i32> %i %n
179
                [%second_br] BRANCH2 %lt %body(%n %p %i) %exit(%p)
180 181 182 183 184 185 186 187

            %body(<@i32> %n <@i32> %p <@i32> %i):
                %p2 = MUL <@i32> %p %i
                %i2 = ADD <@i32> %i @I32_1
                BRANCH %head(%n %p2 %i2)

            %exit(<@i32> %p):
                RET %p
188
        }
Kunshan Wang's avatar
Kunshan Wang committed
189

190 191 192 193 194 195 196 197
    In the above example, the global names of the function version, the basic
    blocks and their parameters and instructions are:

    - ``%v1`` -> ``@fac.v1``

      - ``%entry`` -> ``@fac.v1.entry``

        - ``%n`` -> ``@fac.v1.entry.n``
198
        - ``%first_br`` -> ``@fac.v1.entry.first_br``
199 200

      - ``%head`` -> ``@fac.v1.head``
Kunshan Wang's avatar
Kunshan Wang committed
201

202 203 204 205
        - ``%n`` -> ``@fac.v1.head.n``
        - ``%p`` -> ``@fac.v1.head.p``
        - ``%i`` -> ``@fac.v1.head.i``
        - ``%lt`` -> ``@fac.v1.head.lt``
206
        - ``%second_br`` -> ``@fac.v1.head.second_br``
Kunshan Wang's avatar
Kunshan Wang committed
207

208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245
      - ``%body`` -> ``@fac.v1.body``

        - ``%n`` -> ``@fac.v1.body.n``
        - ``%p`` -> ``@fac.v1.body.p``
        - ``%i`` -> ``@fac.v1.body.i``
        - ``%p2`` -> ``@fac.v1.body.p2``
        - ``%i2`` -> ``@fac.v1.body.i2``
        - The anonymous ``BRANCH`` instruction: no global name.

      - ``%exit`` -> ``@fac.v1.exit``

        - ``%p`` -> ``@fac.v1.exit.p``
        - The anonymous ``RET`` instruction: no global name.

    Note that the same local name, such as ``%p``, has **different global names
    in different basic blocks**. ``@fac.v1.head.p`` and ``@fac.v1.body.p`` are
    not the same. They even seldom have the same value.

    Function versions, basic blocks, parameters and instructions can use global
    names, too. For example, instead of the previous example, it is legal to
    write::

        .funcdef @fac VERSION @fac.v1 <@fac.sig> {
            @fac.v1.entry(<@i32> @fac.v1.entry.n):
                BRANCH @fac.v1.head(<@i32> @fac.v1.entry.n <@i32> @I32_1 <@i32> @I32_1)

            @fac.v1.head(<@i32> @fac.v1.head.n <@i32> @fac.v1.head.p <@i32> @fac.v1.head.i):
                @fac.v1.head.lt = SLT <@i32> @fac.v1.head.i @fac.v1.head.n

    or even::

        .funcdef @fac VERSION @n1 <@fac.sig> {
            @n2(<@i32> @n3):
                BRANCH @n4(<@i32> @n3 <@i32> @I32_1 <@i32> @I32_1)

            @n4(<@i32> @n5 <@i32> @n6 <@i32> @n7)
                @n8 = SLT <@i32> @n7 @n5

246 247 248
Because local names are merely syntax sugar, everything that has a local name
can be identified by their global names. It is still considered a naming
conflict if two local names have the same global name.
Kunshan Wang's avatar
Kunshan Wang committed
249 250 251

..

252 253 254 255 256
    NOTE: It is useful to have local things globally identifiable, especially
    *function call sites* and *traps*. For example::

        .funcdef @foo VERSION @foo.v1 <...> {
            %entry():
257 258
                (%rv1 %rv2 %rv3) = [%the_call_site] CALL <@T1 @T2 @T3> @some_func (...)
                () = [%the_trap] TRAP <> KEEPALIVE (...)
259 260 261
                ...
        }

262 263 264
    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
265
    in *trap handlers* (see `the API <api.rst#trap-handling>`__).
Kunshan Wang's avatar
Kunshan Wang committed
266

Kunshan Wang's avatar
Kunshan Wang committed
267
Identifiers
268
~~~~~~~~~~~
Kunshan Wang's avatar
Kunshan Wang committed
269

270 271
All identifiers are global. Every ID uniquely identifies one entity in the whole
Mu instance.
272

Kunshan Wang's avatar
Kunshan Wang committed
273 274
0 is an invalid ID. IDs in the range of 1-65535 are reserved by Mu. The Mu
specification only uses 1-32767. 32768-65535 can be used by the Mu
275
implementation for extension purposes.
Kunshan Wang's avatar
Kunshan Wang committed
276

Kunshan Wang's avatar
Kunshan Wang committed
277 278 279
Type Definition
===============

280
Types and the **type constructor** syntax are documented in `<type-system.rst>`__.
Kunshan Wang's avatar
Kunshan Wang committed
281

282
A **type definition** gives a name to a type. It has the following form::
Kunshan Wang's avatar
Kunshan Wang committed
283

284
    .typedef Name = TypeCtor
Kunshan Wang's avatar
Kunshan Wang committed
285

286
where:
Kunshan Wang's avatar
Kunshan Wang committed
287

288 289
* ``Name`` is a global name for the type, and
* ``TypeCtor`` is a type constructor which defines the type.
Kunshan Wang's avatar
Kunshan Wang committed
290

291
..
Kunshan Wang's avatar
Kunshan Wang committed
292

293
    Example: The following type definition defines a simple non-recursive type::
Kunshan Wang's avatar
Kunshan Wang committed
294

295
        .typedef @i64 = int<64>
Kunshan Wang's avatar
Kunshan Wang committed
296

297
    It gives a name ``@i64`` to a 64-bit integer.
Kunshan Wang's avatar
Kunshan Wang committed
298

Kunshan Wang's avatar
Kunshan Wang committed
299 300
..

301
    Example: The following type definition defines a recursive type::
Kunshan Wang's avatar
Kunshan Wang committed
302

Kunshan Wang's avatar
Kunshan Wang committed
303 304
        .typedef @i64 = int<64>
        .typedef @Node = struct<@i64 @NodeRef>
305 306 307 308 309 310
        .typedef @NodeRef = ref<@Node>

    These define a node in a singly-linked list. The second field of the struct
    is an object reference to itself. Note that **the order of top-level
    definitions does not matter**. They can be written in any order.

Kunshan Wang's avatar
Kunshan Wang committed
311 312
..

313 314 315 316 317
    NOTE: There is no way to simply make an alias of another type. ``.typedef
    @Foo = @Bar`` is illegal because ``@Bar`` is not a type constructor. In this
    event, replacing all occurrences of ``@Foo`` with ``@Bar`` in the whole
    program is the desired approach.

Kunshan Wang's avatar
Kunshan Wang committed
318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333
..

    For C programmers: In Mu IR, types cannot be "inlined", i.e. all types
    referenced by other definitions (such as other types, constants, globals,
    functions, ...) must be defined at top-level. For example::

        .typedef @refi64 = ref<int<64>>     // WRONG. Cannot write int<64> inside.
        
        .typedef @i64 = int<64>
        .typedef @refi64 = ref<@i64>        // Right.

        %sum = FADD <double> %a %b          // WRONG. "double" is a type constructor, not a type

        .typedef @double = double
        %sum = FADD <@double> %a %b         // Right.

334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349
Function Signature Definition
=============================

A **function signature definition** gives a name to a **function signature**, or
**signature** when unambiguous. It has the following form::

    .funcsig Name = SigCtor

where:

* ``Name`` is a global name for the signature, and
* ``SigCtor`` is a function signature constructor which defines the function
  signature.

A function signature constructor has the form::

350
    (ParamTys) -> (RetTys)
351

352 353
where both ``ParamTys`` and ``RetTys`` are a list of global names separated by
spaces for the types of parameters and return values, respectively.
354

355 356
    Example: The following signature receives no parameters and return no
    values::
Kunshan Wang's avatar
Kunshan Wang committed
357

358
        .funcsig @empty_func_s = () -> ()
359

Kunshan Wang's avatar
Kunshan Wang committed
360 361
    The following signature receives a 64-bit integer and a double as parameters
    and returns an object reference to a 64-bit integer::
362

Kunshan Wang's avatar
Kunshan Wang committed
363 364 365
        .typedef @double = double
        .typedef @i64 = int<64>
        .typedef @refi64 = ref<@i64>
366
        .funcsig @some_func_s = (@i64 @double) -> (@refi64)
Kunshan Wang's avatar
Kunshan Wang committed
367

Kunshan Wang's avatar
Kunshan Wang committed
368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383
..

    For C programmers: Just like types, function signatures cannot be inlined.
    For example::

        // Asssume @i64 is defined as int<64>

        .typedef @foo_fp  = funcref<(@i64 @i64) -> (@i64)>      // WRONG.
        
        %rv = CALL <(@i64 @i64) -> (@i64)> @func (%arg1 %arg2)  // WRONG.

        .funcsig @foo_sig = (@i64 @i64) -> (@i64)
        .typedef @foo_fp  = funcref<@foo_sig>               // Right.

        %rv = CALL <@foo_sig> @func (%arg1 %arg2)           // Right.

Kunshan Wang's avatar
Kunshan Wang committed
384 385 386
Constant Definition
===================

387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409
Constants are global `SSA variables <instruction-set.rst#ssa-variables>`__ of
given values, can be used anywhere SSA variables are accepted, and cannot
change.

..

    For C programmers:

    1. In Mu, constants are just values, not part of the Mu memory. Although, in
       C, you can declare an object with the "const" decorator: ``const int a =
       42;`` and then have a pointer to it: ``const int* pa = &a;``, you cannot
       do the same in Mu. Global cells may be more appropriate if references to
       constants are ever taken.
    
    2. Just like types, constants cannot be inlined.  For example::

        // Asssume @i64 is defined as int<64>

        %b = ADD <@i64> %a 123          // WRONG. What type is 123?

        .const @I64_123 <@i64> = 123    // 123 is an @i64
        %b = ADD <@i64> %a @I64_123     // Right.

410 411
A **constant definition** has the form::

Kunshan Wang's avatar
Kunshan Wang committed
412
    .const Name <Type> = ConstCtor
413 414 415 416

where:

* ``Name`` is global name for the constant;
Kunshan Wang's avatar
Kunshan Wang committed
417
* ``Type`` is a global name for the type of the constant, and
418 419 420 421
* ``ConstCtor`` is a constant constructor.

A **constant constructor** can be the following:

422
- **integer constructor**, such as ``42``, ``0x2a``
423

424 425
- **floating point constructor**, such as ``3.14f``, ``3.14d``,
  ``bitsd(0x3ff8000000000000)``
426

427
- **list constructor**, such as ``{ @foo @bar @baz }``
428

429
- **null constructor**: ``NULL``
430

431
- **external constructor**, such as ``EXTERN "write"``
432

433 434
Integer Constructor
-------------------
435

436
**Integer constructors** are applicable to:
437

438 439
+ integer types: ``int<n>``, and
+ pointer types: ``uptr<T>``, ``ufuncptr<sig>``
Kunshan Wang's avatar
Kunshan Wang committed
440

441
The IR builder API constructs such constants using actual integers.
442

443
.. _integer-literal:
444

445 446 447 448 449 450 451 452
The text form is written as an **integer literal**, which is:
  
+ an optional sign [+-], followed by
+ an optional prefix: ``0`` or ``0x``, and
+ a sequence of digits [0-9a-fA-F].
  
A prefix 0 represents an octal number. A prefix 0x represents a hexadecimal
number. Otherwise it is a decimal number.
453

Kunshan Wang's avatar
Kunshan Wang committed
454
..
455

Kunshan Wang's avatar
Kunshan Wang committed
456
    NOTE: The client must ensure the number (integer or floating point) can be
Kunshan Wang's avatar
Kunshan Wang committed
457 458 459 460
    represented by the type, or it is an error.

..

461 462 463
    Example::
    
        .typedef @i64 = int<64>
464

465 466 467 468
        .const @oct1 <@i64> = 0
        .const @oct2 <@i64> = +01234567
        .const @dec1 <@i64> = 1234567890
        .const @hex1 <@i64> = -0x123456789abcdef0
469

470 471
        .typedef @ptri64          = uptr<@i64>
        .typedef @fpnoparamsnoret = ufuncptr<@noparamsnoret>
Kunshan Wang's avatar
Kunshan Wang committed
472

473 474 475 476
        // Address should be looked up before generating the bundle.
        .const @ptrconst <@ptri64> = 0x12345678
        .const @fpconst  <@fpnoparamsnoret> = 0x7ff00000000
        .const @nullptr  <@ptri64> = 0
Kunshan Wang's avatar
Kunshan Wang committed
477

478 479
Floating Point Constructor
--------------------------
Kunshan Wang's avatar
Kunshan Wang committed
480

481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510
**Floating point constructors** are applicable to floating point types:

+ ``float`` (if the suffix is 'f' in the text form);

+ ``double`` (if the suffix is 'd' in the text form).

The IR builder API constructs such constants using actual IEEE754 value.

The text form is written as a **floating point literal**, which can be one of
the following forms:

+ An optional sign [+-], an integral part, a dot (.), a fraction part,
  an optional exponent part and a suffix.

  * Both the integral part and the fraction part are a sequence of decimal
    digits [0-9].
  * The exponent part is ``e`` followed by an optional sign [+-] followed by a
    sequence of decimal digits [0-9].
  * The suffix is either ``f`` (for ``float``) or ``d`` (for ``double``).
  * Example: ``123.456f``, ``+123.456e789d``, ``-123.456e-789d``

+ One of ``nan``, ``+inf`` and ``-inf`` with a suffix ``f`` or ``d``.

  * Example: ``nanf``, ``-infd``

+ ``bitsf(intlit)`` or ``bitsd(intlit)`` where ``intlit`` is an `integer literal
  <integer-literal_>`__ as defined before, and the ``f`` and ``d`` represents
  ``float`` and ``double``, respectively. In the case, the resulting ``float``
  and ``double`` value has the same bit-wise representation as the 32-bit or
  64-bit integer of ``intlit``, respectively.
511 512 513

..

514
    Example::
515 516 517

        .typedef @float = float
        .typedef @double = double
518

519 520 521 522 523 524
        .const @float1 <@float> = 123.456f
        .const @float2 <@float> = +123.456e789f
        .const @float3 <@float> = -123.456e-789f
        .const @float4 <@float> = nanf
        .const @float5 <@float> = +inff
        .const @float6 <@float> = -inff
525 526 527
        .const @float7 <@float> = bitsf(0x7f800000)   // float inf
        .const @float7 <@float> = bitsf(0x7f800001)   // float nan
        
528 529 530 531 532 533
        .const @double1 <@double> = 123.456d
        .const @double2 <@double> = +123.456e789d
        .const @double3 <@double> = -123.456e-789d
        .const @double4 <@float> = nand
        .const @double5 <@float> = +infd
        .const @double6 <@float> = -infd
534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555
        .const @double7 <@float> = bitsd(0x7ff0000000000000)   // double inf
        .const @double7 <@float> = bitsd(0x7ff0000000000001)   // double nan

List Constructor
----------------

**List constructors** are applicable for composite types, but not hybrid:

+ ``struct``

+ ``array``

+ ``vector``

The IR builder API constructs such constants by providing a list of handles
to its members (other global SSA values).

In the text form, it is written as:

+ an opening brace ``{``, followed by

+ a sequence of global names of other global variables separated by spaces, and
Kunshan Wang's avatar
Kunshan Wang committed
556

557 558 559 560 561 562 563 564 565 566 567 568 569
+ a closing brace ``}``.

The sequence of names must have the same number of names as the number of
fields/elements as the type requires.

A constant must not recursively contain itself. (It is impossible to construct
recursive constants using the IR builder API.)

..

    Example::

        // simple struct
Kunshan Wang's avatar
Kunshan Wang committed
570 571 572
        .typedef @record_t = struct<@i64 @double>
        .const @record <@record_t> = {@dec1 @double1}

573
        // nested struct
Kunshan Wang's avatar
Kunshan Wang committed
574
        .typedef @nested_record_t = struct<@i64 @record_t @float>
575 576 577 578 579 580 581 582 583 584 585 586 587 588
        .const @nested_record <@nested_record_t> = {@hex1 @record @float2}

        // vector
        .typedef @4xfloat = vector <@float 4>
        .const @vec1 <@4xfloat> = { @float1 @float2 @float3 @float4 }

        // array constant
        // Not recommended to use unless intracting with native function.
        .typedef @i64ary = array<@i64 3>
        .const @constary <@i64ary> = {@oct1 @oct2 @dec1}

        // Global cells and functions are global variables, too.
        // They can be components of constants.
        .global @g1 <@i64>
Kunshan Wang's avatar
Kunshan Wang committed
589

590
        .funcsig @noparamsnoret = () -> ()
591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615
        .funcdecl @f1 <@noparamsnoret>

        .typedef @irefi64 = iref<@i64>
        .typedef @record2_t = struct<@irefi64 @some_func>

        .const @record2 <@record2_t> = {@g1 @f1}

Null constructor
----------------

**Null constructors** are applicable for all *general reference types* except
`weakref <type-system.rst#reference-types>`__:

- ``ref<T>``

- ``iref<T>``

- ``funcref<sig>``

- ``threadref``

- ``stackref``

- ``framecursorref``

616
- ``irbuilderref``
617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651

It can only have ``NULL`` value.

In the text form, it is written as the **null literal**: ``NULL``. 

..

    NOTE: ``weakref`` cannot be the type of an SSA variable, but all constants
    are SSA variables. (See `<type-system.rst>`__ and `<instruction-set.rst>`__).

..

    NOTE: The only constant of reference types is ``NULL``. The reason why Mu
    forbids constant object references is manifold:

    * To define a constant heap reference, the client must provide a reference
      to a heap object, which itself is recursively a constant heap reference.
      Even if such a reference is created, it renders a heap object immortal (as
      immortal as a global cell), which defeated the purpose of garbage
      collection.

    * When a heap object is moved, the garbage collector must update all
      existing references to the object. This makes the constant reference not
      really "constant". Extra difficulties are introduced when such references
      become immediate values in the machine code.

    The global memory is an alternative to such needs. Either store a global
    data structure in the global memory or allocate it in the heap and assign
    its reference to a global cell. In fact, the ID or the name of any global
    cell is a constant SSA variable of an internal reference to it. The ID or
    the name of a Mu function is a constant SSA variable of a ``funcref``.

..

    Example::
Kunshan Wang's avatar
Kunshan Wang committed
652

653
        .typedef @void = void
Kunshan Wang's avatar
Kunshan Wang committed
654 655 656 657 658 659
        .typedef @ref_void = ref<@void>
        .const @null_ref <@ref_void> = NULL

        .typedef @iref_void = iref<@void>
        .const @null_iref <@iref_void> = NULL

Kunshan Wang's avatar
Kunshan Wang committed
660
        .typedef @some_func = funcref<@noparamsnoret>
Kunshan Wang's avatar
Kunshan Wang committed
661 662
        .const @null_func <@some_func> = NULL

Kunshan Wang's avatar
Kunshan Wang committed
663 664
        .typedef @tref = threadref
        .const @null_tr <@tref> = NULL
Kunshan Wang's avatar
Kunshan Wang committed
665

Kunshan Wang's avatar
Kunshan Wang committed
666 667
        .typedef @sref = stackref
        .const @null_sr <@sref> = NULL
668

669 670
External Constructor
--------------------
Kunshan Wang's avatar
Kunshan Wang committed
671

672
**External constructor** are applicable for pointer types:
673

674
- ``uptr<T>``
675

676
- ``ufuncptr<T>``
677

678
In the text form, it is written as:
679

680
+ the keyword ``EXTERN``, followed by
681

682 683 684 685 686 687 688 689 690 691
+ a string literal, which is a sequence of ASCII characters surrounded by ``"``
  (code is 34).  The code of each character shall be within 33–126 inclusive,
  but not 34 (non-space printable characters except ``"``). There are no escape
  sequences. This string represents a symbolic name.

The IR builder API constructs such constants by providing the symbol, which has
the same limitation as the text form: 33-126 but not 34.

The values of such constants are implementation-defined. Usually the
implementation will resolve the symbolic names to the address of C functions.
692

Kunshan Wang's avatar
Kunshan Wang committed
693 694
..

695
    Example::
Kunshan Wang's avatar
Kunshan Wang committed
696

697 698 699 700 701 702 703
        .typedef @char    = int<8>
        .typedef @charp   = uptr<@char>
        .typedef @int     = int<32>
        .typedef @void    = void
        .typedef @voidp   = uptr<@void>
        .typedef @size_t  = int<64>
        .typedef @ssize_t = int<64>
Kunshan Wang's avatar
Kunshan Wang committed
704

705 706
        .funcsig @write.sig = (@int @voidp @size_t) -> (@ssize_t)
        .typedef @write.fp  = ufuncptr<@write.sig>
Kunshan Wang's avatar
Kunshan Wang committed
707

708
        .const @write = EXTERN "write"
Kunshan Wang's avatar
Kunshan Wang committed
709

710 711 712 713 714 715 716 717 718 719 720
        .funcsig @puts.sig = (@charp) -> (@int)
        .typedef @puts.fp  = ufuncptr<@puts.sig>

        .const @puts = EXTERN "puts"

        .funcdef @main ... <...> {
            %...(...):
                ...
                %rv = CCALL #DEFAULT <@write.fp @write.sig> @write (%fd %buf %sz)
                ...
        }
721

722 723 724 725
Global Cell Definition
======================

A **global cell definition** defines a **global cell**. A global cell is the
726
memory allocation unit in the *global memory*. See `<memory.rst>`__ for more
727 728 729
information about the global memory.

    NOTE: The global memory is the counterpart of static or global variables in
730 731
    C/C++. In Mu, global cells are also permanently pinned so that it can be
    used to interact with native programs.
732 733 734

A global cell definition has the form::

Kunshan Wang's avatar
Kunshan Wang committed
735
    .global Name <Type>
736 737

* where ``Name`` is a global name for the global cell and
Kunshan Wang's avatar
Kunshan Wang committed
738
* ``Type`` is a global name for the type of the data the global cell
739 740 741 742 743 744
  represents.

..

    Example::

Kunshan Wang's avatar
Kunshan Wang committed
745 746 747 748 749
        .typedef    @i8 = int<8>
        .typedef    @i32 = int<32>
        .const      @i32_0 <@i32> = 0

        .global @my_errno <@i32>
750

Kunshan Wang's avatar
Kunshan Wang committed
751
        .typedef @small_char_array = array<@i8 12>
752
        .global @hello_world_str <@small_char_array>
Kunshan Wang's avatar
Kunshan Wang committed
753 754
        
        // The client can populate the memory in @hello_world_str at loading time
755

756 757
        .funcdef @func VERSION ... <...> {
            %entry():
758
                %a = LOAD <@i32> @my_errno       // @my_errno has type iref<@i32>
759 760
                STORE <@i32> @my_errno @i32_0
                ...
761
        }
Kunshan Wang's avatar
Kunshan Wang committed
762

Kunshan Wang's avatar
Kunshan Wang committed
763 764 765 766 767
..

    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
768
    (load, store, ...), or indirectly via the `HAIL <hail.rst>`__ language.
Kunshan Wang's avatar
Kunshan Wang committed
769 770 771
    Beware that concurrent non-atomic access (even as a result of careless
    initialisation) may result in data race, which has undefined behaviour.

Kunshan Wang's avatar
Kunshan Wang committed
772 773 774
Function Definition and Declaration
===================================

Kunshan Wang's avatar
Kunshan Wang committed
775 776 777 778
**Functions** are callable in Mu. A function is an identified entity. A function
may have multiple versions. A **version of function** has its control flow graph
which defines how it is executed. A version of function is also an identified
entity.
Kunshan Wang's avatar
Kunshan Wang committed
779

Kunshan Wang's avatar
Kunshan Wang committed
780 781 782 783 784 785
A **function definition** defines a *version of function*. A *function version*
contains a control flow graph (CFG), but cannot be directly called. Calling a
*function* will actually call the most recent version a thread can see (see
`Bundle Loading`_ below for the exact visibility requirement).

In the text form, if a function has not been declared, a *function definition*
786 787 788
will implicitly define the *function*. In the `API
<irbuilder.rst#define-a-function>`__, *functions* and *function versions* are
created separately. The text form is::
Kunshan Wang's avatar
Kunshan Wang committed
789

790
    .funcdef Name VERSION VerName <Sig> { Body }
Kunshan Wang's avatar
Kunshan Wang committed
791

792
where:
Kunshan Wang's avatar
Kunshan Wang committed
793

794 795
* ``Name`` is a global name for the function
* ``VerName`` is a global name of this particular version of function
Kunshan Wang's avatar
Kunshan Wang committed
796
* ``Sig`` is a global name for the signature of the function
797
* ``Body`` is a sequence of instructions, constants and labels.
Kunshan Wang's avatar
Kunshan Wang committed
798

Kunshan Wang's avatar
Kunshan Wang committed
799
..
Kunshan Wang's avatar
Kunshan Wang committed
800

Kunshan Wang's avatar
Kunshan Wang committed
801
    NOTE: The VerName is required for each definition. Although calling a
Kunshan Wang's avatar
Kunshan Wang committed
802
    function will always call the most recent version, stack introspection and
Kunshan Wang's avatar
Kunshan Wang committed
803 804 805
    on-stack replacement still need to know the concrete version. Although a
    function can be redefined multiple times, existing activations in the stack
    will continue to execute their respective versions.
Kunshan Wang's avatar
Kunshan Wang committed
806

807
..
Kunshan Wang's avatar
Kunshan Wang committed
808

809
    Example::
Kunshan Wang's avatar
Kunshan Wang committed
810

Kunshan Wang's avatar
Kunshan Wang committed
811 812 813
        .typedef @i64 = int<64>
        .typedef @float = float
        .typedef @double = double
Kunshan Wang's avatar
Kunshan Wang committed
814

815
        .funcsig @ExampleSig = (@float @double) -> (@i64)
Kunshan Wang's avatar
Kunshan Wang committed
816

817
        .funcdef @example VERSION %v1 <@ExampleSig> {
818 819
            ...
        }
Kunshan Wang's avatar
Kunshan Wang committed
820

Kunshan Wang's avatar
Kunshan Wang committed
821
A **function declaration** defines a function with no versions. It has the
822
following form::
Kunshan Wang's avatar
Kunshan Wang committed
823

Kunshan Wang's avatar
Kunshan Wang committed
824
    .funcdecl Name <Sig>
Kunshan Wang's avatar
Kunshan Wang committed
825

826
where:
Kunshan Wang's avatar
Kunshan Wang committed
827

828
* ``Name`` is a global name for the function and
Kunshan Wang's avatar
Kunshan Wang committed
829
* ``Sig`` is a global name for the signature of the function.
Kunshan Wang's avatar
Kunshan Wang committed
830

831 832 833
When executing a function without version, it behaves as if it has a hidden
version defined as::

834 835
    .funcdef Name VERSION NoVersion <Sig> {
        %entry(ParamList):
836
            TRAP <> KEEPALIVE (ParamList)
837 838 839
            TAILCALL <Sig> Name (ParamList)
    }

840
That is, it will trap to the client, using all parameters as the keep-alive
841 842 843 844 845 846 847 848
variables. If the stack is ever rebound passing 0 values, it will try to
tail-call the same function (**Not necessarily the same hidden version!** It may
have been defined by the client in the trap!) using the same arguments. If an
exception is thrown when rebound, the ``TRAP`` will re-throw it to the parent
frame. The ``cur_func`` API will return the ID of the function.  This hidden
version is still not a real version, so the ``cur_func_ver`` API will return 0.
The ``TRAP`` is not a real instruction, either, so the ``cur_inst`` API will
also return 0.  ``dump_keepalives`` will dump the arguments.
849

850
It is an error to have multiple function declarations and/or function
Kunshan Wang's avatar
Kunshan Wang committed
851 852 853
definitions of the same function name in the same bundle.

It is an error to declare a function which is previously declared or defined.
Kunshan Wang's avatar
Kunshan Wang committed
854

Kunshan Wang's avatar
Kunshan Wang committed
855
See the `Bundle Loading`_ section for the semantics of bundle loading and
Kunshan Wang's avatar
Kunshan Wang committed
856
function redefinition.
Kunshan Wang's avatar
Kunshan Wang committed
857

858 859
.. _exception-parameter:

Kunshan Wang's avatar
Kunshan Wang committed
860 861 862
Function Body
=============

863
A function definition has a **function body**.
Kunshan Wang's avatar
Kunshan Wang committed
864

865 866 867 868 869 870 871 872 873 874 875 876 877 878 879
A function body has many **basic block** enclosed between ``{`` and ``}``. A
basic block has the following form::

    Name (ParamList) ExcParam:
        Inst
        Inst
        ...

where ``ParamList`` is a list of type-name pairs: ``<T1> N1 <T2> N2 <T3> N3
...``, which specifies the normal **parameters** to the basic block.
``ExcParam`` is optional.  When present, it has the form ``[ ExcName ]`` where
``ExcName`` is the name of the **exception parameter**, which is also a
(non-normal) parameter. The exception parameter always has the ``ref<void>``
type. Many instructions follow the colon ``:``.

880 881 882 883 884 885 886 887
    Example::

        %bb1(<@T1> %p1 <@T2> %p2 <@T3> %p3):
            ...

        %bb2() [%exc]:
            ...

Kunshan Wang's avatar
Kunshan Wang committed
888 889
The first basic block is the **entry block**. The parameters of the entry block
must match the parameters of the function (determined by its signature).  The
890 891 892 893
execution starts from the entry block, and its parameters receive the arguments
to the function. The entry block must not have the exception parameter.

..
Kunshan Wang's avatar
Kunshan Wang committed
894

895 896
    NOTE: The name of the entry block is conventionally called ``%entry``, but
    is not compulsory.
Kunshan Wang's avatar
Kunshan Wang committed
897

Kunshan Wang's avatar
Kunshan Wang committed
898 899 900 901 902 903 904 905
The entry block must not be branched to from any basic blocks. Other basic
blocks are executed when branched to. The normal parameters receive arguments
from the branching sites. The exception parameter receives the exception caught
by the branching site as the argument. If the exception parameter is omitted but
the basic block is supposed to receive an exception, the exception will be
silently ignored. A basic block with an exception parameter must only be used as
the exceptional destination of instructions which can catch exceptions, which
currently include ``CALL``, ``TRAP``, ``WATCHPOINT`` and ``SWAPSTACK``.
906 907 908 909 910 911 912 913 914 915 916 917 918 919 920

    An example of a basic block with an exception parameter::

        %entry():
            ...
            %rv = CALL <...> @foo (...) EXC(%nor_dest(%rv) %exc_dest(%a %b %c))

        %nor_dest(<@T0> %p0):
            // process the return value
            // %p0 = %rv

        %exc_dest(<@T1> %p1 <@T2> %p2 <@T3> %p3) [%exc]:
            // handle exceptions here
            // %p1 = %a, %p2 = %b, %p3 = c, %exc = the exception

921 922
Each basic block contains a sequence of **instructions**. An instruction has one
of the following forms::
Kunshan Wang's avatar
Kunshan Wang committed
923

924
    ( Name1 Name2 Name3 ... ) = InstName InstBody
Kunshan Wang's avatar
Kunshan Wang committed
925

926
    Name = InstName InstBody
Kunshan Wang's avatar
Kunshan Wang committed
927

928
    InstName InstBody
Kunshan Wang's avatar
Kunshan Wang committed
929

930 931
The left hand side can be a list of names: ``( Name1 Name2 Name3 ... )``, each
is bound to a result of an instruction.
Kunshan Wang's avatar
Kunshan Wang committed
932

933 934 935
The latter two forms are syntax sugars. A single name without brackets is a
syntax sugar of ``( Name )``. If both the name and the equal sign ``=`` are
omitted, it is equivalent to an empty list of names: ``()``.
Kunshan Wang's avatar
Kunshan Wang committed
936

937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963
The number of results written in the IR must match the actual number of results
the instruction produces.

The ``InstName`` is optional. When present, it has the form ``[ Name ]``, where
``Name`` is the name of the instruction. This can be used to identify a
particular instruction, especially ``CALL`` and ``TRAP``. If ``InstName`` is
absent, the instruction does not have a name.

    Examples:

    ``%call_site`` is the name of the instruction; ``%rv1``, ``%rv2`` and
    ``%rv3`` are the names of return values::

        (%rv1 %rv2 %rv3) = [%call_site] CALL <@sig> @callee (%a1 %a2)

    The instruction has no name; ``%rv`` is the return value::

        %rv = ADD <@i64> %x %y

    ``%trap1`` is the name of the instruction; There is no return values. The
    empty angular bracket ``<>`` means the TRAP is not expecting any return
    values::

        [%trap1] TRAP <> KEEPALIVE (%x %y %z)


The grammar of the ``InstBody`` part for each instruction is defined separately
964
in `<instruction-set.rst>`__.
965 966

    Full example::
Kunshan Wang's avatar
Kunshan Wang committed
967

Kunshan Wang's avatar
Kunshan Wang committed
968
        .typedef @i64 = int<64>
969
        .funcsig @gcd_sig = (@i64 @i64) -> (@i64)
Kunshan Wang's avatar
Kunshan Wang committed
970 971 972

        .const @i64_0 <@i64> = 0

973 974 975
        .funcdef @gcd VERSION %v1 <@gcd_sig> {
            %entry(<@i64> %a <@i64> %b):
                BRANCH %head(%a %b)
Kunshan Wang's avatar
Kunshan Wang committed
976

977
            %head(<@i64> %a <@i64> %b):
Kunshan Wang's avatar
Kunshan Wang committed
978
                %z = EQ <@i64> %b @i64_0
979
                BRANCH2 %z %exit(%a) %body(%a %b)
Kunshan Wang's avatar
Kunshan Wang committed
980

981
            %body(<@i64> %a <@i64> %b):
Kunshan Wang's avatar
Kunshan Wang committed
982
                %b1 = SREM <@i64> %a %b
983
                BRANCH %head(%b %b1)
Kunshan Wang's avatar
Kunshan Wang committed
984

985
            %exit(<@i64> %a):
986
                RET %a
987
        }
Kunshan Wang's avatar
Kunshan Wang committed
988

989
The last instruction of any basic block must be a **terminator instruction**,
990
which is one of the following:
Kunshan Wang's avatar
Kunshan Wang committed
991

992
- ``BRANCH``, ``BRANCH2``, ``SWITCH``, ``WPBRANCH``
993 994 995 996
- ``TAILCALL``
- ``RET``
- ``THROW``
- ``SWAPSTACK`` if the "current stack clause" is ``KILL_OLD``
997
- Some `Common Instructions <common-insts.rst>`__ are always terminators:
998 999 1000

  - ``@uvm.thread_exit``

1001 1002
- Any instructions that may have an **exception clause** and actually have the
  exception clause, which are:
Kunshan Wang's avatar
Kunshan Wang committed
1003

1004
  - Binary operations (only ``UDIV``, ``SDIV``, ``UREM`` and ``SREM``)
1005
  - ``CALL``, ``CCALL``
1006 1007 1008
  - ``NEW``, ``NEWHYBRID``, ``ALLOCA``, ``ALLOCAHYBRID``
  - ``LOAD``, ``STORE``, ``CMPXCHG``, ``ATOMICRMW``
  - ``TRAP``, ``WATCHPOINT``
1009
  - ``NEWTHREAD``, ``SWAPSTACK``
1010
  - Some `Common Instructions <common-insts.rst>`__ when having exception
1011 1012 1013
    clause

    - ``@uvm.new_stack``
Kunshan Wang's avatar
Kunshan Wang committed
1014

1015
..
Kunshan Wang's avatar
Kunshan Wang committed
1016

1017 1018 1019
    NOTE: This is to say, for example, if a particular ``CALL`` instruction does
    have an exception clause, then it is a terminator. If it does not have
    exceptional clause clause, it is not a terminator.
Kunshan Wang's avatar
Kunshan Wang committed
1020

1021 1022 1023
Function Exposing Definition
============================

1024 1025 1026 1027 1028
A **function exposing definition** creates a value (usually an untraced function
pointer, ``ufuncptr``) so that the Mu function can be called from native
programs (usually C programs).

In the text form, it has the following form::
1029

1030
    .expose Name = FuncName CallConv Cookie
1031 1032 1033

where:

1034
* ``Name`` is a global name of the exposed function.
1035

1036
* ``FuncName`` is the name of a Mu function.
1037

1038
* ``CallConv`` is a flag that denotes the calling convention. See platform-specific ABI.
1039

1040 1041
* ``Cookie`` is the cookie. Must be the global name to a ``int<64>`` constant.

1042
This definition exposes a Mu function *FuncName* as an exposed value, identified
1043 1044 1045 1046
by *Name*, using the calling convention *CallConv*.

The *Cookie* is an ``int<64>`` constant attached to this exposed value. See
`Native Interface <native-interface.rst#cookie>`__ for more explanations.
1047

Kunshan Wang's avatar
Kunshan Wang committed
1048 1049 1050 1051 1052
    NOTE: It is the **function** that is exposed, not the version. Like in Mu, C
    programs can only directly call Mu functions rather than function versions.
    When a Mu function is redefined, the exposed function will automatically
    use the new version if called after redefining.

1053
How such an exposed function can be called is implementation-specific.
1054

Kunshan Wang's avatar
Kunshan Wang committed
1055 1056 1057 1058 1059
    NOTE: The spec is just trying to be general. In most cases, it will be
    called from C, and the exposed function is seen by C as a function pointer,
    and can be called using the same C calling convention (usually
    ``#DEFAULT``).

1060 1061 1062 1063
    Example::

        .expose @name = @func #DEFAULT @cookie

Kunshan Wang's avatar
Kunshan Wang committed
1064 1065 1066
Bundle Loading
==============

1067
The API provides the `load_bundle <api.rst#bundle-and-hail-loading>`__ and the
1068 1069 1070 1071
`IRBuilder.load <irbuilder.rst#load>`__ functions. These functions load bundles
from the text form or the constructed AST. They can be can be called by multiple
client threads on their `client contexts <api.rst#client-context>`__, and the
result is always equivalent to as if they were loaded in a particular sequence.
1072

1073 1074
The client must ensure the names of all entities in all bundles (already loaded
or being loaded) are distinct.
Kunshan Wang's avatar
Kunshan Wang committed
1075

1076 1077 1078 1079 1080 1081
    NOTE: There is a special case for the text form: If the function name in the
    ``.funcdef`` definition (such as ``@f`` in ``.funcdef @f VERSION @v <@sig> {
    ... }``) is the same as a function already loaded, it only defines a new
    version ``@v`` for the existing function ``@f``. If the function ``@f`` does
    not exist, the text form creates both a new function ``@f`` and a new
    version ``@v``.
Kunshan Wang's avatar
Kunshan Wang committed
1082

1083 1084
If a bundle contains a new version of an existing function, it **redefines** the
function. After this bundle is loaded, all function-calling operations to the
1085 1086 1087 1088 1089 1090 1091 1092
function that `happen after <memory-model.rst#happens-before>`__ the bundle
loading operation will call the newly defined version of the function.  The
actions of defining functions (bundle loading) and using of functions (including
function calls and the creation of stacks, i.e. the `@uvm.new_stack
<common-insts.rst#uvm-new-stack>`__ instruction or the `new_stack
<api.rst#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.rst#special-funcdef>`__.
Kunshan Wang's avatar
Kunshan Wang committed
1093 1094 1095 1096

All existing activations of any functions remain unchanged, that is, they remain
to be the old versions of the functions. 

1097 1098 1099
    NOTE: Specifically, existing `traps (including watchpoints)
    <instruction-set.rst#traps-and-watchpoints>`__ in older versions of
    functions remain valid. During OSR, redefining a function will not affect
1100 1101
    any existing function activations unless they are explicitly popped by the
    client.
Kunshan Wang's avatar
Kunshan Wang committed
1102

Kunshan Wang's avatar
Kunshan Wang committed
1103
.. vim: textwidth=80