2.2 JSON-RPC 2.0 function call format

Iris interfaces use the JSON-RPC 2.0 format and semantics for function calls and responses.

JSON-RPC 2.0 is a lightweight Remote Procedure Call (RPC) mechanism that is easy to understand and implement.

In this documentation, the terms request, notification, and response refer to the Request, Notification, and Response Objects that are defined by JSON-RPC 2.0, see http://www.jsonrpc.org/specification.

All functions are called by name, and responses are associated with requests by using a request id, which the caller assigns to the request.

The JSON-RPC 2.0 standard supports various use patterns. For example, it supports argument passing by position or by name. Iris uses the following subset of, and extensions to, JSON-RPC 2.0:

Function arguments

Function arguments are passed by name, not by position. In other words, params is an object, not an array. The order of the arguments in the Iris API documentation is irrelevant.

When manually generating JSON or U64JSON requests, you can order function arguments alphabetically by name to speed up function call processing.

Request ids

The request id that is passed to a function call is a NumberU64. The caller specifies bits[31:0] of the request id. This allows the caller to match function return values with function calls. It is usually an integer that increases with every request. This increasing id can wrap around, but ids of ongoing function calls must not be reused. There is no requirement to use an increasing id or even unique ids.

The instId argument specifies the instance that the function operates on, similar to a this pointer in C++. For more information about instId, see 3.2 Instances. The caller must set bits[63:32] of the request id to the instance id, instId, of the caller. This part of the id is used to route responses back to the caller. The usage of bits[63:32] is an Iris-specific extension of JSON RPC 2.0 to support the Iris Object Model. For more information about the Object Model, see Chapter 3 Object model

Note:

Notifications do not need to route a response back to the caller. Therefore, notifications do not use a request id.
Requests and notifications

All Iris functions can be sent either as a request or as a notification, unless otherwise stated in the API documentation:

  • For requests, the caller always receives a response, even if the function is specified to have no return value. In this case, a Null value is returned.
  • For notifications, the caller never receives a response and no value is returned, even if the function is specified to return one.
String encoding

All strings, including object member names, are encoded using UTF-8. All Iris function names, function argument names, and object member names are plain ASCII and are C identifiers. Iris does not use String to transport binary data, because String cannot represent all binary byte sequences. For example, Strings cannot contain NUL bytes.

Binary data
Binary data is transported as a NumberU64[] with an explicit size argument, if necessary.
Case sensitivity

The following are case sensitive:

  • Function names.
  • Argument names.
  • Object member names.
  • Instance names.
  • Event source names.
  • Event source field names.
  • Any other names and textual identifiers.
  • Type strings.
  • Verbatim strings that are used in the interface.
Bi-directional calls

Functions can generally be called in both directions between two instances.

Batch requests

Iris does not support batch requests or batch responses, in other words, arrays of requests or arrays of responses. Independent function calls to independent instances do not map well onto the batch requests and batch responses as defined in JSON-RPC 2.0. However, IrisRpc uses persistent TCP connections, and sending individual requests has almost the same performance as sending them in an array as a batch request.

Non-ConfidentialPDF file icon PDF version101196_0100_00_en
Copyright © 2018 Arm Limited or its affiliates. All rights reserved.