Josh Gao | bfb6bae | 2016-07-15 17:25:21 -0700 | [diff] [blame] | 1 | /* |
Elliott Hughes | dfb74c5 | 2016-10-24 12:53:17 -0700 | [diff] [blame] | 2 | * Copyright (C) 2016 The Android Open Source Project |
Josh Gao | bfb6bae | 2016-07-15 17:25:21 -0700 | [diff] [blame] | 3 | * |
| 4 | * Licensed under the Apache License, Version 2.0 (the "License"); |
| 5 | * you may not use this file except in compliance with the License. |
| 6 | * You may obtain a copy of the License at |
| 7 | * |
Elliott Hughes | dfb74c5 | 2016-10-24 12:53:17 -0700 | [diff] [blame] | 8 | * http://www.apache.org/licenses/LICENSE-2.0 |
Josh Gao | bfb6bae | 2016-07-15 17:25:21 -0700 | [diff] [blame] | 9 | * |
| 10 | * Unless required by applicable law or agreed to in writing, software |
| 11 | * distributed under the License is distributed on an "AS IS" BASIS, |
| 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 13 | * See the License for the specific language governing permissions and |
| 14 | * limitations under the License. |
| 15 | */ |
| 16 | |
Elliott Hughes | c0f4656 | 2018-11-09 15:38:52 -0800 | [diff] [blame] | 17 | #pragma once |
Josh Gao | bfb6bae | 2016-07-15 17:25:21 -0700 | [diff] [blame] | 18 | |
Dan Albert | ed2d383 | 2024-08-28 20:21:52 +0000 | [diff] [blame] | 19 | /** |
| 20 | * @def __ANDROID_UNAVAILABLE_SYMBOLS_ARE_WEAK__ |
| 21 | * |
| 22 | * Controls whether calling APIs newer than the developer's minSdkVersion are a |
| 23 | * build error (when not defined) or allowed as a weak reference with a |
| 24 | * __builtin_available() guard (when defined). |
| 25 | * |
| 26 | * See https://developer.android.com/ndk/guides/using-newer-apis for more |
| 27 | * details. |
| 28 | */ |
Elliott Hughes | a37b181 | 2021-02-11 12:56:39 -0800 | [diff] [blame] | 29 | #if defined(__ANDROID_UNAVAILABLE_SYMBOLS_ARE_WEAK__) |
Dan Albert | ed2d383 | 2024-08-28 20:21:52 +0000 | [diff] [blame] | 30 | // In this mode, Clang will emit weak references to the APIs if the |
| 31 | // minSdkVersion is less than the __what argument. This allows the libraries to |
| 32 | // load even on systems too old to contain the API, but calls must be guarded |
| 33 | // with `__builtin_available(android api_level, *)` to avoid segfaults. |
Dan Albert | 398e1aa | 2024-05-01 22:06:54 +0000 | [diff] [blame] | 34 | #define __BIONIC_AVAILABILITY(__what, ...) __attribute__((__availability__(android,__what __VA_OPT__(,) __VA_ARGS__))) |
Dan Albert | e5da496 | 2024-10-24 22:09:09 +0000 | [diff] [blame] | 35 | |
| 36 | // When the caller is using weak API references, we should expose the decls for |
| 37 | // APIs which are not available in the caller's minSdkVersion, otherwise there's |
| 38 | // no way to take advantage of the weak references. |
| 39 | #define __BIONIC_AVAILABILITY_GUARD(api_level) 1 |
Jiyong Park | 23bfed2 | 2020-08-10 13:35:05 +0900 | [diff] [blame] | 40 | #else |
Dan Albert | ed2d383 | 2024-08-28 20:21:52 +0000 | [diff] [blame] | 41 | // The 'strict' flag is required for NDK clients where the code was not written |
| 42 | // to handle the case where the API was available at build-time but not at |
| 43 | // run-time. Most 3p code ported to Android was not written to use |
| 44 | // `__builtin_available()` for run-time availability checking, and so would not |
| 45 | // compile in this mode (or worse, if the build doesn't use |
| 46 | // -Werror=unguarded-availability, it would build but crash at runtime). |
Dan Albert | 398e1aa | 2024-05-01 22:06:54 +0000 | [diff] [blame] | 47 | #define __BIONIC_AVAILABILITY(__what, ...) __attribute__((__availability__(android,strict,__what __VA_OPT__(,) __VA_ARGS__))) |
Dan Albert | e5da496 | 2024-10-24 22:09:09 +0000 | [diff] [blame] | 48 | |
| 49 | // When the caller is using strict API references, we hide APIs which are not |
| 50 | // available in the caller's minSdkVersion. This is a bionic-only deviation in |
| 51 | // behavior from the rest of the NDK headers, but it's necessary to maintain |
| 52 | // source compatibility with 3p libraries that either can't correctly detect API |
| 53 | // availability (either incorrectly detecting as always-available or as |
| 54 | // never-available, but neither is true), or define their own polyfills which |
| 55 | // conflict with our declarations. |
| 56 | // |
| 57 | // https://github.com/android/ndk/issues/2081 |
| 58 | #define __BIONIC_AVAILABILITY_GUARD(api_level) (__ANDROID_MIN_SDK_VERSION__ >= (api_level)) |
Jiyong Park | 23bfed2 | 2020-08-10 13:35:05 +0900 | [diff] [blame] | 59 | #endif |
| 60 | |
Aditya Kumar | 52fe6ce | 2024-10-10 20:40:39 +0000 | [diff] [blame] | 61 | #pragma clang diagnostic push |
| 62 | #pragma clang diagnostic ignored "-Wc23-extensions" |
| 63 | // Passing no argument for the '...' parameter of a variadic macro is a C23 extension |
Elliott Hughes | a37b181 | 2021-02-11 12:56:39 -0800 | [diff] [blame] | 64 | #define __INTRODUCED_IN(api_level) __BIONIC_AVAILABILITY(introduced=api_level) |
Aditya Kumar | 52fe6ce | 2024-10-10 20:40:39 +0000 | [diff] [blame] | 65 | #pragma clang diagnostic pop |
| 66 | |
Dan Albert | e25abd9 | 2024-05-15 17:55:55 +0000 | [diff] [blame] | 67 | #define __DEPRECATED_IN(api_level, msg) __BIONIC_AVAILABILITY(deprecated=api_level, message=msg) |
| 68 | #define __REMOVED_IN(api_level, msg) __BIONIC_AVAILABILITY(obsoleted=api_level, message=msg) |
Jiyong Park | 23bfed2 | 2020-08-10 13:35:05 +0900 | [diff] [blame] | 69 | |
| 70 | // The same availability attribute can't be annotated multiple times. Therefore, the macros are |
| 71 | // defined for the configuration that it is valid for so that declarations like the below doesn't |
| 72 | // cause inconsistent availability values which is an error with -Wavailability: |
| 73 | // |
| 74 | // void foo() __INTRODUCED_IN_32(30) __INTRODUCED_IN_64(31); |
| 75 | // |
Jiyong Park | 23bfed2 | 2020-08-10 13:35:05 +0900 | [diff] [blame] | 76 | #if !defined(__LP64__) |
Elliott Hughes | a37b181 | 2021-02-11 12:56:39 -0800 | [diff] [blame] | 77 | #define __INTRODUCED_IN_32(api_level) __BIONIC_AVAILABILITY(introduced=api_level) |
Logan Chien | d7d9ebc | 2019-11-27 07:25:07 -0800 | [diff] [blame] | 78 | #define __INTRODUCED_IN_64(api_level) |
Jiyong Park | 23bfed2 | 2020-08-10 13:35:05 +0900 | [diff] [blame] | 79 | #else |
| 80 | #define __INTRODUCED_IN_32(api_level) |
Elliott Hughes | a37b181 | 2021-02-11 12:56:39 -0800 | [diff] [blame] | 81 | #define __INTRODUCED_IN_64(api_level) __BIONIC_AVAILABILITY(introduced=api_level) |
Jiyong Park | 23bfed2 | 2020-08-10 13:35:05 +0900 | [diff] [blame] | 82 | #endif |