From 392b07463bf39dcf115ae3f99626ca281fca1d0d Mon Sep 17 00:00:00 2001 From: Jim Harris Date: Thu, 10 Dec 2020 22:15:10 +0000 Subject: [PATCH] jsonrpc.md: add section for rpc.py BKMs Generating JSON-RPC config files by hand is very tedious. Thankfully, SPDK has a number of ways to simplify the process. Let's document them in jsonrpc.md so that we have a single place to point people who have questions. Signed-off-by: Jim Harris Change-Id: I7470cf07923f2ea25ab55bf40a422c31d17b31d0 Reviewed-on: https://review.spdk.io/gerrit/c/spdk/spdk/+/5530 Tested-by: SPDK CI Jenkins Reviewed-by: Aleksey Marchuk Reviewed-by: Shuhei Matsumoto --- doc/jsonrpc.md | 71 ++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 69 insertions(+), 2 deletions(-) diff --git a/doc/jsonrpc.md b/doc/jsonrpc.md index 2ce7f410d..8c5011c67 100644 --- a/doc/jsonrpc.md +++ b/doc/jsonrpc.md @@ -1,4 +1,4 @@ -# JSON-RPC Methods {#jsonrpc} +# JSON-RPC {#jsonrpc} # Overview {#jsonrpc_overview} @@ -54,7 +54,74 @@ This type of error is most common one. It mean that there is an error while proc - Parameter domain check failed. - Request is valid but some other error occurred during processing request. If possible message explains the error reason nature. -## Adding external RPC methods +## rpc.py {#rpc_py} + +SPDK provides a set of Python scripts which can invoke the JSON-RPC methods described in this document. 'rpc.py' in the scripts +directory is the main script that users will invoke to execute a JSON-RPC method. The scripts/rpc directory contains modules +that 'rpc.py' imports for definitions of each SPDK library's or module's methods. + +Example: + +~~~ +scripts/rpc.py bdev_nvme_attach_controller -b nvme0 -a 00:02.0 -t pcie +~~~ + +A brief description of each of the RPC methods and optional 'rpc.py' arguments can be viewed with: + +~~~ +scripts/rpc.py --help +~~~ + +A detailed description of each RPC method and its parameters is also available. For example: + +~~~ +scripts/rpc.py bdev_nvme_attach_controller --help +~~~ + +### Generate JSON-RPC methods for current configuration + +An initial configuration can be specified for an SPDK application via the '-c' command line parameter. +The configuration file is a JSON file containing all of the JSON-RPC method invocations necessary +for the desired configuration. Writing these files by hand is extremely tedious however, so 'rpc.py' +provides a mechanism to generate a JSON-RPC file based on the current configuration. + +~~~ +scripts/rpc.py save_config > config.json +~~~ + +'config.json' can then be passed to a new SPDK application using the '-c' command line parameter +to reproduce the same configuration. + +### JSON-RPC batching + +'rpc.py' also supports batching of multiple JSON-RPC methods with one invocation. So instead of +calling 'rpc.py' once for each JSON-RPC method, such as: + +~~~ +scripts/rpc.py bdev_malloc_create -b malloc0 64 512 +scripts/rpc.py nvmf_create_subsystem nqn.2016-06.io.spdk:cnode1 -a +scripts/rpc.py nvmf_subsystem_add_ns nqn.2016-06.io.spdk:cnode1 malloc0 +scripts/rpc.py nvmf_create_transport -t tcp +scripts/rpc.py nvmf_subsystem_add_listener nqn.2016-06.io.spdk:cnode1 -t tcp -a 127.0.0.1 -s 4420 +~~~ + +you can put the following into a text file: + +~~~ +bdev_malloc_create -b malloc0 64 512 +nvmf_create_subsystem nqn.2016-06.io.spdk:cnode1 -a +nvmf_subsystem_add_ns nqn.2016-06.io.spdk:cnode1 malloc0 +nvmf_create_transport -t tcp +nvmf_subsystem_add_listener nqn.2016-06.io.spdk:cnode1 -t tcp -a 127.0.0.1 -s 4420 +~~~ + +and then just do: + +~~~ +scripts/rpc.py < rpc.txt +~~~ + +### Adding external RPC methods SPDK includes both in-tree modules as well as the ability to use external modules. The in-tree modules include some python scripts to ease the process of sending RPCs to in-tree modules. External modules can utilize this same framework to add new RPC