Merge branch 'doc-annot'

* improve presentation of the doc, mainly the sidebar

6 files changed, 113 insertions, 66 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 50afa558..4047343a 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -63,42 +63,28 @@ To subscribe to the list, send an email with
 Bugs can also be reported and tracked via the `Linux kernel's bugzilla for sparse
 <https://bugzilla.kernel.org/enter_bug.cgi?component=Sparse&product=Tools>`_.
 
-User documentation
-------------------
-.. toctree::
-   :maxdepth: 1
 
-   nocast-vs-bitwise
-
-Developer documentation
------------------------
 .. toctree::
+   :caption: Documentation
    :maxdepth: 1
 
-   test-suite
+   annotations
    dev-options
+   types
    api
    IR
-   types
+   test-suite
+   doc-guide
 
-How to contribute
------------------
 .. toctree::
+   :caption: How to contribute
    :maxdepth: 1
 
    submitting-patches
    TODO
 
-Documentation
--------------
-.. toctree::
-   :maxdepth: 1
-
-   doc-guide
-
-Release Notes
--------------
 .. toctree::
+   :caption: Release Notes
    :maxdepth: 1
 
    release-notes/index
diff --git a/Documentation/nocast-vs-bitwise.md b/Documentation/nocast-vs-bitwise.md
deleted file mode 100644
index 9ba5a789..00000000
--- a/Documentation/nocast-vs-bitwise.md
+++ /dev/null
@@ -1,43 +0,0 @@
-__nocast vs __bitwise
-=====================
-
-`__nocast` warns about explicit or implicit casting to different types.
-HOWEVER, it doesn't consider two 32-bit integers to be different
-types, so a `__nocast int` type may be returned as a regular `int`
-type and then the `__nocast` is lost.
-
-So `__nocast` on integer types is usually not that powerful. It just
-gets lost too easily. It's more useful for things like pointers. It
-also doesn't warn about the mixing: you can add integers to `__nocast`
-integer types, and it's not really considered anything wrong.
-
-`__bitwise` ends up being a *stronger integer separation*. That one
-doesn't allow you to mix with non-bitwise integers, so now it's much
-harder to lose the type by mistake.
-
-So the basic rule is:
-
-- `__nocast` on its own tends 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. So a 64-bit integer
-  that you don't want to mistakenly/silently be returned as `int`, for
-  example. But they mix well with random integer types, so you can add
-  to them etc without using anything special. However, that mixing also
-  means that the `__nocast` really gets lost fairly easily.
-
-- `__bitwise` is for *unique types* that cannot be mixed with other
-  types, and that you'd never want to just use as a random integer (the
-  integer `0` is special, though, and gets silently accepted - it's
-  kind of like `NULL` for pointers). So `gfp_t` or the `safe endianness`
-  types would be `__bitwise`: you can only operate on them by doing
-  specific operations that know about *that* particular type.
-
-Generally, you want `__bitwise` if you are looking for type safety.
-`__nocast` really is pretty weak.
-
-Reference:
-----------
-
-* Linus' e-mail about `__nocast` vs `__bitwise`:
-
-  <https://marc.info/?l=linux-mm&m=133245421127324&w=2>
diff --git a/Documentation/submitting-patches.md b/Documentation/submitting-patches.md
index fb176ce5..6a4275c3 100644
--- a/Documentation/submitting-patches.md
+++ b/Documentation/submitting-patches.md
@@ -1,5 +1,5 @@
-Submitting patches: the sparse version
-======================================
+Submitting patches
+==================
 
 Sparse uses a patch submit process similar to the Linux Kernel
 [Submitting Patches](https://www.kernel.org/doc/html/v4.12/process/submitting-patches.html)
diff --git a/Documentation/templates/breadcrumbs.html b/Documentation/templates/breadcrumbs.html
new file mode 100644
index 00000000..4f22fa9a
--- /dev/null
+++ b/Documentation/templates/breadcrumbs.html
@@ -0,0 +1,11 @@
+{%- extends "sphinx_rtd_theme/breadcrumbs.html" %}
+
+{% block breadcrumbs_aside %}
+  {% if hasdoc(pagename) %}
+    <li class="wy-breadcrumbs-aside">
+    {% if show_source and has_source and sourcename %}
+      <a href="{{ pathto('_sources/' + sourcename, true)|e }}" rel="nofollow"> {{ _('View page source') }}</a>
+    {% endif %}
+    </li>
+  {% endif %}
+{% endblock %}
diff --git a/Documentation/templates/layout.html b/Documentation/templates/layout.html
new file mode 100644
index 00000000..a2fe215f
--- /dev/null
+++ b/Documentation/templates/layout.html
@@ -0,0 +1,8 @@
+{% extends "!layout.html" %}
+{% block menu %}
+    {{ super() }}
+    <p class="caption"><span class="caption-text">Index</span></p>
+    <ul>
+    <li class="toctree-l1"><a class="reference internal" href="{{ pathto('genindex') }}">Index</a></li>
+    </ul>
+{% endblock %}