On 10/15/2014 10:10 PM, Rufe Glick wrote:
On Tue, Oct 14, 2014 at 9:02 PM, Andy Grover <agrover@xxxxxxxxxx> wrote:
On 10/13/2014 08:37 PM, Rufe Glick wrote:
Do you have some specific parameters that you think we should document
better? Docs certainly could be made comprehensive, but it would help to
know where to focus first.
Regards -- Andy
I'm probably being pedantic here, but I think that every configurable
parameter in the targetcli should be described. For example, when I
enter 'get attribute' and hit Tab in TPG context I see a list of
suggested parameters. default_cmdsn, netif_timeout, cache_dynamic_acls
are among them. But the man page doesn't say a word about what these
are for. In the same context I enter 'get parameter', hit Tab and see
another large list of parameters. I have no idea what those are for
and the man page is of no help there.
Agreed.
Improvement on that front is one of the goals of the 3.x series.
One of the problems to document attributes, parameters and the type of
their values is that targetcli and rtslib are generic. They are made to
work with drop-in 3rd party modules, and to some extent with different
kernel modules versions.
In the 2.x series, the 3rd party modules have to provide a specfile,
that describes the WWN format, how to assemble a list of legal WWNs (in
case of hardware fabric adapters), the name of the kernel module to
load, and the SCSI target functionalities that are implemented (single
or multiple TPG per target, support for ACLs, etc.).
This has been extended in 3.x series with the introduction of policy
files. Policy files do not replace (yet) specfiles, but provide a full
grammar of the object tree supported by a fabric modules and core
backends, along with the type expected for legal values. This allows for
type-checking, extended inline completion help and 2-step
edit-and-commit configuration. Note that there are provisions to allow
usage of unknown attributes supported by the running kernel modules, in
which case we fallback to a generic type.
The policy files (which have the same syntax as the configuration files,
only extending it a little) also support comments, and the parser knows
how to relate a comment to a policy rule.
For now, this is neither used or exposed. But in the future, the idea is
to allow comments to contains short documentation strings for any part
of the policy rules. Also, I would like to introduce a syntax for
pointing at external help files from the policy files.
Best,
--
Jerome
--
To unsubscribe from this list: send the line "unsubscribe target-devel" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
