Documentation/annotations.rst

   1 Annotations
   2 ===========
   3
   4 Sparse extends C's type system with a number of extra type qualifiers
   5 which add restrictions on what you can do on objects annotated with them.
   6 These qualifiers are specified with GCC's ``__attribute__`` syntax.
   7
   8 address_space(*name*)
   9 ---------------------
  10 This attribute is to be used on pointers to specify that its target is
  11 in address space *name* (an identifier or a constant integer).
  12
  13 Sparse treats pointers with different address spaces as distinct types
  14 and will warn on casts (implicit or explicit) mixing the address spaces.
  15 An exception to this is when the destination type is ``uintptr_t`` or
  16 ``unsigned long`` since the resulting integer value is independent
  17 of the address space and can't be dereferenced without first casting
  18 it back to a pointer type.
  19
  20 bitwise
  21 -------
  22 This attribute is to be used to define new, unique integer types that
  23 cannot be mixed with other types. In particular, you can't mix a
  24 "bitwise" integer with a normal integer expression, and you can't even
  25 mix it with another bitwise expression of a different type.
  26 The integer 0 is special, though, and can be mixed with any bitwise type
  27 since it's safe for all bitwise operations.
  28
  29 Since this qualifier defines new types, it only makes sense to use
  30 it in typedefs, which effectively makes each of these typedefs
  31 a single "bitwise class", incompatible with any other types.
  32
  33 context(*ctxt*, *entry*, *exit*)
  34 --------------------------------
  35 This attribute is to be used on function declarations to specify
  36 the function's entry and exit count for a given context. This
  37 context can be pretty much anything that can be counted.
  38
  39 Sparse will check that the function's entry and exit contexts match, and
  40 that no path through a function is ever entered with conflicting contexts.
  41 In particular, it is designed for doing things like matching up a "lock"
  42 with the pairing "unlock". For example, a function doing a lock should be
  43 annotated with an entry value of 0 and an exit value of 1, the corresponding
  44 unlock function should use the values 1 and 0, and a function that should
  45 only be called on some locked data, release the lock but which doesn't exit
  46 without reacquiring the lock being, should use entry and exit values of 1.
  47
  48 The first argument, *ctxt*, is an expression only used as documentation
  49 to identify the context. Usually, what is used is a pointer to the structure
  50 containing the context, for example, the structure protected by the lock.
  51
  52 See also https://lwn.net/Articles/109066/.
  53
  54 noderef
  55 -------
  56 This attribute is to be used on a r-value to specify it cannot be
  57 dereferenced. A pointer so annotated is in all other aspects exactly
  58 like a pointer  but trying to actually access anything through it will
  59 cause a warning.
  60
  61 nocast
  62 ------
  63 This attribute is similar to ``bitwise`` but in a much weaker form.
  64 It warns about explicit or implicit casting to different types.
  65 However, it doesn't warn about the mixing with other types and it easily
  66 gets lost: you can add plain integers to __nocast integer types and the
  67 result will be plain integers.
  68 So, it ends to be more useful for big integers that still need to act
  69 like integers, but you want to make it much less likely that they get
  70 truncated by mistake. For example, a 64-bit integer that you don't want
  71 to mistakenly/silently be returned as int.
  72
  73 See also `Linus' e-mail about __nocast vs __bitwise
  74 <https://lore.kernel.org/linux-mm/CA+55aFzbhYvw7Am9EYgatpjTknBFm9eq+3jBWQHkSCUpnb3HRQ@mail.gmail.com/>`_.
  75
  76 safe
  77 ----
  78 This attribute specifies that the object, which should be a pointer,
  79 is defined to never be NULL or nontrapping.
  80 It causes a warning if the object is tested in a conditional.
  81
  82 force
  83 -----
  84 This attribute is to be used in casts to suppress warnings that would
  85 otherwise be caused by the presence of one of these extra qualifiers.