Consider PIC for bytecode

[bolkedebruin]

First of all thank you very much for this! I am using this on an ESP32 and I hope to distribute it to users soon with some custom device bindings.

My ESP32 is very limited in memory (320KB and much of that is consumed for program code) so I'd like to limit memory as much as possible. I am allowing users to compile (WASM :-) ) their code and upload it to a partition which is them mmap'ed to memory. To ensure true zero copy I need to relocate the memory addresses at compile time.

For the ESP32 this poses a challenge as mmap'ed virtual addresses are not guaranteed to be deterministic across firmware updates and devices.

The question is would you consider having a position independent bytecode (PIC) implementation? Or would load-time relocation be better?

[bolkedebruin]

What I have done until now is:

1. Provide on device relocation with chunking - splitting JS_RelocateBytecode2 into JS_RelocateHdr and JS_RelocateMtag and making these available
2. Add a RomAtom table after the header. This is required as the pointers to stdlib are different across devices. This table provides a lookup from pointer to offset
3. Change the bytecode version to version 2

This works. It allows me to use bytecode that is compiled in the browser (WASM) to be re-used on the device. It does not use extra memory as the table is contained in ROM. For searching the offset I am using a binary search.

In case you are interested I can prepare a PR, but I am not sure if you want to go this way.

[bellard]

I am not sure I understand your problem. The persistent bytecode is not position independent and modifying the engine to allow it would be very invasive and would bring a noticeable slowdown.

The way to go is to relocate the bytecode on the device just before flashing it. Doing the relocation by chunks is on my TODO list as it allows to relocate the bytecode without having to temporarily store it into RAM. If you have a patch for it I can look at it.

[bolkedebruin]

Scenario: JavaScript is compiled in a web browser (WASM build of mquickjs) and the bytecode is uploaded to an ESP32 device for execution.

The Issue: ROM Atoms Have Different Addresses Across Runtimes

When you compile this JavaScript in the browser:

  led.setColor(0, 255, 0, 0);
  setTimeout(function() {
      led.off(0);
  }, 1000);

The WASM compiler generates bytecode with ROM atom pointers that reference WASM's ROM table:

  // In WASM memory space (browser)
  JSAtomStruct *wasm_rom_atoms[] = {
      /* ... */
      [JS_ATOM_setColor] = 0x00002449,  // WASM ROM pointer
      [JS_ATOM_setTimeout] = 0x00002581, // WASM ROM pointer
      /* ... */
  };

But when that bytecode runs on ESP32, it needs ESP32's ROM table:

  // In ESP32 memory space (device)
  JSAtomStruct *esp32_rom_atoms[] = {
      /* ... */
      [JS_ATOM_setColor] = 0x3c0a4320,  // ESP32 ROM pointer
      [JS_ATOM_setTimeout] = 0x3c0a4458, // ESP32 ROM pointer
      /* ... */
  };

Why Standard Relocation Doesn't Work

Standard JS_RelocateBytecode2() relocates addresses within the bytecode, but ROM atoms are pointers INTO the stdlib ROM table, which has a completely different layout between WASM and ESP32.

What I did now, is instead of storing device-specific ROM pointers, store device-independent ROM atom indices:

  v0x0002 Bytecode Format:
  [Header - 20 bytes]
    version: 0x0002
    base_addr: 0x3c31c05c
    rom_atom_count: 9

  [ROM Translation Table - xxx bytes]
    Entry 0: { bytecode_offset: 0x0128, rom_index: 42 }  // "setColor"
    Entry 1: { bytecode_offset: 0x0134, rom_index: 87 }  // "setTimeout"
    ...

  [Bytecode Data - xxx bytes]
    ... compiled instructions ...

Compiler (browser or command line):

// Build translation table by detecting ROM pointers
for (each pointer in bytecode) {
    if (pointer points to ROM table) {
        // Store: bytecode offset → ROM index (not pointer!)
        rom_table[n] = {
            .bytecode_offset = current_offset,
            .rom_index = get_rom_index(pointer),  // e.g., 42 for "setColor"
            .padding = 0
        };
    }
}

Runtime (e.g. ESP32):

// Translate during bytecode loading
uint32_t bc_reloc_value(uint32_t value, uint32_t base_addr) {
    // Check if this offset needs ROM translation
    int16_t rom_index = lookup_rom_translation(value);

    if (rom_index >= 0) {
        // Translate: ROM index → ESP32 ROM pointer
        return (uint32_t)&esp32_rom_atoms[rom_index];
    }

    // Standard relocation for non-ROM pointers
    return base_addr + value;
}

This ensures there is no RAM allocation as the ROM table lives entirely in flash (or something else), there is no bytecode copied into RAM and we can have the same bytecode run across different architectures. It is also backwards compatible.

This is what I use on my device as part of my firmware to do the relocation:

// Upload bytecode without loading it all into RAM
void relocateBytecode(const uint8_t* data, size_t length) {
    // 1. Write header with target base_addr
    JSBytecodeHeader* hdr = (JSBytecodeHeader*)data;
    uint32_t rom_table_size = JS_GetRomTableSize(hdr);
    uint32_t target_base = flash_addr + sizeof(header) + rom_table_size;

    JS_RelocateHdr(hdr, target_base);
    partition.write(flash_addr, hdr, sizeof(header));

    // 2. Copy ROM table as-is (no relocation needed!)
    partition.write(flash_addr + sizeof(header),
                    data + sizeof(header),
                    rom_table_size);

    // 3. Relocate bytecode in 4KB chunks
    uint32_t offset = sizeof(header) + rom_table_size;
    while (offset < length) {
        uint32_t chunk_size = min(4096, length - offset);
        JS_RelocateMtag((uint8_t*)data + offset, chunk_size, target_base);
        partition.write(flash_addr + offset, data + offset, chunk_size);
        offset += chunk_size;
    }
}

Does this approach make sense for upstream mquickjs? The ROM translation table is a small addition (9 atoms × 8 bytes = 72 bytes) that enables cross-compilation scenarios without breaking existing functionality.

[bolkedebruin]

Alternatively, an option is to store the ROM indices and use a flag to distinguish them from pointers. Using indices instead of pointers would incur a small performance hit. So, this could be done as post processing with a flag ("-portable") and looks the simplest or more invasive with serialization updates.

[bellard]

In the persistent bytecode all the atoms are present including the ones present in stdlib. You can confirm it by dumping it:

./mqjs -dd -o a.bin a.js

The relocation done by JS_RelocateBytecode() converts them to stdlib atoms if necessary. So there is no need for any other information. So what you do is not needed.

The only thing which is missing is the relocation by chunks. I'll commit an API ASAP.

Did I miss something ?

Best regards,

Fabrice.

[bolkedebruin]

O wow, I think I got sucked down into a rabbit hole when I was playing with WASM compilation and trying to do relocation in the browser (with the device providing the addresses).

I was aware of prepare_compilation but somehow couldn't get it to work earlier.

I think my proposal would be slightly faster, but I have no proof ;-).

It would be awesome to have official chunked relocation. I have just split the function in to header relocation and mtag relocation. This works fine and I can provide it if you are interested but maybe you want to do it differently.