Skip to content

Latest commit

 

History

History
217 lines (163 loc) · 7.83 KB

0050-vm-syscalls-3.md

File metadata and controls

217 lines (163 loc) · 7.83 KB
Raw
Number Category Status Author Created
0050
Standards Track
Draft
Xu Jiandong <[email protected]>, Dingwei Zhang <[email protected]>
2023-04-17

VM Syscalls 3

Abstract

This document describes the addition of the syscalls during the CKB2023. This update significantly enhances the flexibility of CKB Script.

The following four syscalls are added:

Spawn

The syscall Spawn is the core part of this update. The Spawn and the latter two syscalls: Get Memory Limit and Set Content together, implement a way to call another CKB Script in a CKB Script. Unlike the Exec1 syscall, Spawn saves the execution context of the current script, like posix_spawn, the parent script continues when the child script ends.

typedef struct spawn_args_t {
  uint64_t memory_limit;
  int8_t* exit_code;
  uint8_t* content;
  uint64_t* content_length;
} spawn_args_t;

int ckb_spawn(size_t index, size_t source, size_t bounds,
              int argc, char* argv[], spawn_args_t* spgs);

The arguments used here are:

  • index: an index value denoting the index of entries to read.
  • source: a flag denoting the source of cells to locate, possible values include:
    • 1: input cells.
    • 0x0100000000000001: input cells with the same running script as current script
    • 2: output cells.
    • 0x0100000000000002: output cells with the same running script as current script
    • 3: dep cells.
  • bounds: high 32 bits means offset, low 32 bits means length. If length equals to zero, it read to end instead of reading 0 bytes.
  • argc: argc contains the number of arguments passed to the program
  • argv: argv is a one-dimensional array of strings
  • memory_limit: an integer value denoting the memory size to use(Not including descendant children scripts), possible values include:
    • 1 (0.5 M)
    • 2 (1 M)
    • 3 (1.5 M)
    • 4 (2 M)
    • 5 (2.5 M)
    • 6 (3 M)
    • 7 (3.5 M)
    • 8 (4 M)
  • exit_code: an int8 pointer denoting where we save the exit code of a child script.
  • content: a pointer to a buffer in VM memory space denoting where we would load the sub-script data. The child script will write data in this buffer via set_content.
  • content_length: a pointer to a 64-bit unsigned integer in VM memory space. When calling the syscall, this memory location should store the length of the buffer specified by content. When returning from the syscall, CKB VM would fill in content_length with the actual length of the buffer. content_length up to 256K.

The arguments used here index, source, bounds, argc and argv follow the usage described in EXEC.

If the sub-script does not write data, then NULL can be passed in for content and content_length.

This syscall might return the following results:

  • 0: Success.
  • 1-3: Reserved. These values are already assigned to other syscalls.
  • 4: Elf format error
  • 5: Exceeded max content length.
  • 6: Wrong memory limit
  • 7: Exceeded max peak memory

Note that now we have a new limit called Peak Memory Usage. The maximum memory usage of the parent script and its descendant children cannot exceed this value. Currently, this limit is set at 32M.

Unlike cycles which always increase, the current memory can decrease or increase. When a child script is returned, the occupied memory is freed. This makes current memory usage lower.

Get Memory Limit

Get the maximum available memory for the current script.

int ckb_get_memory_limit();

For the script(prime script) directly invoked by CKB, it will always return 8(4M). For the child script invoked by prime script or other child script, it depends on the parameters set by Spawn.

Current Memory

Get the Current Memory Usage. The result is the sum of the memory usage of the parent script and the child script.

int ckb_current_memory();

The system call returns an integer. Multiply it by 0.5 to get the actual memory usage (unit: megabytes)

Set Content

The child script can return bytes data to the parent script through Set Content.

int ckb_set_content(uint8_t* content, uint64_t* length);
  • Length up to 256K.
  • If the written length is greater than the limit given by Spawn, the final written length is the minimum of the two.
  • Returns 0 for success, otherwise for failure.
  • This function is optional. Not every child script needs to call this, and nothing will happen if you call it from the prime script.

Spawn example

Consider the creation of a dependency library with a straightforward function that receives parameters, concatenates them, and subsequently returns the resulting string to the caller.

lib_strcat.c

#include <stdint.h>
#include <string.h>

#include "ckb_syscalls.h"

int main(int argc, char *argv[]) {
  char content[80];
  for (int i = 0; i < argc; i++) {
    strcat(content, argv[i]);
  }
  uint64_t content_size = (uint64_t)strlen(content);
  ckb_set_content(&content[0], &content_size);
  if (content_size != (uint64_t)strlen(content)) {
    return 1;
  }
  return 0;
}

We can call this dependent library in the prime script. The prime script passes in two parameters "hello", "world" and checks if the return value is equal to "helloworld”:

prime.c

#include <stdint.h>
#include <string.h>

#include "ckb_syscalls.h"

int main() {
  const char *argv[] = {"hello", "world"};

  int8_t       spgs_exit_code = 255;
  uint8_t      spgs_content[80] = {};
  uint64_t     spgs_content_length = 80;
  spawn_args_t spgs = {
    .memory_limit = 8,
    .exit_code = &spgs_exit_code,
    .content = &spgs_content[0],
    .content_length = &spgs_content_length,
  };

  ckb_spawn(1, 3, 0, 2, argv, &spgs);
  if (strlen(spgs_content) != 10) {
    return 1;
  }
  if (strcmp(spgs_content, "helloworld") != 0) {
    return 1;
  }
  if (spgs_exit_code != 0) {
    return 1;
  }
  return 0;
}

Load Block Extension

Load Block Extension syscall has a signature like the following:

int ckb_load_block_extension(void* addr, uint64_t* len, size_t offset, size_t index, size_t source)
{
  return syscall(2104, addr, len, offset, index, source, 0);
}

The arguments used here are:

  • addr, len and offset follow the usage described in Partial Loading section.
  • index: an index value denoting the index of entries to read.
  • source: a flag denoting the source of cells to locate, possible values include:
    • 1: input cells.
    • 0x0100000000000001: input cells with the same running script as current script
    • 3: dep cells.
    • 4: header deps.

This syscall would locate the extension field associated either with an input cell, a dep cell, or a header dep based on source and index value, then use the same step as documented in Partial Loading section to feed the serialized value into VM.

Note when you are loading the extension associated with an input cell or a dep cell, the header hash of the corresponding block should still be included in header deps section of the current transaction.

This syscall might return the following errors:

  • An invalid source value would immediately trigger an VM error and halt execution.
  • The syscall would return with 1 as return value if the index value is out of bound.
  • This syscall would return with 2 as return value if requesting a header for an input cell, but the header deps section is missing the header hash for the input cell.

In case of errors, addr and index will not contain meaningful data to use.