doc: document the sparse's extensions

First try at documenting sparse's extensions to C's type system.

Signed-off-by: Luc Van Oostenryck <luc.vanoostenryck@gmail.com>

2 files changed, 86 insertions, 0 deletions

diff --git a/Documentation/annotations.rst b/Documentation/annotations.rst
new file mode 100644
index 00000000..d4b5546f
--- /dev/null
+++ b/Documentation/annotations.rst
@@ -0,0 +1,85 @@
+Annotations
+===========
+
+Sparse extends C's type system with a number of extra type qualifiers
+which add restrictions on what you can do on objects annotated with them.
+These qualifiers are specified with GCC's ``__attribute__`` syntax.
+
+address_space(*name*)
+---------------------
+This attribute is to be used on pointers to specify that its target is
+in address space *name* (an identifier or a constant integer).
+
+Sparse treats pointers with different address spaces as distinct types
+and will warn on casts (implicit or explicit) mixing the address spaces.
+An exception to this is when the destination type is ``uintptr_t`` or
+``unsigned long`` since the resulting integer value is independent
+of the address space and can't be dereferenced without first casting
+it back to a pointer type.
+
+bitwise
+-------
+This attribute is to be used to define new, unique integer types that
+cannot be mixed with other types. In particular, you can't mix a
+"bitwise" integer with a normal integer expression, and you can't even
+mix it with another bitwise expression of a different type.
+The integer 0 is special, though, and can be mixed with any bitwise type
+since it's safe for all bitwise operations.
+
+Since this qualifier defines new types, it only makes sense to use
+it in typedefs, which effectively makes each of these typedefs
+a single "bitwise class", incompatible with any other types.
+
+context(*ctxt*, *entry*, *exit*)
+--------------------------------
+This attribute is to be used on function declarations to specify
+the function's entry and exit count for a given context. This
+context can be pretty much anything that can be counted.
+
+Sparse will check that the function's entry and exit contexts match, and
+that no path through a function is ever entered with conflicting contexts.
+In particular, it is designed for doing things like matching up a "lock"
+with the pairing "unlock". For example, a function doing a lock should be
+annotated with an entry value of 0 and an exit value of 1, the corresponding
+unlock function should use the values 1 and 0, and a function that should
+only be called on some locked data, release the lock but which doesn't exit
+without reacquiring the lock being, should use entry and exit values of 1.
+
+The first argument, *ctxt*, is an expression only used as documentation
+to identify the context. Usually, what is used is a pointer to the structure
+containing the context, for example, the structure protected by the lock.
+
+See also https://lwn.net/Articles/109066/.
+
+noderef
+-------
+This attribute is to be used on a r-value to specify it cannot be
+dereferenced. A pointer so annotated is in all other aspects exactly
+like a pointer  but trying to actually access anything through it will
+cause a warning.
+
+nocast
+------
+This attribute is similar to ``bitwise`` but in a much weaker form.
+It warns about explicit or implicit casting to different types.
+However, it doesn't warn about the mixing with other types and it easily
+gets lost: you can add plain integers to __nocast integer types and the
+result will be plain integers.
+So, it ends to be more useful for big integers that still need to act
+like integers, but you want to make it much less likely that they get
+truncated by mistake. For example, a 64-bit integer that you don't want
+to mistakenly/silently be returned as int.
+
+See also `Linus' e-mail about __nocast vs __bitwise
+<https://lore.kernel.org/linux-mm/CA+55aFzbhYvw7Am9EYgatpjTknBFm9eq+3jBWQHkSCUpnb3HRQ@mail.gmail.com/>`_.
+
+safe
+----
+This attribute specifies that the object, which should be a pointer,
+is defined to never be NULL or nontrapping.
+It causes a warning if the object is tested in a conditional.
+
+force
+-----
+This attribute is to be used in casts to suppress warnings that would
+otherwise be caused by the presence of one of these extra qualifiers.
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 737f4423..9c76419b 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -68,6 +68,7 @@ User documentation
 .. toctree::
    :maxdepth: 1
 
+   annotations
    nocast-vs-bitwise
 
 Developer documentation