admin-passthru duplicate -o command line options

[david-okamoto-wdc]

Command line short option "-o" is used twice for the admin-passthru command. I think this is a bug.
--output-format=<FMT>, -o <FMT> and --opcode=<NUM>, -o <NUM>

[ikegami-t]

The PR #2090 changes fix this issue but -o for --opcode will be changed to -O.

[igaw]

I've merged #2090. I still hope our move to make -o the shorthand for --output globally is not making too much troubles.

[david-okamoto-wdc]

Thank you and no trouble at all.

[ZiqiangYoung]

I've merged #2090. I still hope our move to make -o the shorthand for --output globally is not making too much troubles.

Hi nvme-cli maintainers,

First of all, thank you for your continued work on this critical tool. I wanted to provide some feedback regarding a recent change that may unintentionally affect backward compatibility.

The case-sensitive parameter distinction between lowercase -O (opcode) and uppercase -o (output-format) appears to be causing silent failures in legacy environments. Specifically:

1. Existing vendor command (admin-passthru) documentation using 0xFF formatted opcodes are now being parsed by output-format without errors
2. Numerous archived scripts and monitoring tools have begun failing due to this case sensitivity
3. Community members are being forced to downgrade versions for consistency

Observed Impacts:

• Copy-pasted commands from historical documentation now require manual parameter correction
• Automated test systems using older script are reporting false negatives
• Confusion in user forums about "version compatibility requirements"

Suggested Resolution Paths:

1. Consider adding deprecated parameter aliases during transition period
2. Implement strict validation for output-format values to detect numeric opcodes
3. Update man pages with explicit case sensitivity warnings

This is absolutely not about assigning blame - I fully understand the challenges of maintaining CLI parameter space. My goal is to help preserve the tool's legendary stability while enabling necessary evolution.

Would be happy to help test any compatibility patches if useful.

Best regards

[ikegami-t]

Very sorry for this issue. Just FYI: The PR changes #2556 closed without merging before related to this issue.

[igaw]

Thanks for your feedback.

Suggested Resolution Paths:

1. Consider adding deprecated parameter aliases during transition period

2. Implement strict validation for output-format values to detect numeric opcodes

3. Update man pages with explicit case sensitivity warnings

1. It's a bit hard to do for short options. But we can definitively do that for the long options.
2. I think we have moved all the output format code to a central place. Need to check if we covered all the commands now
3. Yes, that would make a sense.

BTW, there is the wiki we can also documet these things, e.g. in the FAQ section: https://github.com/linux-nvme/nvme-cli/wiki

[ikegami-t]

• Existing vendor command (admin-passthru) documentation using 0xFF formatted opcodes are now being parsed by output-format without errors

Could you please show me the actual command behavior log? If possible I would like to confirm the root cause for the issue.

[ZiqiangYoung]

• Existing vendor command (admin-passthru) documentation using 0xFF formatted opcodes are now being parsed by output-format without errors

Could you please show me the actual command behavior log? If possible I would like to confirm the root cause for the issue.

I cannot provide the exact command as it involves proprietary vendor-specific commands, but I can describe the general format:

nvme admin-passthru /dev/nvme0 -o 0xFF -4 0xFFFF -6 0xFFFFFF -l 4096 -i ~/xxxx -w

The tool incorrectly interpreted -o as output-format (instead of expecting an opcode), yet executed successfully. The response echoed something like "Admin Delete SQ Success ret 0x00000" (I apologize for being unsure whether it was SQ or CQ, i forgot it.).

Important Notes:

1. This is reconstructed from brain — I currently do not have access to the corporate environment.
2. I can attempt to reproduce this tomorrow if needed.
3. Proposal: Would it be better to explicitly throw an error when the opcode is not received (e.g., alert users about the -o/-O case sensitivity breaking change)?

This is just my personal suggestion for your consideration. Thank you!

[ikegami-t]

Thank you for your information. The latest nvme-cli outputs the error message Invalid output format as below. In this case the issue resolved?

tokunori@tokunori-desktop:~/nvme-cli$ nvme-build admin-passthru /dev/nvme0 -o 0xFF -4 0xFFFF -6 0xFFFFFF -l 4096 -i ~/xxxx -w
[sudo] tokunori のパスワード: 
Invalid output format

Since currently the option -o parameter value checked by the funtion below.

int validate_output_format(const char *format, nvme_print_flags_t *flags)
{
	nvme_print_flags_t f;

	if (!format)
		return -EINVAL;

	if (!strcmp(format, "normal"))
		f = NORMAL;
#ifdef CONFIG_JSONC
	else if (!strcmp(format, "json"))
		f = JSON;
#endif /* CONFIG_JSONC */
	else if (!strcmp(format, "binary"))
		f = BINARY;
	else
		return -EINVAL;

	*flags = f;

	return 0;
}

[igaw]

The -o is the shorthand for --output and for the opcode argument the shorthand is -O. If non is provided then the opcode is 0 and this is the 'Delete I/O Submission Queue'.

Yes, we could make the --opcode argument mandatory. This makes sense. Let's open this issue for this again.

As explained, I don't want to switch back to the --opcode/-o mapping. For scripting I suggest to use the long options only.

What we could do is when the -o/--output doesn't see either normal, json or binary we could issue a warning. But I think we should make this only for the commands which used to have the -o option before.

[ikegami-t]

Yes, we could make the --opcode argument mandatory. This makes sense. Let's open this issue for this again.

The PR #2786 fixes to check the --opcode argument mandatory.

[igaw]

I think there is not much we can do as explained above. The documentation is updated thanks @ikegami-t .