Commit 0a920a0c authored by Boris Glimcher's avatar Boris Glimcher Committed by Tomasz Zawadzki
Browse files

schema: add embedded objects 



in addition to normal arguments, we also have objects
objects can be referenced in parameters
and we also keep html ref as well

this patch adds those objects to schema
and handle their auto-generation as well.

Change-Id: Id4edcb5bb26d4cfa1558777dc185a89453402d73
Signed-off-by: default avatarBoris Glimcher <Boris.Glimcher@emc.com>
Reviewed-on: https://review.spdk.io/c/spdk/spdk/+/26482


Reviewed-by: default avatarKonrad Sztyber <ksztyber@nvidia.com>
Tested-by: default avatarSPDK Automated Test System <spdkbot@gmail.com>
Reviewed-by: default avatarJacek Kalwas <jacek.kalwas@nutanix.com>
parent 0817c3c7

doc/jsonrpc.md.jinja2

+11 −63
Original line number Diff line number Diff line
@@ -6451,12 +6451,7 @@ Create an authentication group for CHAP authentication. 


##### secret {#rpc_iscsi_create_auth_group_secret}



 Name    | Optional   | Type   | Description

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

 user    | Required   | string | Unidirectional CHAP name

 secret  | Required   | string | Unidirectional CHAP secret

 muser   | Optional   | string | Bidirectional CHAP name

 msecret | Optional   | string | Bidirectional CHAP secret

{{ iscsi_auth_secret_object }}



#### Example
@@ -7034,10 +7029,7 @@ Add initiator group to portal group mappings to an existing iSCSI target node. 


##### Portal to Initiator group mappings object



 Name   | Optional   | Type   | Description

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

 ig_tag | Required   | number | Existing initiator group tag

 pg_tag | Required   | number | Existing portal group tag

{{ iscsi_tgt_pg_ig_map_object }}



#### Example
@@ -7088,10 +7080,7 @@ Delete initiator group to portal group mappings from an existing iSCSI target no 


##### Portal to Initiator group mappings object



 Name   | Optional   | Type   | Description

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

 ig_tag | Required   | number | Existing initiator group tag

 pg_tag | Required   | number | Existing portal group tag

{{ iscsi_tgt_pg_ig_map_object }}



#### Example
@@ -7216,10 +7205,7 @@ Add a portal group. 


##### Portal object



 Name   | Optional   | Type   | Description

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

 host   | Required   | string | Hostname or IP address

 port   | Required   | string | Port number

{{ iscsi_portal_object }}



#### Example
@@ -7834,12 +7820,7 @@ This method will fail if listener with given address already exists. 
The listen_address is used for adding the listeners to the NVMe-oF target

and for referring to discovery services on other targets.



 Name    | Optional   | Type   | Description

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

 trtype  | Required   | string | Transport type ("RDMA")

 adrfam  | Optional   | string | Address family ("IPv4", "IPv6", "IB", or "FC")

 traddr  | Required   | string | Transport address

 trsvcid | Optional   | string | Transport service ID (required for RDMA or TCP)

{{ nvmf_listen_address_object }}



#### Example
@@ -7962,16 +7943,7 @@ Add a namespace to a subsystem. The namespace ID is returned as the result. 


##### namespace {#rpc_nvmf_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")

 uuid          | Optional   | string | RFC 4122 UUID (e.g. "ceccf520-691e-4b46-9546-34af789907c5")

 ptpl_file     | Optional   | string | File path to save/restore persistent reservation information

 anagrpid      | Optional   | number | ANA group ID. Default: Namespace ID.

 hide_metadata | Optional   | bool   | Enable hide_metadata option to the bdev. Default: false

{{ nvmf_namespace_object }}



#### Example
@@ -8585,17 +8557,7 @@ have been initialized. 


##### admin_cmd_passthru {#spdk_nvmf_admin_passthru_conf}



 Name               | Optional   | Type   | Description

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

 identify_ctrlr     | Optional   | bool   | If true, enables custom identify handler that reports some identify attributes from the underlying NVMe drive

 identify_uuid_list | Optional   | bool   | If true, enables passthru identify UUID list (0x17 CNS) admin cmds for underlying NVMe device

 get_log_page       | Optional   | bool   | If true, enables passthru get log page command handlers for underlying NVMe drive (for non-fabrics related log pages)

 get_set_features   | Optional   | bool   | If true, enables passthru get/set_feature OPC handlers for underlying NVMe drive

 sanitize           | Optional   | bool   | If true, enables passthru sanitize OPC handlers for underlying NVMe drive

 security_send_recv | Optional   | bool   | If true, enables passthru security send/recieve OPC handlers for underlying NVMe drive

 fw_update          | Optional   | bool   | If true, enables passthru firmware download/commit OPC handlers for underlying NVMe drive

 nvme_mi            | Optional   | bool   | If true, enables passthru NVMe-MI send/recieve OPC handlers for underlying NVMe drive

 vendor_specific    | Optional   | bool   | If true, enables passthru command handlers for underlying NVMe drive for vendor specific cmds (OPCs: 0xC0-0xFF)

{{ nvmf_admin_cmd_passthru_object }}



#### Example
@@ -9330,39 +9292,25 @@ Response is an array of objects describing requested controller(s). Common field 


`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_blk_controller_params_object }}



##### Vhost SCSI {#rpc_vhost_get_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_vhost_get_controllers_scsi_luns

{{ vhost_scsi_controller_params_object }}



##### Vhost SCSI LUN {#rpc_vhost_get_controllers_scsi_luns}



Object of type:



 Name                    | Type        | Description

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

 id                      | number      | SCSI LUN ID

 bdev_name               | string      | Backing bdev name

{{ vhost_scsi_luns_controller_params_object }}



##### Vhost NVMe {#rpc_vhost_get_controllers_nvme}



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



 Name                    | Type        | Description

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

 nsid                    | number      | Namespace ID

 bdev                    | string      | Backing bdev name

{{ vhost_nvme_controller_params_object }}



#### Example

schema/schema.json

+291 −0
Original line number Diff line number Diff line 
{

  "objects": [

    {

      "name": "iscsi_auth_secret",

      "fields": [

        {

          "name": "user",

          "type": "string",

          "required": true,

          "description": "Unidirectional CHAP name"

        },

        {

          "name": "secret",

          "type": "string",

          "required": true,

          "description": "Unidirectional CHAP secret"

        },

        {

          "name": "muser",

          "type": "string",

          "required": false,

          "description": "Bidirectional CHAP name"

        },

        {

          "name": "msecret",

          "type": "string",

          "required": false,

          "description": "Bidirectional CHAP secret"

        }

      ]

    },

    {

      "name": "iscsi_tgt_pg_ig_map",

      "fields": [

        {

          "name": "ig_tag",

          "type": "number",

          "required": true,

          "description": "Existing initiator group tag"

        },

        {

          "name": "pg_tag",

          "type": "number",

          "required": true,

          "description": "Existing portal group tag"

        }

      ]

    },

    {

      "name": "iscsi_portal",

      "fields": [

        {

          "name": "host",

          "type": "string",

          "required": true,

          "description": "Hostname or IP address"

        },

        {

          "name": "port",

          "type": "string",

          "required": true,

          "description": "Port number"

        }

      ]

    },

    {

      "name": "nvmf_listen_address",

      "fields": [

        {

          "name": "trtype",

          "type": "string",

          "required": true,

          "description": "Transport type (\"RDMA\")"

        },

        {

          "name": "adrfam",

          "type": "string",

          "required": false,

          "description": "Address family (\"IPv4\", \"IPv6\", \"IB\", or \"FC\")"

        },

        {

          "name": "traddr",

          "type": "string",

          "required": true,

          "description": "Transport address"

        },

        {

          "name": "trsvcid",

          "type": "string",

          "required": false,

          "description": "Transport service ID (required for RDMA or TCP)"

        }

      ]

    },

    {

      "name": "nvmf_namespace",

      "fields": [

        {

          "name": "nsid",

          "type": "number",

          "required": false,

          "description": "Namespace ID between 1 and 4294967294, inclusive. Default: Automatically assign NSID."

        },

        {

          "name": "bdev_name",

          "type": "string",

          "required": true,

          "description": "Name of bdev to expose as a namespace."

        },

        {

          "name": "nguid",

          "type": "string",

          "required": false,

          "description": "16-byte namespace globally unique identifier in hexadecimal (e.g. \"ABCDEF0123456789ABCDEF0123456789\")"

        },

        {

          "name": "eui64",

          "type": "string",

          "required": false,

          "description": "8-byte namespace EUI-64 in hexadecimal (e.g. \"ABCDEF0123456789\")"

        },

        {

          "name": "uuid",

          "type": "string",

          "required": false,

          "description": "RFC 4122 UUID (e.g. \"ceccf520-691e-4b46-9546-34af789907c5\")"

        },

        {

          "name": "ptpl_file",

          "type": "string",

          "required": false,

          "description": "File path to save/restore persistent reservation information"

        },

        {

          "name": "anagrpid",

          "type": "number",

          "required": false,

          "description": "ANA group ID. Default: Namespace ID."

        },

        {

          "name": "hide_metadata",

          "type": "bool",

          "required": false,

          "description": "Enable hide_metadata option to the bdev. Default: false"

        }

      ]

    },

    {

      "name": "nvmf_admin_cmd_passthru",

      "fields": [

        {

          "name": "identify_ctrlr",

          "type": "bool",

          "required": false,

          "description": "If true, enables custom identify handler that reports some identify attributes from the underlying NVMe drive"

        },

        {

          "name": "identify_uuid_list",

          "type": "bool",

          "required": false,

          "description": "If true, enables passthru identify UUID list (0x17 CNS) admin cmds for underlying NVMe device"

        },

        {

          "name": "get_log_page",

          "type": "bool",

          "required": false,

          "description": "If true, enables passthru get log page command handlers for underlying NVMe drive (for non-fabrics related log pages)"

        },

        {

          "name": "get_set_features",

          "type": "bool",

          "required": false,

          "description": "If true, enables passthru get/set_feature OPC handlers for underlying NVMe drive"

        },

        {

          "name": "sanitize",

          "type": "bool",

          "required": false,

          "description": "If true, enables passthru sanitize OPC handlers for underlying NVMe drive"

        },

        {

          "name": "security_send_recv",

          "type": "bool",

          "required": false,

          "description": "If true, enables passthru security send/recieve OPC handlers for underlying NVMe drive"

        },

        {

          "name": "fw_update",

          "type": "bool",

          "required": false,

          "description": "If true, enables passthru firmware download/commit OPC handlers for underlying NVMe drive"

        },

        {

          "name": "nvme_mi",

          "type": "bool",

          "required": false,

          "description": "If true, enables passthru NVMe-MI send/recieve OPC handlers for underlying NVMe drive"

        },

        {

          "name": "vendor_specific",

          "type": "bool",

          "required": false,

          "description": "If true, enables passthru command handlers for underlying NVMe drive for vendor specific cmds (OPCs: 0xC0-0xFF)"

        }

      ]

    },

    {

      "name": "vhost_blk_controller_params",

      "fields": [

        {

          "name": "bdev",

          "type": "string",

          "required": false,

          "description": "Backing bdev name or Null if bdev is hot-removed"

        },

        {

          "name": "readonly",

          "type": "boolean",

          "required": false,

          "description": "True if controllers is readonly, false otherwise"

        }

      ]

    },

    {

      "name": "vhost_scsi_controller_params",

      "fields": [

        {

          "name": "target_name",

          "type": "string",

          "required": false,

          "description": "Name of this SCSI target"

        },

        {

          "name": "id",

          "type": "number",

          "required": false,

          "description": "Unique SPDK global SCSI target ID"

        },

        {

          "name": "scsi_dev_num",

          "type": "number",

          "required": false,

          "description": "SCSI target ID initiator will see when scanning this controller"

        },

        {

          "name": "luns",

          "type": "array",

          "required": false,

          "description": "array of objects describing @ref rpc_vhost_get_controllers_scsi_luns"

        }

      ]

    },

    {

      "name": "vhost_scsi_luns_controller_params",

      "fields": [

        {

          "name": "id",

          "type": "number",

          "required": false,

          "description": "SCSI LUN ID"

        },

        {

          "name": "bdev_name",

          "type": "string",

          "required": false,

          "description": "Backing bdev name"

        }

      ]

    },

    {

      "name": "vhost_nvme_controller_params",

      "fields": [

        {

          "name": "nsid",

          "type": "number",

          "required": false,

          "description": "Namespace ID"

        },

        {

          "name": "bdev",

          "type": "string",

          "required": false,

          "description": "Backing bdev name"

        }

      ]

    }

  ],

  "methods": [

    {

      "name": "spdk_kill_instance",
@@ -3652,6 +3938,7 @@ 
          "name": "listen_address",

          "type": "object",

          "required": true,

          "class": "nvmf_listen_address",

          "description": "@ref rpc_nvmf_listen_address object"

        },

        {
@@ -3687,6 +3974,7 @@ 
          "name": "listen_address",

          "type": "object",

          "required": true,

          "class": "nvmf_listen_address",

          "description": "@ref rpc_nvmf_listen_address object"

        }

      ]
@@ -3710,6 +3998,7 @@ 
          "name": "listen_address",

          "type": "object",

          "required": true,

          "class": "nvmf_listen_address",

          "description": "@ref rpc_nvmf_listen_address object"

        },

        {
@@ -4050,6 +4339,7 @@ 
          "name": "address",

          "type": "object",

          "required": true,

          "class": "nvmf_listen_address",

          "description": "@ref rpc_nvmf_listen_address object"

        },

        {
@@ -4073,6 +4363,7 @@ 
          "name": "address",

          "type": "object",

          "required": true,

          "class": "nvmf_listen_address",

          "description": "@ref rpc_nvmf_listen_address object"

        }

      ]

scripts/genrpc.py

+15 −0
Original line number Diff line number Diff line
@@ -85,6 +85,21 @@ def generate_docs(schema): 
            if params

            else "This method has no parameters."

        )

    for obj in schema['objects']:

        fields = [

            dict(

                Name=el["name"],

                Optional="Required" if el["required"] else "Optional",

                Type=el["type"],

                Description=el["description"],

            )

            for el in obj["fields"]

        ]

        transformation[f"{obj['name']}_object"] = (

            tabulate(fields, headers="keys", tablefmt="presto").replace("-+-", " | ")

            if fields

            else "This method has no parameters."

        )

    result = schema_template.render(transformation)

    print(result)