Commit a0f4eeaf authored by Pawel Wodkowski's avatar Pawel Wodkowski Committed by Jim Harris
Browse files

doc/jsonrpc: add rpc for vhost target 



Change-Id: Ifa1bc84c3a8e531bdc69cf8d0f5b9214fb1417e3
Signed-off-by: default avatarPawel Wodkowski <pawelx.wodkowski@intel.com>
Reviewed-on: https://review.gerrithub.io/417719


Tested-by: default avatarSPDK CI Jenkins <sys_sgci@intel.com>
Chandler-Test-Pool: SPDK Automated Test System <sys_sgsw@intel.com>
Reviewed-by: default avatarBen Walker <benjamin.walker@intel.com>
Reviewed-by: default avatarJim Harris <james.r.harris@intel.com>
Reviewed-by: default avatarShuhei Matsumoto <shuhei.matsumoto.xt@hitachi.com>
parent a8b9e3e0

doc/jsonrpc.md

+472 −1
Original line number Diff line number Diff line
@@ -1130,6 +1130,477 @@ Example response: 
}

~~~



# Vhost Target {#jsonrpc_components_vhost_tgt}



The following common preconditions need to be met in all target types.



Controller name will be used to create UNIX domain socket. This implies that name concatenated with vhost socket

directory path needs to be valid UNIX socket name.



@ref cpu_mask parameter is used to choose CPU on which pollers will be launched when new initiator is connecting.

It must be a subset of application CPU mask. Default value is CPU mask of the application.



## set_vhost_controller_coalescing {#rpc_set_vhost_controller_coalescing}



Controls interrupt coalescing for specific target. Because `delay_base_us` is used to calculate delay in CPU ticks

there is no hardcoded limit for this parameter. Only limitation is that final delay in CPU ticks might not overflow

32 bit unsigned integer (which is more than 1s @ 4GHz CPU). In real scenarios `delay_base_us` should be much lower

than 150us. To disable coalescing set `delay_base_us` to 0.



### Parameters



Name                    | Optional | Type        | Description

----------------------- | -------- | ----------- | -----------

ctrlr                   | Required | string      | Controller name

delay_base_us           | Required | number      | Base (minimum) coalescing time in microseconds

iops_threshold          | Required | number      | Coalescing activation level greater than 0 in IO per second



### Example



Example request:



~~~

{

  "params": {

    "iops_threshold": 100000,

    "ctrlr": "VhostScsi0",

    "delay_base_us": 80

  },

  "jsonrpc": "2.0",

  "method": "set_vhost_controller_coalescing",

  "id": 1

}

~~~



Example response:



~~~

{

  "jsonrpc": "2.0",

  "id": 1,

  "result": true

}

~~~



## construct_vhost_scsi_controller {#rpc_construct_vhost_scsi_controller}



Construct vhost SCSI target.



### Parameters



Name                    | Optional | Type        | Description

----------------------- | -------- | ----------- | -----------

ctrlr                   | Required | string      | Controller name

cpumask                 | Optional | string      | @ref cpu_mask for this controller



### Example



Example request:



~~~

{

  "params": {

    "cpumask": "0x2",

    "ctrlr": "VhostScsi0"

  },

  "jsonrpc": "2.0",

  "method": "construct_vhost_scsi_controller",

  "id": 1

}

~~~



Example response:



~~~

{

  "jsonrpc": "2.0",

  "id": 1,

  "result": true

}

~~~



## add_vhost_scsi_lun {#rpc_add_vhost_scsi_lun}



In vhost target `ctrlr` create SCSI target with ID `scsi_target_num` and add `bdev_name` as LUN 0.



### Parameters



Name                    | Optional | Type        | Description

----------------------- | -------- | ----------- | -----------

ctrlr                   | Required | string      | Controller name

scsi_target_num         | Required | number      | SCSI target ID between 0 and 7

bdev_name               | Required | string      | Name of bdev to expose as a LUN 0



### Example



Example request:



~~~

{

  "params": {

    "scsi_target_num": 1,

    "bdev_name": "Malloc0",

    "ctrlr": "VhostScsi0"

  },

  "jsonrpc": "2.0",

  "method": "add_vhost_scsi_lun",

  "id": 1

}

~~~



Example response:



~~~

response:

{

  "jsonrpc": "2.0",

  "id": 1,

  "result": true

}

~~~



## remove_vhost_scsi_target {#rpc_remove_vhost_scsi_target}



Remove SCSI target ID `scsi_target_num` from vhost target `scsi_target_num`.



This method will fail if initiator is connected, but doesn't support hot-remove (the `VIRTIO_SCSI_F_HOTPLUG` is not negotiated).



### Parameters



Name                    | Optional | Type        | Description

----------------------- | -------- | ----------- | -----------

ctrlr                   | Required | string      | Controller name

scsi_target_num         | Required | number      | SCSI target ID between 0 and 7



### Example



Example request:



~~~

request:

{

  "params": {

    "scsi_target_num": 1,

    "ctrlr": "VhostScsi0"

  },

  "jsonrpc": "2.0",

  "method": "remove_vhost_scsi_target",

  "id": 1

}

~~~



Example response:



~~~

{

  "jsonrpc": "2.0",

  "id": 1,

  "result": true

}

~~~



## construct_vhost_nvme_controller {#rpc_construct_vhost_nvme_controller}



Construct empty vhost NVMe controller.



### Parameters



Name                    | Optional | Type        | Description

----------------------- | -------- | ----------- | -----------

ctrlr                   | Required | string      | Controller name

io_queues               | Required | number      | Number between 1 and 31 of IO queues for the controller

cpumask                 | Optional | string      | @ref cpu_mask for this controller





### Example



Example request:



~~~

{

  "params": {

    "cpumask": "0x2",

    "io_queues": 4,

    "ctrlr": "VhostNvme0"

  },

  "jsonrpc": "2.0",

  "method": "construct_vhost_nvme_controller",

  "id": 1

}

~~~



Example response:



~~~

{

  "jsonrpc": "2.0",

  "id": 1,

  "result": true

}

~~~



## add_vhost_nvme_ns {#rpc_add_vhost_nvme_ns}



Add namespace backed by `bdev_name`



### Parameters



Name                    | Optional | Type        | Description

----------------------- | -------- | ----------- | -----------

ctrlr                   | Required | string      | Controller name

bdev_name               | Required | string      | Name of bdev to expose as a namespace

cpumask                 | Optional | string      | @ref cpu_mask for this controller



### Example



Example request:



~~~

{

  "params": {

    "bdev_name": "Malloc0",

    "ctrlr": "VhostNvme0"

  },

  "jsonrpc": "2.0",

  "method": "add_vhost_nvme_ns",

  "id": 1

}

~~~



Example response:



~~~

{

  "jsonrpc": "2.0",

  "id": 1,

  "result": true

}

~~~



## construct_vhost_blk_controller {#rpc_construct_vhost_blk_controller}



Construct vhost block controller



If `readonly` is `true` then vhost block target will be created as read only and fail any write requests.

The `VIRTIO_BLK_F_RO` feature flag will be offered to the initiator.



### Parameters



Name                    | Optional | Type        | Description

----------------------- | -------- | ----------- | -----------

ctrlr                   | Required | string      | Controller name

bdev_name               | Required | string      | Name of bdev to expose block device

readonly                | Optional | boolean     | If true, this target will be read only (default: false)

cpumask                 | Optional | string      | @ref cpu_mask for this controller





### Example



Example request:



~~~

{

  "params": {

    "dev_name": "Malloc0",

    "ctrlr": "VhostBlk0"

  },

  "jsonrpc": "2.0",

  "method": "construct_vhost_blk_controller",

  "id": 1

}

~~~



Example response:



~~~

{

  "jsonrpc": "2.0",

  "id": 1,

  "result": true

}

~~~



## get_vhost_controllers {#rpc_get_vhost_controllers}



Display information about all vhost controllers.



### Parameters



This method has no parameters.



### Response {#rpc_get_vhost_controllers_response}



Response is an array of objects describing each controllers. Common fields are:



Name                    | Type        | Description

----------------------- | ----------- | -----------

ctrlr                   | string      | Controller name

cpumask                 | string      | @ref cpu_mask of this controller

delay_base_us           | number      | Base (minimum) coalescing time in microseconds (0 if disabled)

iops_threshold          | number      | Coalescing activation level

backend_specific        | object      | Backend specific informations



### Vhost block {#rpc_get_vhost_controllers_blk}



`backend_specific` contains one `block` object  of type:



Name                    | Type        | Description

----------------------- | ----------- | -----------

bdev                    | string      | Backing bdev name or Null if bdev is hot-removed

readonly                | boolean     | True if controllers is readonly, false otherwise



### Vhost SCSI {#rpc_get_vhost_controllers_scsi}



`backend_specific` contains `scsi` array of following objects:



Name                    | Type        | Description

----------------------- | ----------- | -----------

target_name             | string      | Name of this SCSI target

id                      | number      | Unique SPDK global SCSI target ID

scsi_dev_num            | number      | SCSI target ID initiator will see when scanning this controller

luns                    | array       | array of objects describing @ref rpc_get_vhost_controllers_scsi_luns



### Vhost SCSI LUN {#rpc_get_vhost_controllers_scsi_luns}



Object of type:



Name                    | Type        | Description

----------------------- | ----------- | -----------

id                      | number      | SCSI LUN ID

bdev_name               | string      | Backing bdev name



### Vhost NVMe {#rpc_get_vhost_controllers_nvme}



`backend_specific` contains `namespaces` array of following objects:



Name                    | Type        | Description

----------------------- | ----------- | -----------

nsid                    | number      | Namespace ID

bdev                    | string      | Backing bdev name



### Example



Example request:



~~~

{

  "jsonrpc": "2.0",

  "method": "get_vhost_controllers",

  "id": 1

}

~~~



Example response:



~~~

{

  "jsonrpc": "2.0",

  "id": 1,

  "result": [

    {

      "cpumask": "0x2",

      "backend_specific": {

        "block": {

          "readonly": false,

          "bdev": "Malloc0"

        }

      },

      "iops_threshold": 60000,

      "ctrlr": "VhostBlk0",

      "delay_base_us": 100

    },

    {

      "cpumask": "0x2",

      "backend_specific": {

        "scsi": [

          {

            "target_name": "Target 2",

            "luns": [

              {

                "id": 0,

                "bdev_name": "Malloc1"

              }

            ],

            "id": 0,

            "scsi_dev_num": 2

          },

          {

            "target_name": "Target 5",

            "luns": [

              {

                "id": 0,

                "bdev_name": "Malloc2"

              }

            ],

            "id": 1,

            "scsi_dev_num": 5

          }

        ]

      },

      "iops_threshold": 60000,

      "ctrlr": "VhostScsi0",

      "delay_base_us": 0

    },

    {

      "cpumask": "0x2",

      "backend_specific": {

        "namespaces": [

          {

            "bdev": "Malloc3",

            "nsid": 1

          },

          {

            "bdev": "Malloc4",

            "nsid": 2

          }

        ]

      },

      "iops_threshold": 60000,

      "ctrlr": "VhostNvme0",

      "delay_base_us": 0

    }

  ]

}

~~~



## remove_vhost_controller {#rpc_remove_vhost_controller}



Remove vhost target.



This call will fail if there is an initiator connected or there is at least one SCSI target configured in case of

vhost SCSI target. In the later case please remove all SCSI targets first using @ref rpc_remove_vhost_scsi_target.



### Parameters



Name                    | Optional | Type        | Description

----------------------- | -------- | ----------- | -----------

ctrlr                   | Required | string      | Controller name



### Example



Example request:



~~~

{

  "params": {

    "ctrlr": "VhostNvme0"

  },

  "jsonrpc": "2.0",

  "method": "remove_vhost_controller",

  "id": 1

}

~~~



Example response:



~~~

{

  "jsonrpc": "2.0",

  "id": 1,

  "result": true

}

~~~



# Logical Volume {#jsonrpc_components_lvol}



Identification of logical volume store and logical volume is explained first.
@@ -1157,7 +1628,7 @@ bdev_name | Required | string | Bdev on which to construct lo 
lvs_name                | Required | string      | Name of the logical volume store to create

cluster_sz              | Optional | number      | Cluster size of the logical volume store in bytes



### Reponse

### Response



UUID of the created logical volume store is returned.