[PATCH v4 3/5] doc: add more documentation on bitmasks and sets

[Christoph Anton Mitterer <mail@christoph.anton.mitterer.name>]

Signed-off-by: Christoph Anton Mitterer <mail@christoph.anton.mitterer.name>
---
 doc/data-types.txt | 31 +++++++++++++++++++++++++++++++
 doc/nft.txt        |  5 +++++
 2 files changed, 36 insertions(+)

diff --git a/doc/data-types.txt b/doc/data-types.txt
index 18af266a..b36ca768 100644
--- a/doc/data-types.txt
+++ b/doc/data-types.txt
@@ -26,6 +26,37 @@ 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 generally the same as
+*'expression' {'bit'[,'bit']...}* and analogously with a named set.
+The latter forms are lookups in a set and will match only if the set contains
+exactly one value that matches.
+They are however effectively the same (with matching bitmasks typically being
+faster) when all bits are semantically mutually exclusive.
+
+Examples:
+* *tcp flags syn,ack* matches packets that have the SYN, the ACK or both SYN and
+  ACK flags set. Other flags are ignored.
+  *tcp flags { syn, ack }* matches packets that have either only the SYN or only
+  the ACK flag set. All other flags must be unset.
+* *ct state established,related* and *ct state { established, related } * match
+  exactly the same packets, because the bits of *ct state* are all mutually
+  exclusive.
+
+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 4cd3fa8e..4ae998ed 100644
--- a/doc/nft.txt
+++ b/doc/nft.txt
@@ -775,6 +775,11 @@ 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 (which for intervals means that it’s contained in any of them).
+See <<BITMASK TYPE>> for the subtle differences between syntactically similarly
+looking equiality checks of sets and bitmasks.
+
 MAPS
 -----
 [verse]
-- 
2.51.0