3.5.1 U64JSON format

In U64JSON, each JSON value is encoded as a sequence of uint64_t values.

The following terminology is used in the table below:

MSB
The most significant 4 or 8 bits of each uint64_t value, in other words, bits[63:60] or bits[63:56]. The MSB determines the type and encoding of the value.
Container length
The number of uint64_t values, including the leading MSB value, representing the Value. This is the number of uint64_t values that must be skipped when skipping the Value. If the container length is not specified in the table, it is one.
Array length
The number of elements in an array. This is not the same as the container length.
Value
Any JSON value that is encoded according to this table.

Note:

For examples of U64JSON, see 3.5.7 U64JSON examples.

Table 3-2 U64JSON format

MSB JSON type Meaning
0x0 Number Positive integer Numbers from 0 to 0x0fffffffffffffff (60 bits).
0x1 Number Negative Numbers from -0x1000000000000000 to -1. To convert such a negative 64-bit pattern to U64JSON, bits[63:60] (0xf) are replaced with 0x1. To convert the U64JSON representation back to a 64-bit pattern, bits[63:60] (0x1) are replaced with 0xf.
0x2-0x7 String

String. Short string, 255 or fewer bytes long, where string[6] is in 0x20-0x7f if longer than 6 bytes. Format:

// nn = string length, s…+MM = string
uint64_t msb_and_string_data = 0xMMss ssss ssss ssnn;
uint64_t more_string_data_if_necessary[n >> 3]; // missing for nn <= 7

If the string is less than 7 bytes long, bits[63:56] (MM) are set to 0x20. This makes the MSB 0x2-0x7. String bytes are stored in little-endian format. All padding bytes are 0 bytes, except for the 0x20 in MM for short strings <= 6 bytes.

The string can contain null bytes and is not zero-terminated. The string encoding is UTF-8.

Note:

  • All ASCII strings that contain only printable characters, and therefore all C identifiers, which are 255 or fewer bytes long, belong to this class. This includes all Iris function names, argument names, and object member names, and also a lot of transported strings, like resource names.
  • Strings with 15 or fewer bytes can be compared with one or two uint64_t compares.
  • Encoding and decoding on little-endian machines is efficient (string follows length byte).
Container length: (nn >> 3) + 1.
0x8 NumberU64[]

Array of NumberU64 values. Format:

uint64_t msb_and_array_length = 0x8nnn nnnn nnnn nnnn; // n… = array length
uint64_t data[n];

Data is not encoded according to this table but rather stored as plain uint64_t values.

Container length: n… + 1.

0x9 - Reserved.
0xa Array

Generic array which can contain anything. Format:

// x… = container length
uint64_t msb_and_container_length = 0xaxxx xxxx xxxx xxxx;
uint64_t array_length; 
Value elements[array_length];

Container length: x….

0xb Object

Object container. Map from String to Value. Format:

// x… = container length
uint64_t msb_and_container_length = 0xbxxx xxxx xxxx xxxx; 
uint64_t number_of_members; 
struct { String member_name; Value value; } members[number_of_members];

Container length: x….

When converting from JSON, the object members should be sorted alphabetically by member name. This neither restricts nor enhances JSON, because in JSON, object members have no defined order. When converting to JSON, the object members can be emitted in alphabetical order or in any other order.

The reason for ordering object members is that U64JSON is used for time-critical, in-process function calls. Function arguments can be found faster in an ordered list than in an unordered list.

The reason for using alphabetical ordering is that function calls can be converted to and from JSON and the arguments are represented as an object, in which no order can be relied upon. Alphabetical order can be mechanically re-established, regardless of the Object's semantics.

0xc0 Number

64-bit NumberU64. Only used if the number cannot be represented using the MSB4=0 or MSB4=0xf formats. Format:

uint64_t msb = 0xc000 0000 0000 0000;
uint64_t number; 

Container length: 2.

0xc1 Number

64-bit NumberS64. Only used if the number cannot be represented using the MSB4=0, MSB4=0x1, or MSB8=0xc0 formats. Format:

uint64_t msb = 0xc100 0000 0000 0000; 
uint64_t number;

Container length: 2.

0xc2-0xc9 - Reserved, except 0xc9ffffffffffffff is an invalid U64JSON encoding and causes an E_u64json_encoding_error. Implementations can use this internally to explicitly represent an invalid U64JSON value, without affecting future extensions.
0xca Number

64-bit double-precision floating-point number. Format:

uint64_t msb = 0xca00 0000 0000 0000; 
double number;

Container length: 2.

0xcb - Reserved.
0xcc String

String. All strings that are not represented using the MSB=0x2-0x7 format, that is, either of the following:

  • Strings that are 256 or more bytes long.
  • Strings that are 7 or more bytes long and string[6] not in 0x20-0x7f.

Format:

uint64_t msb_and_string_length = 0xccnn nnnn nnnn nnnn; // n… = string length
uint64_t string_data[(n + 7) >> 3]

String bytes are stored in little-endian format. Unused bytes, if any, must be set to zero. The string can contain null-bytes and is not zero-terminated. The string encoding is UTF-8.

Container length: (n…+15) >> 3.

0xcd Null

Null value. Format:

uint64_t msb = 0xcd00 0000 0000 0000;
0xce Boolean

Boolean value False. Format:

uint64_t msb = 0xce00 0000 0000 0000;
0xcf Boolean

Boolean value True. Format:

uint64_t msb = 0xcf00 0000 0000 0000;
0xd - Reserved
0xe0 Request Encodes an Iris request message.
uint64_t msb = 0xe0vv xxxx xxxx xxxx xxxx;

vv indicates the JSON-RPC version and is 0x20.

x… is the container length.

uint64_t request_id; // request[1]

This is the same as the id field in a JSON-encoded request. The request_id is a plain uint64 and is not encoded according to the Number format in this table.

uint64_t instId; // request[2]

Indicates the destination instance, in other words, the callee of the Iris function. Equivalent to the instId parameter that is required by almost all Iris functions. Setting instId to zero is equivalent to omitting the instId parameter, targeting the global instance. The instId is a plain uint64 and is not encoded according to the Number format in this table.

String method; // request[3:n]

Equivalent to the method field in a JSON-encoded request. This field has a variable length and is encoded as a U64JSON string according to the format in this table. The offset n is given by the encoding of the string.

Object params; // request[n:m]

Equivalent to the params field in a JSON-encoded request. This field has a variable length and is encoded as a U64JSON object according to the format in this table. The offset n is given by the encoding of the previous field and m by the encoding of the params object.

0xe1 Notification

Encodes an Iris notification message.

The encoding of a Notification is the same as that of a Request except for the following differences:

  • The MSB is 0xe1 instead of 0xe0.
  • The request_id field is ignored and should be set to 0xffffffffffffffff. All other fields are encoded in the same way as a Request.
0xe2 Response Encodes an Iris response message.
uint64_t msb = 0xe2vv xxxx xxxx xxxx xxxx;

vv indicates the JSON-RPC version and is 0x20.

x… is the container length.

uint64_t request_id; // response[1]

This is the same as the id field in a JSON-encoded response. The request_id is a plain uint64 and is not encoded according to the Number format in this table.

uint64_t instId; // response[2]

Indicates the destination instance, in other words, the caller of the Iris function. The instId is a plain uint64 and is not encoded according to the Number format in this table.

int64_t error_code; // response[3]

If this is zero (E_ok), this response returns a result. Any other value is an Iris error code and this response returns an error. The value of this field determines the encoding of the rest of the Response. The error code is a plain int64 and is not encoded according to the Number format in this table. See Chapter 6 Response error codes for information about error codes.

Value result; // response[4:n]

or

String message; // response[4:m]

The type and meaning of this field depends on the value of the preceeding error_code field. If error_code is E_ok, this field is the result of the call encoded as a U64JSON value. It can have any type. If error_code is not E_ok, this field is the response error object message field encoded as a U64JSON string.

Value data; // response[m:xx]

Optional error object data field. This field is only present if this is an error response, in other words, error_code is not E_ok.

This can be any value encoded as U64JSON according to this table. The data field is optional and can be omitted. In this case, the Response container ends at the end of the message field and m == xx.

0xf Number Positive integer Numbers from 0xf000000000000000-0xffffffffffffffff (60 bits).
Non-ConfidentialPDF file icon PDF version101196_0100_03_en
Copyright © 2018, 2019 Arm Limited or its affiliates. All rights reserved.