1 // © 2021 Qualcomm Innovation Center, Inc. All rights reserved. 2 // 3 // SPDX-License-Identifier: BSD-3-Clause 4 5 // This file documents the permitted function, type and variable attributes, and 6 // defines short names for them. Do not use any attribute specifier unless it is 7 // listed below. 8 // 9 // This file is automatically included in all source files; this is done with 10 // -imacro, so this file must not contain any non-preprocessor declarations. 11 // 12 // This rule does not apply to language constructs that have an effect that is 13 // similar or equivalent to an attribute, such as _Noreturn or _Alignas. 14 15 // Mark a function as cold. This is used to mark cold functions for 16 // which internal inlining or size increasing optimizations would be 17 // a waste of space. 18 #define COLD __attribute__((cold)) 19 20 // Don't inline this function. This is used to mark functions for which 21 // inlining would be a waste of space and/or would make debugging inconvenient. 22 #define NOINLINE __attribute__((noinline)) 23 24 // Always inline the function. This is used for certain inline assembler 25 // wrappers which cannot safely be wrapped in a function call, such as 26 // load-exclusive instructions which might lose their exclusivity. 27 #define ALWAYS_INLINE __attribute__((always_inline)) 28 29 // Declare or define a function as weakly linked. 30 // 31 // If placed on a definition, this creates a weak definition, which can be 32 // overridden by a non-weak definition in another object. 33 // 34 // If placed on a declaration, this causes calls to the function to be linked as 35 // weak references, which do not require a definition to exist at all. The 36 // behaviour of calling an undefined function is unspecified, so this usage 37 // is not recommended. 38 #define WEAK __attribute__((weak)) 39 40 // 41 // Clang thread safety analysis attributes. 42 // 43 44 // Declare a type as representing a thread-safety capability (in Clang SA terms; 45 // this is unrelated to the Gunyah API's object capabilities). 46 // 47 // Note that calling this "lockable" is misleading because it is not necessarily 48 // exclusive, but that's better than overloading "capability". 49 // 50 // The name is a human-readable string used in error messages. 51 #define LOCKABLE(name) __attribute__((capability(name))) 52 53 // Declare a variable as being protected by a specific lock. 54 #define PROTECTED_BY(lock) __attribute__((guarded_by(lock))) 55 56 // Declare a variable as being protected by a specific lock. 57 #define PTR_PROTECTED_BY(lock) __attribute__((pt_guarded_by(lock))) 58 59 // Declare a function as acquiring a specified lock object. 60 #define ACQUIRE_LOCK(lock) __attribute__((acquire_capability(lock))) 61 62 // Declare a function as acquiring a specified lock object if it returns a 63 // specified value. 64 #define TRY_ACQUIRE_LOCK(success, lock) \ 65 __attribute__((try_acquire_capability(success, lock))) 66 67 // Declare a function as releasing a specified lock object. 68 #define RELEASE_LOCK(lock) __attribute__((release_capability(lock))) 69 70 // Declare a function as requiring a lock to be held. 71 #define REQUIRE_LOCK(lock) __attribute__((requires_capability(lock))) 72 73 // Declare a function as requiring a lock to _not_ be held. 74 #define EXCLUDE_LOCK(lock) __attribute__((requires_capability(!&(lock)))) 75 76 // Declare a function as acquiring a shared reader lock. 77 #define ACQUIRE_READ(lock) __attribute__((acquire_shared_capability(lock))) 78 79 // Declare a function as acquiring a specified shared read lock if it 80 // returns a specified value. 81 #define TRY_ACQUIRE_READ(success, lock) \ 82 __attribute__((try_acquire_shared_capability(success, lock))) 83 84 // Declare a function as releasing a shared reader lock. 85 #define RELEASE_READ(lock) __attribute__((release_shared_capability(lock))) 86 87 // Declare a function as requiring a shared reader lock to be held. 88 #define REQUIRE_READ(lock) __attribute__((requires_shared_capability(lock))) 89 90 // Declare a function as requiring a shared reader lock to _not_ be held. 91 #define EXCLUDE_READ(lock) __attribute__((locks_excluded(lock))) 92 93 // Define a function that implements a lock acquire or release. This disables 94 // checking of thread safety throughout the function, so the function should 95 // ideally do nothing other than implement the lock, hence the name. 96 // 97 // This attribute can also disable analysis in a function that is too complex 98 // for the analyser to understand; e.g. one that has conditional locking. Using 99 // it for this purpose so is strongly deprecated. 100 #define LOCK_IMPL __attribute__((no_thread_safety_analysis)) 101