Ark Bytecode Fundamentals

Overall Design

Overview

Ark bytecode is a binary file generated by the ArkCompiler from ArkTS/TS/JS code and provided for Ark Runtime to interpret and execute. Bytecode mainly contains Ark bytecode instructions.
This topic introduces the design of these instructions, covering key concepts, specific formats, and meanings to help you understand and work with Ark bytecode instructions effectively.
An Ark bytecode instruction consists of an operation code (instruction name) and a list of parameters. An operation code can be prefix-free or prefixed. Registers, immediate values, string id, method id, and literal id can be used as parameters. In addition, the accumulator can be used as a default parameter in some instructions.
In addition to registers and accumulator, Ark bytecode supports four value storage mechanisms: global variables, module namespaces and variables, lexical environments and variables, and patch variables. Instructions can reference values from these storage locations as parameters.

Terms and Constraints

Terms

The following table lists the terms used in this topic.

Constraints

• All code examples provided in this topic adhere to the ArkTS language specifications.
• This topic is applicable only to Ark bytecode of version 12.0.6.0. The version number is an internal field of the ArkCompiler and does not require your attention.

Bytecode Composition

Operation Codes and Prefixes

Operation codes in Ark bytecode are typically 8-bit values, allowing for up to 256 unique opcodes. However, as the ArkCompiler’s functionality has expanded, the number of operation codes has exceeded 256. To accommodate this, the Ark bytecode introduces prefixes, expanding the maximum operation code width from 8 bits to 16 bits. 8-bit operation codes (prefix-free) are used for common instructions, whereas 16-bit operation codes (prefixed) are used for less frequent ones.
Prefixed operation codes are stored in little-endian format, composed of an 8-bit operation code and an 8-bit prefix. During encoding, the operation code is shifted left by 8 bits and then ORed with the prefix. | Prefix | Mnemonic | Description | | ———-| ———- | ———- | | 0xfe | throw | Conditional/Unconditional throw instruction.| | 0xfd | wide | Instructions with wider encoding widths for immediate values, IDs, or register indexes.| | 0xfc | deprecated | Instructions no longer generated by the ArkCompiler. They are used only for runtime compatibility.
These instructions are not described in the following sections.| | 0xfb | callruntime| Instructions for calling runtime methods.|

The mnemonic form of a prefixed operation code is prefix mnemonic.operation code mnemonic. For example, wide.stlexvar combines the prefix wide (0xfd) with the operation code stlexvar (0x0d), resulting in the prefixed operation code 0x0dfd.

Registers and Accumulator

The Ark Virtual Machine (VM) uses a register-based model with virtual registers. When a register holds a primitive value, it is 64 bits wide; when it holds an object reference, its width adjusts accordingly.
A special invisible register called the accumulator (acc) is used in the Ark bytecode. The acc serves as the default target for many instructions and as a default parameter for others, helping to produce more compact bytecode without consuming additional encoding width.

Example:

function foo(): number {
    return 1;
}

Related instructions in the bytecode:

.function any .foo(any a0, any a1, any a2) {
    ldai 0x1
    return
}

ldai 0x1: loads integer literal 1 to the acc.
return: returns the value in the acc.

immediate values

Some instructions use constants to represent integer values, double-precision floating-point values, or jump offsets. These constants, known as immediate values, can be 8-bit, 16-bit, 32-bit, or 64-bit.

Method, String, and Literal Indexes

The Ark bytecode stores offsets for all methods, strings, and literal arrays used in the source file. Literal arrays contain various literals, such as integer numbers, string offsets, and method offsets. In Ark bytecode instructions, these indexes are 16-bit values, referred to as method indexes (method id), string indexes (string id), and literal indexes (literal id). These indexes are encoded in instructions to reference methods, strings, and literal arrays.

Value Storage Mechanisms

Global Variables

In Script build mode, global variables are stored in a globally unique mapping, with the variable name as the key and its value as the value. Global variables can be accessed using global-related instructions.

Example:

function foo(): void {
    a += 2;
    b = 5;
}

Related instructions in the bytecode:

.function any .foo(any a0, any a1, any a2) {
    tryldglobalbyname 0x0, a
    sta v4
    ldai 0x2
    add2 0x1, v4
    trystglobalbyname 0x2, a
    ldai 0x5
    trystglobalbyname 0x3, b
    ...
}

tryldglobalbyname 0x0, a: loads a global variable named a to the acc. If this variable does not exist, an exception is thrown.
trystglobalbyname 0x2, a: stores the value of the acc to a global variable named a. If this variable does not exist, an exception is thrown.
trystglobalbyname 0x3, b: stores the value of the acc to a global variable named b. If this variable does not exist, an exception is thrown.

NOTE

0x0, 0x2, and 0x3 in the preceding instructions are reserved for internal use in the Ark Runtime.

Module Namespaces and Variables

All module namespaces used in the source file are compiled into arrays, referenced by instructions using indexes. For example, getmodulenamespace 0x1 references the module namespace at index 0x1.
All module variables used in the source file are compiled into arrays, referenced by instructions using indexes. For example, stmodulevar 0x1 references a module variable at index 0x1.
In a function, if the declaration of a module variable is in the same source file as the function, the variable is called a local module variable. Otherwise, it is called an external module variable. For example, ldlocalmodulevar and ldexternalmodulevar are used to load local module variables and external module variables, respectively.
Scenarios for generating module instructions include import and export. The main scenarios are as follows: * import * as: module namespace * import { }: module variable * export: local export

NOTE

Module-related logic is an internal implementation detail of the compiler. As the ArkCompiler evolves, new scenarios involving module instructions may emerge, and existing ones may change due to evolving requirements or code refactoring.

Example:

import { a, b } from "./module_foo"
import * as c from "./module_bar"

export let d: number = 3;

a + b + d;

Related instructions in the bytecode:

.function any .func_main_0(any a0, any a1, any a2) {
    getmodulenamespace 0x1
    ldai 0x3
    stmodulevar 0x0
    ldexternalmodulevar 0x0
    sta v0
    throw.undefinedifholewithname a
    ldexternalmodulevar 0x1
    sta v1
    throw.undefinedifholewithname b
    lda v1
    add2 0x0, v0
    sta v0
    ldlocalmodulevar 0x0
    sta v1
    throw.undefinedifholewithname d
    lda v1
    add2 0x1, v0
    ...
}

getmodulenamespace 0x1: obtains the module namespace © of slot 1 and stores it in the acc.
stmodulevar 0x0: stores the values in the acc into slot 0 of the current module.
ldexternalmodulevar 0x0: loads the value (a) of slot 0 of the external module and stores it in the acc.
ldlocalmodulevar 0x0: loads the value (d) of slot 0 of the current local module and stores it in the acc.

Lexical Environments and Lexical Variables

In Ark bytecode, a lexical environment may be considered as an array with multiple slots, and each slot corresponds to one lexical variable. A method may contain multiple lexical environments. Instructions reference lexical variables using the relative nesting level and slot index of the lexical environment. For example, ldlexvar 0x1, 0x2 loads the value from slot 0x2 of the lexical environment one level outside the current lexical environment into the acc.

|xxx|xxx|xxx|xxx|  <-- Lexical environment one level outside the current lexical environment.
         ^
       |------------ ldlexvar 0x1, 0x2

|xxx|xxx|xxx|xxx|  <-- Current lexical environment.

NOTE
The logic related to lexical is used in the compiler. With subsequent evolution of the ArkCompiler, new scenarios involving lexical instructions may emerge. On the other hand, existing lexical instruction-related scenarios may no longer generates lexical instructions as requirements evolve and code is reconstructed. Example:

function foo(): void {
    let a: number = 1;
    function bar(): number {
        return a;
    }
}

Related instructions in the bytecode:

.function any .foo(any a0, any a1, any a2) {
    newlexenv 0x1
    ...
    definefunc 0x0, .bar, 0x0
    sta v3
    ldai 0x1 
    ...
    stlexvar 0x0, 0x0
    ...
}    

.function any .bar(any a0, any a1, any a2) {
    ...
    ldlexvar 0x0, 0x0
    ...
}

newlexenv 0x1: creates a lexical environment with one slot, stores it in the acc, and enters this environment.
stlexvar 0x0, 0x0: stores the value in the acc into slot 0 of the lexical environment 0 level outside the current lexical environment.
ldlexvar 0x0, 0x0: stores the value from slot 0 of the lexical environment 0 level outside the current lexical environment into the acc.

Shared Lexical Environments

Shared lexical environments are a special type of lexical environment Unlike regular lexical environments, each lexical variable in a shared lexical environment is a Sendable object. The ArkCompiler uses shared lexical environments to enable sharing of lexical variables across multiple threads.

Example:

@Sendable
class A { }

@Sendable
class B {
    u: A = new A()
}

Related instructions in the bytecode:

.function any .#~B=#B(any a0, any a1, any a2) {
label_1: 
label_0: 
	callruntime.ldsendablevar 0x0, 0x0
	sta v0
	throw.undefinedifholewithname A
	...
label_2: 
}

.function any .func_main_0(any a0, any a1, any a2) {
label_1: 
label_0: 
	callruntime.newsendableenv 0x1
	...
	callruntime.definesendableclass 0x0, .#~A=#A, _3, 0x0, v0
	callruntime.stsendablevar 0x0, 0x0
	...
label_2: 
}

an instruction callruntime.newsendableenv 0x1: creates a shared lexical environment with one slot and enters this lexical environment.
callruntime.stsendablevar 0x0, 0x0: stores the value in the acc into slot 0 of the lexical environment outside level 0.
callruntime.ldsendablevar 0x0, 0x0: stores the value from slot 0 of the lexical environment 0 level outside the current lexical environment into the acc.

Patch Variables

The ArkCompiler supports patch mode compilation. When a source file is modified, patch mode compilation generates a patch bytecode that, together with the original bytecode, completes the functional update. During patch mode compilation, patch variables generated by the ArkCompiler are stored in a special patch lexical environment. Instructions in the Ark bytecode use slot numbers from the patch lexical environment to reference patch variables. For example, the instruction ldpatchvar 0x1 is used to load the patch variable from slot 1.

Example:

function bar(): void {} // Add a statement and compile the patch.

function foo(): void {
    bar(); // Add a statement and compile the patch.
}

Related instructions in the bytecode:

.function any foo(...) {
    ...
    wide.ldpatchvar 0x0
    sta v4
    lda v4
    callarg0 0x0
    ...
}

.function any patch_main_0(...) {
    newlexenv 0x1
    definefunc 0x1, bar:(any,any,any), 0x0
    wide.stpatchvar 0x0
    ...
}

wide.stpatchvar 0x0: stores the bar function into slot 0 of the patch lexical environment.
wide.ldpatchvar 0x0: stores the value from slot 0 in the patch lexical environment into the acc.

Function Call Specifications

For a method with N formal parameters, the last N+3 registers are used to pass parameters. The first three registers are fixed to represent the function object (FunctionObject), new.target (NewTarget), and this from the lexical environment where the function resides. The subsequent N registers correspond to the N formal parameters.

Example:

function foo(a: number, b: number): void {}

Related instructions in the bytecode:

.function any .foo(any a0, any a1, any a2, any a3, any a4) {
    // a0: FunctionObject
    // a1: NewTarget
    // a2: this 
    // a3: a
    // a4: b
}

Bytecode Format Description

Bytecode Summary

The table below summarizes all Ark bytecode instructions in the current version. The register index, immediate value, and id are described using a character to represent each four-bit width.
For example, consider the instruction defineclasswithbuffer RR, @AAAA, @BBBB, +CCCC, vDD:
* defineclasswithbuffer: mnemonic for the operation code. * RR: 8-bit reserved number used internally during the Ark runtime. The number mentioned here is just an example showing a complete instruction format. * @AAAA, @BBBB: 16-bit id * +CCCC: 16-bit immediate value * vDD: 8-bit register index

你可能感兴趣的鸿蒙文章

harmony 鸿蒙ArkTS

harmony 鸿蒙Configuring arkOptions in build-profile.json5

harmony 鸿蒙Asynchronous Lock

harmony 鸿蒙Ark Bytecode File Format

harmony 鸿蒙Naming Conventions for Ark Bytecode Functions

harmony 鸿蒙Overview of Ark Bytecode

harmony 鸿蒙Shared Container

harmony 鸿蒙Asynchronous Waiting

harmony 鸿蒙ArkTS Cross-Language Interaction

harmony 鸿蒙Dynamic Import