diff --git a/doc/applications.md b/doc/applications.md index 5f37de6b3..82a542061 100644 --- a/doc/applications.md +++ b/doc/applications.md @@ -24,26 +24,27 @@ initialization and teardown path. The SPDK application framework defines a set of base command line flags for all applications that use it. Specific applications may implement additional flags. -Param | Type | Default | Description --------- | -------- | ---------------------- | ----------- --c | string | | @ref cmd_arg_config_file --d | flag | false | disable coredump file creation --e | integer | 0x0 | tracepoint group hexadecimal mask for SPDK trace buffers --g | flag | false | force creating just one hugetlbfs file --h | flag | false | show all available parameters and exit --i | integer | process PID | shared memory ID --m | CPU mask | 0x1 | application @ref cpu_mask --n | integer | all channels | number of memory channels used for DPDK --p | integer | first core in CPU mask | master (primary) core for DPDK --q | flag | false | disable notice level logging to `stderr` --r | string | /var/tmp/spdk.sock | RPC listen address --s | integer | all hugepage memory | memory size in MB for DPDK --u | flag | false | @ref cmd_arg_disable_pci_access. --w | flag | false | @ref cmd_arg_deferred_initialization --B | B:D:F | | @ref cmd_arg_pci_blacklist_whitelist. --W | B:D:F | | @ref cmd_arg_pci_blacklist_whitelist. --L | string | | @ref cmd_arg_debug_log_flags --f | string | | save pid to file under given path +Param | Long Param | Type | Default | Description +-------- | ---------------------- | -------- | ---------------------- | ----------- +-c | --config | string | | @ref cmd_arg_config_file +-d | --limit-coredump | flag | | +-e | --tpoint-group-mask | integer | 0x0 | +-g | --single-file-segments | flag | | @ref cmd_arg_single_file_segments +-h | --help | flag | | show all available parameters and exit +-i | --shm-id | integer | | @ref cmd_arg_multi_process +-m | --cpumask | CPU mask | 0x1 | application @ref cpu_mask +-n | --mem-channels | integer | all channels | number of memory channels used for DPDK +-p | --master-core | integer | first core in CPU mask | master (primary) core for DPDK +-r | --rpc-socket | string | /var/tmp/spdk.sock | RPC listen address +-s | --mem-size | integer | all hugepage memory | @ref cmd_arg_memory_size + | --silence-noticelog | flag | | disable notice level logging to `stderr` +-u | --no-pci | flag | | @ref cmd_arg_disable_pci_access. + | --wait-for-rpc | flag | | @ref cmd_arg_deferred_initialization +-B | --pci-blacklist | B:D:F | | @ref cmd_arg_pci_blacklist_whitelist. +-W | --pci-whitelist | B:D:F | | @ref cmd_arg_pci_blacklist_whitelist. +-R | --huge-unlink | flag | | @ref cmd_arg_huge_unlink +-L | --traceflag | string | | @ref cmd_arg_debug_log_flags + ### Configuration file {#cmd_arg_config_file} @@ -51,16 +52,16 @@ Historically, the SPDK applications were configured using a configuration file. This is still supported, but is considered deprecated in favor of JSON RPC configuration. See @ref jsonrpc for details. -Note that `-c` and `-w` cannot be used at the same time. +Note that `--config` and `--wait-for-rpc` cannot be used at the same time. ### Deferred initialization {#cmd_arg_deferred_initialization} SPDK applications progress through a set of states beginning with `STARTUP` and ending with `RUNTIME`. -If the `-w` parameter is provided SPDK will pause just before starting subsystem -initialization. This state is called `STARTUP`. The JSON RPC server is ready but -only a small subsystem of commands are available to set up initialization +If the `--wait-for-rpc` parameter is provided SPDK will pause just before starting +subsystem initialization. This state is called `STARTUP`. The JSON RPC server is +ready but only a small subsystem of commands are available to set up initialization parameters. Those parameters can't be changed after the SPDK application enters `RUNTIME` state. When the client finishes configuring the SPDK subsystems it needs to issue the @ref rpc_start_subsystem_init RPC command to begin the @@ -73,6 +74,30 @@ To see which RPC methods are available in the current state, issue the For more details see @ref jsonrpc documentation. +### Create just one hugetlbfs file {#cmd_arg_single_file_segments} + +Instead of creating one hugetlbfs file per page, this option makes SPDK create +one file per hugepagesz per socket. This is needed for @ref virtio to be used +with more than 8 hugepages. See @ref virtio_2mb. + +### Multi process mode {#cmd_arg_multi_process} + +When `--shm-id` is specified, the application is started in multi-process mode. +Applications using the same shm-id share their memory and +[NVMe devices](@ref nvme_multi_process). The first app to start with a given id +becomes a primary process, with the rest, called secondary processes, only +attaching to it. When the primary process exits, the secondary ones continue to +operate, but no new processes can be attached at this point. All processes within +the same shm-id group must use the same +[--single-file-segments setting](@ref cmd_arg_single_file_segments). + +### Memory size {#cmd_arg_memory_size} + +Total size of the hugepage memory to reserve. If DPDK env layer is used, it will +reserve memory from all available hugetlbfs mounts, starting with the one with +the highest page size. This option accepts a number of bytes with a possible +binary prefix, e.g. 1024, 1024M, 1G. The default unit is megabyte. + ### Disable PCI access {#cmd_arg_disable_pci_access} If SPDK is run with PCI access disabled it won't detect any PCI devices. This @@ -81,17 +106,22 @@ are not required in this mode. ### PCI address blacklist and whitelist {#cmd_arg_pci_blacklist_whitelist} -Note that `-B` and `-W` cannot be used at the same time. +If blacklist is used, then all devices with the provided PCI address will be +ignored. If a whitelist is used, only whitelisted devices will be probed. +`-B` or `-W` can be used more than once, but cannot be mixed together. That is, +`-B` and `-W` cannot be used at the same time. -If a blacklist is used all devices with the provided PCI address will be -ignored. If a whitelist is used only those devices will be probed. You can used -`-B` or `-W` more than once to add more than one device to list. +### Unlink hugepage files after initialization {#cmd_arg_huge_unlink} -### Debug log flags {#cmd_arg_debug_log_flags} +By default, each DPDK-based application tries to remove any orphaned hugetlbfs +files during its initialization. This option removes hugetlbfs files of the current +process as soon as they're created, but is not compatible with `--shm-id`. -Use a comma separated list of flags or use `-L all` to enable all debug flags. -Run SPDK application with `-h` to get a list of all valid flags. Debug flags are -only available in debug builds of SPDK. +### Debug log {#cmd_arg_debug_log_flags} + +Enable a specific debug log type. This option can be used more than once. A list of +all available types is provided in the `--help` output, with `--traceflag all` +enabling all of them. Debug logs are only available in debug builds of SPDK. ## CPU mask {#cpu_mask} diff --git a/lib/event/app.c b/lib/event/app.c index 543df7790..a8dd3c782 100644 --- a/lib/event/app.c +++ b/lib/event/app.c @@ -681,7 +681,6 @@ usage(void (*app_usage)(void)) printf(" -m, --cpumask core mask for DPDK\n"); printf(" -n, --mem-channels channel number of memory channels used for DPDK\n"); printf(" -p, --master-core master (primary) core for DPDK\n"); - printf(" --silence-noticelog disable notice level logging to stderr\n"); printf(" -r, --rpc-socket RPC listen address (default %s)\n", SPDK_DEFAULT_RPC_ADDR); printf(" -s, --mem-size memory size in MB for DPDK (default: "); if (g_default_opts.mem_size > 0) { @@ -689,8 +688,9 @@ usage(void (*app_usage)(void)) } else { printf("all hugepage memory)\n"); } + printf(" --silence-noticelog disable notice level logging to stderr\n"); printf(" -u, --no-pci disable PCI access\n"); - printf(" -w, --wait-for-rpc wait for RPCs to initialize subsystems\n"); + printf(" --wait-for-rpc wait for RPCs to initialize subsystems\n"); printf(" -B, --pci-blacklist \n"); printf(" pci addr to blacklist (can be used more than once)\n"); printf(" -R, --huge-unlink unlink huge files after initialization\n");