ivampiresp/Spdk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
1e481d0438
Spdk/doc/jsonrpc.md
Yanbo Zhou 64ccd4b95b bdev: a new public function to get the I/O statistics of bdev 
Add a new function and its RPC caller. By using it, we can
get the statistics of all the bdevs or the specified bdev.

Meanwhile, with this patch, the open source tool 'sysstat/iostat'
can support for SPDK. The 'iostat' tool can call this function to
get the statistics of all the SPDK managed devices via the rpc
interface.

Change-Id: I135a7bbd49d923014bdf93720f78dd5a588d7afa
Signed-off-by: Yanbo Zhou <yanbo.zhou@intel.com>
Reviewed-on: https://review.gerrithub.io/393130
Tested-by: SPDK Automated Test System <sys_sgsw@intel.com>
Reviewed-by: Dariusz Stojaczyk <dariuszx.stojaczyk@intel.com>
Reviewed-by: Daniel Verkamp <daniel.verkamp@intel.com>
Reviewed-by: Shuhei Matsumoto <shuhei.matsumoto.xt@hitachi.com>
Reviewed-by: Ben Walker <benjamin.walker@intel.com>
2018-05-23 17:49:21 +00:00

14 KiB
Raw Blame History

JSON-RPC Methods

Overview

SPDK implements a JSON-RPC 2.0 server to allow external management tools to dynamically configure SPDK components.

App Framework

kill_instance

Send a signal to the application.

Parameters

Name Optional Type Description
sig_name Required string Signal to send (SIGINT, SIGTERM, SIGQUIT, SIGHUP, or SIGKILL)

Example

Example request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "kill_instance",
  "params": {
    "sig_name": "SIGINT"
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

context_switch_monitor

Query, enable, or disable the context switch monitoring functionality.

Parameters

Name Optional Type Description
enabled Optional boolean Enable (true) or disable (false) monitoring (omit this parameter to query the current state)

Response

The current state of context switch monitoring is returned as a boolean.

Example

Example request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "context_switch_monitor",
  "params": {
    "enabled": false
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": false
}

Block Device Abstraction Layer

get_bdevs

Get information about block devices (bdevs).

Parameters

The user may specify no parameters in order to list all block devices, or a block device may be specified by name.

Name Optional Type Description
name Optional string Block device name

Response

The response is an array of objects containing information about the requested block devices.

Example

Example request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "get_bdevs",
  "params": {
    "name": "Malloc0"
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "name": "Malloc0",
      "product_name": "Malloc disk",
      "block_size": 512,
      "num_blocks": 20480,
      "claimed": false,
      "supported_io_types": {
        "read": true,
        "write": true,
        "unmap": true,
        "write_zeroes": true,
        "flush": true,
        "reset": true,
        "nvme_admin": false,
        "nvme_io": false
      },
      "driver_specific": {}
    }
  ]
}

get_bdevs_iostat

Get I/O statistics of block devices (bdevs).

Parameters

The user may specify no parameters in order to list all block devices, or a block device may be specified by name.

Name Optional Type Description
name Optional string Block device name

Response

The response is an array of objects containing I/O statistics of the requested block devices.

Example

Example request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "get_bdevs_iostat",
  "params": {
    "name": "Nvme0n1"
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "name": "Nvme0n1",
      "bytes_read": 34051522560,
      "num_read_ops": 8312910,
      "bytes_written": 0,
      "num_write_ops": 0
    }
  ]
}

delete_bdev

Unregister a block device.

Example

Example request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "delete_bdev",
  "params": {
    "name": "Malloc0"
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

Parameters

Name Optional Type Description
name Required string Block device name

set_bdev_qos_limit_iops

Set an IOPS-based quality of service rate limit on a bdev.

Parameters

Name Optional Type Description
name Required string Block device name
ios_per_sec Required number Number of I/Os per second to allow. 0 means unlimited.

Example

Example request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "set_bdev_qos_limit_iops",
  "params": {
    "name": "Malloc0"
    "ios_per_sec": 20000
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

NVMe-oF Target

get_nvmf_subsystems method

Parameters

This method has no parameters.

Example

Example request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "get_nvmf_subsystems"
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "nqn": "nqn.2014-08.org.nvmexpress.discovery",
      "subtype": "Discovery"
      "listen_addresses": [],
      "hosts": [],
      "allow_any_host": true
    },
    {
      "nqn": "nqn.2016-06.io.spdk:cnode1",
      "subtype": "NVMe",
      "listen_addresses": [
        {
          "trtype": "RDMA",
          "adrfam": "IPv4",
          "traddr": "192.168.0.123",
          "trsvcid": "4420"
        }
      ],
      "hosts": [
        {"nqn": "nqn.2016-06.io.spdk:host1"}
      ],
      "allow_any_host": false,
      "serial_number": "abcdef",
      "namespaces": [
        {"nsid": 1, "name": "Malloc2"},
        {"nsid": 2, "name": "Nvme0n1"}
      ]
    }
  ]
}

construct_nvmf_subsystem method

Construct an NVMe over Fabrics target subsystem.

Parameters

Name Optional Type Description
nqn Required string Subsystem NQN
listen_addresses Optional array Array of @ref rpc_construct_nvmf_subsystem_listen_address objects
hosts Optional array Array of strings containing allowed host NQNs. Default: No hosts allowed.
allow_any_host Optional boolean Allow any host (true) or enforce allowed host whitelist (false). Default: false.
serial_number Required string Serial number of virtual controller
namespaces Optional array Array of @ref rpc_construct_nvmf_subsystem_namespace objects. Default: No namespaces.
max_namespaces Optional number Maximum number of namespaces that can be attached to the subsystem. Default: 0 (Unlimited)

listen_address

Name Optional Type Description
trtype Required string Transport type ("RDMA")
adrfam Required string Address family ("IPv4", "IPv6", "IB", or "FC")
traddr Required string Transport address
trsvcid Required string Transport service ID

namespace

Name Optional Type Description
nsid Optional number Namespace ID between 1 and 4294967294, inclusive. Default: Automatically assign NSID.
bdev_name Required string Name of bdev to expose as a namespace.
nguid Optional string 16-byte namespace globally unique identifier in hexadecimal (e.g. "ABCDEF0123456789ABCDEF0123456789")
eui64 Optional string 8-byte namespace EUI-64 in hexadecimal (e.g. "ABCDEF0123456789")

Example

Example request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "construct_nvmf_subsystem",
  "params": {
    "nqn": "nqn.2016-06.io.spdk:cnode1",
    "listen_addresses": [
      {
        "trtype": "RDMA",
        "adrfam": "IPv4",
        "traddr": "192.168.0.123",
        "trsvcid: "4420"
      }
    ],
    "hosts": [
      "nqn.2016-06.io.spdk:host1",
      "nqn.2016-06.io.spdk:host2"
    ],
    "allow_any_host": false,
    "serial_number": "abcdef",
    "namespaces": [
      {"nsid": 1, "name": "Malloc2"},
      {"nsid": 2, "name": "Nvme0n1"}
    ]
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

delete_nvmf_subsystem method

Delete an existing NVMe-oF subsystem.

Parameters

Parameter Optional Type Description
nqn Required string Subsystem NQN to delete.

Example

Example request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "delete_nvmf_subsystem",
  "params": {
    "nqn": "nqn.2016-06.io.spdk:cnode1"
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

nvmf_subsystem_add_listener method

Add a new listen address to an NVMe-oF subsystem.

Parameters

Name Optional Type Description
nqn Required string Subsystem NQN
listen_address Required object @ref rpc_construct_nvmf_subsystem_listen_address object

Example

Example request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "nvmf_subsystem_add_listener",
  "params": {
    "nqn": "nqn.2016-06.io.spdk:cnode1",
    "listen_address": {
      "trtype": "RDMA",
      "adrfam": "IPv4",
      "traddr": "192.168.0.123",
      "trsvcid: "4420"
    }
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

nvmf_subsystem_add_ns method

Add a namespace to a subsystem. The namespace ID is returned as the result.

Parameters

Name Optional Type Description
nqn Required string Subsystem NQN
namespace Required object @ref rpc_construct_nvmf_subsystem_namespace object

Example

Example request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "nvmf_subsystem_add_ns",
  "params": {
    "nqn": "nqn.2016-06.io.spdk:cnode1",
    "namespace": {
      "nsid": 3,
      "bdev_name": "Nvme0n1"
    }
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": 3
}

nvmf_subsystem_remove_ns method

Remove a namespace from a subsystem.

Parameters

Name Optional Type Description
nqn Required string Subsystem NQN
nsid Required number Namespace ID

Example

Example request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "nvmf_subsystem_remove_ns",
  "params": {
    "nqn": "nqn.2016-06.io.spdk:cnode1",
    "nsid": 1
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

nvmf_subsystem_add_host method

Add a host NQN to the whitelist of allowed hosts.

Parameters

Name Optional Type Description
nqn Required string Subsystem NQN
host Required string Host NQN to add to the list of allowed host NQNs

Example

Example request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "nvmf_subsystem_add_host",
  "params": {
    "nqn": "nqn.2016-06.io.spdk:cnode1",
    "host": "nqn.2016-06.io.spdk:host1"
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

nvmf_subsystem_remove_host method

Remove a host NQN from the whitelist of allowed hosts.

Parameters

Name Optional Type Description
nqn Required string Subsystem NQN
host Required string Host NQN to remove from the list of allowed host NQNs

Example

Example request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "nvmf_subsystem_remove_host",
  "params": {
    "nqn": "nqn.2016-06.io.spdk:cnode1",
    "host": "nqn.2016-06.io.spdk:host1"
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

nvmf_subsystem_allow_any_host method

Configure a subsystem to allow any host to connect or to enforce the host NQN whitelist.

Parameters

Name Optional Type Description
nqn Required string Subsystem NQN
allow_any_host Required boolean Allow any host (true) or enforce allowed host whitelist (false).

Example

Example request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "nvmf_subsystem_allow_any_host",
  "params": {
    "nqn": "nqn.2016-06.io.spdk:cnode1",
    "allow_any_host": true
  }
}

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}