From bdf3eca7298e5d57864c83329e979a7746d7c130 Mon Sep 17 00:00:00 2001 From: Luc Van Oostenryck Date: Sat, 1 Aug 2020 02:37:50 +0200 Subject: doc: document the sparse's extensions First try at documenting sparse's extensions to C's type system. Signed-off-by: Luc Van Oostenryck --- Documentation/annotations.rst | 85 +++++++++++++++++++++++++++++++++++++++++++ Documentation/index.rst | 1 + 2 files changed, 86 insertions(+) create mode 100644 Documentation/annotations.rst 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 +`_. + +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 -- cgit 1.2.3-korg From 9cc01abd43e3950a7c4da2b01a8851fd48dfa3b0 Mon Sep 17 00:00:00 2001 From: Luc Van Oostenryck Date: Sat, 1 Aug 2020 02:45:55 +0200 Subject: doc: replace nocast-vs-bitwise document with its lore link The nocast-vs-bitwise document was copied here to be sure to remain accessible but isn't really useful here now because: 1) the original document have also been archived to lore.kernel.org 2) nocast & bitwise have now been documented 3) 2) contains a link to 1) So, remove this redundant document. Signed-off-by: Luc Van Oostenryck --- Documentation/index.rst | 1 - Documentation/nocast-vs-bitwise.md | 43 -------------------------------------- 2 files changed, 44 deletions(-) delete mode 100644 Documentation/nocast-vs-bitwise.md diff --git a/Documentation/index.rst b/Documentation/index.rst index 9c76419b..cbe0521b 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -69,7 +69,6 @@ User documentation :maxdepth: 1 annotations - nocast-vs-bitwise Developer documentation ----------------------- 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`: - - -- cgit 1.2.3-korg From b09b9dda368dcc8640f9dff2129e8b651872edf4 Mon Sep 17 00:00:00 2001 From: Luc Van Oostenryck Date: Sat, 1 Aug 2020 03:18:27 +0200 Subject: doc: simplify the toctree Combine the 'user' documentation with the one for developers and add captions for each sections in order to have this structuration visible in the sidebar. Signed-off-by: Luc Van Oostenryck --- Documentation/index.rst | 28 +++++++--------------------- 1 file changed, 7 insertions(+), 21 deletions(-) diff --git a/Documentation/index.rst b/Documentation/index.rst index cbe0521b..e8e40c0c 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: http://bugzilla.kernel.org/enter_bug.cgi?component=Sparse&product=Tools. -User documentation ------------------- -.. toctree:: - :maxdepth: 1 - - annotations -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 -- cgit 1.2.3-korg From 4631d03232968ee63b073e47818b3cd4a3647260 Mon Sep 17 00:00:00 2001 From: Luc Van Oostenryck Date: Sun, 2 Aug 2020 17:17:16 +0200 Subject: doc: add index to the sidebar It's very useful to be able to access the index from the sidebar but no change in the configuration seems to allow this. Trying to abuse the toctree give the same result. So, add it directly via the template system. Signed-off-by: Luc Van Oostenryck --- Documentation/templates/layout.html | 8 ++++++++ 1 file changed, 8 insertions(+) create mode 100644 Documentation/templates/layout.html 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() }} +

Index

+ +{% endblock %} -- cgit 1.2.3-korg From a82ef22e014028b08c60cd69bb3d8cfd31ad80e6 Mon Sep 17 00:00:00 2001 From: Luc Van Oostenryck Date: Sun, 2 Aug 2020 17:30:30 +0200 Subject: doc: remove link "edit on github" since the development isn't done on github, the link "edit on github" is useless and confusing. So remove this link (but leave the one "View page source" as it's sometimes quite handy). Signed-off-by: Luc Van Oostenryck --- Documentation/templates/breadcrumbs.html | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 Documentation/templates/breadcrumbs.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) %} +
  • + {% if show_source and has_source and sourcename %} + {{ _('View page source') }} + {% endif %} +
    • + {% endif %} +{% endblock %} -- cgit 1.2.3-korg From bf520529b31645688ec93b771f8f68ca20c438f9 Mon Sep 17 00:00:00 2001 From: Luc Van Oostenryck Date: Sun, 2 Aug 2020 22:31:10 +0200 Subject: doc: shorter title for "submitting-patches.md" The documentation for submitting patches has ": the sparse version" is in its title. This is quite useless and makes it longer than needed. So, remove this part from the title. Signed-off-by: Luc Van Oostenryck --- Documentation/submitting-patches.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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) -- cgit 1.2.3-korg