From b3bd7abb67c698280f90b1ef17ba3aaed2bc9c70 Mon Sep 17 00:00:00 2001 From: Keith Busch Date: Mon, 1 Dec 2014 10:31:47 -0700 Subject: [PATCH] NVMe: Add additional help documentation Added: fw-download fw-activate format io-passthru Signed-off-by: Keith Busch --- ...assthrough.txt => nvme-admin-passthru.txt} | 0 Documentation/nvme-format.txt | 99 +++++++++++++++++ Documentation/nvme-fw-activate.txt | 78 ++++++++++++++ Documentation/nvme-fw-download.txt | 68 ++++++++++++ Documentation/nvme-help.txt | 2 +- Documentation/nvme-io-passthru.txt | 101 ++++++++++++++++++ nvme.c | 11 +- 7 files changed, 355 insertions(+), 4 deletions(-) rename Documentation/{nvme-admin-passthrough.txt => nvme-admin-passthru.txt} (100%) create mode 100644 Documentation/nvme-format.txt create mode 100644 Documentation/nvme-fw-activate.txt create mode 100644 Documentation/nvme-fw-download.txt create mode 100644 Documentation/nvme-io-passthru.txt diff --git a/Documentation/nvme-admin-passthrough.txt b/Documentation/nvme-admin-passthru.txt similarity index 100% rename from Documentation/nvme-admin-passthrough.txt rename to Documentation/nvme-admin-passthru.txt diff --git a/Documentation/nvme-format.txt b/Documentation/nvme-format.txt new file mode 100644 index 00000000..db6baa07 --- /dev/null +++ b/Documentation/nvme-format.txt @@ -0,0 +1,99 @@ +nvme-help(1) +============= + +NAME +---- +nvme-format - Format an NVMe device + +SYNOPSIS +-------- +[verse] +'nvme format' [--namespace-id= | -n ] + [--lbaf= | -l ] + [--ses= | -s ] + [--pil= | -p ] + [--pi= | -i ] + [--ms= | -m ] + +DESCRIPTION +----------- +For the NVMe device given, send an nvme Format Namespace admin command +and provides the results. + +The parameter is mandatory and may be either the NVMe character +device (ex: /dev/nvme0), or a namespace block device (ex: /dev/nvme0n1). +If the character device is given, the namespace identifer will default +to 0xffffffff to send the format to all namespace, but can be overridden +to any namespace with the 'namespace-id' option. If the block device +is given, the namespace identifier will default to the namespace id of +the block device given, but can be overriden with the same option. + +On success, the program will automatically issue BLKRRPART ioctl to +force rescanning the namespaces. If the driver is recent enough, this +will automatically update the physical block size. If it is not recent +enough, you will need to remove and rescan your device some other way +for the new block size to be visible. + +OPTIONS +------- +-n :: +--namespace-id=:: + Send the format command for the specified nsid. This can be + used to override the default value for either character device + (0xffffffff) or the block device (result from NVME_IOCTL_ID). + +-l :: +--lbaf=:: + LBA Format: This field specifies the LBA format to apply to the NVM + media. This corresponds to the LBA formats indicated in the + Identify Namespace command. Defaults to 0. + +-s :: +--ses=:: + Secure Erase Settings: This field specifies whether a secure + erase should be performed as part of the format and the type of + the secureerase operation. The erase applies to all user data, + regardless of location (e.g., within an exposed LBA, within a + cache, within deallocated LBAs, etc). Defaults to 0. + +-p :: +--pil=:: + Protection Information Location: If set to ‘1’ and protection + information is enabled, then protection information is transferred + as the first eight bytes of metadata. If cleared to ‘0’ and + protection information is enabled, then protection information + is transferred as the last eight bytes of metadata. Defaults to 0. + +-i :: +--pi=:: + Protection Information: This field specifies whether end-to-end + data protection is enabled and the type of protection + information. Defaults to 0. + +-m :: +--ms=:: + Metadata Settings: This field is set to ‘1’ if the metadata + is transferred as part of an extended data LBA. This field is + cleared to ‘0’ if the metadata is transferred as part of a + separate buffer. The metadata may include protection information, + based on the Protection Information (PI) field. Defaults to 0. + +EXAMPLES +-------- +* Format the device using all defaults: ++ +------------ +# nvme format /dev/nvme0n1 +------------ ++ + +* Format namespace 1 with user data secure erase settings and protection +information: ++ +------------ +# nvme format /dev/nvme0 --namespace-id=1 --ses=1 --pi=1 +------------ + +NVME +---- +Part of the nvme-user suite diff --git a/Documentation/nvme-fw-activate.txt b/Documentation/nvme-fw-activate.txt new file mode 100644 index 00000000..e64fae5a --- /dev/null +++ b/Documentation/nvme-fw-activate.txt @@ -0,0 +1,78 @@ +nvme-help(1) +============= + +NAME +---- +nvme-fw-activate - Used to verify and commit a firmware image. + +SYNOPSIS +-------- +[verse] +'nvme fw-activate' [--slot= | -s ] + [--action= | -a ] + +DESCRIPTION +----------- +For the NVMe device given, send an nvme Firmware Activate admin command +and provides the results. + +The Firmware Activate command is used to verify that a valid firmware +image has been downloaded and to commit that revision to a specific +firmware slot. The host may select the firmware image to activate on the +next controller reset (CC.EN transitions from ‘1’ to ‘0’, a PCI +function level reset, and/or other Controller or NVM Subsystem Reset) +as part of this command. The currently executing firmware revision may +be determined from the Firmware Revision field of the Identify Controller +data structure as indicated in the Firmware Slot Information log page. + +No further action is automatically taken to reset the device, which is +usually required to complete the activation process. If your kernel and +driver are recent enough, you can activate the firmware by issuing a +reset through Linux sysfs, for example: + +------------ + # echo 1 > /sys/class/misc/nvme0/device/reset +------------ + +If your kernel is not recent enough, you will need to remove and add +the device some other way. + +OPTIONS +------- +-a :: +--action=:: + Activate Action: This field specifies the action that is taken + on the image downloaded with the Firmware Image Download command + or on a previously downloaded and placed image. ++ +[] +|================= +|Value|Definition +|0|Downloaded image replaces the image indicated by the Firmware Slot +field. This image is not activated. +|1|Downloaded image replaces the image indicated by the Firmware Slot +field. This image is activated at the next reset. +|2|The image indicated by the Firmware Slot field is activated at the +next reset. +|3|Reserved. +|================= + +-s :: +--slot=:: + Firmware Slot: Specifies the firmware slot that shall be used for + the Activate Action, if applicable. If the value specified is 0h, + then the controller shall choose the firmware slot (slot 1 – 7) + to use for the operation. + +EXAMPLES +-------- +* Activate the last downloaded fw to slot 1. ++ +------------ +# nvme fw-activate /dev/nvme0 --slot=1 --action=2 +------------ + + +NVME +---- +Part of the nvme-user suite diff --git a/Documentation/nvme-fw-download.txt b/Documentation/nvme-fw-download.txt new file mode 100644 index 00000000..a842a614 --- /dev/null +++ b/Documentation/nvme-fw-download.txt @@ -0,0 +1,68 @@ +nvme-help(1) +============= + +NAME +---- +nvme-fw-download - Download all or a portion of an nvme firmware image. + +SYNOPSIS +-------- +[verse] +'nvme fw-download' [--fw= | -f ] + [--xfer= | -x ] + [--offset= | -o ] + +DESCRIPTION +----------- +The Firmware Image Download command is used to download all or a portion +of the firmware image for a future update to the controller. The Firmware +Image Download command may be submitted while other commands on the Admin +Submission Queue or I/O Submission Queues are outstanding. The Firmware +Image Download command copies the new firmware image (in whole or in part) +to the controller. + +The firmware image may be constructed of multiple pieces that +are individually downloaded with separate Firmware Image Download +commands. Each Firmware Image Download command includes a Dword +Offset and Number of Dwords that specify a Dword range. The host +software shall ensure that firmware pieces do not have Dword ranges +that overlap. Firmware portions may be submitted out of order to the +controller. + +The new firmware image is not applied as part of the Firmware Image +Download command. It is applied following a reset, where the image to +apply and the firmware slot it should be committed to is specified with +the Firmware Activate command. + +OPTIONS +------- +-f :: +--fw=:: + Required argument. This specifies the path to the device's + firmware file on your system that will be read by the program + and sent to the device. + +-x :: +--xfer=:: + This specifies the size to split each transfer. This is useful if + the device has a max transfer size requirement for firmware. It + defaults to 4k. + +-o :: +--offset=:: + This specifies the starting offset in dwords. This is really only + useful if your firmware is split in multiple files; otherwise + the offset starts at zero and automatically adjusts based on the + 'xfer' size given. + +EXAMPLES +-------- +* Transfer a firmware size 128KiB at a time: ++ +------------ +# nvme fw-download /dev/nvme0 --fw=/path/to/nvme.fw --xfer=0x20000 +------------ + +NVME +---- +Part of the nvme-user suite diff --git a/Documentation/nvme-help.txt b/Documentation/nvme-help.txt index 24887a57..0c0c4cd8 100644 --- a/Documentation/nvme-help.txt +++ b/Documentation/nvme-help.txt @@ -8,7 +8,7 @@ nvme-help - Help information. SYNOPSIS -------- [verse] -'nvme help' +'nvme help' [] DESCRIPTION ----------- diff --git a/Documentation/nvme-io-passthru.txt b/Documentation/nvme-io-passthru.txt new file mode 100644 index 00000000..39c12595 --- /dev/null +++ b/Documentation/nvme-io-passthru.txt @@ -0,0 +1,101 @@ +nvme-admin-passthru(1) +====================== + +NAME +---- +nvme-io-passthru - Submit an arbitrary io command, return results + +SYNOPSIS +-------- +[verse] +'nvme-io-passthru' [--opcode= | -o ] + [--flags= | -f ] [-rsvd= | -R ] + [--namespace-id= | -nsid ] + [--cdw2=] [--cdw3=] [--cdw10=] + [--cdw11=] [--cdw12=] [--cdw13=] + [--cdw14=] [--cdw15=] + [--data-len= | -l ] + [--metadata-len= | -m ] + [--read | -r ] [--write | -w] + [--input-file= | -f ] + [--timeout= | -t ] + [--show-command | --dry-run | -s] + [--raw-binary | -b] + +DESCRIPTION +----------- +Submits an arbitrary NVMe IO command and returns the applicable +results. This may be the simply the commands result and status, or may +also include a buffer if the command returns one. This command does no +interpretation of the opcodes or options. + +The parameter is mandatory and may be either the NVMe character +device (ex: /dev/nvme0), or a namespace block device (ex: /dev/nvme0n1). + +On success, the returned structure (if applicable) may be returned in +one of several ways depending on the option flags; the structure may +printed by the program as a hex dump, or may be returned as a raw buffer +printed to stdout for another program to parse. + +OPTIONS +------- +-o :: +--opcode=:: + The NVMe opcode to send to the device in the command + +-f :: +--flags=:: + The NVMe command flags to send to the device in the command + +-R :: +--rsvd=:: + The value for the reserved field in the command. + +-n :: +--namespace-id=:: + The value for the ns-id in the command. + +--cdw[2-3,10-15]=:: + Specifies the command dword value for that specified entry in + the command + +-r:: +--read:: +-w:: +--write:: + Used for the data-direction for the command and required for + commands sending/receiving data. Don't use both read and write + at the same time. + +-i :: +--input-file=:: + If the command is a data-out (write) command, use this file + to fill the buffer sent to the device. If no file is given, + assumed to use STDIN. + +-l :: +--data-len=:: + The data length for the buffer used for this command. + +-m :: +--metadata-len=:: + The metadata length for the buffer used for this command. + +-s:: +--show-cmd:: +--dry-run:: + Do not actually send the command; print out the command that + would be sent. + +-b:: +--raw-binary:: + Print the raw returned buffer to stdout if the command returns + data or a structure. + +EXAMPLES +-------- +No examples yet. + +NVME +---- +Part of the nvme-user suite diff --git a/nvme.c b/nvme.c index 094aa8c7..e5443c18 100644 --- a/nvme.c +++ b/nvme.c @@ -871,10 +871,11 @@ static int fw_download(int argc, char **argv) static struct option opts[] = { {"fw", required_argument, 0, 'f'}, {"xfer", required_argument, 0, 'x'}, + {"offset", required_argument, 0, 'o'}, { 0, 0, 0, 0} }; - while ((opt = getopt_long(argc, (char **)argv, "x:f:", opts, + while ((opt = getopt_long(argc, (char **)argv, "x:f:o:", opts, &long_index)) != -1) { switch (opt) { case 'f': @@ -883,6 +884,10 @@ static int fw_download(int argc, char **argv) case 'x': get_int(optarg, &xfer_size); break; + case 'p': + get_int(optarg, &offset); + offset <<= 2; + break; default: return EINVAL; } @@ -902,11 +907,11 @@ static int fw_download(int argc, char **argv) fw_size = sb.st_size; if (fw_size & 0x3) { fprintf(stderr, "Invalid size:%d for f/w image\n", fw_size); - return 1; + return EINVAL; } if (posix_memalign(&fw_buf, getpagesize(), fw_size)) { fprintf(stderr, "No memory for f/w size:%d\n", fw_size); - exit(ENOMEM); + return ENOMEM; } if (xfer_size % 4096) xfer_size = 4096; -- 2.50.1