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