Re: [PATCH v3 4/6] doc: add more documentation on bitmasks and sets

[Florian Westphal <fw@strlen.de>]

Christoph Anton Mitterer <mail@christoph.anton.mitterer.name> wrote:
> Signed-off-by: Christoph Anton Mitterer <mail@christoph.anton.mitterer.name>
> ---
>  doc/data-types.txt | 26 ++++++++++++++++++++++++++
>  doc/nft.txt        | 10 ++++++++++
>  2 files changed, 36 insertions(+)
> 
> diff --git a/doc/data-types.txt b/doc/data-types.txt
> index 18af266a..8a86060d 100644
> --- a/doc/data-types.txt
> +++ b/doc/data-types.txt
> @@ -26,6 +26,32 @@ integer
>  
>  The bitmask type (*bitmask*) is used for bitmasks.
>  
> +In expressions the bits of a bitmask may be specified as *'bit'[,'bit']...* with
> +'bit' being the value of the bit or a pre-defined symbolic constant, if any (for
> +example *ct state*’s bit 0x1 has the symbolic constant `new`).
> +
> +Equality of a value with such bitmask is given, if the value has any of the
> +bitmask’s bits set (and optionally others).
> +
> +The syntax *'expression' 'value' / 'mask'* is identical to
> +*'expression' and 'mask' == 'value'*.
> +For example `tcp flags syn,ack / syn,ack,fin,rst` is the same as
> +`tcp flags and (syn|ack|fin|rst) == syn|ack`.
> +
> +Note that *'expression' 'bit'[,'bit']...* is not the same as *'expression'
> +{'bit'[,'bit']...}* and analogously with a named set.
> +The latter constitute a lookup in a set and will match only if the set contains
> +exactly one value that matches.
> +For example: *tcp flags syn,ack* matches packets that have at least the flag SYN
> +, the flag ACK or the flags SYN and ACK set (regardless of whether or not any
> +other flags are set), whereas *tcp flags { syn, ack }* matches only packets that
> +have either only the flag SYN or only the flag ACK set (with all other flags
> +having to be not set).
> +See also <<SETS>> above.
> +
> +As usual, the the *nft describe* command may be used to get details on a data
> +type, which for bitmasks shows the symbolic names and values of the bits.
> +
>  STRING TYPE
>  ~~~~~~~~~~~~
>  [options="header"]
> diff --git a/doc/nft.txt b/doc/nft.txt
> index 363c67ba..09da6f28 100644
> --- a/doc/nft.txt
> +++ b/doc/nft.txt
> @@ -776,6 +776,16 @@ Example: When the set contains range *1.2.3.1-1.2.3.4*, then adding element *1.2
>  effect.  Adding *1.2.3.5* changes the existing range to cover *1.2.3.1-1.2.3.5*.
>  Without this flag, *1.2.3.2* can not be added and *1.2.3.5* is inserted as a new entry.
>  
> +Equality of a value with a set is given if the value matches exactly one value
> +in the set.

That contradicts whats right above, which describes range handling.

> +It shall be noted that for bitmask values this means, that
> +*'expression' 'bit'[,'bit']...* (which yields true if *any* of the bits are set)
> +is not the same as *'expression' {'bit'[,'bit']...}* (which yields true if
> +exactly one of the bits are set).
> +It may however be (effectively) the same, in cases like
> +`ct state established,related` and `ct state {established,related}`, where these
> +states are mutually exclusive.

Would you object if I apply this patch but onlt rhe first part?

I think the above just duplicates what is explained in the new
bitmask part above it.