docs/command line: Clarify the behavior with invalid input.

docs/command line: Clarify the behavior with invalid input.

[Andrew Cooper]

[-- Attachment #1: Type: text/plain, Size: 207 bytes --]

A college asked me these questions after reading the html page, so I
guess others may wish to know.

-- 
Andrew Cooper - Dom0 Kernel Engineer, Citrix XenServer
T: +44 (0)1223 225 900, http://www.citrix.com


[-- Attachment #2: docs-cmdline.patch --]
[-- Type: text/x-patch, Size: 1915 bytes --]

# HG changeset patch
# Parent 1126b3079bef37e1bb5a97b90c14a51d4e1c91c3
docs/command line: Clarify the behavior with invalid input.

Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>

diff -r 1126b3079bef docs/misc/xen-command-line.markdown
--- a/docs/misc/xen-command-line.markdown
+++ b/docs/misc/xen-command-line.markdown
@@ -11,7 +11,8 @@ Hypervisor.
 ## Types of parameter
 
 Most parameters take the form `option=value`.  Different options on
-the command line should be space delimited.
+the command line should be space delimited.  All options are case
+sensitive, as are all values unless explicitly noted.
 
 ### Boolean (`<boolean>`)
 
@@ -68,6 +69,39 @@ Some options take a comma separated list
 Some parameters act as combinations of the above, most commonly a mix
 of Boolean and String.  These are noted in the relevant sections.
 
+## Unexpected input
+
+This information describes the behaviour with unexpected or malformed
+input, for reference purposes.  It is not expected to be used in any
+situation, nor relied upon.
+
+### Boolean
+
+* `<values>` other than those listed will invert the option, so take
+  its non-default value.
+
+* A `no-` prefix can be stacked with an explicit `=<value>`.
+ * A `no-<option>=0` will cancel, so the option takes its default
+   value.
+ * A `no-<option>=1` will invert the option, so take its non-default
+   value.
+
+### Integer
+
+Input which cannot be converted to a valid number will result in the
+parameter being set to 0.  Strings which start as a valid integer but
+contain invalid characters as a suffix will have the suffix ignored.
+
+### Size
+
+Unrecognised suffixes will be ignored, and the default suffix will be
+used.
+
+### Strings, Lists and Combinations
+
+Depending on implementation, strings may be truncated or ignored all
+together as if the option were not specified in the first place.
+
 ## Parameter details
 
 ### acpi

[-- Attachment #3: Type: text/plain, Size: 126 bytes --]

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
http://lists.xen.org/xen-devel

Re: docs/command line: Clarify the behavior with invalid input.

[Ian Campbell]

> @@ -68,6 +69,39 @@ Some options take a comma separated list
>  Some parameters act as combinations of the above, most commonly a mix
>  of Boolean and String.  These are noted in the relevant sections.
>  
> +## Unexpected input
> +
> +This information describes the behaviour with unexpected or malformed
> +input, for reference purposes.  It is not expected to be used in any
> +situation, nor relied upon.

We should document most of these as explicitly having Undefined
Behaviour (i.e. it might eat your dog). Writing down what the code
happens to do in the face of a nonsensical option isn't that useful.

Ian.

Re: docs/command line: Clarify the behavior with invalid input.

[Jan Beulich]

>>> On 31.08.12 at 16:55, Andrew Cooper <andrew.cooper3@citrix.com> wrote:

I don't think we should specifically document the behavior for
unexpected value; instead, the behavior should simply be
"undefined".

Jan

Re: (v2) docs/command line: Clarify the behavior with invalid input.

[Andrew Cooper]

[-- Attachment #1: Type: text/plain, Size: 393 bytes --]

On 31/08/12 16:36, Jan Beulich wrote:
>>>> On 31.08.12 at 16:55, Andrew Cooper <andrew.cooper3@citrix.com> wrote:
> I don't think we should specifically document the behavior for
> unexpected value; instead, the behavior should simply be
> "undefined".
>
> Jan
>

Yes ok.  v2 attached.

-- 
Andrew Cooper - Dom0 Kernel Engineer, Citrix XenServer
T: +44 (0)1223 225 900, http://www.citrix.com


[-- Attachment #2: docs-cmdline.patch --]
[-- Type: text/x-patch, Size: 1702 bytes --]

# HG changeset patch
# Parent 993922337bc1ceaac1054c31ba683af74e737cc1
docs/command line: Clarify the behavior with invalid input.

Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>

--
v2: State that invalid input is undefined, rather than describing the
current behaviour.

diff -r 993922337bc1 docs/misc/xen-command-line.markdown
--- a/docs/misc/xen-command-line.markdown
+++ b/docs/misc/xen-command-line.markdown
@@ -11,7 +11,8 @@ Hypervisor.
 ## Types of parameter
 
 Most parameters take the form `option=value`.  Different options on
-the command line should be space delimited.
+the command line should be space delimited.  All options are case
+sensitive, as are all values unless explicitly noted.
 
 ### Boolean (`<boolean>`)
 
@@ -35,6 +36,9 @@ Disable x2apic support (if present)
 Enable synchronous console mode
 > `sync_console`
 
+Explicitly specifying any value other than those listed above is
+undefined, as is stacking a `no-` prefix with an explicit value.
+
 ### Integer (`<integer>`)
 
 An integer parameter will default to decimal and may be prefixed with
@@ -42,6 +46,9 @@ a `-` for negative numbers.  Alternative
 used by prefixing the number with `0x`, or an octal number may be used
 if a leading `0` is present.
 
+Providing a string which does not validly convert to an integer is
+undefined.
+
 ### Size (`<size>`)
 
 A size parameter may be any integer, with a size suffix
@@ -51,7 +58,8 @@ A size parameter may be any integer, wit
 * `K` or `k`: Kilo (2^10)
 * `B` or `b`: Bytes
 
-Without a size suffix, the default will be kilo.
+Without a size suffix, the default will be kilo.  Providing a suffix
+other than those listed above is undefined.
 
 ### String
 

[-- Attachment #3: Type: text/plain, Size: 126 bytes --]

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
http://lists.xen.org/xen-devel

Re: (v2) docs/command line: Clarify the behavior with invalid input.

[Jan Beulich]

>>> On 31.08.12 at 18:49, Andrew Cooper <andrew.cooper3@citrix.com> wrote:
> On 31/08/12 16:36, Jan Beulich wrote:
>> I don't think we should specifically document the behavior for
>> unexpected value; instead, the behavior should simply be
>> "undefined".
> 
> Yes ok.  v2 attached.

Acked-by: Jan Beulich <jbeulich@suse.de>

Thanks.

Re: (v2) docs/command line: Clarify the behavior with invalid input.

[Ian Campbell]

On Mon, 2012-09-03 at 07:55 +0100, Jan Beulich wrote:
> >>> On 31.08.12 at 18:49, Andrew Cooper <andrew.cooper3@citrix.com> wrote:
> > On 31/08/12 16:36, Jan Beulich wrote:
> >> I don't think we should specifically document the behavior for
> >> unexpected value; instead, the behavior should simply be
> >> "undefined".
> > 
> > Yes ok.  v2 attached.
> 
> Acked-by: Jan Beulich <jbeulich@suse.de>

Applied, thanks.