Note: This is a beta release of Red Hat Bugzilla 5.0. The data contained within is a snapshot of the live data so any changes you make will not be reflected in the production Bugzilla. Also email is disabled so feel free to test any aspect of the site that you want. File any problems you find or give feedback here.
Bug 1512155 - VDO documentation omits "--vdoHashZoneThreads" option
Summary: VDO documentation omits "--vdoHashZoneThreads" option
Keywords:
Status: CLOSED CURRENTRELEASE
Alias: None
Product: Red Hat Enterprise Linux 7
Classification: Red Hat
Component: doc-Storage_Administration_Guide
Version: 7.5
Hardware: Unspecified
OS: Unspecified
unspecified
unspecified
Target Milestone: rc
: ---
Assignee: Marek Suchanek
QA Contact: Zhang Kexin
URL:
Whiteboard:
Depends On:
Blocks: 1552784 1495322
TreeView+ depends on / blocked
 
Reported: 2017-11-11 01:26 UTC by Ken Raeburn
Modified: 2019-03-06 02:20 UTC (History)
1 user (show)

Fixed In Version:
Doc Type: If docs needed, set a value
Doc Text:
Clone Of:
Environment:
Last Closed: 2018-03-16 17:05:59 UTC


Attachments (Terms of Use)

Description Ken Raeburn 2017-11-11 01:26:03 UTC
The VDO documentation (DocBook version, at least) omits a new option recently added to the command-line interface.

The "vdo" subcommands "create" and "modify" accept a new option "--vdoHashZoneThreads=<number>".

The nroff documentation added to the man page for the option says:

.B \-\-vdoHashZoneThreads=\fIthread count\fR
Specifies the number of threads across which to
subdivide parts of the VDO processing based on the
hash value computed from the block data. The default is 1;
the value must be at least 0 and less than or equal to 100.
vdoHashZonesThreads, vdoLogicalThreads and vdoPhysicalThreads
must be either all zero or all non-zero.

The DocBook version doesn't appear to describe the default, allowed range, or combined zero/nonzero constraints for --vdoLogicalThreads and --vdoPhysicalThreads, so either that part can be left out, or it should be added to the others (--vdoPhysicalThreads is limited to 16, --vdoLogicalThreads to 100) to keep them in similar form.

Comment 2 Ken Raeburn 2017-11-11 01:38:42 UTC
I noticed when submitting the description above that "vdoHashZonesThreads" in the last sentence of the man-page text should be "vdoHashZoneThreads" instead (no "s" after "zones"). So, just in case you do use that part of the text...

Comment 3 Marek Suchanek 2017-11-13 10:20:34 UTC
Hello Ken,

Thanks for reporting this. I'm setting this bug as a blocker for our main VDO docs bug.

Marek

Comment 4 Marek Suchanek 2018-02-09 17:10:25 UTC
I've added the option and references to it to match the current vdo man page.

See the built preview:
https://access.qa.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/storage_administration_guide/vdo-ig-commands#vdo_opt_vdoHashZoneThreads

The man page describes the option in a slightly different way than what you suggest, so could you please check if it's correct?

Also, the typos are now fixed.

Comment 5 Ken Raeburn 2018-02-21 01:34:34 UTC
It looks like you've changed the numbers, and I don't think they're correct. The minimum is 0 (with the constraint about other parameters also being zero or nonzero), and the default is 1.

Comment 6 Marek Suchanek 2018-02-21 20:15:44 UTC
I actually copied the description from the current vdo(8) man page, which says:

> --vdoHashZoneThreads=thread count
> 
> Specifies the number of threads across which to subdivide  parts
> of  the VDO processing based on the hash value computed from the
> block data. The value must be at least 1 and less than or  equal
> to  100.  vdoHashZonesThreads,  vdoLogicalThreads  and vdoPhysi‐
> calThreads must be either all zero or all non-zero. The  default
> is 2.

I'm happy with changing the values in the documentation, but I just wanted to point out that the man page is probably wrong in that case.

Comment 7 Ken Raeburn 2018-02-21 23:18:18 UTC
Ah, I see. It looks like the values for vdoHashZoneThreads were erroneously copied from vdoCpuThreads when a rewrite of the man page was done recently. The values there are wrong. (And inconsistent: It says vdoHashZoneThreads can be 0 if two other parameters are 0, but also says it must be at least 1.)

The program requires 0-100 and defaults to 1. The help message output by the program appears to have the correct values.

I've just opened bug 1547786 for the man page issue.

Comment 8 Marek Suchanek 2018-03-05 16:58:46 UTC
I've updated the description of the vdoHashZoneThreads option in the documentation to what you suggested in comment#0. See the built preview:
https://access.qa.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/storage_administration_guide/vdo-ig-commands#vdo_opt_vdoHashZoneThreads

Thanks for opening the man page bug. If there's anything more to do, please let me know.

Comment 9 Ken Raeburn 2018-03-07 19:52:19 UTC
The new text looks correct, thanks.

Minor nit-picking: It says "vdoHashZoneThreads, vdoLogicalThreads and vdoPhysicalThreads must...", whereas the other two say, "The vdoHashZoneThreads, vdoLogicalThreads, and vdoPhysicalThreads options must be either all zero or all non‐zero."

I'm not sure the latter is the best wording, either; strictly speaking, I'd say "the vdoHashZoneThreads option" refers to the argument "--vdoHashZoneThreads=3" or whatever, not just the number, so the "option" isn't a numeric value. Perhaps the option is *given* or *set to* a numeric value, or we could refer to the vdoHashZoneThreads *value*. But now I'm really getting picky. :-)

Comment 10 Marek Suchanek 2018-03-16 17:05:59 UTC
Ken,
your nitpicking is right: the descriptions were inconsistent and it's questionable whether those values can be called "options". I'm removing "options" so that the documentation is identical to what the man page says.

As a side note, the VDO documentation is now published on the Customer Portal. See here for the section that includes the description of "--vdoHashZoneThreads":
https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/storage_administration_guide/vdo-ig-commands#vdo_opt_vdoHashZoneThreads

I'm closing this bug as CURRENTRELEASE.

Thanks for your help!


Note You need to log in before you can comment on or make changes to this bug.