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}
|
||||
|
||||
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.
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user