doc/jsonrpc: add rpc for vhost target
Change-Id: Ifa1bc84c3a8e531bdc69cf8d0f5b9214fb1417e3 Signed-off-by: Pawel Wodkowski <pawelx.wodkowski@intel.com> Reviewed-on: https://review.gerrithub.io/417719 Tested-by: SPDK CI Jenkins <sys_sgci@intel.com> Chandler-Test-Pool: SPDK Automated Test System <sys_sgsw@intel.com> Reviewed-by: Ben Walker <benjamin.walker@intel.com> Reviewed-by: Jim Harris <james.r.harris@intel.com> Reviewed-by: Shuhei Matsumoto <shuhei.matsumoto.xt@hitachi.com>
This commit is contained in:
Pawel Wodkowski
Jim Harris
parent
a8b9e3e0c3
commit
a0f4eeaf38
473
doc/jsonrpc.md
473
doc/jsonrpc.md
@ -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}
|
# Logical Volume {#jsonrpc_components_lvol}
|
||||||
|
|
||||||
Identification of logical volume store and logical volume is explained first.
|
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
|
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
|
cluster_sz | Optional | number | Cluster size of the logical volume store in bytes
|
||||||
|
|
||||||
### Reponse
|
### Response
|
||||||
|
|
||||||
UUID of the created logical volume store is returned.
|
UUID of the created logical volume store is returned.
|
||||||
|
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user