[PATCH] Updated __nocast vs __bitwise documentation

[PATCH] Updated __nocast vs __bitwise documentation

[Shakthi Kannan]

I have updated the sparse.1 man page including the __bitwise
relevant content, and created Documentation/sparse.txt with the
complete comparison between __nocast vs __bitwise.

Signed-off-by: Shakthi Kannan <shakthimaan@gmail.com>
---
 Documentation/sparse.txt |   39 +++++++++++++++++++++++++++++++++++++++
 sparse.1                 |   14 +++++++++++++-
 2 files changed, 52 insertions(+), 1 deletions(-)
 create mode 100644 Documentation/sparse.txt

diff --git a/Documentation/sparse.txt b/Documentation/sparse.txt
new file mode 100644
index 0000000..37e8916
--- /dev/null
+++ b/Documentation/sparse.txt
@@ -0,0 +1,39 @@
+Sparse
+~~~~~~
+
+__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 iirc - 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.
diff --git a/sparse.1 b/sparse.1
index bde6b6d..ae85b54 100644
--- a/sparse.1
+++ b/sparse.1
@@ -53,7 +53,19 @@ arithmetic operations other than bitwise
operations, and on any conversion of
 one restricted type into another, except via a cast that includes
 \fB__attribute__((force))\fR.

-Sparse does not issue these warnings by default.
+__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.
+
+__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 iirc - 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. Sparse
+does not issue these warnings by default.
 .
 .TP
 .B \-Wcast\-to\-as
-- 
1.7.7.6

Re: [PATCH] Updated __nocast vs __bitwise documentation

[Christopher Li]

Looks good. Thanks for doing that.

Can you add some reference (in sparse.txt) to the original Linus email
where some
of this document is base on? Just to give credit where it is due. A link to the
Linus original email would be perfect.

Thanks

Chris


On Wed, May 9, 2012 at 11:54 PM, Shakthi Kannan <shakthimaan@gmail.com> wrote:
> I have updated the sparse.1 man page including the __bitwise
> relevant content, and created Documentation/sparse.txt with the
> complete comparison between __nocast vs __bitwise.
>
> Signed-off-by: Shakthi Kannan <shakthimaan@gmail.com>
> ---
>  Documentation/sparse.txt |   39 +++++++++++++++++++++++++++++++++++++++
>  sparse.1                 |   14 +++++++++++++-
>  2 files changed, 52 insertions(+), 1 deletions(-)
>  create mode 100644 Documentation/sparse.txt
>
> diff --git a/Documentation/sparse.txt b/Documentation/sparse.txt
> new file mode 100644
> index 0000000..37e8916
> --- /dev/null
> +++ b/Documentation/sparse.txt
> @@ -0,0 +1,39 @@
> +Sparse
> +~~~~~~
> +
> +__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 iirc - 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.
> diff --git a/sparse.1 b/sparse.1
> index bde6b6d..ae85b54 100644
> --- a/sparse.1
> +++ b/sparse.1
> @@ -53,7 +53,19 @@ arithmetic operations other than bitwise
> operations, and on any conversion of
>  one restricted type into another, except via a cast that includes
>  \fB__attribute__((force))\fR.
>
> -Sparse does not issue these warnings by default.
> +__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.
> +
> +__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 iirc - 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. Sparse
> +does not issue these warnings by default.
>  .
>  .TP
>  .B \-Wcast\-to\-as
> --
> 1.7.7.6
> --
> To unsubscribe from this list: send the line "unsubscribe linux-sparse" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
--
To unsubscribe from this list: send the line "unsubscribe linux-sparse" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] Updated __nocast vs __bitwise documentation

[Shakthi Kannan]

Hi Chris:

--- On Thu, May 10, 2012 at 4:20 PM, Christopher Li <sparse@chrisli.org> wrote:
| Looks good. Thanks for doing that.
|
| Can you add some reference (in sparse.txt) to the original Linus email
| where some
| of this document is base on? Just to give credit where it is due. A
link to the
| Linus original email would be perfect.
\--

Is the following reference sufficient if added to the sparse.txt file?

=== sparse.txt ===

Sparse
~~~~~

Copyright (C) 2012 Linus Torvalds

Source: https://lkml.org/lkml/2012/3/22/409

__nocast vs __bitwise:

...
...
...

=== END ===

I will re-submit the patch with the approved changes.

Thanks for your quick response!

SK

-- 
Shakthi Kannan
http://www.shakthimaan.com

Re: [PATCH] Updated __nocast vs __bitwise documentation

[Christopher Li]

On Thu, May 10, 2012 at 4:06 AM, Shakthi Kannan <shakthimaan@gmail.com> wrote:
> Hi Chris:
>
> --- On Thu, May 10, 2012 at 4:20 PM, Christopher Li <sparse@chrisli.org> wrote:
> | Looks good. Thanks for doing that.
> |
> | Can you add some reference (in sparse.txt) to the original Linus email
> | where some
> | of this document is base on? Just to give credit where it is due. A
> link to the
> | Linus original email would be perfect.
> \--
>
> Is the following reference sufficient if added to the sparse.txt file?
>
> === sparse.txt ===
>
> Sparse
> ~~~~~
>
> Copyright (C) 2012 Linus Torvalds

CCing Linus,

Not sure about the rules of quoting other people's email.
Does it need the full copyright notice?

I would just add these two lines to the end of the sparse.txt

Reference:
 * Linus' email about __nocast vs __bitwise: https://lkml.org/lkml/2012/3/22/409

Chris

Re: [PATCH] Updated __nocast vs __bitwise documentation

[Josh Triplett]

On Thu, May 10, 2012 at 04:36:28PM +0530, Shakthi Kannan wrote:
> Source: https://lkml.org/lkml/2012/3/22/409

I've found lkml.org somewhat unreliable.  I'd suggest liking to
http://mid.gmane.org/<the-message-ID> ; in this case,
http://mid.gmane.org/CA+55aFzbhYvw7Am9EYgatpjTknBFm9eq+3jBWQHkSCUpnb3HRQ@mail.gmail.com

- Josh Triplett

Re: [PATCH] Updated __nocast vs __bitwise documentation

[Shakthi Kannan]

Hi,

I am resending the patch with the reference to Linus' email added to
Documentation/sparse.txt.

Thanks for all your feedback and replies.

Signed-off-by: Shakthi Kannan <shakthimaan@gmail.com>
---
 Documentation/sparse.txt |   45 +++++++++++++++++++++++++++++++++++++++++++++
 sparse.1                 |   14 +++++++++++++-
 2 files changed, 58 insertions(+), 1 deletions(-)
 create mode 100644 Documentation/sparse.txt

diff --git a/Documentation/sparse.txt b/Documentation/sparse.txt
new file mode 100644
index 0000000..1ee3b39
--- /dev/null
+++ b/Documentation/sparse.txt
@@ -0,0 +1,45 @@
+Sparse
+~~~~~~
+
+__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 iirc - 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:
+
+  http://article.gmane.org/gmane.linux.kernel.mm/75784
diff --git a/sparse.1 b/sparse.1
index bde6b6d..ae85b54 100644
--- a/sparse.1
+++ b/sparse.1
@@ -53,7 +53,19 @@ arithmetic operations other than bitwise
operations, and on any conversion of
 one restricted type into another, except via a cast that includes
 \fB__attribute__((force))\fR.

-Sparse does not issue these warnings by default.
+__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.
+
+__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 iirc - 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. Sparse
+does not issue these warnings by default.
 .
 .TP
 .B \-Wcast\-to\-as
-- 
1.7.7.6